Document Astro config loading and refactor to use Vite fallback

[diogoascarneiro]

What does this PR do?

Makes every PolyStella CLI command load the Astro config the way Astro does, so configs that import TypeScript-only packages (e.g. @cloudflare/substrate/static) no longer break check-ui, sync-ui, translate-ui, translate, or audit-mdx.

Previously the CLI imported astro.config.mjs with plain Node. Node refuses to strip types under node_modules, so any config that builds only via Astro's Vite path failed with ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING, which broke pre-commit hooks running check-ui.

• Adds loadAstroConfig(cwd) to @cloudflare/polystella-core/cli/config, mirroring Astro's loadConfigWithVite:
  • Finds astro.config.{mjs,js,ts,mts} (previously .mjs only).
  • Tries a plain Node import first, so configs that load today behave exactly as before.
  • On failure, loads the config through Vite's public runnerImport, using the Vite that ships with the project's own astro install. No new dependency, and it's the same Vite Astro uses.
  • Clear errors when both fail (Node and Vite messages), or when Vite can't be found (original error plus "install astro").
• The Astro package's loadAstroI18n (used by translate and audit-mdx) now calls core's loader instead of keeping its own copy.
• The EmDash CLI routes through core, so it gets the fix with no code change.

Type of change

• Bug fix
• Feature
• Refactor (no behavior change)
• Documentation
• Tests
• CI / tooling
• Chore

PolyStella invariants touched

• None
• Cache key formula
• Translation batching / segment grouping
• Apply-before-PUT cache write order
• Local cache index isolation
• Runtime bridge timing
• URL-rewrite idempotence
• Provider permanent vs retriable errors
• R2 key / local path separator handling

Core still never imports Astro or Vite: it looks up the consumer's Astro install at runtime, only in the Node-only cli subpath and only when the plain import fails.

Checklist

• I have read CONTRIBUTING.md
• I have added or updated tests, or this change does not need tests
• I have added a changeset, or this change does not affect the published package
• I have updated docs, or this change does not affect public behavior
• pnpm test passes, or I have explained why it was not run
• pnpm typecheck passes, or I have explained why it was not run
• Docs checks/builds pass if docs or public APIs changed

pnpm typecheck and pnpm check:packages fail on 12 TS7006 errors in packages/emdash/src/admin/**/*.tsx. These are pre-existing: the same 12 errors appear on a clean tree with this change stashed. Core and Astro typecheck cleanly on their own.

AI-generated code disclosure

• This PR includes AI-generated code - OpenCode (anthropic/claude-opus-5-5)

Screenshots / logs / test output

New test packages/astro/tests/cli/astro-config-loader.test.ts runs core's built loader in a plain Node subprocess (under Vitest the config import would go through Vite and hide the failure). With the fallback removed, it fails with the reported error:

Error [ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING]: Stripping types is currently unsupported
for files under node_modules, for ".../node_modules/ts-only-pkg/src/index.ts"

With the fallback:

pnpm test                                        1418 passed
pnpm --filter @cloudflare/polystella-core typecheck   ok
pnpm --filter @cloudflare/polystella-astro typecheck  ok
pnpm --filter polystella-docs build              ok

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	polystella-docs	fbbf92b	Commit Preview URL Branch Preview URL	Sep 24 2026, 10:07 AM

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Failed ❌ View logs ↗		fbbf92b	2026-09-24T10:07:13.250Z	View logs ↗