Code extraction into separate packages by diogoascarneiro · Pull Request #36 · cloudflare/polystella

diogoascarneiro · 2026-08-31T09:21:13Z

What does this PR do?

Extracts PolyStella from a single Astro package into five packages with explicit dependency boundaries. Astro and its compatibility package share a version; core, adapters, and providers are versioned independently:

@cloudflare/polystella -> @cloudflare/polystella-astro
                              |-> @cloudflare/polystella-adapters -> core
                              |-> @cloudflare/polystella-providers -> core
                              `-> @cloudflare/polystella-core

Makes @cloudflare/polystella-astro the canonical Astro integration.
Keeps @cloudflare/polystella as a forwarding compatibility package.
Extracts platform-neutral translation orchestration, format adapters, and provider transports into reusable packages that work without nodejs_compat.
Adds package boundary, clean-consumer, tarball, workerd, and baseline checks.
Updates CI, release workflows, documentation, examples, contributor guidance, and the MDX playground for the new package graph.
Documents package ownership and dependency direction in PACKAGE_ARCHITECTURE.md.

The extraction also hardens the new package boundaries:

Moves format-specific prompt guidance from core to the Markdown adapter.
Enforces segment grouping and unique-ID invariants in core.
Colocates Markdown and MDX implementation files and moves MDX options out of generic adapter contracts.
Protects recursively nested inline MDX JSX and restores nested placeholders inside-out.
Rejects malformed structured-data key paths after array indexes.
Consolidates duplicated private MDX AST utilities.

Migration notes

Astro consumers should import the integration from @cloudflare/polystella-astro.
Existing @cloudflare/polystella integration imports continue through the compatibility package.
Low-level consumers should import contracts from @cloudflare/polystella-core, formats from @cloudflare/polystella-adapters, and transports from @cloudflare/polystella-providers.
Markdown adapter callers should use MarkdownAdapterExtractOptions and MarkdownAdapterApplyOptions for mdxRules; the generic adapter options are now format-neutral.

Type of change

PolyStella invariants touched

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
pnpm typecheck passes
Docs checks and builds pass

AI-generated code disclosure

This PR includes AI-generated code - model/tool: OpenCode (GPT-5.6 Sol)

Screenshots / logs / test output

pnpm test: 1,299 tests passed, including package, Astro, workerd, and boundary suites.
pnpm typecheck: all five public packages passed strict typechecking.
pnpm check:packages: five tarballs, 17 runtime imports, clean Astro consumers, and both CLIs passed.
pnpm check:baseline: passed.
pnpm format:check and git diff --check: passed.
Documentation export checks, example checks, and production build passed.

…ence Update extraction plan status from "In progress (Steps 1-2 complete)" to "In progress (Steps 1-3 complete)". Mark steps 3-5 as complete in progress table with test counts and verification details. Add completion evidence sections for core (26 tests, p-retry dependency), adapters (40 tests, Remark parser), and providers (33 tests, Workers AI/Anthropic factories) packages. Add corresponding pnpm-lock.yaml entries for packages/core, packages/adapters, and packages

Reorganize from single-package to monorepo with fixed-version group: @cloudflare/polystella-core (translation engine), @cloudflare/polystella-adapters (file format parsers), @cloudflare/polystella-providers (AI transport factories), and @cloudflare/polystella (Astro integration). Update Changesets config to link all four packages at same version. Split test suite into package-level, workerd, and boundary tests with increased CI timeout. Update all

Replace `pnpm exec tsc --noEmit` with `pnpm typecheck` in pull request template checklist.

cloudflare-workers-and-pages · 2026-08-31T09:21:20Z

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Status	Commit	Updated (UTC)	See this deployment's details
Build: Failed ❌ View logs ↗	`cc06e0c`	2026-08-31T15:06:08.399Z	View logs ↗
Build: Failed ❌ View logs ↗	`75b4a25`	2026-08-31T14:49:03.293Z	View logs ↗
Build: Failed ❌ View logs ↗	`b501153`	2026-08-31T14:37:33.089Z	View logs ↗
Build: Failed ❌ View logs ↗	`64ab8a2`	2026-08-31T14:16:32.190Z	View logs ↗
Build: Failed ❌ View logs ↗	`9469492`	2026-08-31T14:06:18.960Z	View logs ↗
Build: Failed ❌ View logs ↗	`941c772`	2026-08-31T13:03:19.538Z	View logs ↗
Build: Failed ❌ View logs ↗	`7778a56`	2026-08-31T10:31:05.626Z	View logs ↗
Build: Failed ❌ View logs ↗	`f021d03`	2026-08-31T09:21:15.584Z	View logs ↗

cloudflare-workers-and-pages · 2026-08-31T09:21:21Z

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	`cc06e0c`	Commit Preview URL Branch Preview URL	Aug 31 2026, 03:06 PM

github-actions · 2026-08-31T09:21:28Z

Scope check

This PR changes 12,594 lines across 277 files. PolyStella is maintained by a small team, so smaller focused PRs are more likely to be reviewed.

If this scope is intentional, no action is required.

pkg-pr-new · 2026-08-31T09:21:52Z

Open in StackBlitz

@cloudflare/polystella-adapters

npm i https://pkg.pr.new/cloudflare/polystella/@cloudflare/polystella-adapters@cc06e0c

@cloudflare/polystella-astro

npm i https://pkg.pr.new/cloudflare/polystella/@cloudflare/polystella-astro@cc06e0c

@cloudflare/polystella-core

npm i https://pkg.pr.new/cloudflare/polystella/@cloudflare/polystella-core@cc06e0c

@cloudflare/polystella

npm i https://pkg.pr.new/cloudflare/polystella/@cloudflare/polystella@cc06e0c

@cloudflare/polystella-providers

npm i https://pkg.pr.new/cloudflare/polystella/@cloudflare/polystella-providers@cc06e0c

commit: cc06e0c

…sion group Add `@cloudflare/polystella-astro` compatibility package to Changesets fixed group alongside core, adapters, providers, and polystella packages. Update all documentation, workflows, and examples to reference five packages instead of four. Update install instructions and import examples to prefer `@cloudflare/polystella-astro` as the canonical Astro integration name. Add CLI smoke test for astro-alias package. Update exports reference to document all 29

Rename `packages/astro-alias/` to `packages/polystella/` to reflect that `@cloudflare/polystella` is the compatibility package forwarding to the canonical `@cloudflare/polystella-astro` integration. Update all references across CI workflows, documentation, changeset descriptions, and test paths. Clarify in exports reference and install guide that `@cloudflare/polystella` forwards to `@cloudflare/polystella-astro` rather than the reverse.

… boundaries and ownership Add PACKAGE_ARCHITECTURE.md as fourth companion doc explaining package graph, dependency direction, per-package responsibilities, key file locations, and boundary enforcement checks. Update AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, and README.md to reference new guide. Add PACKAGE_ARCHITECTURE.md to docs workflow triggers and llms-full.txt generation. Update ARCHITECTURE.md runtime bridge section to clarify custom-loader vs

…o core translateSegments Move flat(groups) === segments validation from markdownAdapter.groupSegments to translateSegments in core package. Update changeset description to reflect enforcement in format-neutral core. Refactor cache.test.ts to use groupSegments callback pattern instead of pre-computed groups array. Add test case for groups that omit segments. Remove "How It Connects" section from core README.

…eResponse, and translateSegments Add assertUniqueSegmentIds helper to segment.ts and call it from buildPrompt, parseResponse, and translateSegments to reject duplicate IDs. Export only Segment type from core index (not assertUniqueSegmentIds). Add test cases for duplicate ID rejection in prompt.test.ts and translate-segments.test.ts. Update changeset description to mention duplicate ID rejection alongside grouping invariants.

…ubdirectory Move markdown.ts, extract.ts, apply.ts, mdx-rules.ts, mdx-placeholders.ts, mdx-jsx-attributes.ts, mdx-static-data.ts, parser.ts, and traverse.ts from src/ to src/adapters/markdown/. Update adapter.ts to make FileAdapter generic over extract/apply options types. Update index.ts barrel exports to reference new paths. Update README.md file locations to reflect new structure. Add MarkdownExtractOptions and MarkdownApplyOptions interfaces extending base adapter options with

…s, and extract shared MDX utilities Recursively protect inline JSX nested in Markdown formatting (bold, italic, links, strikethrough) by traversing children arrays and building placeholders from inside out. Restore nested placeholders in reverse order to reconstruct from innermost to outermost. Extract shared helpers (allowedAttributesForElement, findQuotedAttributeValueSpan, isMdxJsxAttribute, readArrayProperty, readPositionSpan, walkUnknown, getPatternMatcher)

…ders packages Remove core, adapters, and providers from Changesets fixed group, keeping only Astro and compatibility packages locked together. Update workspace dependencies from `workspace:*` to `workspace:^` for independently versioned packages. Update documentation across README.md, AGENTS.md, ARCHITECTURE.md, PACKAGE_ARCHITECTURE.md, and changeset README to reflect independent versioning model. Update check-packages.mjs to validate caret ranges for independent packages and

diogoascarneiro added 5 commits August 28, 2026 09:31

chore: add packages directory to pnpm workspace configuration

a1c56db

chore: remove completed monorepo extraction planning documents

1669544

chore(ci): update PR template to use pnpm typecheck command

f021d03

Replace `pnpm exec tsc --noEmit` with `pnpm typecheck` in pull request template checklist.

github-actions Bot added review/needs-review No maintainer review yet area/docs Documentation area/github GitHub workflows and repo management area/parsing File parsing and adapters area/translation Translation pipeline and providers size/XL 500+ changed lines labels Aug 31, 2026

diogoascarneiro added 2 commits August 31, 2026 11:30

github-actions Bot added the area/tests Tests and fixtures label Aug 31, 2026

diogoascarneiro added 6 commits August 31, 2026 15:05

diogoascarneiro merged commit 0612536 into main Aug 31, 2026
16 of 17 checks passed

diogoascarneiro deleted the monorepo-extraction branch August 31, 2026 15:31

Navigation Menu

Uh oh!

Code extraction into separate packages - #36

Code extraction into separate packages#36
diogoascarneiro merged 13 commits into
mainfrom
monorepo-extraction

diogoascarneiro commented Aug 31, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 31, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 31, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 31, 2026

Uh oh!

pkg-pr-new Bot commented Aug 31, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

diogoascarneiro commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Migration notes

Type of change

PolyStella invariants touched

Checklist

AI-generated code disclosure

Screenshots / logs / test output

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Deploying Preview to Cloudflare 🚀

Preview Deployments by commit

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

github-actions Bot commented Aug 31, 2026

Scope check

Uh oh!

pkg-pr-new Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

diogoascarneiro commented Aug 31, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Aug 31, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Aug 31, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 31, 2026 •

edited

Loading