Fix docs Cloudflare build flow and stabilize workspace checks by richardjoo · Pull Request #1098 · emdash-cms/emdash

richardjoo · 2026-05-19T07:29:02Z

What does this PR do?

This PR improves the docs deployment/operations path for Cloudflare-hosted EmDash sites and fixes several workspace-level validation issues that were blocking clean local and CI-style runs.

Closes #

Adds Cloudflare post-deploy API/runbook documentation and links it from the deployment and REST API docs.
Unblocks docs Worker builds without a configured Cloudflare AI Search instance by adding a local-only Wrangler config, an MCP fallback path, and a custom Starlight 404 page.
Restores green workspace validation by isolating type-aware lint to a dedicated tsconfig, switching @emdash-cms/registry-client typecheck to tsc, and stabilizing browser/passkey tests that were flaking under full-suite load.
Temporarily removes the crashing @e18e/eslint-plugin integration from oxlint; type-aware lint still runs, but the previous e18e/* rule coverage is intentionally dropped until the upstream JS-plugin crash can be replaced safely.

Type of change

Checklist

I have read CONTRIBUTING.md
pnpm typecheck passes
pnpm lint passes
pnpm test passes (or targeted tests for my change)
pnpm format has been run
I have added/updated tests for my changes (if applicable)
User-visible strings in the admin UI are wrapped for translation (if applicable). Do not include messages.po changes except in translation PRs — a workflow extracts catalogs on merge to main.
I have added a changeset (if this PR changes a published package)
New features link to an approved Discussion: https://github.com/emdash-cms/emdash/discussions/...

AI-generated code disclosure

This PR includes AI-generated code — model/tool: GPT-5.4 / OpenCode

Screenshots / test output

pnpm typecheck
pnpm lint
pnpm test
pnpm format:check
pnpm --dir docs build

changeset-bot · 2026-05-19T07:29:06Z

⚠️ No Changeset found

Latest commit: 44e4413

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-05-19T07:29:13Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

github-actions · 2026-05-19T07:29:16Z

Scope check

This PR changes 554 lines across 26 files. Large PRs are harder to review and more likely to be closed without review.
This PR spans 4 different areas (area/core, area/admin, area/docs, area/auth). Consider breaking it into smaller, focused PRs.

If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs.

See CONTRIBUTING.md for contribution guidelines.

richardjoo · 2026-05-19T07:31:30Z

I have read the CLA Document and I hereby sign the CLA

richardjoo · 2026-05-19T07:31:50Z

recheck

Copilot

Pull request overview

This PR updates the docs Cloudflare deployment flow (including a local-only Wrangler config and an MCP/AI Search fallback) and stabilizes workspace validation by adjusting lint/typecheck tooling and hardening flaky tests.

Changes:

Add Cloudflare docs runbooks + link them from deployment and REST API docs.
Make docs Worker build/preview work without a configured Cloudflare AI Search binding (local wrangler config + MCP fallback + custom 404).
Stabilize workspace checks (dedicated oxlint tsconfig, registry-client typecheck via tsc, and longer timeouts/mocking for flaky tests).

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tsconfig.oxlint.json	Introduces a dedicated tsconfig for oxlint type-aware runs with targeted excludes.
packages/registry-client/tsconfig.json	Adjusts TS lib config for registry-client compilation/typechecking.
packages/registry-client/package.json	Switches registry-client typecheck script from `tsgo` to `tsc`.
packages/registry-cli/src/commands/info.ts	Minor typing simplification for parsed profile handling.
packages/core/tests/unit/database/migrations/036_i18n_menus_and_taxonomies.test.ts	Uses `toSorted()` in migration test assertions.
packages/core/src/api/handlers/registry.ts	Preserves SSRF error cause when rethrowing artifact URL rejection.
packages/auth/src/passkey/register.test.ts	Increases timeout for RS256 registration test to reduce flakes.
packages/auth/src/passkey/authenticate.test.ts	Increases timeout for RS256 assertion test to reduce flakes.
packages/admin/tests/locales/LocaleDirectionProvider.test.tsx	Mocks message loading and increases waitFor timeout to stabilize locale-direction test.
packages/admin/tests/components/SeoPanel.test.tsx	Tightens assertions for SEO flush-on-unmount behavior.
packages/admin/src/lib/api/client.ts	Renames destructured error message var for clarity.
packages/admin/src/components/SeoPanel.tsx	Changes flush behavior for pending SEO draft updates.
packages/admin/src/components/ContentTypeEditor.tsx	Renames plural label variable for clarity.
packages/admin/src/components/ContentEditor.tsx	Removes unused `Link` import.
package.json	Routes `lint` scripts through the dedicated oxlint tsconfig.
e2e/tests/bylines.spec.ts	Removes unused byline IDs from test setup.
docs/wrangler.local.jsonc	Adds local-only Wrangler config without AI Search binding.
docs/src/worker.ts	Adds MCP `search_docs` fallback when AI Search binding is missing.
docs/src/pages/404.astro	Adds custom Starlight 404 page (Starlight default disabled).
docs/src/content/docs/runbooks/index.mdx	Adds runbooks index page.
docs/src/content/docs/runbooks/deployment/cloudflare-post-deploy-operations.mdx	Adds Cloudflare post-deploy operational runbook.
docs/src/content/docs/reference/rest-api.mdx	Links REST API docs to the Cloudflare post-deploy runbook.
docs/src/content/docs/deployment/cloudflare.mdx	Adds “Manage a deployed site via API” section and runbook link.
docs/README.md	Documents local preview workflow using the local Wrangler config.
docs/astro.config.mjs	Disables default 404 route, adds runbooks to sidebar, tweaks Cloudflare adapter config.
.oxlintrc.json	Removes `@e18e/eslint-plugin` integration and associated rules.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

richardjoo · 2026-05-19T08:10:13Z

 	const flushPendingDraft = React.useCallback(() => {
+		if (!pendingTextFlushTimerRef.current) {
+			return;
+		}
 		clearPendingTextFlush();
 		emitChange(currentDraftRef.current);
 	}, [clearPendingTextFlush, emitChange]);


Good catch. This one was valid.

I updated flushPendingDraft() so it no longer depends on pendingTextFlushTimerRef.current being non-null. It now compares the current draft snapshot against lastEmittedSnapshotRef.current, clears any pending timer, and emits only when there is an unflushed draft. That avoids dropping pending text edits during unmount/content switches after debounce cleanup.

Fixed in commit 44e4413 (Fix SeoPanel pending draft flush).

richardjoo · 2026-05-19T08:12:11Z

+	editUrl: false,
+	pagefind: false,
+	hero: {
+		tagline: Astro.locals.t("404.text"),


This one appears to be a false positive.

Astro.locals.t is provided by Starlight itself via its locals augmentation/middleware. I verified that against @astrojs/starlight/locals.d.ts, which explicitly documents Astro.locals.t('404.text'), and the docs build on this branch renders /404.html successfully.

richardjoo · 2026-05-19T08:06:49Z

Follow-up on the two Copilot review points:

packages/admin/src/components/SeoPanel.tsx

This one was valid. I updated flushPendingDraft() so it no longer depends on pendingTextFlushTimerRef.current being non-null. It now compares the current draft snapshot against lastEmittedSnapshotRef.current, clears any pending timer, and emits only when there is an unflushed draft. That avoids dropping pending text edits during unmount/content switches after debounce cleanup.

This fix is included in commit 44e4413 (Fix SeoPanel pending draft flush).

docs/src/pages/404.astro

This one appears to be a false positive. Astro.locals.t is provided by Starlight itself via its locals augmentation/middleware. I verified that against @astrojs/starlight/locals.d.ts, which explicitly documents Astro.locals.t('404.text'), and the docs build on this branch renders /404.html successfully. So there does not appear to be a runtime/build break there.

Local validation after the SeoPanel fix still passes:

pnpm --filter @emdash-cms/admin test
PR checks are green

ascorbic

These are generally good changes, but there are quite a few unrelated things in one PR here. Could you split them up into logical parts and open seperate PRs for each?

richardjoo · 2026-05-19T19:04:11Z

Thanks — agreed. I’m splitting this into smaller logical PRs now and will replace this combined PR with separate focused ones.

richardjoo · 2026-05-19T19:20:38Z

Per review feedback, I’ve split this combined PR into focused replacements:

Docs: add Cloudflare post-deploy runbook #1106 — Docs: add Cloudflare post-deploy runbook
Docs: unblock local docs build without AI Search #1107 — Docs: unblock local docs build without AI Search
Fix lint tooling and isolate type-aware config #1108 — Fix lint tooling and isolate type-aware config
Fix SeoPanel pending draft flush #1109 — Fix SeoPanel pending draft flush

I’m closing this larger PR in favor of those smaller ones. I also intentionally left out the incidental warning-cleanup / broader test-stability edits from the split set for now so each replacement PR stays narrowly scoped.

Copilot AI review requested due to automatic review settings May 19, 2026 07:29

github-actions Bot added area/admin area/auth area/core area/docs needs-rebase size/XL labels May 19, 2026

github-actions Bot added the cla: needed label May 19, 2026

Copilot started reviewing on behalf of richardjoo May 19, 2026 07:29 View session

github-actions Bot added a commit that referenced this pull request May 19, 2026

@richardjoo has signed the CLA in #1098

62608dd

github-actions Bot added cla: signed and removed cla: needed labels May 19, 2026

Copilot AI reviewed May 19, 2026

View reviewed changes

richardjoo added 5 commits May 19, 2026 01:38

Docs: add cloudflare post-deploy runbook

1b99f74

Docs: unblock local docs build without AI Search

a2cb375

Fix lint tooling and isolate type-aware config

44c7689

Fix docs 404 route and stabilize local checks

67a374f

Stabilize admin browser tests and docs preview notes

0cdab72

richardjoo force-pushed the fix/docs-build-and-ci branch from 101d0a2 to 0cdab72 Compare May 19, 2026 07:41

github-actions Bot removed the needs-rebase label May 19, 2026

Fix SeoPanel pending draft flush

44e4413

ascorbic reviewed May 19, 2026

View reviewed changes

richardjoo closed this May 19, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix docs Cloudflare build flow and stabilize workspace checks#1098

Fix docs Cloudflare build flow and stabilize workspace checks#1098
richardjoo wants to merge 6 commits into
emdash-cms:mainfrom
richardjoo:fix/docs-build-and-ci

richardjoo commented May 19, 2026

Uh oh!

changeset-bot Bot commented May 19, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 19, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

richardjoo May 19, 2026

Uh oh!

richardjoo May 19, 2026

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

ascorbic left a comment

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

richardjoo commented May 19, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

richardjoo commented May 19, 2026

What does this PR do?

Type of change

Checklist

AI-generated code disclosure

Screenshots / test output

Uh oh!

changeset-bot Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

Scope check

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

richardjoo May 19, 2026

Choose a reason for hiding this comment

Uh oh!

richardjoo May 19, 2026

Choose a reason for hiding this comment

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

ascorbic left a comment

Choose a reason for hiding this comment

Uh oh!

richardjoo commented May 19, 2026

Uh oh!

richardjoo commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot Bot commented May 19, 2026 •

edited

Loading

github-actions Bot commented May 19, 2026 •

edited

Loading

richardjoo commented May 19, 2026 •

edited

Loading