Code extraction into separate packages

.changeset/README.md

@@ -1,7 +1,7 @@
 # Changesets
 
 This directory tracks pending version + changelog entries between
-releases. Each PR that user-visibly changes the package adds one
+releases. Each PR that user-visibly changes a public package adds one
 markdown file here describing the change.
 
 ## Adding a changeset
@@ -12,13 +12,16 @@ pnpm changeset
 
 …which interactively asks:
 
-- **Which packages are affected?** Just `@cloudflare/polystella` for most
-  changes. The `polystella-docs` site is ignored (`ignore` list in
-  `config.json`).
+- **Which packages are affected?** Select every package changed by the PR:
+  `@cloudflare/polystella-core`, `@cloudflare/polystella-adapters`,
+  `@cloudflare/polystella-providers`, `@cloudflare/polystella`, and/or
+  `@cloudflare/polystella-astro`. Astro and the compatibility package form a
+  fixed group; core, adapters, and providers are versioned independently. The
+  private root and `polystella-docs` are not released.
 - **Is the change major / minor / patch?** Pre-1.0, "major" stays
   reserved for 1.0; bump minor for breaking changes within 0.x,
   patch otherwise.
-- **A summary.** One-liner that lands in `CHANGELOG.md`.
+- **A summary.** One-liner that lands in the affected package changelogs.
 
 The result is a small markdown file in this directory. Commit it
 with the PR.
@@ -28,12 +31,10 @@ with the PR.
 Pending changesets are consumed by the versioning step for a release.
 That step:
 
-- Bumps `package.json`'s version per the changeset severities.
-- Updates `CHANGELOG.md` with each changeset's summary.
+- Bumps affected independent packages and both packages in the Astro fixed group.
+- Updates the package-local `CHANGELOG.md` files.
 - Deletes the consumed changeset files.
 
 Publishing is automated from `.github/workflows/release.yml`. Merging
 the generated release PR back to `main` publishes to npm via Trusted
-Publishing, so routine releases must not use an npm token secret. The
-tag-based `.github/workflows/publish.yml` workflow remains a manual
-fallback for `v*` tags.
+Publishing, so routine releases must not use an npm token secret.

.changeset/clean-stars-extract.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/polystella-core": minor
+"@cloudflare/polystella-adapters": minor
+"@cloudflare/polystella-providers": minor
+"@cloudflare/polystella": minor
+"@cloudflare/polystella-astro": minor
+---
+
+Extract PolyStella into independently versioned portable core, adapters, and providers packages, plus the canonical `@cloudflare/polystella-astro` integration and its fixed-version `@cloudflare/polystella` compatibility package.

.changeset/config.json

@@ -7,9 +7,10 @@
     }
   ],
   "commit": false,
-  "fixed": [],
+  "fixed": [["@cloudflare/polystella", "@cloudflare/polystella-astro"]],
   "linked": [],
   "access": "public",
+  "privatePackages": false,
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": ["polystella-docs"]

.changeset/document-package-boundaries.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/polystella": patch
+"@cloudflare/polystella-astro": patch
+"@cloudflare/polystella-core": patch
+"@cloudflare/polystella-adapters": patch
+"@cloudflare/polystella-providers": patch
+---
+
+Document post-migration package ownership, dependency boundaries, key files, and package relationships for contributors.

.changeset/lazy-maps-prompt.md

@@ -0,0 +1,7 @@
+---
+"@cloudflare/polystella-astro": patch
+"@cloudflare/polystella-core": patch
+"@cloudflare/polystella-adapters": patch
+---
+
+Keep format-specific prompt guidance in its owning adapter, enforce segment grouping invariants, and reject duplicate segment IDs in the format-neutral core.

.changeset/tidy-adapter-layout.md

@@ -0,0 +1,6 @@
+---
+"@cloudflare/polystella-astro": minor
+"@cloudflare/polystella-adapters": minor
+---
+
+Colocate the Markdown and MDX adapter implementation, move MDX-specific options out of generic contracts, protect nested inline JSX, and reject malformed key paths.

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/PULL_REQUEST_TEMPLATE.md

@@ -37,7 +37,7 @@ Closes #
 - [ ] 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 exec tsc --noEmit` 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
 
 ## AI-generated code disclosure

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
   test:
     name: Test
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
@@ -30,8 +30,18 @@ jobs:
           node-version: 24.x
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: pnpm test
-      - run: pnpm exec tsc --noEmit
+      - name: Audit production dependencies
+        run: pnpm audit:prod
+      - name: Test reusable packages under Node
+        run: pnpm test:packages
+      - name: Test Astro package under Node
+        run: pnpm test:node
+      - name: Test reusable packages under workerd
+        run: pnpm test:workerd
+      - name: Check package boundaries
+        run: pnpm test:boundaries
+      - name: Typecheck all public packages
+        run: pnpm typecheck
 
   format:
     name: Prettier check
@@ -74,9 +84,9 @@ jobs:
           fi
 
   build:
-    name: Library + CLI build
+    name: Topological package build
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
@@ -87,23 +97,32 @@ jobs:
           node-version: 24.x
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: pnpm build
+      - name: Build all public packages in dependency order
+        run: pnpm build
+      - name: Check packed packages in a clean consumer
+        run: pnpm check:packages
       - name: Verify dist tree
         # Smoke-check every exports entry resolves to an emitted file.
         run: |
-          test -f dist/cli.js
-          test -x dist/cli.js
-          test -f dist/index.js
-          test -f dist/index.d.ts
-          test -f dist/runtime/index.js
-          test -f dist/runtime/middleware.js
-          test -f dist/runtime/locals.d.ts
-          test -f dist/content/index.js
-          test -f dist/i18n/index.js
-          test -f dist/react/index.js
+          test -f packages/astro/dist/cli.js
+          test -x packages/astro/dist/cli.js
+          test -f packages/astro/dist/index.js
+          test -f packages/astro/dist/index.d.ts
+          test -f packages/astro/dist/runtime/index.js
+          test -f packages/astro/dist/runtime/middleware.js
+          test -f packages/astro/dist/runtime/locals.d.ts
+          test -f packages/astro/dist/content/index.js
+          test -f packages/astro/dist/i18n/index.js
+          test -f packages/astro/dist/react/index.js
+          test -f packages/polystella/dist/cli.js
+          test -x packages/polystella/dist/cli.js
+          test -f packages/polystella/dist/index.js
+          test -f packages/polystella/dist/index.d.ts
       - name: Smoke-test the CLI bundle under bare Node
         # No tsx, no Vite — exactly the environment a downstream
         # consumer's standalone `polystella <subcommand>` invocation
         # uses. Regression guard for the Node 24
         # `ERR_UNSUPPORTED_NODE_MODULES_TYPESCRIPT` class of bug.
-        run: node dist/cli.js --version
+        run: |
+          node packages/astro/dist/cli.js --version
+          node packages/polystella/dist/cli.js --version

.github/workflows/docs.yml

@@ -6,16 +6,40 @@ on:
       - main
     paths:
       - "docs/**"
-      - "src/config/options.ts"
+      - "packages/astro/src/config/options.ts"
+      - "packages/core/package.json"
+      - "packages/adapters/package.json"
+      - "packages/providers/package.json"
+      - "packages/astro/package.json"
+      - "packages/polystella/package.json"
       - "package.json"
+      - "AGENTS.md"
+      - "PACKAGE_ARCHITECTURE.md"
+      - "ARCHITECTURE.md"
+      - "skills/polystella-consumer/SKILL.md"
+      - "skills/polystella-contributor/SKILL.md"
+      - "scripts/build-llms-full.mjs"
+      - "llms-full.txt"
       - ".github/workflows/docs.yml"
   pull_request:
     branches:
       - main
     paths:
       - "docs/**"
-      - "src/config/options.ts"
+      - "packages/astro/src/config/options.ts"
+      - "packages/core/package.json"
+      - "packages/adapters/package.json"
+      - "packages/providers/package.json"
+      - "packages/astro/package.json"
+      - "packages/polystella/package.json"
       - "package.json"
+      - "AGENTS.md"
+      - "PACKAGE_ARCHITECTURE.md"
+      - "ARCHITECTURE.md"
+      - "skills/polystella-consumer/SKILL.md"
+      - "skills/polystella-contributor/SKILL.md"
+      - "scripts/build-llms-full.mjs"
+      - "llms-full.txt"
       - ".github/workflows/docs.yml"
 
 permissions:
@@ -40,9 +64,13 @@ jobs:
           node-version: 24.x
           cache: pnpm
       - run: pnpm install --frozen-lockfile
+      - name: Verify generated agent context is current
+        run: |
+          pnpm build:llms
+          git diff --exit-code llms-full.txt
       - name: Build docs (includes config-reference generation)
         run: pnpm --filter polystella-docs build
       - name: Verify every public export is documented
         run: pnpm --filter polystella-docs check-exports
-      - name: Verify every example builds (currently no-op)
+      - name: Verify examples compile
         run: pnpm --filter polystella-docs check-examples

.github/workflows/pr-triage.yml

@@ -66,19 +66,29 @@ jobs:
             }
 
             const areaMap = {
-              "area/catalog": (file) => file.startsWith("src/catalog/") || file.includes("CATALOG_ONLY_PLAN"),
-              "area/cli": (file) => file === "src/cli.ts" || file.startsWith("src/cli/"),
-              "area/config": (file) => file.startsWith("src/config/"),
-              "area/content": (file) => file.startsWith("src/content/"),
-              "area/docs": (file) => file.startsWith("docs/") || file === "README.md" || file === "CHANGELOG.md",
+              "area/catalog": (file) => file.startsWith("packages/astro/src/catalog/") || file.includes("CATALOG_ONLY_PLAN"),
+              "area/cli": (file) => file === "packages/astro/src/cli.ts" || file.startsWith("packages/astro/src/cli/"),
+              "area/config": (file) => file.startsWith("packages/astro/src/config/"),
+              "area/content": (file) => file.startsWith("packages/astro/src/content/"),
+              "area/docs": (file) =>
+                file.startsWith("docs/") ||
+                file === "README.md" ||
+                /^packages\/(astro|core|adapters|providers)\/(README|CHANGELOG)\.md$/.test(file),
               "area/github": (file) => file.startsWith(".github/"),
-              "area/i18n": (file) => file.startsWith("src/i18n/"),
-              "area/parsing": (file) => file.startsWith("src/parsing/"),
-              "area/routing": (file) => file.startsWith("src/routing/"),
-              "area/runtime": (file) => file.startsWith("src/runtime/") || file.startsWith("src/react/"),
-              "area/storage": (file) => file.startsWith("src/storage/"),
-              "area/tests": (file) => file.startsWith("tests/"),
-              "area/translation": (file) => file.startsWith("src/translation/") || file.startsWith("src/glossary/"),
+              "area/i18n": (file) => file.startsWith("packages/astro/src/i18n/"),
+              "area/parsing": (file) =>
+                file.startsWith("packages/adapters/") || file.startsWith("packages/astro/src/parsing/"),
+              "area/routing": (file) => file.startsWith("packages/astro/src/routing/"),
+              "area/runtime": (file) =>
+                file.startsWith("packages/astro/src/runtime/") || file.startsWith("packages/astro/src/react/"),
+              "area/storage": (file) => file.startsWith("packages/astro/src/storage/"),
+              "area/tests": (file) =>
+                /^packages\/(astro|core|adapters|providers)\/tests\//.test(file) || file.startsWith("tests/"),
+              "area/translation": (file) =>
+                file.startsWith("packages/core/") ||
+                file.startsWith("packages/providers/") ||
+                file.startsWith("packages/astro/src/translation/") ||
+                file.startsWith("packages/astro/src/glossary/"),
             };
 
             for (const file of files) {

.github/workflows/preview-releases.yml

@@ -35,4 +35,4 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm build
       - name: Publish preview
-        run: pnpm exec pkg-pr-new publish --pnpm --commentWithSha .
+        run: pnpm exec pkg-pr-new publish --pnpm --commentWithSha './packages/*'

.github/workflows/release.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-  workflow_dispatch:
 
 permissions: {}
 
@@ -34,9 +33,12 @@ jobs:
           registry-url: "https://registry.npmjs.org"
       - run: npm install -g "npm@^11.5.1"
       - run: pnpm install --frozen-lockfile
+      - run: pnpm audit:prod
       - run: pnpm test
-      - run: pnpm exec tsc --noEmit
+      - run: pnpm typecheck
       - run: pnpm build
+      - run: pnpm check:baseline
+      - run: pnpm check:packages
       - name: Create release PR or publish
         uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1
         with:

.prettierignore

@@ -15,4 +15,4 @@ docs/src/content/docs/configuration/reference.md
 # variants (e.g. `***` / `___` / `---` thematic breaks, inline vs.
 # block footnote definitions). Prettier would normalise them away
 # and defeat the test corpus.
-tests/fixtures/parsing/round-trip/
+packages/astro/tests/fixtures/parsing/round-trip/