Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

cli docs: integration guides, a last pass on every doc, and `integration verify` (#6737)

Joeyf0355e3a4c9d
diff --git a/.changeset/cli-docs-last-pass.md b/.changeset/cli-docs-last-pass.md
new file mode 100644
index 0000000000..bebc29b3ac
--- /dev/null
+++ b/.changeset/cli-docs-last-pass.md
@@ -0,0 +1,17 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] Fix the CLI's topic docs and how they print.
+
+- A code block's label now prints above the block instead of as a `// label` line inside it, so copied bash, CSS, JSON, and HTML stay valid. Table cells escape `|`, so a union type stays in one column.
+- `astryx search dark mode` searches for both words; it used to drop every word after the first. A result that matches every word of a query, one of them by name or keyword, now outranks one that matches only some, and a section whose title or heading holds the whole query ranks near the top. Topics can declare search `keywords`, now a documented ReferenceDoc field, and a namespace's `keywords` now count too. A query keeps its phrase when common words such as `make`, `build`, or `an` drop out, so `astryx search make an integration` finds the integration guides, a plural of a doc's name matches it, one step below the exact name, and a component's name typed as words, such as `command palette`, finds the component. Outside an app, where `@astryxdesign/core` is not installed, `astryx search` searches the docs instead of failing, and says so; `--type component`, `hook`, or `template` still needs Core.
+- Snippets that failed when copied now work: StyleX token imports, the `fr-FR.json` locale path, Tailwind `rounded-lg`, `--color-background-muted`, icon and color values, and the Cursor rule path.
+- Claims that did not match the code are corrected: the 30 shipped locales and how RTL mirroring works, what `astryx init` writes, `--detail brief` for a shorter read, the Neutral and Matcha fonts, the components that need anchor positioning, `gap` steps, Card's radius, and the Next.js StyleX example. The deprecated bare classes are still emitted and will be removed in a later release.
+- `astryx docs tokens` lists all 258 tokens, adding the data visualization and syntax groups, and shows both halves of every `light-dark()` value.
+- Long sections are split, vague titles renamed, and the `--dense` and Chinese versions no longer drop blocks. Eleven long section keys are shorter, such as `astryx docs styling stylex-setup`, and every old key still resolves. An integration section that extends a Core topic by a section's old title still replaces that section.
+- `astryx integration add codemod --to` help says it takes the Core version whose upgrade runs the codemod.
+- The agent block that `astryx init` writes now says `upgrade --from <old version> --apply`; `upgrade --apply` alone stops with "Missing required --from".
+- The contributor-only sections, on adding a semantic icon and on strings and text direction inside components, moved to CONTRIBUTING.md.
+
+@josephfarina
diff --git a/.changeset/cli-reference-last-pass.md b/.changeset/cli-reference-last-pass.md
new file mode 100644
index 0000000000..1db7eaba49
--- /dev/null
+++ b/.changeset/cli-reference-last-pass.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] The CLI reference now matches what the commands do. Every `--help` ends with the command's examples and a `More:` line that names its full docs page. Function docs show each parameter's default, mark required parameters, list the error codes each function throws, and use examples that run. The response-type list adds `help`, `version`, and `upgrade.registry`, and `astryx manifest` now lists `upgrade.registry` for `upgrade`. The `--zh`, `--dense`, `--lang`, and `--detail` descriptions name the commands they change, and command summaries say when to use each command. When `astryx template` refuses to overwrite a file, it now says to re-run with `--overwrite` (or `-f`). The `upgrade` command page (`astryx docs cli/commands/upgrade`) now explains which files codemods never edit, what happens when one of them needs a change, and how to regenerate it.
+
+@josephfarina
diff --git a/.changeset/doctor-integration-docs-placement.md b/.changeset/doctor-integration-docs-placement.md
new file mode 100644
index 0000000000..fe1fbd42e9
--- /dev/null
+++ b/.changeset/doctor-integration-docs-placement.md
@@ -0,0 +1,11 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx doctor integration docs` fails when a namespace doc or a placement fails, as its help says.
+
+Such a failure hides the doc from the docs tree, so it now exits 1 with an `invalid_doc_graph` error instead of a warning. A link that names no doc still only warns, since it prints as written. `doctor integration docs` and `doctor integration components` also no longer print an `[ok]` line after a check that failed.
+
+A mistyped subcommand under `doctor` now fails and lists the subcommands the group has: `astryx doctor integrations` used to run the project checks, and `astryx doctor integration bogus` exited 0 in text though it exited 1 with `--json`.
+
+@josephfarina
diff --git a/.changeset/integration-themes-need-cli.md b/.changeset/integration-themes-need-cli.md
new file mode 100644
index 0000000000..40dc64bfb7
--- /dev/null
+++ b/.changeset/integration-themes-need-cli.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] A package that ships a theme, or a doc section with an `id`, now declares the CLI that can read it.
+
+A stable CLI before 0.7.0 rejects both: it cannot read the typed theme descriptors that `astryx integration add theme` writes, and it rejects a section `id`. Either way it hides the package's themes or doc topics with no warning. `astryx integration add theme` now adds `"@astryxdesign/cli": ">=0.7.0"` to `peerDependencies`, marked optional, and `astryx integration verify` fails with `themes_need_cli` or `section_ids_need_cli` when a package needs that peer range and does not declare it.
+
+@josephfarina
diff --git a/.changeset/integration-verify-packed-imports.md b/.changeset/integration-verify-packed-imports.md
new file mode 100644
index 0000000000..5044a87359
--- /dev/null
+++ b/.changeset/integration-verify-packed-imports.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx integration verify` resolves every public import in the packed package, not in your source folder.
+
+Before, its temporary app resolved your package's own name through the source `package.json`, so an `exports` target left out of the tarball still passed. It now fails with `component_export_missing`, as an app that installs the tarball would.
+
+@josephfarina
diff --git a/.changeset/integration-verify.md b/.changeset/integration-verify.md
new file mode 100644
index 0000000000..9ce5cc00ea
--- /dev/null
+++ b/.changeset/integration-verify.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] `astryx integration verify` is the new name of `astryx integration pack --check`.
+
+The check you run before publishing an integration now has a name that says what it does. `astryx integration verify` packs the package with npm, installs the tarball into a temporary app, and checks that the app sees the same components, templates, themes, docs, and codemods. It takes no flags. `astryx integration pack --check` still works as a deprecated alias: it runs the same check with the same output, JSON, and exit codes, prints a note that names `integration verify`, and shows as deprecated in help. It will be removed in a later release. The `integrationPackCheck()` API and its `integration.pack-check` JSON response do not change. With `--json`, a command group given an unknown subcommand now reports `ERR_UNKNOWN_SUBCOMMAND` and lists its subcommands, where it used to say JSON output is not supported.
+
+@josephfarina
diff --git a/AGENTS.md b/AGENTS.md
index 3c04f5add7..5cf97fac87 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -147,7 +147,7 @@ Documentation lives in two places:
**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.
-**Audience**: every `.doc.mjs`, and everything under `packages/cli/assets/docs/`, is written for people **building with** Astryx — not for people building Astryx. Rubrics, readiness gates, audit checklists and lab→core criteria belong in the wiki. [`packages/cli/assets/docs/README.md`](packages/cli/assets/docs/README.md) has the test and the page each kind of material goes to.
+**Audience**: every `.doc.mjs`, and everything under `packages/cli/assets/docs/`, is written for people **building with** Astryx — not for people building Astryx. Internal review rubrics, readiness gates, audit checklists and lab→core criteria belong in the wiki. A public authoring-quality rubric belongs in shipped docs when callers use it to evaluate an artifact they create through Astryx and a current system spec assigns that ownership. [`packages/cli/assets/docs/README.md`](packages/cli/assets/docs/README.md) has the test and the page each kind of material goes to.
## Quick Reference
@@ -219,10 +219,10 @@ astryx component <Name> --dense # props, variants, usage, anatomy for one compon
astryx template <name> # emit full page source
astryx template <name> --skeleton # layout skeleton with spatial annotations
astryx swizzle <Name> # eject component source for deep customization
-astryx upgrade --apply # run version migration codemods
+astryx upgrade --from <old version> --apply # run version migration codemods
OPTIONS: --detail compact|brief less output | --dense token-efficient | --zh Chinese
RULE: always run bootstrap on each branch — docs reflect the branch's actual API
RULE: always run astryx component <Name> --dense before modifying a component
-RULE: after @astryxdesign/core bump, always run astryx upgrade --apply
+RULE: after @astryxdesign/core bump, always run astryx upgrade --from <old version> --apply
<!-- ASTRYX-CLI:END -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c4502bd762..b80d7a3abe 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -289,6 +289,83 @@ export * from './MyComponent';
> committed automatically when changes land on `main`. If you need to verify your
> component will be included, run `pnpm sync:exports:check`.
+### User-facing strings and text direction
+
+Components read user-facing strings with `useTranslator()` rather than
+hardcoding them:
+
+```tsx
+import {useTranslator} from '@astryxdesign/core/i18n';
+
+function SaveButton() {
+ const t = useTranslator();
+ return <button>{t('@astryx.actions.save')}</button>;
+}
+```
+
+Astryx's own strings live in `packages/core/locales/en.json`. The
+`@astryx/no-hardcoded-i18n-string` ESLint rule rejects a hardcoded one. For a
+prop whose default is a translated string, alias the prop and resolve it in the
+body: destructure `label: labelFromProps`, then
+`const label = labelFromProps ?? t('@astryx.<component>.<key>')`.
+
+A component that responds to text direction resolves it from the DOM, not from
+a render-time JavaScript read. Reach for the lightest tool that works, in this
+order:
+
+1. **CSS logical properties.** Use `insetInlineStart`, `paddingInlineEnd`,
+ `marginInline`, and friends instead of physical `left`/`right`. Most
+ mirroring needs nothing more: the browser flips it from the ambient `dir`.
+ The `@astryx/no-physical-properties` ESLint rule enforces this.
+2. **Directional icons: mirror with CSS, not a name swap.** Render one fixed
+ glyph and wrap it in the shared `rtlStyles.mirror` (a `scaleX(-1)` that only
+ applies under `[dir="rtl"]`). It flips from the ancestor `dir` through the
+ cascade, so it works on the server with no hydration flash. Do not pick
+ `chevronLeft` or `chevronRight` in JavaScript. Pagination, Calendar, and
+ Carousel handle their chevrons this way.
+
+ ```tsx
+ import * as stylex from '@stylexjs/stylex';
+ import {rtlStyles} from '@astryxdesign/core';
+
+ function NextButton() {
+ // One glyph; CSS flips it under RTL. No direction read.
+ return (
+ <span {...stylex.props(rtlStyles.mirror)}>
+ <Icon icon="chevronRight" />
+ </span>
+ );
+ }
+ ```
+
+3. **Behavior: read the DOM lazily, on the event.** For what CSS can't express
+ (arrow-key mapping, drag and scroll math), read direction at interaction
+ time with `isRtlElement(el)` (a `getComputedStyle().direction` check), never
+ during render. The focus hooks (`useListFocus`, `useGridFocus`,
+ `useTreeFocus`) already detect direction from their container, so arrow keys
+ flip for free; don't pass them a direction flag.
+4. **`useDirection()` context, as a last resort.** Use it only when you need
+ the direction value during render and nothing above fits. It is SSR-safe
+ and returns `'ltr'` outside a provider (like `useTranslator`'s silent
+ fallback), but it is the one path that can mismatch on hydration when the
+ provider's direction disagrees with `<html dir>`. No Astryx component reads
+ direction from context at render time.
+
+### Adding a semantic icon
+
+Add a semantic icon name only for a glyph the whole system shares:
+
+1. Add the name to the `IconName` type in
+ `packages/core/src/Icon/globalIconRegistry.tsx`.
+2. Add the default SVG to `packages/core/src/Icon/defaultIcons.tsx`.
+3. Add a row to the Available Names table in
+ `packages/cli/assets/docs/icons.doc.mjs`.
+
+A glyph that belongs to one component takes a namespaced key instead
+(`numberInput:stepperDown`), so the shared `IconName` list does not grow. Ship
+its fallback in `defaultIcons` under the same key so the glyph still renders
+with no theme.
+
## Accessibility Checklist
Every new component — and any change to an interactive one — must clear the
@@ -817,7 +894,8 @@ and doesn't need network to use.
Astryx accepts community translations via Crowdin. To help translate astryx
into your language, visit <https://crowdin.com/project/astryx>. New locales are
picked up automatically after a maintainer reviews the auto-generated
-translations PR.
+translations PR. Direct PRs against `packages/core/locales/*.json` also work if
+you prefer that flow.
Calendar’s compact weekday labels, such as `Su` and `Mo`, are generated from
Unicode CLDR data because browsers do not provide that format.
diff --git a/apps/docsite/next.config.mjs b/apps/docsite/next.config.mjs
index be1363f5be..15d48f568c 100644
--- a/apps/docsite/next.config.mjs
+++ b/apps/docsite/next.config.mjs
@@ -43,6 +43,23 @@ const nextConfig = {
],
};
},
+ // The CLI's integration guide became short guides under cli/integrations,
+ // each with its own page (/docs/cli-integrations-<name>). The old guide
+ // pages redirect to where their content now starts.
+ async redirects() {
+ return [
+ {
+ source: '/docs/cli-integrations',
+ destination: '/docs/cli-integrations-overview',
+ permanent: true,
+ },
+ {
+ source: '/docs/cli-writing-docs',
+ destination: '/docs/cli-integrations-docs-add-a-topic',
+ permanent: true,
+ },
+ ];
+ },
// The playground preview evaluates user-authored code, so it is the one
// route that must never be embeddable by another site and never a loader of
// third-party script. The nonce-attested port handshake on its message
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 6b277911e0..4a406754fc 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -1687,14 +1687,19 @@ export const templateMetadataCount = ${templateMetadata.length};
*/
async function docsTreeGuides() {
const guides = [];
+ // Every route the tree has. The site has a page only for a guide; a
+ // reference to any other route still opens it in `astryx docs`.
+ const routes = [];
const list = await readDocs();
const pending = (list.meta?.namespaces ?? []).map(entry => entry.topic);
while (pending.length > 0) {
const route = pending.shift();
+ routes.push(route);
const read = await readDocs(route);
if (read.type !== 'docs.node') continue;
for (const slot of read.data.slots) {
for (const child of slot.children) {
+ if (child.kind !== 'namespace') routes.push(child.route);
if (child.kind === 'namespace') {
pending.push(child.route);
} else if (child.kind === 'generic' && child.route.includes('/')) {
@@ -1712,7 +1717,7 @@ async function docsTreeGuides() {
}
}
}
- return guides;
+ return {guides, routes};
}
async function generateDocsRegistry() {
@@ -1722,7 +1727,7 @@ async function generateDocsRegistry() {
if (!fs.existsSync(DOCS_DIR)) {
writeRegistry(
'docsRegistry.ts',
- `// Auto-generated — no docs found\nexport const docTopics = [];\nexport const docsCount = 0;\n`,
+ `// Auto-generated — no docs found\nexport const docTopics = [];\nexport const docsCount = 0;\nexport const docsTreeRoutes = [];\n`,
);
return {docTopics: [], docsCount: 0};
}
@@ -1784,10 +1789,12 @@ async function generateDocsRegistry() {
// Guides the CLI's docs tree places (spec:AST-046) are not topic files: the
// CLI reads them only by route. Until the site renders the tree itself, each
// keeps a flat page whose slug is its route with "/" as "-", so
- // `cli/integrations` stays at /docs/cli-integrations.
- for (const guide of await docsTreeGuides()) {
+ // `cli/integrations/quick-start` is /docs/cli-integrations-quick-start.
+ const tree = await docsTreeGuides();
+ for (const guide of tree.guides) {
docTopics.push(guide);
}
+ const docsTreeRoutes = [...new Set(tree.routes)].sort();
docTopics.sort((a, b) => a.topic.localeCompare(b.topic));
@@ -1833,6 +1840,10 @@ export interface DocTopic {
export const docTopics: DocTopic[] = ${JSON.stringify(docTopics, null, 2)};
export const docsCount = ${docTopics.length};
+
+/** Every route of the CLI's docs tree. A guide has a page here; any other
+ * route (a namespace, a command or API doc) opens only in \`astryx docs\`. */
+export const docsTreeRoutes: string[] = ${JSON.stringify(docsTreeRoutes, null, 2)};
`;
writeRegistry('docsRegistry.ts', content);
return {docTopics, docsCount: docTopics.length};
diff --git a/apps/docsite/src/__tests__/code-linkifiers.test.ts b/apps/docsite/src/__tests__/code-linkifiers.test.ts
index 0c0e32d767..de53c4bb4a 100644
--- a/apps/docsite/src/__tests__/code-linkifiers.test.ts
+++ b/apps/docsite/src/__tests__/code-linkifiers.test.ts
@@ -8,7 +8,7 @@
import {describe, it, expect} from 'vitest';
import {linkifyCode} from '../components/codeLinkifiers';
-import {docTopics} from '../generated/docsRegistry';
+import {docTopics, docsTreeRoutes} from '../generated/docsRegistry';
import {components} from '../generated/componentRegistry';
describe('doc topic linkifier', () => {
@@ -122,7 +122,16 @@ describe('doc references in shipped content', () => {
});
it('links every reference to a page the site serves', () => {
+ // A docs-tree route the site has no page for yet (a namespace, a command
+ // or API doc) stays plain code, and still opens in `astryx docs`; any
+ // other unlinked reference is stale.
+ const treeRoutes = new Set(docsTreeRoutes);
+ const inTree = (ref: string) =>
+ treeRoutes.has(ref.replace(/^(?:npx )?astryx docs /, '').split(' ')[0]);
const all = Object.values(corpora).flatMap(docReferences);
- expect(all.filter(ref => linkifyCode(ref) == null)).toEqual([]);
+ expect(all.filter(ref => linkifyCode(ref) == null && !inTree(ref))).toEqual(
+ [],
+ );
+ expect(treeRoutes.has('cli/commands/upgrade')).toBe(true);
});
});
diff --git a/apps/docsite/src/components/docs/TokensDocView.tsx b/apps/docsite/src/components/docs/TokensDocView.tsx
index 2371fc44d1..cc713d8085 100644
--- a/apps/docsite/src/components/docs/TokensDocView.tsx
+++ b/apps/docsite/src/components/docs/TokensDocView.tsx
@@ -53,7 +53,7 @@ const TOPIC_SECTION_OVERRIDES: Record<
'Type Scale Tokens': TypographyTokenTable,
},
color: {
- 'Surface Colors': ColorTokenTable,
+ 'Color Tokens': ColorTokenTable,
},
elevation: {
'Elevation Scale': ElevationTokenTable,
diff --git a/docs/architecture/cli-surface.md b/docs/architecture/cli-surface.md
index 3316925956..20464ba137 100644
--- a/docs/architecture/cli-surface.md
+++ b/docs/architecture/cli-surface.md
@@ -158,7 +158,7 @@ and remains available through explicit Core package selection.
same installed package in place, preserving its configured order while making
working bytes authoritative.
- **INV17 — Pack verification examines the artifact consumers receive.**
- `integration pack --check` runs the package lifecycle through `npm pack`,
+ `integration verify` runs the package lifecycle through `npm pack`,
compares the required file inventory with the actual tarball, extracts that
tarball into a scratch consumer, and reruns contribution discovery. It rejects
advertised component imports ending in `.ts` or `.tsx`, resolves every exact
@@ -281,7 +281,7 @@ updated in the same pull request when it moves an invariant:
or JSON (INV27);
- changing an integration writer's receipt, no-clobber/rollback behavior,
package.json mutation policy, or public subpath spelling;
-- changing what `integration pack --check` executes, resolves, or proves about
+- changing what `integration verify` executes, resolves, or proves about
the tarball;
- changing local, configured, or autolinked integration precedence;
- changing an integration item descriptor, the theme directory boundary, or the consumer copy contract.
diff --git a/docs/architecture/template-authoring.md b/docs/architecture/template-authoring.md
index b3f25a5282..8a7c33db41 100644
--- a/docs/architecture/template-authoring.md
+++ b/docs/architecture/template-authoring.md
@@ -44,8 +44,9 @@ content surfaces. Block templates provide focused patterns and component example
This record owns their source shapes, catalog identity, validation boundary,
consumer projections, and copy semantics.
-It does not copy contributor instructions, visual-design guidance, or the grading
-rubric. Those facts have separate owners under [Delegated authority](#delegated-authority).
+It does not copy contributor instructions or internal audit-publication workflow.
+The shipped template-quality guide owns the public grading rubric, and the
+public contributor guide links to that source.
## System model
@@ -169,11 +170,13 @@ authoring check; it does not replace runtime catalog validation.
This record does not absorb adjacent facts:
-- The public [Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates)
- guide owns contributor workflow, naming and description guidance, implementation
- recipes, grading rules, rubric versioning, and the score-ledger procedure. Its
- current statement that renaming is breaking is superseded by
- `spec:AST-017/DEC-2`.
+- The shipped `cli/integrations/templates/template-quality` guide owns the public
+ grading rules, rubric version, grade bands, categories, weights, and agent
+ workflow. The public
+ [Contributing Templates](https://github.com/facebook/astryx/wiki/Contributing-Templates)
+ guide owns contributor workflow and the score-ledger publication procedure,
+ and links to the shipped rubric instead of copying it. Its current statement
+ that renaming is breaking is superseded by `spec:AST-017/DEC-2`.
- `design:template-composition` owns shared human visual, hierarchy, responsive, and
interaction intent. It remains a candidate record while its authority is `draft`.
- Component, module, and family records own the behavior of components composed by a
@@ -198,13 +201,18 @@ This record does not absorb adjacent facts:
target and regenerates the showcase/example registries.
- A visual or interaction change follows applicable current design, family, and
component records. One review does not substitute for another.
-- A rubric scoring change increments the rubric version and updates the score-ledger
- contract. It changes this architecture only when it moves a system boundary.
+- A rubric scoring change updates the shipped template-quality guide's version
+ and score-ledger contract together. It changes this architecture only when it
+ moves a system boundary.
- A proposal to share behavior across several templates updates the relevant family,
design, or system record rather than inferring a contract from similarity.
## Owning code
+- `packages/cli/assets/docs/tree/template-quality.doc.mjs` and its child guides —
+ the canonical public rubric and agent grading workflow.
+- `scripts/template-score-ledger.mjs` — rubric score persistence; imports the
+ canonical version, grade bands, categories, and weights from the guide.
- `packages/cli/assets/templates/` — built-in page and block source plus metadata.
- `packages/cli/authoring/doctypes/template/` — first-party authoring types and the
runtime template envelope.
diff --git a/docs/specs/AST-046-docs-tree/spec.md b/docs/specs/AST-046-docs-tree/spec.md
index 2c48cf1d8e..5fb0fb913f 100644
--- a/docs/specs/AST-046-docs-tree/spec.md
+++ b/docs/specs/AST-046-docs-tree/spec.md
@@ -114,14 +114,14 @@ the docsite onto the tree.
checks are new, so they warn: a project that passed before keeps passing. The progressive-disclosure check MUST hold each guide the tree
places to the same size budget as every topic.
- **FR9 — Phase 1 places the CLI's own docs.** The CLI MUST ship the `cli`
- namespace with the `integrations` guide and the `commands` and `api`
+ namespace with the `integrations` namespace and the `commands` and `api`
namespaces under it. Every command doc MUST have a route under
`cli/commands`, and every function, schema, and enum doc in the `cli/api`
- group a route under `cli/api/<kind>s`. The integration guide's route MUST be
- `cli/integrations`; its old flat name `cli-integrations` is gone. Under
- `spec:AST-017/FR45`, a CLI route or name MAY change like this when every
- reference changes with it: links name docs by identity (`spec:AST-047` FR9),
- and the graph walk fails on a reference
+ group a route under `cli/api/<kind>s`. The integration guides MUST live under
+ `cli/integrations`, one short guide per task; the old flat name
+ `cli-integrations` is gone. Under `spec:AST-017/FR45`, a CLI route or name MAY
+ change like this when every reference changes with it: links name docs by
+ identity (`spec:AST-047` FR9), and the graph walk fails on a reference
left behind (`spec:AST-047` FR11, FR12).
- **FR10 — Search finds the smallest part that answers.** `astryx search` MUST
index each section of each topic and placed guide, and each namespace and
@@ -145,7 +145,9 @@ the docsite onto the tree.
provider that lost it, and the topic list, reads, and search MUST agree with
the tree. `astryx doctor integration docs` MUST run the
same tree and link checks on one integration's docs, so an author finds a
- broken placement or link before the package ships, and
+ broken placement or link before the package ships. It MUST fail on a tree
+ error diagnostic filed against the package, since that hides a doc, and warn
+ on a link that names no doc; `astryx doctor` keeps FR8's warnings. And
`astryx integration add doc <name> --parent <namespace>` MUST write a guide
placed in that namespace, found by its name, and the namespace doc when the
package has none. A CLI release that does not read the docs tree can hide every doc topic of a
@@ -153,8 +155,10 @@ the docsite onto the tree.
(published 0.6.3 does so for a namespace doc, and earlier builds of main for a
placed guide too), so such a package MUST declare a `@astryxdesign/cli` peer
range that admits only CLIs that read it: `integration add doc --parent` MUST declare it,
- and `astryx integration pack --check` MUST fail without it. The same check
- covers a template that sets `replaces` (`spec:AST-035`).
+ and `astryx integration verify` MUST fail without it. The same check
+ covers a template that sets `replaces` (`spec:AST-035`), a doc section that
+ sets `id`, and a theme, whose typed descriptor an older CLI rejects along
+ with the package's doc topics; `integration add theme` declares the peer.
- **FR12 — Every doc has a home.** Every flat topic, the CLI's and each
integration's, MUST sit in the generated Unorganized level (`unorganized`), in
the order the topic list reads. The level has no authored doc, so its `id` is
@@ -191,8 +195,8 @@ Phase 1 changes:
- `cli-integrations` moves to `cli/integrations`, and every reference moves
with it;
- every flat topic sits in the generated Unorganized level, as FR12 states;
-- the docsite reads the placed guide through `docs()` and keeps
- `/docs/cli-integrations`.
+- the docsite reads the placed guides through `docs()`, and
+ `/docs/cli-integrations` redirects to the first of them.
`architecture:cli-surface` INV25 and INV26 carry this record into the code.
diff --git a/packages/cli/README.md b/packages/cli/README.md
index e9dbcf3c96..6f2303757b 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -30,7 +30,8 @@ The CLI documents itself, so these commands print what the installed version doe
`astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
`TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
`astryx docs authoring <section>`, for example `astryx docs authoring config`.
-- `astryx docs cli/integrations`: the guide to building an integration package.
+- `astryx docs cli/integrations`: the guides to building an integration package,
+ from a quick start to publishing.
- `astryx docs`: every docs topic, including the design-system guides (for
example `tokens`, `theme`, and `layout`).
@@ -77,36 +78,36 @@ Options:
<!-- BEGIN GENERATED: commands -->
-| Command | Description |
-| ------------- | ----------------------------------------------------------------------------- |
-| `blog` | Read the Astryx blog from the published feed |
-| `build` | Build a page: the template to start from, or the workflow playbook (no query) |
-| `component` | List components or print component docs |
-| `discover` | Browse and search integrations: the ones you have and the ones you could add |
-| `docs` | Print reference docs |
-| `doctor` | Diagnose Astryx projects and integration packages |
-| `gap-report` | Route a design-system gap to its owning package |
-| `hook` | List hooks or print hook docs |
-| `init` | Initialize the design system in your project |
-| `integration` | Author and verify an Astryx integration package |
-| `search` | Search components, hooks, docs, and templates in one ranked list |
-| `swizzle` | Copy component source for customization |
-| `template` | Inject a page or block template |
-| `theme` | Theme tools: build, export, and manage themes |
-| `upgrade` | Migrate versions and update ShadCN-copied compositions |
+| Command | Description |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `blog` | Read the Astryx blog from the published feed |
+| `build` | Build a page: the template to start from, or the workflow playbook (no query) |
+| `component` | List components or print component docs |
+| `discover` | Browse and search integrations: the ones you have and the ones you could add |
+| `docs` | Print reference docs |
+| `doctor` | Diagnose Astryx projects and integration packages |
+| `gap-report` | Report a missing component or feature to the package that owns it |
+| `hook` | List hooks or print hook docs |
+| `init` | Initialize the design system in your project |
+| `integration` | Author and verify an Astryx integration package |
+| `search` | Search components, hooks, docs, and templates in one ranked list |
+| `swizzle` | Copy component source for customization |
+| `template` | List, show, or scaffold page and block templates |
+| `theme` | Create and build themes: add a shipped one, compile to CSS, or list what a theme can override |
+| `upgrade` | Update your code after upgrading Astryx, and refresh ShadCN-copied components |
<!-- END GENERATED: commands -->
<!-- Generated by scripts/generate-cli-readme.mjs from `astryx manifest`. Run `pnpm -F @astryxdesign/cli readme`. -->
### Global options
-These flags work with any command:
+`--json` works with every command listed in `jsonSupported` (`astryx manifest --json`), which is every command except the bare groups such as `astryx theme`. The other four change only the reads named here; other commands ignore them:
- `--json`: Output as typed JSON envelope: `{ apiVersion, type, data, meta? }` (errors: `{ apiVersion, error, code, suggestions? }`)
-- `--detail <level>`: Detail level for list views, increasing in size: `brief` (names only, default for `--list`) < `compact` (names + 1-line descriptions) < `full` (full docs per entry). Single-item views default to `full`.
-- `--zh`: Output docs in Chinese Simplified
-- `--dense`: Compressed format (token-efficient, useful for AI agents)
-- `--lang <locale>`: Language/format shorthand (`en`, `zh`, `dense`)
+- `--detail <level>`: Detail level for `component`, `hook`, and docs tree reads (such as `astryx docs cli/commands/build`), increasing in size: `brief` (names only, default for lists) < `compact` (names + 1-line descriptions) < `full` (full docs per entry). Single-item views default to `full`.
+- `--zh`: Simplified Chinese for component reads and for docs topics that have a translation (English otherwise)
+- `--dense`: Token-efficient dense text for `astryx component <Name>` and `astryx docs <topic>`
+- `--lang <locale>`: Language or format for component and docs reads: `en` (default), `zh` (as `--zh`), or `dense` (as `--dense`)
## JSON API
@@ -163,9 +164,9 @@ if (isError(result)) {
| `ERR_UNKNOWN` | Fallback for any error without a more specific code. |
| `ERR_UNKNOWN_COMMAND` | A top-level command name was not recognized (e.g. `astryx bogus`). |
| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a command group was not recognized (e.g. `astryx theme bogus`). |
-| `ERR_INVALID_OPTION` | An unknown flag/option was passed (Commander `unknownOption`). |
-| `ERR_INVALID_ARGUMENT` | An option/argument had a value Commander's parser rejected. |
-| `ERR_MISSING_ARGUMENT` | A required positional argument was omitted (Commander `missingArgument`). |
+| `ERR_INVALID_OPTION` | An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto. |
+| `ERR_INVALID_ARGUMENT` | An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination. |
+| `ERR_MISSING_ARGUMENT` | A required argument or option value was omitted. |
| `ERR_INVALID_LANG` | `--lang` was given a value outside its choices (en, zh, dense). |
| `ERR_INVALID_DETAIL` | `--detail` was given a value outside its choices (full, compact, brief). |
| `ERR_NODE_VERSION` | The running Node.js version is below the supported minimum. |
@@ -183,8 +184,8 @@ if (isError(result)) {
| `ERR_UNKNOWN_THEME` | No theme matched the requested slug (theme add). |
| `ERR_INTEGRATION_ROOT_CONFLICT` | An integration manifest already declares a different path for the requested contribution root. |
| `ERR_INTEGRATION_EXPORT_CONFLICT` | A package export already maps a generated contribution subpath to a different target. |
-| `ERR_UNKNOWN_PACKAGE` | No package matched the requested name (discover). |
-| `ERR_UNKNOWN_AGENT` | An unrecognized `--agent` value was passed to agent-docs/init. |
+| `ERR_UNKNOWN_PACKAGE` | No package matched the requested name. |
+| `ERR_UNKNOWN_AGENT` | An unrecognized `--agent` value was passed to init. |
| `ERR_UNKNOWN_FEATURE` | An unrecognized `--features` value was passed to init. |
| `ERR_UNKNOWN_CODEMOD` | A `--codemod` value did not match any registered codemod (upgrade). |
| `ERR_CODEMOD_FAILED` | One or more codemods failed during an upgrade run. |
@@ -210,7 +211,7 @@ if (isError(result)) {
| `ERR_FETCH_FAILED` | A network fetch (RSS feed or post text) failed. |
| `ERR_LAYOUT_PARSE` | A layout expression failed to parse (syntax error, with line/col). |
| `ERR_LAYOUT_INVALID` | A layout expression parsed but failed validation (unknown component/prop/enum/block). |
-| `ERR_UNCLASSIFIED_EXIT` | Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available. |
+| `ERR_UNCLASSIFIED_EXIT` | Recorded in the debug log, never printed: a command exited non-zero without reporting an error code. |
| `ERR_SIGNAL_TERMINATED` | Recorded in the debug log, never printed: the process was ended by a signal (Ctrl-C, SIGTERM) before the command reached a terminal path. |
<!-- END GENERATED: error-codes -->
@@ -421,7 +422,7 @@ Every response has a `type` discriminant. The full set is below (generated from
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init.run` | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted. |
| `init.remove` | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set. |
-| `component.list` | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry. |
+| `component.list` | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry. |
| `component.batch` | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |
| `component.detail` | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc). |
| `component.detail.props` | Just one component's props table (ComponentPropDoc[]). |
@@ -444,7 +445,7 @@ Every response has a `type` discriminant. The full set is below (generated from
| `build.help` | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation. |
| `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin. |
| `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. |
-| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note. |
+| `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. |
| `gap-report.categories` | The fixed gap category values and human-readable labels. |
| `gap-report.file` | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals. |
| `template.list` | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list. |
@@ -464,10 +465,13 @@ Every response has a `type` discriminant. The full set is below (generated from
| `theme.targets` | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key. |
| `theme.palette.generate` | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result. |
| `upgrade.list` | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything. |
+| `upgrade.registry` | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items. |
| `upgrade.status` | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. |
| `upgrade.run` | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors. |
| `manifest` | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index. |
-| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status. |
+| `help` | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second. |
+| `version` | The CLI version, for `astryx --version --json`: {version}. |
+| `doctor` | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status. |
| `integration.add` | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun. |
| `integration.pack-check` | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |
| `integration.validate` | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. |
@@ -675,9 +679,10 @@ Warnings go to stderr and never corrupt a `--json` envelope. To inspect problems
Core identity overlaps before publishing. Bare `astryx doctor` checks overall
project health.
-For the full authoring walkthrough (component doc format, template packaging
-and `exports` requirements, and codemod authoring), see the guide:
+For the full walkthrough, from an empty folder to a published package, see the
+guides:
```bash
astryx docs cli/integrations
+astryx docs cli/integrations/quick-start
```
diff --git a/packages/cli/api/build/build.doc.mjs b/packages/cli/api/build/build.doc.mjs
index c9ef6901e2..e005a08b9c 100644
--- a/packages/cli/api/build/build.doc.mjs
+++ b/packages/cli/api/build/build.doc.mjs
@@ -40,6 +40,7 @@ export const doc = {
type: 'string',
description:
'Directory to resolve @astryxdesign/core and templates from.',
+ default: 'process.cwd()',
},
{
name: 'options.type',
@@ -69,7 +70,11 @@ export const doc = {
throws: [
{
code: 'ERR_INVALID_ARGUMENT',
- when: 'options.type is not a known domain, or options.limit is not a positive integer',
+ when: 'a query is given and options.type is not a known domain, or options.limit is not a positive integer',
+ },
+ {
+ code: 'ERR_CORE_NOT_FOUND',
+ when: 'a query is given and @astryxdesign/core cannot be found from cwd',
},
],
examples: [
diff --git a/packages/cli/api/build/build.test.mjs b/packages/cli/api/build/build.test.mjs
index 4b2c0780ef..a9ef6bcab7 100644
--- a/packages/cli/api/build/build.test.mjs
+++ b/packages/cli/api/build/build.test.mjs
@@ -179,6 +179,28 @@ describe('build kit — coverage gates the pages group', () => {
}
});
+ it('does not call a page that only mentions every word a direct match', async () => {
+ // `empty state` and `command palette` name components. A page whose text
+ // mentions both words, or that renders the component, is a layout
+ // reference, not the page the reader asked for.
+ for (const query of ['empty state', 'command palette']) {
+ const r = await build(query, {cwd: REPO});
+ if (r.type !== 'build.kit') throw new Error('expected build.kit');
+ expect(r.data.directMatch, query).toBe(false);
+ }
+ });
+
+ it('keeps the page and component a query names first', async () => {
+ const pageOf = async (/** @type {string} */ query) => {
+ const r = await build(query, {cwd: REPO});
+ if (r.type !== 'build.kit') throw new Error('expected build.kit');
+ return r.data;
+ };
+ expect((await pageOf('checkout flow')).pages[0]).toMatchObject({name: 'checkout-wizard'});
+ expect((await pageOf('sign in with sso')).pages[0]).toMatchObject({name: 'login-sso'});
+ expect((await pageOf('search results')).domain.map(e => e.name)).toContain('PowerSearch');
+ });
+
it('leaves single-concept queries alone (nothing to cover)', async () => {
const r = await build('dashboard', {cwd: REPO});
expect(r.type).toBe('build.kit');
diff --git a/packages/cli/api/build/kit/kit.mjs b/packages/cli/api/build/kit/kit.mjs
index a25e1cbcfe..4da3dee004 100644
--- a/packages/cli/api/build/kit/kit.mjs
+++ b/packages/cli/api/build/kit/kit.mjs
@@ -28,6 +28,9 @@
*/
import {search} from '../../search/search.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {getResultCoverage} from '../../search/coverage.mjs';
import {loadPageTemplates} from '../_adapter.mjs';
import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
@@ -188,12 +191,30 @@ function chooseStart(ranked, pages, directMatch, catalog) {
*/
export async function buildKit(query, options = {}) {
const {cwd = process.cwd(), type, limit = 60} = options;
+ // A kit is built from Core's components, hooks, and templates. An open
+ // search without core covers the docs alone, so the kit asks for core here.
+ if (type !== 'doc' && !findCoreDir(cwd)) {
+ throw new AstryxError(
+ 'Could not find @astryxdesign/core package',
+ undefined,
+ ERROR_CODES.ERR_CORE_NOT_FOUND,
+ );
+ }
// search()'s JSDoc @returns widens results to object[]; the SearchResponse
// shape is the contract (api/search/search.type.mjs). Cast locally rather than
// tightening the search @returns (a separate follow-up).
const result =
/** @type {import('../../search/search.type.mjs').SearchResponse} */ (
- await search(query, {cwd, type, limit})
+ await search(query, {
+ cwd,
+ type,
+ // Search wider than the surfaced kit so a flood of doc matches cannot
+ // bury the page templates past the cutoff; the caller's `limit` still
+ // caps the kit below. A non-positive or non-integer limit is passed
+ // through unchanged so search rejects it (ERR_INVALID_ARGUMENT).
+ limit:
+ Number.isInteger(limit) && limit > 0 ? Math.max(limit, 200) : limit,
+ })
);
const results = result.data.results;
// The TOTAL number of matches, not the number that survived `limit`. The kit
@@ -257,6 +278,24 @@ export async function buildKit(query, options = {}) {
command: `${page.command} --skeleton`,
}));
+ // The caller's `limit` caps the surfaced kit, even though the search above
+ // ran wider to find templates that a flood of doc matches would otherwise
+ // bury past the cutoff. Keep pages first, then blocks, then components.
+ let budget = limit;
+ /**
+ * @template T
+ * @param {T[]} arr
+ * @returns {T[]}
+ */
+ const toLimit = arr => {
+ const out = arr.slice(0, Math.max(0, budget));
+ budget -= out.length;
+ return out;
+ };
+ const pagesKept = toLimit(pages);
+ const blocksKept = toLimit(blocks);
+ const domainKept = toLimit(domain);
+
// A kit narrowed to components or hooks has no page to start from; every
// other kit does, so the reader is never left to compose a page from scratch.
const wantsPages = !type || type === 'template';
@@ -288,7 +327,7 @@ export async function buildKit(query, options = {}) {
// not resolve — the same defect `getCliInvocation` exists to prevent, and
// the renderer applies it. A JSON caller gets the parts, not a sentence.
const hint =
- pages.length + blocks.length + domain.length < THIN_KIT
+ pagesKept.length + blocksKept.length + domainKept.length < THIN_KIT
? {
reason:
'Few matches. This is keyword search, not semantic — try other wordings.',
@@ -306,9 +345,9 @@ export async function buildKit(query, options = {}) {
matchCount,
directMatch,
start,
- pages,
- blocks,
- domain,
+ pages: pagesKept,
+ blocks: blocksKept,
+ domain: domainKept,
frame: FRAME,
foundation: FOUNDATION,
hint,
diff --git a/packages/cli/api/component/component.doc.mjs b/packages/cli/api/component/component.doc.mjs
index 15ce9c6f69..057d62dcaf 100644
--- a/packages/cli/api/component/component.doc.mjs
+++ b/packages/cli/api/component/component.doc.mjs
@@ -45,6 +45,7 @@ export const doc = {
name: 'options.cwd',
type: 'string',
description: 'Directory to resolve @astryxdesign/core from.',
+ default: 'process.cwd()',
},
{
name: 'options.list',
@@ -54,13 +55,14 @@ export const doc = {
{
name: 'options.category',
type: 'string',
- description: 'List only components in this category.',
+ description:
+ "List only the components in this group: a key of the unfiltered list (each component's group field), such as 'Layout' or 'Button'. It is not the category field of a component detail.",
},
{
name: 'options.package',
type: 'string',
description:
- "Scope lookup to a specific external package (e.g. '@acme/xds-widgets').",
+ "Scope lookup to a specific external package (e.g. '@acme/widgets').",
},
{
name: 'options.props',
@@ -87,7 +89,8 @@ export const doc = {
name: 'options.detail',
type: "'full' | 'compact' | 'brief'",
description: 'Detail level for list views.',
- default: "'full' for a named component, 'brief' for list views",
+ default:
+ "'full' for a named component; 'brief' for lists (returned as data.detail: 'names')",
},
{
name: 'options.lang',
@@ -110,7 +113,7 @@ export const doc = {
{
type: 'component.list',
description:
- "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
+ "The catalog grouped by component group. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
},
{
type: 'component.batch',
@@ -160,7 +163,7 @@ export const doc = {
},
{
code: 'ERR_UNKNOWN_CATEGORY',
- when: 'options.category is not a string or matches no known category',
+ when: 'options.category is not a string or matches no component group',
},
{
code: 'ERR_UNKNOWN_COMPONENT',
@@ -174,6 +177,10 @@ export const doc = {
code: 'ERR_NO_DOC',
when: 'the resolved component has no .doc.mjs typed doc file',
},
+ {
+ code: 'ERR_INVALID_DOC',
+ when: "the resolved component's .doc.mjs fails to load or validate",
+ },
{
code: 'ERR_NO_SOURCE',
when: 'options.source is set but the component has no source file',
@@ -194,8 +201,8 @@ export const doc = {
},
{label: 'Props only', code: "await component('Button', {props: true});"},
{
- label: 'Browse a category',
- code: "await component(undefined, {category: 'Form', detail: 'compact'});",
+ label: 'Browse one group',
+ code: "await component(undefined, {category: 'Layout', detail: 'compact'});",
},
],
command: 'component',
diff --git a/packages/cli/api/docs/_adapter.mjs b/packages/cli/api/docs/_adapter.mjs
index 57f6898553..c0846b638a 100644
--- a/packages/cli/api/docs/_adapter.mjs
+++ b/packages/cli/api/docs/_adapter.mjs
@@ -667,10 +667,12 @@ export async function docsLinkProblems(
/**
* What \`astryx doctor integration docs\` checks in one integration's docs: the
* docs tree they build beside the CLI's (namespaces, placements, routes) and
- * every link in them (spec:AST-046, spec:AST-047).
+ * every link in them (spec:AST-046, spec:AST-047). A tree problem hides a doc,
+ * so it is an error; a link that names no doc prints as written, so it is a
+ * warning.
* @param {{name: string}} integration
* @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
- * @returns {Promise<string[]>}
+ * @returns {Promise<Array<{severity: 'error' | 'warning', message: string}>>}
*/
export async function packageDocsProblems(integration, discovered) {
const catalog = DocsCatalog.fromBuiltins();
@@ -680,12 +682,18 @@ export async function packageDocsProblems(integration, discovered) {
guides: discovered.guides.map(input => ({...input, rank: 1})),
});
const tree = await projectTree(catalog);
+ /** @type {Array<{severity: 'error' | 'warning', message: string}>} */
const problems = tree.diagnostics
.filter(d => d.severity === 'error' && d.provider === integration.name)
- .map(d => `${d.source ?? integration.name}: ${d.message}`);
- problems.push(
- ...(await docsLinkProblems(catalog, tree, {owner: integration.name})),
- );
+ .map(d => ({
+ severity: /** @type {const} */ ('error'),
+ message: `${d.source ?? integration.name}: ${d.message}`,
+ }));
+ for (const message of await docsLinkProblems(catalog, tree, {
+ owner: integration.name,
+ })) {
+ problems.push({severity: 'warning', message});
+ }
return problems;
}
diff --git a/packages/cli/api/docs/docOverlays.test.mjs b/packages/cli/api/docs/docOverlays.test.mjs
index b463c79cda..5619f5147c 100644
--- a/packages/cli/api/docs/docOverlays.test.mjs
+++ b/packages/cli/api/docs/docOverlays.test.mjs
@@ -76,6 +76,32 @@ describe('reference doc overlays (#2182)', () => {
).toEqual([]);
});
+ it(`${topic} --${variant}: every content override lands on a block of its own type`, async () => {
+ // Blocks are matched by index and type, and a mismatch is dropped with
+ // no warning: a prose override aimed at a code block leaves the base
+ // text in place, so the reader gets a translated title over an English
+ // body. Pad with null to reach the block you mean.
+ const base = await load(basePath);
+ const overlayMod = await load(overlayPath);
+ const overlay = overlayMod.docsDense || overlayMod.docsZh;
+ const byTitle = new Map(base.docs.sections.map(s => [s.title, s]));
+ const dropped = [];
+ for (const entry of overlay.sections || []) {
+ const section = byTitle.get(entry.section);
+ if (!section) continue;
+ (entry.content || []).forEach((block, i) => {
+ if (block == null) return;
+ const target = section.content[i];
+ if (target?.type !== block.type) {
+ dropped.push(
+ `${entry.section} block ${i}: ${block.type} over ${target?.type ?? 'nothing'}`,
+ );
+ }
+ });
+ }
+ expect(dropped, `${topic}.doc.${variant}.mjs overrides that never apply`).toEqual([]);
+ });
+
it(`${topic} --${variant}: no base section is overridden twice`, async () => {
const overlayMod = await load(overlayPath);
const overlay = overlayMod.docsDense || overlayMod.docsZh;
@@ -127,7 +153,7 @@ describe('the reported defect: docs tokens --dense (#2182)', () => {
const zh = await docs('theme', null, {zh: true});
const titles = zh.data.sections.map(s => s.title);
// Every section the overlay translates must appear once, in Chinese only.
- expect(titles).not.toContain('Light/Dark Mode');
+ expect(titles).not.toContain('Dark mode');
expect(titles).toContain('亮/暗模式');
});
});
diff --git a/packages/cli/api/docs/docs.doc.mjs b/packages/cli/api/docs/docs.doc.mjs
index 4d25e28573..2872e8abb3 100644
--- a/packages/cli/api/docs/docs.doc.mjs
+++ b/packages/cli/api/docs/docs.doc.mjs
@@ -27,7 +27,7 @@ export const doc = {
'A route opens a node of the docs tree instead: a namespace such as ' +
"`cli/api` returns its children one level down, a typed doc such as " +
"`cli/api/functions/search` returns its content, and a guide the tree " +
- 'places (`cli/integrations`) reads like any topic. ' +
+ 'places (`cli/integrations/quick-start`) reads like any topic. ' +
'Every read but the list carries `links`, the commands that move from it: ' +
'`up` to the level it sits in, `previous` and `next` to its neighbors, and, ' +
'for a typed doc, `related` to the docs it names (its command or function, ' +
@@ -137,7 +137,7 @@ export const doc = {
{label: 'One API function', code: "await docs('cli/api/functions/search');"},
{
label: 'A whole guide from the docs tree',
- code: "await docs('cli/integrations');",
+ code: "await docs('cli/integrations/quick-start');",
},
{label: 'One section by key', code: "await docs('tokens', 'spacing');"},
],
diff --git a/packages/cli/api/docs/docs.test.mjs b/packages/cli/api/docs/docs.test.mjs
deleted file mode 100644
index aaa22e2af2..0000000000
--- a/packages/cli/api/docs/docs.test.mjs
+++ /dev/null
@@ -1,245 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Dispatcher-level tests for docs() — the argument-shape routing that
- * sits above the list/detail/section leaves. The leaves have their own tests;
- * this pins the router: docs() -> list, docs(topic) -> detail,
- * docs(topic, section) -> section, plus the unknown-topic/section error codes.
- * Runs against the real CLI-bundled docs (no cwd/project needed).
- */
-
-import {describe, it, expect} from 'vitest';
-import {docs} from './docs.mjs';
-import {AstryxError} from '../error.mjs';
-
-const SLOW = 30_000;
-
-describe('docs() dispatcher routing', () => {
- it('no topic -> docs.list', async () => {
- const r = await docs();
- expect(r.type).toBe('docs.list');
- expect(Array.isArray(r.data)).toBe(true);
- expect(r.data.length).toBeGreaterThan(0);
- }, SLOW);
-
- it('empty topic -> docs.list (falsy topic routes to list)', async () => {
- expect((await docs('')).type).toBe('docs.list');
- }, SLOW);
-
- it('topic only -> docs.detail, the whole doc', async () => {
- const {data} = await docs();
- expect((await docs(data[0].topic)).type).toBe('docs.detail');
- }, SLOW);
-
- it('topic + index -> docs.index', async () => {
- const {data} = await docs();
- const r = await docs(data[0].topic, undefined, {index: true});
- expect(r.type).toBe('docs.index');
- }, SLOW);
-
- it('topic + section -> docs.detail.section', async () => {
- const {data} = await docs();
- let routed = null;
- for (const {topic} of data) {
- const detail = await docs(topic);
- const sections = detail.data.sections;
- if (Array.isArray(sections) && sections.length > 0) {
- routed = await docs(topic, sections[0].title);
- break;
- }
- }
- expect(routed).not.toBeNull();
- expect(routed.type).toBe('docs.detail.section');
- }, SLOW);
-
- it('unknown topic -> ERR_UNKNOWN_TOPIC', async () => {
- await expect(docs('zzz-not-a-real-topic')).rejects.toBeInstanceOf(AstryxError);
- await expect(docs('zzz-not-a-real-topic')).rejects.toMatchObject({
- code: 'ERR_UNKNOWN_TOPIC',
- });
- }, SLOW);
-
- it('known topic + unknown section -> ERR_UNKNOWN_SECTION', async () => {
- const {data} = await docs();
- const topic = data[0].topic;
- await expect(docs(topic, 'zzz-not-a-real-section')).rejects.toMatchObject({
- code: 'ERR_UNKNOWN_SECTION',
- });
- }, SLOW);
-
- it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
- const res = await docs();
- expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'unorganized']);
- for (const entry of res.data) {
- expect((await docs(entry.topic)).type).toBe('docs.detail');
- }
- }, SLOW);
-
- it('opens a route typed in another case', async () => {
- const r = await docs('CLI/API');
- expect(r.type).toBe('docs.node');
- expect(r.data).toMatchObject({route: 'cli/api', links: {up: 'astryx docs cli'}});
- }, SLOW);
-
- it('a section of a typed doc -> ERR_UNKNOWN_SECTION, suggesting the doc itself', async () => {
- const err = await docs('cli/api/functions/search', 'x').catch(e => e);
- expect(err.code).toBe('ERR_UNKNOWN_SECTION');
- expect(err.message).toContain('astryx docs cli/api/functions/search');
- expect(err.suggestions.map(s => s.name)).toEqual(['cli/api/functions/search']);
- }, SLOW);
-
- it('a namespace route -> docs.node, one level of children', async () => {
- const r = await docs('cli/api');
- expect(r.type).toBe('docs.node');
- expect(r.data).toMatchObject({
- id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/namespace/api',
- route: 'cli/api',
- kind: 'namespace',
- package: '@astryxdesign/cli',
- breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
- content: [],
- });
- expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
- 'cli/api/functions',
- 'cli/api/schemas',
- 'cli/api/enums',
- ]);
- }, SLOW);
-
- it('a typed doc route -> docs.node with its content', async () => {
- const r = await docs('cli/api/functions/search');
- expect(r.type).toBe('docs.node');
- expect(r.data).toMatchObject({
- id: 'astryx:artifact:v1/%40astryxdesign%2Fcli/function/search',
- kind: 'function',
- title: 'search()',
- slots: [],
- });
- expect(r.data.breadcrumb.map(link => link.route)).toEqual([
- 'cli',
- 'cli/api',
- 'cli/api/functions',
- ]);
- expect(JSON.stringify(r.data.content)).toContain(
- '`astryx search` runs it. Read it with `astryx docs cli/commands/search`.',
- );
- }, SLOW);
-
- it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
- expect((await docs('cli/integrations')).type).toBe('docs.detail');
- const index = await docs('cli/integrations', undefined, {index: true});
- expect(index).toMatchObject({type: 'docs.index', data: {name: 'cli/integrations'}});
- expect(index.data.sections.length).toBeGreaterThan(1);
- expect((await docs('cli/integrations', 'components')).type).toBe(
- 'docs.detail.section',
- );
- }, SLOW);
-
- it('every read carries its moves (spec:AST-047)', async () => {
- const root = (await docs('cli')).data;
- expect(root.links).toEqual({up: 'astryx docs'});
- const leaf = (await docs('cli/api/functions/search')).data;
- expect(leaf.links.up).toBe('astryx docs cli/api/functions');
- expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
- expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
- const index = await docs('cli/integrations', undefined, {index: true});
- // A guide moves across its namespace's slot, as any tree node does.
- expect(index.data.links).toEqual({
- up: 'astryx docs cli',
- previous: 'astryx docs cli/component-lookups',
- next: 'astryx docs cli/writing-docs',
- });
- const first = (await docs('cli/integrations', index.data.sections[0].id)).data;
- expect(first.links).toEqual({
- up: 'astryx docs cli/integrations --index',
- next: `astryx docs cli/integrations ${index.data.sections[1].id}`,
- });
- const last = index.data.sections.at(-1).id;
- const end = (await docs('cli/integrations', last)).data;
- expect(end.links.next).toBeUndefined();
- expect(end.links.previous).toBe(
- `astryx docs cli/integrations ${index.data.sections.at(-2).id}`,
- );
- // A flat topic's home is the Unorganized level, and it moves across it.
- const flat = (await docs('principles')).data.links;
- expect(flat.up).toBe('astryx docs unorganized');
- expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
- expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
- const home = (await docs('unorganized')).data;
- expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
- expect(home.slots[0].children.map(child => child.route)).toEqual(
- (await docs()).data.map(entry => entry.topic),
- );
- }, SLOW);
-
- it('names a node by its doc identity; a generated level has id null', async () => {
- const level = (await docs('cli/api/functions')).data;
- expect(level).toHaveProperty('id', null);
- expect(level.route).toBe('cli/api/functions');
- }, SLOW);
-
- it("offers a typed doc's related docs as moves", async () => {
- const fn = (await docs('cli/api/functions/search')).data;
- expect(fn.links.related).toContain('astryx docs cli/commands/search');
- const cmd = (await docs('cli/commands/search')).data;
- expect(cmd.links.related).toContain('astryx docs cli/api/functions/search');
- }, SLOW);
-
- it('a topic read returns the whole doc; index returns its sections', async () => {
- expect((await docs('principles')).type).toBe('docs.detail');
- const index = await docs('principles', undefined, {index: true});
- expect(index.type).toBe('docs.index');
- expect(index.data.sections.length).toBeGreaterThan(1);
- expect((await docs('principles', undefined, {dense: true})).type).toBe(
- 'docs.detail',
- );
- }, SLOW);
-
- it("the guide's old flat name is gone, and its error names the new route", async () => {
- await expect(docs('cli-integrations')).rejects.toMatchObject({
- code: 'ERR_UNKNOWN_TOPIC',
- suggestions: [expect.objectContaining({name: 'cli/integrations'})],
- });
- expect((await docs()).data.map(entry => entry.topic)).not.toContain(
- 'cli-integrations',
- );
- }, SLOW);
-
- it('a section of a namespace -> ERR_UNKNOWN_SECTION, naming its children', async () => {
- const err = await docs('cli', 'commands').catch(e => e);
- expect(err).toBeInstanceOf(AstryxError);
- expect(err.code).toBe('ERR_UNKNOWN_SECTION');
- expect(err.suggestions.map(s => s.name)).toEqual([
- 'cli/component-lookups',
- 'cli/integrations',
- 'cli/writing-docs',
- 'cli/commands',
- 'cli/api',
- ]);
- }, SLOW);
-
- it('an unknown route suggests the children of the deepest namespace it reaches', async () => {
- const err = await docs('cli/api/functions/serch').catch(e => e);
- expect(err.code).toBe('ERR_UNKNOWN_TOPIC');
- expect(err.suggestions.map(s => s.name)).toContain('cli/api/functions/search');
- expect(err.suggestions.every(s => s.name.startsWith('cli/api/functions/'))).toBe(true);
- }, SLOW);
-
- it('non-string topic -> ERR_UNKNOWN_TOPIC (not a raw TypeError)', async () => {
- for (const bad of [123, {}, ['tokens'], true]) {
- const err = await docs(/** @type {any} */ (bad)).catch(e => e);
- expect(err).toBeInstanceOf(AstryxError);
- expect(err.code).toBe('ERR_UNKNOWN_TOPIC');
- }
- }, SLOW);
-
- it('non-string section -> ERR_UNKNOWN_SECTION (not a raw TypeError)', async () => {
- const {data} = await docs();
- const topic = data[0].topic;
- for (const bad of [456, {}, ['x']]) {
- const err = await docs(topic, /** @type {any} */ (bad)).catch(e => e);
- expect(err).toBeInstanceOf(AstryxError);
- expect(err.code).toBe('ERR_UNKNOWN_SECTION');
- }
- }, SLOW);
-});
diff --git a/packages/cli/api/docs/integration-tree.test.mjs b/packages/cli/api/docs/integration-tree.test.mjs
deleted file mode 100644
index 6ea3c7f704..0000000000
--- a/packages/cli/api/docs/integration-tree.test.mjs
+++ /dev/null
@@ -1,555 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Integration docs in the docs tree (spec:AST-046, spec:AST-047): an
- * integration's namespace docs and placed guides join the CLI's tree with the
- * same moves, links, search, and doctor checks, named by its provider id.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
-import {docs} from './docs.mjs';
-import {loadDocsCatalog} from './_adapter.mjs';
-import {search} from '../search/search.mjs';
-import {checkDocsTree} from '../doctor/doctor.mjs';
-import {integrationDocConflicts} from '../integration/authoring-checks.mjs';
-
-const SLOW = 60_000;
-
-/** @type {string} */
-let tmpDir;
-
-const NAMESPACE = {
- type: 'namespace',
- name: 'acme',
- title: 'Acme',
- summary: 'Everything about the Acme kit.',
- slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},
-};
-
-/**
- * A guide placed in the acme namespace.
- * @param {string} name
- * @param {object} [fields]
- */
-function guide(name, fields = {}) {
- return {
- type: 'generic',
- name,
- title: `Acme ${name}`,
- description: `How to ${name} the Acme kit.`,
- placement: {parent: 'namespace:acme', slot: 'guides'},
- sections: [
- {title: 'Overview', content: [{type: 'prose', text: `Do ${name}.`}]},
- ],
- ...fields,
- };
-}
-
-/** The docs of a small integration: a namespace, two guides, and a topic. */
-function kit() {
- return {
- 'acme.doc.mjs': NAMESPACE,
- 'setup.doc.mjs': guide('setup', {
- placement: {parent: 'namespace:acme', slot: 'guides', order: 1},
- sections: [
- {
- title: 'Install',
- content: [
- {
- type: 'prose',
- text: 'Frobnicate the kit, then check it with {@link @astryxdesign/cli:command:doctor}.',
- },
- {type: 'prose', text: 'Next: {@link generic:deploy}.'},
- ],
- },
- {
- title: 'Configure',
- content: [{type: 'prose', text: 'Add it to astryx.config.'}],
- },
- ],
- }),
- 'deploy.doc.mjs': guide('deploy', {
- placement: {parent: 'namespace:acme', slot: 'guides', order: 2},
- }),
- 'notes.doc.mjs': {
- type: 'generic',
- name: 'acme-notes',
- title: 'Acme notes',
- description: 'Notes about the kit.',
- sections: [
- {
- title: 'Start',
- content: [{type: 'prose', text: 'Start at {@link generic:setup}.'}],
- },
- ],
- },
- };
-}
-
-/** A guide whose only link names no doc. */
-const broken = () =>
- guide('broken', {
- sections: [
- {
- title: 'Overview',
- content: [{type: 'prose', text: 'See {@link generic:nope}.'}],
- },
- ],
- });
-
-/**
- * A consumer project that configures `@acme/kit`, whose manifest names a
- * provider id that differs from its package name.
- * @param {Record<string, object>} files
- */
-function scaffold(files) {
- fs.writeFileSync(
- path.join(tmpDir, 'package.json'),
- JSON.stringify({name: 'consumer'}),
- );
- fs.writeFileSync(
- path.join(tmpDir, 'astryx.config.mjs'),
- "export default {integrations: ['@acme/kit']};\n",
- );
- const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'kit');
- fs.mkdirSync(path.join(pkgDir, 'docs'), {recursive: true});
- fs.writeFileSync(
- path.join(pkgDir, 'package.json'),
- JSON.stringify({name: '@acme/kit', version: '1.0.0'}),
- );
- fs.writeFileSync(
- path.join(pkgDir, 'astryx.integration.mjs'),
- "export default {docs: './docs', providerId: '@acme/tree-provider'};\n",
- );
- for (const [file, doc] of Object.entries(files)) {
- fs.writeFileSync(
- path.join(pkgDir, 'docs', file),
- `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
- );
- }
-}
-
-beforeEach(() => {
- tmpDir = fs.mkdtempSync(
- path.join(process.cwd(), '.astryx-integration-tree-test-'),
- );
-});
-
-afterEach(() => {
- fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-describe('integration docs in the docs tree', () => {
- it('names a package whose docs did not load, instead of dropping them silently', async () => {
- scaffold({
- ...kit(),
- 'broken.doc.mjs': {
- type: 'generic',
- name: 'broken',
- title: 'Broken',
- description: 'A topic whose block no topic may hold.',
- sections: [
- {
- title: 'Only',
- content: [
- {
- type: 'workflow',
- steps: [{title: 'Set up', references: ['generic:setup']}],
- },
- ],
- },
- ],
- },
- });
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- expect(listed.meta?.notLoaded).toEqual([
- expect.objectContaining({package: '@acme/kit', message: expect.any(String)}),
- ]);
- }, 60_000);
-
- it('lists an integration namespace beside the CLI, named by its provider id', async () => {
- scaffold(kit());
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- expect(listed.meta.namespaces).toContainEqual({
- topic: 'acme',
- description: 'Everything about the Acme kit.',
- package: '@acme/kit',
- });
- const top = await docs('acme', undefined, {cwd: tmpDir});
- expect(top.type).toBe('docs.node');
- expect(top.data).toMatchObject({
- id: 'astryx:artifact:v1/%40acme%2Ftree-provider/namespace/acme',
- package: '@acme/kit',
- links: {up: 'astryx docs'},
- });
- expect(
- top.data.slots[0].children.map((/** @type {any} */ c) => c.route),
- ).toEqual(['acme/setup', 'acme/deploy']);
- }, SLOW);
-
- it('reads a placed guide one level at a time, with its links resolved', async () => {
- scaffold(kit());
- const index = await docs('acme/setup', undefined, {cwd: tmpDir, index: true});
- expect(index.type).toBe('docs.index');
- expect(index.data.links.up).toBe('astryx docs acme');
- const install = await docs('acme/setup', 'install', {cwd: tmpDir});
- const [prose, next] = install.data.content;
- expect(prose.text).toBe(
- 'Frobnicate the kit, then check it with `astryx docs cli/commands/doctor`.',
- );
- expect(next.text).toBe('Next: `astryx docs acme/deploy`.');
- const notes = await docs('acme-notes', undefined, {cwd: tmpDir});
- expect(notes.data.sections[0].content[0].text).toBe(
- 'Start at `astryx docs acme/setup`.',
- );
- }, SLOW);
-
- it('finds a section of the guide by search, with its package and parent', async () => {
- scaffold(kit());
- const {data} = await search('frobnicate', {cwd: tmpDir, type: 'doc'});
- expect(data.results[0]).toMatchObject({
- name: 'acme/setup',
- section: 'install',
- command: 'astryx docs acme/setup install',
- parent: 'astryx docs acme/setup --index',
- package: '@acme/kit',
- });
- }, SLOW);
-
- it('passes doctor, and warns on a link that names no doc', async () => {
- scaffold(kit());
- const ok = await checkDocsTree({
- docsCatalog: await loadDocsCatalog(tmpDir),
- });
- expect(ok).toMatchObject({id: 'docs-tree', status: 'pass'});
- scaffold({...kit(), 'broken.doc.mjs': broken()});
- const bad = await checkDocsTree({
- docsCatalog: await loadDocsCatalog(tmpDir),
- });
- expect(bad.status).toBe('warn');
- expect(bad.message).toContain('acme/broken');
- expect(bad.message).toContain('"generic:nope" names no doc');
- }, SLOW);
-
- it("keeps the CLI's routes: an integration namespace or topic that claims one is withdrawn, and both doctors say so", async () => {
- const flat = (/** @type {string} */ name) => ({
- type: 'generic',
- name,
- title: `Acme ${name}`,
- description: `Acme's ${name} notes.`,
- sections: [
- {title: 'One', content: [{type: 'prose', text: 'One.'}]},
- {title: 'Two', content: [{type: 'prose', text: 'Two.'}]},
- ],
- });
- scaffold({
- ...kit(),
- 'unorganized.doc.mjs': {...NAMESPACE, name: 'unorganized', title: 'Mine', summary: 'Mine.'},
- 'tokens.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Acme tokens', summary: 'Acme tokens.'},
- 'cli.doc.mjs': flat('cli'),
- });
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- expect(listed.meta.namespaces).toEqual(
- expect.arrayContaining([
- expect.objectContaining({topic: 'cli', package: '@astryxdesign/cli'}),
- expect.objectContaining({topic: 'unorganized', package: '@astryxdesign/cli'}),
- ]),
- );
- expect(listed.meta.namespaces.filter(n => ['tokens', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
- expect(listed.data.map(entry => entry.topic)).not.toContain('cli');
- // Each name opens the CLI's doc, and a CLI topic keeps its home.
- expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
- expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
- const tokens = await docs('tokens', undefined, {cwd: tmpDir});
- expect(tokens.type).toBe('docs.detail');
- expect(tokens.data.links.up).toBe('astryx docs unorganized');
- // The project doctor and the package doctor both name the claims.
- const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
- expect(check.status).toBe('warn');
- expect(check.message).toContain('takes the route "unorganized", which the CLI\'s own docs keep');
- expect(check.message).toContain('takes the route "tokens"');
- expect(check.message).toContain('both have the route "cli"');
- const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
- const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message).join('\n');
- expect(graph).toContain('takes the route "unorganized"');
- expect(graph).toContain('takes the route "tokens"');
- expect(graph).toContain('route "cli"');
- }, SLOW);
-
- it("keeps the CLI's routes from a claim that differs only in case", async () => {
- const flat = (/** @type {string} */ name) => ({
- type: 'generic',
- name,
- title: `Acme ${name}`,
- description: `Acme's ${name} notes.`,
- sections: [
- {title: 'One', content: [{type: 'prose', text: 'One.'}]},
- {title: 'Two', content: [{type: 'prose', text: 'Two.'}]},
- ],
- });
- scaffold({...kit(), 'caps-cli.doc.mjs': flat('CLI')});
- // Another spelling, in a nested folder of the package's docs.
- const nested = path.join(tmpDir, 'node_modules', '@acme', 'kit', 'docs', 'nested');
- fs.mkdirSync(nested, {recursive: true});
- fs.writeFileSync(
- path.join(nested, 'caps-unorganized.doc.mjs'),
- `export const docs = ${JSON.stringify(flat('Unorganized'), null, 2)};\n`,
- );
- fs.writeFileSync(
- path.join(nested, 'caps-tokens.doc.mjs'),
- `export const docs = ${JSON.stringify(flat('TOKENS'), null, 2)};\n`,
- );
- expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
- expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
- expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs unorganized');
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- expect(listed.data.map(entry => entry.topic.toLowerCase())).not.toContain('cli');
- // Search does not offer a topic whose route another doc owns.
- const found = await search("Acme's CLI notes", {cwd: tmpDir, type: 'doc', limit: 20});
- expect(
- found.data.results.filter(hit => hit.package === '@acme/kit' && /^cli$/i.test(hit.name)),
- ).toEqual([]);
- const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
- expect(check.status).toBe('warn');
- expect(check.message).toContain('route "CLI"');
- expect(check.message).toContain('takes the route "Unorganized"');
- // `TOKENS` is the CLI's topic `tokens` in another spelling: the CLI's wins.
- const tokens = await docs('TOKENS', undefined, {cwd: tmpDir, index: true});
- expect(tokens.data).toMatchObject({name: 'tokens', links: {up: 'astryx docs unorganized'}});
- expect(tokens.data.title).not.toBe('Acme TOKENS');
- const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
- const graph = result.data.issues
- .filter(issue => issue.code === 'invalid_doc_graph')
- .map(issue => issue.message)
- .join('\n');
- expect(graph).toContain('route "CLI"');
- expect(graph).toContain('takes the route "Unorganized"');
- }, SLOW);
-
- it("keeps a replaced name for the topic that replaces it, over another integration's namespace", async () => {
- scaffold({...kit(), 'tokens-ns.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Kit tokens', summary: 'Kit tokens.'}});
- const two = path.join(tmpDir, 'node_modules', '@acme', 'two');
- fs.mkdirSync(path.join(two, 'docs'), {recursive: true});
- fs.writeFileSync(path.join(two, 'package.json'), JSON.stringify({name: '@acme/two', version: '1.0.0'}));
- fs.writeFileSync(path.join(two, 'astryx.integration.mjs'), "export default {docs: './docs'};\n");
- fs.writeFileSync(
- path.join(two, 'docs', 'acme-tokens.doc.mjs'),
- `export const docs = ${JSON.stringify({
- type: 'generic',
- name: 'acme-tokens',
- title: 'Acme tokens',
- description: 'Acme tokens.',
- replaces: 'tokens',
- sections: [{title: 'One', content: [{type: 'prose', text: 'One.'}]}],
- }, null, 2)};\n`,
- );
- fs.writeFileSync(
- path.join(tmpDir, 'astryx.config.mjs'),
- "export default {integrations: ['@acme/kit', '@acme/two']};\n",
- );
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('tokens');
- const read = await docs('tokens', undefined, {cwd: tmpDir, index: true});
- expect(read.data.name).toBe('acme-tokens');
- const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
- expect(check.status).toBe('warn');
- expect(check.message).toContain('which the topic "acme-tokens" also answers to');
- }, SLOW);
-
- it('keeps every name a topic replaced twice answers to, and the CLI\'s links to it still open', async () => {
- scaffold({...kit(), 'tokens-ns.doc.mjs': {...NAMESPACE, name: 'tokens', title: 'Kit tokens', summary: 'Kit tokens.'}});
- /** @param {string} pkg @param {string} name @param {string} replaces */
- const replacement = (pkg, name, replaces) => {
- const dir = path.join(tmpDir, 'node_modules', '@acme', pkg);
- fs.mkdirSync(path.join(dir, 'docs'), {recursive: true});
- fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name: `@acme/${pkg}`, version: '1.0.0'}));
- fs.writeFileSync(path.join(dir, 'astryx.integration.mjs'), "export default {docs: './docs'};\n");
- fs.writeFileSync(
- path.join(dir, 'docs', `${name}.doc.mjs`),
- `export const docs = ${JSON.stringify({
- type: 'generic',
- name,
- title: `Tokens by ${pkg}`,
- description: `Tokens by ${pkg}.`,
- replaces,
- sections: [{title: 'One', content: [{type: 'prose', text: 'One.'}]}],
- }, null, 2)};\n`,
- );
- };
- replacement('two', 'acme-tokens', 'tokens');
- replacement('three', 'b-tokens', 'tokens');
- replacement('four', 'super-tokens', 'b-tokens');
- fs.writeFileSync(
- path.join(tmpDir, 'astryx.config.mjs'),
- "export default {integrations: ['@acme/kit', '@acme/two', '@acme/three', '@acme/four']};\n",
- );
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- expect(listed.meta.namespaces.map(entry => entry.topic)).not.toContain('tokens');
- for (const name of ['tokens', 'acme-tokens', 'b-tokens', 'super-tokens']) {
- expect((await docs(name, undefined, {cwd: tmpDir, index: true})).data.name).toBe('super-tokens');
- }
- // A walk over every topic: the CLI's own links to `tokens` still open it.
- /** @type {string[]} */
- const raw = [];
- for (const entry of listed.data) {
- const read = await docs(entry.topic, undefined, {cwd: tmpDir});
- if (/\{@link [^}]*tokens\}/.test(JSON.stringify(read.data))) raw.push(entry.topic);
- }
- expect(raw).toEqual([]);
- const principles = await docs('principles', undefined, {cwd: tmpDir});
- expect(JSON.stringify(principles.data)).toContain('astryx docs super-tokens');
- const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
- expect(check.message).toContain('takes the route "tokens", which the topic "super-tokens" also answers to');
- expect(check.message).not.toContain('names no doc');
- }, SLOW);
-
- it("keeps the CLI's routes from a replacement that answers to one, in one package or across a chain", async () => {
- const flat = (/** @type {string} */ name, /** @type {object} */ extra = {}) => ({
- type: 'generic',
- name,
- title: `Acme ${name}`,
- description: `Acme's ${name} notes.`,
- sections: [
- {title: 'One', content: [{type: 'prose', text: 'One.'}]},
- {title: 'Two', content: [{type: 'prose', text: 'Two.'}]},
- ],
- ...extra,
- });
- scaffold({
- ...kit(),
- 'a-cli.doc.mjs': flat('cli'),
- 'a-unorganized.doc.mjs': flat('Unorganized'),
- 'z-b2.doc.mjs': flat('b2', {replaces: 'cli'}),
- 'z-u2.doc.mjs': flat('u2', {replaces: 'Unorganized'}),
- });
- // Another package carries the chain on: c3 replaces b2, which replaced cli.
- const three = path.join(tmpDir, 'node_modules', '@acme', 'three');
- fs.mkdirSync(path.join(three, 'docs'), {recursive: true});
- fs.writeFileSync(path.join(three, 'package.json'), JSON.stringify({name: '@acme/three', version: '1.0.0'}));
- fs.writeFileSync(path.join(three, 'astryx.integration.mjs'), "export default {docs: './docs'};\n");
- fs.writeFileSync(
- path.join(three, 'docs', 'c3.doc.mjs'),
- `export const docs = ${JSON.stringify(flat('c3', {replaces: 'b2'}), null, 2)};\n`,
- );
- fs.writeFileSync(
- path.join(tmpDir, 'astryx.config.mjs'),
- "export default {integrations: ['@acme/kit', '@acme/three']};\n",
- );
- for (const name of ['cli', 'CLI']) {
- expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
- }
- for (const name of ['unorganized', 'UNORGANIZED']) {
- expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
- }
- // The replacement still answers to its own names.
- for (const name of ['b2', 'c3']) {
- expect((await docs(name, undefined, {cwd: tmpDir, index: true})).data.name).toBe('c3');
- }
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- for (const entry of listed.data) {
- const read = await docs(entry.topic, undefined, {cwd: tmpDir});
- expect(read.type).toBe('docs.detail');
- expect(read.data.name).toBe(entry.topic);
- }
- const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
- expect(check.status).toBe('warn');
- expect(check.message).toContain('The topic "c3" answers to "cli" through replaces');
- expect(check.message).toContain('The topic "u2" answers to "unorganized" through replaces');
- const inPackage = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
- const graph = inPackage.data.issues
- .filter(issue => issue.code === 'invalid_doc_graph')
- .map(issue => issue.message)
- .join('\n');
- expect(graph).toContain('answers to "cli" through replaces');
- }, SLOW);
-
- it('runs the same checks inside the package: doctor integration docs', async () => {
- scaffold({...kit(), 'broken.doc.mjs': broken()});
- const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
- expect(result.data.issues).toContainEqual(
- expect.objectContaining({
- code: 'invalid_doc_graph',
- severity: 'warning',
- message: expect.stringContaining('"generic:nope" names no doc'),
- }),
- );
- }, SLOW);
-
- it("resolves an extension's links against the extension's provider, not the base topic's", async () => {
- scaffold({
- ...kit(),
- 'integrations.doc.mjs': guide('integrations'),
- 'theme-acme.doc.mjs': {
- type: 'generic',
- name: 'theme-acme',
- title: 'Acme theming',
- description: 'Acme notes on theming.',
- extends: 'theme',
- sections: [
- {
- title: 'Acme theming notes',
- content: [
- {
- type: 'prose',
- text: 'See {@link generic:integrations}, and {@link @astryxdesign/cli:generic:tokens} for the tokens.',
- },
- ],
- },
- ],
- },
- });
- const {data} = await docs('theme', 'acme-theming-notes', {cwd: tmpDir});
- // `generic:integrations` is the extension's own guide, never the CLI's
- // `cli/integrations`; a provider-qualified link reaches the CLI's topic.
- expect(data.content[0].text).toBe(
- 'See `astryx docs acme/integrations`, and `astryx docs tokens` for the tokens.',
- );
- // The CLI's own sections of the topic still resolve against the CLI.
- const full = await docs('theme', undefined, {cwd: tmpDir});
- expect(JSON.stringify(full.data)).not.toContain('{@link');
- }, SLOW);
-
- it("warns, in the project and in the package, on an extension link that names no doc of its provider", async () => {
- scaffold({
- ...kit(),
- 'theme-acme.doc.mjs': {
- type: 'generic',
- name: 'theme-acme',
- title: 'Acme theming',
- description: 'Acme notes on theming.',
- extends: 'theme',
- sections: [
- {
- title: 'Acme theming notes',
- content: [{type: 'prose', text: 'See {@link generic:tokens}.'}],
- },
- ],
- },
- });
- const check = await checkDocsTree({
- docsCatalog: await loadDocsCatalog(tmpDir),
- });
- expect(check.status).toBe('warn');
- expect(check.message).toContain('"generic:tokens" names no doc');
- const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
- expect(result.data.issues).toContainEqual(
- expect.objectContaining({
- code: 'invalid_doc_graph',
- message: expect.stringContaining('"generic:tokens" names no doc'),
- }),
- );
- }, SLOW);
-
- it('keeps the CLI route when an integration claims it, and names the claim', async () => {
- scaffold({'cli.doc.mjs': {...NAMESPACE, name: 'cli', title: 'Not the CLI'}});
- const top = await docs('cli', undefined, {cwd: tmpDir});
- expect(top.data.package).toBe('@astryxdesign/cli');
- const check = await checkDocsTree({
- docsCatalog: await loadDocsCatalog(tmpDir),
- });
- expect(check.status).toBe('warn');
- expect(check.message).toContain('both have the route "cli"');
- }, SLOW);
-});
diff --git a/packages/cli/api/docs/integrationDocs.test.mjs b/packages/cli/api/docs/integrationDocs.test.mjs
deleted file mode 100644
index d8a633f450..0000000000
--- a/packages/cli/api/docs/integrationDocs.test.mjs
+++ /dev/null
@@ -1,314 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file End-to-end tests for integration-contributed doc topics: a scaffolded
- * consumer project whose configured integration ships a `docs` root, read back
- * through the public surfaces — `docs()`, `search()`, and the agent-docs block.
- *
- * The unit-level rules (what a docs root contributes, what the catalog does
- * with `replaces`/`extends`) are covered in
- * foundation/discovery/docs-discovery.test.mjs. What is pinned here is that a
- * contributed topic is indistinguishable from a built-in one at the surfaces
- * an agent actually reads.
- *
- * Fixtures live under a repo-local temp dir, not /tmp, because Vite refuses to
- * dynamically import a module from outside the project root.
- */
-
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {docs} from './docs.mjs';
-import {search} from '../search/search.mjs';
-import {loadDocsCatalog} from './_adapter.mjs';
-import {AstryxError} from '../error.mjs';
-
-const SLOW = 30_000;
-
-let tmpDir;
-
-/** A minimal, valid topic. */
-function topic(fields) {
- return {
- type: 'generic',
- name: 'deploying',
- title: 'Deploying',
- description: 'How to ship an app built with Acme widgets.',
- category: 'guide',
- sections: [
- {title: 'Overview', content: [{type: 'prose', text: 'Push the button.'}]},
- ],
- ...fields,
- };
-}
-
-/**
- * A consumer project that configures one integration, optionally with a docs
- * root holding the given topics.
- * @param {Record<string, object|string>} [topics] file name → doc
- * @param {{config?: string}} [options]
- */
-function scaffold(topics, {config} = {}) {
- fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'consumer'}));
- fs.writeFileSync(
- path.join(tmpDir, 'astryx.config.mjs'),
- config ?? "export default {integrations: ['@acme/widgets']};\n",
- );
-
- const pkgDir = path.join(tmpDir, 'node_modules', '@acme', 'widgets');
- fs.mkdirSync(pkgDir, {recursive: true});
- fs.writeFileSync(
- path.join(pkgDir, 'package.json'),
- JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
- );
- fs.writeFileSync(
- path.join(pkgDir, 'astryx.integration.mjs'),
- `export default ${JSON.stringify(topics ? {docs: './docs'} : {})};\n`,
- );
-
- if (topics) {
- const docsDir = path.join(pkgDir, 'docs');
- fs.mkdirSync(docsDir, {recursive: true});
- for (const [file, doc] of Object.entries(topics)) {
- fs.writeFileSync(
- path.join(docsDir, file),
- typeof doc === 'string'
- ? doc
- : `export const docs = ${JSON.stringify(doc, null, 2)};\n`,
- );
- }
- }
-}
-
-beforeEach(() => {
- tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-integration-docs-test-'));
-});
-
-afterEach(() => {
- fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-describe('integration-contributed topics', () => {
- it('lists and reads like a built-in topic, naming its owner', async () => {
- scaffold({'deploying.doc.mjs': topic()});
-
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- const entry = listed.data.find(t => t.topic === 'deploying');
- expect(entry).toMatchObject({
- topic: 'deploying',
- description: 'How to ship an app built with Acme widgets.',
- package: '@acme/widgets',
- });
- // The built-in topics keep their own owner.
- expect(listed.data.find(t => t.topic === 'tokens').package).toBe('@astryxdesign/cli');
-
- const detail = await docs('deploying', undefined, {cwd: tmpDir, full: true});
- expect(detail.type).toBe('docs.detail');
- expect(detail.data.sections[0].content[0].text).toBe('Push the button.');
-
- const section = await docs('deploying', 'overview', {cwd: tmpDir});
- expect(section.data.title).toBe('Overview');
- }, SLOW);
-
- it('is invisible to a project that does not configure the integration', async () => {
- scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {};\n'});
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- expect(listed.data.some(t => t.topic === 'deploying')).toBe(false);
- }, SLOW);
-
- it('serves the replacement of a built-in topic, and says what it replaced', async () => {
- scaffold({
- 'getting-started.doc.mjs': topic({
- name: 'getting-started',
- replaces: 'getting-started',
- title: 'Getting started',
- description: 'Install Acme widgets.',
- sections: [
- {title: 'Install', content: [{type: 'prose', text: 'yarn add @acme/widgets'}]},
- ],
- }),
- });
-
- const detail = await docs('getting-started', undefined, {cwd: tmpDir, full: true});
- expect(detail.data.sections.map(s => s.title)).toEqual(['Install']);
- expect(detail.data.sections[0].content[0].text).toBe('yarn add @acme/widgets');
-
- const listed = await docs(undefined, undefined, {cwd: tmpDir});
- const entries = listed.data.filter(t => t.topic === 'getting-started');
- expect(entries).toHaveLength(1);
- expect(entries[0]).toMatchObject({
- package: '@acme/widgets',
- replaces: 'getting-started',
- });
- }, SLOW);
-
- it('keeps the replaced name resolving when the replacement renames it', async () => {
- scaffold({
- 'setup.doc.mjs': topic({name: 'setup', replaces: 'getting-started'}),
- });
- const byOldName = await docs('getting-started', undefined, {cwd: tmpDir, full: true});
- const byNewName = await docs('setup', undefined, {cwd: tmpDir, full: true});
- expect(byOldName.data.name).toBe('setup');
- expect(byNewName.data.name).toBe('setup');
- }, SLOW);
-
- it('merges an extension into the topic it extends', async () => {
- const builtin = await docs('theme', undefined, {full: true});
- const baseSectionTitle = builtin.data.sections[0].title;
- scaffold({
- 'theme-internal.doc.mjs': topic({
- name: 'theme-internal',
- extends: 'theme',
- sections: [
- {title: baseSectionTitle, content: [{type: 'prose', text: 'Use the Acme theme.'}]},
- {title: 'Acme themes', content: [{type: 'prose', text: 'Three of them.'}]},
- ],
- }),
- });
-
- const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});
- // The extension is not a topic of its own.
- expect((await docs(undefined, undefined, {cwd: tmpDir})).data.some(
- t => t.topic === 'theme-internal',
- )).toBe(false);
- expect(extended.data.sections[0].content[0].text).toBe('Use the Acme theme.');
- expect(extended.data.sections.at(-1).title).toBe('Acme themes');
- // Everything the extension did not name is still the base doc's.
- expect(extended.data.sections.length).toBe(builtin.data.sections.length + 1);
- }, SLOW);
-
- it('migrates a real built-in section to a stable ID without duplicating it', async () => {
- const builtin = await docs('theme', undefined, {full: true});
- // Readers see a key on every section; the migration case is one whose
- // source authors no id.
- const {docs: authored} = await import('../../assets/docs/theme.doc.mjs');
- const target = authored.sections.find(section => section.id == null);
- expect(target).toBeDefined();
- scaffold({
- 'theme-internal.doc.mjs': topic({
- name: 'theme-internal',
- extends: 'theme',
- sections: [
- {
- id: 'acme-theme-setup',
- title: target.title,
- content: [{type: 'prose', text: 'Use the Acme theme.'}],
- },
- ],
- }),
- });
-
- const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});
- expect(extended.data.sections).toHaveLength(builtin.data.sections.length);
- const matches = extended.data.sections.filter(
- section => section.title === target.title,
- );
- expect(matches).toEqual([
- expect.objectContaining({
- id: 'acme-theme-setup',
- content: [{type: 'prose', text: 'Use the Acme theme.'}],
- }),
- ]);
- }, SLOW);
-
- it('replaces a real built-in section by the key its index shows', async () => {
- const index = await docs('theme', undefined, {index: true});
- const target = index.data.sections[0];
- scaffold({
- 'theme-internal.doc.mjs': topic({
- name: 'theme-internal',
- extends: 'theme',
- sections: [
- {
- id: target.id,
- title: `${target.title} with Acme`,
- content: [{type: 'prose', text: 'Acme first.'}],
- },
- ],
- }),
- });
-
- const extended = await docs('theme', undefined, {cwd: tmpDir, full: true});
- expect(extended.data.sections).toHaveLength(index.data.sections.length);
- expect(extended.data.sections.filter(s => s.id === target.id)).toEqual([
- expect.objectContaining({content: [{type: 'prose', text: 'Acme first.'}]}),
- ]);
- const read = await docs('theme', target.id, {cwd: tmpDir});
- expect(read.data.title).toBe(`${target.title} with Acme`);
- }, SLOW);
-
- it.each(['zh', 'dense'])(
- 'replaces translated real sections by their authored titles under --%s',
- async lang => {
- const english = await docs('theme', undefined, {full: true});
- const englishTitles = english.data.sections.map(section => section.title);
- expect(englishTitles).toEqual(
- expect.arrayContaining(['Quick Start', 'Theme Props']),
- );
- scaffold({
- 'theme-internal.doc.mjs': topic({
- name: 'theme-internal',
- extends: 'theme',
- sections: [
- {
- id: 'acme-quick-start',
- title: 'Quick Start',
- content: [{type: 'prose', text: 'Acme quick start.'}],
- },
- {
- title: 'Theme Props',
- content: [{type: 'prose', text: 'Acme props.'}],
- },
- ],
- }),
- });
-
- const base = await docs('theme', undefined, {lang, full: true});
- expect(base.data.sections.map(section => section.title)).not.toEqual(
- englishTitles,
- );
- const extended = await docs('theme', undefined, {cwd: tmpDir, lang, full: true});
- expect(extended.data.sections).toHaveLength(base.data.sections.length);
- expect(
- extended.data.sections.filter(
- section => section.id === 'acme-quick-start',
- ),
- ).toHaveLength(1);
- expect(
- extended.data.sections.filter(
- section => section.content[0]?.text === 'Acme props.',
- ),
- ).toHaveLength(1);
- },
- SLOW,
- );
-
- it('offers the contributed topics as suggestions on an unknown one', async () => {
- scaffold({'deploying.doc.mjs': topic()});
- await expect(docs('nope-not-a-topic', undefined, {cwd: tmpDir, full: true})).rejects.toBeInstanceOf(
- AstryxError,
- );
- try {
- await docs('nope-not-a-topic', undefined, {cwd: tmpDir, full: true});
- } catch (err) {
- expect(err.suggestions.map(s => s.name)).toContain('deploying');
- }
- }, SLOW);
-
- it('indexes a contributed topic in search', async () => {
- scaffold({'deploying.doc.mjs': topic()});
- const {data} = await search('deploying', {cwd: tmpDir, type: 'doc'});
- expect(data.results[0]).toMatchObject({
- domain: 'doc',
- name: 'deploying',
- command: 'astryx docs deploying',
- });
- }, SLOW);
-
- it("falls back to the CLI's own topics when the project config is unreadable", async () => {
- scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {integrations: 42};\n'});
- const catalog = await loadDocsCatalog(tmpDir);
- expect(catalog.resolve('tokens')).toBeTruthy();
- expect(catalog.resolve('deploying')).toBeUndefined();
- }, SLOW);
-});
diff --git a/packages/cli/api/doctor/doctor.doc.mjs b/packages/cli/api/doctor/doctor.doc.mjs
index fb01e356cd..f0f3b350e3 100644
--- a/packages/cli/api/doctor/doctor.doc.mjs
+++ b/packages/cli/api/doctor/doctor.doc.mjs
@@ -13,14 +13,18 @@ export const doc = {
name: 'doctor',
namespace: 'cli/api',
displayName: 'doctor()',
- summary: 'Read-only project + environment health check.',
+ summary:
+ "Check a project's Astryx setup and get a pass/warn/fail report per check. Use it as a CI gate or before debugging a broken install.",
description:
- 'Runs a series of side-effect-free diagnostics: Node version, ' +
+ 'Runs a series of diagnostics: Node version, ' +
'@astryxdesign/core install and version alignment with the CLI, installed ' +
'themes and wiring, astryx.config validity, integrations linked from ' +
- 'package.json without a config entry, agent docs, core peer ' +
- 'dependencies, and the detected package manager, and returns a structured ' +
- 'report. It only reads (never installs, writes, or mutates), so it is safe ' +
+ 'package.json without a config entry, core peer dependencies, ' +
+ 'integration provider identity and contribution issues, agent docs, the ' +
+ 'detected package manager, and the health of the docs the CLI reads (authoring ' +
+ 'and CLI docs, the docs tree, doc size), and returns a structured ' +
+ 'report. It only reads (never installs, writes, or mutates), apart from ' +
+ "importing astryx.config, which runs that file's top-level code, so it is safe " +
'as a CI gate and for agents to invoke.',
importPath: '@astryxdesign/cli/api',
signature: 'doctor(options?: DoctorOptions): Promise<DoctorResponse>',
@@ -29,18 +33,23 @@ export const doc = {
{
name: 'options.cwd',
type: 'string',
- description: 'Directory to diagnose.',
+ description:
+ 'Directory to diagnose. A missing directory is not an error; it shows up in the checks (e.g. core-installed: fail).',
+ default: 'process.cwd()',
},
],
returns: [
{
type: 'doctor',
description:
- 'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass`; plus `data.summary` with counts per status.',
+ 'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and an optional `fix` (always present on `warn` and `fail`; some `info` checks carry one too); plus `data.summary` with counts per status.',
},
],
examples: [
- {label: 'Run diagnostics', code: 'const r = await doctor();'},
+ {
+ label: 'Fail a CI step on any failed check',
+ code: 'const r = await doctor();\nif (r.data.summary.fail > 0) process.exitCode = 1;',
+ },
{
label: 'Diagnose a directory',
code: "await doctor({cwd: '/path/to/app'});",
diff --git a/packages/cli/api/doctor/doctor.type.mjs b/packages/cli/api/doctor/doctor.type.mjs
index cecdb22dbe..f166be436b 100644
--- a/packages/cli/api/doctor/doctor.type.mjs
+++ b/packages/cli/api/doctor/doctor.type.mjs
@@ -19,7 +19,7 @@
* @property {string} label - Human-readable check name.
* @property {DoctorStatus} status
* @property {string} message - One-line result summary.
- * @property {string} [fix] - Actionable remediation, present when status is not 'pass'.
+ * @property {string} [fix] - Actionable remediation: always present on 'warn' and 'fail'; some 'info' checks carry one too.
*/
/**
diff --git a/packages/cli/api/gap-report/gap-report.doc.mjs b/packages/cli/api/gap-report/gap-report.doc.mjs
index 9c53dfac63..bfa9a334a6 100644
--- a/packages/cli/api/gap-report/gap-report.doc.mjs
+++ b/packages/cli/api/gap-report/gap-report.doc.mjs
@@ -12,12 +12,16 @@ export const doc = {
name: 'gapReport',
namespace: 'cli/api',
displayName: 'gapReport()',
- summary: 'Route a design-system gap through the fan-out handler composition.',
+ summary:
+ 'Report a missing or hard-to-use design-system capability to the package that owns it.',
description:
- 'Creates a normalized gap report and fans it out to every effective handler: the project config handler first, then each loaded integration handler in config order, deduplicated by handle function identity. Each handler receives a structuredClone of the report and an AbortSignal, then runs in its own worker with a 30 s timeout and stdout redirected to stderr. A timed-out worker is terminated before the next handler starts, so process.exit, process.exitCode, and late continuations cannot affect the CLI process. A public handler requires confirmPublic per handler; internal handlers always run. When no handlers exist, a built-in GitHub/routed-only fallback runs. The aggregate response carries ordered deliveries with per-handler outcomes.',
+ 'Sends a gap report to every configured handler: the project config handler first, then each integration handler in config order. ' +
+ 'Each handler has 30 s to finish, and its output goes to stderr. Public handlers run only with confirmPublic; internal handlers always run. ' +
+ "With no handler, it files a GitHub issue for the owning package only with confirmPublic (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+ 'The report records whether an agent or a person ran it, and the response lists each handler outcome in order.',
importPath: '@astryxdesign/cli/api',
signature:
- 'gapReport(component?: string, options?: GapReportOptions): Promise<GapReportCategoriesResponse | GapReportReceiptResponse>',
+ 'gapReport(component: string | undefined, options?: GapReportOptions): Promise<GapReportCategoriesResponse | GapReportReceiptResponse>',
keywords: [
'gap',
'report',
@@ -56,13 +60,13 @@ export const doc = {
name: 'options.package',
type: 'string',
description:
- 'Explicit owning package when automatic routing is ambiguous.',
+ 'Package that owns the gap: @astryxdesign/core, or a loaded integration by package name or config entry. Overrides automatic owner routing; required when more than one package provides the component.',
},
{
name: 'options.confirmPublic',
type: 'boolean',
description:
- 'Explicitly consent to invoking public handlers or creating a GitHub issue.',
+ 'Allow public delivery: public handlers run, and with no handler a GitHub issue is filed through the gh CLI.',
default: 'false',
},
{
@@ -77,6 +81,7 @@ export const doc = {
type: 'string',
description:
'Directory used to load project config and component ownership.',
+ default: 'process.cwd()',
},
],
returns: [
@@ -87,17 +92,21 @@ export const doc = {
{
type: 'gap-report.file',
description:
- 'An aggregate receipt with per-handler deliveries, filedCount/routedOnlyCount totals, and overall status.',
+ 'Receipt: status (filed, partial, failed, routed_only, consent_required, skipped), package, issuesUrl, ordered deliveries (handlerType, handler, audience, status, url, message), filedCount, and routedOnlyCount.',
},
],
throws: [
+ {
+ code: 'ERR_MISSING_ARGUMENT',
+ when: 'component, category, or reason is missing, blank, or not a string (unless listCategories is true)',
+ },
{
code: 'ERR_UNKNOWN_CATEGORY',
when: 'category is not one of the fixed gap-report values',
},
{
code: 'ERR_INVALID_ARGUMENT',
- when: 'a field value is invalid',
+ when: 'component is over 120 characters, category is over 80, reason is over 2000, or detail is not a string or is over 8000 characters',
},
{
code: 'ERR_AMBIGUOUS_COMPONENT',
@@ -109,7 +118,7 @@ export const doc = {
},
{
code: 'ERR_NOT_FOUND',
- when: 'no handler and no issues URL available',
+ when: 'no report handler is configured and the owning package has no issues URL',
},
],
examples: [
@@ -122,8 +131,8 @@ export const doc = {
code: "const receipt = await gapReport('Button', {category: 'missing_variant', reason: 'Need a compact size'});",
},
{
- label: 'Confirm public filing',
- code: "await gapReport('Button', {category: 'docs_gap', reason: 'Missing keyboard example', confirmPublic: true});",
+ label: 'Name the owning package',
+ code: "const receipt = await gapReport('Button', {category: 'docs_gap', reason: 'Missing keyboard example', package: '@astryxdesign/core'});",
},
],
command: 'gap-report',
diff --git a/packages/cli/api/hook/hook.doc.mjs b/packages/cli/api/hook/hook.doc.mjs
index df72906cc8..d233e10f60 100644
--- a/packages/cli/api/hook/hook.doc.mjs
+++ b/packages/cli/api/hook/hook.doc.mjs
@@ -34,6 +34,7 @@ export const doc = {
name: 'options.cwd',
type: 'string',
description: 'Directory to resolve @astryxdesign/core from.',
+ default: 'process.cwd()',
},
{
name: 'options.list',
@@ -43,7 +44,8 @@ export const doc = {
{
name: 'options.category',
type: 'string',
- description: 'List only hooks in this category.',
+ description:
+ "List only the hooks in this category, a key of the unfiltered list such as 'Media' or 'Focus'.",
},
{
name: 'options.params',
@@ -54,7 +56,8 @@ export const doc = {
name: 'options.detail',
type: "'full' | 'compact' | 'brief'",
description: 'Detail level for list views.',
- default: "'full' for a named hook, 'brief' for list views",
+ default:
+ "'full' for a named hook; 'brief' for lists (returned as data.detail: 'names')",
},
{
name: 'options.lang',
@@ -104,7 +107,7 @@ export const doc = {
},
{
label: 'Browse a category',
- code: "await hook(undefined, {category: 'State', detail: 'compact'});",
+ code: "await hook(undefined, {category: 'Media', detail: 'compact'});",
},
],
command: 'hook',
diff --git a/packages/cli/api/index.mjs b/packages/cli/api/index.mjs
index 54459d31b7..b33d4839f2 100644
--- a/packages/cli/api/index.mjs
+++ b/packages/cli/api/index.mjs
@@ -3,7 +3,7 @@
/**
* @file Programmatic API for the Astryx CLI.
*
- * Every function returns the same { type, data } envelope that `xds --json` outputs.
+ * Every function returns the same { type, data } envelope that `astryx --json` outputs.
* Errors throw AstryxError (with optional .suggestions).
*
* @example
diff --git a/packages/cli/api/init/init.doc.mjs b/packages/cli/api/init/init.doc.mjs
index ef536e5792..2f2d38b2f9 100644
--- a/packages/cli/api/init/init.doc.mjs
+++ b/packages/cli/api/init/init.doc.mjs
@@ -19,10 +19,9 @@ export const doc = {
'Sets a project up with NO prompts, so it behaves identically for humans, ' +
'agents, CI, and piped I/O. By default it installs the AGENTS.md/CLAUDE.md ' +
'agent-docs cheat sheet, including guidance from configured integrations, and ' +
- 'prints getting-started guidance; `features` / ' +
- '`all` add theme and page-building guidance and can scaffold a starter ' +
- 'template. With `removeAgents` it removes the managed agent-docs block ' +
- 'instead of installing.',
+ "prints getting-started guidance; `features` / `all` print only the chosen features' " +
+ 'guidance instead (the theme feature also writes the annotated theme template). ' +
+ 'With `removeAgents` it removes the managed agent-docs block instead of installing.',
importPath: '@astryxdesign/cli/api',
signature:
'init(options?: InitOptions, ctx?: {cwd?: string}): Promise<InitRunResponse | InitRemoveResponse>',
@@ -32,7 +31,7 @@ export const doc = {
name: 'options.features',
type: 'string',
description:
- 'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (page-template guidance).',
+ 'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (the page-building commands; writes a page only with templateName).',
},
{
name: 'options.all',
@@ -47,7 +46,8 @@ export const doc = {
{
name: 'options.agent',
type: 'string',
- description: 'Agent preset: claude, cursor, codex, hermes, muse, all.',
+ description:
+ 'Agent preset: claude, cursor, codex, hermes, muse, all. Used only when the agents feature runs.',
},
{
name: 'options.agentDocsPath',
@@ -58,9 +58,14 @@ export const doc = {
name: 'options.templateName',
type: 'string',
description:
- 'Scaffold a named page template (programmatic only; the CLI never sets it).',
+ 'Scaffold this page template to src/pages/<name>/page.tsx. Used only when the template feature runs (features includes template, or all); otherwise ignored. Programmatic only; the CLI never sets it.',
+ },
+ {
+ name: 'ctx.cwd',
+ type: 'string',
+ description: 'Directory to set up.',
+ default: 'process.cwd()',
},
- {name: 'ctx.cwd', type: 'string', description: 'Directory to set up.'},
],
returns: [
{
@@ -71,13 +76,13 @@ export const doc = {
{
type: 'init.remove',
description:
- 'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
+ 'Returned when `removeAgents` is set. `data.removed` is always true, even when no managed block was found.',
},
],
throws: [
{
code: 'ERR_UNKNOWN_AGENT',
- when: '`agent` is not one of claude, cursor, codex, hermes, muse, all',
+ when: 'the agents feature runs (default mode, features includes agents, or all) and `agent` is not one of claude, cursor, codex, hermes, muse, all',
},
{
code: 'ERR_UNKNOWN_FEATURE',
@@ -85,7 +90,7 @@ export const doc = {
},
{
code: 'ERR_UNKNOWN_TEMPLATE',
- when: '`templateName` matches no bundled template',
+ when: 'the template feature runs and `templateName` matches no bundled template',
},
{
code: 'ERR_FILE_EXISTS',
@@ -93,7 +98,7 @@ export const doc = {
},
{
code: 'ERR_PATH_TRAVERSAL',
- when: 'the template output path resolves outside cwd, for example through a symlinked src directory',
+ when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file resolves outside cwd through a symlink',
},
],
examples: [
diff --git a/packages/cli/api/integration/add-theme.mjs b/packages/cli/api/integration/add-theme.mjs
index 8891d49ee1..0e0031b694 100644
--- a/packages/cli/api/integration/add-theme.mjs
+++ b/packages/cli/api/integration/add-theme.mjs
@@ -24,6 +24,10 @@ import {
import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
import {themeDescriptorSource} from '../../foundation/integrations/theme-descriptor.mjs';
import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {
+ themesCliProblem,
+ withDocsTreeCli,
+} from '../../foundation/integrations/cli-requirement.mjs';
import {
applyWrites,
findPackageDir,
@@ -233,11 +237,28 @@ export async function integrationAddTheme(name, options = {}) {
createOnly: true,
},
];
- const packageUpdate = packageJsonUpdate(
+ let packageUpdate = packageJsonUpdate(
packageFile,
rootPath,
path.basename(manifestFile),
);
+ // A CLI older than the one that reads typed theme descriptors rejects the
+ // themes root and withholds the package's themes and docs. Declare the CLI
+ // that reads them as a peer, so an older one is flagged at install instead.
+ {
+ const expectedOriginal =
+ packageUpdate?.expectedOriginal ?? fs.readFileSync(packageFile);
+ const text = packageUpdate?.contents ?? expectedOriginal.toString('utf-8');
+ const current = JSON.parse(text);
+ if (themesCliProblem(current) != null) {
+ packageUpdate = {
+ contents:
+ JSON.stringify(withDocsTreeCli(current), null, 2) +
+ (text.endsWith('\n') ? '\n' : ''),
+ expectedOriginal,
+ };
+ }
+ }
if (packageUpdate != null) {
plans.push({
path: packageFile,
diff --git a/packages/cli/api/integration/add-theme.test.mjs b/packages/cli/api/integration/add-theme.test.mjs
index 3016c9a2f7..e36602d522 100644
--- a/packages/cli/api/integration/add-theme.test.mjs
+++ b/packages/cli/api/integration/add-theme.test.mjs
@@ -77,6 +77,40 @@ describe('integrationAddTheme', () => {
expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
});
+ it('declares the optional CLI peer that reads typed theme descriptors', async () => {
+ setup({includeFiles: false});
+ const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+ expect(result.data.files).toContain('package.json');
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+ );
+ expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.7.0'});
+ expect(pkg.peerDependenciesMeta).toEqual({
+ '@astryxdesign/cli': {optional: true},
+ });
+ });
+
+ it('keeps a CLI peer that already reads typed theme descriptors', async () => {
+ const pkg = {
+ name: '@acme/themes',
+ version: '1.0.0',
+ peerDependencies: {'@astryxdesign/cli': '^0.7.2'},
+ };
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ `${JSON.stringify(pkg, null, 2)}\n`,
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'astryx.integration.mjs'),
+ 'export default {};\n',
+ );
+ const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+ expect(result.data.files).not.toContain('package.json');
+ expect(
+ JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8')),
+ ).toEqual(pkg);
+ });
+
it('dry-runs the identical receipt without writing anything', async () => {
setup();
const beforeManifest = fs.readFileSync(
diff --git a/packages/cli/api/integration/authoring-checks.mjs b/packages/cli/api/integration/authoring-checks.mjs
index 942a74ef1a..2328b174dc 100644
--- a/packages/cli/api/integration/authoring-checks.mjs
+++ b/packages/cli/api/integration/authoring-checks.mjs
@@ -368,11 +368,11 @@ export async function integrationDocConflicts(pkg, options = {}) {
// and placed guides this package adds to the docs tree, and every link in
// its docs (spec:AST-046, spec:AST-047).
if (errors.length === 0) {
- for (const message of await packageDocsProblems(
+ for (const {severity, message} of await packageDocsProblems(
/** @type {{name: string}} */ (resolved.integration),
discovered,
)) {
- issues.push({code: 'invalid_doc_graph', severity: 'warning', message});
+ issues.push({code: 'invalid_doc_graph', severity, message});
}
// A reference block includes content rather than linking to it, so one
diff --git a/packages/cli/api/integration/integrationPackCheck.doc.mjs b/packages/cli/api/integration/integrationPackCheck.doc.mjs
index 2901479e02..eda9e78bae 100644
--- a/packages/cli/api/integration/integrationPackCheck.doc.mjs
+++ b/packages/cli/api/integration/integrationPackCheck.doc.mjs
@@ -7,13 +7,13 @@ export const doc = {
name: 'integrationPackCheck',
namespace: 'cli/api',
displayName: 'integrationPackCheck()',
- summary: 'Prove an integration package survives npm packing.',
+ summary: 'Check an integration package the way npm will publish it.',
description:
"Validates the local integration, runs the package lifecycle, packs with npm, checks required files against npm's authoritative tarball list, extracts the real tarball into a scratch consumer, compares local and packed contribution inventories, and resolves every packed component through its documented public import to verify that module exports the component. A package that ships a namespace doc or a placed guide, or has a template that sets `replaces`, fails unless its `@astryxdesign/cli` peer range admits only CLIs that read them.",
importPath: '@astryxdesign/cli/api',
signature:
'integrationPackCheck(options?: IntegrationPackCheckOptions): Promise<IntegrationPackCheckResponse>',
- keywords: ['integration', 'pack', 'check', 'publish', 'tarball', 'consumer'],
+ keywords: ['verify', 'pack', 'publish', 'tarball', 'consumer'],
params: [
{
name: 'options.cwd',
@@ -31,6 +31,6 @@ export const doc = {
examples: [
{label: 'Check the local package', code: 'await integrationPackCheck();'},
],
- command: 'integration pack',
+ command: 'integration verify',
related: ['integrationAdd', 'validateIntegration'],
};
diff --git a/packages/cli/api/integration/pack-check.lifecycle-output.test.mjs b/packages/cli/api/integration/pack-check.lifecycle-output.test.mjs
index b121e61963..eb319d9766 100644
--- a/packages/cli/api/integration/pack-check.lifecycle-output.test.mjs
+++ b/packages/cli/api/integration/pack-check.lifecycle-output.test.mjs
@@ -24,6 +24,8 @@ function writeThemePackage(scripts) {
name: '@acme/widgets',
version: '1.0.0',
files: ['astryx.integration.mjs', 'themes'],
+ peerDependencies: {'@astryxdesign/cli': '>=0.7.0'},
+ peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
scripts,
},
null,
diff --git a/packages/cli/api/integration/pack-check.mjs b/packages/cli/api/integration/pack-check.mjs
index d59e3f11c5..38a343776d 100644
--- a/packages/cli/api/integration/pack-check.mjs
+++ b/packages/cli/api/integration/pack-check.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file `astryx integration pack --check` — verify an integration package is
+ * @file `astryx integration verify` — verify an integration package is
* ready to publish by cross-referencing its declared contributions against the
* real npm tarball.
*
@@ -30,8 +30,13 @@ import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs'
import {
docsTreeCliProblem,
replacesCliProblem,
+ sectionIdsCliProblem,
+ themesCliProblem,
} from '../../foundation/integrations/cli-requirement.mjs';
-import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
+import {
+ discoverIntegrationDocs,
+ loadTopicModule,
+} from '../../foundation/discovery/docs-discovery.mjs';
import {
discoverIntegrationComponents,
resolveIntegrationImportPath,
@@ -333,6 +338,23 @@ function moduleExportsName(file, exportName, seen = new Set()) {
return found;
}
+/**
+ * Whether any of these doc files has a section that sets `id`.
+ * @param {string[]} files
+ * @returns {Promise<boolean>}
+ */
+async function setsSectionIds(files) {
+ for (const file of files) {
+ if (typeof file !== 'string') continue;
+ const doc = /** @type {any} */ (await loadTopicModule(file).catch(() => null));
+ const sections = Array.isArray(doc?.sections) ? doc.sections : [];
+ if (sections.some((/** @type {any} */ section) => section?.id != null)) {
+ return true;
+ }
+ }
+ return false;
+}
+
/**
* Resolve package specifiers through Node's real ESM resolver from the scratch
* consumer. Resolution does not execute the target module, so source `.tsx`
@@ -625,19 +647,31 @@ export async function integrationPackCheck(options = {}) {
// (spec:AST-046 FR11): an older CLI can hide every doc topic the package
// ships, so the declared CLI range must admit only CLIs that read it.
if (loaded.docs) {
- const {namespaces, guides} = await discoverIntegrationDocs(loaded).catch(
- () => ({namespaces: [], guides: []}),
- );
+ const {records, namespaces, guides} = await discoverIntegrationDocs(
+ loaded,
+ ).catch(() => ({records: [], namespaces: [], guides: []}));
const problem =
namespaces.length > 0 || guides.length > 0
? docsTreeCliProblem(pkg)
: null;
if (problem != null) {
issues.push(error('docs_tree_needs_cli', problem));
+ } else if (
+ await setsSectionIds([
+ ...records.map(record => record.path),
+ ...guides.map(guide => /** @type {any} */ (guide.ref).topicFile),
+ ])
+ ) {
+ // A section `id` is also a field an older CLI rejects, hiding the
+ // package's doc topics; the same peer range fixes both.
+ const idProblem = sectionIdsCliProblem(pkg);
+ if (idProblem != null) {
+ issues.push(error('section_ids_need_cli', idProblem));
+ }
}
}
// A template that sets `replaces` needs a CLI that reads the field
- // (spec:AST-035): an older CLI withholds the package's templates and docs.
+ // (spec:AST-035): an older CLI drops that template and hides the package's docs.
if (loaded.templates) {
const found = await discoverIntegrationTemplatesForOne(loaded).catch(
() => ({templates: [], errors: []}),
@@ -650,6 +684,12 @@ export async function integrationPackCheck(options = {}) {
const problem = setsReplaces ? replacesCliProblem(pkg) : null;
if (problem != null) issues.push(error('replaces_needs_cli', problem));
}
+ // A theme needs a CLI that reads typed theme descriptors: an older CLI
+ // rejects the themes root and withholds the package's themes and docs.
+ if (localIdentities.themes.length > 0) {
+ const problem = themesCliProblem(pkg);
+ if (problem != null) issues.push(error('themes_need_cli', problem));
+ }
// Temp resources — always cleaned up
const tgzTmpDir = fs.mkdtempSync(
@@ -682,6 +722,14 @@ export async function integrationPackCheck(options = {}) {
// package's already-installed dependencies. The unique suffix makes
// concurrent checks independent.
scratchBase = fs.mkdtempSync(path.join(packageDir, '.astryx-pack-check-'));
+ // The consumer's own package.json makes it the package scope for its
+ // imports. Without one, Node resolves the package's name through the
+ // SOURCE package.json (self-reference), so an export target left out of
+ // the tarball would still resolve.
+ fs.writeFileSync(
+ path.join(scratchBase, 'package.json'),
+ `${JSON.stringify({name: 'astryx-verify-consumer', private: true})}\n`,
+ );
// Cross-reference file inventory vs pack list
if (!packResult.packedPaths.has(fileInv.manifest)) {
diff --git a/packages/cli/api/integration/pack-check.test.mjs b/packages/cli/api/integration/pack-check.test.mjs
index e8917a8325..7144a88f4b 100644
--- a/packages/cli/api/integration/pack-check.test.mjs
+++ b/packages/cli/api/integration/pack-check.test.mjs
@@ -36,6 +36,8 @@ function writePackage({
scripts,
} = {}) {
const pkg = {name, version};
+ // A theme needs a CLI that reads typed theme descriptors.
+ if (themes) pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
if (files !== undefined) pkg.files = files;
if (scripts !== undefined) pkg.scripts = scripts;
fs.writeFileSync(
@@ -94,6 +96,30 @@ describe('integrationPackCheck', () => {
);
});
+ it('fails a package that ships a theme on a CLI range that cannot read it', async () => {
+ writePackage({files: ['astryx.integration.mjs', 'themes']});
+ const pkgFile = path.join(tmpDir, 'package.json');
+ const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+ delete pkg.peerDependencies;
+ fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+
+ const missing = await integrationPackCheck({cwd: tmpDir});
+ expect(missing.data.packable).toBe(false);
+ expect(missing.data.issues).toContainEqual(
+ expect.objectContaining({
+ code: 'themes_need_cli',
+ message: expect.stringContaining('ships a theme'),
+ }),
+ );
+
+ pkg.peerDependencies = {'@astryxdesign/cli': '^0.6.3'};
+ fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+ const old = await integrationPackCheck({cwd: tmpDir});
+ expect(old.data.issues).toContainEqual(
+ expect.objectContaining({code: 'themes_need_cli'}),
+ );
+ });
+
it('fails when a theme entry omits its inferred runtime export', async () => {
writePackage({files: ['astryx.integration.mjs', 'themes']});
fs.writeFileSync(
@@ -193,6 +219,39 @@ describe('integrationPackCheck', () => {
);
});
+ it('resolves public imports in the packed package, not the source', async () => {
+ // The root export's target is left out of `files`: the source package
+ // resolves it, but an app that installs the tarball cannot.
+ fs.writeFileSync(
+ path.join(tmpDir, 'package.json'),
+ `${JSON.stringify({
+ name: '@acme/widgets',
+ version: '1.0.0',
+ files: ['astryx.integration.mjs'],
+ exports: {'.': './index.mjs'},
+ })}\n`,
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'index.mjs'),
+ "export {AcmeWidget} from './components/AcmeWidget.tsx';\n",
+ );
+ await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+ const docFile = path.join(tmpDir, 'components', 'AcmeWidget.doc.mjs');
+ const doc = fs.readFileSync(docFile, 'utf-8');
+ expect(doc).toContain('@acme/widgets/components/AcmeWidget');
+ fs.writeFileSync(
+ docFile,
+ doc.replace('@acme/widgets/components/AcmeWidget', '@acme/widgets'),
+ );
+
+ const result = await integrationPackCheck({cwd: tmpDir});
+
+ expect(result.data.packable).toBe(false);
+ expect(result.data.issues).toContainEqual(
+ expect.objectContaining({code: 'component_export_missing'}),
+ );
+ });
+
it('fails when packed template source is hidden by package exports', async () => {
writePackage({
manifest: "export default {templates: './templates'};\n",
@@ -336,6 +395,37 @@ describe('integrationPackCheck', () => {
expect(await codes()).not.toContain('docs_tree_needs_cli');
}, 120_000);
+ it('fails a package whose doc section sets id on a CLI range that rejects the field', async () => {
+ writePackage({manifest: "export default {docs: './docs'};\n", themes: false});
+ fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+ const topic = (/** @type {string} */ section) =>
+ `export default {type: 'generic', name: 'notes', title: 'Notes', description: 'Notes.', sections: [${section}]};\n`;
+ const file = path.join(tmpDir, 'docs', 'notes.doc.mjs');
+ const codes = async () =>
+ (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+ (/** @type {{code: string}} */ issue) => issue.code,
+ );
+ fs.writeFileSync(
+ file,
+ topic("{title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}"),
+ );
+ expect(await codes()).not.toContain('section_ids_need_cli');
+ // A fresh file name: the module loader caches a path once it is imported.
+ fs.rmSync(file);
+ fs.writeFileSync(
+ path.join(tmpDir, 'docs', 'notes-with-ids.doc.mjs'),
+ topic(
+ "{id: 'take-notes', title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}",
+ ),
+ );
+ expect(await codes()).toContain('section_ids_need_cli');
+ const pkgFile = path.join(tmpDir, 'package.json');
+ const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+ pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
+ fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+ expect(await codes()).not.toContain('section_ids_need_cli');
+ }, 120_000);
+
it('fails a package with a template that sets replaces on a CLI range that rejects the field', async () => {
writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
diff --git a/packages/cli/api/integration/pack-check.type.mjs b/packages/cli/api/integration/pack-check.type.mjs
index 72987e6b74..d114e02174 100644
--- a/packages/cli/api/integration/pack-check.type.mjs
+++ b/packages/cli/api/integration/pack-check.type.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Colocated types for `astryx integration pack --check`.
+ * @file Colocated types for `astryx integration verify`.
*/
/**
diff --git a/packages/cli/api/json/assertResponse.doc.mjs b/packages/cli/api/json/assertResponse.doc.mjs
index bfb102645f..bb8a277deb 100644
--- a/packages/cli/api/json/assertResponse.doc.mjs
+++ b/packages/cli/api/json/assertResponse.doc.mjs
@@ -49,7 +49,7 @@ export const doc = {
throws: [
{
code: 'Error',
- when: 'the CLI returned an error envelope (the CLI message is rethrown), or the response `type` is not expectedType',
+ when: 'a plain Error with no code: the CLI returned an error envelope (its message is rethrown; code and suggestions are dropped), or the response `type` is not expectedType',
},
],
examples: [
diff --git a/packages/cli/api/json/isError.doc.mjs b/packages/cli/api/json/isError.doc.mjs
index a9f0bb7c14..bee311a703 100644
--- a/packages/cli/api/json/isError.doc.mjs
+++ b/packages/cli/api/json/isError.doc.mjs
@@ -15,7 +15,7 @@ export const doc = {
displayName: 'isError()',
summary: 'Did the CLI return an error envelope?',
description:
- 'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
+ 'Tests a parsed response for an `error` key. Branch on this before touching `data`, ' +
'and prefer the stable `code` field over matching the human-readable message, which is ' +
'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
'it does not narrow on its own: cast to the matching *Response type to get typed access.',
diff --git a/packages/cli/api/search/search.doc.mjs b/packages/cli/api/search/search.doc.mjs
index 56e9fbe4fd..79e66b5fb9 100644
--- a/packages/cli/api/search/search.doc.mjs
+++ b/packages/cli/api/search/search.doc.mjs
@@ -48,7 +48,7 @@ export const doc = {
name: 'options.cwd',
type: 'string',
description:
- "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it.",
+ "Directory to resolve @astryxdesign/core from. A docs-only search (`type: 'doc'`) does not need it, and a search with no `type` covers the docs alone when core is missing.",
},
],
returns: [
@@ -65,7 +65,7 @@ export const doc = {
},
{
code: 'ERR_CORE_NOT_FOUND',
- when: '@astryxdesign/core cannot be found from the cwd, and the search reads it: every `type` but `doc`',
+ when: '@astryxdesign/core cannot be found from the cwd, and `type` names a domain that reads it: `component`, `hook`, or `template`',
},
],
examples: [
diff --git a/packages/cli/api/search/search.mjs b/packages/cli/api/search/search.mjs
index 94d74ec4d7..d9883a0901 100644
--- a/packages/cli/api/search/search.mjs
+++ b/packages/cli/api/search/search.mjs
@@ -42,6 +42,18 @@
* sentence, a near miss is usually a different word: "site" is not "side",
* "cable" is not "table".
*
+ * A multi-word query has a reserved top tier (see {@link scoreQuery}): the
+ * whole query as a candidate's name or keyword (190-200), then the whole query
+ * as a phrase inside a doc's title or one of its headings (170), then a whole
+ * title of two words or more inside the query (160-169), then a candidate that
+ * matches every word of the query, at least one of them by name or keyword
+ * (151-159). Below those sits everything else: a partial match, or every word
+ * matched only in prose or through the components a page renders. A section titled "Light/Dark Mode" answers `dark
+ * mode` better than any doc that merely names `mode` in code, however exactly;
+ * "Dark mode" answers `how do I add dark mode`; and a guide whose title and
+ * description hold both words of `troubleshoot integration` answers it better
+ * than a doc named `integration`.
+ *
* Description and guidance are separate tiers on purpose. A component's own
* one-line description saying "notification" is a claim about what it IS; the
* same word inside another component's best-practice advice is a passing
@@ -105,6 +117,9 @@ import {setResultCoverage} from './coverage.mjs';
* @property {string} [description]
* @property {string[]} [prose]
* @property {string[]} [guidance]
+ * @property {string[]} [titles] - A doc's title and the headings inside it:
+ * the lines a reader scans to pick it. The whole query standing in one of
+ * them, or one of them standing whole in the query, is a top-tier match.
* @property {string} [_import]
* @property {string} [_title]
* @property {string} [_topic] - A doc result's topic or docs-tree route.
@@ -414,6 +429,120 @@ function bestForToken(tok, candidate, opts = {}) {
return best;
}
+/**
+ * The score of a whole-query phrase inside a doc's title or heading: a keyword
+ * substring hit (70) promoted by the same 100 as the exact tier. Below an
+ * exact name or keyword (190-200), above the token-sum path (~151 at most).
+ */
+const TITLE_PHRASE_SCORE = 170;
+
+/**
+ * The score of a whole title inside a longer query, before its coverage bonus:
+ * one step below {@link TITLE_PHRASE_SCORE}. The bonus (one per query term the
+ * candidate matches, at most 9) orders the sections that share a common title,
+ * so "best practices for spacing" puts Spacing's Best Practices first.
+ */
+const TITLE_IN_QUERY_SCORE = 160;
+
+/**
+ * The score of a candidate that matches every content word of a multi-word
+ * query, before a bonus of up to 8 for how strong its strongest match is: just
+ * above anything that matches only some of the words. The token-sum path tops
+ * out near 150 for a partial match (a 100 on one word, the per-word bonus, and
+ * the coverage term), so an AND-match with one keyword-strength hit (see
+ * {@link STRONG_TOKEN_SCORE}) always outranks an OR-match, and stays below the
+ * title tiers.
+ */
+const FULL_COVERAGE_SCORE = 151;
+
+/**
+ * The strongest single-word hit an every-word match needs to take that tier: a
+ * keyword substring. Two passing mentions in prose, or the components a page
+ * happens to render, are breadth, not relevance; they stay on the token sum,
+ * below an exact name or keyword hit on one of the words.
+ */
+const STRONG_TOKEN_SCORE = 70;
+
+/**
+ * The words of a title or query, lowercased, without punctuation or code ticks.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function phraseWords(text) {
+ return unlinkText(text).toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+
+/**
+ * Whether two words are the same word, allowing a plural on either side, so
+ * `data attributes selector` still reads "Data attribute selectors".
+ * @param {string} a
+ * @param {string} b
+ */
+function samePhraseWord(a, b) {
+ return (
+ a === b ||
+ `${a}s` === b ||
+ `${b}s` === a ||
+ `${a}es` === b ||
+ `${b}es` === a
+ );
+}
+
+/**
+ * Whether `plural` is the plural of `word`: `integrations` of `integration`,
+ * `boxes` of `box`. `es` only follows s, x, z, ch, or sh, so `notes` is not a
+ * plural of `not`.
+ * @param {string} plural
+ * @param {string} word
+ */
+function pluralOf(plural, word) {
+ if (word.length < 3) return false;
+ if (plural === `${word}s`) return true;
+ return /(?:s|x|z|ch|sh)$/.test(word) && plural === `${word}es`;
+}
+
+/**
+ * The first title or heading that holds every word of the query, in order and
+ * side by side, or null.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function headingWithPhrase(term, titles) {
+ const query = phraseWords(term);
+ if (query.length < 2 || !titles) return null;
+ for (const title of titles) {
+ const words = phraseWords(String(title ?? ''));
+ for (let i = 0; i + query.length <= words.length; i++) {
+ if (query.every((word, j) => samePhraseWord(words[i + j], word)))
+ return title;
+ }
+ }
+ return null;
+}
+
+/**
+ * The first title or heading of two words or more that the query holds whole,
+ * in order and side by side, or null. A question such as "how do I add dark
+ * mode" names the "Dark mode" section outright, around words no title has.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function titleInQuery(term, titles) {
+ const query = phraseWords(term);
+ if (!titles) return null;
+ for (const title of titles) {
+ const words = phraseWords(String(title ?? ''));
+ if (words.length < 2 || words.length > query.length) continue;
+ for (let i = 0; i + words.length <= query.length; i++) {
+ if (words.every((word, j) => samePhraseWord(query[i + j], word)))
+ return title;
+ }
+ }
+ return null;
+}
+
/**
* @param {string} term - Lowercased full query.
* @param {string[]} tokens - Content tokens from tokenizeQuery(term).
@@ -437,16 +566,22 @@ export function scoreQuery(term, tokens, candidate) {
// is usually a different word, not a typo.
const fuzzy = tokens.length <= 1;
const full = scoreCandidate(term, candidate, {fuzzy});
+ // A query of several words keeps its phrase tiers below even when stopwords
+ // leave one content word: "make an integration" is still the phrase an
+ // author declares as a keyword, and "build an integration" still names a
+ // title outright, though each tokenizes to `integration` alone.
+ const phrase = phraseWords(term).length >= 2;
- // 0–1 content tokens: keep whole-phrase fuzzy matching (typo tolerance for
- // single words), but if stopwords left exactly one DIFFERENT token (e.g.
- // "pricing page" → "pricing"), score that token too and take the stronger.
- if (tokens.length <= 1) {
+ /** 0–1 content tokens: whole-phrase fuzzy matching (typo tolerance for
+ * single words), but if stopwords left exactly one DIFFERENT token (e.g.
+ * "pricing page" → "pricing"), score that token too and take the stronger. */
+ const fewTokens = () => {
const single =
tokens.length === 1 ? bestForToken(tokens[0], candidate, {fuzzy}) : null;
if (full && (!single || full.score >= single.score)) return asFull(full);
return single ? asFull(single) : null;
- }
+ };
+ if (tokens.length <= 1 && !phrase) return fewTokens();
// The full (untokenized) query matching a candidate's name or a declared
// keyword VERBATIM — full.score 90 or 100, the only two scoreCandidate
@@ -463,6 +598,22 @@ export function scoreQuery(term, tokens, candidate) {
return asFull({score: full.score + 100, reason: full.reason});
}
+ // The whole query standing as a phrase in a doc's title or one of its
+ // headings is the next tier down, and still above the token-sum path. The
+ // reader named what the section is about, in order: `dark mode` is the
+ // "Light/Dark Mode" section. Without this, the title scores a keyword
+ // substring (70) and loses to a doc that happens to name `mode` exactly in
+ // a code tick (90 on one token, 98 with coverage), so API enum docs outrank
+ // the guide section.
+ const heading = headingWithPhrase(term, candidate.titles);
+ if (heading != null) {
+ return asFull({
+ score: TITLE_PHRASE_SCORE,
+ reason: `title "${heading}" holds the whole query`,
+ });
+ }
+ if (tokens.length <= 1) return fewTokens();
+
// Multi-word natural language: score each content token, counting only
// strong hits, then reward coverage so candidates matching more terms win.
let strongest = 0;
@@ -477,8 +628,42 @@ export function scoreQuery(term, tokens, candidate) {
hitTerms.push(tok);
}
}
+ // The reverse of the title tier, a step lower: the query holds a whole title
+ // of two words or more, so the reader asked a question around the section's
+ // name ("how do I add dark mode"). Coverage breaks ties between sections
+ // that share a title such as "Best Practices".
+ const named = titleInQuery(term, candidate.titles);
+ if (named != null) {
+ return {
+ score: TITLE_IN_QUERY_SCORE + Math.min(matched, 9),
+ reason: `the query names the title "${named}"`,
+ matched,
+ total,
+ };
+ }
if (matched === 0) return full ? asFull(full) : null;
+ const reason = `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`;
+
+ // Every word matched is its own tier. Summed per word, a doc that matches
+ // both words of `troubleshoot integration` in its title and description
+ // (50 + bonus + coverage = 77) lost to thirty docs that each match
+ // `integration` alone, by name or in a code tick (98-108). The reader asked for
+ // both; a candidate that has both comes first, ordered among its peers by
+ // how strong its strongest match is. It needs one keyword-strength hit:
+ // every word mentioned in prose, or rendered by a page, is breadth, and
+ // stays on the token sum below an exact hit on one word.
+ if (matched === tokens.length && strongest >= STRONG_TOKEN_SCORE) {
+ return {
+ score:
+ FULL_COVERAGE_SCORE +
+ Math.floor((strongest - MIN_TOKEN_SCORE) / 6.25),
+ reason,
+ matched,
+ total,
+ };
+ }
+
// Base the score on the STRONGEST concept that matched, plus a bonus per
// additional matched concept and a coverage term.
//
@@ -500,14 +685,8 @@ export function scoreQuery(term, tokens, candidate) {
const tokenScore = Math.round(
strongest + Math.min(matched - 1, 3) * 12 + coverage * 15,
);
-
if (full && full.score >= tokenScore) return asFull(full);
- return {
- score: tokenScore,
- reason: `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`,
- matched,
- total,
- };
+ return {score: tokenScore, reason, matched, total};
}
/**
@@ -518,6 +697,8 @@ export function scoreQuery(term, tokens, candidate) {
* @param {string} term - Lowercased search term.
* @param {object} candidate
* @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string} [candidate.domain] - A component, hook, or template name
+ * also matches typed as words: `command palette` is CommandPalette.
* @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
* @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
* @param {string} [candidate.description]
@@ -530,6 +711,7 @@ export function scoreCandidate(
term,
{
name,
+ domain,
keywords = [],
weakKeywords = [],
description = '',
@@ -552,10 +734,26 @@ export function scoreCandidate(
};
const nameLower = name.toLowerCase();
+ // A placed guide's name is its route, and the route's last segment is its
+ // name too, as a flat topic's is: `codemods` is cli/integrations/codemods.
+ const leafLower = nameLower.slice(nameLower.lastIndexOf('/') + 1);
// ── Name signals ────────────────────────────────────────────────
- if (nameLower === term) {
+ // A plural of the name is the name: `integration` is the `integrations`
+ // guides, `tab` the `tabs` doc.
+ // A component, hook, or template name typed as words is its name:
+ // `command palette` is CommandPalette. A doc's name is a route or key,
+ // matched as written.
+ const spelled =
+ domain !== 'doc' &&
+ !/[\s_-]/.test(nameLower) &&
+ nameLower === term.replace(/\s+/g, '');
+ if (nameLower === term || leafLower === term || spelled) {
consider(100, 'exact name');
+ } else if (pluralOf(nameLower, term) || pluralOf(term, nameLower)) {
+ // One point under the exact spelling, so the doc named `tokens` still
+ // outranks the Token component for `tokens`.
+ consider(99, 'plural of the name');
} else {
if (sameWord(term, nameLower)) consider(95, `name "${name}"`);
// The term is a word of the name, or starts one: "input" in TextInput.
@@ -962,11 +1160,14 @@ async function gatherDocs(cwd) {
keywords: [
node.route.slice(node.route.lastIndexOf('/') + 1),
...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),
+ // A namespace doc's own keywords, which it declares for search.
+ ...(Array.isArray(node.keywords) ? node.keywords : []),
...defined,
...codeTerms({content}),
],
description: node.summary || '',
prose: sectionProse({title: node.title, content}),
+ titles: [node.title],
_topic: node.route,
_title: path.join(' › '),
_command: `astryx docs ${node.route}`,
@@ -1086,12 +1287,16 @@ function topicCandidates(
const sections = doc?.sections ?? [];
const docTitle = path || doc?.title || title || name;
const split = sections.length > 1;
+ // A placed guide also answers to its last route segment's words:
+ // `quick start` is cli/integrations/quick-start.
+ const leaf = name.slice(name.lastIndexOf('/') + 1);
/** @type {Candidate[]} */
const out = [
{
domain: 'doc',
name,
keywords: [
+ ...(leaf !== name ? [leaf.replaceAll('-', ' ')] : []),
...(doc?.title || title ? [doc?.title || title] : []),
...(Array.isArray(doc?.keywords) ? doc.keywords : []),
],
@@ -1099,6 +1304,11 @@ function topicCandidates(
prose: split
? sections.map(section => section.title).filter(Boolean)
: sections.flatMap(sectionProse),
+ titles: [
+ doc?.title || title || name,
+ // A topic read whole answers for the headings inside it.
+ ...(split ? [] : sections.flatMap(s => [s.title, ...headings(s)])),
+ ].filter(Boolean),
_topic: name,
_title: docTitle,
_command: split ? `astryx docs ${name} --index` : `astryx docs ${name}`,
@@ -1119,6 +1329,7 @@ function topicCandidates(
],
description: sectionSummary(section),
prose: sectionProse(section),
+ titles: [section.title, ...headings(section)].filter(Boolean),
_topic: name,
_section: key,
_title: `${docTitle} › ${section.title}`,
@@ -1296,10 +1507,11 @@ export async function search(query, options = {}) {
const tokens = tokenizeQuery(term);
// `astryx docs` reads docs without @astryxdesign/core, so a docs-only
- // search must too. Every other domain reads core.
+ // search must too. Every other domain reads core: asked for by name, it is
+ // an error without core; an open search then covers the docs alone.
const docsOnly = type === 'doc';
const coreDir = docsOnly ? null : findCoreDir(cwd);
- if (!docsOnly && !coreDir) {
+ if (type && !docsOnly && !coreDir) {
throw new AstryxError(
'Could not find @astryxdesign/core package',
undefined,
@@ -1309,7 +1521,7 @@ export async function search(query, options = {}) {
// Gather candidates from each requested domain in parallel.
/** @param {string} d */
- const wants = d => !type || type === d;
+ const wants = d => (!type && (coreDir != null || d === 'doc')) || type === d;
const [components, hooks, docTopics, templates] = await Promise.all([
wants('component')
? gatherComponents(/** @type {string} */ (coreDir), cwd)
diff --git a/packages/cli/api/search/search.test.mjs b/packages/cli/api/search/search.test.mjs
deleted file mode 100644
index 9f113c177c..0000000000
--- a/packages/cli/api/search/search.test.mjs
+++ /dev/null
@@ -1,530 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Colocated tests for the `search` leaf (api/search/search.mjs), run
- * against the real @astryxdesign/core registry. `search` had no api-level tests;
- * this locks the envelope, ranking invariants, the `--type`/limit handling, and
- * the error paths.
- *
- * The API validates its own inputs (not just the CLI): a non-positive/non-integer
- * `limit`, an empty query, and a bad `--type` all throw AstryxError with the
- * ERR_INVALID_ARGUMENT code, so a direct `@astryxdesign/cli/api` caller gets the
- * same contract as `astryx search` on the command line.
- *
- * The last describe block covers integration-contributed components, using the
- * same temp-consumer harness as template-integration.test.mjs. Before this,
- * `search`/`build` only ever scanned @astryxdesign/core — an integration's own
- * components were invisible to both, even though `component --list` and
- * `component <Name>` already resolved them. The two discovery paths silently
- * disagreed.
- */
-
-import {describe, it, expect} from 'vitest';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-import {
- search,
- scoreCandidate,
- scoreQuery,
- tokenizeQuery,
- SEARCH_DOMAINS,
-} from './search.mjs';
-
-const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
-const cwd = REPO;
-const SLOW = 30_000;
-
-describe('search leaf — envelope + ranking', () => {
- it('returns a `search` envelope with query + results', async () => {
- const r = await search('button', {cwd});
- expect(r.type).toBe('search');
- expect(r.data.query).toBe('button');
- expect(Array.isArray(r.data.results)).toBe(true);
- expect(r.data.results.length).toBeGreaterThan(0);
- }, SLOW);
-
- it('keeps tokenizer coverage out of the public result shape', async () => {
- const r = await search('table of contents', {cwd});
- expect(r.data.results.length).toBeGreaterThan(0);
- for (const result of r.data.results) {
- expect(result).not.toHaveProperty('matchedTerms');
- expect(result).not.toHaveProperty('queryTerms');
- }
- }, SLOW);
-
- it('returns an empty result set (not an error) for a no-match query', async () => {
- const r = await search('zzznomatch99', {cwd});
- expect(r.type).toBe('search');
- expect(r.data.results).toEqual([]);
- }, SLOW);
-
- it('defaults to at most 20 results', async () => {
- const r = await search('button', {cwd});
- expect(r.data.results.length).toBeLessThanOrEqual(20);
- }, SLOW);
-
- it('caps results to a positive limit', async () => {
- const r = await search('button', {cwd, limit: 2});
- expect(r.data.results.length).toBeLessThanOrEqual(2);
- }, SLOW);
-});
-
-describe('search leaf — per-domain result fields', () => {
- it('carries import for components and hooks, title for docs, displayName and kind for templates', async () => {
- const r = await search('theme', {cwd, limit: 60});
- expect(new Set(r.data.results.map(res => res.domain))).toEqual(
- new Set(SEARCH_DOMAINS),
- );
- for (const res of r.data.results) {
- expect(typeof res.command).toBe('string');
- expect(typeof res.description).toBe('string');
- if (res.domain === 'component' || res.domain === 'hook') {
- expect(res.import).toMatch(/\S/);
- } else if (res.domain === 'doc') {
- expect(res.title).toMatch(/\S/);
- const read = `astryx docs ${res.name}`;
- expect([read, `${read} --index`, `${read} ${res.section}`]).toContain(res.command);
- } else {
- expect(res.displayName).toMatch(/\S/);
- expect(['page', 'block']).toContain(res.kind);
- }
- }
- }, SLOW);
-});
-
-describe('search leaf — docs at the grain a reader reads them', () => {
- it(
- 'finds one section of a guide, and a docs-tree leaf by its own name',
- async () => {
- const guide = await search('codemod protected files', {cwd, type: 'doc'});
- expect(guide.data.results.slice(0, 3)).toContainEqual(
- expect.objectContaining({
- domain: 'doc',
- name: 'cli/integrations',
- section: 'codemods',
- title: 'Astryx CLI › CLI Integrations › Codemods',
- parent: 'astryx docs cli/integrations --index',
- command: 'astryx docs cli/integrations codemods',
- }),
- );
- const block = await search('token-ref', {cwd});
- expect(block.data.results[0]).toMatchObject({
- name: 'authoring',
- section: 'reference-doc',
- command: 'astryx docs authoring reference-doc',
- });
- const fn = await search('assertResponse', {cwd, type: 'doc'});
- expect(fn.data.results[0]).toMatchObject({
- name: 'cli/api/functions/assert-response',
- title: 'Astryx CLI › API › Functions › assertResponse()',
- parent: 'astryx docs cli/api/functions',
- command: 'astryx docs cli/api/functions/assert-response',
- });
- expect(fn.data.results[0]).not.toHaveProperty('section');
- },
- SLOW,
- );
-
- it(
- 'finds the component batch guide from task language',
- async () => {
- const result = await search('look up several components', {
- cwd,
- type: 'doc',
- });
- expect(result.data.results).toContainEqual(
- expect.objectContaining({
- name: 'cli/component-lookups',
- section: 'several',
- command: 'astryx docs cli/component-lookups several',
- }),
- );
- },
- SLOW,
- );
-
- it(
- 'gives a top-level namespace hit the topic list as its parent',
- async () => {
- for (const [query, route] of [['unorganized', 'unorganized'], ['Astryx CLI', 'cli']]) {
- const r = await search(query, {cwd, type: 'doc'});
- expect(r.data.results).toContainEqual(
- expect.objectContaining({
- name: route,
- command: `astryx docs ${route}`,
- parent: 'astryx docs',
- }),
- );
- }
- },
- SLOW,
- );
-
- it(
- 'points a topic hit at its index, never a whole-topic read',
- async () => {
- const r = await search('cli/integrations', {cwd, type: 'doc'});
- expect(r.data.results[0]).toMatchObject({
- name: 'cli/integrations',
- command: 'astryx docs cli/integrations --index',
- });
- expect(r.data.results[0]).not.toHaveProperty('section');
- },
- SLOW,
- );
-
- it(
- 'searches docs where @astryxdesign/core is not installed',
- async () => {
- const bare = fs.mkdtempSync(
- path.join(os.tmpdir(), 'astryx-search-bare-'),
- );
- try {
- const r = await search('assertResponse', {cwd: bare, type: 'doc'});
- expect(r.data.results[0].name).toBe(
- 'cli/api/functions/assert-response',
- );
- } finally {
- fs.rmSync(bare, {recursive: true, force: true});
- }
- },
- SLOW,
- );
-});
-
-describe('search leaf — matchCount is the total, not the cap', () => {
- it('reports every match while `results` stays bounded by the limit', async () => {
- // The regression: `matchCount` used to be `results.length`, so a query
- // matching 57 things reported 20 — the cap read back as the answer. Any
- // consumer counting matches (the recorded run, a caller paginating) then
- // could not tell a capped answer from an exactly-cap-sized one.
- const capped = await search('button', {cwd, limit: 2});
- expect(capped.data.results.length).toBe(2);
- expect(capped.data.matchCount).toBeGreaterThan(2);
-
- // Same query, no meaningful cap: the count is stable across limits, which
- // is what makes it a count of MATCHES rather than of what was returned.
- const full = await search('button', {cwd, limit: 500});
- expect(full.data.matchCount).toBe(capped.data.matchCount);
- expect(full.data.results.length).toBe(full.data.matchCount);
- }, SLOW);
-
- it('reports 0 for a no-match query', async () => {
- const r = await search('zzznomatch99', {cwd});
- expect(r.data.matchCount).toBe(0);
- }, SLOW);
-
- it('counts only the requested domain under --type', async () => {
- const all = await search('button', {cwd, limit: 500});
- const components = await search('button', {
- cwd,
- type: 'component',
- limit: 500,
- });
- expect(components.data.matchCount).toBe(components.data.results.length);
- expect(components.data.matchCount).toBeLessThanOrEqual(all.data.matchCount);
- }, SLOW);
-});
-
-describe('search leaf — --type filter', () => {
- it('restricts results to the requested domain', async () => {
- const r = await search('button', {cwd, type: 'component'});
- expect(r.data.results.every(x => x.domain === 'component')).toBe(true);
- }, SLOW);
-
- it('exposes the valid domain list', () => {
- expect(SEARCH_DOMAINS).toEqual(expect.arrayContaining(['component', 'hook', 'doc', 'template']));
- });
-});
-
-describe('search leaf — exact keyword phrase outranks incidental token matches (issue #5239)', () => {
- it('surfaces Outline for its own declared keyword "table of contents", ranked first', async () => {
- // Before the fix, "table" and "contents" each separately matched dozens
- // of unrelated Table-related templates by coincidence, and their
- // combined token-sum score outranked Outline's single exact match,
- // pushing it out of the results entirely at the default limit.
- const r = await search('table of contents', {cwd});
- expect(r.data.results[0]?.name).toBe('Outline');
- }, SLOW);
-
- it('surfaces Outline for its own declared keyword "heading navigation", ranked first', async () => {
- const r = await search('heading navigation', {cwd});
- expect(r.data.results[0]?.name).toBe('Outline');
- }, SLOW);
-
- it('preserves query coverage metadata on the promoted exact phrase', () => {
- const query = 'table of contents';
- const tokens = tokenizeQuery(query);
- expect(
- scoreQuery(query, tokens, {
- name: 'Outline',
- keywords: [query],
- }),
- ).toMatchObject({matched: tokens.length, total: tokens.length});
- });
-
- it('still returns no results for a nonsense query (the fix does not loosen matching)', async () => {
- const r = await search('zzzzqqqx', {cwd});
- expect(r.data.results).toEqual([]);
- }, SLOW);
-});
-
-describe('search leaf — error paths (pinned)', () => {
- it('throws ERR_INVALID_ARGUMENT when the query is empty/whitespace', async () => {
- await expect(search(' ', {cwd})).rejects.toMatchObject({
- code: 'ERR_INVALID_ARGUMENT',
- message: expect.stringMatching(/query is required/i),
- });
- }, SLOW);
-
- it('throws ERR_INVALID_ARGUMENT for an unknown --type', async () => {
- await expect(
- search('button', {cwd, type: /** @type {any} */ ('bogus')}),
- ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
- }, SLOW);
-
- it('throws ERR_CORE_NOT_FOUND when @astryxdesign/core cannot be found', async () => {
- const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-no-core-'));
- try {
- await expect(search('button', {cwd: empty})).rejects.toMatchObject({
- code: 'ERR_CORE_NOT_FOUND',
- });
- } finally {
- fs.rmSync(empty, {recursive: true, force: true});
- }
- }, SLOW);
-});
-
-describe('search leaf — limit validation (API matches the CLI contract)', () => {
- it('throws ERR_INVALID_ARGUMENT for a limit of 0 (no longer returns everything)', async () => {
- await expect(search('button', {cwd, limit: 0})).rejects.toMatchObject({
- code: 'ERR_INVALID_ARGUMENT',
- });
- }, SLOW);
-
- it('throws ERR_INVALID_ARGUMENT for a negative limit', async () => {
- await expect(search('button', {cwd, limit: -5})).rejects.toMatchObject({
- code: 'ERR_INVALID_ARGUMENT',
- });
- }, SLOW);
-
- it('throws ERR_INVALID_ARGUMENT for a non-integer limit', async () => {
- await expect(search('button', {cwd, limit: 2.5})).rejects.toMatchObject({
- code: 'ERR_INVALID_ARGUMENT',
- });
- }, SLOW);
-});
-
-describe('search leaf — integration components', () => {
- /**
- * A minimal consumer project: a stub `@astryxdesign/core` (so `findCoreDir`
- * resolves without needing the real package) plus an installed
- * `@acme/widgets` integration that contributes one component.
- */
- function makeConsumerWithIntegrationComponent() {
- const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-search-it-'));
- fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({name: 'consumer'}));
- fs.writeFileSync(
- path.join(dir, 'astryx.config.mjs'),
- `export default { integrations: ['@acme/widgets'] };\n`,
- );
-
- // Stub core: just needs to exist with an (empty) src/ so discoverComponents
- // doesn't throw. Its own component list is irrelevant to this test.
- const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
- fs.mkdirSync(path.join(coreDir, 'src'), {recursive: true});
-
- const widgetsDir = path.join(dir, 'node_modules', '@acme', 'widgets');
- fs.mkdirSync(path.join(widgetsDir, 'components'), {recursive: true});
- fs.writeFileSync(
- path.join(widgetsDir, 'package.json'),
- JSON.stringify({name: '@acme/widgets', version: '1.0.0'}),
- );
- fs.writeFileSync(
- path.join(widgetsDir, 'astryx.integration.mjs'),
- `export default { components: './components' };\n`,
- );
- fs.writeFileSync(
- path.join(widgetsDir, 'components', 'FancyGizmo.doc.mjs'),
- `export default {
- type: 'component',
- name: 'FancyGizmo',
- keywords: ['gizmo', 'widget'],
- usage: {description: 'A fancy gizmo widget.'},
- props: [],
- };\n`,
- );
- fs.writeFileSync(
- path.join(widgetsDir, 'components', 'FancyGizmo.tsx'),
- `export function FancyGizmo() { return null; }\n`,
- );
-
- return dir;
- }
-
- it('includes a component contributed by a configured integration', async () => {
- const dir = makeConsumerWithIntegrationComponent();
- try {
- const r = await search('gizmo', {cwd: dir, type: 'component'});
- expect(r.data.results.some(x => x.name === 'FancyGizmo')).toBe(true);
- } finally {
- fs.rmSync(dir, {recursive: true, force: true});
- }
- }, SLOW);
-
- it('reports the contributing package as the import hint', async () => {
- const dir = makeConsumerWithIntegrationComponent();
- try {
- const r = await search('FancyGizmo', {cwd: dir, type: 'component'});
- const hit = r.data.results.find(x => x.name === 'FancyGizmo');
- expect(hit?.import).toBe('@acme/widgets');
- } finally {
- fs.rmSync(dir, {recursive: true, force: true});
- }
- }, SLOW);
-});
-
-describe('search scoring — multi-token aggregation is monotonic', () => {
- /**
- * @param {string} q
- * @param {object} candidate
- * @returns {number}
- */
- const score = (q, candidate) => scoreQuery(q, tokenizeQuery(q), candidate)?.score ?? 0;
-
- it('ranks matching both terms above matching only the stronger one', () => {
- // The shipped regression: scoring averaged over MATCHED tokens, so the
- // weaker second hit pulled the mean down further than the coverage bonus
- // pushed it up. `build "file browser"` put two form wizards that matched
- // only "file" (98) above the actual file browser that matched both (97),
- // and 98 clears the confident-match gate.
- const partial = {name: 'form-wizard-vertical', keywords: ['file']};
- const complete = {
- name: 'file-explorer',
- keywords: ['file'],
- description: 'Column browser for nested folders',
- };
- expect(score('file browser', complete)).toBeGreaterThan(score('file browser', partial));
- });
-
- it('never scores a superset of matched terms below a subset', () => {
- const subset = {name: 'zzz-none', keywords: ['alpha']};
- const supersets = [
- {name: 'zzz-none', keywords: ['alpha'], description: 'beta things'},
- {name: 'zzz-none', keywords: ['alpha', 'beta']},
- {name: 'zzz-none', keywords: ['alpha'], weakKeywords: ['beta']},
- ];
- for (const superset of supersets) {
- expect(score('alpha beta', superset)).toBeGreaterThanOrEqual(score('alpha beta', subset));
- }
- });
-
- it('still scores a verbose prompt on the concepts it did hit', () => {
- // Guards the reason the mean was used: a long prompt matching one concept
- // strongly must not be crushed by dividing across every query token.
- const candidate = {name: 'kanban', keywords: ['kanban']};
- expect(score('i need a kanban somewhere in this rambling request', candidate))
- .toBeGreaterThanOrEqual(90);
- });
-});
-
-describe('search scoring — derived keywords rank below authored ones', () => {
- it('scores an authored keyword above a derived one', () => {
- const authored = scoreCandidate('dialog', {name: 'x', keywords: ['Dialog']});
- const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
- expect(authored?.score).toBe(90);
- expect(derived?.score).toBe(60);
- });
-
- it('keeps one incidental derived match below the confident-match gate', () => {
- // PAGE_DIRECT in api/build/kit is 95: at full keyword strength a page that
- // renders one of everything got a 90-point shot per component and was
- // returned as a confident match for queries it had nothing to do with.
- const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
- expect(derived?.score).toBeLessThan(95);
- });
-
- it('still surfaces a derived match above the page floor', () => {
- // PAGE_FLOOR is 50 — weakening the signal must not make it invisible.
- const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
- expect(derived?.score).toBeGreaterThanOrEqual(50);
- });
-
- it('explains a derived hit as something the template renders', () => {
- const derived = scoreCandidate('dialog', {name: 'x', weakKeywords: ['Dialog']});
- expect(derived?.reason).toMatch(/renders Dialog/);
- });
-});
-
-describe('search — usage guidance is indexed, a tier below description', () => {
- // The vocabulary a reader types usually lives in a component's guidance, not
- // in its one-line description. Banner calls itself "a persistent message";
- // only its best practices name "caution", "problems", "form errors". Before
- // this, none of those words found it.
- const banner = {
- name: 'Banner',
- keywords: ['alert', 'notification'],
- description: 'A persistent message shown above content.',
- guidance: [
- 'Pick a status that matches the message: info for updates, warning for caution.',
- 'Use error for problems the reader must resolve before continuing.',
- ],
- };
-
- it('finds a term that appears ONLY in guidance', () => {
- // Red before this change: guidance was never read, so this scored null.
- const hit = scoreCandidate('caution', banner);
- expect(hit).not.toBeNull();
- expect(hit?.reason).toMatch(/guidance mentions "caution"/);
- });
-
- it('scores guidance BELOW description, so a component about X outranks one that merely mentions X', () => {
- const own = scoreCandidate('persistent', banner);
- const mention = scoreCandidate('caution', banner);
- expect(own?.score).toBe(50);
- expect(mention?.score).toBe(45);
- expect(mention.score).toBeLessThan(own.score);
- });
-
- it('never lets guidance outrank a name or keyword hit', () => {
- expect(scoreCandidate('banner', banner)?.score).toBe(100);
- expect(scoreCandidate('notification', banner)?.score).toBe(90);
- });
-
- it('prefers the stronger signal when a term is in both description and guidance', () => {
- const both = scoreCandidate('message', banner);
- expect(both?.score).toBe(50);
- expect(both?.reason).toMatch(/description mentions/);
- });
-
- it('stays below MIN_TOKEN_SCORE, so guidance never counts as a matched CONCEPT', () => {
- // Measured regression this prevents: counting guidance as a matched term
- // moved `nested menu` from SideNav to List, and `explain why a field is
- // required` from Field to TextInput — in both cases a component whose
- // guidance happens to mention the other word displaced the real answer.
- // Guidance decides single-word queries; it must not win multi-word ones on
- // breadth. Same reason weakKeywords are capped.
- expect(scoreCandidate('caution', banner)?.score).toBeLessThan(50);
- // Both words are in this candidate's guidance and nowhere else, so if
- // guidance counted as a concept this would come back as a 2/2 match.
- const multi = scoreQuery('caution problems', tokenizeQuery('caution problems'), banner);
- expect(multi).toBeNull();
- });
-
- it('lets a real description hit still win the multi-word pass', () => {
- // The floor must exclude guidance without muting the tiers above it.
- const hit = scoreQuery('persistent message', tokenizeQuery('persistent message'), banner);
- expect(hit?.reason).toMatch(/matches 2\/2 terms/);
- });
-
- it('tolerates the object-shaped bestPractices entries core actually ships', () => {
- // Core writes `{guidance: true, description: '...'}`, not plain strings.
- const hit = scoreCandidate('resolve', {
- name: 'X',
- guidance: ['Use error for problems the reader must resolve.'],
- });
- expect(hit?.score).toBe(45);
- });
-});
diff --git a/packages/cli/api/swizzle/swizzle.doc.mjs b/packages/cli/api/swizzle/swizzle.doc.mjs
index 49993f08cc..c95c6c0898 100644
--- a/packages/cli/api/swizzle/swizzle.doc.mjs
+++ b/packages/cli/api/swizzle/swizzle.doc.mjs
@@ -29,17 +29,19 @@ export const doc = {
name: 'component',
type: 'string',
description:
- 'Bare or XDS-prefixed component name to copy. Omit to list the swizzlable components.',
+ "Component name to copy (e.g. 'Button'). Omit to list the swizzlable components.",
},
{
name: 'options.cwd',
type: 'string',
description: 'Directory to resolve @astryxdesign/core from.',
+ default: 'process.cwd()',
},
{
name: 'options.output',
type: 'string',
- description: 'Output directory; must resolve inside cwd.',
+ description:
+ 'Output directory, relative to cwd. An absolute path, or one that resolves outside cwd, throws ERR_PATH_TRAVERSAL.',
default: "'./components/astryx'",
},
{
@@ -71,7 +73,7 @@ export const doc = {
{
type: 'swizzle.copy',
description:
- 'A receipt after copying the component into the project: the component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer-feedback note.',
+ 'A receipt after copying the component into the project: the component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
},
],
throws: [
@@ -81,7 +83,7 @@ export const doc = {
},
{
code: 'ERR_PATH_TRAVERSAL',
- when: 'the component name contains a path separator or traversal, output resolves outside cwd, or an existing output file or directory is a symlink that resolves outside cwd',
+ when: 'the component name contains a path separator or traversal, output is absolute or resolves outside cwd, or an existing output file or directory is a symlink that resolves outside cwd',
},
{
code: 'ERR_UNKNOWN_COMPONENT',
@@ -108,7 +110,7 @@ export const doc = {
{label: 'Eject a component', code: "await swizzle('Button');"},
{
label: 'Disambiguate by package',
- code: "await swizzle('Button', {package: '@astryxdesign/core'});",
+ code: "await swizzle('Button', {package: '@astryxdesign/core', overwrite: true});",
},
{
label: 'Custom output directory',
diff --git a/packages/cli/api/template/copy/copy.mjs b/packages/cli/api/template/copy/copy.mjs
index e7cc0646eb..793f9b46f5 100644
--- a/packages/cli/api/template/copy/copy.mjs
+++ b/packages/cli/api/template/copy/copy.mjs
@@ -74,7 +74,7 @@ export function templateCopy(match, {targetPath, cwd, overwrite = false}) {
if (!overwrite && fs.existsSync(outputFilePath)) {
const rel = path.relative(cwd, outputFilePath) || outputFilePath;
throw new AstryxError(
- `Refusing to overwrite existing file ${rel}. Re-run with overwrite to replace it.`,
+ `Refusing to overwrite existing file ${rel}. Re-run with --overwrite (or -f) to replace it.`,
undefined,
ERROR_CODES.ERR_FILE_EXISTS,
);
diff --git a/packages/cli/api/template/copy/copy.test.mjs b/packages/cli/api/template/copy/copy.test.mjs
index d0189f1d83..176cea7b6a 100644
--- a/packages/cli/api/template/copy/copy.test.mjs
+++ b/packages/cli/api/template/copy/copy.test.mjs
@@ -35,6 +35,15 @@ describe('template.copy — overwrite + path safety', () => {
expect(fs.readFileSync(path.join(dir, 'mine.tsx'), 'utf-8')).toBe('USER CODE');
}, SLOW);
+ it('names the flag that replaces the file, as swizzle and theme add do', async () => {
+ fs.writeFileSync(path.join(dir, 'mine.tsx'), 'USER CODE');
+ await expect(
+ template('blank', {targetPath: './mine.tsx', cwd: dir}),
+ ).rejects.toThrow(
+ 'Refusing to overwrite existing file mine.tsx. Re-run with --overwrite (or -f) to replace it.',
+ );
+ }, SLOW);
+
it('overwrites when overwrite:true is passed', async () => {
fs.writeFileSync(path.join(dir, 'mine.tsx'), 'USER CODE');
const res = await template('blank', {targetPath: './mine.tsx', overwrite: true, cwd: dir});
diff --git a/packages/cli/api/template/template.doc.mjs b/packages/cli/api/template/template.doc.mjs
index d14ded4b05..d0643d233b 100644
--- a/packages/cli/api/template/template.doc.mjs
+++ b/packages/cli/api/template/template.doc.mjs
@@ -102,6 +102,7 @@ export const doc = {
type: 'string',
description:
'Directory to discover templates and resolve the target path from.',
+ default: 'process.cwd()',
},
],
returns: [
@@ -134,7 +135,7 @@ export const doc = {
throws: [
{
code: 'ERR_UNKNOWN_TEMPLATE',
- when: 'the named template does not exist, or --skeleton is run without a name',
+ when: 'the named template does not exist, or options.skeleton is set without a name',
},
{
code: 'ERR_AMBIGUOUS_TEMPLATE',
diff --git a/packages/cli/api/theme/generateTonalPalette.doc.mjs b/packages/cli/api/theme/generateTonalPalette.doc.mjs
index d33c478b82..6669de364b 100644
--- a/packages/cli/api/theme/generateTonalPalette.doc.mjs
+++ b/packages/cli/api/theme/generateTonalPalette.doc.mjs
@@ -29,7 +29,7 @@ export const doc = {
name: 'input',
type: 'TonalPaletteGenerationInput',
description:
- 'Families and seeds plus optional modes, shared stops, anchors, vibrancy from 0 to 100 (default 50), and neutral profile. Only generate an accent family when one is explicitly requested; clarify whether an ambiguous accent means one theme value or a tonal family.',
+ 'Families and seeds plus optional modes, shared stops, anchors, vibrancy from 0 to 100 (default 50), and neutral profile.',
required: true,
},
],
@@ -72,6 +72,5 @@ export const doc = {
code: "generateTonalPalette({stops: [12.5, 50], families: [{id: 'blue', seed: '#0074e2'}]});",
},
],
- command: 'theme palette generate',
related: ['themePaletteGenerate'],
};
diff --git a/packages/cli/api/theme/listThemes.doc.mjs b/packages/cli/api/theme/listThemes.doc.mjs
index 07c7e8f9b1..cfbc1d07f2 100644
--- a/packages/cli/api/theme/listThemes.doc.mjs
+++ b/packages/cli/api/theme/listThemes.doc.mjs
@@ -13,7 +13,7 @@ export const doc = {
displayName: 'listThemes()',
summary: 'Read the CLI bundled-theme descriptors.',
description:
- 'Reads the typed same-stem descriptors under templates/themes and returns normalized entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
+ "Synchronously returns the themes bundled with the CLI, including each one's entry file, export name and file list. Bundled themes only; use themeListAvailable() to include themes from installed integrations.",
importPath: '@astryxdesign/cli/api',
signature: 'listThemes(): BundledTheme[]',
keywords: ['theme', 'themes', 'descriptor', 'bundled', 'adapter', 'list'],
diff --git a/packages/cli/api/theme/themeAdd.doc.mjs b/packages/cli/api/theme/themeAdd.doc.mjs
index 18606793aa..597d0df8bc 100644
--- a/packages/cli/api/theme/themeAdd.doc.mjs
+++ b/packages/cli/api/theme/themeAdd.doc.mjs
@@ -44,6 +44,7 @@ export const doc = {
type: 'string',
description:
'Project directory used for integration discovery and target paths.',
+ default: 'process.cwd()',
},
{
name: 'options.package',
@@ -57,11 +58,6 @@ export const doc = {
description:
'Copy receipt with slug, displayName, maintained flag, owner package, outputDir, entry, exportName, and files.',
},
- {
- type: 'theme.list',
- description:
- 'The CLI list affordance routes a bare `astryx theme add` or `--list` to themeListAvailable() and returns every available theme with its owner.',
- },
],
throws: [
{
@@ -74,7 +70,10 @@ export const doc = {
when: 'the selected installed package has a blocking integration or theme-descriptor error',
},
{code: 'ERR_PATH_TRAVERSAL', when: 'the target path escapes cwd'},
- {code: 'ERR_NO_SOURCE', when: 'a theme file to copy is missing'},
+ {
+ code: 'ERR_NO_SOURCE',
+ when: 'the bundled theme descriptors cannot be read, or a theme file to copy is missing',
+ },
{
code: 'ERR_FILE_EXISTS',
when: 'a destination exists and overwrite is not set',
@@ -82,12 +81,12 @@ export const doc = {
{code: 'ERR_WRITE_FAILED', when: 'writing files fails'},
],
examples: [
- {label: 'Copy a bundled theme', code: "await themeAdd('ocean');"},
+ {label: 'Copy a bundled theme', code: "await themeAdd('butter');"},
{
- label: 'Copy an integration theme',
- code: "await themeAdd('ocean', {package: '@acme/themes'});",
+ label: 'Name the owner package and the destination',
+ code: "await themeAdd('butter', {package: '@astryxdesign/cli', targetPath: 'src/brand-theme'});",
},
],
command: 'theme add',
- related: ['themeList', 'listThemes'],
+ related: ['themeListAvailable', 'themeTemplate', 'listThemes'],
};
diff --git a/packages/cli/api/theme/themeBuild.doc.mjs b/packages/cli/api/theme/themeBuild.doc.mjs
index e3bf88f27e..99966aadc7 100644
--- a/packages/cli/api/theme/themeBuild.doc.mjs
+++ b/packages/cli/api/theme/themeBuild.doc.mjs
@@ -14,14 +14,13 @@ export const doc = {
name: 'themeBuild',
namespace: 'cli/api',
displayName: 'themeBuild()',
- summary: 'Compile a defineTheme file to CSS + JS + type declarations.',
+ summary:
+ 'Compile a defineTheme() file to scoped CSS, a JS module, and type declarations, or check committed outputs for drift in CI.',
description:
- 'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and, ' +
- "via @astryxdesign/core's shared generator (the single source of truth, so the build " +
- 'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
- 'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
- 'theme adds custom prop values). When another build step emits the icon registry, ' +
- '{iconsSpecifier} declares the fully specified module path for the generated JS import. ' +
+ 'The compiler behind `astryx theme build`. Reads a file that calls defineTheme() and ' +
+ 'writes a scoped CSS file, a JS module that re-exports the built theme, and a .d.ts ' +
+ '(plus an optional .variants.d.ts when the theme adds custom prop values). It uses ' +
+ "@astryxdesign/core's own generator, so the CSS matches what the <Theme> runtime emits. " +
'With {check: true} it writes nothing and instead compares ' +
'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
importPath: '@astryxdesign/cli/api',
@@ -48,7 +47,7 @@ export const doc = {
name: 'options.out',
type: 'string',
description:
- 'Override the output CSS path; the sibling .js and .d.ts derive from it. A relative path must stay within cwd.',
+ 'Override the output CSS path. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file. A relative path must stay within cwd.',
},
{
name: 'options.check',
@@ -61,13 +60,14 @@ export const doc = {
name: 'options.iconsSpecifier',
type: 'string',
description:
- 'Override the icon-registry import specifier in the generated JS module, for example ./icons.mjs. When omitted, the source specifier is preserved.',
+ 'Override the import specifier of the icon registry in the generated JS module, for example ./icons.mjs. Takes effect only when the theme sets icons: to a named import; when omitted, the source specifier is kept.',
},
{
name: 'ctx.cwd',
type: 'string',
description:
- 'Directory the theme file and @astryxdesign/core resolve against.',
+ 'Directory the theme file, a relative out path, and the returned output paths resolve against.',
+ default: 'process.cwd()',
},
],
returns: [
@@ -79,7 +79,7 @@ export const doc = {
{
type: 'theme.build.check',
description:
- 'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing.',
+ 'The {check: true} receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: "missing" | "outdated"}), and the full list of checked paths. Writes nothing. Resolves to null, like a normal build, when the theme produces no CSS.',
},
],
throws: [
@@ -102,7 +102,7 @@ export const doc = {
},
{
code: 'ERR_CORE_INCOMPATIBLE',
- when: 'the selected theme carries ordered-adaptation intent but the installed @astryxdesign/core does not export generateAdaptationCSS (upgrade core)',
+ when: 'the installed @astryxdesign/core does not export generateAdaptationCSS and the theme either declares ordered adaptations or has lineage whose adaptation use could not be observed (upgrade core)',
},
{
code: 'ERR_WRITE_FAILED',
@@ -124,5 +124,5 @@ export const doc = {
},
],
command: 'theme build',
- related: ['themeAdd', 'themeList', 'listThemes'],
+ related: ['themeTemplate', 'themeAdd', 'themeListAvailable', 'listThemes'],
};
diff --git a/packages/cli/api/theme/themeList.doc.mjs b/packages/cli/api/theme/themeList.doc.mjs
index 65e54a501a..4ab0d809a4 100644
--- a/packages/cli/api/theme/themeList.doc.mjs
+++ b/packages/cli/api/theme/themeList.doc.mjs
@@ -13,7 +13,7 @@ export const doc = {
displayName: 'themeList()',
summary: 'List themes bundled with this CLI build.',
description:
- 'Projects the bundled typed theme descriptors into a synchronous theme.list envelope. This preserves the original programmatic API contract. The CLI command uses themeListAvailable() so installed integrations also appear.',
+ 'Synchronous list of the themes bundled with the CLI. It does not include themes from installed integrations; use themeListAvailable() for the list `astryx theme list` shows.',
importPath: '@astryxdesign/cli/api',
signature: 'themeList(): ThemeListResponse',
keywords: ['theme', 'list', 'themes', 'bundled', 'available'],
diff --git a/packages/cli/api/theme/themeListAvailable.doc.mjs b/packages/cli/api/theme/themeListAvailable.doc.mjs
index b3cdca0311..3607900a08 100644
--- a/packages/cli/api/theme/themeListAvailable.doc.mjs
+++ b/packages/cli/api/theme/themeListAvailable.doc.mjs
@@ -13,7 +13,7 @@ export const doc = {
displayName: 'themeListAvailable()',
summary: 'List bundled and installed integration themes.',
description:
- 'Loads Project for the requested directory, combines the CLI bundle with source themes from installed integrations, and projects each entry with its owner package. An unreadable project configuration degrades to the bundled descriptors.',
+ 'Lists the bundled themes plus source themes from integrations installed in cwd, each with its owner package. If the project configuration cannot be read, it falls back to the bundled themes.',
importPath: '@astryxdesign/cli/api',
signature:
'themeListAvailable(options?: {cwd?: string, package?: string}): Promise<ThemeListResponse>',
@@ -24,6 +24,7 @@ export const doc = {
type: 'string',
description:
'Project directory whose installed integrations contribute themes.',
+ default: 'process.cwd()',
},
{
name: 'options.package',
diff --git a/packages/cli/api/theme/themePaletteGenerate.doc.mjs b/packages/cli/api/theme/themePaletteGenerate.doc.mjs
index 2d6344f0b7..ac84eacbd6 100644
--- a/packages/cli/api/theme/themePaletteGenerate.doc.mjs
+++ b/packages/cli/api/theme/themePaletteGenerate.doc.mjs
@@ -27,30 +27,34 @@ export const doc = {
{
name: 'configPath',
type: 'string',
- description: 'JSON generation request, resolved within cwd.',
+ description:
+ 'Path to a JSON file holding a TonalPaletteGenerationInput (the object generateTonalPalette() takes), resolved within cwd.',
required: true,
},
{
name: 'options.out',
type: 'string',
description:
- 'Optional candidate JSON destination. A sibling .receipt.json path is derived from it.',
+ 'Where to write the candidate: a path ending in .ts (a TypeScript module) or .json. A sibling <name>.receipt.json is written next to it.',
},
{
name: 'options.preview',
type: 'string',
- description: 'Optional path for a self-contained HTML review artifact.',
+ description:
+ 'Optional path, ending in .html, for a self-contained HTML review page.',
},
{
name: 'options.overwrite',
type: 'boolean',
- description: 'Replace existing candidate and receipt files.',
+ description:
+ "Replace existing candidate, receipt and preview files. Without it, if any target exists, nothing is written and the result has written: false, reason: 'exists'.",
default: 'false',
},
{
name: 'ctx.cwd',
type: 'string',
description: 'Directory used to resolve the input and output paths.',
+ default: 'process.cwd()',
},
],
returns: [
@@ -64,17 +68,20 @@ export const doc = {
{code: 'ERR_FILE_NOT_FOUND', when: 'the config file does not exist'},
{
code: 'ERR_PALETTE_GENERATION',
- when: 'the request, seed, stop layout, mode, or anchor constraint is invalid',
+ when: 'the config is not valid JSON; the request, seed, stop layout, mode or anchor is invalid; out does not end in .ts or .json; or preview does not end in .html',
},
{
code: 'ERR_PATH_TRAVERSAL',
when: 'an input or output path escapes cwd, or output would replace input',
},
- {code: 'ERR_WRITE_FAILED', when: 'the candidate pair cannot be written'},
+ {
+ code: 'ERR_WRITE_FAILED',
+ when: 'the candidate, receipt or preview file cannot be written',
+ },
],
examples: [
{
- label: 'Preview a candidate',
+ label: 'Generate a candidate without writing files',
code: "themePaletteGenerate('palette.config.json');",
},
{
@@ -83,5 +90,5 @@ export const doc = {
},
],
command: 'theme palette generate',
- related: ['themeBuild', 'themeTemplate'],
+ related: ['generateTonalPalette', 'themeBuild', 'themeTemplate'],
};
diff --git a/packages/cli/api/theme/themeTargets.doc.mjs b/packages/cli/api/theme/themeTargets.doc.mjs
index d280abec24..b7969ab5e8 100644
--- a/packages/cli/api/theme/themeTargets.doc.mjs
+++ b/packages/cli/api/theme/themeTargets.doc.mjs
@@ -22,7 +22,7 @@ export const doc = {
'Same source as the Theming table `astryx component <Name>` prints ' +
'(the component docs), so the list cannot drift from the components, and `theme build` ' +
'validates overrides against this exact set. A filter naming a component gives that ' +
- "component's set; anything else is a substring search over the keys.",
+ "component's set; anything else is a case-insensitive substring search over each target's key, class and component.",
importPath: '@astryxdesign/cli/api',
signature:
'themeTargets(filter?: string, ctx?: {cwd?: string}): Promise<ThemeTargetsResponse>',
@@ -41,13 +41,14 @@ export const doc = {
name: 'filter',
type: 'string',
description:
- 'A component name (exact, case-insensitive) or a substring of a target key. Omit for the whole surface.',
+ 'A component name (exact, case-insensitive), or a substring of a target key, class or component. Omit for the whole surface.',
},
{
name: 'ctx.cwd',
type: 'string',
description:
"Directory the project's @astryxdesign/core is resolved from.",
+ default: 'process.cwd()',
},
],
returns: [
diff --git a/packages/cli/api/theme/themeTemplate.doc.mjs b/packages/cli/api/theme/themeTemplate.doc.mjs
index 984cb5d329..2f89901025 100644
--- a/packages/cli/api/theme/themeTemplate.doc.mjs
+++ b/packages/cli/api/theme/themeTemplate.doc.mjs
@@ -43,6 +43,7 @@ export const doc = {
name: 'options.cwd',
type: 'string',
description: 'Directory the target path resolves against.',
+ default: 'process.cwd()',
},
],
returns: [
@@ -64,5 +65,5 @@ export const doc = {
},
],
command: 'theme template',
- related: ['themeAdd', 'themeBuild', 'themeList'],
+ related: ['themeAdd', 'themeBuild', 'themeListAvailable', 'themeTargets'],
};
diff --git a/packages/cli/api/upgrade/upgrade.doc.mjs b/packages/cli/api/upgrade/upgrade.doc.mjs
index 16e0bef762..e9f0971e9d 100644
--- a/packages/cli/api/upgrade/upgrade.doc.mjs
+++ b/packages/cli/api/upgrade/upgrade.doc.mjs
@@ -13,19 +13,16 @@ export const doc = {
name: 'upgrade',
namespace: 'cli/api',
displayName: 'upgrade()',
- summary: 'Run version migrations and reconcile copied compositions.',
+ summary:
+ 'After bumping @astryxdesign/core, migrate project source with codemods and update copied compositions.',
description:
- 'Migrates project source from a previous Astryx version to the currently ' +
- 'installed one by running the registered codemods, and compares the fully ' +
- 'rendered managed agent-docs block on every migration path, including ' +
- 'same-Core integration guidance changes; list and registry-only modes do not ' +
- 'run migration reconciliation. Dry-run previews without writing; `apply` ' +
- 'writes the prepared block only after selected codemods and hooks succeed. ' +
- 'Core codemods run before ' +
- 'the config is loaded so a config codemod can repair an otherwise-invalid ' +
- 'astryx.config. Copied compositions carry adjacent receipts with exact canonical and format-specific install bases; upgrade ' +
- 'compares those installed bases with the matching registry release, updates pristine ' +
- 'files, merges non-overlapping edits, and leaves conflicting originals untouched.',
+ 'Runs the codemods between `from` and the installed Core version, then refreshes the ' +
+ 'managed agent-docs block. Dry-run by default; `apply` writes changes only after the ' +
+ 'selected codemods and hooks succeed. Config codemods run before astryx.config is ' +
+ 'loaded, so they can repair an invalid config. Also updates copied compositions from ' +
+ 'their install receipts: unchanged files are updated, non-overlapping edits are merged, ' +
+ 'and conflicts are left untouched. `list` only lists codemods; `registry` only updates ' +
+ 'copied compositions.',
importPath: '@astryxdesign/cli/api',
signature:
'upgrade(options?: UpgradeOptions, ctx?: {cwd?: string}): Promise<UpgradeListResponse | UpgradeRegistryResponse | UpgradeStatusResponse | UpgradeRunResponse>',
@@ -42,7 +39,7 @@ export const doc = {
name: 'options.from',
type: 'string',
description:
- 'Version before the dependency bump. Required unless `list` or `registry` is set.',
+ 'Version before the dependency bump; the target is the installed @astryxdesign/core (or legacy @xds/core). Required unless `list` or `registry` is set.',
},
{
name: 'options.apply',
@@ -55,11 +52,13 @@ export const doc = {
type: 'boolean',
description:
'Run codemods even when `from` is at/after the installed version.',
+ default: 'false',
},
{
name: 'options.codemod',
type: 'string',
- description: 'Run a single named transform instead of the full set.',
+ description:
+ 'Run only this codemod. Optional codemods run only when named here. Setting it also skips copied-composition reconciliation.',
},
{
name: 'options.skipCodemod',
@@ -83,23 +82,26 @@ export const doc = {
type: 'boolean',
description:
'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',
+ default: 'false',
},
{
name: 'options.registry',
type: 'boolean',
description:
- 'Reconcile copied compositions from their install receipts without requiring `from`.',
+ 'Only reconcile copied compositions from their install receipts; `from` is not required. Cannot be combined with `list`, `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`.',
default: 'false',
},
{
name: 'options.list',
type: 'boolean',
description: 'Return the available codemods instead of running any.',
+ default: 'false',
},
{
name: 'ctx.cwd',
type: 'string',
description: 'Directory to run the upgrade in.',
+ default: 'process.cwd()',
},
],
returns: [
@@ -116,36 +118,36 @@ export const doc = {
{
type: 'upgrade.status',
description:
- 'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). Each carries the agent-docs summary and, when found, the copied-composition registry summary.',
+ 'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary.',
},
{
type: 'upgrade.run',
description:
- 'The terminal run receipt: from/to versions, codemod count, integrations processed, agent-docs and registry summaries, modifiedFiles, protectedFiles, declinedCandidates, and completion state. A protected required change returns complete: false with ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
+ 'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
},
],
throws: [
{
code: 'ERR_INVALID_ARGUMENT',
- when: '`from` is missing (and neither `list` nor `registry` is set), or the project config fails strict validation and no pending config codemod can repair it',
+ when: '`from` is missing (and neither `list` nor `registry` is set); `list` and `registry` are both set; `registry` is combined with `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`; an `integration` specifier is invalid or not installed; or astryx.config fails to load or validate and no pending config codemod repairs it',
},
{code: 'ERR_INVALID_VERSION', when: '`from` is not a valid semver string'},
{code: 'ERR_PATH_TRAVERSAL', when: '`path` resolves outside cwd'},
{
code: 'ERR_VERSION_DETECT',
- when: 'the installed @astryxdesign/core version cannot be detected',
+ when: 'neither @astryxdesign/core nor legacy @xds/core is installed in cwd; with `registry`, only when copied-composition receipts exist and @astryxdesign/core is not installed',
},
{
code: 'ERR_DEP_MISSING',
- when: 'jscodeshift is required but could not be installed',
+ when: 'jscodeshift is missing and `installDeps` is not set, or installing it failed',
},
{
code: 'ERR_UNKNOWN_CODEMOD',
- when: 'a `codemod` name matches no registered codemod',
+ when: 'the version range has codemods but none remain selected: `codemod` names no codemod in the range, or `skipCodemod` excludes all of them',
},
{
code: 'ERR_CODEMOD_FAILED',
- when: 'one or more codemods failed, or a post-codemod hook failed',
+ when: 'one or more codemods failed, or a post-codemod hook failed, and no protected file still needs a change (otherwise an upgrade.run receipt with complete: false is returned)',
},
{
code: 'ERR_CODEMOD_PROTECTION_SOURCE',
diff --git a/packages/cli/assets/docs/README.md b/packages/cli/assets/docs/README.md
index 6d5445aca1..4d8a96be36 100644
--- a/packages/cli/assets/docs/README.md
+++ b/packages/cli/assets/docs/README.md
@@ -21,13 +21,15 @@ Someone building a product with Astryx. Their questions:
## Tells that you are writing for us instead
- second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
-- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- an internal rubric, readiness gate, audit checklist, or sign-off that the reader must satisfy for Astryx maintainers
- a table of things to verify rather than things to use
- anything about lab → core, which is our lifecycle, not theirs
- Storybook, Playwright, CI or the Simulator named as tools the reader runs
One subtlety: a statement about the **system's behavior** is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — **rewrite it rather than move it**.
+A public authoring-quality rubric is also caller-facing when it helps someone evaluate an artifact they create through Astryx. It must be complete and actionable from public inputs. It must not include Astryx's internal approval, promotion, evidence-publication, or CI process. A current system spec must assign the shipped guide as the rubric's owner.
+
## Where the rest goes
The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/wiki) — **as a section on the page that already covers it, not a new page.** The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
@@ -55,5 +57,5 @@ Worked example: a responsive-and-interaction readiness rubric is grading criteri
one section by its key. A section's key is its `id`, or a key derived from its
title when it has none. Give a section an `id` when its title may change, since
readers and extensions link to the key. Two sections in one topic cannot share
-a key. Keep each section small enough to read on its own: `astryx doctor` fails
+a key. Keep each section small enough to read on its own: `astryx doctor` warns on
any section over 32 KB.
diff --git a/packages/cli/assets/docs/browser-support.doc.mjs b/packages/cli/assets/docs/browser-support.doc.mjs
index b5f922e558..69d8b78682 100644
--- a/packages/cli/assets/docs/browser-support.doc.mjs
+++ b/packages/cli/assets/docs/browser-support.doc.mjs
@@ -73,7 +73,7 @@ export const docs = {
'Baseline 2026: the tightest requirement.',
],
[
- '[`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
+ '`Popover` API',
'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
'Baseline 2025.',
],
@@ -86,7 +86,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'The gap that matters is between Tier 1 and Tier 2: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
+ text: 'The gap that matters is between Tier 1 and Tier 2: the `Popover` API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
},
],
},
@@ -95,24 +95,24 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'The browser requirement is concentrated in the layered-surface components: anything that renders content in an overlay positioned against a trigger:',
+ text: 'Any component that opens a menu, popover, tooltip, or dropdown carries the browser requirement: it renders that surface in an overlay positioned against its trigger. That includes:',
},
{
type: 'list',
style: 'unordered',
items: [
- 'Tooltip',
- 'HoverCard',
- 'Popover',
- 'ContextMenu',
- 'Selector and MultiSelector (dropdown surfaces)',
+ 'Tooltip, HoverCard, and Popover, and any prop that shows one (such as the Button `tooltip`)',
+ 'DropdownMenu, MoreMenu, and ContextMenu',
+ 'Selector, MultiSelector, ComplexSelector, Typeahead, and PowerSearch (dropdown surfaces)',
+ 'DateInput, DateRangeInput, and DateTimeInput (calendar popovers)',
'Tokenizer (suggestion menu)',
+ 'The overflow and flyout menus in Breadcrumbs, TabList, TopNav, and SideNav',
'Carousel (anchored controls)',
],
},
{
type: 'prose',
- text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+ text: 'If your product opens no menus, popovers, tooltips, or dropdowns, it has no anchor-positioning requirement; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, and tables work down to Tier 2 with no special handling.',
},
],
},
@@ -123,7 +123,7 @@ export const docs = {
type: 'list',
style: 'do',
items: [
- 'Components never throw on missing platform APIs. Where a browser lacks the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
+ 'Components never throw on missing platform APIs. Where a browser lacks the `Popover` API, layers fall back to plain visibility instead of crashing.',
'Tier 1 and Tier 2 are officially supported and tested.',
'Non-layered components render correctly down to Tier 2.',
],
@@ -192,7 +192,7 @@ const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
},
{
type: 'prose',
- text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+ text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the `Popover` API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
},
],
},
diff --git a/packages/cli/assets/docs/color.doc.mjs b/packages/cli/assets/docs/color.doc.mjs
index 0810137713..8a992c73ca 100644
--- a/packages/cli/assets/docs/color.doc.mjs
+++ b/packages/cli/assets/docs/color.doc.mjs
@@ -22,7 +22,8 @@ export const docs = {
],
},
{
- title: 'Surface Colors',
+ id: 'surface-colors',
+ title: 'Color Tokens',
category: 'foundations',
content: [
{
@@ -37,9 +38,14 @@ export const docs = {
],
},
{
- title: 'Usage',
+ id: 'usage',
+ title: 'Use color tokens in StyleX',
category: 'foundations',
content: [
+ {
+ type: 'prose',
+ text: 'Import the typed color tokens and use them in `stylex.create()`; they resolve to the active theme and color mode.',
+ },
{
type: 'code',
lang: 'tsx',
diff --git a/packages/cli/assets/docs/elevation.doc.mjs b/packages/cli/assets/docs/elevation.doc.mjs
index 845e839cca..131dda88aa 100644
--- a/packages/cli/assets/docs/elevation.doc.mjs
+++ b/packages/cli/assets/docs/elevation.doc.mjs
@@ -82,7 +82,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',
+ text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, ToggleButton, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',
},
{
type: 'prose',
@@ -92,11 +92,13 @@ export const docs = {
type: 'code',
lang: 'tsx',
label: 'Raising a surface with the elevation prop',
- code: `// Flat by default; raise only when the surface needs to float.
+ code: `import {Plus} from 'lucide-react';
+
+// Flat by default; raise only when the surface needs to float.
<Card elevation="low">Raised card</Card>
// A floating action button.
-<IconButton icon={<Icon icon="add" />} label="New" variant="primary" elevation="med" />
+<IconButton icon={<Icon icon={Plus} />} label="New" variant="primary" elevation="med" />
// Flatten the composer (defaults to 'low').
<ChatComposer elevation="none" onSubmit={handleSubmit} />`,
@@ -119,7 +121,7 @@ export const docs = {
type: 'code',
lang: 'tsx',
label: 'Applying elevation',
- code: `import {shadowVars} from '@astryxdesign/core';
+ code: `import {shadowVars} from '@astryxdesign/core/theme/tokens.stylex';
const styles = stylex.create({
dropdown: {
diff --git a/packages/cli/assets/docs/getting-started.doc.mjs b/packages/cli/assets/docs/getting-started.doc.mjs
index 65de63e884..e24dc6218d 100644
--- a/packages/cli/assets/docs/getting-started.doc.mjs
+++ b/packages/cli/assets/docs/getting-started.doc.mjs
@@ -8,6 +8,7 @@ export const docs = {
category: 'guide',
description:
'Add the design system to your project and start building.',
+ keywords: ['quick start', 'setup', 'install'],
sections: [
{
@@ -81,24 +82,11 @@ export const docs = {
},
{
type: 'prose',
- text: 'Available themes:',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- '`@astryxdesign/theme-neutral`: muted and minimal; a good starting point',
- '`@astryxdesign/theme-butter`: warm, golden tones with blue accents',
- '`@astryxdesign/theme-chocolate`: rich chocolate and caramel tones',
- '`@astryxdesign/theme-gothic`: dark-only theme with ink and noir influences',
- '`@astryxdesign/theme-matcha`: earthy greens and botanical tones',
- '`@astryxdesign/theme-stone`: warm neutrals inspired by sandstone',
- '`@astryxdesign/theme-y2k`: playful early-2000s pop aesthetic',
- ],
+ text: 'Run `astryx theme list` to see every theme.',
},
{
type: 'prose',
- text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in {@link generic:migration} before building screens.',
+ text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. Before building screens, read the two cascade layer sections of {@link generic:migration}.',
},
{
type: 'prose',
@@ -135,7 +123,7 @@ export default function Page() {
content: [
{
type: 'prose',
- text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](/docs/styling) for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
+ text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See {@link generic:styling} for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
},
{
type: 'code',
@@ -167,6 +155,7 @@ const overrides = stylex.create({
['Next.js + Tailwind', 'Next.js + Tailwind bridge', '[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)'],
['Next.js Source', 'Next.js importing from source', '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)'],
['Vite', 'Vite', '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)'],
+ ['Vite + Tailwind', 'Vite + Tailwind bridge', '[apps/example-vite-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-vite-tailwind)'],
],
},
{
diff --git a/packages/cli/assets/docs/icons.doc.mjs b/packages/cli/assets/docs/icons.doc.mjs
index 4ffa6326de..aaf5dbbc1d 100644
--- a/packages/cli/assets/docs/icons.doc.mjs
+++ b/packages/cli/assets/docs/icons.doc.mjs
@@ -73,7 +73,7 @@ export const docs = {
import { HeartIcon } from 'lucide-react';
<Icon icon={PhotoIcon} size="lg" />
-<Icon icon={HeartIcon} color="negative" />`,
+<Icon icon={HeartIcon} color="error" />`,
},
],
},
@@ -128,26 +128,7 @@ export const brandTheme = defineTheme({
},
{
type: 'prose',
- text: 'Ship the fallback in `defaultIcons` under the same key so the glyph still renders with no theme, or pass one to `getExtendedIcon(key, fallback)` when the icon lives outside core.',
- },
- ],
- },
- {
- title: 'Adding New Icons',
- category: 'foundations',
- content: [
- {
- type: 'prose',
- text: 'To add a new semantic icon name to the design system, only for a glyph the whole system shares; a component-owned one takes a namespaced key instead:',
- },
- {
- type: 'list',
- style: 'ordered',
- items: [
- 'Add the name to IconName type in `packages/core/src/Icon/globalIconRegistry.tsx`',
- 'Add the default SVG to `packages/core/src/Icon/defaultIcons.tsx`',
- 'Add a row to the Available Names table in `packages/cli/assets/docs/icons.doc.mjs`',
- ],
+ text: 'Outside core, pass a fallback to `getExtendedIcon(key, fallback)` so the glyph renders with no theme.',
},
],
},
diff --git a/packages/cli/assets/docs/illustrations.doc.mjs b/packages/cli/assets/docs/illustrations.doc.mjs
index 63b210c846..98491686b9 100644
--- a/packages/cli/assets/docs/illustrations.doc.mjs
+++ b/packages/cli/assets/docs/illustrations.doc.mjs
@@ -7,6 +7,7 @@ export const docs = {
category: 'foundations',
description:
'Illustration guidelines for empty states, onboarding flows, and feature highlights.',
+ keywords: ['empty state'],
sections: [
{
@@ -59,26 +60,17 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Place illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
+ text: 'For an empty state, pass the illustration to the `icon` slot of `EmptyState`, which centers it above the title and description. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a title and a description that says what to do next.',
},
{
type: 'code',
lang: 'tsx',
label: 'Empty state with illustration',
- code: `<Center>
- <Stack direction="vertical" gap={3} hAlign="center">
- <img
- src="/illustrations/empty-search.svg"
- alt="No results"
- style={{ width: 200, height: 200 }}
- />
- <Heading level={3}>No results found</Heading>
- <Text type="body" color="secondary">
- Try adjusting your search or filters to find what you\u2019re
- looking for.
- </Text>
- </Stack>
-</Center>`,
+ code: `<EmptyState
+ icon={<img src="/illustrations/empty-search.svg" alt="" width={200} height={200} />}
+ title="No results found"
+ description="Try adjusting your search or filters."
+/>`,
},
],
},
diff --git a/packages/cli/assets/docs/layout.doc.dense.mjs b/packages/cli/assets/docs/layout.doc.dense.mjs
index 9a634221de..728047178c 100644
--- a/packages/cli/assets/docs/layout.doc.dense.mjs
+++ b/packages/cli/assets/docs/layout.doc.dense.mjs
@@ -33,8 +33,35 @@ export const docsDense = {
section: 'Scaffold',
title: 'Scaffold',
content: [
- // Shell
- null,
+ {
+ type: 'prose',
+ text: 'pick shell, budget regions, choose nav, before content. steps: Shell, Navigation. rules for both:',
+ },
+ {
+ type: 'list',
+ items: [
+ 'decide frame + region width budgets + fill-or-capped before content',
+ 'state the reason for the nav choice, or inherit template pairing',
+ 'raw px for structural widths; interior = tokens',
+ ],
+ },
+ {
+ type: 'list',
+ items: [
+ 'build content-first, Card-wrapping each section',
+ 'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
+ 'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
+ 'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
+ 'both bars when the ecosystem layer is thin',
+ 'break template nav pairing without a reason',
+ ],
+ },
+ ],
+ },
+ {
+ section: 'Shell',
+ title: 'Shell',
+ content: [
{
type: 'prose',
text: 'pick the shell + budget its regions before any content exists. structural widths are the one place raw px belongs; everything inside uses the scale.',
@@ -53,8 +80,12 @@ export const docsDense = {
type: 'prose',
text: 'verify: every region has a width budget + fill-or-capped + a container policy written down before any content.',
},
- // Navigation
- null,
+ ],
+ },
+ {
+ section: 'Navigation',
+ title: 'Navigation',
+ content: [
{
type: 'prose',
text: 'nav left open? default SideNav: it absorbs destinations you have not planned yet. app type + destination count are guiding indicators, not determining rules.',
@@ -73,35 +104,45 @@ export const docsDense = {
type: 'prose',
text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the template to start from; scaffold it and the pairing is wired up.',
},
- // Best practices
- null,
+ ],
+ },
+ {
+ section: 'Structure',
+ title: 'Structure',
+ content: [
+ {
+ type: 'prose',
+ text: 'rank content per region, pick the weakest container that groups it. steps: Type hierarchy, Card or rows, Headers and footers, Side panels. rules for all:',
+ },
{
type: 'list',
items: [
- 'decide frame + region width budgets + fill-or-capped before content',
- 'state the reason for the nav choice, or inherit template pairing',
- 'raw px for structural widths; interior = tokens',
+ 'one lead per region; rank via weight+color; one primary action',
+ 'leave body copy at its defaults; demote via weight+color, not size',
+ 'default Section; weakest container that reads as a group',
+ 'collections = rows (Table/List), edge-to-edge with dividers',
+ 'side panel on select; it yields width at narrow sizes',
],
},
{
type: 'list',
items: [
- 'build content-first, Card-wrapping each section',
- 'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
- 'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
- 'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
- 'both bars when the ecosystem layer is thin',
- 'break template nav pairing without a reason',
+ 'grey + shrink body copy, so a whole region reads as metadata',
+ 'the disabled color for content; it fails contrast, it is for disabled controls',
+ 'card soup: each record in its own Card',
+ 'cards-in-cards, or full-width Cards as page structure',
+ 'a header/footer rebuilt inside the body, where it scrolls away with the rows',
+ 'flexbox soup instead of Grid/Layout/Section/FormLayout',
+ 'two competing primary actions in one region',
+ 'Badge as decoration; use StatusDot/Token for status',
],
},
],
},
{
- section: 'Structure',
- title: 'Structure',
+ section: 'Type hierarchy',
+ title: 'Type hierarchy',
content: [
- // Type hierarchy
- null,
{
type: 'prose',
text: 'one lead per region, then rank with weight+color, not size. two text colors only: primary + secondary, nothing dimmer. body copy needs no props.',
@@ -120,8 +161,12 @@ export const docsDense = {
type: 'prose',
text: 'squint test: read lead, then support, then groups, in order. everything at once = raise contrast (weight/color), not borders and not smaller text.',
},
- // Containers
- null,
+ ],
+ },
+ {
+ section: 'Card or rows',
+ title: 'Card or rows',
+ content: [
{
type: 'prose',
text: 'weakest container that reads as a group, escalate only when it fails. weakest to strongest:',
@@ -140,8 +185,12 @@ export const docsDense = {
type: 'prose',
text: 'test: records -> rows (Table columnar, List single-line); self-contained widget or hard boundary -> Card; everything else -> Section.',
},
- // Headers and footers
- null,
+ ],
+ },
+ {
+ section: 'Headers and footers',
+ title: 'Headers and footers',
+ content: [
{
type: 'prose',
text: 'a region can pin a header/footer while its body scrolls. both are Layout slots, and padding set once on Layout reaches all three, so header/body/footer share one content line.',
@@ -160,8 +209,12 @@ export const docsDense = {
type: 'prose',
text: 'verify: scroll the body. header + footer stay put, dividers run full-bleed, all three still share one left content line.',
},
- // Side panels
- null,
+ ],
+ },
+ {
+ section: 'Side panels',
+ title: 'Side panels',
+ content: [
{
type: 'prose',
text: 'master-detail: select a row -> fixed-width side panel, no navigation away.',
@@ -179,41 +232,43 @@ export const docsDense = {
null,
{
type: 'prose',
- text: 'verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.',
+ text: 'verify: at narrow widths the panel yields width instead of squeezing content (see Responsive contract), and only one element between the regions draws a border.',
+ },
+ ],
+ },
+ {
+ section: 'Spacing',
+ title: 'Spacing',
+ content: [
+ {
+ type: 'prose',
+ text: 'one content line per region, then tune gaps + density. steps: Alignment, Rhythm, Density and size. rules for all:',
},
- // Best practices
- null,
{
type: 'list',
items: [
- 'one lead per region; rank via weight+color; one primary action',
- 'leave body copy at its defaults; demote via weight+color, not size',
- 'default Section; weakest container that reads as a group',
- 'collections = rows (Table/List), edge-to-edge with dividers',
- 'side panel on select; it yields width at narrow sizes',
+ 'container owns padding; children zero margins',
+ 'one content line: text on line, hover bleeds to edge',
+ 'one padding token across region header/body/footer',
+ 'contrast tight vs generous gaps',
+ 'one control size per row; density by use frequency',
],
},
{
type: 'list',
items: [
- 'grey + shrink body copy, so a whole region reads as metadata',
- 'the disabled color for content; it fails contrast, it is for disabled controls',
- 'card soup: each record in its own Card',
- 'cards-in-cards, or full-width Cards as page structure',
- 'a header/footer rebuilt inside the body, where it scrolls away with the rows',
- 'flexbox soup instead of Grid/Layout/Section/FormLayout',
- 'two competing primary actions in one region',
- 'Badge as decoration; use StatusDot/Token for status',
+ 'double padding (component past its heading); keep one inset owner',
+ 'raw px for interior spacing; tokens only',
+ 'one repeated gap everywhere',
+ 'mixed control sizes in one row',
],
},
],
},
{
- section: 'Spacing',
- title: 'Spacing',
+ section: 'Alignment',
+ title: 'Alignment',
content: [
- // Alignment
- null,
{
type: 'prose',
text: 'container owns padding + child gaps; children zero margins; interior spacing = token. one content line per region, hold the line not the padding: container_inset = content_line - component_intrinsic_inset.',
@@ -231,8 +286,12 @@ export const docsDense = {
type: 'prose',
text: 'verify: draw one vertical line down the left. every label touches it; only hover/selected backgrounds cross it.',
},
- // Rhythm
- null,
+ ],
+ },
+ {
+ section: 'Rhythm',
+ title: 'Rhythm',
+ content: [
{
type: 'prose',
text: 'grouping = contrast between tight and generous gaps, not one repeated value. same step everywhere = proximity does no work.',
@@ -250,8 +309,12 @@ export const docsDense = {
type: 'prose',
text: 'verify: borders removed, you can still name the groups from spacing alone. cannot = intervals too uniform. form fields excepted: FormLayout owns their spacing.',
},
- // Density and size
- null,
+ ],
+ },
+ {
+ section: 'Density and size',
+ title: 'Density and size',
+ content: [
{
type: 'prose',
text: 'density by use frequency; every control in a row shares one size so heights share a baseline.',
@@ -269,35 +332,38 @@ export const docsDense = {
type: 'prose',
text: 'verify: one size per row, paired with the density of the region it sits in.',
},
- // Best practices
- null,
+ ],
+ },
+ {
+ section: 'Breakpoints',
+ title: 'Breakpoints',
+ content: [
+ {
+ type: 'prose',
+ text: 'decide what each region does as width changes. step: Responsive contract. rules:',
+ },
{
type: 'list',
items: [
- 'container owns padding; children zero margins',
- 'one content line: text on line, hover bleeds to edge',
- 'one padding token across region header/body/footer',
- 'contrast tight vs generous gaps',
- 'one control size per row; density by use frequency',
+ 'write the contract down for every region before calling the layout done',
+ 'decide per region: revealed, resized, or swapped at each width',
+ 'drop a region rather than let it fight for width it lacks',
],
},
{
type: 'list',
items: [
- 'double padding (component past its heading); keep one inset owner',
- 'raw px for interior spacing; tokens only',
- 'one repeated gap everywhere',
- 'mixed control sizes in one row',
+ '3 regions at a width where none has usable space',
+ 'shrink every region uniformly instead of swapping/dropping one',
+ 'a CSS breakpoint the contract comment never mentions',
],
},
],
},
{
- section: 'Breakpoints',
- title: 'Breakpoints',
+ section: 'Responsive contract',
+ title: 'Responsive contract',
content: [
- // Responsive contract
- null,
{
type: 'prose',
text: 'lock what each region does as width changes; pair each contract line with the prop/hook that enforces it.',
@@ -316,24 +382,6 @@ export const docsDense = {
type: 'prose',
text: 'verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
},
- // Best practices
- null,
- {
- type: 'list',
- items: [
- 'write the contract down for every region before calling the layout done',
- 'decide per region: revealed, resized, or swapped at each width',
- 'drop a region rather than let it fight for width it lacks',
- ],
- },
- {
- type: 'list',
- items: [
- '3 regions at a width where none has usable space',
- 'shrink every region uniformly instead of swapping/dropping one',
- 'a CSS breakpoint the contract comment never mentions',
- ],
- },
],
},
],
diff --git a/packages/cli/assets/docs/layout.doc.mjs b/packages/cli/assets/docs/layout.doc.mjs
index 25b65ddd13..4bec88088e 100644
--- a/packages/cli/assets/docs/layout.doc.mjs
+++ b/packages/cli/assets/docs/layout.doc.mjs
@@ -34,9 +34,40 @@ export const docs = {
],
},
{
+ id: 'scaffold',
title: 'Scaffold',
content: [
- {type: 'heading', level: 3, text: 'Shell'},
+ {
+ type: 'prose',
+ text: 'Pick the shell, budget each region, and choose navigation, before any content exists. Shell and Navigation cover each step; these rules hold for both.',
+ },
+ {
+ type: 'list',
+ style: 'do',
+ items: [
+ 'Decide the frame, region width budgets, and fill or capped before any content exists',
+ 'State the reason for the navigation choice, or inherit the template pairing',
+ 'Reserve raw px for structural widths; interior spacing uses tokens',
+ ],
+ },
+ {
+ type: 'list',
+ style: 'dont',
+ items: [
+ 'Build content-first and wrap each section in a Card, producing a padded scroll column',
+ 'Stretch prose, forms, or lists across a wide region instead of capping with contentWidth',
+ 'SideNav when the nav is really filters or controls, or must hold wide elements like breadcrumbs',
+ 'TopNav when top-slot ownership is unclear, or the hierarchy is deep or still growing',
+ 'Both bars when the ecosystem layer is thin, so the second only wastes space',
+ 'Deviate from the template navigation pairing without a stated reason',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'shell',
+ title: 'Shell',
+ content: [
{
type: 'prose',
text: 'Pick the shell and budget its regions before any content exists. Structural widths are the one place raw px belongs; everything inside them uses the spacing scale.',
@@ -75,8 +106,12 @@ export const docs = {
type: 'prose',
text: 'Verify: every region has a width budget, a fill-or-capped decision, and a container policy written down before any content exists.',
},
-
- {type: 'heading', level: 3, text: 'Navigation'},
+ ],
+ },
+ {
+ id: 'navigation',
+ title: 'Navigation',
+ content: [
{
type: 'prose',
text: 'When the frame leaves navigation open, default to SideNav: it absorbs destinations you have not planned yet. App type and destination count are guiding indicators, not determining rules.',
@@ -108,35 +143,47 @@ export const docs = {
type: 'prose',
text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the template to start from; scaffold it and the pairing is already wired up.',
},
-
- {type: 'heading', level: 3, text: 'Best practices'},
+ ],
+ },
+ {
+ id: 'structure',
+ title: 'Structure',
+ content: [
+ {
+ type: 'prose',
+ text: 'Rank the content in each region, then pick the weakest container that groups it. Type hierarchy, Card or rows, Headers and footers, and Side panels cover each step; these rules hold for all of them.',
+ },
{
type: 'list',
style: 'do',
items: [
- 'Decide the frame, region width budgets, and fill or capped before any content exists',
- 'State the reason for the navigation choice, or inherit the template pairing',
- 'Reserve raw px for structural widths; interior spacing uses tokens',
+ 'One lead per region; rank with weight and color; one primary action',
+ 'Leave body copy at its defaults; demote by weight and color, not size',
+ 'Default to Section; use the weakest container that reads as a group',
+ 'Render collections as rows (Table or List), edge-to-edge with dividers',
+ 'Open a fixed-width side panel on select; let it yield width at narrow sizes',
],
},
{
type: 'list',
style: 'dont',
items: [
- 'Build content-first and wrap each section in a Card, producing a padded scroll column',
- 'Stretch prose, forms, or lists across a wide region instead of capping with contentWidth',
- 'SideNav when the nav is really filters or controls, or must hold wide elements like breadcrumbs',
- 'TopNav when top-slot ownership is unclear, or the hierarchy is deep or still growing',
- 'Both bars when the ecosystem layer is thin, so the second only wastes space',
- 'Deviate from the template navigation pairing without a stated reason',
+ 'Grey and shrink body copy, so a whole region reads as secondary metadata',
+ 'The disabled color for content; it fails contrast and is for disabled controls',
+ 'Card soup: each record wrapped in its own Card instead of rendered as rows',
+ 'Cards inside Cards, or full-width Cards stacked as page structure',
+ 'A header or footer rebuilt inside the body, where it scrolls away with the rows',
+ 'Flexbox soup: nested ad-hoc flexboxes instead of Grid, Layout, Section, or FormLayout',
+ 'Two competing primary actions in one region',
+ 'Badge as decoration; use StatusDot or Token for status and metadata',
],
},
],
},
{
- title: 'Structure',
+ id: 'type-hierarchy',
+ title: 'Type hierarchy',
content: [
- {type: 'heading', level: 3, text: 'Type hierarchy'},
{
type: 'prose',
text: 'Give every region one lead, then rank the rest with weight and color rather than size. Content uses two text colors, primary and secondary, and nothing dimmer: body copy needs no props at all.',
@@ -170,8 +217,12 @@ export const docs = {
type: 'prose',
text: 'Squint test: blurred, you read lead, then support, then groups, in that order. If everything reads at once, raise contrast with weight and color, not borders and not smaller text.',
},
-
- {type: 'heading', level: 3, text: 'Containers'},
+ ],
+ },
+ {
+ id: 'containers',
+ title: 'Card or rows',
+ content: [
{
type: 'prose',
text: 'Reach for the weakest container that reads as a group, and escalate only when it fails. Weakest to strongest:',
@@ -202,8 +253,12 @@ export const docs = {
type: 'prose',
text: 'Decision test: records render as rows, Table for columnar and List for single-line; a self-contained widget or hard boundary is a Card; everything else is a Section.',
},
-
- {type: 'heading', level: 3, text: 'Headers and footers'},
+ ],
+ },
+ {
+ id: 'headers-and-footers',
+ title: 'Headers and footers',
+ content: [
{
type: 'prose',
text: 'A region can pin a header or footer while its body scrolls. Both are Layout slots, and padding set once on Layout reaches all three, so header, body, and footer share one content line.',
@@ -235,8 +290,12 @@ export const docs = {
type: 'prose',
text: 'Verify: scroll the body. The header and footer stay put, their dividers run full-bleed, and all three still share one left content line.',
},
-
- {type: 'heading', level: 3, text: 'Side panels'},
+ ],
+ },
+ {
+ id: 'side-panels',
+ title: 'Side panels',
+ content: [
{
type: 'prose',
text: 'Master-detail: selecting a row opens a fixed-width side panel instead of navigating away.',
@@ -278,41 +337,45 @@ end={
},
{
type: 'prose',
- text: 'Verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.',
+ text: 'Verify: at narrow widths the panel yields width instead of squeezing content (see Responsive contract), and only one element between the regions draws a border.',
+ },
+ ],
+ },
+ {
+ id: 'spacing',
+ title: 'Spacing',
+ content: [
+ {
+ type: 'prose',
+ text: 'Hold one content line per region, then tune gaps and density. Alignment, Rhythm, and Density and size cover each step; these rules hold for all of them.',
},
-
- {type: 'heading', level: 3, text: 'Best practices'},
{
type: 'list',
style: 'do',
items: [
- 'One lead per region; rank with weight and color; one primary action',
- 'Leave body copy at its defaults; demote by weight and color, not size',
- 'Default to Section; use the weakest container that reads as a group',
- 'Render collections as rows (Table or List), edge-to-edge with dividers',
- 'Open a fixed-width side panel on select; let it yield width at narrow sizes',
+ 'Let the container own padding; children zero their own margins',
+ 'Hold one content line per region: text on the line, hover backgrounds bleed to the edge',
+ 'Hold one padding token across a region header, body, and footer',
+ 'Contrast tight and generous gaps so grouping reads without borders',
+ 'One control size per row; match density to use frequency',
],
},
{
type: 'list',
style: 'dont',
items: [
- 'Grey and shrink body copy, so a whole region reads as secondary metadata',
- 'The disabled color for content; it fails contrast and is for disabled controls',
- 'Card soup: each record wrapped in its own Card instead of rendered as rows',
- 'Cards inside Cards, or full-width Cards stacked as page structure',
- 'A header or footer rebuilt inside the body, where it scrolls away with the rows',
- 'Flexbox soup: nested ad-hoc flexboxes instead of Grid, Layout, Section, or FormLayout',
- 'Two competing primary actions in one region',
- 'Badge as decoration; use StatusDot or Token for status and metadata',
+ 'Double padding: a component indented past its Section heading (keep one inset owner)',
+ 'Raw px for interior spacing; tokens only, px is for structural widths',
+ 'One repeated gap everywhere, which flattens grouping',
+ 'Mixed control sizes in a single row',
],
},
],
},
{
- title: 'Spacing',
+ id: 'alignment',
+ title: 'Alignment',
content: [
- {type: 'heading', level: 3, text: 'Alignment'},
{
type: 'prose',
text: 'The container owns padding and child gaps; children zero their margins, and interior spacing is always a token. Pick one content line per region and hold it constant, not the padding: `container_inset = content_line - component_intrinsic_inset`.',
@@ -342,8 +405,12 @@ end={
type: 'prose',
text: 'Verify: draw one vertical line down the left of the region. Every label touches it; only hover and selected backgrounds cross it.',
},
-
- {type: 'heading', level: 3, text: 'Rhythm'},
+ ],
+ },
+ {
+ id: 'rhythm',
+ title: 'Rhythm',
+ content: [
{
type: 'prose',
text: 'Grouping comes from contrast between tight and generous gaps, not one repeated value. If every gap is the same step, proximity does no work.',
@@ -375,8 +442,12 @@ end={
type: 'prose',
text: 'Verify: with every border removed, you can still name the groups from spacing alone. If you cannot, the intervals are too uniform. Form fields are the exception: FormLayout owns their spacing.',
},
-
- {type: 'heading', level: 3, text: 'Density and size'},
+ ],
+ },
+ {
+ id: 'density',
+ title: 'Density and size',
+ content: [
{
type: 'prose',
text: 'Match density to how often a region is used, and give every control in a row the same size so heights share a baseline.',
@@ -403,35 +474,40 @@ end={
type: 'prose',
text: 'Verify: every interactive element in a row shares one size, and that size is paired with the density of the region it sits in.',
},
-
- {type: 'heading', level: 3, text: 'Best practices'},
+ ],
+ },
+ {
+ id: 'breakpoints',
+ title: 'Breakpoints',
+ content: [
+ {
+ type: 'prose',
+ text: 'Decide what each region does as width changes. Responsive contract covers it; these rules hold for every region.',
+ },
{
type: 'list',
style: 'do',
items: [
- 'Let the container own padding; children zero their own margins',
- 'Hold one content line per region: text on the line, hover backgrounds bleed to the edge',
- 'Hold one padding token across a region header, body, and footer',
- 'Contrast tight and generous gaps so grouping reads without borders',
- 'One control size per row; match density to use frequency',
+ 'Write the contract down for every region before you call the layout done',
+ 'Decide per region whether it is revealed, resized, or swapped at each width',
+ 'Drop a region rather than let it compete for width it does not have',
],
},
{
type: 'list',
style: 'dont',
items: [
- 'Double padding: a component indented past its Section heading (keep one inset owner)',
- 'Raw px for interior spacing; tokens only, px is for structural widths',
- 'One repeated gap everywhere, which flattens grouping',
- 'Mixed control sizes in a single row',
+ 'Hold three regions at a width where none of them has usable space',
+ 'Shrink every region uniformly instead of swapping or dropping one',
+ 'Wire a breakpoint in CSS that the contract comment never mentions',
],
},
],
},
{
- title: 'Breakpoints',
+ id: 'responsive-contract',
+ title: 'Responsive contract',
content: [
- {type: 'heading', level: 3, text: 'Responsive contract'},
{
type: 'prose',
text: 'Lock what each region does as width changes, and pair every line of the contract with the prop or hook that enforces it.',
@@ -468,26 +544,6 @@ const isNarrow = useMediaQuery('(max-width: 1024px)');
type: 'prose',
text: 'Verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
},
-
- {type: 'heading', level: 3, text: 'Best practices'},
- {
- type: 'list',
- style: 'do',
- items: [
- 'Write the contract down for every region before you call the layout done',
- 'Decide per region whether it is revealed, resized, or swapped at each width',
- 'Drop a region rather than let it compete for width it does not have',
- ],
- },
- {
- type: 'list',
- style: 'dont',
- items: [
- 'Hold three regions at a width where none of them has usable space',
- 'Shrink every region uniformly instead of swapping or dropping one',
- 'Wire a breakpoint in CSS that the contract comment never mentions',
- ],
- },
],
},
],
diff --git a/packages/cli/assets/docs/migration.doc.mjs b/packages/cli/assets/docs/migration.doc.mjs
index d022b96644..c4c70d0d5b 100644
--- a/packages/cli/assets/docs/migration.doc.mjs
+++ b/packages/cli/assets/docs/migration.doc.mjs
@@ -30,12 +30,12 @@ export const docs = {
type: 'list',
style: 'ordered',
items: [
- 'Install the design system and run init so the project has package scripts, theme CSS, and agent docs.',
+ 'Install the packages and run `astryx init` for agent docs, then add the reset, `astryx.css`, and theme CSS imports (see Theme and CSS Setup).',
'Wrap the app root with Theme and choose the initial light, dark, or system mode behavior.',
'Make Tailwind and design system CSS layer order explicit before replacing components.',
'Render the foundation smoke test page and confirm primitives keep their padding before migrating any surface.',
'Move the persistent frame first: AppShell, TopNav, SideNav, page content, and mobile navigation.',
- 'Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, Tabs, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.',
+ 'Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, TabList, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.',
'Replace global workflows: command palette, settings popover, theme toggle, search, filters, create flows, and destructive confirmation dialogs.',
'Remove legacy Tailwind classes from each completed surface, keeping only token-backed layout utilities or local wrappers that still need to be migrated.',
'Verify both light and dark modes, keyboard navigation, responsive layout, and empty/error/loading states before moving to the next route.',
@@ -69,13 +69,13 @@ astryx component TextInput`,
},
{
type: 'prose',
- text: 'Use --dense when pasting output into an AI coding tool, and use --json when building automated migration reports.',
+ text: 'For a shorter read to paste into an AI coding tool, add `--detail brief` (one line per section) or `--detail compact`. Use `--json` when building automated migration reports.',
},
{
type: 'code',
lang: 'bash',
- label: 'Dense and JSON modes',
- code: `astryx docs migration --dense
+ label: 'Short and JSON modes',
+ code: `astryx docs migration --full --detail brief
astryx component Button --json`,
},
],
@@ -110,21 +110,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
},
{
type: 'prose',
- text: 'When Tailwind remains in the app, declare layer order once in the global CSS file. design system reset and theme CSS should load before Tailwind utilities so migrated components keep design system defaults while legacy utility classes still work.',
- },
- {
- type: 'code',
- lang: 'css',
- label: 'Tailwind v4 coexistence',
- code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
-
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/preflight.css" layer(base);
-@import "@astryxdesign/core/reset.css";
-@import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-neutral/theme.css";
-@import "@astryxdesign/core/tailwind-theme.css";
-@import "tailwindcss/utilities.css" layer(utilities);`,
+ text: 'When Tailwind remains in the app, declare layer order once in the global CSS file. Load the Astryx reset and theme CSS before Tailwind utilities so migrated components keep design system defaults while legacy utility classes still work. On Tailwind v4, use the imports and layer order in the Tailwind section of {@link generic:styling-libraries}.',
},
{
type: 'prose',
@@ -149,7 +135,8 @@ export function AppRoot({children}: {children: React.ReactNode}) {
],
},
{
- title: 'Cascade Layer Safety',
+ id: 'cascade-layer-safety',
+ title: 'Why resets break cascade layers',
content: [
{
type: 'prose',
@@ -166,6 +153,16 @@ export function AppRoot({children}: {children: React.ReactNode}) {
code: `/* was: @import "./legacy-reset.css"; (unlayered: beats every layer) */
@import "./legacy-reset.css" layer(reset);`,
},
+ {
+ type: 'prose',
+ text: 'Before building screens, check every stylesheet against Cascade layer audit.',
+ },
+ ],
+ },
+ {
+ id: 'layer-audit',
+ title: 'Cascade layer audit',
+ content: [
{
type: 'prose',
text: 'Audit the layers around the design system with this checklist before building screens.',
@@ -310,6 +307,7 @@ if (getComputedStyle(button).paddingInline === '0px') {
],
},
{
+ id: 'command-palette',
title: 'Command Palette, Settings, and Theme',
content: [
{
diff --git a/packages/cli/assets/docs/motion.doc.mjs b/packages/cli/assets/docs/motion.doc.mjs
index ab2cb7a9b3..a99a9282bb 100644
--- a/packages/cli/assets/docs/motion.doc.mjs
+++ b/packages/cli/assets/docs/motion.doc.mjs
@@ -33,6 +33,10 @@ export const docs = {
title: 'Duration',
category: 'foundations',
content: [
+ {
+ type: 'prose',
+ text: 'Nine duration tokens in fast, medium, and slow bands.',
+ },
{
type: 'token-ref',
topic: 'tokens',
@@ -44,6 +48,10 @@ export const docs = {
title: 'Easing',
category: 'foundations',
content: [
+ {
+ type: 'prose',
+ text: 'One easing curve, `--ease-standard`.',
+ },
{
type: 'token-ref',
topic: 'tokens',
@@ -101,19 +109,24 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Some users experience motion sensitivity; animation that feels polished to one person can cause discomfort for another. Components should honor the operating system\'s reduced motion setting. When it\'s enabled, replace animations with instant state changes.',
+ text: 'Some users experience motion sensitivity; animation that feels polished to one person can cause discomfort for another. Astryx components already switch to instant changes when the OS reduced-motion setting is on. Do the same in your own animations with `@media (prefers-reduced-motion: reduce)`.',
},
],
},
{
- title: 'Usage',
+ id: 'usage',
+ title: 'Animate with motion tokens',
category: 'foundations',
content: [
+ {
+ type: 'prose',
+ text: 'Set transition durations and easing from the motion tokens, so a theme that retunes motion retunes your animations too.',
+ },
{
type: 'code',
lang: 'tsx',
label: 'Applying motion tokens',
- code: `import {durationVars, easeVars} from '@astryxdesign/core';
+ code: `import {durationVars, easeVars} from '@astryxdesign/core/theme/tokens.stylex';
const styles = stylex.create({
fadeIn: {
diff --git a/packages/cli/assets/docs/principles.doc.dense.mjs b/packages/cli/assets/docs/principles.doc.dense.mjs
index bf698c76b1..64194511d3 100644
--- a/packages/cli/assets/docs/principles.doc.dense.mjs
+++ b/packages/cli/assets/docs/principles.doc.dense.mjs
@@ -5,10 +5,10 @@
export const docsDense = {
description: 'core design principles + rules for the design system',
sections: [
- { section: 'Design Philosophy', title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
- { section: 'Rules', title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
- { section: 'Styling Approach', title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
- { section: 'Anti-Patterns', title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
- { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run astryx docs tokens for full reference' }] },
+ { section: 'Design Philosophy', title: 'Philosophy', content: [{ type: 'prose', text: 'consistency, adaptability, DX. core ideas:' }, { type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
+ { section: 'Rules', title: 'Rules', content: [{ type: 'prose', text: '8 rules for on-system app code.' }, { type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content ({@link generic:layout})', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling ({@link generic:styling})', 'semantic tokens only ({@link generic:tokens})', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
+ { section: 'Styling Approach', title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout.' }, { type: 'prose', text: 'full guide: {@link generic:styling}' }] },
+ { section: 'Anti-Patterns', title: 'Anti-Patterns', content: [{ type: 'prose', text: 'what breaks theming, routing, or layout, and the fix.' }, { type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data ({@link generic:layout})', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
+ { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'full token reference: {@link generic:tokens}' }] },
],
};
diff --git a/packages/cli/assets/docs/principles.doc.mjs b/packages/cli/assets/docs/principles.doc.mjs
index 9f42985fa6..eb21bc6448 100644
--- a/packages/cli/assets/docs/principles.doc.mjs
+++ b/packages/cli/assets/docs/principles.doc.mjs
@@ -34,6 +34,10 @@ export const docs = {
title: 'Rules',
category: 'guide',
content: [
+ {
+ type: 'prose',
+ text: 'Eight rules that keep app code on-system.',
+ },
{
type: 'list',
style: 'ordered',
@@ -68,6 +72,10 @@ export const docs = {
title: 'Anti-Patterns',
category: 'guide',
content: [
+ {
+ type: 'prose',
+ text: 'Patterns that break theming, routing, or layout, and what to use instead.',
+ },
{
type: 'list',
style: 'dont',
diff --git a/packages/cli/assets/docs/principles.doc.zh.mjs b/packages/cli/assets/docs/principles.doc.zh.mjs
index 6b2a1967ff..f1f28ec133 100644
--- a/packages/cli/assets/docs/principles.doc.zh.mjs
+++ b/packages/cli/assets/docs/principles.doc.zh.mjs
@@ -3,12 +3,12 @@
/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
export const docsZh = {
- description: 'XDS 核心设计原则和规则。',
+ description: 'Astryx 核心设计原则和规则。',
sections: [
- { section: 'Design Philosophy', title: '设计哲学', content: [{ type: 'list', items: ['组件优于原始元素 — 优先使用 XDS 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },
- { section: 'Rules', title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 astryx docs layout)', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌,不使用硬编码值', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },
- { section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
- { section: 'Anti-Patterns', title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 astryx docs layout)', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
- { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 astryx docs tokens 查看完整参考' }] },
+ { section: 'Design Philosophy', title: '设计哲学', content: [{ type: 'prose', text: '一个注重一致性、适应性和开发者体验的设计系统。核心理念:' }, { type: 'list', items: ['组件优于原始元素 — 优先使用 Astryx 组件', '语义化令牌优于硬编码值', '主题无关的代码 — 深色模式自动生效', '开放的内部机制 — 所有基础组件均可导出和组合'] }] },
+ { section: 'Rules', title: '规则', content: [{ type: 'prose', text: '让应用代码保持在设计系统之内的八条规则。' }, { type: 'list', items: ['所有支持的场景都使用 Astryx 组件', '布局采用框架优先:先选定外壳并规划区域尺寸,再编写内容(见 {@link generic:layout})', '密集数据使用行(Table、List/Item)通栏渲染;Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置(见 {@link generic:styling})', '使用语义化令牌,不使用硬编码值(见 {@link generic:tokens})', '使用 CSS 变量设置颜色,不使用十六进制值', '表单输入为受控组件(value + onChange)', '使用 useLinkComponent() 进行导航'] }] },
+ { section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。' }, { type: 'prose', text: '完整指南见 {@link generic:styling}。' }] },
+ { section: 'Anti-Patterns', title: '反模式', content: [{ type: 'prose', text: '会破坏主题、路由或布局的写法,以及应改用的做法。' }, { type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架,密集数据用行渲染(见 {@link generic:layout})', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
+ { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '完整令牌参考见 {@link generic:tokens}。' }] },
],
};
diff --git a/packages/cli/assets/docs/shape.doc.mjs b/packages/cli/assets/docs/shape.doc.mjs
index 7b62db82aa..f031b03cea 100644
--- a/packages/cli/assets/docs/shape.doc.mjs
+++ b/packages/cli/assets/docs/shape.doc.mjs
@@ -25,6 +25,10 @@ export const docs = {
title: 'Radius Scale',
category: 'foundations',
content: [
+ {
+ type: 'prose',
+ text: 'Seven radius tokens, from 0px to 9999px.',
+ },
{
type: 'token-ref',
topic: 'tokens',
@@ -38,14 +42,15 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'When a rounded container has padding, inner elements need a smaller radius to appear concentric. Components like Card handle this automatically; the inner radius is computed as max(0, outerRadius - padding).',
+ text: 'Inside a padded, rounded container, give nested elements a radius of outer radius minus padding so the curves stay concentric. Card does not do this for your content.',
},
{
type: 'code',
lang: 'css',
label: 'Concentric radius formula',
- code: `/* Automatic in Astryx Card */
---card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
+ code: `.inner {
+ border-radius: max(0px, calc(var(--radius-container) - var(--spacing-4)));
+}`,
},
],
},
diff --git a/packages/cli/assets/docs/spacing.doc.mjs b/packages/cli/assets/docs/spacing.doc.mjs
index 1559c3af4c..f538d38893 100644
--- a/packages/cli/assets/docs/spacing.doc.mjs
+++ b/packages/cli/assets/docs/spacing.doc.mjs
@@ -8,6 +8,7 @@ export const docs = {
category: 'foundations',
description:
'Spacing scale tokens for padding, gap, and margin: the rhythmic foundation of design system layouts.',
+ keywords: ['padding', 'margin', 'gap'],
tokenCategory: 'spacing',
sections: [
@@ -25,6 +26,10 @@ export const docs = {
title: 'Scale',
category: 'foundations',
content: [
+ {
+ type: 'prose',
+ text: 'Fifteen spacing tokens, from 0px to 48px.',
+ },
{
type: 'token-ref',
topic: 'tokens',
@@ -38,7 +43,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Most components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX.',
+ text: 'Stack, HStack, VStack, Grid, Toolbar, OverflowList, and ChatMessageList take a `gap` step: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, or 10 (×4px). Carousel takes the steps from 0 to 4. For custom layouts, use the spacing tokens in StyleX.',
},
{
type: 'code',
@@ -48,7 +53,7 @@ export const docs = {
<Stack gap={4}>{/* 16px gap */}</Stack>
// Via StyleX tokens (custom layouts)
-import {spacingVars} from '@astryxdesign/core';
+import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
const styles = stylex.create({
custom: {
diff --git a/packages/cli/assets/docs/styling-libraries.doc.mjs b/packages/cli/assets/docs/styling-libraries.doc.mjs
index 05f4cb9a14..7900346d89 100644
--- a/packages/cli/assets/docs/styling-libraries.doc.mjs
+++ b/packages/cli/assets/docs/styling-libraries.doc.mjs
@@ -185,6 +185,7 @@ const styles = stylex.create({
],
},
{
+ id: 'semantic-token-systems',
title: 'Panda, Chakra, and Other Semantic Token Systems',
category: 'guide',
content: [
@@ -246,7 +247,7 @@ tokens: {
content: [
{
type: 'prose',
- text: 'MUI expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.',
+ text: '`MUI` expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.',
},
{
type: 'code',
@@ -293,12 +294,13 @@ tokens: {
],
},
{
+ id: 'css-in-js',
title: 'Emotion, styled-components, Theme UI, and Styled System',
category: 'guide',
content: [
{
type: 'prose',
- text: 'Runtime CSS-in-JS libraries usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.',
+ text: 'Runtime CSS-in-JS libraries such as `Emotion` and `styled-components` usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.',
},
{
type: 'code',
@@ -327,6 +329,7 @@ tokens: {
],
},
{
+ id: 'unocss',
title: 'UnoCSS and Custom Utility Systems',
category: 'guide',
content: [
@@ -422,6 +425,7 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
],
},
{
+ id: 'non-css-best-practices',
title: 'Non-CSS Processing Best Practices',
category: 'guide',
content: [
diff --git a/packages/cli/assets/docs/styling.doc.mjs b/packages/cli/assets/docs/styling.doc.mjs
index 357216da45..7840c91acf 100644
--- a/packages/cli/assets/docs/styling.doc.mjs
+++ b/packages/cli/assets/docs/styling.doc.mjs
@@ -8,6 +8,7 @@ export const docs = {
category: 'guide',
description:
'How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, theming hooks, and styling-library interop.',
+ keywords: ['override', 'customize', 'css'],
sections: [
{
@@ -16,7 +17,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'There are several ways to style things. Here is when to use each:',
+ text: 'Style components with `xstyle` (StyleX), `className` (Tailwind or your own CSS), or a styling library aliased to Astryx tokens. All of them resolve to the same tokens.',
},
{
type: 'table',
@@ -30,7 +31,7 @@ export const docs = {
},
{
type: 'prose',
- text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
+ text: 'Theming and dark mode work whichever you choose. For external styling libraries, run {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
},
],
},
@@ -40,7 +41,7 @@ export const docs = {
content: [
{
type: 'prose',
- text: 'Every component accepts an xstyle prop for style customization. It accepts StyleX styles created via stylex.create(), not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.',
+ text: 'Every component accepts an `xstyle` prop for style customization. It accepts StyleX styles created via `stylex.create()`, not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.',
},
{
type: 'code',
@@ -94,24 +95,14 @@ const overrides = stylex.create({
text: 'The package ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.',
},
{
- type: 'code',
- lang: 'css',
- label: 'globals.css: import the bridge',
- code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
-
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/preflight.css" layer(base);
-@import "@astryxdesign/core/reset.css";
-@import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-neutral/theme.css";
-@import "@astryxdesign/core/tailwind-theme.css";
-@import "tailwindcss/utilities.css" layer(utilities);`,
+ type: 'prose',
+ text: 'For the imports and the cascade-layer order to put in your global CSS, see the Tailwind section of {@link generic:styling-libraries}.',
},
{
type: 'code',
lang: 'tsx',
label: 'Tailwind utilities alongside components',
- code: `<div className="text-primary bg-surface rounded-container p-4 flex gap-3">
+ code: `<div className="text-primary bg-surface rounded-lg p-4 flex gap-3">
<Button label="Save" variant="primary" />
<Button label="Cancel" variant="secondary" />
</div>`,
@@ -128,7 +119,7 @@ const overrides = stylex.create({
content: [
{
type: 'prose',
- text: 'Every component also accepts standard className and style props. className is appended after the component\'s own classes. style is merged after StyleX inline styles, so consumer values win on conflict.',
+ text: 'Every component also accepts standard `className` and `style` props. `className` is appended after the component\'s own classes. `style` is merged after StyleX inline styles, so consumer values win on conflict.',
},
{
type: 'code',
@@ -226,7 +217,10 @@ const overrides = stylex.create({
],
},
{
- title: 'Preferred Selector Surface: Data Attributes',
+ // The key it had in 0.6, so `astryx docs styling
+ // preferred-selector-surface-data-attributes` keeps working.
+ id: 'preferred-selector-surface-data-attributes',
+ title: 'Data attribute selectors',
category: 'guide',
content: [
{
@@ -268,12 +262,13 @@ const overrides = stylex.create({
],
},
{
+ id: 'deprecated-classes',
title: 'Deprecated: Bare Prop and State Classes',
category: 'guide',
content: [
{
type: 'prose',
- text: 'Astryx continues to emit deprecated bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` through the 0.7.0 removal window. Prefer the explicit reflected data attributes for new CSS, and run `astryx upgrade --apply` before 0.7.0 to parse `.css` files and rewrite selectors qualified by a known Astryx target when the 0.5.4 target/value pair has one or more known meanings. Declarations, comments, JavaScript/TypeScript strings, and unqualified classes are never rewritten. Stable base target classes (`.astryx-button`, `.astryx-card`, etc.) remain unchanged.',
+ text: 'Astryx still emits the deprecated bare classes (`.primary`, `.sm`, `.level-2`, `.checked`) and will remove them in a later release. Use data attributes for new CSS; `astryx upgrade --from <old version> --apply` rewrites qualified selectors in `.css` files.',
},
{
type: 'code',
@@ -290,7 +285,7 @@ const overrides = stylex.create({
},
{
type: 'prose',
- text: 'Each known old value becomes a specificity-preserving `:is(...)` union containing the original class arm plus every v0.5.4 data-attribute arm. Both arms match Astryx output during the deprecation window; the data-attribute arm continues matching after the bare compatibility classes are eligible for removal in 0.7.0. The class arm also preserves consumer-supplied `className` matches. Narrow the union later only when class provenance or prop-axis intent is known. Custom/unknown qualified classes and unqualified classes stay unchanged. Search for unqualified old values such as `.primary` or `.sm` and migrate only confirmed Astryx uses manually. Migrate selectors embedded in JavaScript or TypeScript manually with the same rules.',
+ text: 'The upgrade rewrites a selector only when an `.astryx-*` component class qualifies it, turning the old class into an `:is(...)` union of that class and the data attributes it stood for. The union keeps the selector\'s specificity and your own `className` matches, and keeps matching once the bare classes are gone; the `.astryx-*` classes themselves stay. It leaves unqualified classes (a bare `.primary`), unknown classes, and selectors in JavaScript or TypeScript alone: migrate those by hand, and only where they target Astryx.',
},
],
},
@@ -343,6 +338,7 @@ const styles = stylex.create({
],
},
{
+ id: 'stylex-setup',
title: 'StyleX Build Setup (required for swizzled components)',
category: 'guide',
content: [
@@ -362,11 +358,11 @@ const styles = stylex.create({
},
{
type: 'prose',
- text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, which in turn breaks SWC-dependent features like `next/font`. So the "obvious" Babel setup is actively incompatible with a standard Next 15 App Router app.',
+ text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.',
},
{
type: 'prose',
- text: 'The working path on Next.js is an SWC-based StyleX transform (e.g. the community `@stylexswc/nextjs-plugin`) wired into `next.config`, which keeps SWC and `next/font` intact. See the example app `apps/example-nextjs-stylex` in the repo for a complete, working Next.js + StyleX + SWC configuration.',
+ text: 'The repo\'s `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.',
},
{
type: 'code',
@@ -389,7 +385,7 @@ export default stylexPlugin({
style: 'unordered',
items: [
'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',
- 'Do NOT add @stylexjs/babel-plugin to a Next.js App Router app; it disables SWC and breaks next/font.',
+ 'A Babel config turns off SWC in Next.js; skip it if you need `next/font`.',
'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',
],
},
diff --git a/packages/cli/assets/docs/theme.doc.dense.mjs b/packages/cli/assets/docs/theme.doc.dense.mjs
index 89cd78ce9c..99222f309d 100644
--- a/packages/cli/assets/docs/theme.doc.dense.mjs
+++ b/packages/cli/assets/docs/theme.doc.dense.mjs
@@ -3,11 +3,12 @@
/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
export const docsDense = {
- description: 'Theme provider, custom themes, light/dark, component overrides',
+ description:
+ 'Theme provider, custom themes, theme build (prod/SSR), light/dark, component overrides',
sections: [
{
- section: 'Quick Start',
- title: 'Quick Start',
+ section: 'Wrap your app in a theme',
+ title: 'Wrap your app',
content: [
null,
null,
@@ -31,9 +32,18 @@ export const docsDense = {
},
],
},
- {section: 'Theme Props', title: 'Props', content: [null]},
{
- section: 'Creating a Custom Theme',
+ section: 'Theme Props',
+ title: 'Props',
+ content: [
+ {
+ type: 'prose',
+ text: "<Theme> props: theme (required), mode ('system' default, or 'light'/'dark'), children. every prop: astryx component Theme.",
+ },
+ ],
+ },
+ {
+ section: 'Custom themes',
title: 'Custom Theme',
content: [
{
@@ -65,10 +75,36 @@ export const docsDense = {
content: [
{
type: 'prose',
- text: 'adaptations = ordered {when,value} rules over width/pointer/contrast/motion. widthBreakpoints fixed sm|md|lg|xl|2xl defaults 640|768|1024|1280|1536; map alone emits no CSS. width.from inclusive, width.below exclusive; condition fields AND. root first, then matching rules in authored order (later writes win), then onDark/onLight. rules can write typography/color/radius/motion/tokens/localTokens/components; local names belong on root. Component writes validate exactly like root components (same targets/axes/domains); only difference: a rule cannot be the sole enroller of a custom value (type augmentation is unconditional) — declare it on root, then restyle. Built-ins need no root declaration. Co-matching token/localToken writes are validated together; any reachable var() cycle fails. extends inherits breakpoints + ordered rules, appends child rules, re-resolves against child axes. CSS-only; use built themes for SSR first paint.',
+ text: 'adaptations = ordered {when,value} rules over width/pointer/contrast/motion. condition fields AND. rules can write typography/color/radius/motion/tokens/localTokens/components.',
},
null,
null,
+ {
+ type: 'prose',
+ text: 'widthBreakpoints fixed sm|md|lg|xl|2xl defaults 640|768|1024|1280|1536; map alone emits no CSS. width.from inclusive, width.below exclusive. order + validation: see Adaptation Rules.',
+ },
+ ],
+ },
+ {
+ section: 'Adaptation order and validation',
+ title: 'Adaptation Rules',
+ content: [
+ {
+ type: 'prose',
+ text: 'root first, then matching rules in authored order (later writes win), then onDark/onLight on the same leaf.',
+ },
+ {
+ type: 'prose',
+ text: 'extends inherits breakpoints + ordered rules, appends child rules, re-resolves against child axes. an empty child rule is a no-op, not a removal.',
+ },
+ {
+ type: 'prose',
+ text: 'local names belong on root. Component writes validate exactly like root components (same targets/axes/domains); only difference: a rule cannot be the sole enroller of a custom value (type augmentation is unconditional) — declare it on root, then restyle. Built-ins need no root declaration. Co-matching token/localToken writes are validated together; any reachable var() cycle fails.',
+ },
+ {
+ type: 'prose',
+ text: 'CSS-only (media queries, no resize listener); use built themes for SSR first paint.',
+ },
],
},
{
@@ -77,7 +113,7 @@ export const docsDense = {
content: [
{
type: 'prose',
- text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx theme targets [Name]` to enumerate every themeable key (--json for lint), `astryx component <Name>` for one component.',
+ text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors ({@link generic:styling}). write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx theme targets [Name]` to enumerate every themeable key (--json for lint), `astryx component <Name>` for one component.',
},
null,
null,
@@ -100,16 +136,19 @@ export const docsDense = {
],
},
{
- section: 'Building Themes for Production',
+ section: 'Build a theme',
title: 'Build for Production',
content: [
{
type: 'prose',
text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.',
},
- null,
- null,
- null,
+ ],
+ },
+ {
+ section: 'Built themes with an icon registry',
+ title: 'Icon Registry',
+ content: [
{
type: 'prose',
text: 'current build detects named imports used by icons:. registry module is not compiled. inline/local registries accepted by defineTheme are omitted from built output; move them to a separate module and import by name.',
@@ -123,9 +162,6 @@ export const docsDense = {
type: 'prose',
text: 'without --icons-specifier, source import is copied unchanged. default flow without --out: bundlers can resolve ./icons to neighboring icons.tsx; Node ESM fails with ERR_MODULE_NOT_FOUND. moving output changes relative import resolution.',
},
- null,
- null,
- null,
],
},
{
@@ -154,8 +190,8 @@ export const docsDense = {
],
},
{
- section: 'Light/Dark Mode',
- title: 'Light/Dark',
+ section: 'Dark mode',
+ title: 'Dark mode',
content: [
{
type: 'prose',
@@ -166,7 +202,7 @@ export const docsDense = {
],
},
{
- section: 'Nesting Themes',
+ section: 'Nested themes',
title: 'Nesting',
content: [
{type: 'prose', text: 'wrap sections in separate <Theme> providers'},
@@ -178,7 +214,11 @@ export const docsDense = {
title: 'useTheme',
content: [
null,
- {type: 'prose', text: 'read-only. manage state at app level.'},
+ null,
+ {
+ type: 'prose',
+ text: 'read-only. ordinary styling: CSS vars, StyleX tokens, xstyle, className. to change theme/mode, manage state at app level and pass it to <Theme>.',
+ },
],
},
],
diff --git a/packages/cli/assets/docs/theme.doc.mjs b/packages/cli/assets/docs/theme.doc.mjs
index 95fe3c9de6..c9b8a769d2 100644
--- a/packages/cli/assets/docs/theme.doc.mjs
+++ b/packages/cli/assets/docs/theme.doc.mjs
@@ -11,7 +11,8 @@ export const docs = {
sections: [
{
- title: 'Quick Start',
+ id: 'quick-start',
+ title: 'Wrap your app in a theme',
category: 'guide',
content: [
{
@@ -96,7 +97,7 @@ function App() {
[
'Matcha',
"import {matchaTheme} from '@astryxdesign/theme-matcha'",
- 'Earthy green theme with Figtree typography.',
+ 'Earthy greens; DM Sans + Playwrite US Trad type.',
],
[
'Stone',
@@ -121,22 +122,13 @@ function App() {
category: 'guide',
content: [
{
- type: 'table',
- headers: ['Prop', 'Type', 'Default', 'Description'],
- rows: [
- ['theme', 'DefinedTheme', '-', 'Theme object (required)'],
- [
- 'mode',
- "'system' | 'light' | 'dark'",
- "'system'",
- 'Color mode. system follows OS preference.',
- ],
- ['children', 'ReactNode', '-', 'App content'],
- ],
+ type: 'prose',
+ text: "`<Theme>` takes `theme` (required), `mode` (`'system'` by default, or `'light'`/`'dark'`), and `children`. For every prop, run `astryx component Theme`.",
},
],
},
{
+ id: 'integration-themes',
title: 'Using a Theme from an Integration',
category: 'guide',
content: [
@@ -157,7 +149,8 @@ function App() {
],
},
{
- title: 'Creating a Custom Theme',
+ id: 'creating-a-custom-theme',
+ title: 'Custom themes',
category: 'guide',
content: [
{
@@ -365,11 +358,18 @@ const brandTheme = defineTheme({
},
{
type: 'prose',
- text: '`widthBreakpoints` are fixed named start points. Defaults are 640 / 768 / 1024 / 1280 / 1536 CSS pixels. `from` includes its point; `below` excludes it. Breakpoint configuration alone emits no CSS.',
+ text: '`widthBreakpoints` are fixed named start points. Defaults are 640 / 768 / 1024 / 1280 / 1536 CSS pixels. `from` includes its point; `below` excludes it. Breakpoint configuration alone emits no CSS. For how matching rules combine and what a rule may write, see Adaptation order and validation.',
},
+ ],
+ },
+ {
+ id: 'adaptation-rules',
+ title: 'Adaptation order and validation',
+ category: 'guide',
+ content: [
{
type: 'prose',
- text: '**Precedence follows rule order.** Root theme values apply first, then every matching rule in declaration order. A later rule may deliberately restore a root value. `onDark` and `onLight` media-surface overrides apply after adaptations and win on the same leaf.',
+ text: 'Precedence follows rule order. Root theme values apply first, then every matching rule in declaration order. A later rule may deliberately restore a root value. `onDark` and `onLight` media-surface overrides apply after adaptations and win on the same leaf.',
},
{
type: 'prose',
@@ -464,7 +464,7 @@ const brandTheme = defineTheme({
banner: {
// Any extensible prop axis works — not just variant
'status:neutral': {
- backgroundColor: 'var(--color-muted)',
+ backgroundColor: 'var(--color-background-muted)',
color: 'var(--color-text-secondary)',
},
},
@@ -489,7 +489,8 @@ const brandTheme = defineTheme({
],
},
{
- title: 'Building Themes for Production',
+ id: 'building-themes-for-production',
+ title: 'Build a theme',
category: 'guide',
content: [
{
@@ -516,7 +517,7 @@ const brandTheme = defineTheme({
],
[
'ocean.js',
- 'ES module exporting the theme object with `__built: true` and pre-resolved token values. Also imports and re-exports an icon registry when the build detects its named import in the source theme (see the limitations below).',
+ 'ES module exporting the theme object with `__built: true` and pre-resolved token values. Also imports and re-exports an icon registry when the build detects its named import in the source theme (see Built themes with an icon registry).',
],
[
'ocean.d.ts',
@@ -528,29 +529,6 @@ const brandTheme = defineTheme({
],
],
},
- {
- type: 'prose',
- text: "The current `theme build` implementation emits an icon import when it detects a named import used by the theme’s `icons:` field, such as `import {oceanIcons} from './icons'` with `icons: oceanIcons`. It does not compile that registry module. Inline registries, including local constants, are currently omitted from the generated theme even though `defineTheme` accepts them at runtime. Move the registry to a separate module and use a named import for this build flow. For a registry that uses React and lucide-react, the following example compiles it alongside the generated theme:",
- },
- {
- type: 'code',
- lang: 'bash',
- label: 'Compiling the icon registry sidecar',
- code: `# Emit the built theme; point its icon import at the file the next step produces
-astryx theme build ./src/themes/ocean.ts -o dist/theme.css --icons-specifier ./icons.mjs
-
-# Compile the icon registry to a real ES module next to the generated JS
-esbuild src/themes/icons.tsx --bundle --format=esm --outfile=dist/icons.mjs \\
- --external:react --external:lucide-react --jsx=automatic`,
- },
- {
- type: 'prose',
- text: 'In the example above, the generated theme imports `./icons.mjs` from `dist`. If the second command is skipped, `theme build` can still succeed, but loading or bundling the generated module fails because `dist/icons.mjs` is missing. `--icons-specifier` changes the emitted import; it does not create or verify the target file. Match the specifier to a module that resolves from the generated JS file. Keep `react` and the icon library external so the registry does not bundle its own copies of those dependencies.',
- },
- {
- type: 'prose',
- text: 'Without `--icons-specifier`, the detected source import specifier is emitted unchanged. In the default no-`--out` flow, a bundler can resolve an extensionless `./icons` to the neighboring `icons.tsx` source. Node ESM does not perform that lookup and reports `ERR_MODULE_NOT_FOUND`. Moving the output with `--out` also changes where relative imports resolve; the generated module cannot find the original source merely because a bundler is used.',
- },
{
type: 'prose',
text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it.',
@@ -576,6 +554,36 @@ import './themes/ocean.css';
},
],
},
+ {
+ id: 'icon-registry',
+ title: 'Built themes with an icon registry',
+ category: 'guide',
+ content: [
+ {
+ type: 'prose',
+ text: "The current `theme build` implementation emits an icon import when it detects a named import used by the theme’s `icons:` field, such as `import {oceanIcons} from './icons'` with `icons: oceanIcons`. It does not compile that registry module. Inline registries, including local constants, are currently omitted from the generated theme even though `defineTheme` accepts them at runtime. Move the registry to a separate module and use a named import for this build flow. For a registry that uses React and lucide-react, the following example compiles it alongside the generated theme:",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ label: 'Compiling the icon registry sidecar',
+ code: `# Emit the built theme; point its icon import at the file the next step produces
+astryx theme build ./src/themes/ocean.ts -o dist/theme.css --icons-specifier ./icons.mjs
+
+# Compile the icon registry to a real ES module next to the generated JS
+esbuild src/themes/icons.tsx --bundle --format=esm --outfile=dist/icons.mjs \\
+ --external:react --external:lucide-react --jsx=automatic`,
+ },
+ {
+ type: 'prose',
+ text: 'In the example above, the generated theme imports `./icons.mjs` from `dist`. If the second command is skipped, `theme build` can still succeed, but loading or bundling the generated module fails because `dist/icons.mjs` is missing. `--icons-specifier` changes the emitted import; it does not create or verify the target file. Match the specifier to a module that resolves from the generated JS file. Keep `react` and the icon library external so the registry does not bundle its own copies of those dependencies.',
+ },
+ {
+ type: 'prose',
+ text: 'Without `--icons-specifier`, the detected source import specifier is emitted unchanged. In the default no-`--out` flow, a bundler can resolve an extensionless `./icons` to the neighboring `icons.tsx` source. Node ESM does not perform that lookup and reports `ERR_MODULE_NOT_FOUND`. Moving the output with `--out` also changes where relative imports resolve; the generated module cannot find the original source merely because a bundler is used.',
+ },
+ ],
+ },
{
title: 'Building a Theme Family',
category: 'guide',
@@ -677,7 +685,8 @@ import './themes/ocean.css';
],
},
{
- title: 'Light/Dark Mode',
+ id: 'light-dark-mode',
+ title: 'Dark mode',
category: 'guide',
content: [
{
@@ -706,12 +715,13 @@ import './themes/ocean.css';
],
},
{
- title: 'Nesting Themes',
+ id: 'nesting-themes',
+ title: 'Nested themes',
category: 'guide',
content: [
{
type: 'prose',
- text: 'Wrap different sections in separate [`<Theme>`](/components/Theme) providers.',
+ text: 'Wrap different sections in separate `<Theme>` providers.',
},
{
type: 'code',
diff --git a/packages/cli/assets/docs/theme.doc.zh.mjs b/packages/cli/assets/docs/theme.doc.zh.mjs
index 88684ebff0..050d9ac3dc 100644
--- a/packages/cli/assets/docs/theme.doc.zh.mjs
+++ b/packages/cli/assets/docs/theme.doc.zh.mjs
@@ -3,17 +3,18 @@
/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
export const docsZh = {
- description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',
+ description: 'Theme 提供者、自定义主题、生产/SSR 主题构建、亮/暗模式和组件样式覆盖。',
sections: [
- { section: 'Quick Start', title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS(需配合 theme.css)。' }] },
+ { section: 'Wrap your app in a theme', title: '用主题包裹应用', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS(需配合 theme.css)。' }] },
{ section: 'Available Themes', title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题:neutral(推荐起点)、butter、chocolate、gothic(仅暗色)、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版(运行时注入)。@astryxdesign/theme-{name}/built = 优化版(配合 theme.css)。' }] },
- { section: 'Theme Props', title: 'Theme 属性', content: [null] },
- { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '用 `theme list` + `theme add <slug>` 从内置主题或已安装集成提供的主题开始;重名时传 `--package`。也可以用 defineTheme 从零编写。只覆盖与默认值不同的令牌。' }, null, { type: 'prose', text: '`astryx theme template` 会写入 theme.template.ts:带注释的完整参考,涵盖每个 defineTheme 字段、令牌族和覆盖语法,并标明打印各自参考的 CLI 命令。' }] },
+ { section: 'Theme Props', title: 'Theme 属性', content: [{ type: 'prose', text: "`<Theme>` 接受 `theme`(必填)、`mode`(默认 `'system'`,也可以是 `'light'` 或 `'dark'`)和 `children`。运行 `astryx component Theme` 查看全部属性。" }] },
+ { section: 'Custom themes', title: '自定义主题', content: [{ type: 'prose', text: '用 `theme list` + `theme add <slug>` 从内置主题或已安装集成提供的主题开始;重名时传 `--package`。也可以用 defineTheme 从零编写。只覆盖与默认值不同的令牌。' }, null, { type: 'prose', text: '`astryx theme template` 会写入 theme.template.ts:带注释的完整参考,涵盖每个 defineTheme 字段、令牌族和覆盖语法,并标明打印各自参考的 CLI 命令。' }] },
{ section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置(color、typography、radius、motion)+ 显式令牌覆盖 + 组件覆盖。color 通过 HCT 从 accent 派生完整调色板;accent 接受单个十六进制值或 [light, dark] 元组(每个模式使用各自的种子色)。tokens 覆盖按令牌逐个生效;--color-on-accent 始终由 color.accent 计算得出,因此优先使用元组 accent 而不是覆盖 --color-accent。' }, null, null] },
- { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, { type: 'prose', text: '当前 theme build 仅在检测到 icons: 字段使用的具名导入时,才在生成的模块中导入图标注册表;它不会编译注册表模块。defineTheme 在运行时接受的内联注册表(包括本地常量)目前会在构建产物中被省略。使用此构建流程时,请把注册表移到独立模块并使用具名导入。以下示例适用于使用 React 和 lucide-react 的注册表。' }, null, { type: 'prose', text: '上例中生成的主题从 dist 导入 ./icons.mjs。如果跳过第二条命令,theme build 仍可能成功,但加载或打包生成的模块都会因缺少 dist/icons.mjs 而失败。--icons-specifier 只更改生成的导入,不会创建或验证目标文件。路径应相对于生成的 JS 文件可解析。将 react 和图标库标记为 external,避免在注册表中重复打包这些依赖。' }, { type: 'prose', text: '不传 --icons-specifier 时,会原样保留检测到的源码导入路径。默认不传 --out 时,打包器可以把无扩展名的 ./icons 解析为旁边的 icons.tsx;Node ESM 不执行这种查找,会报 ERR_MODULE_NOT_FOUND。用 --out 移动输出位置也会改变相对导入的解析位置;使用打包器并不意味着它能自动找到原来的源码。' }, null, null, null] },
+ { section: 'Build a theme', title: '构建主题', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }] },
+ { section: 'Built themes with an icon registry', title: '带图标注册表的构建主题', content: [{ type: 'prose', text: '当前 theme build 仅在检测到 icons: 字段使用的具名导入时,才在生成的模块中导入图标注册表;它不会编译注册表模块。defineTheme 在运行时接受的内联注册表(包括本地常量)目前会在构建产物中被省略。使用此构建流程时,请把注册表移到独立模块并使用具名导入。以下示例适用于使用 React 和 lucide-react 的注册表。' }, null, { type: 'prose', text: '上例中生成的主题从 dist 导入 ./icons.mjs。如果跳过第二条命令,theme build 仍可能成功,但加载或打包生成的模块都会因缺少 dist/icons.mjs 而失败。--icons-specifier 只更改生成的导入,不会创建或验证目标文件。路径应相对于生成的 JS 文件可解析。将 react 和图标库标记为 external,避免在注册表中重复打包这些依赖。' }, { type: 'prose', text: '不传 --icons-specifier 时,会原样保留检测到的源码导入路径。默认不传 --out 时,打包器可以把无扩展名的 ./icons 解析为旁边的 icons.tsx;Node ESM 不执行这种查找,会报 ERR_MODULE_NOT_FOUND。用 --out 移动输出位置也会改变相对导入的解析位置;使用打包器并不意味着它能自动找到原来的源码。' }] },
{ section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时:useInsertionEffect 在客户端注入样式。构建:静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
- { section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'(默认)跟随系统偏好。" }, null, null] },
- { section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
- { section: 'useTheme Hook', title: 'useTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式,在应用层管理状态并传递给 <Theme>。' }] },
+ { section: 'Dark mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'(默认)跟随系统偏好。" }, null, null] },
+ { section: 'Nested themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
+ { section: 'useTheme Hook', title: 'useTheme 钩子', content: [null, null, { type: 'prose', text: '普通样式优先使用 CSS 变量、StyleX 令牌导入、xstyle 或 className。useTheme() 是只读的:要更改主题或模式,在应用层管理状态并传递给 <Theme>。' }] },
],
};
diff --git a/packages/cli/assets/docs/tokens.doc.dense.mjs b/packages/cli/assets/docs/tokens.doc.dense.mjs
index ae5d04eb13..30e7e2e743 100644
--- a/packages/cli/assets/docs/tokens.doc.dense.mjs
+++ b/packages/cli/assets/docs/tokens.doc.dense.mjs
@@ -3,10 +3,10 @@
/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
export const docsDense = {
- description: 'spacing/color/radius/type/shadow token ref',
+ description: 'color/data-viz/syntax/spacing/size/radius/shadow/motion/type token ref',
sections: [
{ section: 'Color Tokens', title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },
- { section: 'Spacing Tokens', title: 'Spacing', content: [{ type: 'prose', text: 'defined in tokens.stylex.ts. gap props use space0-space12.' }, null] },
+ { section: 'Spacing Tokens', title: 'Spacing', content: [{ type: 'prose', text: 'padding/gap/margin scale. gap props take steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.' }, null] },
{ section: 'Size Tokens', title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },
{ section: 'Radius Tokens', title: 'Radius', content: [null] },
{ section: 'Shadow Tokens', title: 'Elevation', content: [null] },
diff --git a/packages/cli/assets/docs/tokens.doc.mjs b/packages/cli/assets/docs/tokens.doc.mjs
index 0572576c50..6b98fb7ad2 100644
--- a/packages/cli/assets/docs/tokens.doc.mjs
+++ b/packages/cli/assets/docs/tokens.doc.mjs
@@ -1,9 +1,10 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
// AUTO-GENERATED — do not edit manually.
-// Source: packages/core/src/theme/tokens.stylex.ts
+// Source: packages/core/src/theme/tokens.stylex.ts,
+// domainTokens/dataTokens.ts, and syntax/tokens.ts
// Run: node scripts/generate-token-docs.mjs
-// Total: 188 tokens across 13 categories.
+// Total: 258 tokens across 15 categories.
/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
@@ -11,7 +12,12 @@ export const docs = {
"name": "tokens",
"title": "All Tokens",
"category": "foundations",
- "description": "Complete reference for spacing, color, radius, typography, shadow, motion, and size tokens.",
+ "description": "Complete reference for color, data visualization, syntax, spacing, size, border, focus, radius, shadow, motion, and typography tokens.",
+ "keywords": [
+ "design tokens",
+ "css variables",
+ "custom properties"
+ ],
"sections": [
{
"title": "Color Tokens",
@@ -45,8 +51,8 @@ export const docs = {
],
[
"--color-neutral",
- "light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))",
- "light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))"
+ "rgba(5, 54, 89, 0.1)",
+ "rgba(223, 226, 229, 0.2)"
],
[
"--color-background-surface",
@@ -215,8 +221,8 @@ export const docs = {
],
[
"--color-shadow",
- "light-dark(rgba(5, 54, 89, 0.1), rgba(0, 0, 0, 0.3))",
- "light-dark(rgba(5, 54, 89, 0.1), rgba(0, 0, 0, 0.3))"
+ "rgba(5, 54, 89, 0.1)",
+ "rgba(0, 0, 0, 0.3)"
],
[
"--color-tint-hover",
@@ -428,6 +434,381 @@ export const docs = {
],
"previewType": "swatch"
},
+ {
+ "title": "Data Visualization Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps."
+ },
+ {
+ "type": "table",
+ "headers": [
+ "Token",
+ "Light",
+ "Dark"
+ ],
+ "rows": [
+ [
+ "--color-data-categorical-blue",
+ "#0171E3",
+ "#0171E3"
+ ],
+ [
+ "--color-data-categorical-orange",
+ "#EB6E00",
+ "#EB6E00"
+ ],
+ [
+ "--color-data-categorical-purple",
+ "#6B1EFD",
+ "#6B1EFD"
+ ],
+ [
+ "--color-data-categorical-green",
+ "#0B991F",
+ "#0B991F"
+ ],
+ [
+ "--color-data-categorical-pink",
+ "#F351C0",
+ "#F351C0"
+ ],
+ [
+ "--color-data-categorical-cyan",
+ "#0171A4",
+ "#0171A4"
+ ],
+ [
+ "--color-data-categorical-red",
+ "#F5394F",
+ "#F5394F"
+ ],
+ [
+ "--color-data-categorical-teal",
+ "#08A3A3",
+ "#08A3A3"
+ ],
+ [
+ "--color-data-categorical-brown",
+ "#965E03",
+ "#965E03"
+ ],
+ [
+ "--color-data-categorical-indigo",
+ "#6F8AFF",
+ "#6F8AFF"
+ ],
+ [
+ "--color-data-neutral",
+ "#8494A3",
+ "#8C939B"
+ ],
+ [
+ "--color-data-blue-5",
+ "#02165E",
+ "#02165E"
+ ],
+ [
+ "--color-data-blue-4",
+ "#004CBC",
+ "#004CBC"
+ ],
+ [
+ "--color-data-blue-3",
+ "#2694FE",
+ "#2694FE"
+ ],
+ [
+ "--color-data-blue-2",
+ "#78BEFF",
+ "#78BEFF"
+ ],
+ [
+ "--color-data-blue-1",
+ "#DBECFF",
+ "#DBECFF"
+ ],
+ [
+ "--color-data-shamrock-5",
+ "#0B603D",
+ "#0B603D"
+ ],
+ [
+ "--color-data-shamrock-4",
+ "#138546",
+ "#138546"
+ ],
+ [
+ "--color-data-shamrock-3",
+ "#24BB5E",
+ "#24BB5E"
+ ],
+ [
+ "--color-data-shamrock-2",
+ "#8EF7AA",
+ "#8EF7AA"
+ ],
+ [
+ "--color-data-shamrock-1",
+ "#D6FEE4",
+ "#D6FEE4"
+ ],
+ [
+ "--color-data-orange-5",
+ "#A13F04",
+ "#A13F04"
+ ],
+ [
+ "--color-data-orange-4",
+ "#D66100",
+ "#D66100"
+ ],
+ [
+ "--color-data-orange-3",
+ "#FD9537",
+ "#FD9537"
+ ],
+ [
+ "--color-data-orange-2",
+ "#FDB876",
+ "#FDB876"
+ ],
+ [
+ "--color-data-orange-1",
+ "#FFE6CF",
+ "#FFE6CF"
+ ],
+ [
+ "--color-data-pink-5",
+ "#8E1073",
+ "#8E1073"
+ ],
+ [
+ "--color-data-pink-4",
+ "#D123A1",
+ "#D123A1"
+ ],
+ [
+ "--color-data-pink-3",
+ "#F989D3",
+ "#F989D3"
+ ],
+ [
+ "--color-data-pink-2",
+ "#FEADE3",
+ "#FEADE3"
+ ],
+ [
+ "--color-data-pink-1",
+ "#FCE3F4",
+ "#FCE3F4"
+ ],
+ [
+ "--color-data-purple-5",
+ "#3E0697",
+ "#3E0697"
+ ],
+ [
+ "--color-data-purple-4",
+ "#6B1EFD",
+ "#6B1EFD"
+ ],
+ [
+ "--color-data-purple-3",
+ "#9081FF",
+ "#9081FF"
+ ],
+ [
+ "--color-data-purple-2",
+ "#B3B0FE",
+ "#B3B0FE"
+ ],
+ [
+ "--color-data-purple-1",
+ "#E8E8FB",
+ "#E8E8FB"
+ ],
+ [
+ "--color-data-red-5",
+ "#9D0519",
+ "#9D0519"
+ ],
+ [
+ "--color-data-red-4",
+ "#D31130",
+ "#D31130"
+ ],
+ [
+ "--color-data-red-3",
+ "#FB7D87",
+ "#FB7D87"
+ ],
+ [
+ "--color-data-red-2",
+ "#FFB2B8",
+ "#FFB2B8"
+ ],
+ [
+ "--color-data-red-1",
+ "#FEE4E6",
+ "#FEE4E6"
+ ],
+ [
+ "--color-data-teal-5",
+ "#08767D",
+ "#08767D"
+ ],
+ [
+ "--color-data-teal-4",
+ "#0C9293",
+ "#0C9293"
+ ],
+ [
+ "--color-data-teal-3",
+ "#0DB7AF",
+ "#0DB7AF"
+ ],
+ [
+ "--color-data-teal-2",
+ "#6CE6D8",
+ "#6CE6D8"
+ ],
+ [
+ "--color-data-teal-1",
+ "#D7FCF8",
+ "#D7FCF8"
+ ],
+ [
+ "--color-data-yellow-5",
+ "#8A5001",
+ "#8A5001"
+ ],
+ [
+ "--color-data-yellow-4",
+ "#D69804",
+ "#D69804"
+ ],
+ [
+ "--color-data-yellow-3",
+ "#FBCE03",
+ "#FBCE03"
+ ],
+ [
+ "--color-data-yellow-2",
+ "#FCEC85",
+ "#FCEC85"
+ ],
+ [
+ "--color-data-yellow-1",
+ "#FDF6BA",
+ "#FDF6BA"
+ ],
+ [
+ "--color-data-gray-5",
+ "#25363F",
+ "#333338"
+ ],
+ [
+ "--color-data-gray-4",
+ "#5D6C7B",
+ "#666A72"
+ ],
+ [
+ "--color-data-gray-3",
+ "#AFB9C4",
+ "#B2B8BE"
+ ],
+ [
+ "--color-data-gray-2",
+ "#CCD3DB",
+ "#D0D3D6"
+ ],
+ [
+ "--color-data-gray-1",
+ "#F1F4F7",
+ "#F2F4F6"
+ ]
+ ]
+ }
+ ],
+ "previewType": "swatch"
+ },
+ {
+ "title": "Syntax Tokens",
+ "content": [
+ {
+ "type": "prose",
+ "text": "Code highlighting colors used by CodeBlock. Each defaults to a palette token, so syntax colors follow the theme; defineTheme({syntax}) sets a syntax theme instead."
+ },
+ {
+ "type": "table",
+ "headers": [
+ "Token",
+ "Value"
+ ],
+ "rows": [
+ [
+ "--color-syntax-keyword",
+ "var(--color-text-accent)"
+ ],
+ [
+ "--color-syntax-string",
+ "var(--color-text-green)"
+ ],
+ [
+ "--color-syntax-comment",
+ "var(--color-text-secondary)"
+ ],
+ [
+ "--color-syntax-number",
+ "var(--color-text-orange)"
+ ],
+ [
+ "--color-syntax-function",
+ "var(--color-text-blue)"
+ ],
+ [
+ "--color-syntax-type",
+ "var(--color-text-purple)"
+ ],
+ [
+ "--color-syntax-variable",
+ "var(--color-text-primary)"
+ ],
+ [
+ "--color-syntax-operator",
+ "var(--color-text-cyan)"
+ ],
+ [
+ "--color-syntax-constant",
+ "var(--color-text-orange)"
+ ],
+ [
+ "--color-syntax-tag",
+ "var(--color-text-red)"
+ ],
+ [
+ "--color-syntax-attribute",
+ "var(--color-text-teal)"
+ ],
+ [
+ "--color-syntax-property",
+ "var(--color-text-cyan)"
+ ],
+ [
+ "--color-syntax-punctuation",
+ "var(--color-text-secondary)"
+ ],
+ [
+ "--color-syntax-background",
+ "var(--color-background-muted)"
+ ]
+ ]
+ }
+ ],
+ "previewType": "swatch"
+ },
{
"title": "Spacing Tokens",
"content": [
@@ -1098,7 +1479,7 @@ export const docs = {
"type": "code",
"lang": "tsx",
"label": "Using token imports",
- "code": "import * as stylex from '@stylexjs/stylex';\nimport {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core';\n\nconst styles = stylex.create({\n card: {\n padding: spacingVars['--spacing-4'],\n backgroundColor: colorVars['--color-background-surface'],\n borderRadius: radiusVars['--radius-container'],\n },\n button: {\n height: sizeVars['--size-element-md'],\n },\n});"
+ "code": "import * as stylex from '@stylexjs/stylex';\nimport {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';\n\nconst styles = stylex.create({\n card: {\n padding: spacingVars['--spacing-4'],\n backgroundColor: colorVars['--color-background-surface'],\n borderRadius: radiusVars['--radius-container'],\n },\n button: {\n height: sizeVars['--size-element-md'],\n },\n});"
},
{
"type": "prose",
diff --git a/packages/cli/assets/docs/tokens.doc.zh.mjs b/packages/cli/assets/docs/tokens.doc.zh.mjs
index bbb8e7788b..0d8916dc20 100644
--- a/packages/cli/assets/docs/tokens.doc.zh.mjs
+++ b/packages/cli/assets/docs/tokens.doc.zh.mjs
@@ -3,10 +3,10 @@
/** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
export const docsZh = {
- description: '间距、颜色、圆角、排版和阴影设计令牌参考。',
+ description: '颜色、数据可视化、语法高亮、间距、尺寸、圆角、阴影、动效和排版设计令牌参考。',
sections: [
{ section: 'Color Tokens', title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色,支持 light-dark() 自动切换模式。' }, null, null, null] },
- { section: 'Spacing Tokens', title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, null] },
+ { section: 'Spacing Tokens', title: '间距令牌', content: [{ type: 'prose', text: '用于内边距、间距和外边距的刻度。组件 gap 属性接受步长 0、0.5、1、1.5、2、3、4、5、6、8、10。' }, null] },
{ section: 'Size Tokens', title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },
{ section: 'Radius Tokens', title: '圆角令牌', content: [null] },
{ section: 'Shadow Tokens', title: '阴影令牌', content: [null] },
diff --git a/packages/cli/assets/docs/tree/add-a-component.doc.mjs b/packages/cli/assets/docs/tree/add-a-component.doc.mjs
new file mode 100644
index 0000000000..e2ed1f648b
--- /dev/null
+++ b/packages/cli/assets/docs/tree/add-a-component.doc.mjs
@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/add-a-component`: choose a
+ * component name and generate its first source and doc files.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'add-a-component',
+ placement: {parent: 'namespace:components', slot: 'guides', order: 10},
+ title: 'Add a component',
+ category: 'guide',
+ description:
+ 'Choose a stable component name and generate its source, doc, package export, and integration entry.',
+ sections: [
+ {
+ id: 'pick-a-component-name',
+ title: 'Pick a component name',
+ content: [
+ {
+ type: 'prose',
+ text: 'Choose a unique PascalCase name, such as `AcmeCarousel`. The name is the component\'s public export and CLI identity, so keep it stable. Use `displayName` when you only want to change the label people read.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Prefer a name that describes the component\'s purpose in your product.',
+ 'Avoid a Core component name unless you are deliberately replacing that component.',
+ 'If replacement is truly required, read {@link generic:replace-a-core-component}.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'run-the-add-command',
+ title: 'Run the add command',
+ content: [
+ {
+ type: 'prose',
+ text: 'Run `integration add component` in your package with the name. It writes the component, its doc file, and the public import apps use.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add component AcmeCarousel',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `component contribution added
+
+[ok] AcmeCarousel
+
+Declare component root ./components in astryx.integration.mjs.
+
+- components/AcmeCarousel.doc.mjs
+- components/AcmeCarousel.tsx
+- package.json
+- astryx.integration.mjs`,
+ },
+ {
+ type: 'prose',
+ text: '`integration add` starts with one source export and one single-component `.doc.mjs`. Keep that shape for one public component. If the source exposes a family, choose the correct shape in {@link namespace:describe-the-component}.',
+ },
+ {
+ type: 'prose',
+ text: 'Add never overwrites a file, and `--dry-run` shows what it would write. Component commands read Core, so install `@astryxdesign/core` in the package first ({@link generic:quick-start}).',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/add-a-theme.doc.mjs b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
new file mode 100644
index 0000000000..1c87b7f0ab
--- /dev/null
+++ b/packages/cli/assets/docs/tree/add-a-theme.doc.mjs
@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/add-a-theme`:
+ * scaffold a theme in a package — blank, or forked from an existing theme.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'add-a-theme',
+ placement: {parent: 'namespace:themes', slot: 'guides', order: 10},
+ title: 'Add a theme',
+ category: 'guide',
+ description:
+ 'Scaffold a theme in your package — blank, or forked from an existing theme.',
+ sections: [
+ {
+ id: 'add-a-theme',
+ title: 'Add a theme',
+ content: [
+ {
+ type: 'prose',
+ text: 'Run `integration add theme` with a lowercase kebab-case slug. It writes a blank theme — a `defineTheme` skeleton and its descriptor — into a folder named after the slug.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add theme ocean',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `theme contribution added
+
+[ok] ocean
+
+Declare theme root ./themes in astryx.integration.mjs.
+
+- themes/ocean/oceanTheme.ts
+- themes/ocean/oceanTheme.doc.mjs
+- package.json
+- astryx.integration.mjs`,
+ },
+ {
+ type: 'prose',
+ text: "`oceanTheme.ts` exports `oceanTheme`, a `defineTheme` source. `oceanTheme.doc.mjs` describes it with `type: 'theme'`, `name`, `displayName`, `description`, and `maintained`; `theme list` shows its `name`, `description`, and `maintained`. Every field is in {@link generic:authoring}.",
+ },
+ {
+ type: 'prose',
+ text: 'The source ships in your package. An app installs the package and applies the theme — it is not copied; see {@link generic:use-a-theme-in-an-app}.',
+ },
+ ],
+ },
+ {
+ id: 'start-from-an-existing-theme',
+ title: 'Start from an existing theme',
+ content: [
+ {
+ type: 'prose',
+ text: 'To begin from an existing theme instead of a blank one, pass `--from`. It copies that theme as your starting point to diverge from — a fork, with no link back.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add theme ocean --from neutral',
+ },
+ {
+ type: 'prose',
+ text: 'Use `--from` when you want to change a lot. For a small change that should stay linked to a base theme, use `extends` instead ({@link generic:define-the-theme}).',
+ },
+ ],
+ },
+ {
+ id: 'ship-several-themes',
+ title: 'Ship several themes',
+ content: [
+ {
+ type: 'prose',
+ text: 'A package can ship more than one theme. Run `integration add theme` once per slug; each theme gets its own folder and descriptor, and `theme list` shows them all.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/add-a-topic.doc.mjs b/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
new file mode 100644
index 0000000000..6edd4e39b4
--- /dev/null
+++ b/packages/cli/assets/docs/tree/add-a-topic.doc.mjs
@@ -0,0 +1,144 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/add-a-topic`: add a doc topic to an
+ * integration package, write its sections, and pick the doc kind for each
+ * thing the package ships.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'add-a-topic',
+ placement: {parent: 'namespace:docs', slot: 'guides', order: 10},
+ title: 'Add a topic',
+ category: 'guide',
+ keywords: ['add a doc', 'integration docs', 'write docs'],
+ description: 'Add a doc topic to your package and write its sections.',
+ sections: [
+ {
+ id: 'add-a-topic-with-the-cli',
+ title: 'Add a topic with the CLI',
+ content: [
+ {
+ type: 'prose',
+ text: 'Run `integration add doc` in your package to add a topic. It writes the topic file and declares the `docs` root in `astryx.integration.mjs`.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add doc deploying\n# Read it the way an app will\nnpx astryx docs deploying',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'doc contribution added\n\n[ok] deploying\n\nDeclare doc root ./docs in astryx.integration.mjs.\n\n- docs/deploying.doc.mjs\n- astryx.integration.mjs',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Name the topic in lowercase kebab-case, such as `deploying`. Readers type the name as a command argument, so it holds only letters, digits, `_`, and `-`.',
+ 'Keep the name stable: readers and links find the topic by it.',
+ 'Pick a name no Core topic uses. To take over or add to a Core topic, see {@link generic:extend-or-replace}.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'write-the-sections',
+ title: 'Write the sections',
+ content: [
+ {
+ type: 'prose',
+ text: "A topic is a plain object with `type: 'generic'`, a `name`, a `title`, a one-sentence `description`, and `sections`. Each section has a `title` and a list of `content` blocks.",
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'docs/deploying.doc.mjs',
+ code: "/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n type: 'generic',\n name: 'deploying',\n title: 'Deploying',\n description: 'Ship an app built with Acme widgets.',\n sections: [{\n id: 'build-before-you-ship',\n title: 'Build before you ship',\n content: [\n {type: 'prose', text: 'Build the app, then upload the `dist` folder.'},\n {type: 'code', lang: 'bash', code: 'npm run build'},\n {type: 'list', style: 'unordered', items: ['Keep `dist` out of git.']},\n {type: 'table', headers: ['Variable', 'Value'], rows: [['`NODE_ENV`', '`production`']]},\n ],\n }],\n};",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Content blocks are `prose`, `code`, `list`, and `table`, as shown; `heading`, with a `level` from 3 to 6 and a `text`; and `token-ref`, which inlines a token table from another topic.',
+ '`id` is optional: a stable key for the section. Without it, the key comes from the title. A stable CLI before 0.7.0 cannot read `id`; see {@link generic:versioning}.',
+ 'Replace the `Overview` placeholder that `integration add` writes. Every field is in {@link generic:authoring}.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'pick-the-doc-kind',
+ title: 'Pick the doc kind',
+ content: [
+ {
+ type: 'prose',
+ text: 'Every doc is a `.doc.mjs` file whose `type` says what it describes. `integration add` writes the right `type` and file for each kind.',
+ },
+ {
+ type: 'table',
+ headers: [
+ 'You document',
+ '`type`',
+ 'File that `integration add` writes',
+ ],
+ rows: [
+ ['A guide or topic', "`'generic'`", '`docs/deploying.doc.mjs`'],
+ [
+ "Your package's docs section",
+ "`'namespace'`",
+ '`docs/acme.doc.mjs`',
+ ],
+ [
+ 'A component',
+ "`'component'`",
+ '`components/AcmeCarousel.doc.mjs`, beside `AcmeCarousel.tsx`',
+ ],
+ [
+ 'A template',
+ "`'page'` or `'block'`",
+ '`templates/acme-dashboard.doc.mjs`, beside `acme-dashboard.tsx`',
+ ],
+ [
+ 'A theme',
+ "`'theme'`",
+ '`themes/ocean/oceanTheme.doc.mjs`, beside `oceanTheme.ts`',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Only guides, topics, and your docs section go in the `docs` root. The others have their own guides: {@link namespace:components}, {@link namespace:templates}, and {@link namespace:themes}.',
+ },
+ ],
+ },
+ {
+ id: 'keep-topics-in-the-docs-root',
+ title: 'Keep topics in the docs root',
+ content: [
+ {
+ type: 'prose',
+ text: 'The `docs` field in `astryx.integration.mjs` names the folder that holds your topics. The CLI reads every `.doc.mjs` file under it, in subfolders too.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'astryx.integration.mjs',
+ code: "export default {\n docs: './docs'\n};",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Readers open a topic by its `name`, not its file name. Name the file after the doc, `<name>.doc.mjs`, so each one is easy to find.',
+ 'A topic with no `placement` is a flat topic: the docs list shows it under Topics, and readers open it by its name.',
+ 'To give your package its own section in the docs tree instead, see {@link generic:sections-and-placement}.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/agent-guidance.doc.mjs b/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
new file mode 100644
index 0000000000..58186b60e6
--- /dev/null
+++ b/packages/cli/assets/docs/tree/agent-guidance.doc.mjs
@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/agent-guidance`: add short lines of
+ * guidance that apps put in front of their AI agents, within the limits.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'agent-guidance',
+ placement: {parent: 'namespace:configuration', slot: 'guides', order: 10},
+ title: 'Agent guidance',
+ category: 'guide',
+ keywords: ['agent docs', 'agents.md'],
+ description:
+ 'Add a few lines of guidance that apps put in front of the AI agents working in their code.',
+ sections: [
+ {
+ id: 'add-a-guidance-line',
+ title: 'Add a line of guidance',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration add agent-doc` adds one line for AI agents that work in apps using your package. Apps show it in their agent file, such as `AGENTS.md`.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: "npx astryx integration add agent-doc 'Use AcmeCarousel for rotating content.'",
+ },
+ {
+ type: 'prose',
+ text: 'The line lands in `agentDocs.append` in your manifest:',
+ },
+ {
+ type: 'code',
+ lang: 'js',
+ code: `// astryx.integration.mjs
+export default {
+ components: './components',
+ agentDocs: {
+ append: ['Use AcmeCarousel for rotating content.'],
+ },
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'Adding the same line again changes nothing. To reword or remove a line, edit `agentDocs.append` by hand.',
+ },
+ ],
+ },
+ {
+ id: 'keep-within-the-limits',
+ title: 'Keep within the limits',
+ content: [
+ {
+ type: 'prose',
+ text: "Every line costs space in each app's agent file, so the CLI keeps guidance short and few. Put detail in your docs instead.",
+ },
+ {
+ type: 'table',
+ headers: ['Limit', 'What happens past it'],
+ rows: [
+ [
+ '8 lines per package',
+ '`integration add` fails: `append may contain at most 8 lines`.',
+ ],
+ [
+ '240 characters per line',
+ '`integration add` fails: `must contain at most 240 Unicode code points`.',
+ ],
+ [
+ '32 lines per app, from all its packages',
+ '`init` writes no agent block and prints `Could not install agent docs.`',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'A line is one line of plain text. Line breaks, control characters, spaces at either end, and managed-block markers such as `<!-- ASTRYX:START -->` are rejected.',
+ },
+ ],
+ },
+ {
+ id: 'see-what-agents-read',
+ title: 'See what agents read',
+ content: [
+ {
+ type: 'prose',
+ text: "An app's `astryx init` writes your lines at the end of its managed agent block, each labeled with your package name. The CLI owns the heading, the labels, and the markers.",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx init --features agents',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `INTEGRATIONS:
+- \`@acme/astryx-widgets\`: Use AcmeCarousel for rotating content.
+<!-- ASTRYX:END -->`,
+ },
+ {
+ type: 'prose',
+ text: 'The block collects lines from every integration the app has installed, with or without an `astryx.config` entry.',
+ },
+ ],
+ },
+ {
+ id: 'refresh-the-block',
+ title: 'Refresh the block in an app',
+ content: [
+ {
+ type: 'prose',
+ text: 'The block changes only when the app runs `init`, or `upgrade --from <version> --apply`. After an app installs a version of your package with new lines, it runs one of them.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `npx astryx init --features agents
+# Or: --from takes the Core version the app had before
+npx astryx upgrade --from 0.7.0 --apply`,
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: '[ok] Agent docs refreshed -> AGENTS.md',
+ },
+ {
+ type: 'prose',
+ text: '`upgrade --apply` prints that line; `init` prints `[ok] AI agent docs installed -> AGENTS.md`. Without `--apply`, `upgrade` only reports `Agent docs differ from the installed Astryx and integration configuration.` It refreshes the block even when Core did not change. See {@link command:upgrade}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/block-template.doc.mjs b/packages/cli/assets/docs/tree/block-template.doc.mjs
new file mode 100644
index 0000000000..330f07db84
--- /dev/null
+++ b/packages/cli/assets/docs/tree/block-template.doc.mjs
@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template/block-template`:
+ * the block-only fields: component relationships and the preview shape.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'block-template',
+ placement: {
+ parent: 'namespace:document-the-template',
+ slot: 'guides',
+ order: 30,
+ },
+ title: 'Block template',
+ category: 'guide',
+ description:
+ 'Describe a smaller composition, choose its preview shape, and connect it to component examples only when that relationship is real.',
+ sections: [
+ {
+ id: 'start-with-a-standalone-block',
+ title: 'Start with a standalone block',
+ content: [
+ {
+ type: 'prose',
+ text: 'Most blocks stand alone. Start with this shape unless the block is specifically the example or showcase for one component.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'templates/acme-stat-card.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+ type: 'block',
+ name: 'acme-stat-card',
+ displayName: 'Acme Stat Card',
+ description:
+ 'A compact metric card with a current value, period delta, and supporting trend. KPI, scorecard, summary, or dashboard statistic.',
+ isReady: false,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Card', 'HStack', 'Text', 'VStack'],
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'Do not add `exampleFor` only because the block uses a component. `componentsUsed` records composition; `exampleFor` declares that one component owns the example.',
+ },
+ ],
+ },
+ {
+ id: 'choose-the-component-relationship',
+ title: 'Choose the component relationship',
+ content: [
+ {
+ type: 'reference',
+ target: 'schema:template-doc',
+ projection: {
+ fields: [
+ 'exampleFor',
+ 'alsoExampleFor',
+ 'alsoShowcaseFor',
+ 'componentsUsed',
+ 'isShowcase',
+ ],
+ },
+ presentation: 'full',
+ },
+ {
+ type: 'prose',
+ text: 'Keep one clear primary owner. Use the `also*` fields only for intentional secondary placements.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'templates/acme-status-card-showcase.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+ type: 'block',
+ name: 'acme-status-card-showcase',
+ displayName: 'Acme Status Card Showcase',
+ description:
+ 'An account-health summary that demonstrates status, trend, and action states for AcmeStatusCard.',
+ isReady: true,
+ exampleFor: 'AcmeStatusCard',
+ isShowcase: true,
+ alsoExampleFor: ['AcmeDashboard'],
+ aspectRatio: 4 / 3,
+ componentsUsed: ['AcmeStatusCard', 'Button', 'HStack', 'VStack'],
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'Then check the package-scoped template list ({@link generic:template-doc-overview}) and confirm the entry carries the relationship you set. `astryx component` does not show integration blocks, so the list is where to check.',
+ },
+ ],
+ },
+ {
+ id: 'choose-a-useful-preview',
+ title: 'Choose a useful preview',
+ content: [
+ {
+ type: 'reference',
+ target: 'schema:template-doc',
+ projection: {fields: ['aspectRatio']},
+ presentation: 'full',
+ },
+ {
+ type: 'prose',
+ text: 'Start from the value for the closest shape below, render the block at that ratio, and adjust it until it neither clips nor leaves large empty space. These are starting points, not contract defaults.',
+ },
+ {
+ type: 'table',
+ headers: ['Block shape', 'Starting value'],
+ rows: [
+ ['Wide navigation, banner, toolbar, or tabs', '`16 / 4`'],
+ ['Square button, badge, avatar, icon, spinner, or status', '`1`'],
+ ['Tall navigation, calendar, list, or tree', '`3 / 4`'],
+ ['Content card, dialog, table, or form group', '`4 / 3`'],
+ ],
+ },
+ {
+ type: 'prose',
+ text: "`scale` affects only Astryx's own block previews. Integration blocks can leave it out.",
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/build-the-template.doc.mjs b/packages/cli/assets/docs/tree/build-the-template.doc.mjs
new file mode 100644
index 0000000000..bbf5057928
--- /dev/null
+++ b/packages/cli/assets/docs/tree/build-the-template.doc.mjs
@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template`:
+ * author portable template source and every asset that source needs.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'build-the-template',
+ placement: {parent: 'namespace:templates', slot: 'build', order: 30},
+ title: 'Build the template',
+ summary:
+ 'Make sure your template works when an app copies it: write the template file, set up its styles, fonts, icons, and images, then package and test it.',
+ keywords: [
+ 'template source',
+ 'portable template',
+ 'template assets',
+ 'template imports',
+ ],
+ slots: {
+ guides: {
+ title: 'Guides',
+ accepts: {kinds: ['generic', 'namespace']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/building-blocks.doc.mjs b/packages/cli/assets/docs/tree/building-blocks.doc.mjs
new file mode 100644
index 0000000000..5a788561bd
--- /dev/null
+++ b/packages/cli/assets/docs/tree/building-blocks.doc.mjs
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations/building-blocks — the kinds you can add. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'building-blocks',
+ placement: {parent: 'namespace:integrations', slot: 'guides', order: 20},
+ title: 'Building Blocks',
+ summary:
+ 'Add components, templates, themes, docs, and codemods, and configure how it behaves.',
+ keywords: [
+ 'building blocks',
+ 'contribute',
+ 'add to an integration',
+ 'contribution kinds',
+ ],
+ slots: {
+ guides: {
+ title: 'Building Blocks',
+ accepts: {kinds: ['generic', 'namespace']},
+ },
+ },
+ blocks: [
+ {
+ type: 'prose',
+ text: 'These are everything you can add to an integration. Mix them however you like. You are not limited to any one thing.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'One component, or a whole library of them.',
+ 'Components together with themes and templates.',
+ 'Only docs, if that is all you need.',
+ 'Agent guidance, so the AI agents in an app follow your library.',
+ 'Codemods that update app code across your breaking changes.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Each kind below is its own guide. Open one to learn, in depth, how to add it and how to keep it healthy as your package grows.',
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/check-your-docs.doc.mjs b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
new file mode 100644
index 0000000000..50ac6f94e6
--- /dev/null
+++ b/packages/cli/assets/docs/tree/check-your-docs.doc.mjs
@@ -0,0 +1,137 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/check-your-docs`: what each check
+ * proves about an integration's docs: the docs check, the read size, and the
+ * CLI peer.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'check-your-docs',
+ placement: {parent: 'namespace:docs', slot: 'guides', order: 60},
+ title: 'Check your docs',
+ category: 'guide',
+ description: 'Check the docs tree, links, overlaps, read size, and CLI peer.',
+ sections: [
+ {
+ id: 'run-the-docs-check',
+ title: 'Run the docs check',
+ content: [
+ {
+ type: 'prose',
+ text: 'Run `doctor integration docs` in your package to check the docs tree, every link, and overlaps with Core topics. Pass a package name to check an installed package.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration docs\n# In an app, check an installed package\nnpx astryx doctor integration docs @acme/astryx-widgets',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'Checking integration docs: @acme/[email protected]\n\n[ok] The docs tree and every link in these docs check out.\n\n[ok] No doc topics overlap with Core.',
+ },
+ {
+ type: 'prose',
+ text: 'Its arguments and exit codes are in {@link command:doctor integration docs}.',
+ },
+ ],
+ },
+ {
+ id: 'know-what-fails-the-check',
+ title: 'Know what fails the check',
+ content: [
+ {
+ type: 'prose',
+ text: 'A doc that does not load, an accidental Core overlap, or a failed namespace or placement fails the check with exit code 1. A link that names no doc only warns, and the exit code stays 0.',
+ },
+ {
+ type: 'table',
+ headers: ['Problem', 'Reported as', 'Exit code'],
+ rows: [
+ [
+ 'A doc that does not load, such as an unknown section field or block type',
+ '`[fail]` `invalid_doc`',
+ '1',
+ ],
+ [
+ "A topic with a Core topic's name and no `replaces` or `extends`",
+ '`[fail]` `accidental`',
+ '1',
+ ],
+ [
+ 'A placement that fails, which hides the doc',
+ '`[fail]` `invalid_doc_graph`',
+ '1',
+ ],
+ ['A link that names no doc', '`[warn]` `invalid_doc_graph`', '0'],
+ [
+ 'A topic that sets `replaces` or `extends`',
+ '`[info]` `replaces` or `extends`',
+ '0',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Read the warnings before you publish. With `--json`, they are in `data.issues`, with `severity: "warning"`.',
+ },
+ ],
+ },
+ {
+ id: 'check-read-size',
+ title: 'Check read size',
+ content: [
+ {
+ type: 'prose',
+ text: '`npx astryx doctor` also measures every read and warns on one over 32 KB. Run it in your package or in an app that installs it; `doctor integration docs` does not check size.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'id: docs-progressive-disclosure\nstatus: [warn]\nlabel: Documentation navigation and size\nmessage: acme/deploying build-before-you-ship: 46 KB, over the 32 KB one read may return',
+ },
+ {
+ type: 'prose',
+ text: 'Split a section over the limit into smaller ones, each with its own key. See {@link command:doctor}.',
+ },
+ ],
+ },
+ {
+ id: 'check-the-cli-peer',
+ title: 'Check the CLI peer',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration verify` fails a package that ships a docs section, a placed guide, or a doc section with an `id` without an `@astryxdesign/cli` peer of `>=0.7.0`. It does not run the docs check, so run both.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration verify',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: '- [fail] The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer. A stable CLI before 0.7.0 does not read the docs tree, and can hide every doc topic the package ships. Declare "@astryxdesign/cli": ">=0.7.0" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required).',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`integration add doc --parent` writes the peer for you.',
+ '`integration verify` passes a hidden guide and an accidental Core overlap; only `doctor integration docs` catches them.',
+ 'Everything else it checks is in {@link command:integration verify} and {@link generic:checks}.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/checks.doc.mjs b/packages/cli/assets/docs/tree/checks.doc.mjs
new file mode 100644
index 0000000000..e0c0dae122
--- /dev/null
+++ b/packages/cli/assets/docs/tree/checks.doc.mjs
@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/checks`: what each package check
+ * proves, what fails and what only warns, and one command to run them all.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'checks',
+ placement: {parent: 'namespace:ship', slot: 'guides', order: 20},
+ title: 'Check an integration',
+ category: 'guide',
+ keywords: ['check before publishing', 'validate an integration', 'ci'],
+ description:
+ 'Pick the check for each problem, learn what fails and what only warns, and run every check in CI.',
+ sections: [
+ {
+ id: 'pick-a-check',
+ title: 'Pick a check',
+ content: [
+ {
+ type: 'prose',
+ text: 'Run these in the package folder. The four `doctor integration` checks read your source; `integration verify` checks the package npm would publish.',
+ },
+ {
+ type: 'table',
+ headers: ['Command', 'Proves', 'Exits 1 when', 'Only warns when'],
+ rows: [
+ [
+ '`npx astryx doctor integration validate`',
+ 'The manifest loads, and each root holds contributions the CLI can read',
+ 'A declared root is missing (`missing_root`), a contribution does not load (`invalid_doc`, `invalid_component`, `invalid_theme`), or two templates in the package replace one Core id (`ambiguous_template_replacement`)',
+ 'The manifest has a key this CLI does not know (`unknown_manifest_key`). With no `astryx.integration.mjs` it prints a hint and exits 0',
+ ],
+ [
+ '`npx astryx doctor integration components`',
+ 'No component name clashes with a Core component',
+ 'Core is not installed (`core_not_found`)',
+ 'A name clashes with Core',
+ ],
+ [
+ '`npx astryx doctor integration templates`',
+ 'Each `replaces` names a Core template of the same type',
+ 'A `replaces` target is missing (`missing_template_replacement_target`) or of the other type (`invalid_template_replacement`), or two templates replace one id (`ambiguous_template_replacement`)',
+ 'A template id matches a Core id without `replaces`',
+ ],
+ [
+ '`npx astryx doctor integration docs`',
+ 'Your docs tree, every link, and topic names against Core',
+ 'A topic takes a Core topic name without `replaces` or `extends`, a doc is invalid (`invalid_doc`), or a namespace or placement fails, which hides the doc (`invalid_doc_graph`)',
+ 'A link names no doc (`invalid_doc_graph`)',
+ ],
+ [
+ '`npx astryx integration verify`',
+ 'The packed package holds every file, shows the same contributions, resolves every public import, and declares the CLI it needs',
+ 'Anything `validate` fails on, no manifest, a file left out of the `.tgz` file, an import that does not resolve, or a missing CLI peer',
+ 'Anything `validate` warns about',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Pass a package name, such as `npx astryx doctor integration validate @acme/astryx-widgets`, to check an installed copy from an app instead.',
+ },
+ ],
+ },
+ {
+ id: 'run-every-check-in-ci',
+ title: 'Run every check in CI',
+ content: [
+ {
+ type: 'prose',
+ text: 'Chain the five checks so the first failure stops the run. Install devDependencies first, because the components check needs Core.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration validate && npx astryx doctor integration components && npx astryx doctor integration templates && npx astryx doctor integration docs && npx astryx integration verify',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`integration verify` runs `validate` but none of the other three: a Core name clash, a `replaces` that names no Core template, a topic that takes a Core name, or a hidden guide still passes it.',
+ 'Warnings keep exit code 0, so read them before you publish.',
+ 'Bare `npx astryx doctor` in the package also warns about a doc section over 32 KB, which no check above measures.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'what-integration-verify-does',
+ title: 'Verify the packed package',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration verify` packs your package with npm, unpacks it into a temporary app, and checks that the app sees everything your source has. It publishes nothing and leaves no `.tgz` file or temporary folder behind.',
+ },
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'It runs `npm pack` the way `npm publish` would, including your `prepack` script.',
+ 'It checks that every contribution file is in the `.tgz` file. A root missing from `files` fails with `Add "templates" to "files" in package.json.`',
+ 'It lists the components, templates, themes, docs, and codemods the temporary app sees, and compares them with your source.',
+ "It resolves each component's `import`, and each template's public import, the way Node does, and checks that the module exports the component, or a default export for a template.",
+ 'It fails a package that ships a docs section, a placed guide, a template `replaces`, a doc section with an `id`, or a theme without an `@astryxdesign/cli` peer of `>=0.7.0`.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: '`integration pack --check`, the name this check had in 0.6, still runs it and prints a note; it will be removed in a later release. The options and exit codes are in {@link command:integration verify}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/codemods.doc.mjs b/packages/cli/assets/docs/tree/codemods.doc.mjs
new file mode 100644
index 0000000000..dffd123d1d
--- /dev/null
+++ b/packages/cli/assets/docs/tree/codemods.doc.mjs
@@ -0,0 +1,147 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/codemods`: add codemods to an
+ * integration package, and know which of them `astryx upgrade` runs in an app.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'codemods',
+ placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 50},
+ title: 'Codemods',
+ category: 'guide',
+ keywords: ['breaking change', 'migrate apps', 'integration codemod'],
+ description:
+ 'Ship codemods that `astryx upgrade` runs to migrate app code, and know which of them an app runs.',
+ sections: [
+ {
+ id: 'add-a-codemod',
+ title: 'Add a codemod',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration add codemod` writes a codemod into a folder named after a version. Apps run it with `astryx upgrade` to migrate their code.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add codemod rename-delay --to 0.7.0',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `codemods/
+ 0.7.0/
+ rename-delay.mjs # the codemod
+ rename-delay.test.mjs # skipped: a test file
+ __tests__/ # skipped: a test folder`,
+ },
+ {
+ type: 'prose',
+ text: "The first add declares `codemods: './codemods'` in `astryx.integration.mjs`. The codemod's id is its path inside the version folder, without the extension: `rename-delay`. An id must be unique across all version folders in the package.",
+ },
+ {
+ type: 'prose',
+ text: 'The loader skips `*.test.*`, `*.spec.*`, and `*.fixture.*` files and everything under `__tests__/` or `__fixtures__/`, so tests can sit beside the codemod. The folder name decides when an app runs the codemod; see "Choose when a codemod runs".',
+ },
+ ],
+ },
+ {
+ id: 'write-the-transform',
+ title: 'Write the transform',
+ content: [
+ {
+ type: 'prose',
+ text: 'A codemod default-exports a plain object with a `type`, a `title`, and a `transform` function. `transform` returns the new source, or `null` to leave the file as it is.',
+ },
+ {
+ type: 'code',
+ lang: 'js',
+ code: `// codemods/0.7.0/rename-delay.mjs
+/** @type {import('@astryxdesign/cli/authoring').AstryxCodemod} */
+export default {
+ type: 'code',
+ title: 'Rename AcmeCarousel delay to interval',
+ description: 'Renames the delay prop on AcmeCarousel.',
+ fileExtensions: ['.tsx', '.jsx'],
+ transform(file, api) {
+ const j = api.jscodeshift;
+ const root = j(file.source);
+ const props = root
+ .find(j.JSXOpeningElement, {name: {name: 'AcmeCarousel'}})
+ .find(j.JSXAttribute, {name: {name: 'delay'}});
+ if (props.size() === 0) return null;
+ props.forEach(path => {
+ path.node.name.name = 'interval';
+ });
+ return root.toSource();
+ },
+};`,
+ },
+ {
+ type: 'prose',
+ text: "`type: 'code'` rewrites the app's source files that match `fileExtensions`. `type: 'config'` rewrites the app's `astryx.config` file instead, and runs before code codemods. `title` shows in the upgrade output, and `api.jscodeshift` is a jscodeshift instance for the file. Every field is in {@link generic:authoring}.",
+ },
+ ],
+ },
+ {
+ id: 'which-codemods-run',
+ title: 'Choose when a codemod runs',
+ content: [
+ {
+ type: 'prose',
+ text: "Two rules decide whether an app's `astryx upgrade` runs your codemods: the app's Core versions, and whether the app names your package.",
+ },
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ "Version folders are matched against the app's `@astryxdesign/core` versions, not your package's version. `upgrade --from <version>` runs each folder above `--from`, up to and including the Core version installed in the app. With Core 0.7.0 installed, `--from 0.6.3` runs `0.7.0/`, and `--from 0.7.0` runs nothing. A folder named after your own release, such as `1.0.0/`, waits until the app has Core 1.0.0.",
+ '`upgrade` runs your codemods only when the app lists your package in `integrations` in its `astryx.config`, or passes `--integration @acme/astryx-widgets`. Having your package installed is not enough: the run then skips your codemods with no warning.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'run-codemods-in-an-app',
+ title: 'Run codemods in an app',
+ content: [
+ {
+ type: 'prose',
+ text: 'An app previews codemods with `astryx upgrade` and writes the changes with `--apply`. Without `--apply`, nothing on disk changes.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `# Preview each codemod and the files it would change
+npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets
+# Write the changes
+npx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply`,
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `Integrations: @acme/astryx-widgets
+1 codemod to run (dry run)
+Applying integration codemods...
+ Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)
+! ~ src/Hero.tsx (would change)`,
+ },
+ {
+ type: 'prose',
+ text: "The count includes Core's codemods for the same versions, which run first and print above `Integrations:`. To run only yours, as when you test it, add `--codemod rename-delay`.",
+ },
+ {
+ type: 'prose',
+ text: '`--from` is the Core version the app had before it upgraded. The run scans `./src` unless the app passes `--path`, and it never writes a file the app marks as generated, vendored, or ignored; see {@link command:upgrade}. `upgrade --list` shows only Core codemods.',
+ },
+ {
+ type: 'prose',
+ text: "An integration manifest has no `hooks` field. Commands that run after codemods, such as a formatter, are the app's to set, in `hooks.postCodemod` in its `astryx.config`.",
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/component-family.doc.mjs b/packages/cli/assets/docs/tree/component-family.doc.mjs
new file mode 100644
index 0000000000..740cfe2723
--- /dev/null
+++ b/packages/cli/assets/docs/tree/component-family.doc.mjs
@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/describe-the-component/component-family`:
+ * author one ComponentDoc for several public exports in a component family.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'component-family',
+ placement: {
+ parent: 'namespace:describe-the-component',
+ slot: 'guides',
+ order: 30,
+ },
+ title: 'Component family',
+ category: 'guide',
+ description:
+ 'Adapt a single-component doc when one module exposes several public components or hooks that belong to one family.',
+ sections: [
+ {
+ id: 'choose-the-family-shape',
+ title: 'Choose the family shape',
+ content: [
+ {
+ type: 'prose',
+ text: 'Start with a complete single-component doc. Convert its top-level `props` into a `components` array only when one source module or component directory exposes several public components or hooks as one family. The family doc keeps the shared usage guidance; each array entry owns one public export.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Put the primary or most-used export first.',
+ 'Use a full entry when this file owns that export\'s description and signature.',
+ 'Use `props` for a component entry. Use `params` and `returns` for a hook entry.',
+ 'Do not add private implementation helpers or exports that people should not use directly.',
+ ],
+ },
+ {
+ type: 'reference',
+ target: 'schema:component-doc',
+ projection: {fields: ['components']},
+ presentation: 'full',
+ },
+ ],
+ },
+ {
+ id: 'document-the-family-inline',
+ title: 'Document the family inline',
+ content: [
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'components/AcmeTabs.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+ type: 'component',
+ name: 'AcmeTabs',
+ displayName: 'Acme Tabs',
+ import: '@acme/astryx-widgets/components/AcmeTabs',
+ usage: {
+ description:
+ 'Switches between related views without leaving the page.',
+ },
+ components: [
+ {
+ name: 'AcmeTabs',
+ displayName: 'Acme Tabs',
+ description: 'Owns selection and lays out the tab list and panels.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: 'The selected tab value.',
+ required: true,
+ },
+ ],
+ },
+ {
+ name: 'AcmeTab',
+ displayName: 'Acme Tab',
+ description: 'Selects one view in Acme Tabs.',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ description: 'The value this tab selects.',
+ required: true,
+ },
+ ],
+ },
+ ],
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'The public module named by `import` must export every component or hook named by a full entry.',
+ },
+ ],
+ },
+ {
+ id: 'give-a-member-its-own-file',
+ title: 'Give a member its own file',
+ content: [
+ {
+ type: 'prose',
+ text: 'When one family member needs its own doc, replace its full entry with `{name: \'MemberName\'}` and move the details into a sibling doc. The parent keeps the family relationship without copying the child\'s content. Continue with {@link generic:subcomponent}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/component-imports.doc.mjs b/packages/cli/assets/docs/tree/component-imports.doc.mjs
new file mode 100644
index 0000000000..2c173db02b
--- /dev/null
+++ b/packages/cli/assets/docs/tree/component-imports.doc.mjs
@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/component-imports`: make an
+ * integration component's documented import resolve from the packed package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'component-imports',
+ placement: {parent: 'namespace:components', slot: 'guides', order: 30},
+ title: 'Resolve the import',
+ category: 'guide',
+ description:
+ 'Keep the component doc import and package exports map aligned, then verify the packed package.',
+ sections: [
+ {
+ id: 'export-the-component',
+ title: 'Export the component',
+ content: [
+ {
+ type: 'prose',
+ text: 'Apps copy the component doc\'s `import` field into their code, so that exact specifier must resolve from your packed package. `integration add` writes it together with an `exports` entry in package.json.',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'package.json',
+ code: `"exports": {
+ "./components/AcmeCarousel": "./components/AcmeCarousel.tsx"
+}`,
+ },
+ {
+ type: 'prose',
+ text: 'Add writes the entry only when package.json already has an `exports` map, so start every package with `"exports": {}`.',
+ },
+ ],
+ },
+ {
+ id: 'verify-the-packed-import',
+ title: 'Verify the packed import',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration verify` installs the packed package in a temporary app, resolves each documented import, and checks that the module exports the documented component name.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration verify',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`component_import_unresolvable` means the exports map has no entry for the documented import.',
+ '`component_export_missing` means the module does not export the documented name, or package.json has no exports map.',
+ '`typescript_extension_in_specifier` means the public import ends in `.ts` or `.tsx`.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'To import from the package root, set `import: \'@acme/astryx-widgets\'` and re-export the component from the file that `exports["."]` points to. See {@link command:integration verify}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/components.doc.mjs b/packages/cli/assets/docs/tree/components.doc.mjs
new file mode 100644
index 0000000000..9e9bab4003
--- /dev/null
+++ b/packages/cli/assets/docs/tree/components.doc.mjs
@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components`: guides for adding and
+ * documenting components in an integration package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'components',
+ placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 10},
+ title: 'Components',
+ summary:
+ 'Add components to an integration, document their public contract, and make them work in every app that installs the package.',
+ keywords: ['integration component', 'ship a component', 'component docs'],
+ slots: {
+ guides: {
+ title: 'Components',
+ accepts: {kinds: ['generic', 'namespace']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/configuration.doc.mjs b/packages/cli/assets/docs/tree/configuration.doc.mjs
new file mode 100644
index 0000000000..4b57c9e334
--- /dev/null
+++ b/packages/cli/assets/docs/tree/configuration.doc.mjs
@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations/building-blocks/configuration — set how your integration behaves. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'configuration',
+ placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 60},
+ title: 'Configuration',
+ summary:
+ 'Set how your integration behaves in an app: agent guidance, debug and gap reports, and more as it grows.',
+ keywords: ['configuration', 'agent guidance', 'debug', 'gap reports'],
+ slots: {
+ guides: {title: 'Configuration', accepts: {kinds: ['generic', 'namespace']}},
+ },
+ blocks: [
+ {
+ type: 'prose',
+ text: 'Beyond the things you ship, an integration can set how it behaves in an app: the guidance it gives the AI agents working there, and the record it keeps of each CLI run. Open one below to set it up.',
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
new file mode 100644
index 0000000000..486a84ec08
--- /dev/null
+++ b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs
@@ -0,0 +1,182 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/debug-and-gap-reports`: receive a record
+ * of each CLI run with `debug`, and handle `astryx gap-report` with
+ * `gapReport`, both named exports of the integration manifest.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'debug-and-gap-reports',
+ placement: {parent: 'namespace:configuration', slot: 'guides', order: 20},
+ title: 'Debug and gap reports',
+ category: 'guide',
+ keywords: ['gap report', 'debug handler'],
+ description:
+ 'Receive a record of each CLI run in apps that use your package, and handle the gap reports they send about it.',
+ sections: [
+ {
+ id: 'record-runs-with-debug',
+ title: 'Record runs with debug',
+ content: [
+ {
+ type: 'prose',
+ text: 'Export a `debug` function from `astryx.integration.mjs`, and the CLI calls it once for each command run in an app that loads your package.',
+ },
+ {
+ type: 'code',
+ lang: 'js',
+ code: `// astryx.integration.mjs
+import {appendFileSync} from 'node:fs';
+
+/** @param {import('@astryxdesign/cli/authoring').DebugEvent} event */
+export function debug(event) {
+ if (event.outcome !== 'ok') {
+ appendFileSync('acme-failed-runs.ndjson', JSON.stringify(event) + '\\n');
+ }
+}
+
+export default {
+ components: './components',
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'The event is a `DebugEvent` with `command`, `outcome`, `exitCode`, `durationMs`, `error`, and more, its values scrubbed (`redacted: true`). Every field is in {@link generic:authoring}.',
+ },
+ {
+ type: 'prose',
+ text: "Keep the function synchronous: the CLI calls it as the process exits and never waits for a promise. The app's own `debug` handler runs first, then yours. A handler that throws is skipped, and the command's output and exit code stay the same.",
+ },
+ {
+ type: 'prose',
+ text: "An app records every command only when its `astryx.config` names `integrations` or `debug`, as listing your package does. Otherwise your handler runs only for commands that load the app's project, such as `component` and `docs`, and not for `--version` or a mistyped command. In an app whose config names neither word, each of those commands also prints a warning on stderr.",
+ },
+ {
+ type: 'prose',
+ text: '`debug` is a named export, not a manifest field, so a CLI that does not know it ignores it and loads the rest of your manifest.',
+ },
+ ],
+ },
+ {
+ id: 'turn-off-debug-in-an-app',
+ title: 'Turn off debug in an app',
+ content: [
+ {
+ type: 'prose',
+ text: "An app can refuse every integration's `debug` handler and keep its own. It sets `inheritDebug` in its package.json:",
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ code: '{"astryx": {"inheritDebug": false}}',
+ },
+ {
+ type: 'prose',
+ text: 'From then on, your handler no longer runs in that app.',
+ },
+ ],
+ },
+ {
+ id: 'handle-gap-reports',
+ title: 'Handle gap reports',
+ content: [
+ {
+ type: 'prose',
+ text: 'Export a `gapReport` handler, and `astryx gap-report` in an app sends it each gap report, such as a missing component or variant. The handler files the report and returns a receipt.',
+ },
+ {
+ type: 'code',
+ lang: 'js',
+ code: `/** @type {import('@astryxdesign/cli/authoring').GapReportHandler} */
+export const gapReport = {
+ audience: 'public',
+ async handle(report, {signal}) {
+ if (report.target.package !== '@acme/astryx-widgets') return {status: 'skipped'};
+ const body = JSON.stringify(report);
+ const response = await fetch('https://tracker.example.com/issues', {method: 'POST', body, signal});
+ const {url} = await response.json();
+ return {status: 'filed', url};
+ },
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'Every handler in the app gets every report, so check `report.target.package` and skip reports about other packages. The receipt `status` is one of:',
+ },
+ {
+ type: 'table',
+ headers: ['`status`', 'Meaning'],
+ rows: [
+ [
+ '`filed`',
+ 'You created or queued the report. Return `url` or `message`.',
+ ],
+ [
+ '`routed_only`',
+ 'You point the caller to where to file it. `url` is required.',
+ ],
+ ['`skipped`', 'You chose not to act, for example on a duplicate.'],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'The CLI waits 30 seconds, then aborts `signal`. A throw, a timeout, or an invalid receipt fails your delivery, and the command exits 1; the other handlers still run. Like `debug`, `gapReport` is a named export that older CLIs ignore.',
+ },
+ ],
+ },
+ {
+ id: 'ask-before-filing-in-public',
+ title: 'Ask before filing in public',
+ content: [
+ {
+ type: 'prose',
+ text: "Set `audience: 'public'` when your handler writes somewhere the public can read. The CLI runs it only when the caller passes `--confirm-public`; an `'internal'` handler always runs.",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: "npx astryx gap-report AcmeCarousel --category missing_variant --reason 'Need a vertical layout'",
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `handlerType: integration
+handler: @acme/astryx-widgets
+audience: public
+status: consent_required
+message: Rerun with --confirm-public to file this report.`,
+ },
+ {
+ type: 'prose',
+ text: 'With `--confirm-public`, the same delivery reads `status: filed` and shows your `url`. The report goes to the package named by `--package`, else the package that owns the component, else Core.',
+ },
+ ],
+ },
+ {
+ id: 'fall-back-to-issues-url',
+ title: 'Fall back to issuesUrl',
+ content: [
+ {
+ type: 'prose',
+ text: "When the app has no `gapReport` handler at all, the CLI routes the report to the target package's `issuesUrl` from its manifest instead.",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'A GitHub issues URL, such as `https://github.com/acme/widgets/issues`, gets an issue filed with the GitHub CLI, `gh`, once the caller passes `--confirm-public`.',
+ 'Any other URL comes back as a `routed_only` receipt for the caller to open.',
+ 'With no `issuesUrl`, the command fails: `Package "@acme/astryx-widgets" provides neither a report handler nor an issues URL.`',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'One handler anywhere in the app, from the app or from any package, turns the fallback off for every report. See {@link command:gap-report}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/define-the-theme.doc.mjs b/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
new file mode 100644
index 0000000000..25b0a7b0f2
--- /dev/null
+++ b/packages/cli/assets/docs/tree/define-the-theme.doc.mjs
@@ -0,0 +1,118 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/define-the-theme`:
+ * map the palette to tokens, keep light-dark() to colors, and avoid Core internals.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'define-the-theme',
+ placement: {parent: 'namespace:themes', slot: 'guides', order: 30},
+ title: 'Define the theme',
+ category: 'guide',
+ description:
+ 'Point theme tokens at the palette, keep light-dark() to colors, and avoid Core internals.',
+ sections: [
+ {
+ id: 'map-the-palette-to-tokens',
+ title: 'Map the palette to tokens',
+ content: [
+ {
+ type: 'prose',
+ text: 'A theme token is a named slot that Astryx components read for a value — `--color-accent` for the accent color, and so on. Components never read your palette directly; they read tokens. Defining a theme means pointing each token at a palette shade, so the components wear your colors.',
+ },
+ {
+ type: 'prose',
+ text: 'Import the palette in `oceanTheme.ts` and point your tokens at its stops. Each token takes a `[light, dark]` pair — the shade to use in light mode and the one in dark mode.',
+ },
+ {
+ type: 'code',
+ lang: 'ts',
+ code: `// themes/ocean/oceanTheme.ts
+import {defineTheme} from '@astryxdesign/core/theme';
+import {palette} from './tokens/ocean.palette';
+
+const {light, dark} = palette.ocean;
+
+export const oceanTheme = defineTheme({
+ name: 'ocean',
+ tokens: {
+ '--color-accent': [light['45'], dark['70']],
+ },
+});`,
+ },
+ {
+ type: 'prose',
+ text: 'Local imports must stay inside the theme folder. One that leaves it, such as `../../shared/colors`, fails with `invalid_theme`, and the theme disappears from `theme list`. `npx astryx theme template` writes a file that explains every `defineTheme` field. For the full token set, scope selectors, and component theming, read {@link generic:theme}.',
+ },
+ ],
+ },
+ {
+ id: 'build-on-another-theme',
+ title: 'Build on another theme',
+ content: [
+ {
+ type: 'prose',
+ text: 'To base a theme on an existing one, `extends` it: import the base theme and override only the tokens you change. The derived theme keeps a live link to the base and inherits its later changes — unlike `--from`, which forks a copy ({@link generic:add-a-theme}).',
+ },
+ {
+ type: 'code',
+ lang: 'ts',
+ code: `import {defineTheme} from '@astryxdesign/core/theme';
+import {oceanTheme} from './oceanTheme';
+
+export const oceanContrastTheme = defineTheme({
+ name: 'ocean-contrast',
+ extends: oceanTheme,
+ tokens: {
+ '--color-accent': ['#0051a3', '#4aa3ff'],
+ },
+});`,
+ },
+ ],
+ },
+ {
+ id: 'keep-light-dark-to-colors',
+ title: 'Keep light-dark() to colors',
+ content: [
+ {
+ type: 'prose',
+ text: 'Each `[light, dark]` pair compiles to a `light-dark()` value, which switches only colors. Give it colors. For a value that is not a plain color — a gradient — put `light-dark()` on each color stop, not around the whole value: a browser without `light-dark()` drops the declaration, and the stop form is the one that degrades safely.',
+ },
+ ],
+ },
+ {
+ id: 'avoid-core-internals',
+ title: 'Do not set Core private variables',
+ content: [
+ {
+ type: 'prose',
+ text: 'Core private variables start with `--_`, such as `--_field-radius`. They are internals and can change in any Core release, so `theme build` reports each one it finds as an `[error]`. Set the standard CSS property instead — `borderRadius`, `padding` — and let the build emit the internal variable where Core needs it.',
+ },
+ ],
+ },
+ {
+ id: 'declare-the-peers',
+ title: 'Declare the peer dependencies',
+ content: [
+ {
+ type: 'prose',
+ text: 'The theme imports `@astryxdesign/core/theme`, so declare Core as a peer dependency, with the range of Core versions you test the theme against — a range, not an exact version, so a Core patch release does not force a republish. `integration add theme` already declared the optional `@astryxdesign/cli` peer that reads themes:',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ code: `"peerDependencies": {
+ "@astryxdesign/core": "^0.7.0",
+ "@astryxdesign/cli": ">=0.7.0"
+},
+"peerDependenciesMeta": {
+ "@astryxdesign/cli": {"optional": true}
+}`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/describe-the-component.doc.mjs b/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
new file mode 100644
index 0000000000..7ea18f6254
--- /dev/null
+++ b/packages/cli/assets/docs/tree/describe-the-component.doc.mjs
@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/describe-the-component`:
+ * choose and maintain the ComponentDoc shape that matches a component's public
+ * source.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'describe-the-component',
+ placement: {parent: 'namespace:components', slot: 'guides', order: 20},
+ title: 'Describe the component',
+ summary:
+ 'Write and maintain the default component doc, then adapt it when one family owns several exports or a member needs its own file.',
+ keywords: [
+ 'component doc',
+ 'component documentation',
+ 'component family',
+ 'subcomponent',
+ ],
+ slots: {
+ guides: {
+ title: 'Describe the component',
+ accepts: {kinds: ['generic']},
+ },
+ },
+ blocks: [
+ {
+ type: 'prose',
+ text: 'A component\'s `.doc.mjs` is part of the integration\'s public contract, not optional commentary. Astryx uses it for CLI output and search, and people and agents read it to decide whether the component fits and how to use it.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Change the source and its `.doc.mjs` together.',
+ 'Update the doc whenever the public name, import, behavior, props, defaults, examples, or accessibility requirements change.',
+ '`integration verify` checks the doc shape and packed import, but it cannot prove the prose still matches the component.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Every component doc has one stable identity and enough usage guidance for a reader to choose it correctly. Pick the shape below that matches your module.',
+ },
+ {
+ type: 'prose',
+ text: 'After every source or doc change, read the component back. This output is what people and agents receive.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx component AcmeCarousel',
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/docs.doc.mjs b/packages/cli/assets/docs/tree/docs.doc.mjs
new file mode 100644
index 0000000000..9d45ebfd8b
--- /dev/null
+++ b/packages/cli/assets/docs/tree/docs.doc.mjs
@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs`: the guides to writing docs for an
+ * integration package, which join the same docs tree as the CLI's own
+ * (spec:AST-046, spec:AST-047).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'docs',
+ placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 40},
+ title: 'Docs',
+ summary:
+ 'Write docs that ship with your package and that people and agents find by search or one level at a time.',
+ keywords: ['writing docs', 'doc topic', 'docs section', 'placement', 'links'],
+ slots: {
+ guides: {title: 'Guides', accepts: {kinds: ['generic']}},
+ },
+};
diff --git a/packages/cli/assets/docs/tree/document-the-template.doc.mjs b/packages/cli/assets/docs/tree/document-the-template.doc.mjs
new file mode 100644
index 0000000000..5f5dcfc741
--- /dev/null
+++ b/packages/cli/assets/docs/tree/document-the-template.doc.mjs
@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template`:
+ * document page and block templates for discovery and correct reuse.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'document-the-template',
+ placement: {parent: 'namespace:templates', slot: 'build', order: 20},
+ title: 'Document the template',
+ summary:
+ 'Write the doc that helps people and agents find, choose, and trust your template: its name, description, readiness, preview, and any Core replacement.',
+ keywords: [
+ 'template doc',
+ 'template documentation',
+ 'page template',
+ 'block template',
+ ],
+ slots: {
+ guides: {
+ title: 'Guides',
+ accepts: {kinds: ['generic']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/document-the-theme.doc.mjs b/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
new file mode 100644
index 0000000000..ee488f701f
--- /dev/null
+++ b/packages/cli/assets/docs/tree/document-the-theme.doc.mjs
@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/document-the-theme`:
+ * document a theme by extending the core theme topic, not in agent guidance.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'document-the-theme',
+ placement: {parent: 'namespace:themes', slot: 'guides', order: 50},
+ title: 'Document the theme',
+ category: 'guide',
+ description:
+ 'Document a theme by extending the core theme topic, so an app reads it in `astryx docs theme`.',
+ sections: [
+ {
+ id: 'extend-the-theme-topic',
+ title: 'Extend the core theme topic',
+ content: [
+ {
+ type: 'prose',
+ text: 'Give your theme a doc topic that extends the core `theme` topic, so an app that lists your package sees your theme at the end of `astryx docs theme`. Add it with `extends: \'theme\'` ({@link generic:extend-or-replace}).',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ code: `// docs/ocean-theme.doc.mjs
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export default {
+ type: 'generic',
+ name: 'ocean-theme',
+ extends: 'theme',
+ title: 'Ocean theme',
+ description: 'Use the Ocean theme from @acme/astryx-widgets.',
+ sections: [
+ {
+ id: 'use-the-ocean-theme',
+ title: 'Use the Ocean theme',
+ content: [
+ {
+ type: 'prose',
+ text: "Add \`@acme/astryx-widgets\` to the app's dependencies and apply the Ocean theme with \`<Theme theme={oceanTheme}>\`.",
+ },
+ ],
+ },
+ ],
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'Keep the section short: how to add the package, apply the theme ({@link generic:use-a-theme-in-an-app}), and — if the theme uses a custom font — which fonts the app must load ({@link generic:fonts-and-assets}). Extend `theme` rather than a topic another package replaces, or an app that lists that package first drops your section.',
+ },
+ ],
+ },
+ {
+ id: 'not-agent-guidance',
+ title: 'Not agent guidance',
+ content: [
+ {
+ type: 'prose',
+ text: 'Do not put theme usage in `agentDocs`. Agent lines land in every app\'s agent file and are for guidance needed every session; a theme\'s install-and-use steps belong in a doc topic that people and agents read on demand. See {@link generic:agent-guidance}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/export-template-assets.doc.mjs b/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
new file mode 100644
index 0000000000..cde01fe276
--- /dev/null
+++ b/packages/cli/assets/docs/tree/export-template-assets.doc.mjs
@@ -0,0 +1,147 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets`:
+ * expose and include everything a copied template imports, and declare the
+ * packages it needs.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'export-template-assets',
+ placement: {
+ parent: 'namespace:package-and-test',
+ slot: 'guides',
+ order: 10,
+ },
+ title: 'Export the template and assets',
+ category: 'guide',
+ description:
+ 'Make sure the published package contains and exposes everything the copied template imports.',
+ sections: [
+ {
+ id: 'keep-the-generated-template-export',
+ title: 'Keep the generated template export',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration verify` resolves each template through a public package path without a file extension, such as `./templates/acme-dashboard`, and fails when that path is missing.',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'package.json',
+ code: `{
+ "exports": {
+ "./templates/acme-dashboard": "./templates/acme-dashboard.tsx"
+ }
+}`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`integration add` writes this entry when `package.json` has an `exports` map ({@link generic:start-a-template}). Without a map it writes nothing, because creating one would make existing deep imports private. Add the map yourself, then the entry.',
+ 'Keep the public path without `.tsx`. Only the target file ends in `.tsx`.',
+ 'Do not point the entry at a barrel file that loses the template default export.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'export-package-owned-support-files',
+ title: 'Export package-owned support files',
+ content: [
+ {
+ type: 'prose',
+ text: 'Add a public path for every package-owned component, helper, icon, or stylesheet that the copied source imports. Keep implementation-only files private.',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'Relevant package.json entries',
+ code: `{
+ "exports": {
+ "./templates/acme-dashboard": "./templates/acme-dashboard.tsx",
+ "./components/AcmeStatusCard": "./components/AcmeStatusCard.tsx",
+ "./icons/AcmePulseIcon": "./icons/AcmePulseIcon.tsx",
+ "./styles/acme-dashboard.css": "./styles/acme-dashboard.css"
+ }
+}`,
+ },
+ {
+ type: 'prose',
+ text: 'If a block is also loaded directly as a live `.tsx` preview, add a pattern that keeps the extension, such as `"./templates/*.tsx": "./templates/*.tsx"`. Keep the generated entry too; `integration verify` resolves the template through it.',
+ },
+ ],
+ },
+ {
+ id: 'include-every-file',
+ title: 'Include every file',
+ content: [
+ {
+ type: 'prose',
+ text: 'An export can point to a file that npm leaves out. When `package.json#files` exists, list the integration manifest, the templates directory, and every directory the copied file depends on.',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'package.json',
+ code: `{
+ "files": [
+ "astryx.integration.mjs",
+ "templates",
+ "components",
+ "icons",
+ "styles",
+ "assets/fonts"
+ ],
+ "sideEffects": ["**/*.css"]
+}`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`integration add` appends the manifest and templates directory when a `files` list already exists. Add the other directories yourself.',
+ 'If `package.json` sets `sideEffects`, include CSS in it, as above, so bundlers keep side-effect stylesheet imports.',
+ 'Run `npm pack --dry-run` and read the real file list instead of reasoning from the workspace.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'declare-what-the-copied-file-imports',
+ title: 'Declare what the copied file imports',
+ content: [
+ {
+ type: 'prose',
+ text: 'A copied file imports from the app, so the app must install every package it imports. Declare the Astryx peers as described in {@link generic:versioning}. For other packages:',
+ },
+ {
+ type: 'table',
+ headers: ['Field', 'Use it for'],
+ rows: [
+ [
+ '`peerDependencies`',
+ 'Libraries the copied source imports, such as an icon library. List them in `devDependencies` too, so the package itself builds.',
+ ],
+ [
+ '`dependencies`',
+ 'Runtime packages used only by package-owned modules, which should travel with the integration',
+ ],
+ [
+ '`devDependencies`',
+ 'Everything needed to build and test the integration itself',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Use only ranges you test. A package that resolves only because a workspace hoisted it is not declared.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs b/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
new file mode 100644
index 0000000000..5d414a5516
--- /dev/null
+++ b/packages/cli/assets/docs/tree/extend-or-replace.doc.mjs
@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/extend-or-replace`: take over an
+ * existing topic with `replaces`, merge sections into one with `extends`, and
+ * check overlaps with Core topics.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'extend-or-replace',
+ placement: {parent: 'namespace:docs', slot: 'guides', order: 40},
+ title: 'Extend or replace a topic',
+ category: 'guide',
+ description: 'Take over a topic, or merge sections into it.',
+ sections: [
+ {
+ id: 'replace-a-topic',
+ title: 'Replace a topic',
+ content: [
+ {
+ type: 'prose',
+ text: "Set `replaces` to take over an existing topic, such as Core's `getting-started`. Readers who open the old name get your topic.",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add doc acme-getting-started --replaces getting-started\n# The old name now opens your topic\nnpx astryx docs getting-started',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'docs/acme-getting-started.doc.mjs',
+ code: "export default {\n type: 'generic',\n name: 'acme-getting-started',\n replaces: 'getting-started',\n title: 'Acme getting started',\n description: 'Install Acme widgets and render your first carousel.',\n sections: [/* ... */],\n};",
+ },
+ {
+ type: 'prose',
+ text: 'The docs list shows your topic in place of the old one. Because your topic has its own `name`, the old name keeps resolving to it, so links and agents that learned the old name still land on your topic.',
+ },
+ ],
+ },
+ {
+ id: 'extend-a-topic',
+ title: 'Extend a topic',
+ content: [
+ {
+ type: 'prose',
+ text: 'Set `extends` to merge sections into an existing topic instead of owning it. A section with the same key replaces the base section, and a new section is added at the end.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add doc acme-theming --extends theme\nnpx astryx docs theme --index',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'docs/acme-theming.doc.mjs',
+ code: "export default {\n type: 'generic',\n name: 'acme-theming',\n extends: 'theme',\n title: 'Acme theming',\n description: 'Theme an app that uses Acme widgets.',\n sections: [\n {id: 'quick-start', title: 'Quick Start', content: [/* replaces the base section */]},\n {id: 'use-the-ocean-theme', title: 'Use the ocean theme', content: [/* added at the end */]},\n ],\n};",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ "A section's key is its `id`, or a key made from its title. Read the base topic's keys with `--index`.",
+ "The topic keeps the base's title and description, and readers open it by the base's name.",
+ 'Replace the `Overview` placeholder that `integration add` writes, or it is added to the base topic.',
+ "Extend a topic to correct or add to it. A copy made with `replaces` stops getting the owner's fixes.",
+ ],
+ },
+ ],
+ },
+ {
+ id: 'check-overlaps-with-core-topics',
+ title: 'Check overlaps with Core topics',
+ content: [
+ {
+ type: 'prose',
+ text: "A topic sets `replaces` or `extends`, never both, and a placed guide sets neither. A topic that uses a Core topic's name with neither is an accidental conflict: apps keep reading the Core topic.",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration docs',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'severity: [info]\ntopic: acme-getting-started\nrelationship: replaces\ncoreTopic: getting-started\nmessage: Intentional override: "acme-getting-started" replaces the Core topic "getting-started".\n\nseverity: [fail]\ntopic: tokens\nrelationship: accidental\ncoreTopic: tokens\nmessage: Accidental conflict: "tokens" is already a Core topic. Rename it, declare replaces: \'tokens\' to take it over, or declare extends: \'tokens\' to merge sections.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'An intentional overlap prints as `[info]`. An accidental one fails with exit code 1.',
+ 'A topic that sets both fails as `invalid_doc`, and so does a placed guide that sets either one.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs b/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
new file mode 100644
index 0000000000..7446b4ebf5
--- /dev/null
+++ b/packages/cli/assets/docs/tree/fonts-and-assets.doc.mjs
@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/fonts-and-assets`:
+ * name a theme's fonts, and have the app load them (Astryx never loads a font).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'fonts-and-assets',
+ placement: {parent: 'namespace:themes', slot: 'guides', order: 35},
+ title: 'Fonts',
+ category: 'guide',
+ description:
+ 'Name your theme\'s fonts in its tokens, then have the app load them — Astryx never loads a font file.',
+ sections: [
+ {
+ id: 'name-the-font',
+ title: 'Name the font',
+ content: [
+ {
+ type: 'prose',
+ text: 'A theme names its typefaces in `typography`: `body`, `heading`, and `code`, each with a `family` and `fallbacks`. These set the `--font-family-*` tokens every component reads. Always give real `fallbacks` so text stays readable before the font loads, or if it never does. `heading` inherits `family` and `fallbacks` from `body` when you omit them.',
+ },
+ {
+ type: 'code',
+ lang: 'ts',
+ code: `// themes/ocean/oceanTheme.ts
+export const oceanTheme = defineTheme({
+ name: 'ocean',
+ typography: {
+ body: {family: 'Acme Sans', fallbacks: 'system-ui, sans-serif'},
+ code: {family: 'Acme Mono', fallbacks: 'ui-monospace, monospace'},
+ },
+ // ...your tokens
+});`,
+ },
+ {
+ type: 'prose',
+ text: 'The full type scale and font roles are in {@link generic:theme}.',
+ },
+ ],
+ },
+ {
+ id: 'load-the-font-in-the-app',
+ title: 'Load the font in the app',
+ content: [
+ {
+ type: 'prose',
+ text: 'Naming a family does not load it — Astryx never downloads a font file. The app that uses your theme loads the font itself, so your job is to tell your users which families and weights to load, in your theme\'s docs ({@link generic:document-the-theme}). An app loads a font one of two ways:',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Link a hosted stylesheet in the app\'s `<head>` — for example a Google Fonts `<link>` covering every weight the UI uses.',
+ 'Self-host: serve the font files and add an `@font-face` for each weight and style to the app\'s global CSS.',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'css',
+ code: `/* In the app's global CSS, when self-hosting */
+@font-face {
+ font-family: 'Acme Sans';
+ src: url('/fonts/acme-sans.woff2') format('woff2');
+ font-weight: 100 900;
+ font-style: normal;
+ font-display: swap;
+ unicode-range: U+0000-00FF, U+0131, U+0152-0153;
+}`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Load every weight and style the theme uses. Do not let the browser synthesize bold or italic — include the italic face, with the same `unicode-range`s as the roman.',
+ 'Set a `unicode-range` per face so the browser downloads only the subsets it needs.',
+ 'Use `font-display: swap` unless a measured need justifies another value.',
+ 'Serve WOFF2; add another format only when a target browser needs it.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'verify-in-an-app',
+ title: 'Verify in an app',
+ content: [
+ {
+ type: 'prose',
+ text: 'Before publishing, install the package in a clean app, apply the theme, load the fonts, and open it in a browser. The source and the applied result are not the same thing until you look.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Text renders in the named families at every weight and style — the italic face resolves, not a synthesized slant.',
+ 'Every font request succeeds; nothing silently falls back to a system font.',
+ 'Color pairs still meet contrast in both light and dark mode.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs b/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
new file mode 100644
index 0000000000..f6cce3bc61
--- /dev/null
+++ b/packages/cli/assets/docs/tree/generate-a-palette.doc.mjs
@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/generate-a-palette`:
+ * turn a few seed colors into a full light and dark color palette.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'generate-a-palette',
+ placement: {parent: 'namespace:themes', slot: 'guides', order: 20},
+ title: 'Generate a palette',
+ category: 'guide',
+ description:
+ 'Turn a few seed colors into full light and dark color ramps, saved in the theme folder.',
+ sections: [
+ {
+ id: 'generate-a-palette',
+ title: 'Generate a palette',
+ content: [
+ {
+ type: 'prose',
+ text: 'A theme needs dozens of related colors — shades of each brand color for backgrounds, borders, text, and states, in both light and dark mode. A palette is that full set of shades. Rather than hand-pick every one, you name a few seed colors and generate the rest, so the shades stay consistent and keep enough contrast to read.',
+ },
+ {
+ type: 'prose',
+ text: 'You write a short config naming each color family and its seed, then run `theme palette generate`. It expands each seed into a full light and dark ramp — the scale of shades — and writes the result into the theme folder, where your theme tokens point at it (see {@link generic:define-the-theme}). Keep the config and the generated palette together in that folder.',
+ },
+ {
+ type: 'prose',
+ text: 'The smallest config is one color family: an `id` to name it and a `seed` color to grow it from. Save it as `themes/ocean/palette.config.json`:',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ code: '{"families": [{"id": "ocean", "seed": "#0074e2"}]}',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `# Print the palette without writing files
+npx astryx theme palette generate themes/ocean/palette.config.json
+# Write the palette and its receipt
+npx astryx theme palette generate themes/ocean/palette.config.json \\
+ --out themes/ocean/tokens/ocean.palette.ts`,
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `[ok] Wrote themes/ocean/tokens/ocean.palette.ts
+
+[ok] Wrote themes/ocean/tokens/ocean.palette.receipt.json`,
+ },
+ {
+ type: 'prose',
+ text: 'The command writes two files. `ocean.palette.ts` is the palette your theme tokens will read: it exports `black`, `white`, and `palette` — a ramp of 21 shades (stops `0` to `100`) for both `light` and `dark`. The `.receipt.json` beside it records the exact seeds and settings, so you can regenerate the same palette later. A second run leaves both files alone unless you pass `--overwrite`.',
+ },
+ {
+ type: 'prose',
+ text: 'Add `--preview <file>.html` to also get a web page showing every shade, so you can eyeball the palette in a browser. Write it outside `themes/` so it does not ship in your package. The full list of config fields and options is in {@link command:theme palette generate}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs b/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
new file mode 100644
index 0000000000..daa42b7c14
--- /dev/null
+++ b/packages/cli/assets/docs/tree/grade-template-with-agent.doc.mjs
@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/templates/grade-template-with-agent`:
+ * give an agent the canonical rubric and require a reproducible template grade.
+ */
+
+import {TEMPLATE_RUBRIC} from './template-grading-rubric.doc.mjs';
+
+const scorecardRows = TEMPLATE_RUBRIC.categories
+ .map(({title, max}) => `| ${title} | X | ${max} | |`)
+ .join('\n');
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'grade-template-with-agent',
+ placement: {parent: 'namespace:write-good-templates', slot: 'guides', order: 20},
+ title: 'Grade and improve with an agent',
+ category: 'guide',
+ description:
+ 'Give an agent the rubric and evidence it needs to find problems, produce a reproducible scorecard, and improve the template.',
+ sections: [
+ {
+ id: 'give-the-agent-the-rubric',
+ title: 'Give the agent the rubric',
+ content: [
+ {
+ type: 'prose',
+ text: `Grade one exact package revision against template rubric ${TEMPLATE_RUBRIC.version}. Give the agent the template id, the package name, and a clean app that can install the packed package, then use this prompt. Replace every angle-bracket value. The first pass is read-only so the original score and findings stay visible.`,
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ label: 'Agent grading prompt',
+ code: `Grade integration template <id> from <package> at <revision>.
+
+Before scoring:
+1. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates --full\`.
+2. Read \`npx astryx docs cli/integrations/building-blocks/templates/write-good-templates/template-grading-rubric --full\` and every guide it links.
+3. Inspect the template source, its matching .doc.mjs file, package.json exports and files, and astryx.integration.mjs.
+4. Run \`npx astryx integration verify\` in the package.
+5. Follow \`npx astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/test-template-in-app --full\`: install the packed package in the clean app, copy the template, build the app, and render the behavior matrix.
+
+Score all seven rubric categories. Cite file and line evidence for every deduction. Do not award points for a state you did not inspect. If browser or build evidence is unavailable, say so and mark the template not publishable.
+
+Return the rubric version, package revision, numeric score, letter grade, category scorecard, publishable yes/no verdict, detailed findings, and the top three fixes. Treat 100 as the target. Name every remaining deduction and say whether it is an intentional tradeoff or still needs work. Do not edit files during this first pass.`,
+ },
+ ],
+ },
+ {
+ id: 'require-a-scorecard',
+ title: 'Require a scorecard',
+ content: [
+ {
+ type: 'code',
+ lang: 'markdown',
+ code: `# Template grade: <id>
+
+**Rubric:** ${TEMPLATE_RUBRIC.version}
+**Package revision:** <revision>
+**Type:** page | block
+**Grade:** <letter> (<score>/100)
+**Publishable:** yes | no
+
+| Category | Points | Max | Evidence |
+| --- | ---: | ---: | --- |
+${scorecardRows}
+| **Total** | **X** | **100** | |
+
+## Detailed findings
+- <file:line, rubric rule, observed problem, and deduction>
+
+## Publication blockers
+- <failed pack, copy, build, asset, browser, theme, responsive, or input check>
+
+## Top three fixes
+1. <highest-value fix>
+2. <second fix>
+3. <third fix>`,
+ },
+ {
+ type: 'prose',
+ text: `The category scores must add exactly to the total, and the grade comes from the published bands. The verdict is \`yes\` only when the score is ${TEMPLATE_RUBRIC.minimumScore} or higher and every package, copy, build, asset, and rendered-app check passes.`,
+ },
+ ],
+ },
+ {
+ id: 'improve-and-regrade',
+ title: 'Improve and regrade',
+ content: [
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'Fix publication blockers first.',
+ 'Fix every reasonable deduction without hiding it behind helper components or package CSS.',
+ 'Pack again, copy into a fresh app, and have the agent repeat the full grade. Keep the earlier scorecard so the improvement is visible.',
+ 'Stop only when no reasonable fix remains, and record every intentional tradeoff that still costs points.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/help.doc.mjs b/packages/cli/assets/docs/tree/help.doc.mjs
new file mode 100644
index 0000000000..b78aeb0310
--- /dev/null
+++ b/packages/cli/assets/docs/tree/help.doc.mjs
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations/help — find a CLI message and its fix. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'help',
+ placement: {parent: 'namespace:integrations', slot: 'guides', order: 40},
+ title: 'Help',
+ summary: 'Find a CLI message and how to fix it.',
+ keywords: ['help', 'troubleshooting', 'error'],
+ slots: {
+ guides: {title: 'Help', accepts: {kinds: ['generic']}},
+ },
+};
diff --git a/packages/cli/assets/docs/tree/integrations.doc.mjs b/packages/cli/assets/docs/tree/integrations.doc.mjs
index 92a2920eab..4906a4863b 100644
--- a/packages/cli/assets/docs/tree/integrations.doc.mjs
+++ b/packages/cli/assets/docs/tree/integrations.doc.mjs
@@ -1,485 +1,40 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/**
- * @file `astryx docs cli/integrations`: the guide to building an integration
- * package. It lives in the docs tree under the `cli` namespace (spec:AST-046),
- * so its only route is `cli/integrations`.
- */
+/** @file astryx docs cli/integrations — build an integration package. */
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
export const docs = {
- type: 'generic',
+ type: 'namespace',
name: 'integrations',
placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
- title: 'CLI Integrations',
- category: 'guide',
- description:
- 'Build an Astryx integration: an npm package that contributes components, templates, themes, docs, and upgrade codemods.',
-
- sections: [
- {
- title: 'Overview',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: "An integration is an npm package that contributes components, templates, source themes, doc topics, agent guidance, and/or upgrade codemods to a consumer's design-system workflow. Consumers install the package as a direct dependency and Astryx autolinks it; an explicit `astryx.config` entry remains available when the app needs to control ordering.",
- },
- {
- type: 'prose',
- text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run {@link generic:getting-started}.',
- },
- {
- type: 'prose',
- text: 'Every file an integration author writes is documented field by field in {@link generic:authoring}: the manifest, astryx.config, codemods, identity, and each doc type. `npx astryx docs authoring --index` lists them, and `npx astryx docs authoring <key>` reads one.',
- },
- {
- type: 'prose',
- text: 'A consumer can still name the package explicitly when order or precedence matters:',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// astryx.config.ts\nexport default {\n integrations: ['@acme/astryx-widgets'],\n};",
- },
- {
- type: 'prose',
- text: "Your components and templates then appear next to core's:",
- },
- {
- type: 'code',
- lang: 'bash',
- code: 'astryx component --list --package @acme/astryx-widgets\nastryx component AcmeCarousel --props',
- },
- ],
- },
- {
- title: 'Authoring with the CLI',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Do not start by hand-editing a manifest. Add the contribution you mean to ship; Astryx creates the manifest, writes every required file, preserves an existing custom root, and updates an existing package.json files allowlist without creating one. Always run these commands from the locally installed CLI in the package (e.g. `node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs` or `pnpm astryx`), not `npx @astryxdesign/cli` — npx may resolve a stale registry version whose integration scaffolding does not match the installed one.',
- },
- {
- type: 'code',
- lang: 'bash',
- code: "astryx integration add component AcmeCarousel\nastryx integration add doc deploying\nastryx integration add template dashboard --type page\nastryx integration add codemod rename-prop --to 1.2.0\nastryx integration add agent-doc 'Use AcmeCarousel for rotating content.'\nastryx integration add theme ocean",
- },
- {
- type: 'prose',
- text: 'The package self-resolves while you author it. Run `astryx component --list`, `astryx docs`, `astryx template --list`, or `astryx theme list` from the package and its local contributions appear with the package name. You do not publish or build a throwaway app to see your own work.',
- },
- {
- type: 'prose',
- text: 'Every add is non-interactive, refuses to overwrite authored files, supports --dry-run, and verifies the generated contribution through the same discovery rules a consumer uses. Before publishing, run the package gate:',
- },
- {
- type: 'code',
- lang: 'bash',
- code: 'astryx integration pack --check',
- },
- {
- type: 'prose',
- text: 'The gate runs the package lifecycle, creates the real npm tarball, checks every required contribution file against the pack list, extracts it into a scratch consumer, and compares the local and packed contribution inventories. `astryx doctor integration` remains the read-only diagnostic surface when something is not found.',
- },
- ],
- },
- {
- title: 'Theme Package Walkthrough',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync. Palette outputs live inside the theme directory, which ships as one unit, so there is nothing to register after generation.',
- },
- {
- type: 'code',
- lang: 'bash',
- label: 'In the provider package',
- code: 'astryx integration add theme ocean\nastryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts\nastryx integration add doc brand-theme\nastryx integration add doc theme-migration\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx integration pack --check\nnpm pack',
- },
- {
- type: 'prose',
- text: 'Edit the generated theme descriptor, source, and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`, a reproducibility receipt. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`. The whole theme directory is copied and packed as one unit, so an optional wrapper, refs, icon, or preview module you add inside it ships with the theme. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source or descriptor fails before a consumer sees it.',
- },
- {
- type: 'code',
- lang: 'bash',
- label: 'In a separate consumer app',
- code: 'npm install @astryxdesign/core ../brand-integration/acme-brand-integration-1.0.0.tgz\nastryx theme list --package @acme/brand-integration\nastryx docs brand-theme\nastryx docs theme-migration\nastryx theme add ocean --package @acme/brand-integration\nastryx theme build src/themes/ocean/oceanTheme.ts',
- },
- {
- type: 'prose',
- text: "The package must be a direct dependency for automatic discovery. No `astryx.config` entry is needed unless the app must control integration order. `theme add` copies the selected theme's complete directory, including its typed `.doc.mjs`, nested token modules, and receipts, and refuses to overwrite existing project files.",
- },
- ],
- },
- {
- title: 'Contribution Kinds at a Glance',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Each contribution kind uses a different metadata suffix, type stamp, and discovery rule. The table below prevents the most common first-time authoring mistake — using the wrong file or export convention.',
- },
- {
- type: 'code',
- lang: 'text',
- code: "Kind Metadata file type stamp Source file\n──────── ───────────────────────── ───────────── ──────────────────────\nComponent Name.doc.mjs 'component' Name.tsx (same stem)\nTemplate Name.doc.mjs 'page'/'block' Name.tsx (same stem)\nDoc topic topic.doc.mjs 'generic' (none — docs are prose)\nCodemod <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme <slug>/nameTheme.doc.mjs 'theme' <slug>/nameTheme.ts (same stem)\n\nReleased .doc.js files, template .doc.ts files, and .template.{ts,mjs,js}\ntemplates still load. A component or topic .doc.ts loads only from a package\nlinked from outside node_modules; installed, it is listed but cannot be read.",
- },
- {
- type: 'prose',
- text: 'The `type` stamp is how new docs should be authored — it routes parsing to the correct schema at the load boundary. Legacy docs without a stamp still load via shape-sniffing for backward compatibility, but unstamped docs rely on heuristics (presence of `props`, `params`, etc.) and may parse under the wrong schema if the shape is ambiguous. Always stamp new integration contributions.',
- },
- ],
- },
- {
- title: 'The Integration File',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'The CLI creates one `astryx.integration.mjs` beside package.json and adds a root only when that same operation writes a real contribution. The file tells consumers where each contribution kind lives; this example is the resulting shape, not a setup step:',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// astryx.integration.ts\nexport default {\n components: './components',\n templates: './templates',\n themes: './themes',\n codemods: './codemods',\n docs: './docs',\n issuesUrl: 'https://github.com/acme/widgets/issues',\n};",
- },
- {
- type: 'prose',
- text: 'Every field is optional. Declare only the contribution roots your package ships. There is no factory to call. Write a plain object, and for editor autocomplete and type-checking annotate it with the `AstryxIntegration` type exported from `@astryxdesign/cli/authoring`.',
- },
- ],
- },
- {
- title: 'Components',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a strongly typed `.doc.mjs` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.mjs`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates). Released `.doc.js` docs remain readable for compatibility. A `.doc.ts` component doc reads only when the package is linked from outside node_modules, not once it is installed. New authoring uses `.doc.mjs`.",
- },
- {
- type: 'prose',
- text: 'Component names are package-aware. If an integration name matches Core, unqualified lookup fails closed instead of choosing one. Run `astryx doctor integration components <package>` before publishing: it recommends renaming and prints the exact `--package` command when the overlap is intentional.',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// AcmeCarousel.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */\nexport default {\n type: 'component',\n name: 'AcmeCarousel',\n displayName: 'Acme Carousel',\n usage: {description: 'A carousel that cycles through slides.'},\n props: [],\n};",
- },
- ],
- },
- {
- title: 'Templates',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a strongly typed plain object stamped with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) in a same-stem `.doc.mjs`, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.doc.mjs`. Released `.template.*` files remain readable for compatibility.",
- },
- {
- type: 'prose',
- text: "A template id is its exact source-relative path with the metadata suffix removed; the display `name` is not its identity and may repeat. Run `astryx --json template --list --package @astryxdesign/core` and copy the Core entry's `id` exactly. To replace one, generate the source/metadata pair with `integration add template`, then set `replaces` in that template's own metadata to the exact Core id. The declaration lives on the template, as `replaces` does on a doc topic; the manifest only points at the templates root.",
- },
- {
- type: 'code',
- lang: 'bash',
- label: 'Create the integration template',
- code: 'astryx integration add template acme-app-shell --type page',
- },
- {
- type: 'code',
- lang: 'typescript',
- label: 'Declare the replacement',
- code: "// templates/acme-app-shell.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n type: 'page',\n name: 'acme-app-shell',\n displayName: 'Acme App Shell',\n description: 'An app shell with Acme navigation.',\n replaces: 'shell-side-nav',\n};",
- },
- {
- type: 'code',
- lang: 'typescript',
- label: 'Use product navigation in the replacement source',
- code: "// templates/acme-app-shell.tsx\nimport {AppShell} from '@astryxdesign/core/AppShell';\nimport {Card} from '@astryxdesign/core/Card';\nimport {AcmeSideNav, AcmeTopNav} from '@acme/navigation';\n\nexport default function AcmeAppShell() {\n return (\n <AppShell\n sideNav={<AcmeSideNav />}\n topNav={<AcmeTopNav />}>\n <Card>Product content</Card>\n </AppShell>\n );\n}",
- },
- {
- type: 'prose',
- text: 'With that declaration, `astryx template shell-side-nav` selects `acme-app-shell`; template listing, search, build suggestions, and block-layout lookup use the same effective identity. `astryx template shell-side-nav --package @astryxdesign/core` still selects the original, and `astryx template acme-app-shell --package @acme/navigation` explicitly selects the integration template. In the `template.list` JSON response, a winning replacement entry carries `replaces` naming the Core id it supersedes, and the Core entry is omitted from the default listing. A page can replace only a Core page, and a block can replace only a Core block. Missing Core targets, type mismatches, a declaration on a template that cannot be used, and more than one replacement from one package fail closed: Core stays the default and `astryx doctor integration templates <package>` reports the error. If multiple explicitly configured packages each replace the target, the package configured later wins with a warning. An explicitly configured replacement always wins over an autolinked one. If only autolinked packages conflict, the package listed later in package.json dependencies wins with a warning; add the intended package to `astryx.config` to make the choice explicit. Without `replaces`, valid template selection keeps the existing package-aware ambiguity behavior; contribution failure isolation still follows the rules below.',
- },
- {
- type: 'prose',
- text: "`replaces` is part of the strict template metadata object, so a CLI older than 0.7.0 rejects it: on those CLIs the package's templates and doc topics are withheld with one warning, while its components still load. Declare `@astryxdesign/cli >=0.7.0` when a package uses `replaces`.",
- },
- {
- type: 'prose',
- text: 'The CLI needs both files at consume time. `integration add` includes the templates root when package.json already has a files allowlist. It never creates an exports map, because doing that can make previously-open deep imports private; when a map already exists, it adds the generated source subpath without replacing author-owned entries. Use consumer-safe extensionless subpaths in the exports map (e.g. `"./templates/AcmeDashboard"` instead of `"./templates/AcmeDashboard.tsx"`), so consumers import without knowing the file extension. `integration pack --check` proves the source and metadata, including `replaces`, survive the tarball and verifies every component through the public import its metadata advertises.',
- },
- ],
- },
- {
- title: 'Docs',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: "Point the integration file's `docs` field at a directory of reference docs and every strongly typed `{topic}.doc.mjs` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'` — not `'component'` (that is for component docs with a same-stem source file) — the same shape core's own topics use.",
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// docs/deploying.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n type: 'generic',\n name: 'deploying',\n title: 'Deploying',\n description: 'Ship an app built with Acme widgets.',\n category: 'guide',\n sections: [\n {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n ],\n};",
- },
- {
- type: 'prose',
- text: "A topic can also speak about one that already exists. `replaces: 'x'` takes over topic x (core's, or another integration's) so a package whose consumers install it differently can serve its own Getting Started instead of the built-in one. Give the replacement a different `name` and the old name keeps resolving to it, so a link or an agent that learned the old topic still lands in the right place.",
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "export default {\n type: 'generic',\n name: 'getting-started',\n replaces: 'getting-started',\n title: 'Getting started',\n description: 'Install Acme widgets and use your first component.',\n sections: [/* ... */],\n};",
- },
- {
- type: 'prose',
- text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. The topic keeps its own title and description; only `replaces` renames it. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'A topic name is a CLI argument and a docsite path, so it may hold only letters, digits, `_` and `-`.',
- 'A name that collides with an existing topic and declares neither `replaces` nor `extends` is an error, not a silent override; the CLI will not guess which one you meant.',
- "`replaces` and `extends` are exclusive: a topic either takes another's place or merges onto it.",
- 'Two integrations replacing one topic is a warning, and the one configured later in `astryx.config` wins.',
- '`astryx doctor integration docs <package>` classifies Core overlaps as intentional replacements, intentional extensions, or accidental same-name conflicts.',
- ],
- },
- ],
- },
- {
- title: 'Themes',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: "A theme contribution is editable `defineTheme` source, not compiled CSS. Add `themes: './themes'` to `astryx.integration.*`. Give each lower-kebab slug its own directory containing a theme source and mandatory same-stem, strongly typed `.doc.mjs`. If package.json has a `files` allowlist, include both the integration manifest and the themes root; packages with no allowlist already publish both. Do not add an `exports` map only for theme discovery.",
- },
- {
- type: 'code',
- lang: 'text',
- code: 'themes/\n ocean/\n oceanTheme.ts\n oceanTheme.doc.mjs\n palette.config.json\n tokens/\n ocean.palette.ts\n ocean.palette.receipt.json',
- },
- {
- type: 'prose',
- text: '`ThemeDoc` owns `name` (the slug), `displayName`, `description`, and `maintained`. The descriptor/source stem supplies the source entry and required named runtime export. Astryx parses the source without executing it, confines every local static import and re-export to the theme directory, copies that complete directory, and rejects missing or type-only exports.',
- },
- {
- type: 'code',
- lang: 'javascript',
- code: "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n type: 'theme',\n name: 'ocean',\n displayName: 'Ocean',\n description: 'Ocean theme.',\n maintained: true,\n};",
- },
- {
- type: 'prose',
- text: 'The generated palette candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output.',
- },
- {
- type: 'prose',
- text: 'After a consumer installs the package, `astryx theme list` shows its themes with the owner package, and `astryx theme add <slug> --package <package>` copies the selected source into the app. If two packages use one slug, an unscoped add fails instead of choosing one silently.',
- },
- {
- type: 'prose',
- text: "Compatibility is additive. A CLI released before the `themes` field ignores that unknown key with a warning and continues loading the integration's older contribution kinds, but it cannot list or add the contributed theme. Upgrade `@astryxdesign/cli` in the consumer to use it.",
- },
- ],
- },
- {
- title: 'Agent Docs',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'An integration can append a small amount of static package guidance to the end of the managed agent block through `agentDocs.append` in its default manifest. The CLI owns the section heading, package-labeled bullets, placement, markers, target files, and writes.',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// astryx.integration.ts\nimport type {AstryxIntegration} from '@astryxdesign/cli/authoring';\n\nexport default {\n components: './components',\n agentDocs: {\n append: ['Run acme verify before finishing.'],\n },\n} satisfies AstryxIntegration;",
- },
- {
- type: 'prose',
- text: '`append` is optional and may contain at most 8 lines per integration. A line is a trimmed, non-blank plain string of at most 240 Unicode code points with no line separators, control characters, NUL, or Astryx/XDS managed-marker text. A configured project may render at most 32 integration lines total.',
- },
- {
- type: 'prose',
- text: '`astryx init` renders the installed manifests. `astryx upgrade` compares the same expected block even when the Core version is unchanged, so a line addition, removal, reorder, or edit appears in dry-run and is written with `--apply`. When codemods or post-codemod hooks run, the block is refreshed only after they succeed; no integration codemod is required for guidance changes.',
- },
- ],
- },
- {
- title: 'Codemods',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: "Ship codemods so `astryx upgrade` can migrate consumers across breaking changes in your package. Point the integration file's `codemods` field at your codemods root, and author each one as a plain object stamped with `type: 'code'` (transforms source files) or `type: 'config'` (rewrites the consumer's `astryx.config`).",
- },
- {
- type: 'prose',
- text: 'The codemods root uses a version-folder-first layout. Each folder name is an exact semver string (no `v` prefix) matching the version the codemod migrates TO. Each module under it is a kebab-case `.ts`, `.mjs`, or `.js` file whose default export is the codemod envelope:',
- },
- {
- type: 'code',
- lang: 'text',
- code: 'codemods/\n 0.2.0/\n rename-widget-prop.ts\n 0.3.0/\n update-theme-import.ts\n config/rename-integration.ts',
- },
- {
- type: 'prose',
- text: 'Codemod ids (the extension-less relative path under the version folder, e.g. `rename-widget-prop`, `config/rename-integration`) must be unique within a package across all versions. A duplicate id across versions is a hard error.',
- },
- {
- type: 'prose',
- text: 'The loader automatically skips test and fixture files so you can colocate tests with transforms. Reserved names: files matching `*.test.*`, `*.spec.*`, or `*.fixture.*`, and any file under a `__tests__/` or `__fixtures__/` directory. These are never loaded as codemods regardless of their extension.',
- },
- {
- type: 'code',
- lang: 'text',
- code: 'codemods/\n 0.2.0/\n rename-widget-prop.ts # loaded as a codemod\n rename-widget-prop.test.ts # skipped (reserved name)\n __tests__/\n rename-widget-prop.test.ts # skipped (reserved directory)',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// codemods/0.2.0/rename-widget-prop.ts\nexport default {\n type: 'code',\n title: 'Rename AcmeWidget oldProp to newProp',\n description: 'Updates JSX props in consumer source files.',\n transform(file, api) {\n // jscodeshift transform\n return file.source;\n },\n};",
- },
- {
- type: 'prose',
- text: "`astryx upgrade` is dry-run by default — it previews which codemods would run and what files would change, without writing anything. Pass `--apply` to write the changes. There is no `--dry-run` flag; omitting `--apply` is the dry run. The `--integration` flag resolves each value beneath the project's `node_modules` (for example, `--integration @acme/widgets`). Absolute paths and `.` or `..` segments are rejected; other slash-separated values remain beneath `node_modules`.",
- },
- {
- type: 'code',
- lang: 'bash',
- code: '# Preview what would change (dry-run, the default)\nastryx upgrade --from 0.1.0\n\n# Apply the migration\nastryx upgrade --from 0.1.0 --apply',
- },
- {
- type: 'prose',
- text: 'Core and integration upgrade codemods do not edit existing consumer files that the working tree protects. Protection is VCS-neutral: Astryx reads nested `.gitattributes` rules for `linguist-generated` and `linguist-vendored`, leading `@generated` and `@partially-generated` comments, standard `Code generated … DO NOT EDIT.` comments, `.gitignore`, and `.hgignore` directly from disk. Later attribute rules, explicit false or unset values, and ignore negation keep their normal semantics. Installed dependencies, VCS metadata, paths outside the project, and symbolic links are also protected. Directory or file names such as `dist` and `generated` are not evidence by themselves.',
- },
- {
- type: 'prose',
- text: 'A protected file is transformed only in memory. If it would change, the upgrade applies eligible owned-source edits, runs `hooks.postCodemod` regeneration, and checks the protected file again. A remaining change makes the run incomplete and exits nonzero with `ERR_CODEMOD_PROTECTED`; JSON output lists `modifiedFiles` and `protectedFiles` with every effective declaration. Generated headers may include `Command: <exact command>` so the result can tell a consumer how to regenerate when no hook resolves the output. Dry-run uses the same classification without writing.',
- },
- {
- type: 'code',
- lang: 'text',
- code: '# .gitattributes\ngenerated/** linguist-generated=true\nvendor/** linguist-vendored=true\n\n# A later rule can explicitly return an authored file to normal handling\ngenerated/hand-authored.ts linguist-generated=false',
- },
- {
- type: 'prose',
- text: 'All authoring types are exported from `@astryxdesign/cli/authoring`: `ComponentDoc`, `HookDoc`, and `ReferenceDoc` for docs, `TemplateDoc` for templates, and `AstryxConfig`, `AstryxIntegration`, and `AstryxCodemod` for the project files. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.',
- },
- ],
- },
- {
- title: 'Recording Runs',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'An integration can receive every command run in the apps that install it, so you can see how your package is actually used without asking each app to add anything. Export a function named `debug` from the integration file. It is a NAMED export, deliberately not a manifest field: a CLI version that predates this feature reads only the default export, so adding one does not disturb any consumer.',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// astryx.integration.ts\nimport type {DebugEvent} from '@astryxdesign/cli/authoring';\n\nexport function debug(event: DebugEvent): void {\n // synchronous only — the process is exiting\n reportSomewhere(event);\n}\n\nexport default {\n components: './components',\n};",
- },
- {
- type: 'prose',
- text: "The event is the same `DebugEvent` a consumer receives from `debug` in their own `astryx.config`, and both run: an app that sets its own handler still reaches yours, and yours never displaces theirs. The app handler is called first, then each integration in the order the config lists them. Every handler is called in isolation with its own copy of the event — one that throws, prints, or calls `process.exit` cannot change the command's output or exit code, and cannot stop the others.",
- },
- {
- type: 'prose',
- text: 'The handler is synchronous, for the same reason a consumer\'s is: it runs on process exit, where Node abandons pending async work. Buffer or write synchronously; do not await. An app that wants no inherited handler sets `{"astryx": {"inheritDebug": false}}` in its `package.json`, which suppresses every integration\'s handler while leaving its own untouched.',
- },
- ],
+ title: 'Build an integration',
+ summary:
+ 'Build an npm package that adds components, templates, themes, docs, and codemods to Astryx apps.',
+ keywords: [
+ 'integration',
+ 'integration package',
+ 'make an integration',
+ 'publish an integration',
+ 'integration authoring',
+ ],
+ slots: {
+ guides: {
+ title: 'Build an integration',
+ accepts: {kinds: ['generic', 'namespace']},
},
+ },
+ blocks: [
{
- title: 'Gap report handler',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'An integration can handle `astryx gap-report` events by exporting a `gapReport` handler from its integration module. The handler is a plain object with an `audience` and a `handle` function — not an executable command. Export it as a named export; do not put it in the default manifest. Older CLI versions ignore the named export and continue loading every manifest contribution they understand.',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// astryx.integration.ts\nimport type {GapReportHandler} from '@astryxdesign/cli/authoring';\n\nexport const gapReport: GapReportHandler = {\n audience: 'public',\n async handle(event, {signal}) {\n // event is a normalized GapReport with camelCase fields\n // and event.target.{package, version, issuesUrl}\n const url = await createIssue(event, {signal});\n return { status: 'filed', url };\n },\n};\n\nexport default {\n components: './components',\n issuesUrl: 'https://github.com/acme/widgets/issues',\n};",
- },
- {
- type: 'prose',
- text: 'The same handler type is available as a `gapReport` field in `astryx.config` for project-level handling. When both exist, the project handler runs first, then each integration handler in config order. Every handler runs — none overrides another.',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// astryx.config.ts\nimport type {AstryxConfig, GapReportHandler} from '@astryxdesign/cli/authoring';\n\nconst projectHandler: GapReportHandler = {\n audience: 'internal',\n async handle(event) {\n await postToTracker(event);\n return { status: 'filed', message: 'Posted to internal tracker' };\n },\n};\n\nexport default {\n integrations: ['@acme/astryx-widgets'],\n gapReport: projectHandler,\n} satisfies AstryxConfig;",
- },
- {
- type: 'prose',
- text: "Each handler receives its own deep copy of the `GapReport` event (via `structuredClone`) plus an `AbortSignal` that fires at the 30-second timeout. Each handler runs in its own worker. A throw, timeout, `stdout` write, `process.exit`, or `process.exitCode` change is contained there and produces a failed delivery for that handler only. On timeout the CLI aborts the signal, terminates the worker before starting the next handler, and preserves its own output and exit code. Handler `stdout` is forwarded to the CLI's `stderr` so it cannot corrupt a JSON envelope.",
- },
- {
- type: 'prose',
- text: "A handler MUST return a `GapReportHandlerReceipt` with a `status` of `'filed'`, `'routed_only'`, or `'skipped'`, plus optional `url` and `message` strings. The aggregate response includes an ordered `deliveries` array. Each entry names its project, integration package, or fallback and includes the declared audience, final status, URL, and message.",
- },
- {
- type: 'prose',
- text: "Use `audience: 'public'` for any public or third-party destination. The CLI will not invoke a public handler unless the caller explicitly confirms the public write. `audience: 'internal'` requires no additional confirmation. In a fan-out with mixed audiences, internal handlers run unconditionally while public handlers are consent-gated independently.",
- },
- {
- type: 'prose',
- text: 'When the effective handler set is empty (no project handler, no integration handlers), and the target has a GitHub `issuesUrl`, the CLI falls back to `gh issue create` after explicit confirmation. Any other `issuesUrl` scheme produces a `routed_only` receipt. The fallback is suppressed entirely when at least one handler is configured.',
- },
- ],
+ type: 'prose',
+ text: 'An integration is a way to share things with Astryx users: a package you own and maintain, built on a framework Astryx gives you. Publish one, many, or any mix, and people install it in one step. It works with the Astryx CLI alongside Core. See each kind under {@link namespace:building-blocks}.',
},
{
- title: 'Discover source',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: '`astryx discover` lists the integrations an app has and, through discover sources, the ones it could add, with every version and what each one adds. An integration can supply a source by exporting an async function named `discover` from its integration module. Like `debug`, it is a named export, not a manifest field, so a CLI that predates it simply does not read it.',
- },
- {
- type: 'code',
- lang: 'typescript',
- code: "// astryx.integration.ts\nimport type {DiscoverSource} from '@astryxdesign/cli/authoring';\n\nexport const discover: DiscoverSource = async ({signal, package: name, version}) => {\n // Every package you know about, each with every version and what the\n // requested (else latest) version adds.\n return readCatalog({signal, name, version});\n};\n\nexport default {\n components: './components',\n};",
- },
- {
- type: 'prose',
- text: 'A project can set the same function as `discover` in `astryx.config`. Discover calls every source, the project one first and then each integration in load order, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others. It keeps the last good answer from each source in the per-user cache and uses it, with its date, when the source cannot be reached. Discover only reads: it prints the command that adds a package and never runs it. `astryx docs authoring discover-source` has the catalog shape.',
- },
- ],
+ type: 'prose',
+ text: 'For example, ship a carousel as an integration. Any app that installs it can find it with `npx astryx search carousel`, and the CLI uses it like any Astryx Core component.',
},
{
- title: 'How It Works',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: "Every CLI command loads the consumer's `astryx.config`, resolves each listed integration's manifest from `node_modules`, and discovers its contributions. Each file is parsed at the load boundary through `@astryxdesign/cli/authoring` — when the CLI loads it, not when you author it. A field of the wrong type fails there. A field this CLI does not know is ignored with a warning naming it, so a manifest written against a newer CLI still contributes everything this one understands. There are no factories; you write a plain object and stamp its `type`.",
- },
- {
- type: 'prose',
- text: 'Runtime integration features — `debug`, `gapReport`, and `discover` — use named exports from the integration module rather than fields in the default manifest. The CLI discovers them alongside the manifest but loads them through the composition rules in `spec:AST-031`: every configured handler runs additively, each in isolation with its own copy of the event.',
- },
- {
- type: 'prose',
- text: "Discovery is resilient. A manifest that fails to load is skipped because none of its roots are trustworthy. An error in one contribution kind is reported without hiding the integration's other valid kinds. Invalid template and component files are omitted without hiding valid siblings; other kinds keep their existing all-or-nothing behavior. Everyday commands keep working with the remaining valid contributions, warnings go to stderr, and `--json` stdout stays clean.",
- },
- {
- type: 'prose',
- text: 'To inspect problems, run `astryx doctor integration validate <package>` for structure, then use `templates`, `components`, or `docs` under the same `astryx doctor integration` group to check Core identity overlaps before publishing. Bare `astryx doctor` checks overall project health.',
- },
- ],
+ type: 'prose',
+ text: 'An integration can also replace a built-in template or doc. To start, install `@astryxdesign/cli` and open {@link generic:quick-start}.',
},
],
};
diff --git a/packages/cli/assets/docs/tree/integrations.test.mjs b/packages/cli/assets/docs/tree/integrations.test.mjs
deleted file mode 100644
index 1f331626a4..0000000000
--- a/packages/cli/assets/docs/tree/integrations.test.mjs
+++ /dev/null
@@ -1,62 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, it} from 'vitest';
-import {docs as integrationGuide} from './integrations.doc.mjs';
-import {doc as integrationSchema} from '../../../authoring/integration/integration.doc.mjs';
-import {doc as templateSchema} from '../../../authoring/doctypes/template/template.doc.mjs';
-
-function guideText() {
- return integrationGuide.sections
- .flatMap(section => section.content)
- .flatMap(block => {
- if (block.type === 'prose') return [block.text];
- if (block.type === 'code') return [block.label ?? '', block.code];
- if (block.type === 'list') return block.items;
- return [];
- })
- .join('\n');
-}
-
-describe('integration template replacement docs', () => {
- it('documents the complete author and consumer contract', () => {
- const text = guideText();
-
- for (const required of [
- "replaces: 'shell-side-nav'",
- 'acme-app-shell',
- 'astryx --json template --list --package @astryxdesign/core',
- 'astryx template shell-side-nav --package @astryxdesign/core',
- 'astryx template acme-app-shell --package @acme/navigation',
- 'templates/acme-app-shell.doc.mjs',
- 'AcmeSideNav',
- 'AcmeTopNav',
- '<Card>Product content</Card>',
- 'fail closed',
- 'configured later wins',
- 'wins over an autolinked one',
- 'listed later in package.json dependencies',
- 'valid siblings',
- 'Without `replaces`',
- '@astryxdesign/cli >=0.7.0',
- 'templates and doc topics are withheld',
- '`template.list` JSON response',
- ]) {
- expect(text, required).toContain(required);
- }
- });
-
- it('declares a replacement on the template, never in the manifest', () => {
- expect(guideText()).not.toContain('templateReplacements');
- expect(
- integrationSchema.fields.some(field => /replac/i.test(field.name)),
- ).toBe(false);
-
- const field = templateSchema.fields.find(
- candidate => candidate.name === 'replaces',
- );
- expect(field).toMatchObject({type: 'string'});
- expect(field.description).toContain('Integration templates only');
- expect(field.description).toContain('--package @astryxdesign/core');
- expect(field.description).toContain('0.7.0');
- });
-});
diff --git a/packages/cli/assets/docs/tree/links.doc.mjs b/packages/cli/assets/docs/tree/links.doc.mjs
new file mode 100644
index 0000000000..816d4c71bb
--- /dev/null
+++ b/packages/cli/assets/docs/tree/links.doc.mjs
@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/links`: link one doc to another by
+ * identity, link the CLI's docs, and fix a link that names no doc.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'links',
+ placement: {parent: 'namespace:docs', slot: 'guides', order: 30},
+ title: 'Links',
+ category: 'guide',
+ description:
+ 'Link one doc to another so the link keeps working when the doc moves.',
+ sections: [
+ {
+ id: 'link-another-doc',
+ title: 'Link another doc',
+ content: [
+ {
+ type: 'prose',
+ text: 'Write `{@link [provider:]kind:name}` in prose, list items, and table cells to link another doc. The CLI prints the command that opens it, so the link keeps working when the doc moves.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ code: "{type: 'prose', text: 'Before you ship, read {@link generic:deploying}.'},\n{type: 'list', style: 'unordered', items: ['All guides: {@link namespace:acme}.']},\n{type: 'table', headers: ['Task', 'Guide'], rows: [['Ship', '{@link generic:deploying}']]},",
+ },
+ {
+ type: 'prose',
+ text: 'Each link reads as a command. This link, {@link generic:extend-or-replace}, opens the next guide.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'The kind is `generic` for a topic or guide, `namespace` for a docs section, and `command` or `function` for a CLI command or API function.',
+ 'A link to a component or a template does not resolve. Write its name in backticks instead, such as `AcmeCarousel`.',
+ 'Inside backticks or a code block, link syntax prints as written.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'link-another-packages-docs',
+ title: "Link another package's docs",
+ content: [
+ {
+ type: 'prose',
+ text: "A link without a provider resolves against your own package. To link the CLI's docs, or another package's, start the target with that package's name, such as `@astryxdesign/cli:`.",
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ code: "// Resolves: the CLI's doctor command\n{type: 'prose', text: 'Check the app with {@link @astryxdesign/cli:command:doctor}.'},\n// Does not resolve: looks for a doctor command in your package\n{type: 'prose', text: 'Check the app with {@link command:doctor}.'},",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Name a CLI command the way you type it, spaces included, such as `@astryxdesign/cli:command:doctor integration docs`.',
+ "In a topic that `extends` another package's topic, your sections still resolve against your package, so a link to the base topic's docs needs its provider.",
+ ],
+ },
+ ],
+ },
+ {
+ id: 'fix-a-link-that-names-no-doc',
+ title: 'Fix a link that names no doc',
+ content: [
+ {
+ type: 'prose',
+ text: 'A link that names no doc prints as written, and `doctor integration docs` warns. The warning names a search that finds the right target.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration docs',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'severity: [warn]\ncode: invalid_doc_graph\nmessage: acme/deploying § check-before-you-ship: "command:doctor" names no doc. Find it with `astryx search doctor --type doc`, then name it as `[<provider>:]<kind>:<name>`.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'The warning keeps exit code 0, so read the report before you ship; see {@link generic:check-your-docs}.',
+ 'A stable CLI before 0.7.0 does not read links: it prints each one as written. See {@link generic:versioning}.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/package-and-test.doc.mjs b/packages/cli/assets/docs/tree/package-and-test.doc.mjs
new file mode 100644
index 0000000000..7022c1e054
--- /dev/null
+++ b/packages/cli/assets/docs/tree/package-and-test.doc.mjs
@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/package-and-test`:
+ * expose a template from its package and prove the copied result in an app.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'package-and-test',
+ placement: {
+ parent: 'namespace:build-the-template',
+ slot: 'guides',
+ order: 30,
+ },
+ title: 'Package and test',
+ summary:
+ 'Publish a package that works the first time: include everything the template needs, check the package before you publish, and try the template in a real app.',
+ keywords: [
+ 'template export',
+ 'package template',
+ 'integration verify',
+ 'test template',
+ ],
+ slots: {
+ guides: {
+ title: 'Guides',
+ accepts: {kinds: ['generic']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/page-template.doc.mjs b/packages/cli/assets/docs/tree/page-template.doc.mjs
new file mode 100644
index 0000000000..9bc5055519
--- /dev/null
+++ b/packages/cli/assets/docs/tree/page-template.doc.mjs
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template/page-template`:
+ * the page-only fields that help people find a page.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'page-template',
+ placement: {
+ parent: 'namespace:document-the-template',
+ slot: 'guides',
+ order: 20,
+ },
+ title: 'Page template',
+ category: 'guide',
+ description:
+ 'Help people find a page: give it a category for `astryx search` and template listings, and flag a sparse starting shell as a scaffold.',
+ sections: [
+ {
+ id: 'start-from-the-generated-page-doc',
+ title: 'Start from the generated page doc',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration add template` writes a page doc by default. Replace its sample description, then add the page-only fields below.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'templates/acme-dashboard.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+ type: 'page',
+ name: 'acme-dashboard',
+ displayName: 'Acme Analytics Dashboard',
+ description:
+ 'A filterable account-health dashboard with headline metrics, trends, and a recent-activity table. Dashboard, reporting, analytics, or status overview.',
+ category: 'Dashboard - Analytics',
+ isReady: false,
+};`,
+ },
+ ],
+ },
+ {
+ id: 'help-people-find-the-page',
+ title: 'Help people find the page',
+ content: [
+ {
+ type: 'reference',
+ target: 'schema:template-doc',
+ projection: {
+ fields: ['category', 'scaffold'],
+ },
+ presentation: 'full',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Set `category` to the most specific supported `{Group} - {Variant}` value. Its words become search terms for `astryx search`, and it appears in the JSON template list.',
+ 'Set `scaffold: true` only for a deliberately sparse starting shell. The JSON template list reports it, so tools and galleries can tell a scaffold from a finished page.',
+ "Fields that only Astryx's own gallery reads, such as `isHiddenFromOverview`, have no effect on integration templates.",
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/publishing.doc.mjs b/packages/cli/assets/docs/tree/publishing.doc.mjs
new file mode 100644
index 0000000000..d86b241bdb
--- /dev/null
+++ b/packages/cli/assets/docs/tree/publishing.doc.mjs
@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/publishing`: publish an integration to
+ * npm, use release tags, and check the package before and after.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'publishing',
+ placement: {parent: 'namespace:ship', slot: 'guides', order: 40},
+ title: 'Publish an integration',
+ category: 'guide',
+ keywords: ['publish an integration', 'npm publish', 'release'],
+ description:
+ 'Publish your package to npm under the right release tag, and check it before and after.',
+ sections: [
+ {
+ id: 'check-before-you-publish',
+ title: 'Check before you publish',
+ content: [
+ {
+ type: 'prose',
+ text: 'Publish only a package that passes every check, then preview the upload with `npm publish --dry-run`. The dry run lists the files and the tag without uploading.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration validate && npx astryx doctor integration components && npx astryx doctor integration templates && npx astryx doctor integration docs && npx astryx integration verify\nnpm publish --dry-run --access public',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access (dry-run)\n+ @acme/[email protected]',
+ },
+ {
+ type: 'prose',
+ text: 'Set a new `version` for each release; {@link generic:versioning} covers what counts as breaking. What each check proves is in {@link generic:checks}.',
+ },
+ ],
+ },
+ {
+ id: 'keep-private-files-out',
+ title: 'Keep private files out',
+ content: [
+ {
+ type: 'prose',
+ text: 'With no `files` list, npm packs every file your ignore files do not exclude, including an old `.tgz` file or an `.env` file. List what ships instead.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: "npm pkg set 'files[]=components' 'files[]=templates' 'files[]=themes' 'files[]=docs' 'files[]=codemods' 'files[]=astryx.integration.mjs'\nnpm pack --dry-run",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'List only the roots you ship, and always `astryx.integration.mjs`. npm adds package.json, and a README and LICENSE when you have them.',
+ 'Each later `integration add` appends its root to the list.',
+ '`integration verify` fails when a root is missing from the list: `Declared templates root "templates" has 0 of 2 expected files in the pack list. Add "templates" to "files" in package.json.`',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'publish-to-npm',
+ title: 'Publish to npm',
+ content: [
+ {
+ type: 'prose',
+ text: 'A scoped package is private by default, so publish it with `--access public`. Without `--tag`, npm tags the release `latest`, which is what `npm install @acme/astryx-widgets` installs.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: '# Publish a release\nnpm publish --access public\n\n# Or set the access once in package.json\nnpm pkg set publishConfig.access=public',
+ },
+ {
+ type: 'prose',
+ text: 'To let apps try a release first, publish it under `next`, then point `latest` at it when it is ready.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: '# Only apps that ask for next get it: npm install @acme/astryx-widgets@next\nnpm publish --tag next\n\n# Make that version the default\nnpm dist-tag add @acme/[email protected] latest\nnpm dist-tag ls @acme/astryx-widgets',
+ },
+ ],
+ },
+ {
+ id: 'check-the-published-package',
+ title: 'Check the published package',
+ content: [
+ {
+ type: 'prose',
+ text: 'Install the version you published in a clean app, and run the same commands you ran against the `.tgz` file.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'mkdir check-release && cd check-release\nnpm init -y\nnpm install @astryxdesign/core @astryxdesign/cli @acme/[email protected]\nnpx astryx component AcmeCarousel\nnpx astryx doctor integration validate @acme/astryx-widgets',
+ },
+ {
+ type: 'prose',
+ text: 'The full list of commands to run in an app is in {@link generic:test-in-an-app}. To help apps move to the new version, see {@link generic:upgrading}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/quick-start.doc.mjs b/packages/cli/assets/docs/tree/quick-start.doc.mjs
new file mode 100644
index 0000000000..3275f81147
--- /dev/null
+++ b/packages/cli/assets/docs/tree/quick-start.doc.mjs
@@ -0,0 +1,272 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'quick-start',
+ placement: {
+ parent: 'namespace:integrations',
+ slot: 'guides',
+ order: 10,
+ },
+ title: 'Quick Start',
+ category: 'guide',
+ keywords: [
+ 'make a package',
+ 'make an integration',
+ 'first integration',
+ 'integration tutorial',
+ 'package.json',
+ 'exports map',
+ 'astryx.integration.mjs',
+ ],
+ description:
+ 'Create a new integration package or add Astryx to one you already publish.',
+ sections: [
+ {
+ id: 'quick-start',
+ title: 'Quick start',
+ content: [
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Make the package',
+ },
+ {
+ type: 'prose',
+ text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI and Core for development.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Start with `"exports": {}`: each component and template you add then writes the public import that `integration verify` resolves.',
+ 'Run the CLI as `npx astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.',
+ 'Component commands read Core, so they need `@astryxdesign/core` installed.',
+ ],
+ },
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Add your first integration item',
+ },
+ {
+ type: 'prose',
+ text: 'An integration can ship several kinds of items. Start with a component named `AcmeCarousel`.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add component AcmeCarousel',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'component contribution added\n\n[ok] AcmeCarousel\n\nDeclare component root ./components in astryx.integration.mjs.\n\n- components/AcmeCarousel.doc.mjs\n- components/AcmeCarousel.tsx\n- package.json\n- astryx.integration.mjs',
+ },
+ {
+ type: 'prose',
+ text: '`integration add` creates the component source, its `.doc.mjs`, the package export, and `astryx.integration.mjs`. Update the generated doc so the CLI understands the component, then write the component itself.',
+ },
+ {
+ type: 'prose',
+ text: 'Read it back the way an app will.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx component AcmeCarousel',
+ },
+ {
+ type: 'prose',
+ text: 'You now have an integration package with one exported component.',
+ },
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Verify and pack the package',
+ },
+ {
+ type: 'prose',
+ text: 'Run `integration verify` to check that an app would see the component, then make the `.tgz` file you install next. `--pack-destination ..` writes it beside the package folder, so the next pack does not ship it.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration verify\nnpm pack --pack-destination ..',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'Integration package ready\n\n[ok] @acme/[email protected]\n\n4 packed files; 3/3 required files present.',
+ },
+ {
+ type: 'prose',
+ text: '`integration verify` packs the package, unpacks it into a temporary app, and checks that the component resolves through its public import there. It publishes nothing and leaves no `.tgz` file, so `npm pack` writes `../acme-astryx-widgets-1.0.0.tgz` for the next step.',
+ },
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Use it in an app',
+ },
+ {
+ type: 'prose',
+ text: 'Install Core, the CLI, and your `.tgz` file in a new app. The app loads your package because it is a dependency, with no config.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'cd ..\nmkdir my-app && cd my-app\nnpm init -y\nnpm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz\nnpx astryx component AcmeCarousel',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: "**Import:** `import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';`",
+ },
+ {
+ type: 'prose',
+ text: 'The next sections explain each package field and the integration file. To build the real component, continue with {@link namespace:components}.',
+ },
+ ],
+ },
+ {
+ id: 'fill-in-package-json',
+ title: 'Fill in package.json',
+ content: [
+ {
+ type: 'prose',
+ text: 'An integration is an ordinary npm package. These six fields control how it is named, developed, checked, and published.',
+ },
+ {
+ type: 'prose',
+ text: '`peerDependencies` are packages the app supplies. `devDependencies` are packages you use while building the integration.',
+ },
+ {
+ type: 'table',
+ headers: ['Field', 'Set it to', 'Why'],
+ rows: [
+ [
+ '`name`',
+ 'Your package name, such as `@acme/astryx-widgets`',
+ 'Each add writes it into the `import` of the doc it generates. Rename before you add, or update each `import` after.',
+ ],
+ [
+ '`version`',
+ 'The release you publish, such as `1.0.0`',
+ 'Apps see it; `astryx.integration.mjs` never repeats it.',
+ ],
+ [
+ '`exports`',
+ 'Start with `{}`',
+ 'Each component and template add writes its public import here, and `integration verify` resolves it.',
+ ],
+ [
+ '`files`',
+ 'Optional: the paths to publish',
+ 'Keeps private files out. When the list exists, each add appends its root and `astryx.integration.mjs`.',
+ ],
+ [
+ '`peerDependencies`',
+ '`@astryxdesign/cli`; add `@astryxdesign/core` when your code imports it',
+ 'The app supplies these packages for your integration.',
+ ],
+ [
+ '`devDependencies`',
+ '`@astryxdesign/cli` and `@astryxdesign/core`',
+ 'Lets you run the CLI and build components while working on the integration.',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Peer ranges and releases are covered in {@link generic:versioning}; `files` and publishing in {@link generic:publishing}.',
+ },
+ ],
+ },
+ {
+ id: 'the-integration-file',
+ title: 'The integration file',
+ content: [
+ {
+ type: 'prose',
+ text: 'The first `integration add` creates `astryx.integration.mjs`, and each later add updates it. You do not need to write or edit this file during the quick start.',
+ },
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Files in the package',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`package.json` defines the npm package, including its name, version, dependencies, published files, and exports.',
+ '`astryx.integration.mjs` tells the CLI where the package keeps each kind of integration item.',
+ 'The integration item files live under those roots. For example, a component can have `AcmeWidget.tsx` for its source and `AcmeWidget.doc.mjs` for its documentation.',
+ ],
+ },
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Fields in the integration file',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'astryx.integration.mjs',
+ code: "/** @type {import('@astryxdesign/cli/authoring').AstryxIntegration} */\nexport default {\n components: './components',\n};",
+ },
+ {
+ type: 'prose',
+ text: 'The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.',
+ },
+ {
+ type: 'reference',
+ target: 'schema:integration',
+ projection: {
+ fields: [
+ 'providerId',
+ 'components',
+ 'templates',
+ 'codemods',
+ 'docs',
+ 'themes',
+ 'agentDocs',
+ 'issuesUrl',
+ ],
+ },
+ presentation: 'full',
+ },
+ {
+ type: 'heading',
+ level: 3,
+ text: 'Use the CLI',
+ },
+ {
+ type: 'prose',
+ text: 'You can edit the package files by hand, but the CLI handles the normal workflow. These links always open the canonical command docs.',
+ },
+ {
+ type: 'reference',
+ target: 'command:integration add',
+ presentation: 'summary',
+ },
+ {
+ type: 'reference',
+ target: 'command:integration verify',
+ presentation: 'summary',
+ },
+ {
+ type: 'reference',
+ target: 'command:doctor integration',
+ presentation: 'summary',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs b/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
new file mode 100644
index 0000000000..77e2386bea
--- /dev/null
+++ b/packages/cli/assets/docs/tree/replace-a-core-component.doc.mjs
@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/replace-a-core-component`:
+ * intentionally make an integration component the default for a Core identity.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'replace-a-core-component',
+ placement: {parent: 'namespace:components', slot: 'guides', order: 50},
+ title: 'Replace a Core component',
+ category: 'guide',
+ description:
+ 'Use a component replacement only when an integration must intentionally own a Core component identity.',
+ sections: [
+ {
+ id: 'decide-whether-to-replace',
+ title: 'Decide whether to replace',
+ content: [
+ {
+ type: 'prose',
+ text: 'Most components should not use `replaces`. Give a new component its own name and let apps choose it explicitly. Replace Core only when your component must become the default for one Core identity everywhere the integration is active.',
+ },
+ {type: 'heading', level: 3, text: 'Use it when'},
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Your component intentionally serves the same role as one specific Core component.',
+ 'Every app that loads the integration should get your component from unqualified component detail, lists, search, swizzle, and issue routing.',
+ 'You have tested both the replacement and explicit access to the original Core component.',
+ ],
+ },
+ {type: 'heading', level: 3, text: 'Do not use it when'},
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Your component is an alternative, variant, wrapper, or product-specific extension. Give it a unique name instead.',
+ 'You only need to resolve an accidental name collision.',
+ 'You want the replacement in only one screen or workflow. Replacement applies across the app wherever the integration is active.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'set-the-replacement',
+ title: 'Set the replacement',
+ content: [
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'components/AcmeSideNav.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+ type: 'component',
+ name: 'AcmeSideNav',
+ displayName: 'Acme Side Nav',
+ replaces: 'SideNav',
+ import: '@acme/astryx-widgets/components/AcmeSideNav',
+ usage: {description: 'Product navigation for Acme apps.'},
+ props: [],
+};`,
+ },
+ {
+ type: 'reference',
+ target: 'schema:component-doc',
+ projection: {fields: ['replaces']},
+ presentation: 'full',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`replaces` names the Core `ComponentDoc` identity, not its display label, import path, or a standalone hook.',
+ 'Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore `replaces`.',
+ '`--package @astryxdesign/core` always selects the original Core component.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'check-replacement-resolution',
+ title: 'Check replacement resolution',
+ content: [
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration components\nnpx astryx component SideNav\nnpx astryx component AcmeSideNav\nnpx astryx component SideNav --package @astryxdesign/core',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'A missing target, invalid value, second replacement for one target in the same package, or a replacement named after a different Core component is an error.',
+ 'When several integrations replace one target, explicit configuration beats the automatic pick. Among explicitly configured integrations, the later package wins and Doctor warns.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
new file mode 100644
index 0000000000..0e992a6470
--- /dev/null
+++ b/packages/cli/assets/docs/tree/replace-a-core-template.doc.mjs
@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template/replace-a-core-template`:
+ * deliberately replace one Core template through template metadata.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'replace-a-core-template',
+ placement: {
+ parent: 'namespace:document-the-template',
+ slot: 'guides',
+ order: 40,
+ },
+ title: 'Replace a Core template',
+ category: 'guide',
+ description:
+ 'Use a template replacement only when an integration intentionally changes the default source returned for one Core template id.',
+ sections: [
+ {
+ id: 'replace-only-on-purpose',
+ title: 'Replace only on purpose',
+ content: [
+ {
+ type: 'prose',
+ text: 'Use with care: replace a Core template only when every app using this integration should receive your source for an existing Core id by default. An alternative, a product-specific variation, or a different kind of template gets its own id instead ({@link generic:start-a-template}).',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Sharing a Core id without `replaces` does not replace Core. It makes the bare id ambiguous, so `astryx template <id>` fails until the app adds `--package`, and `doctor integration templates` reports an accidental collision.',
+ 'A replacement can keep the Core id or use its own. `replaces` is what makes it the default.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'declare-the-replacement',
+ title: 'Declare the replacement',
+ content: [
+ {
+ type: 'prose',
+ text: 'Find the exact Core id and kind first.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx --json template --list --package @astryxdesign/core',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'templates/acme-app-shell.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+ type: 'page',
+ name: 'acme-app-shell',
+ displayName: 'Acme App Shell',
+ description:
+ 'An Acme application shell with product navigation, account controls, and a responsive content region.',
+ replaces: 'shell-side-nav',
+ isReady: true,
+ category: 'Shell - Left Sidebar',
+};`,
+ },
+ {
+ type: 'reference',
+ target: 'schema:template-doc',
+ projection: {fields: ['replaces']},
+ presentation: 'full',
+ },
+ {
+ type: 'prose',
+ text: 'Declare `replaces` on the template doc, never in `astryx.integration.mjs`.',
+ },
+ ],
+ },
+ {
+ id: 'require-a-compatible-cli',
+ title: 'Require a compatible CLI',
+ content: [
+ {
+ type: 'prose',
+ text: 'Declare the CLI floor from the field above as an optional peer ({@link generic:versioning}).',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'package.json',
+ code: `{
+ "peerDependencies": {
+ "@astryxdesign/cli": ">=0.7.0"
+ },
+ "peerDependenciesMeta": {
+ "@astryxdesign/cli": {
+ "optional": true
+ }
+ }
+}`,
+ },
+ {
+ type: 'prose',
+ text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, an older CLI drops that template and hides your doc topics.',
+ },
+ ],
+ },
+ {
+ id: 'what-apps-receive',
+ title: 'What apps receive',
+ content: [
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `# Receives the active replacement
+npx astryx template shell-side-nav src/app
+
+# Receives the original Core template
+npx astryx template shell-side-nav --package @astryxdesign/core src/app`,
+ },
+ {
+ type: 'prose',
+ text: 'When several integrations replace the same Core template, one wins:',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'An integration explicitly listed in `astryx.config.mjs` wins over one that is only installed and picked automatically.',
+ 'When several explicitly configured integrations replace the same target, the one listed later wins and Astryx reports the ambiguity.',
+ "When no integration is configured explicitly, the package listed later in the app's package.json dependencies wins. Configure the intended integration explicitly instead of relying on that order.",
+ ],
+ },
+ ],
+ },
+ {
+ id: 'check-the-replacement',
+ title: 'Check the replacement',
+ content: [
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration templates',
+ },
+ {
+ type: 'table',
+ headers: ['Issue', 'Meaning'],
+ rows: [
+ [
+ '`missing_template_replacement_target`',
+ '`replaces` does not name a Core template id.',
+ ],
+ [
+ '`invalid_template_replacement`',
+ 'The replacement is unusable or its page/block kind differs from Core.',
+ ],
+ [
+ '`ambiguous_template_replacement`',
+ 'One package declares two replacements for a target, or several active packages contend for it.',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Replacement resolution is safe by default. A missing source, invalid doc, missing target, wrong kind, or conflicting declaration never hands the Core id to a questionable replacement: Astryx reports the issue and keeps the Core template. Fix every issue before publishing.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
new file mode 100644
index 0000000000..ebdaf96ce3
--- /dev/null
+++ b/packages/cli/assets/docs/tree/sections-and-placement.doc.mjs
@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/sections-and-placement`: give an
+ * integration package its own section in the docs tree, place guides in it,
+ * and fix a placement that fails.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'sections-and-placement',
+ placement: {parent: 'namespace:docs', slot: 'guides', order: 20},
+ title: 'Sections and placement',
+ category: 'guide',
+ description: 'Give your package its own docs section and place guides in it.',
+ sections: [
+ {
+ id: 'add-a-docs-section',
+ title: 'Add a docs section',
+ content: [
+ {
+ type: 'prose',
+ text: "Give your package its own section in the docs tree with `integration add doc <name> --parent <section>`. The first run also writes the section's namespace doc.",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration add doc deploying --parent acme\n# Open your section\nnpx astryx docs acme',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'docs/acme.doc.mjs',
+ code: "/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */\nexport default {\n type: 'namespace',\n name: 'acme',\n title: 'Acme',\n summary: 'Guides for Acme.',\n slots: {\n guides: {title: 'Guides', accepts: {kinds: ['generic']}},\n },\n};",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Edit its `title` and `summary`: readers see them in the docs list and at the top of your section.',
+ "The guide, `docs/deploying.doc.mjs`, gets `placement: {parent: 'namespace:acme', slot: 'guides'}`. Later runs with `--parent acme` reuse the namespace doc.",
+ '`package.json` gets the optional peer `"@astryxdesign/cli": ">=0.7.0"`, because an older CLI does not read sections; see {@link generic:versioning}.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'place-a-doc',
+ title: 'Place a doc',
+ content: [
+ {
+ type: 'prose',
+ text: 'A guide names its one home with `placement`: a namespace of your package, a slot in it, and an `order`. Its route is the section name, then the guide name.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ code: "placement: {parent: 'namespace:acme', slot: 'guides', order: 10}, // route: acme/deploying",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ "`parent` is `namespace:<name>`, a namespace that your own package ships. You cannot place a doc in the CLI's sections or in another package's.",
+ "`slot` is a slot that the namespace declares for the doc's kind. You can leave it out when the namespace has only one slot.",
+ '`order` is an integer that sorts the guides in the slot and sets their Previous and Next moves. Guides without one come last, by name.',
+ 'A placed guide opens only by its route, `acme/deploying`. Its bare name no longer opens it.',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx docs acme/deploying',
+ },
+ ],
+ },
+ {
+ id: 'fix-a-failed-placement',
+ title: 'Fix a failed placement',
+ content: [
+ {
+ type: 'prose',
+ text: 'A failed `placement` hides the doc: it gets no route and does not show in the docs list. `doctor integration docs` fails with `invalid_doc_graph` and names what to fix.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor integration docs',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'severity: [fail]\ncode: invalid_doc_graph\nmessage: @acme/astryx-widgets/deploying.doc.mjs: placement.parent "namespace:cli" names no namespace; @acme/astryx-widgets declares "acme".',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'A `parent` that your package does not ship, such as `namespace:cli`, "names no namespace".',
+ 'A `slot` that the namespace does not declare "is not a slot of namespace"; the message lists the slots it does declare.',
+ 'The check exits 1; see {@link generic:check-your-docs}.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
new file mode 100644
index 0000000000..157d5ba2a8
--- /dev/null
+++ b/packages/cli/assets/docs/tree/see-it-in-an-app.doc.mjs
@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/see-it-in-an-app`: inspect an
+ * integration component from an app that installs the package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'see-it-in-an-app',
+ placement: {parent: 'namespace:components', slot: 'guides', order: 40},
+ title: 'See it in an app',
+ category: 'guide',
+ description:
+ 'Confirm that an app discovers the component, its package, its public import, and its documentation.',
+ sections: [
+ {
+ id: 'read-the-installed-component',
+ title: 'Read the installed component',
+ content: [
+ {
+ type: 'prose',
+ text: 'An app that installs your package sees the component beside Core components, with its package name and public import. The app needs no config.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `npx astryx component AcmeCarousel
+npx astryx component --list
+npx astryx search carousel`,
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `# AcmeCarousel
+
+Cycles through slides one at a time. Use it for a small set of related cards.
+
+**Import:** \`import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';\``,
+ },
+ {
+ type: 'prose',
+ text: '`component --list` shows it as `import: @acme/astryx-widgets/components/AcmeCarousel [@acme/astryx-widgets]`. The same commands work in your package while you build it.',
+ },
+ ],
+ },
+ {
+ id: 'test-the-packed-package',
+ title: 'Test the packed package',
+ content: [
+ {
+ type: 'prose',
+ text: 'Install the packed package in a test app before publishing. Then run the same detail, list, and search commands there. See {@link generic:test-in-an-app}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/ship.doc.mjs b/packages/cli/assets/docs/tree/ship.doc.mjs
new file mode 100644
index 0000000000..13bdf2fcbe
--- /dev/null
+++ b/packages/cli/assets/docs/tree/ship.doc.mjs
@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @file astryx docs cli/integrations/ship — test, publish, and upgrade. */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'ship',
+ placement: {parent: 'namespace:integrations', slot: 'guides', order: 30},
+ title: 'Ship',
+ summary: 'Test, publish, and upgrade your package.',
+ keywords: ['ship', 'publish', 'release', 'upgrade'],
+ slots: {
+ guides: {title: 'Ship', accepts: {kinds: ['generic']}},
+ },
+};
diff --git a/packages/cli/assets/docs/tree/short-and-findable.doc.mjs b/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
new file mode 100644
index 0000000000..acd4cf7c12
--- /dev/null
+++ b/packages/cli/assets/docs/tree/short-and-findable.doc.mjs
@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/docs/short-and-findable`: keep each read
+ * short, lead each section with its summary, and write docs that search finds.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'short-and-findable',
+ placement: {parent: 'namespace:docs', slot: 'guides', order: 50},
+ title: 'Short and findable',
+ category: 'guide',
+ description: 'Write short sections that people and agents find by search.',
+ sections: [
+ {
+ id: 'keep-each-read-short',
+ title: 'Keep each read short',
+ content: [
+ {
+ type: 'prose',
+ text: 'Readers open one section at a time, so give each section one idea and keep it to about 30 lines. `npx astryx doctor` warns on any read over 32 KB.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'When a section needs a second idea, split it into two sections.',
+ 'Keep a topic to a few sections. When it grows past five, split it into more guides in your docs section.',
+ 'A topic with more than one section reads as its section list. Readers open one section by its key, or the whole topic with `--full`.',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: '# The section list\nnpx astryx docs acme/deploying\n# One section\nnpx astryx docs acme/deploying check-before-you-ship\n# Everything\nnpx astryx docs acme/deploying --full',
+ },
+ ],
+ },
+ {
+ id: 'lead-with-the-summary',
+ title: 'Lead with the summary',
+ content: [
+ {
+ type: 'prose',
+ text: "A section's first prose block, or its first list item, is its summary in section lists and search results. Make it answer the section's question in one or two sentences.",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'The summary is cut at about 240 characters.',
+ 'A code block first does not count: the summary comes from the next prose block.',
+ 'Open with the answer, not with background.',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'build-before-you-ship Build before you ship - Build the app, then upload the `dist` folder to your host.',
+ },
+ ],
+ },
+ {
+ id: 'make-docs-findable',
+ title: 'Make docs findable',
+ content: [
+ {
+ type: 'prose',
+ text: 'Search ranks a query that matches a whole title, or an identifier in backticks, above words in body text. Title each section with the task a reader searches for.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Name the task in the words a reader types, such as "Deploy to production". Avoid titles such as "Overview" or "Details".',
+ 'Write field names, file names, and error codes in backticks, such as `deployTarget`: search treats each one as a keyword.',
+ 'Other words in the summary and body match too, but rank below titles and identifiers. The summary shows under each hit, so make it answer the query.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'test-with-search',
+ title: 'Test with search',
+ content: [
+ {
+ type: 'prose',
+ text: 'Test a doc the way a new reader finds it: search for the question, and check that the first hit answers it. Quote a query of more than one word.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx search "place a doc" --type doc',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'This query returns the section of these guides that shows how to place a doc.',
+ 'Run the same search in an app that installs your package; see {@link generic:test-in-an-app}.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/single-component.doc.mjs b/packages/cli/assets/docs/tree/single-component.doc.mjs
new file mode 100644
index 0000000000..6f33e57a0b
--- /dev/null
+++ b/packages/cli/assets/docs/tree/single-component.doc.mjs
@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/describe-the-component/single-component`:
+ * write and maintain the default ComponentDoc for one public component.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'single-component',
+ placement: {
+ parent: 'namespace:describe-the-component',
+ slot: 'guides',
+ order: 20,
+ },
+ title: 'Single component',
+ category: 'guide',
+ description:
+ 'Write the default component doc: explain when to use the component, document every public prop, and add focused examples.',
+ sections: [
+ {
+ id: 'start-from-the-generated-doc',
+ title: 'Start from the generated doc',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration add component` creates the normal doc for one public component. Keep the generated identity and import, then replace its sample text and props with the component\'s real public contract.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'components/AcmeCarousel.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+ type: 'component',
+ name: 'AcmeCarousel',
+ displayName: 'Acme Carousel',
+ import: '@acme/astryx-widgets/components/AcmeCarousel',
+ usage: {
+ description:
+ 'Cycles through slides one at a time. Use it for a small set of related cards.',
+ },
+ props: [
+ {
+ name: 'slides',
+ type: 'ReactNode[]',
+ description: 'The slides to show, in order.',
+ required: true,
+ },
+ ],
+};`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Keep `props` on the top-level doc. Private implementation helpers do not need entries.',
+ 'Keep the doc beside the source and change both in the same pull request.',
+ 'If the module later exposes several related public exports, adapt this doc with {@link generic:component-family}.',
+ ],
+ },
+ {
+ type: 'reference',
+ target: 'schema:component-doc',
+ presentation: 'summary',
+ },
+ ],
+ },
+ {
+ id: 'explain-when-to-use-it',
+ title: 'Explain when to use it',
+ content: [
+ {
+ type: 'prose',
+ text: 'Write `usage.description` so a person or agent can decide whether this is the right component without opening its source. Say what it does, when to use it, and the most important boundary with a nearby alternative.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ code: `usage: {
+ description:
+ 'Cycles through slides one at a time. Use it for a small set of related cards. Use a static list when every item should stay visible.',
+ bestPractices: [
+ {guidance: true, description: 'Keep the slide order stable while someone interacts with the carousel.'},
+ {guidance: false, description: 'Hide information that must remain visible for comparison.'},
+ ],
+},`,
+ },
+ ],
+ },
+ {
+ id: 'document-every-public-prop',
+ title: 'Document every public prop',
+ content: [
+ {
+ type: 'prose',
+ text: 'Copy the public prop names and types from the source. Explain the behavior a caller controls, not only the TypeScript type.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ code: `props: [
+ {
+ name: 'slides',
+ type: 'ReactNode[]',
+ description: 'The slides to show, in order.',
+ required: true,
+ },
+ {
+ name: 'interval',
+ type: 'number',
+ description: 'Milliseconds between automatic slide changes.',
+ default: '5000',
+ },
+],`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Set `required: true` only when every caller must pass the prop.',
+ 'Write `default` exactly as the value should appear in documentation.',
+ 'Skip styling escape hatches such as `xstyle`, `className`, and `style`.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'add-focused-examples',
+ title: 'Add focused examples',
+ content: [
+ {
+ type: 'prose',
+ text: 'Add short examples for important usage that the prop table does not make obvious. Each example should teach one complete pattern and use only public imports.',
+ },
+ {
+ type: 'code',
+ lang: 'javascript',
+ code: `examples: [
+ {
+ label: 'Automatic rotation',
+ code: '<AcmeCarousel slides={slides} interval={5000} />',
+ },
+],`,
+ },
+ ],
+ },
+ {
+ id: 'read-the-result',
+ title: 'Read the result',
+ content: [
+ {
+ type: 'prose',
+ text: 'Read the component after every source or doc change. Confirm that its purpose, import, props, defaults, and examples match the source, then verify the packed package.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx component AcmeCarousel\nnpx astryx integration verify',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/start-a-template.doc.mjs b/packages/cli/assets/docs/tree/start-a-template.doc.mjs
new file mode 100644
index 0000000000..5da9515874
--- /dev/null
+++ b/packages/cli/assets/docs/tree/start-a-template.doc.mjs
@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/start-a-template`: what a
+ * template is, why an integration shares one, whether it is a page or a
+ * block, and how to add one.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'start-a-template',
+ placement: {parent: 'namespace:templates', slot: 'build', order: 10},
+ title: 'Start a template',
+ category: 'guide',
+ keywords: [
+ 'what is a template',
+ 'add a template',
+ 'page template',
+ 'block template',
+ ],
+ description:
+ 'Help others build apps faster and share a consistent visual language by turning your UI idea into a full page or page section.',
+ sections: [
+ {
+ id: 'what-a-template-is',
+ title: 'What a template is',
+ content: [
+ {
+ type: 'prose',
+ text: 'Unlike a component, a template becomes app code: an app copies it into its own code and adapts it to its product.',
+ },
+ {
+ type: 'prose',
+ text: "A component stays a package dependency and updates with the package. A copied template does not, so updating the package never rewrites the app's copy.",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `# How an app finds a template and copies it
+npx astryx template --list
+npx astryx template acme-dashboard src/app/dashboard`,
+ },
+ ],
+ },
+ {
+ id: 'why-share-one',
+ title: 'Why share one',
+ content: [
+ {
+ type: 'prose',
+ text: 'Templates help other people build apps faster while keeping a consistent visual language across products. Share one when people need more than one component to get started: a template brings the right components, layout, content structure, and interaction wiring already assembled.',
+ },
+ {
+ type: 'prose',
+ text: 'Do not turn a product-specific page into a rigid component only to share its structure. Share it as a template and let each app adapt its copy.',
+ },
+ ],
+ },
+ {
+ id: 'choose-page-or-block',
+ title: 'Choose a page or block',
+ content: [
+ {
+ type: 'table',
+ headers: ['Kind', 'Use it for'],
+ rows: [
+ [
+ 'Page',
+ 'A complete screen, such as a dashboard, settings page, or checkout flow.',
+ ],
+ [
+ 'Block',
+ 'A smaller section that fits inside a page, such as a hero, form, or data panel. A block can also be the example or showcase for a component.',
+ ],
+ ],
+ },
+ ],
+ },
+ {
+ id: 'pick-a-template-id',
+ title: 'Pick a template id',
+ content: [
+ {
+ type: 'prose',
+ text: 'Choose a stable lowercase kebab-case id, such as `acme-dashboard`. The id becomes the source and doc file name, the package export, and the value apps pass to `astryx template`. To change a label, edit the doc ({@link generic:template-doc-overview}); never rename the id.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Start with your product or package name, then name the reusable pattern, so the id stays distinct from Core and other integrations.',
+ 'Do not end the id with `-page`, `-app`, `-view`, or `-screen`.',
+ 'Do not reuse a Core id by accident: the bare id becomes ambiguous in every app that installs your package. To take over a Core template on purpose, declare `replaces` ({@link generic:replace-a-core-template}).',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: '# See the Core ids\nnpx astryx --json template --list --package @astryxdesign/core',
+ },
+ ],
+ },
+ {
+ id: 'run-the-add-command',
+ title: 'Run the add command',
+ content: [
+ {
+ type: 'prose',
+ text: 'Pages are the default. Pass `--type block` to add a block.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `npx astryx integration add template acme-dashboard
+npx astryx integration add template acme-stat-card --type block`,
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: `template contribution added
+
+[ok] acme-dashboard
+
+Declare template root ./templates in astryx.integration.mjs.
+
+- templates/acme-dashboard.doc.mjs
+- templates/acme-dashboard.tsx
+- package.json
+- astryx.integration.mjs`,
+ },
+ {
+ type: 'prose',
+ text: 'The command writes `templates/<id>.tsx` for the UI and `templates/<id>.doc.mjs` for its metadata, and declares the templates directory in `astryx.integration.mjs`. When `package.json` has an `exports` map, it also adds the `./templates/<id>` export ({@link generic:export-template-assets}).',
+ },
+ {
+ type: 'prose',
+ text: 'It never overwrites an existing source or doc file. Add `--dry-run` to see every planned write first.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/subcomponent.doc.mjs b/packages/cli/assets/docs/tree/subcomponent.doc.mjs
new file mode 100644
index 0000000000..bbaccb79e1
--- /dev/null
+++ b/packages/cli/assets/docs/tree/subcomponent.doc.mjs
@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/describe-the-component/subcomponent`:
+ * give one member of a component family its own ComponentDoc.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'subcomponent',
+ placement: {
+ parent: 'namespace:describe-the-component',
+ slot: 'guides',
+ order: 40,
+ },
+ title: 'Subcomponent',
+ category: 'guide',
+ description:
+ 'Move one member of a component family into its own sibling doc without duplicating it in the parent.',
+ sections: [
+ {
+ id: 'choose-a-separate-doc',
+ title: 'Choose a separate doc',
+ content: [
+ {
+ type: 'prose',
+ text: 'Start with a component family doc. Move one public member into a sibling doc when it has its own source and enough behavior, props, or usage guidance to maintain separately. The parent still lists the member, but only by name.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Keep a small member inline when its whole contract stays clear in the family doc.',
+ 'Use a sibling doc when the member needs focused search results, examples, usage guidance, or independent maintenance.',
+ 'Give each member one documentation owner. Do not keep a full parent entry and a sibling doc for the same name.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'reference-it-from-the-parent',
+ title: 'Reference it from the parent',
+ content: [
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'components/AcmeDialog.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+ type: 'component',
+ name: 'AcmeDialog',
+ displayName: 'Acme Dialog',
+ usage: {description: 'Presents a focused task above the current page.'},
+ components: [
+ {
+ name: 'AcmeDialog',
+ displayName: 'Acme Dialog',
+ description: 'Owns the modal surface and open state.',
+ props: [],
+ },
+ {name: 'AcmeDialogHeader'},
+ ],
+};`,
+ },
+ {
+ type: 'prose',
+ text: 'The name-only entry keeps `AcmeDialogHeader` in the family. Its description and props come only from the sibling file.',
+ },
+ ],
+ },
+ {
+ id: 'write-the-subcomponent-doc',
+ title: 'Write the subcomponent doc',
+ content: [
+ {
+ type: 'code',
+ lang: 'javascript',
+ label: 'components/AcmeDialogHeader.doc.mjs',
+ code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+ type: 'component',
+ name: 'AcmeDialogHeader',
+ displayName: 'Acme Dialog Header',
+ subComponentOf: 'AcmeDialog',
+ description: 'Labels an Acme Dialog and holds its close action.',
+ props: [
+ {
+ name: 'title',
+ type: 'string',
+ description: 'The dialog title.',
+ required: true,
+ },
+ ],
+};`,
+ },
+ {
+ type: 'reference',
+ target: 'schema:component-doc',
+ projection: {fields: ['subComponentOf', 'description', 'props']},
+ presentation: 'full',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`subComponentOf` must exactly match the parent doc\'s `name`.',
+ '`description` explains this member\'s role in the family. `usage` is optional; add it when the member needs guidance beyond that sentence.',
+ 'The child inherits family fields such as `group`, `category`, `keywords`, `theming`, and `playground` unless it overrides them.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/template-assets.doc.mjs b/packages/cli/assets/docs/tree/template-assets.doc.mjs
new file mode 100644
index 0000000000..2c92a45f0c
--- /dev/null
+++ b/packages/cli/assets/docs/tree/template-assets.doc.mjs
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/template-assets`: make every
+ * style, font, icon, and media dependency survive a template copy.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'template-assets',
+ placement: {
+ parent: 'namespace:build-the-template',
+ slot: 'guides',
+ order: 20,
+ },
+ title: 'Assets',
+ summary:
+ "Make sure the template's styles, fonts, icons, images, and video still show up after an app copies it.",
+ blocks: [
+ {
+ type: 'prose',
+ text: 'The copied file does not bring sibling assets with it ({@link generic:write-the-template-file}). Give every asset exactly one owner:',
+ },
+ {
+ type: 'table',
+ headers: ['Owner', 'Use when', 'How the copied source reaches it'],
+ rows: [
+ [
+ 'Copied source',
+ 'The value is small, editable, and belongs to the starting point',
+ 'Keep it in the `.tsx` file',
+ ],
+ [
+ 'Integration package',
+ 'The asset should stay centrally maintained with the package',
+ 'Import a stable public package path',
+ ],
+ [
+ 'App',
+ 'The app must provide product-specific content or branding',
+ 'Use an explicit placeholder or app public URL and say what to replace',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Do not make a template look self-contained while it relies on an undocumented package file or app convention.',
+ },
+ ],
+ keywords: [
+ 'template assets',
+ 'template styles',
+ 'template fonts',
+ 'template icons',
+ 'template images',
+ ],
+ slots: {
+ guides: {
+ title: 'Guides',
+ accepts: {kinds: ['generic']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs b/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
new file mode 100644
index 0000000000..8e32fac354
--- /dev/null
+++ b/packages/cli/assets/docs/tree/template-doc-overview.doc.mjs
@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template/template-doc-overview`:
+ * the source and doc file pair, the fields every template doc shares, and how
+ * to check what Astryx lists.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'template-doc-overview',
+ placement: {
+ parent: 'namespace:document-the-template',
+ slot: 'guides',
+ order: 10,
+ },
+ title: 'Template doc overview',
+ category: 'guide',
+ description:
+ 'Understand what the template doc controls, keep it accurate as the UI changes, and check how Astryx lists the template.',
+ sections: [
+ {
+ id: 'understand-the-two-files',
+ title: 'Understand the two files',
+ content: [
+ {
+ type: 'prose',
+ text: 'Every template has a source file and a doc file. For `acme-dashboard`, the source is `templates/acme-dashboard.tsx` and the doc is `templates/acme-dashboard.doc.mjs`. Both begin with `acme-dashboard`, which is how Astryx knows they belong together.',
+ },
+ {
+ type: 'table',
+ headers: ['File', 'What it controls'],
+ rows: [
+ [
+ '`templates/acme-dashboard.tsx`',
+ 'The UI source that an app copies and then owns.',
+ ],
+ [
+ '`templates/acme-dashboard.doc.mjs`',
+ 'How Astryx names, describes, categorizes, previews, and resolves the template before it is copied.',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'The integration manifest points Astryx to the `templates` directory; it does not list each template. Change the source and doc together whenever the purpose, preview, readiness, or replacement behavior changes. No automated check can tell whether the doc still describes the rendered UI.',
+ },
+ ],
+ },
+ {
+ id: 'document-the-shared-fields',
+ title: 'Document the shared fields',
+ content: [
+ {
+ type: 'prose',
+ text: 'These fields apply to every page and block. The page, block, and replacement guides add the fields unique to each.',
+ },
+ {
+ type: 'reference',
+ target: 'schema:template-doc',
+ projection: {
+ fields: ['type', 'name', 'displayName', 'description', 'isReady'],
+ },
+ presentation: 'full',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Set `type` to the kind you chose in {@link generic:start-a-template}. It decides which other fields the doc accepts.',
+ 'The file name sets the template id ({@link generic:start-a-template}). Labels live in the doc: the terminal list prints `name`, and JSON listings print `displayName`. Changing either never changes the id.',
+ 'Write the description for someone choosing between templates. The Doc metadata category in {@link generic:template-grading-rubric} defines what a complete description covers.',
+ 'Add `isReady: false` as soon as you generate the doc, because a doc without `isReady` is listed as ready. Keep it until the template passes {@link generic:test-template-in-app} and the quality review.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'check-how-astryx-lists-it',
+ title: 'Check how Astryx lists it',
+ content: [
+ {
+ type: 'prose',
+ text: 'Read the package-scoped template list after every doc change. Confirm the id, visible name, description, type, readiness, and package.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx --json template --list --package @acme/astryx-templates',
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ label: 'Relevant list result',
+ code: `{
+ "id": "acme-dashboard",
+ "name": "acme-dashboard",
+ "displayName": "Acme Dashboard",
+ "description": "An analytics dashboard for reviewing account health and recent trends.",
+ "type": "page",
+ "package": "@acme/astryx-templates",
+ "isReady": false
+}`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/template-fonts.doc.mjs b/packages/cli/assets/docs/tree/template-fonts.doc.mjs
new file mode 100644
index 0000000000..67a721fec0
--- /dev/null
+++ b/packages/cli/assets/docs/tree/template-fonts.doc.mjs
@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts`:
+ * use the app typeface by default, and ship every font file a template needs
+ * when it must bring its own.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'template-fonts',
+ placement: {
+ parent: 'namespace:template-assets',
+ slot: 'guides',
+ order: 30,
+ },
+ title: 'Fonts',
+ category: 'guide',
+ description:
+ "Keep text in the app's typeface unless the template truly needs its own, and ship every font file it uses when it does.",
+ sections: [
+ {
+ id: 'prefer-host-typography',
+ title: 'Prefer host typography',
+ content: [
+ {
+ type: 'prose',
+ text: 'Use Astryx typography components and theme values unless the template must demonstrate a specific licensed typeface. A copied template should normally inherit the app typography instead of installing a new global font.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Do not add a font only to make sample content look more polished.',
+ 'Do not override the app body font from a template.',
+ 'Use a custom face only for a real product or content requirement that the integration package owns.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'package-a-required-font',
+ title: 'Package a required font',
+ content: [
+ {
+ type: 'prose',
+ text: 'Keep the font files beside a package-owned stylesheet. The stylesheet can use relative `url()` paths because it stays in the package, and the template imports the stylesheet by its public path ({@link generic:template-styles}).',
+ },
+ {
+ type: 'code',
+ lang: 'css',
+ label: 'styles/acme-dashboard.css',
+ code: `@font-face {
+ font-family: 'Acme Sans';
+ src: url('../assets/fonts/acme-sans-regular.woff2') format('woff2');
+ font-style: normal;
+ font-weight: 400;
+ font-display: swap;
+}
+
+.acme-dashboard-title {
+ font-family: 'Acme Sans', sans-serif;
+}`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Ship WOFF2 when it satisfies the supported browsers. Add another format only when those browsers require it.',
+ 'Declare every weight and style the template uses. Do not make the browser synthesize bold or italic because a file is missing.',
+ 'Use `font-display: swap` unless the product requirement and performance test justify another value.',
+ 'Confirm that the font license permits redistribution in the integration package.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Exporting the stylesheet does not publish the font files it points to. Include the font directory in the package as well ({@link generic:export-template-assets}).',
+ },
+ ],
+ },
+ {
+ id: 'check-fonts-in-the-app',
+ title: 'Check fonts in the app',
+ content: [
+ {
+ type: 'prose',
+ text: 'When you test the template in an app ({@link generic:test-template-in-app}), also confirm the following.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Every font request succeeds from the built asset path.',
+ 'Computed styles show the requested family, weight, and style.',
+ 'Text stays readable with the fallback stack when a font loads slowly or fails.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs b/packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs
new file mode 100644
index 0000000000..6202c07056
--- /dev/null
+++ b/packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs
@@ -0,0 +1,452 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/template-grading-rubric`:
+ * complete scoring rules for page and block template quality.
+ */
+
+/**
+ * The single source of rubric version, grade bands, category ids, and weights.
+ * The agent-grading guide and any grading tool import this constant; the
+ * detailed scoring rules live in the sections below.
+ */
+export const TEMPLATE_RUBRIC = Object.freeze({
+ version: '1.4',
+ minimumScore: 75,
+ minimumGrade: 'B',
+ grades: Object.freeze([
+ Object.freeze({
+ grade: 'A',
+ min: 90,
+ max: 100,
+ meaning: 'Exemplary. Copy-ready with no known quality problems.',
+ }),
+ Object.freeze({
+ grade: 'B',
+ min: 75,
+ max: 89,
+ meaning: 'Good. Minor issues may remain, but the template is usable.',
+ }),
+ Object.freeze({
+ grade: 'C',
+ min: 60,
+ max: 74,
+ meaning: 'Needs work before publication.',
+ }),
+ Object.freeze({
+ grade: 'D',
+ min: 40,
+ max: 59,
+ meaning: 'Poor. Significant rewrites are needed.',
+ }),
+ Object.freeze({
+ grade: 'F',
+ min: 0,
+ max: 39,
+ meaning: 'Failing. The template teaches or produces bad patterns.',
+ }),
+ ]),
+ categories: Object.freeze([
+ Object.freeze({
+ id: 'component_purity',
+ title: 'Astryx component purity',
+ max: 30,
+ guide: 'template-grading-rubric',
+ }),
+ Object.freeze({
+ id: 'icon_purity',
+ title: 'Icon purity',
+ max: 15,
+ guide: 'template-grading-rubric',
+ }),
+ Object.freeze({
+ id: 'custom_css',
+ title: 'Custom CSS',
+ max: 15,
+ guide: 'template-grading-rubric',
+ }),
+ Object.freeze({
+ id: 'layout_structure',
+ title: 'Layout & structure',
+ max: 15,
+ guide: 'template-grading-rubric',
+ }),
+ Object.freeze({
+ id: 'doc_metadata',
+ title: 'Doc metadata',
+ max: 10,
+ guide: 'template-grading-rubric',
+ }),
+ Object.freeze({
+ id: 'image_handling',
+ title: 'Image handling',
+ max: 5,
+ guide: 'template-grading-rubric',
+ }),
+ Object.freeze({
+ id: 'code_quality',
+ title: 'Code quality',
+ max: 10,
+ guide: 'template-grading-rubric',
+ }),
+ ]),
+});
+
+const gradeRows = TEMPLATE_RUBRIC.grades.map(({grade, min, max, meaning}) => [
+ grade,
+ `${min}-${max}`,
+ meaning,
+]);
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'template-grading-rubric',
+ placement: {parent: 'namespace:write-good-templates', slot: 'guides', order: 10},
+ title: 'Full grading rubric',
+ category: 'guide',
+ description:
+ 'Use a shared set of heuristics to score template quality consistently across Astryx usage, icons, CSS, layout, metadata, images, and code quality.',
+ sections: [
+ {
+ id: 'understand-the-score',
+ title: 'Understand the score',
+ content: [
+ {
+ type: 'prose',
+ text: `Template rubric ${TEMPLATE_RUBRIC.version} scores seven categories for 100 points. Aim for 100; ${TEMPLATE_RUBRIC.minimumGrade} (${TEMPLATE_RUBRIC.minimumScore}) is the publication floor, not the target. Each category below lists its weight. Never award points for anything you did not inspect.`,
+ },
+ {
+ type: 'table',
+ headers: ['Grade', 'Score', 'Meaning'],
+ rows: gradeRows,
+ },
+ {
+ type: 'prose',
+ text: 'Keep improving while a deduction has a reasonable fix. A score below 100 is fine only when the remaining tradeoff is intentional and recorded. A template is not ready if the copied file fails to build or a required asset is missing, whatever its score.',
+ },
+ {
+ type: 'prose',
+ text: `Version ${TEMPLATE_RUBRIC.version} counts public integration components as Astryx components and grades assets and imports after the copy. Record the version with every score so results stay comparable.`,
+ },
+ ],
+ },
+ {
+ id: 'component-purity',
+ title: 'Astryx component purity: 30 points',
+ content: [
+ {
+ type: 'prose',
+ text: 'Count every JSX opening tag in the copied `.tsx` source. An Astryx element is a component imported from `@astryxdesign/core` or from a public component export of the integration package. A raw HTML element is any lowercase intrinsic JSX tag. Count occurrences, not only unique tag names.',
+ },
+ {
+ type: 'prose',
+ text: 'Do not count fragments or a PascalCase helper defined in the same file. Inspect that helper and count the raw HTML inside it. For each raw element, decide whether it is necessary because Astryx has no equivalent, or unnecessary because an Astryx component can replace it.',
+ },
+ {
+ type: 'table',
+ headers: ['Raw HTML elements', 'Points'],
+ rows: [
+ ['0', '30'],
+ ['1-2, all necessary', '25'],
+ ['1-2, any unnecessary', '20'],
+ ['3-5', '15'],
+ ['6-10', '8'],
+ ['11-20', '4'],
+ ['21 or more', '0'],
+ ],
+ },
+ {
+ type: 'table',
+ headers: ['Raw HTML use', 'Astryx replacement'],
+ rows: [
+ [
+ '`div` for layout',
+ '`VStack`, `HStack`, `Card`, `Section`, or `Center`',
+ ],
+ ['`div` for a grid', '`Grid`'],
+ ['`span` or `p` for text', '`Text`'],
+ ['`h1` through `h6`', '`Heading level={N}`'],
+ ['`button`', '`Button` or `IconButton`'],
+ ['`a`', '`Link`'],
+ ['In-page `nav` or `aside`', '`LayoutPanel` in the start slot'],
+ [
+ '`header` or `main`',
+ '`LayoutHeader` or `LayoutContent` in `Layout`',
+ ],
+ ['`ul`, `ol`, or `li`', '`List` and `ListItem`'],
+ [
+ '`input`, `textarea`, or `select`',
+ 'The matching Astryx form control',
+ ],
+ ['`table`, `tr`, or `td`', '`Table`'],
+ ['`hr`', '`Divider`'],
+ ['`dialog`', '`Dialog`'],
+ ['`details` or `summary`', '`Collapsible`'],
+ ],
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Do not deduct for an `img` when no general Astryx image component fits and its source passes the Image handling category.',
+ 'Do not deduct for a `form` that wraps `FormLayout` to provide native submission semantics.',
+ 'Do not deduct for `input type="hidden"` when it carries native form state.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'icon-purity',
+ title: 'Icon purity: 15 points',
+ content: [
+ {
+ type: 'prose',
+ text: 'Count raw icon markup in the copied file. {@link generic:template-icons} shows how to render icons through Astryx instead.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Count every raw `svg`, `path`, `circle`, `rect`, `line`, `polyline`, `polygon`, `ellipse`, or `g` used as an icon.',
+ 'Count an inline SVG component defined in the template.',
+ 'Count an icon component rendered directly instead of through `Icon` or an Astryx icon prop.',
+ ],
+ },
+ {
+ type: 'table',
+ headers: ['Raw SVG icon instances', 'Points'],
+ rows: [
+ ['0', '15'],
+ ['1-2', '10'],
+ ['3-5', '5'],
+ ['6 or more', '0'],
+ ],
+ },
+ ],
+ },
+ {
+ id: 'custom-css',
+ title: 'Custom CSS: 15 points',
+ content: [
+ {
+ type: 'prose',
+ text: 'Prefer Astryx component props and design tokens. Count individual CSS properties inside `stylex.create` and inline `style` objects. Count each `className` and `stylex.props` use once. Do not count Astryx props such as `gap`, `padding`, `variant`, `size`, `color`, `level`, `columns`, `contentPadding`, or `height`.',
+ },
+ {
+ type: 'table',
+ headers: ['Custom style declarations', 'Points'],
+ rows: [
+ ['0', '15'],
+ ['1-3, all justified because no Astryx alternative exists', '12'],
+ ['1-3, any unjustified because an Astryx prop exists', '8'],
+ ['4-10', '5'],
+ ['11-20', '2'],
+ ['21 or more', '0'],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'This category scores styles authored in the copied source. A package stylesheet is graded through its effect on portability and the rendered app, not as a way to hide custom declarations from this count.',
+ },
+ ],
+ },
+ {
+ id: 'layout-and-structure',
+ title: 'Layout and structure: 15 points',
+ content: [
+ {type: 'heading', level: 3, text: 'Page templates'},
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'Use `Layout` or `Center` as the page root. A template whose category starts with `Shell -` uses `AppShell` because global chrome is its purpose.',
+ 'Outside a `Shell -` template, leave global navigation to the host app. Put in-page navigation in a `LayoutPanel` and page headings in `LayoutHeader`.',
+ 'Use `Grid` with `columns={{minWidth: 280}}` for responsive collections. Do not fix the column count or rebuild the grid in raw CSS.',
+ 'Use `Center` for centered content instead of custom flexbox workarounds.',
+ 'Render one page from one source file. Links may be inert examples, but the template does not create nested routes or router integration.',
+ ],
+ },
+ {
+ type: 'table',
+ headers: ['Page condition', 'Points'],
+ rows: [
+ [
+ 'Correct root, responsive grids, proper centering, and one page',
+ '15',
+ ],
+ [
+ 'Valid root with a smaller issue such as fixed columns or multi-page behavior',
+ '8',
+ ],
+ [
+ 'Wrong root for the category, a raw layout root, or no Astryx root',
+ '0',
+ ],
+ ],
+ },
+ {type: 'heading', level: 3, text: 'Block templates'},
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'Do not wrap a block in `AppShell`. A block renders inside a preview or page container.',
+ 'Keep the block focused on one pattern or component usage.',
+ 'Keep the composition substantial enough to teach the pattern and small enough to adapt. About 20-100 lines is the normal range.',
+ ],
+ },
+ {
+ type: 'table',
+ headers: ['Block condition', 'Points'],
+ rows: [
+ [
+ 'No `AppShell`, one focused pattern, and a reasonable length',
+ '15',
+ ],
+ ['A smaller focus or length issue', '10'],
+ ['Wrapped in `AppShell` or deeply unfocused', '0'],
+ ],
+ },
+ ],
+ },
+ {
+ id: 'doc-metadata',
+ title: 'Doc metadata: 10 points',
+ content: [
+ {
+ type: 'prose',
+ text: 'Score field accuracy for 6 points, the description for 3 points, and naming for 1 point. Read the source and doc together. A field that exists but disagrees with the source is not complete.',
+ },
+ {type: 'heading', level: 3, text: 'Fields: 6 points'},
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Page: `type`, `name`, `displayName`, `description`, explicit `isReady`, and a specific `category` when the page is meant for browsing.',
+ 'Block: `type`, `name`, `displayName`, `description`, explicit `isReady`, positive `aspectRatio`, and complete `componentsUsed`.',
+ 'Relationship and preview fields follow {@link generic:block-template}. A value that contradicts that guide is an inaccuracy.',
+ ],
+ },
+ {
+ type: 'table',
+ headers: ['Field condition', 'Points'],
+ rows: [
+ ['All applicable fields are present and accurate', '6'],
+ ['All fields are present with one inaccuracy', '4'],
+ ['One required field is missing', '2'],
+ ['Two or more required fields are missing, or no doc exists', '0'],
+ ],
+ },
+ {type: 'heading', level: 3, text: 'Description: 3 points'},
+ {
+ type: 'prose',
+ text: 'A strong description covers four slots: the archetype, the job someone does, the structural or behavioral differentiator, and the alternate words people may search. Use at least six distinct content words after removing generic words such as page, screen, app, view, and component names. Describe the reusable shape, not only the sample data.',
+ },
+ {
+ type: 'table',
+ headers: ['Description condition', 'Points'],
+ rows: [
+ [
+ 'All four slots, 6 or more distinct content words, and clear separation from sibling templates',
+ '3',
+ ],
+ [
+ 'Names and differentiates the pattern but misses one slot or leaves a synonym implicit',
+ '2',
+ ],
+ [
+ 'Generic, repeats component names, or describes only the sample data',
+ '1',
+ ],
+ ['Missing or restates the name', '0'],
+ ],
+ },
+ {type: 'heading', level: 3, text: 'Naming: 1 point'},
+ {
+ type: 'prose',
+ text: 'The id follows {@link generic:start-a-template}, `displayName` is readable, and a browsable page has a specific category ({@link generic:page-template}). Slug length is guidance, not a scored condition.',
+ },
+ {
+ type: 'table',
+ headers: ['Naming condition', 'Points'],
+ rows: [
+ [
+ 'Id, display name, and applicable category follow the convention',
+ '1',
+ ],
+ ['Any naming or category requirement is missed', '0'],
+ ],
+ },
+ ],
+ },
+ {
+ id: 'image-handling',
+ title: 'Image handling: 5 points',
+ content: [
+ {
+ type: 'prose',
+ text: 'Inspect every image reference in the copied file against {@link generic:template-images-media}.',
+ },
+ {
+ type: 'table',
+ headers: ['Image condition', 'Points'],
+ rows: [
+ [
+ 'No image is needed, or every image still works after copy and the demo-placeholder behavior is intentional',
+ '5',
+ ],
+ [
+ 'One optional demo image is missing in preview, or a placeholder service remains',
+ '2',
+ ],
+ [
+ 'An essential image breaks after copy, uses a package-relative path, or depends on an inaccessible URL',
+ '0',
+ ],
+ ],
+ },
+ ],
+ },
+ {
+ id: 'code-quality',
+ title: 'Code quality: 10 points',
+ content: [
+ {
+ type: 'prose',
+ text: 'Award 2 points for each condition. Grade the copied file, not only the package source.',
+ },
+ {
+ type: 'table',
+ headers: ['Condition', 'Points', 'How to verify'],
+ rows: [
+ [
+ 'Correct client boundary',
+ '2',
+ '`use client` is the first executable statement when hooks, event handlers, or browser APIs require it. A static template does not add it without need.',
+ ],
+ [
+ 'Default export',
+ '2',
+ 'The copied file has one default-exported React component.',
+ ],
+ [
+ 'Self-contained imports',
+ '2',
+ 'Every import resolves from the copied location through React, a public Astryx path, a public integration-package export, or an app dependency the template explicitly requires.',
+ ],
+ [
+ 'Realistic example data',
+ '2',
+ 'Content has realistic names, amounts, dates, lengths, and states instead of lorem ipsum or numbered placeholders.',
+ ],
+ [
+ 'No dead code',
+ '2',
+ 'There are no unused imports or variables, commented-out blocks, or helpers that are never called.',
+ ],
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/template-icons.doc.mjs b/packages/cli/assets/docs/tree/template-icons.doc.mjs
new file mode 100644
index 0000000000..8980331e42
--- /dev/null
+++ b/packages/cli/assets/docs/tree/template-icons.doc.mjs
@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons`:
+ * render template icons through Astryx and ship custom product icons from the
+ * package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'template-icons',
+ placement: {
+ parent: 'namespace:template-assets',
+ slot: 'guides',
+ order: 40,
+ },
+ title: 'Icons',
+ category: 'guide',
+ description:
+ 'Keep icons consistent and accessible by rendering them through Astryx, and ship custom product icons from your package.',
+ sections: [
+ {
+ id: 'use-astryx-icon',
+ title: 'Use Astryx Icon',
+ content: [
+ {
+ type: 'prose',
+ text: 'Use `Icon` for a standalone icon. For a component icon prop, pass what that prop accepts: most, such as `Button` and `IconButton`, take an element like `<Icon icon={BellIcon} />`, and some menu and navigation items also accept the icon definition itself. This keeps sizing, color, and accessibility aligned with the system.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ code: `import {Button} from '@astryxdesign/core/Button';
+import {Icon} from '@astryxdesign/core/Icon';
+import {BellIcon} from '@heroicons/react/24/outline';
+
+<Icon icon={BellIcon} size="sm" />
+<Button label="Alerts" icon={<Icon icon={BellIcon} />} />`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Use one supported icon set consistently inside a template.',
+ 'Give an icon-only control its required visible or assistive label through the Astryx control API.',
+ 'Do not paste raw `svg` and `path` markup when an existing icon definition fits.',
+ 'Do not render a library icon directly when `Icon` or the receiving Astryx component can render it.',
+ 'Declare an icon library other than Astryx as a dependency ({@link generic:export-template-assets}).',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'ship-a-custom-icon',
+ title: 'Ship a custom icon deliberately',
+ content: [
+ {
+ type: 'prose',
+ text: 'A product mark or missing domain symbol can stay package-owned. Export a compatible icon definition from a public package path, then import that path from the template.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'templates/acme-dashboard.tsx',
+ code: `import {Icon} from '@astryxdesign/core/Icon';
+import {AcmePulseIcon} from '@acme/astryx-widgets/icons/AcmePulseIcon';
+
+<Icon icon={AcmePulseIcon} size="sm" label="Account health" />`,
+ },
+ {
+ type: 'prose',
+ text: 'Export the icon path and include its file in the package ({@link generic:export-template-assets}).',
+ },
+ ],
+ },
+ {
+ id: 'check-icons-in-the-app',
+ title: 'Check icons in the app',
+ content: [
+ {
+ type: 'prose',
+ text: 'When you test the template in an app ({@link generic:test-template-in-app}), also confirm the following.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Every icon state renders, including selected, disabled, loading, and narrow layouts.',
+ 'Meaningful icons have an accessible name, and decorative icons add no duplicate spoken text.',
+ 'No missing icon leaves an empty control.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/template-images-media.doc.mjs b/packages/cli/assets/docs/tree/template-images-media.doc.mjs
new file mode 100644
index 0000000000..5ca9962e04
--- /dev/null
+++ b/packages/cli/assets/docs/tree/template-images-media.doc.mjs
@@ -0,0 +1,127 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media`:
+ * keep template images and video working after the copy, or make them clear
+ * placeholders.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'template-images-media',
+ placement: {
+ parent: 'namespace:template-assets',
+ slot: 'guides',
+ order: 50,
+ },
+ title: 'Images and media',
+ category: 'guide',
+ description:
+ 'Make sure every image and video still works after the copy, or becomes a clear placeholder the app replaces.',
+ sections: [
+ {
+ id: 'do-not-copy-relative-media',
+ title: 'Do not rely on sibling media',
+ content: [
+ {
+ type: 'prose',
+ text: 'A reference such as `./hero.png` or `../assets/demo.mp4` stays unchanged in the copied file and normally breaks.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Use a stable public URL when the integration owner will continue to host the media.',
+ 'Use an explicit app-owned placeholder when every app must supply product-specific media.',
+ 'Use a package-owned JS or CSS entrypoint only when every supported app toolchain can resolve and emit the underlying asset.',
+ 'Do not assume that a file inside `node_modules` is automatically served at a browser URL.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'understand-template-assets',
+ title: 'Understand `/template-assets`',
+ content: [
+ {
+ type: 'prose',
+ text: '`/template-assets/<path>` is a preview-only fixture path. During copy, Astryx replaces a complete static image reference with an inline neutral SVG placeholder. It replaces a complete static video reference with an empty string because it cannot create a valid inline video.',
+ },
+ {
+ type: 'table',
+ headers: ['Source reference', 'Copied result'],
+ rows: [
+ ['`/template-assets/hero.png`', 'Inline SVG data URL placeholder'],
+ ['`/template-assets/demo.mp4`', 'Empty string'],
+ ['`./hero.png` or `/product/hero.png`', 'Unchanged'],
+ ['`https://example.com/template-assets/hero.png`', 'Unchanged'],
+ ],
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Supported preview image suffixes are SVG, PNG, JPG, JPEG, GIF, WebP, AVIF, and ICO.',
+ 'Supported preview video suffixes are MP4, WebM, MOV, OGV, and M4V.',
+ 'Keep the preview path as one complete static string. Concatenation, interpolation, method calls, module imports, and unknown file formats are rejected when Astryx cannot replace them safely.',
+ 'Use this path only when a placeholder is the intended copied result. It is not a way to ship required product media.',
+ 'Astryx serves `/template-assets` only in its own docs. A preview you host must serve that path itself.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'design-a-useful-placeholder',
+ title: 'Design a useful placeholder',
+ content: [
+ {
+ type: 'prose',
+ text: 'When the app must provide the final asset, keep the replacement point obvious in the copied source. Preserve enough surrounding layout and example data that the template still teaches the pattern without pretending the final content is included.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ code: `const HERO_IMAGE = '/acme-dashboard-hero.jpg';
+// Replace HERO_IMAGE with an app-owned public URL before shipping the page.
+
+<img
+ src={HERO_IMAGE}
+ alt="Account health trends for the current quarter"
+ width={1200}
+ height={675}
+/>`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Use accurate alternative text for informative images and `alt=""` for decoration.',
+ 'Provide dimensions or an aspect-ratio container so loading does not shift the page.',
+ 'For video, provide controls, a useful poster, and captions when the content requires them.',
+ 'Do not leave an inaccessible, expiring, authenticated, or environment-specific URL in copied source.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'check-media-in-the-app',
+ title: 'Check media in the app',
+ content: [
+ {
+ type: 'prose',
+ text: 'When you test the template in an app ({@link generic:test-template-in-app}), also confirm the following.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'The copied source shows the placeholder substitutions you expect.',
+ 'The network log has no missing, redirected, blocked, or unauthorized media requests.',
+ 'Each placeholder keeps the layout and says what the app must replace.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/template-styles.doc.mjs b/packages/cli/assets/docs/tree/template-styles.doc.mjs
new file mode 100644
index 0000000000..988ff71808
--- /dev/null
+++ b/packages/cli/assets/docs/tree/template-styles.doc.mjs
@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles`:
+ * style a template with Astryx first, keep editable styles in the file, and
+ * ship shared CSS from the package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'template-styles',
+ placement: {
+ parent: 'namespace:template-assets',
+ slot: 'guides',
+ order: 20,
+ },
+ title: 'Styles',
+ category: 'guide',
+ description:
+ "Keep the copied UI on the app's theme: use Astryx props and tokens first, keep editable styles in the file, and ship shared CSS from your package.",
+ sections: [
+ {
+ id: 'start-with-astryx',
+ title: 'Start with Astryx',
+ content: [
+ {
+ type: 'prose',
+ text: 'Use Astryx component props, layout primitives, and design tokens before writing custom CSS. This keeps the copied result aligned with the host theme and reduces the styling contract an app inherits.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Use Stack and Grid spacing props instead of margins between children.',
+ 'Use component variants, sizes, padding, and alignment props before restyling internals.',
+ 'Use public theme token exports for a value that Astryx does not expose as a prop.',
+ 'Do not copy private generated class names or target component internals with selectors.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'keep-editable-styles-with-the-source',
+ title: 'Keep editable styles with the source',
+ content: [
+ {
+ type: 'prose',
+ text: 'When a style belongs to the editable starting point, define it in the template file.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ code: `import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '@astryxdesign/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ trend: {
+ color: colorVars['--color-success'],
+ minWidth: 0,
+ },
+});
+
+// Later: <Text xstyle={styles.trend}>Up 12%</Text>`,
+ },
+ {
+ type: 'prose',
+ text: 'Use custom declarations only when no Astryx prop or token fits. Each one counts in the Custom CSS category of {@link generic:template-grading-rubric}.',
+ },
+ ],
+ },
+ {
+ id: 'publish-shared-css',
+ title: 'Publish shared CSS deliberately',
+ content: [
+ {
+ type: 'prose',
+ text: 'When a stylesheet must stay package-owned, import it from the template by its public package path.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ label: 'templates/acme-dashboard.tsx',
+ code: "import '@acme/astryx-widgets/styles/acme-dashboard.css';",
+ },
+ {
+ type: 'prose',
+ text: 'Then export that path and include the file in the package ({@link generic:export-template-assets}). In a TypeScript app, this import type-checks only when the app declares `*.css` modules.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/templates.doc.mjs b/packages/cli/assets/docs/tree/templates.doc.mjs
new file mode 100644
index 0000000000..be9700b915
--- /dev/null
+++ b/packages/cli/assets/docs/tree/templates.doc.mjs
@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates`: guides for adding,
+ * documenting, packaging, and testing templates in an integration package.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'templates',
+ placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 20},
+ title: 'Templates',
+ summary:
+ 'Templates are ready-made UI pages or page sections built with Astryx. Apps copy them into their code and adapt them to their product.',
+ keywords: [
+ 'integration template',
+ 'template quality',
+ 'template grading',
+ 'template assets',
+ 'template package',
+ 'replace a core template',
+ ],
+ slots: {
+ build: {
+ title: 'Build',
+ accepts: {kinds: ['generic', 'namespace']},
+ },
+ quality: {
+ title: 'Quality',
+ accepts: {kinds: ['namespace']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
new file mode 100644
index 0000000000..e03df93fd7
--- /dev/null
+++ b/packages/cli/assets/docs/tree/test-in-an-app.doc.mjs
@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/test-in-an-app`: install the packed
+ * package in an app and run the commands its users run.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'test-in-an-app',
+ placement: {parent: 'namespace:ship', slot: 'guides', order: 10},
+ title: 'Test an integration in an app',
+ category: 'guide',
+ keywords: ['test an integration locally', 'try an integration in an app'],
+ description:
+ 'Install your packed package in an app and run the commands its users will run.',
+ sections: [
+ {
+ id: 'install-the-packed-package',
+ title: 'Install the packed package in an app',
+ content: [
+ {
+ type: 'prose',
+ text: 'Pack the package beside its folder, so the next pack does not ship it, then install it in an app together with Core and the CLI. The app loads your package because it is a dependency.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: '# In the package\nnpm pack --pack-destination ..\n\n# In an app folder beside it\nnpm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ "Install the CLI in the app too: `npx astryx` runs the CLI from the app's `node_modules`.",
+ 'The app holds a copy, not a link. After each change, pack again and run the same `npm install`.',
+ 'Reading your work inside the package shows your source. The app shows what npm would publish.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'check-what-the-app-sees',
+ title: 'Check what the app sees',
+ content: [
+ {
+ type: 'prose',
+ text: 'From the app folder, run the commands your users run. Each should show your contribution under your package name.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx component AcmeCarousel\nnpx astryx template --list --package @acme/astryx-widgets\nnpx astryx theme list --package @acme/astryx-widgets\nnpx astryx docs acme\nnpx astryx search deploying --type doc',
+ },
+ {
+ type: 'table',
+ headers: ['Command', 'Look for'],
+ rows: [
+ [
+ '`component AcmeCarousel`',
+ "`import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';`",
+ ],
+ [
+ '`template --list --package`',
+ 'An `acme-dashboard` entry with `package: @acme/astryx-widgets`',
+ ],
+ [
+ '`theme list --package`',
+ '`- ocean (maintained, @acme/astryx-widgets)`',
+ ],
+ ['`docs acme`', 'Your section, with guides such as `deploying`'],
+ [
+ '`search deploying --type doc`',
+ '`acme/deploying` as the first result',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: "`--package` narrows `template --list` and `theme list` to one package. `component --list` ignores it and lists Core too, so look a component up by name. Last, import `AcmeCarousel` in the app's code and build the app, as your users will.",
+ },
+ ],
+ },
+ {
+ id: 'run-doctor-in-the-app',
+ title: 'Run doctor in the app',
+ content: [
+ {
+ type: 'prose',
+ text: '`npx astryx doctor` checks the whole app, including every package it loaded. `doctor integration validate` checks your package as the app installed it.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx doctor\nnpx astryx doctor integration validate @acme/astryx-widgets',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'id: implicit-integrations\nstatus: [info]\nlabel: Implicitly linked integrations\nmessage: 1 integration loaded from installed dependencies with no astryx.config entry: @acme/[email protected] from dependencies, contributing components, templates, themes, docs, codemods.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'The `implicit-integrations` row names each package the app loads with no config. `[info]` is expected.',
+ 'The `docs-progressive-disclosure` row warns when one of your doc sections is over 32 KB. The `doctor integration` checks do not measure size.',
+ '`doctor integration validate @acme/astryx-widgets` prints `[ok] No integration issues found.` when the installed copy is sound.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs b/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
new file mode 100644
index 0000000000..5763a9657b
--- /dev/null
+++ b/packages/cli/assets/docs/tree/test-template-in-app.doc.mjs
@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app`:
+ * copy the packed template into a clean app, build it, and render it the way
+ * apps will.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'test-template-in-app',
+ placement: {
+ parent: 'namespace:package-and-test',
+ slot: 'guides',
+ order: 30,
+ },
+ title: 'Test in an app',
+ category: 'guide',
+ description:
+ 'Prove the template works the way apps use it: installed from the packed package, copied, built, and rendered.',
+ sections: [
+ {
+ id: 'install-the-packed-package',
+ title: 'Install the packed package',
+ content: [
+ {
+ type: 'prose',
+ text: 'Install the packed package in a clean app as described in {@link generic:test-in-an-app}. Also install every library the copied source imports, such as its icon library. Pack and reinstall after every change.',
+ },
+ ],
+ },
+ {
+ id: 'copy-the-template',
+ title: 'Copy the template',
+ content: [
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `# Confirm discovery and metadata
+npx astryx --json template --list --package @acme/astryx-widgets
+
+# Inspect source without writing
+npx astryx template acme-dashboard --package @acme/astryx-widgets
+
+# Copy a page and a block to their real app locations
+npx astryx template acme-dashboard --package @acme/astryx-widgets src/app/acme-dashboard
+npx astryx template acme-stat-card --package @acme/astryx-widgets src/components`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Confirm the copied files: `src/app/acme-dashboard/page.tsx` and `src/components/acme-stat-card.tsx`.',
+ 'Inspect the copied source for placeholder substitutions and relative references.',
+ 'Import the copied block into a real page. A file that is never imported has not been tested.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'build-every-supported-app',
+ title: 'Build every supported app',
+ content: [
+ {
+ type: 'prose',
+ text: "Run the type check (`npx tsc --noEmit`, or the app's own script) and the production build in every framework or bundler the integration supports. One toolchain passing does not prove another.",
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `npx tsc --noEmit
+npm run build`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Every import resolves from the copied location.',
+ 'Production builds keep required side-effect CSS.',
+ 'No import bypasses `exports`, and no dependency resolves only through workspace hoisting.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'render-the-behavior-matrix',
+ title: 'Render the behavior matrix',
+ content: [
+ {
+ type: 'table',
+ headers: ['Dimension', 'Required checks'],
+ rows: [
+ ['Width', 'Wide and narrow; include the smallest supported viewport'],
+ ['Color', 'Every supported color mode and theme'],
+ ['Input', 'Keyboard and pointer for the primary task'],
+ [
+ 'Content',
+ 'Realistic, empty, long, loading, and error states that the pattern supports',
+ ],
+ [
+ 'Assets',
+ 'Successful CSS, font, icon, image, poster, and video requests',
+ ],
+ [
+ 'Runtime',
+ 'No console error, hydration mismatch, or missing-provider failure',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Check the rendered hierarchy, reading order, focus order, clipping, overflow, and fallback states. A screenshot of one default state is not a complete test.',
+ },
+ ],
+ },
+ {
+ id: 'grade-the-result',
+ title: 'Grade the result',
+ content: [
+ {
+ type: 'prose',
+ text: 'Grade the exact packed revision using the evidence from this test ({@link namespace:write-good-templates}).',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/themes.doc.mjs b/packages/cli/assets/docs/tree/themes.doc.mjs
new file mode 100644
index 0000000000..76f7ed9072
--- /dev/null
+++ b/packages/cli/assets/docs/tree/themes.doc.mjs
@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes`: author a theme
+ * in an integration; apps install, apply, and extend it like any theme.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'themes',
+ placement: {parent: 'namespace:building-blocks', slot: 'guides', order: 30},
+ title: 'Themes',
+ summary:
+ 'Author a theme in your integration; apps install, apply, and extend it like any theme.',
+ keywords: [
+ 'integration theme',
+ 'ship a theme',
+ 'define theme',
+ 'theme palette',
+ 'extend a theme',
+ ],
+ blocks: [
+ {
+ type: 'prose',
+ text: 'A theme is an editable `defineTheme` source with a generated color palette. An integration ships a theme the same way a standalone theme package does: an app installs the package, applies the theme with `<Theme>`, and customizes it with `extends`. An integration theme and a standalone theme package are the same shape.',
+ },
+ {
+ type: 'prose',
+ text: 'These guides cover authoring a theme inside an integration — scaffold it, generate its palette, define its tokens, ship its fonts, and document it. Using a theme, applying and extending it, is the same for every theme; see {@link generic:theme}.',
+ },
+ ],
+ slots: {
+ guides: {
+ title: 'Guides',
+ accepts: {kinds: ['generic']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/troubleshooting.doc.mjs b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
new file mode 100644
index 0000000000..34ec5e751a
--- /dev/null
+++ b/packages/cli/assets/docs/tree/troubleshooting.doc.mjs
@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/troubleshooting`: the messages the CLI
+ * prints while you build, verify, and install an integration, and the fix
+ * for each.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'troubleshooting',
+ placement: {parent: 'namespace:help', slot: 'guides', order: 10},
+ title: 'Troubleshooting',
+ category: 'guide',
+ keywords: ['integration error', 'integration not loading'],
+ description:
+ 'Find the message the CLI printed while you build, verify, or install an integration, and apply its fix.',
+ sections: [
+ {
+ id: 'fix-setup-errors',
+ title: 'Fix setup errors',
+ content: [
+ {
+ type: 'prose',
+ text: 'These appear while you start the package or run the CLI in it. Each row quotes what the CLI prints.',
+ },
+ {
+ type: 'table',
+ headers: ['Message', 'Fix'],
+ rows: [
+ [
+ '`No package.json found. Run this command inside an integration package.`',
+ 'Run `npm init -y` and `npm pkg set name=@acme/astryx-widgets` first, in the package folder.',
+ ],
+ [
+ '`Error: Could not find @astryxdesign/core package`',
+ 'Component commands read Core. Run `npm install -D @astryxdesign/core` in the package.',
+ ],
+ [
+ '`core_not_found`: `Could not resolve @astryxdesign/core, so component names could not be checked.`',
+ 'Same fix. The check exits 1.',
+ ],
+ [
+ "`Error: unknown subcommand 'integration verify'`, or `Error: Pass --check to verify the integration tarball.`",
+ 'Your CLI is older than `integration verify`. Run `npm install -D @astryxdesign/cli@latest`. On the older CLI, the same check is `integration pack --check`.',
+ ],
+ [
+ 'Note: `integration pack --check` is deprecated.',
+ 'The old name still runs the same check. Switch to `npx astryx integration verify`; the old name will be removed in a later release.',
+ ],
+ ],
+ },
+ ],
+ },
+ {
+ id: 'fix-verify-failures',
+ title: 'Fix integration verify failures',
+ content: [
+ {
+ type: 'prose',
+ text: '`npx astryx integration verify` prints each failure as a `[fail]` line. Add `--json` to see its issue code, such as `component_export_missing`.',
+ },
+ {
+ type: 'table',
+ headers: ['Message', 'Fix'],
+ rows: [
+ [
+ '`component_export_missing`: `Component "AcmeCarousel" advertises import "@acme/astryx-widgets/components/AcmeCarousel", but that packed module does not export "AcmeCarousel".`',
+ "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`.",
+ ],
+ [
+ '`template_export_missing`: `Template "acme-dashboard" public import "@acme/astryx-widgets/templates/acme-dashboard" does not have a default export.`',
+ 'Run `npm pkg set \'exports[./templates/acme-dashboard]=./templates/acme-dashboard.tsx\'`, and keep `export default` in the source. Start new packages with `"exports": {}` so each add writes these.',
+ ],
+ [
+ '`component_import_unresolvable` or `template_import_unresolvable`: `…Package subpath \'./components/AcmeCarousel\' is not defined by "exports"…`',
+ "The `exports` map has no entry for it. Run `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`, or `'exports[./templates/acme-dashboard]=./templates/acme-dashboard.tsx'` for a template.",
+ ],
+ [
+ '`component_import_unresolvable`: `…but a consumer cannot resolve it: Cannot find package \'@acme/old-name\'`',
+ "You renamed the package after the add wrote each doc's `import`. Change `import` in every component doc to the new name.",
+ ],
+ [
+ '`Declared templates root "templates" has 0 of 2 expected files in the pack list. Add "templates" to "files" in package.json.`',
+ "Run `npm pkg set 'files[]=templates'`.",
+ ],
+ [
+ '`docs_tree_needs_cli`: `The package ships a namespace doc or a placed guide but declares no @astryxdesign/cli peer.`',
+ "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.7.0'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`.",
+ ],
+ [
+ '`replaces_needs_cli`: The package has a template that sets `replaces` but declares no @astryxdesign/cli peer.',
+ 'Same fix: an older CLI rejects `replaces`, drops that template, and hides your doc topics.',
+ ],
+ [
+ '`themes_need_cli`: The package ships a theme but declares no @astryxdesign/cli peer.',
+ 'Same fix: an older CLI cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.',
+ ],
+ [
+ '`section_ids_need_cli`: The package has a doc section that sets `id` but declares no @astryxdesign/cli peer.',
+ 'Same fix, or drop the section `id`s: an older CLI rejects them and hides your doc topics.',
+ ],
+ ],
+ },
+ ],
+ },
+ {
+ id: 'fix-problems-in-an-app',
+ title: 'Fix problems in an app',
+ content: [
+ {
+ type: 'prose',
+ text: 'These appear in an app that installs your package, or in the doctor checks that predict them.',
+ },
+ {
+ type: 'table',
+ headers: ['Symptom', 'Fix'],
+ rows: [
+ [
+ '`Error: Template "dashboard" is ambiguous — narrow it with --type and/or --package.`',
+ "Your template id matches a Core id. Rename it, such as `acme-dashboard`, or set `replaces: 'dashboard'` to take its place. `npx astryx doctor integration templates` warns about this before you publish.",
+ ],
+ [
+ '`invalid_doc_graph`: `placement.parent "namespace:nope" names no namespace; @acme/astryx-widgets declares "acme".`',
+ 'The guide stays hidden until its `placement` names a namespace and slot your package declares. For `"…" names no doc`, fix the link target.',
+ ],
+ [
+ 'Error: Unknown topic "acme". The docs of @acme/astryx-widgets did not load; run `astryx doctor integration docs` in that package to see why.',
+ 'One invalid doc hides all of your docs. Run `npx astryx doctor integration docs` in the package and fix the `invalid_doc` it names.',
+ ],
+ [
+ '`npx astryx upgrade` runs none of your codemods',
+ 'The app must list your package in `integrations` in `astryx.config`, or pass `--integration @acme/astryx-widgets`. It runs a codemod folder only when its version is after `--from` and at most the installed `@astryxdesign/core`.',
+ ],
+ [
+ 'Your docs section, templates, or themes are missing only in some apps',
+ 'Those apps run a stable CLI before 0.7.0. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',
+ ],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'What each check catches is in {@link generic:checks}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/upgrading.doc.mjs b/packages/cli/assets/docs/tree/upgrading.doc.mjs
new file mode 100644
index 0000000000..eae5e7b239
--- /dev/null
+++ b/packages/cli/assets/docs/tree/upgrading.doc.mjs
@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/upgrading`: update an integration
+ * package for each Astryx release, and the command apps run to upgrade with
+ * it.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'upgrading',
+ placement: {parent: 'namespace:ship', slot: 'guides', order: 50},
+ title: 'Upgrading',
+ category: 'guide',
+ keywords: ['upgrade apps', 'release notes'],
+ description:
+ 'Update your package for each Astryx release, and help apps upgrade with it.',
+ sections: [
+ {
+ id: 'update-for-a-new-astryx-release',
+ title: 'Update for a new Astryx release',
+ content: [
+ {
+ type: 'prose',
+ text: 'When Astryx ships a release, bump your devDependencies, rerun the checks, widen your peer ranges, and ship a codemod for each change that breaks apps.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: "# 1. Build and test against the new release\nnpm install -D @astryxdesign/cli@latest @astryxdesign/core@latest\n# 2. Rerun the checks\nnpx astryx doctor integration validate\nnpx astryx doctor integration docs\nnpx astryx integration verify\n# 3. Admit the new Core once the checks pass\nnpm pkg set 'peerDependencies.@astryxdesign/core=^0.6.0 || ^0.7.0'\n# 4. Migrate apps across a change that breaks them\nnpx astryx integration add codemod rename-delay --to 0.7.0",
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Run every check in {@link generic:checks}, not only the ones shown.',
+ 'Name each codemod folder after the Core version whose upgrade should run it; see {@link generic:codemods}.',
+ 'Release the result as a new version of your package; see {@link generic:publishing}.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'upgrade-an-app',
+ title: 'Upgrade an app',
+ content: [
+ {
+ type: 'prose',
+ text: 'After an app installs a new Core, `astryx upgrade` runs the codemods for the versions it crossed. It is a dry run by default; `--apply` writes the changes.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: '# Preview what would change; nothing is written\nnpx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets\n# Write the changes\nnpx astryx upgrade --from 0.6.3 --integration @acme/astryx-widgets --apply',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: 'Integrations: @acme/astryx-widgets\n1 codemod to run\nApplying integration codemods...\n Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok] [ok] src/Hero.tsx',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`--from` is the `@astryxdesign/core` version the app had before, and the target is the installed Core.',
+ '`--integration` names your package. Without it, or an `integrations` entry in `astryx.config`, the upgrade skips your codemods, even when the app has your package installed.',
+ "The count includes Core's codemods for the same versions, which run first.",
+ 'Put this command in your release notes.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'know-which-files-upgrades-skip',
+ title: 'Know which files upgrades skip',
+ content: [
+ {
+ type: 'prose',
+ text: 'Upgrades never write files that the app marks as generated, vendored, or ignored. When such a file still needs a codemod change, the upgrade stops with `ERR_CODEMOD_PROTECTED` and exit code 1.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Generated: an `@generated` comment at the top of the file, or `linguist-generated` in `.gitattributes`.',
+ 'Vendored: `linguist-vendored` in `.gitattributes`.',
+ 'Ignored: a match in `.gitignore` or `.hgignore`.',
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code: '! ! src/gen/Gen.tsx - protected by @generated in the leading comment block\nERR_CODEMOD_PROTECTED: 1 protected file still requires a codemod change:\n src/gen/Gen.tsx — @generated in the leading comment block\nUpgrade incomplete: protected changes remain',
+ },
+ {
+ type: 'prose',
+ text: 'The upgrade still writes every other file. Its options and exit codes are in {@link command:upgrade}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs b/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
new file mode 100644
index 0000000000..2e5b75874c
--- /dev/null
+++ b/packages/cli/assets/docs/tree/use-a-theme-in-an-app.doc.mjs
@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app`:
+ * an app installs the integration and applies or extends the theme, like any theme.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'use-a-theme-in-an-app',
+ placement: {parent: 'namespace:themes', slot: 'guides', order: 40},
+ title: 'Use and extend the theme',
+ category: 'guide',
+ description:
+ 'An app installs the integration and applies or extends your theme, the same as any theme.',
+ sections: [
+ {
+ id: 'apply-the-theme',
+ title: 'Apply the theme',
+ content: [
+ {
+ type: 'prose',
+ text: 'An app installs the integration as a dependency and applies your theme like any Astryx theme: wrap the app in `<Theme>`. The theme comes from the installed package — there is no copy step. Your theme only names its fonts; the app loads them ({@link generic:fonts-and-assets}).',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ code: `import {Theme} from '@astryxdesign/core/theme';
+import {oceanTheme} from '@acme/astryx-widgets/themes/ocean';
+
+<Theme theme={oceanTheme}>{/* app */}</Theme>`,
+ },
+ {
+ type: 'prose',
+ text: 'The import specifier is whatever your integration exports for the theme. Applying a theme — `mode`, SSR, and the production build — works the same for every theme; see {@link generic:theme}.',
+ },
+ ],
+ },
+ {
+ id: 'extend-the-theme',
+ title: 'Extend to customize',
+ content: [
+ {
+ type: 'prose',
+ text: 'To change a theme, an app does not copy it — it derives a new one with `extends`: import your theme and override only the tokens it changes. See {@link generic:define-the-theme}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs b/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
new file mode 100644
index 0000000000..ed107bf35b
--- /dev/null
+++ b/packages/cli/assets/docs/tree/verify-packed-template.doc.mjs
@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/verify-packed-template`:
+ * what `integration verify` checks for templates, and what it leaves to the
+ * app test.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'verify-packed-template',
+ placement: {
+ parent: 'namespace:package-and-test',
+ slot: 'guides',
+ order: 20,
+ },
+ title: 'Verify the packed package',
+ category: 'guide',
+ description:
+ 'Catch missing files, exports, and CLI requirements before you publish, and know what still needs the app test.',
+ sections: [
+ {
+ id: 'run-the-package-check',
+ title: 'Run the package check',
+ content: [
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npx astryx integration verify',
+ },
+ {
+ type: 'prose',
+ text: '`integration verify` runs `npm pack`, including lifecycle scripts, unpacks the `.tgz` file into a temporary app without installing its dependencies, and checks the unpacked integration. It publishes nothing and removes the `.tgz` file and the temporary app.',
+ },
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'It validates the manifest, every template doc, its source file, and the templates directory.',
+ 'It checks that the manifest and every template file are in the `.tgz` file.',
+ 'It checks that each packed template keeps the same id, type, `name`, and `replaces` as your working copy. It does not compare template source or other doc fields.',
+ 'It resolves each template through its public package path in the unpacked package.',
+ 'It checks that the resolved template module has a default export.',
+ 'It checks the CLI peer that features such as template replacement require.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Each failure prints a `[fail]` line with its message; add `--json` to see each issue code. {@link generic:troubleshooting} lists the common messages and their fixes. Fix every error, and review every warning before publishing.',
+ },
+ ],
+ },
+ {
+ id: 'know-what-it-does-not-prove',
+ title: 'Know what it does not prove',
+ content: [
+ {
+ type: 'prose',
+ text: '`integration verify` checks the packed templates and their public entrypoints. It does not copy a template into an app or run a browser build, so it cannot show the following.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Whether a relative helper or stylesheet survives the copy.',
+ 'Whether the copied file type-checks in every supported app toolchain.',
+ 'Whether package-owned CSS, fonts, icons, images, or media load in a browser.',
+ 'Whether layout, color modes, keyboard and pointer input, and real content work.',
+ 'Whether a template id collides with Core, or whether a `replaces` target exists. Run `npx astryx doctor integration templates` for those.',
+ 'How the template scores on quality.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/versioning.doc.mjs b/packages/cli/assets/docs/tree/versioning.doc.mjs
new file mode 100644
index 0000000000..6493de4def
--- /dev/null
+++ b/packages/cli/assets/docs/tree/versioning.doc.mjs
@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/versioning`: version an integration
+ * package, know which changes break apps, declare peer ranges, keep apps on
+ * older CLIs working, and match codemod folders to versions.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'versioning',
+ placement: {parent: 'namespace:ship', slot: 'guides', order: 30},
+ title: 'Versioning',
+ category: 'guide',
+ keywords: ['peer dependency', 'semver', 'cli version'],
+ description:
+ 'Version your package, declare its peers, and keep apps on older CLIs working.',
+ sections: [
+ {
+ id: 'pick-a-version',
+ title: 'Pick a version',
+ content: [
+ {
+ type: 'prose',
+ text: 'Version your package with semver: a major version for a breaking change, a minor version for a new feature, and a patch for a fix.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: '# 1.0.0 -> 2.0.0: a breaking change\nnpm version major\n# 1.0.0 -> 1.1.0: a new feature\nnpm version minor\n# 1.0.0 -> 1.0.1: a fix\nnpm version patch',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Before 1.0.0, npm treats each minor version as breaking: an app that asks for `^0.6.0` never gets `0.7.0`. Bump the minor version for a breaking change, and the patch for anything else.',
+ 'Ship a codemod with each breaking change so apps can migrate; see {@link generic:codemods}.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'know-what-breaks-apps',
+ title: 'Know what breaks apps',
+ content: [
+ {
+ type: 'prose',
+ text: 'A breaking change stops code, commands, or links that worked in an app from working after the upgrade. For an integration, these names are part of its API.',
+ },
+ {
+ type: 'table',
+ headers: ['You change or remove', 'What stops working in the app'],
+ rows: [
+ [
+ 'A component name, such as `AcmeCarousel`',
+ 'Imports, and `npx astryx component AcmeCarousel`',
+ ],
+ [
+ 'A template id, such as `acme-dashboard`',
+ '`npx astryx template acme-dashboard`',
+ ],
+ ['A theme slug, such as `ocean`', '`npx astryx theme add ocean`'],
+ [
+ 'A topic name or route, such as `acme/deploying`',
+ 'Reads of the old name, and links to it from other docs',
+ ],
+ [
+ "A component's `import` path",
+ 'Imports written from the old path',
+ ],
+ [
+ 'An `exports` entry',
+ 'Imports of that path, which fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`',
+ ],
+ ['A prop', 'Code that passes it'],
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'List each breaking change in your release notes, with the codemod that migrates it. Any changelog tool works. If `package.json` has a `files` allowlist, add `CHANGELOG.md` to it so npm packs it.',
+ },
+ ],
+ },
+ {
+ id: 'declare-peer-ranges',
+ title: 'Declare peer ranges',
+ content: [
+ {
+ type: 'prose',
+ text: 'Declare the Astryx packages that your code imports as peer dependencies, in `peerDependencies`, so the app installs one copy of each. Keep each range as wide as your tests prove.',
+ },
+ {
+ type: 'table',
+ headers: ['Peer', 'Declare it when', 'Range'],
+ rows: [
+ [
+ '`@astryxdesign/core`',
+ 'Your code imports Core, as a theme does with `@astryxdesign/core/theme`',
+ 'The Core versions you test, such as `^0.6.0`',
+ ],
+ [
+ '`@astryxdesign/theme-*`',
+ 'Your code imports that theme package',
+ 'The versions you test',
+ ],
+ [
+ '`@astryxdesign/cli`',
+ 'You ship a docs section, a placed guide, a template that sets `replaces`, a doc section with an `id`, or a theme',
+ '`>=0.7.0`, optional in `peerDependenciesMeta`',
+ ],
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'json',
+ code: '{\n "peerDependencies": {\n "@astryxdesign/core": "^0.6.0",\n "@astryxdesign/cli": ">=0.7.0"\n },\n "peerDependenciesMeta": {\n "@astryxdesign/cli": {"optional": true}\n }\n}',
+ },
+ {
+ type: 'prose',
+ text: '`integration verify` fails a package that needs the CLI peer and lacks it, or whose range admits a stable CLI before 0.7.0. `integration add doc --parent` and `integration add theme` write the peer for you.',
+ },
+ ],
+ },
+ {
+ id: 'support-older-clis',
+ title: 'Support older CLIs',
+ content: [
+ {
+ type: 'prose',
+ text: 'An app may run an older CLI than the one you build with. A CLI reads what it knows and skips the rest, but some newer files make an older CLI hide your docs.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'An unknown field in `astryx.integration.mjs` is ignored with an `unknown_manifest_key` warning, and the rest of the manifest still loads.',
+ 'A named export that the CLI does not know is ignored with no warning, so `debug` and `gapReport` are safe to add.',
+ 'A stable CLI before 0.7.0 prints each `{@link ...}` as written.',
+ 'A stable CLI before 0.7.0 cannot read a docs section, a section `id`, a template that sets `replaces`, or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.',
+ 'Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: '`integration verify` requires the CLI peer for a docs section, a placed guide, a template `replaces`, a doc section with an `id`, and a theme. A stable CLI before 0.7.0 cannot read any of them, and when it hides your topics, `docs` gives no warning.',
+ },
+ ],
+ },
+ {
+ id: 'codemods-and-versions',
+ title: 'Name codemod folders after Core versions',
+ content: [
+ {
+ type: 'prose',
+ text: 'Name each codemod folder after the Core version whose upgrade should run it, not after your package\'s version. Which folders an app runs, and when, is in "Choose when a codemod runs" in {@link generic:codemods}.',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/write-good-templates.doc.mjs b/packages/cli/assets/docs/tree/write-good-templates.doc.mjs
new file mode 100644
index 0000000000..52e1eff0c9
--- /dev/null
+++ b/packages/cli/assets/docs/tree/write-good-templates.doc.mjs
@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates`:
+ * what makes a template good, the rubric that scores it, and grading with an agent.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+ type: 'namespace',
+ name: 'write-good-templates',
+ placement: {parent: 'namespace:templates', slot: 'quality', order: 10},
+ title: 'How to write good templates',
+ summary:
+ 'Write templates people trust: what good means, the rubric that scores it, and how to grade one with an agent.',
+ keywords: [
+ 'template quality',
+ 'template rubric',
+ 'grade template',
+ 'template review',
+ ],
+ blocks: [
+ {
+ type: 'prose',
+ text: 'A good template does more than render. It gives an app a clear product starting point that is easy to understand, safe to change, and complete after Astryx copies it out of the package. A rubric scores that quality so you can grade as you build.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Its purpose and primary task are clear before someone reads every detail.',
+ 'It composes Astryx components instead of rebuilding their behavior with raw HTML or custom styles.',
+ 'Its hierarchy, spacing, interactions, and reading order still work at narrow widths and in every supported color mode.',
+ 'Its source, imports, styles, fonts, icons, images, and media still work from the copied location.',
+ 'Its metadata makes the template easy to find and accurately explains when to use it.',
+ 'Its example content is realistic enough to expose overflow, empty-space, and hierarchy problems.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Grade the first runnable version, again after each source, doc, dependency, or asset change, and in full before every release. Grade the source, doc, copied file, and rendered app together; none of them is enough alone.',
+ },
+ {
+ type: 'list',
+ style: 'ordered',
+ items: [
+ 'Read every scoring rule in {@link generic:template-grading-rubric}.',
+ 'Fix publication blockers first, then every reasonable deduction.',
+ 'Repeat the full grade on the packed package in a clean app ({@link generic:test-template-in-app}).',
+ 'To have an agent grade and improve the template, use {@link generic:grade-template-with-agent}.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Keep each scorecard with its package revision and rubric version.',
+ },
+ ],
+ slots: {
+ guides: {
+ title: 'Guides',
+ accepts: {kinds: ['generic']},
+ },
+ },
+};
diff --git a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
new file mode 100644
index 0000000000..f0c9fb7b51
--- /dev/null
+++ b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs
@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/build-the-template/write-the-template-file`:
+ * what gets copied, where the copied file lands, and the imports and
+ * export a copied template needs.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+ type: 'generic',
+ name: 'write-the-template-file',
+ placement: {
+ parent: 'namespace:build-the-template',
+ slot: 'guides',
+ order: 10,
+ },
+ title: 'Write the template file',
+ category: 'guide',
+ description:
+ 'Astryx copies just this one file into an app, so write it to work on its own there: where it lands, what it can import, and what it exports.',
+ sections: [
+ {
+ id: 'know-what-gets-copied',
+ title: 'Know what gets copied',
+ content: [
+ {
+ type: 'prose',
+ text: '`astryx template` copies exactly one source file. It does not copy sibling helpers, stylesheets, fonts, icons, images, or media. Plan for that before you add supporting files.',
+ },
+ {
+ type: 'table',
+ headers: ['Template', 'Directory target', 'Explicit file target'],
+ rows: [
+ ['Page', 'Writes `<target>/page.tsx`', 'Writes the exact file path'],
+ [
+ 'Block',
+ 'Writes `<target>/<source-basename>.tsx`',
+ 'Writes the exact file path',
+ ],
+ ],
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: `# Page: src/app/account/page.tsx
+npx astryx template acme-account src/app/account
+
+# Block: src/features/account/acme-stat-card.tsx
+npx astryx template acme-stat-card src/features/account
+
+# Exact destination for either kind
+npx astryx template acme-stat-card src/features/account/StatusCard.tsx`,
+ },
+ {
+ type: 'prose',
+ text: 'Astryx refuses to replace an existing file unless the caller passes `--overwrite` or `-f`.',
+ },
+ ],
+ },
+ {
+ id: 'keep-edited-code-in-one-file',
+ title: 'Keep edited code in one file',
+ content: [
+ {
+ type: 'prose',
+ text: 'Put every helper that the app is expected to edit in the template source. Small local components, example data, constants, and event handlers can live above or below the default component in the same file.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Inline a helper when it is part of the editable starting point.',
+ 'Move a helper into the integration package only when it should stay package-owned and update with the package.',
+ 'Do not import `./helper`, `./styles`, or any other sibling file.',
+ 'Do not create routes, configuration, or extra files at runtime. Give the app one explicit source file to own.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'use-imports-that-work',
+ title: 'Use imports that work in the app',
+ content: [
+ {
+ type: 'prose',
+ text: 'After the copy, imports resolve from the app, not from the template directory. Every bare import must name a package the app installs, and every package path must be public.',
+ },
+ {
+ type: 'code',
+ lang: 'tsx',
+ code: `import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';
+
+const metrics = [
+ {label: 'Healthy accounts', value: '1,248'},
+ {label: 'Needs review', value: '37'},
+];
+
+function MetricRow({label, value}: {label: string; value: string}) {
+ return (
+ <HStack justify="between">
+ <Text>{label}</Text>
+ <Text>{value}</Text>
+ </HStack>
+ );
+}
+
+export default function AcmeAccountSummary() {
+ return (
+ <Card>
+ <VStack gap={4}>
+ <AcmeStatusCard />
+ {metrics.map(metric => <MetricRow key={metric.label} {...metric} />)}
+ <Button label="Review accounts" />
+ </VStack>
+ </Card>
+ );
+}`,
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Import Astryx components from their public Core paths.',
+ 'Import integration-owned components, helpers, icons, or styles only through paths the package exports ({@link generic:export-template-assets}).',
+ 'Avoid adding another library when Astryx or platform APIs already provide the behavior.',
+ ],
+ },
+ ],
+ },
+ {
+ id: 'export-one-component',
+ title: 'Export one component',
+ content: [
+ {
+ type: 'prose',
+ text: 'The source must default-export one React component. Named helpers inside the file are fine.',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'Add `use client` as the first statement only when hooks, event handlers, or browser APIs need a client boundary.',
+ 'Keep a static template server-compatible when it needs no client behavior.',
+ ],
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/assets/docs/tree/writing-docs.doc.mjs b/packages/cli/assets/docs/tree/writing-docs.doc.mjs
deleted file mode 100644
index e5c23a9d3a..0000000000
--- a/packages/cli/assets/docs/tree/writing-docs.doc.mjs
+++ /dev/null
@@ -1,286 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file `astryx docs cli/writing-docs`: the guide to writing docs that readers,
- * people and agents alike, find by search or by moving one level at a time.
- * It lives in the docs tree under the `cli` namespace, so its only route is
- * `cli/writing-docs`.
- */
-
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
- type: 'generic',
- name: 'writing-docs',
- placement: {parent: 'namespace:cli', slot: 'guides', order: 20},
- title: 'Writing docs',
- category: 'guide',
- description:
- 'Write docs that people and agents find by search or by reading one level at a time.',
-
- sections: [
- {
- title: 'How the docs work',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Every doc is one node in one docs graph, with a stable identity and one home in a tree.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- "Identity: the doc's provider, its kind, and its name. Moving a doc never changes it.",
- 'Route: the names of the doc and its parents, such as `cli/api/functions/search`; `astryx docs <route>` reads it.',
- 'Moves: every read ends with Up, Previous, Next, and Related, each as a command you can run.',
- 'Search: a hit is the smallest part that answers, one section or one tree page. It gives the command that reads it and the command that opens the level above.',
- ],
- },
- {
- type: 'prose',
- text: "You never write moves or lists of children. The CLI derives them from each doc's home and its typed links.",
- },
- ],
- },
- {
- title: 'Add a doc',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'To add a doc, write one `.doc.mjs` file named after the doc, and stamp the type that matches what it describes.',
- },
- {
- type: 'table',
- headers: ['You document', 'Doc type', '`type`'],
- rows: [
- ['A topic or a guide', 'ReferenceDoc', "'generic'"],
- ['A CLI command', 'CommandDoc', "'command'"],
- ['A CLI API function', 'FunctionDoc', "'function'"],
- ['An object shape', 'SchemaDoc', "'schema'"],
- ['A fixed list of values', 'EnumDoc', "'enum'"],
- ['A component', 'ComponentDoc', "'component'"],
- ['A level of the tree', 'NamespaceDoc', "'namespace'"],
- ],
- },
- {
- type: 'prose',
- text: 'A topic or guide holds `sections`. Each section has a `title` and `content` blocks, and covers one idea. The `description` is one sentence that says what the doc covers.',
- },
- {
- type: 'code',
- lang: 'javascript',
- label: 'docs/deploying.doc.mjs',
- code: "export default {\n type: 'generic',\n name: 'deploying',\n title: 'Deploying',\n description: 'Ship an app built with Acme widgets.',\n sections: [\n {\n title: 'Build before you ship',\n content: [\n {type: 'prose', text: 'Build the app, then check it with {@link @astryxdesign/cli:command:doctor}.'},\n {type: 'code', lang: 'bash', code: 'npm run build'},\n {type: 'list', style: 'unordered', items: ['Check the output folder.']},\n {type: 'table', headers: ['Env', 'Value'], rows: [['NODE_ENV', 'production']]},\n ],\n },\n ],\n};",
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'A name is a command argument, so use only letters, digits, `_`, and `-`. Use lowercase kebab-case, such as `writing-docs`, so the name and its route segment match.',
- 'Keep the name stable. Links name a doc by its identity, and the name is part of it.',
- 'A name that collides with an existing topic is an error unless the doc declares `replaces` or `extends`.',
- 'Name the cases a doc does not cover, and link to where they are covered. A reader cannot tell a case you left out from a case that does not exist.',
- ],
- },
- {
- type: 'prose',
- text: 'Every field of every doc type is in {@link generic:authoring}.',
- },
- ],
- },
- {
- title: 'Place a doc',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Each doc gets one home in one of three ways: a namespace adopts it, it places itself, or it stays a flat topic. Folders never decide a home.',
- },
- {
- type: 'prose',
- text: "Adopted: a CLI typed doc declares `namespace`, either `'cli/commands'` or `'cli/api'`. That namespace adopts it by kind, so its route is `cli/commands/<name>` or `cli/api/functions/<name>`.",
- },
- {
- type: 'code',
- lang: 'javascript',
- code: "{type: 'function', name: 'search', namespace: 'cli/api' /* ... */} // cli/api/functions/search",
- },
- {
- type: 'prose',
- text: "Placed: a guide declares `placement`. The `parent` names a namespace of your own package, the `slot` is one that namespace declares for the doc's kind, and `order` sorts the siblings in the slot. A placement that fails withdraws the doc with an error.",
- },
- {
- type: 'code',
- lang: 'javascript',
- code: "placement: {parent: 'namespace:cli', slot: 'guides', order: 20}, // cli/writing-docs",
- },
- {
- type: 'prose',
- text: 'Flat: a doc with neither is a flat topic, read with `astryx docs <name>`.',
- },
- {
- type: 'code',
- lang: 'javascript',
- code: "{type: 'generic', name: 'tokens', title: 'All Tokens' /* ... */} // astryx docs tokens",
- },
- ],
- },
- {
- title: 'Link docs',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Link a doc with `{@link <target>}` or a typed field, never by writing its `astryx docs` route in prose: a route you write goes stale when the doc moves. Other commands, such as `astryx doctor`, you write as they are.',
- },
- {
- type: 'prose',
- text: "Typed fields: a FunctionDoc's `command` names the CLI command that runs it, and its `related` names functions. A CommandDoc's `fn` names the function it runs, and its `related` names commands.",
- },
- {
- type: 'code',
- lang: 'javascript',
- code: "{type: 'function', name: 'search', command: 'search', related: ['docs']}\n{type: 'command', name: 'search', fn: 'search', related: ['docs']}",
- },
- {
- type: 'prose',
- text: "Inside a section's text, write `{@link <target>}`, where the target is `[<provider>:]<kind>:<name>`; leave out the provider for a doc of your own provider. The CLI prints the command that opens the doc. It works in prose, list items, and table cells; link syntax inside code ticks is shown as written, and an older CLI prints the link as plain text. A namespace doc can also carry `reference` and `workflow` blocks in its `blocks`, though the CLI does not print them yet; a topic's sections cannot hold them.",
- },
- {
- type: 'code',
- lang: 'javascript',
- code: "{type: 'prose', text: 'Check it with {@link command:doctor}.'}\n{type: 'list', style: 'unordered', items: ['Search with {@link @astryxdesign/cli:function:search}.']}\n\n// In a namespace doc's blocks only:\n{type: 'workflow', steps: [\n {title: 'Write the doc', references: ['generic:authoring']},\n {title: 'Check it', references: ['command:doctor']},\n]}",
- },
- {
- type: 'prose',
- text: "The route in the printed command is derived when the doc is read, so a link follows its doc when the doc moves. A target that names no doc prints as written, and so does a typed-field name that matches more than one doc; `astryx doctor` warns on both.",
- },
- ],
- },
- {
- title: 'Keep reads short',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Keep every read short so a reader gets one answer per command: one idea per section, a summary first, and a hard size limit.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- 'Give each section one idea. If it needs a second topic, split it into two sections.',
- "A section's summary, shown in the section list and in search, is its first prose block or first list item, cut at 240 characters. Lead with what the section answers.",
- 'In text, a topic with more than one section reads as its section list. The reader opens one section, or prints everything with `--full`. With `--json`, a topic returns the whole doc and `--index` its section list.',
- 'Every read should fit in 32 KB; `astryx doctor` warns on one that does not. Aim for sections under about 30 lines.',
- ],
- },
- {
- type: 'code',
- lang: 'bash',
- code: 'astryx docs cli/writing-docs\nastryx docs cli/writing-docs keep-reads-short\nastryx docs cli/writing-docs --full',
- },
- ],
- },
- {
- title: 'Make docs findable',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Search finds a doc only by the words it indexes, so put the words a reader types where search looks.',
- },
- {
- type: 'prose',
- text: "Search matches titles, section titles, headings, each section's summary, and identifiers written in code ticks, such as `ERR_UNKNOWN_SECTION` or `token-ref`. It also matches a doc's own name and the `keywords` of a namespace or typed doc.",
- },
- {
- type: 'list',
- style: 'do',
- items: [
- 'Title a section with the task or question, such as "Place a doc".',
- 'Start each section with a sentence that names its subject and answers it.',
- 'Write exact identifiers in code ticks: field names, block types, and error codes.',
- 'Add `keywords` only for words that are not already in the title or summary.',
- ],
- },
- {
- type: 'list',
- style: 'dont',
- items: [
- 'Open a section with background. Its first block is its summary.',
- 'Use vague titles such as "Overview" or "Details" when a specific one fits.',
- ],
- },
- {
- type: 'prose',
- text: 'Test it the way a new reader arrives: search for the question, not the title, and check that the first hit answers it.',
- },
- {
- type: 'code',
- lang: 'bash',
- code: 'astryx search placement --type doc',
- },
- ],
- },
- {
- title: 'Docs from an integration',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'An integration joins the same graph with a namespace doc in its docs directory and guides placed in it. The namespace shows in `astryx docs` beside `cli`, with the same moves, search, and links. You can place a doc only in a namespace of your own package.',
- },
- {
- type: 'prose',
- text: 'Let the CLI write the files: inside the package, `astryx integration add doc deploying --parent acme` writes the guide with its placement, declares the docs root, and writes the `acme` namespace doc the first time. Run `astryx docs` in the package to see it.',
- },
- {
- type: 'prose',
- text: "A CLI release that does not read the docs tree can hide every doc topic your package ships when the package contains a namespace doc or a placed guide: none appear in `astryx docs`, in text or JSON, and `astryx doctor` may not say why. So `--parent` also declares the CLI release your docs need as an optional `@astryxdesign/cli` peer in package.json, which makes npm warn when an older CLI is installed, and `astryx integration pack --check` fails a package that ships either one without it.",
- },
- {
- type: 'code',
- lang: 'javascript',
- code: "// docs/acme.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */\nexport default {\n type: 'namespace', name: 'acme', title: 'Acme widgets',\n summary: 'Guides for building apps with Acme widgets.',\n slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},\n};\n\n// docs/deploying.doc.mjs (route: acme/deploying)\n/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n type: 'generic', name: 'deploying', title: 'Deploying',\n description: 'Ship an app built with Acme widgets.',\n placement: {parent: 'namespace:acme', slot: 'guides', order: 10},\n sections: [{title: 'Check before you ship', content: [\n {type: 'prose', text: 'Run {@link @astryxdesign/cli:command:doctor} before every deploy.'},\n ]}],\n};",
- },
- {
- type: 'prose',
- text: "The link names the `@astryxdesign/cli` provider because its target lives in another package. A link without a provider resolves against yours: your manifest's `providerId`, or else your package name. That holds in a topic that `extends` another package's topic too: your sections link your docs, and a link to the other package's docs names its provider.",
- },
- {
- type: 'prose',
- text: 'Everything else an integration ships is in {@link generic:integrations}.',
- },
- ],
- },
- {
- title: 'Check your docs',
- category: 'guide',
- content: [
- {
- type: 'prose',
- text: 'Run the doctor commands to check every home, link, and read in your docs.',
- },
- {
- type: 'list',
- style: 'unordered',
- items: [
- '`astryx doctor`, in a project, checks the whole graph: the tree, the links, and the size of each read.',
- '`astryx doctor integration docs`, inside an integration package, runs the same checks on that package\'s docs before it ships.',
- '`astryx integration pack --check` fails a package that ships a namespace doc or a placed guide without a CLI peer that reads them.',
- ],
- },
- {
- type: 'prose',
- text: 'No check can tell whether a doc is still true. Describe what the CLI does now, and change the doc in the same change that changes the behavior.',
- },
- {
- type: 'prose',
- text: 'A problem in the tree or a link is a warning: it names what to fix, but the exit code stays 0, so read the report (or its `--json`) before you ship.',
- },
- ],
- },
- ],
-};
diff --git a/packages/cli/assets/docs/typography.doc.mjs b/packages/cli/assets/docs/typography.doc.mjs
index abdf771096..66c7b1d6c5 100644
--- a/packages/cli/assets/docs/typography.doc.mjs
+++ b/packages/cli/assets/docs/typography.doc.mjs
@@ -8,6 +8,7 @@ export const docs = {
category: 'foundations',
description:
'Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.',
+ keywords: ['font', 'fonts', 'font size'],
tokenCategory: 'typography',
sections: [
@@ -44,9 +45,10 @@ export const docs = {
],
},
- // ── Loading Custom Fonts ────────────────────────────────────────────────
+ // ── Custom Fonts ────────────────────────────────────────────────────────
{
- title: 'Loading Custom Fonts',
+ id: 'loading-custom-fonts',
+ title: 'Custom fonts',
category: 'foundations',
content: [
{
@@ -165,11 +167,16 @@ export const docs = {
],
},
- // ── Usage ────────────────────────────────────────────────────────────────
+ // ── Headings and text ───────────────────────────────────────────────────
{
- title: 'Usage',
+ id: 'usage',
+ title: 'Headings and text',
category: 'foundations',
content: [
+ {
+ type: 'prose',
+ text: 'Use `Heading` for document structure and `Text` for everything else; each maps its props to the type scale tokens.',
+ },
{
type: 'code',
lang: 'tsx',
@@ -205,6 +212,19 @@ export const docs = {
// Display without heading semantics (data callouts, decorative)
<Text type="display-2">$1.2M Revenue</Text>`,
},
+ ],
+ },
+
+ // ── Custom type scale ───────────────────────────────────────────────────
+ {
+ id: 'custom-type-scale',
+ title: 'Custom type scale',
+ category: 'foundations',
+ content: [
+ {
+ type: 'prose',
+ text: 'Change the whole ramp with `base` and `ratio` in `defineTheme`; every font size and line height recomputes from them.',
+ },
{
type: 'code',
lang: 'tsx',
diff --git a/packages/cli/assets/docs/working-with-ai.doc.mjs b/packages/cli/assets/docs/working-with-ai.doc.mjs
index 581a0e202c..4b325a2893 100644
--- a/packages/cli/assets/docs/working-with-ai.doc.mjs
+++ b/packages/cli/assets/docs/working-with-ai.doc.mjs
@@ -8,6 +8,7 @@ export const docs = {
category: 'guide',
description:
'How to set up AI coding tools to generate correct component code.',
+ keywords: ['claude', 'cursor', 'codex', 'copilot', 'agents', 'mcp'],
sections: [
{
@@ -24,7 +25,8 @@ export const docs = {
],
},
{
- title: 'Quick Start',
+ id: 'quick-start',
+ title: 'Set up agent docs',
content: [
{
type: 'prose',
@@ -38,7 +40,7 @@ export const docs = {
},
{
type: 'prose',
- text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade` reports a stale block and `astryx upgrade --apply` refreshes it.",
+ text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade --from <old version>` reports a stale block and adding `--apply` refreshes it.",
},
{
type: 'prose',
@@ -48,10 +50,12 @@ export const docs = {
type: 'code',
lang: 'bash',
label: 'Manual options',
- code: `npx @astryxdesign/cli init --features agents --agent claude # .claude/CLAUDE.md
-npx @astryxdesign/cli init --features agents --agent cursor # .cursorrules
+ code: `npx @astryxdesign/cli init --features agents --agent claude # CLAUDE.md if present, else .claude/CLAUDE.md
+npx @astryxdesign/cli init --features agents --agent cursor # .cursorrules if present, else AGENTS.md
npx @astryxdesign/cli init --features agents --agent codex # AGENTS.md (Copilot, Codex, etc.)
-npx @astryxdesign/cli init --features agents --agent muse # AGENTS.md (Muse)`,
+npx @astryxdesign/cli init --features agents --agent hermes # .hermes.md or HERMES.md if present, else AGENTS.md
+npx @astryxdesign/cli init --features agents --agent muse # AGENTS.md (Muse)
+npx @astryxdesign/cli init --features agents --agent all # every agent file present, else AGENTS.md and .claude/CLAUDE.md`,
},
],
},
@@ -82,14 +86,17 @@ npx @astryxdesign/cli init --features agents --agent muse # AGENTS.md (Muse
content: [
{
type: 'prose',
- text: 'Cursor project rules aren\'t always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
+ text: 'Cursor reads project rules from `.cursor/rules/`. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as `.cursor/rules/astryx.mdc`; an absolute path is refused.',
},
{
type: 'code',
lang: 'bash',
- label: 'Install as a Cursor user rule',
- code: `mkdir -p ~/.cursor/rules
-npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+ label: 'Install as a Cursor project rule',
+ code: `npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc`,
+ },
+ {
+ type: 'prose',
+ text: 'Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as `alwaysApply: true`) stays.',
},
],
},
@@ -98,7 +105,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
content: [
{
type: 'prose',
- text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
+ text: 'Paste this into your AI before writing any component code. If your AI can\'t answer these questions, it\'ll know to install the agent docs first.',
},
{
type: 'code',
@@ -107,7 +114,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
code: `Before writing any Astryx code, check your knowledge:
1. What is the correct import path for Button?
-2. How do you make an Dialog non-dismissible?
+2. How do you make a Dialog non-dismissible?
3. What prop does Selector use for its items?
If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
@@ -131,33 +138,34 @@ If you don't know all three, run \`npx @astryxdesign/cli init --features agents\
},
{
type: 'prose',
- text: 'With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+ text: 'With this alias, agents run `npm run astryx -- component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
},
{
type: 'code',
lang: 'bash',
label: 'Reliable CLI invocation',
- code: `astryx component --list
-astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+ code: `npm run astryx -- component --list
+npm run astryx -- component Dialog --dense
+npm run astryx -- docs styling --full --detail brief
+npm run astryx -- docs tokens --dense`,
},
],
},
{
- title: 'The --dense Flag',
+ id: 'the-dense-flag',
+ title: 'Shorter output: --detail and --dense',
content: [
{
type: 'prose',
- text: 'Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
+ text: 'For a shorter read, add `--detail brief` (one line per section) or `--detail compact`. `--dense` swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
},
{
type: 'code',
lang: 'bash',
- label: 'Dense output for pasting into AI conversations',
- code: `astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+ label: 'Short output for pasting into AI conversations',
+ code: `astryx docs styling --full --detail brief
+astryx component Dialog --detail compact
+astryx docs principles --dense`,
},
],
},
diff --git a/packages/cli/authoring/config/config.doc.mjs b/packages/cli/authoring/config/config.doc.mjs
index a4a4a5dc63..1e916034bb 100644
--- a/packages/cli/authoring/config/config.doc.mjs
+++ b/packages/cli/authoring/config/config.doc.mjs
@@ -10,7 +10,7 @@
export const doc = {
type: 'schema',
name: 'config',
- displayName: 'Astryx Config',
+ displayName: 'astryx.config',
namespace: 'authoring',
description:
'The optional astryx.config.* file at your project root. Declares which ' +
diff --git a/packages/cli/authoring/doctypes/_schema.mjs b/packages/cli/authoring/doctypes/_schema.mjs
index f1609b2c25..809dadd7e1 100644
--- a/packages/cli/authoring/doctypes/_schema.mjs
+++ b/packages/cli/authoring/doctypes/_schema.mjs
@@ -307,6 +307,7 @@ const ComponentBaseSchema = z
theming: z.unknown().optional(),
playground: z.unknown().optional(),
examples: z.array(z.unknown()).optional(),
+ replaces: z.string().min(1).optional(),
})
.passthrough();
@@ -414,6 +415,9 @@ export const GenericDocKindSchema = z
...BaseDocFields,
type: z.literal('generic'),
title: nonEmptyString.optional(),
+ // Search terms the title and sections do not use; `astryx search` matches
+ // them as keywords of the whole topic (ReferenceDoc `keywords`).
+ keywords: z.array(z.string()).optional(),
sections: z.array(ReferenceSectionSchema).min(1).optional(),
replaces: nonEmptyString.optional(),
extends: nonEmptyString.optional(),
@@ -730,6 +734,8 @@ const LegacyBaseDocSchema = z.object({
const LegacyReferenceDocSchema = LegacyBaseDocSchema.extend({
title: nonEmptyString,
description: z.string(),
+ // As on the stamped schema: search terms for the whole topic.
+ keywords: z.array(z.string()).optional(),
sections: z.array(ReferenceSectionSchema).min(1),
replaces: nonEmptyString.optional(),
extends: nonEmptyString.optional(),
diff --git a/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs b/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
index f7cbf74017..c86df4da41 100644
--- a/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
+++ b/packages/cli/authoring/doctypes/base/graph-fields.doc.mjs
@@ -12,7 +12,7 @@ export const doc = {
displayName: 'Authored doc graph fields',
namespace: 'authoring',
description:
- "Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs tree. The docs tree reads `placement` for every guide, the CLI's and each integration's; aliases and audience are not built yet. A reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
+ "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
appliesTo: 'Every supported .doc.mjs object',
fields: [
{
@@ -45,13 +45,13 @@ export const doc = {
name: 'aliases',
type: 'string[]',
description:
- 'Prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
+ 'Reserved: prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Nothing reads it today, and a topic that sets it fails to load.',
},
{
name: 'audience',
type: "'public' | 'internal'",
description:
- "Which docs bundle includes this doc ('public' when omitted). Not read yet: a topic that sets it fails to load.",
+ "Reserved: which docs bundle includes this doc ('public' when omitted). Nothing reads it today, and a topic that sets it fails to load.",
default: "'public'",
},
],
diff --git a/packages/cli/authoring/doctypes/base/type.ts b/packages/cli/authoring/doctypes/base/type.ts
index eadd266529..c57b53f190 100644
--- a/packages/cli/authoring/doctypes/base/type.ts
+++ b/packages/cli/authoring/doctypes/base/type.ts
@@ -39,9 +39,11 @@ export interface DocPlacement {
export interface AuthoredDocGraphFields {
/** The doc's one parent in the docs tree: a namespace of its own package. */
placement?: DocPlacement;
- /** Prior routes or names the docs tree will keep resolving. Not read yet. */
+ /** Reserved: prior routes or names the docs tree will keep resolving.
+ * Nothing reads it yet. */
aliases?: string[];
- /** Docs bundle audience; omit for public docs. Not read yet. */
+ /** Reserved: docs bundle audience; omit for public docs. Nothing reads it
+ * yet. */
audience?: DocAudience;
}
diff --git a/packages/cli/authoring/doctypes/component/component.doc.mjs b/packages/cli/authoring/doctypes/component/component.doc.mjs
index ea09fb74c0..472113bb46 100644
--- a/packages/cli/authoring/doctypes/component/component.doc.mjs
+++ b/packages/cli/authoring/doctypes/component/component.doc.mjs
@@ -52,6 +52,12 @@ export const doc = {
description:
'Exact public package specifier consumers use to import an integration-owned component. The packed-package gate resolves this specifier and verifies it exports the component name.',
},
+ {
+ name: 'replaces',
+ type: 'string',
+ description:
+ "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, lists, search, swizzle, and issue routing. The Core original stays reachable with `--package @astryxdesign/core`. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+ },
{
name: 'keywords',
type: 'string[]',
diff --git a/packages/cli/authoring/doctypes/component/type.ts b/packages/cli/authoring/doctypes/component/type.ts
index 0957e38e1c..7ce8fd9831 100644
--- a/packages/cli/authoring/doctypes/component/type.ts
+++ b/packages/cli/authoring/doctypes/component/type.ts
@@ -48,6 +48,14 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
displayName: string;
/** Exact consumer import specifier for integration-owned components. */
import?: string;
+ /** Integration components only: the exact `name` of the Core ComponentDoc
+ * this component takes over for unqualified lookup, so every app that loads
+ * the integration gets this component from component detail, lists, search,
+ * swizzle, and issue routing. The Core original stays reachable with
+ * `--package @astryxdesign/core`. Set it only to intentionally own a Core
+ * identity; give an alternative or variant its own name instead. Older CLIs
+ * that do not read `replaces` keep the component under its own name. */
+ replaces?: string;
/** Search keywords for CLI discovery. Terms a developer might type when
* looking for this component: synonyms, related UI concepts, and common
* names from other design systems (MUI, Chakra, Radix, and others).
diff --git a/packages/cli/authoring/doctypes/reference/reference.doc.mjs b/packages/cli/authoring/doctypes/reference/reference.doc.mjs
index 6ad029dd7b..8ca2852f86 100644
--- a/packages/cli/authoring/doctypes/reference/reference.doc.mjs
+++ b/packages/cli/authoring/doctypes/reference/reference.doc.mjs
@@ -51,6 +51,13 @@ export const doc = {
type: 'string',
description: "Navigation category: 'guide' or 'foundations'.",
},
+ {
+ name: 'keywords',
+ type: 'string[]',
+ description:
+ "Words a reader may search for that the title and sections do not use: a synonym, a task, or another library's name for the same thing. `astryx search` matches each as a keyword of the whole topic, so an exact one ranks the topic like its own title does.",
+ example: "['dark mode', 'color scheme']",
+ },
{
name: 'replaces',
type: 'string',
diff --git a/packages/cli/authoring/doctypes/reference/type.ts b/packages/cli/authoring/doctypes/reference/type.ts
index e03ffab219..f1a064af37 100644
--- a/packages/cli/authoring/doctypes/reference/type.ts
+++ b/packages/cli/authoring/doctypes/reference/type.ts
@@ -127,6 +127,11 @@ export interface ReferenceDoc extends AuthoredDocGraphFields {
description: string;
/** Navigation category: 'guide' or 'foundations'. */
category?: string;
+ /** Words a reader may search for that the title and sections do not use:
+ * a synonym, a task ("dark mode"), or another library's name for the same
+ * thing. `astryx search` matches each as a keyword of the whole topic, so
+ * an exact one ranks the topic like its own title does. */
+ keywords?: string[];
/** Name of an existing topic this doc takes the place of. Authored by an
* integration whose guide should be served instead of the built-in one —
* `replaces: 'getting-started'` on a doc named `getting-started` swaps the
diff --git a/packages/cli/authoring/doctypes/schema/schema.doc.mjs b/packages/cli/authoring/doctypes/schema/schema.doc.mjs
index e6d643597f..85171865ec 100644
--- a/packages/cli/authoring/doctypes/schema/schema.doc.mjs
+++ b/packages/cli/authoring/doctypes/schema/schema.doc.mjs
@@ -49,7 +49,7 @@ export const doc = {
name: 'namespace',
type: 'string',
description:
- "The group that reads this doc: 'authoring' for a file an author writes (a section of `astryx docs authoring`), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+ "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
},
{
name: 'aliases',
@@ -162,7 +162,7 @@ export const doc = {
type: '{ dir: string }',
description: 'Where component sources live.',
fields: [
- {name: 'components.dir', type: 'string', description: 'Glob root for XDS*.tsx files.', required: true},
+ {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
],
},
],
diff --git a/packages/cli/authoring/doctypes/template/template.doc.mjs b/packages/cli/authoring/doctypes/template/template.doc.mjs
index 8c44f1b9b7..e679e1831f 100644
--- a/packages/cli/authoring/doctypes/template/template.doc.mjs
+++ b/packages/cli/authoring/doctypes/template/template.doc.mjs
@@ -56,7 +56,7 @@ export const doc = {
name: 'replaces',
type: 'string',
description:
- "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field and withhold the package's templates and doc topics.",
+ "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field, drop that template, and hide the package's doc topics.",
},
{
name: 'isReady',
diff --git a/packages/cli/authoring/doctypes/template/type.ts b/packages/cli/authoring/doctypes/template/type.ts
index c3b0936d67..1b2723d3f6 100644
--- a/packages/cli/authoring/doctypes/template/type.ts
+++ b/packages/cli/authoring/doctypes/template/type.ts
@@ -33,8 +33,8 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
* replaces for unqualified lookup (find it with
* `astryx --json template --list --package @astryxdesign/core`). The Core
* original stays selectable with `--package @astryxdesign/core`. Needs
- * `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field and
- * withhold the package's templates and doc topics. */
+ * `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field,
+ * drop that template, and hide the package's doc topics. */
replaces?: string;
/** Whether this template is ready for use. Templates with
* isReady: false show as "(WIP)" in the gallery and CLI. */
diff --git a/packages/cli/authoring/integration/integration.doc.mjs b/packages/cli/authoring/integration/integration.doc.mjs
index c6c8e5845a..6ee5d9ad32 100644
--- a/packages/cli/authoring/integration/integration.doc.mjs
+++ b/packages/cli/authoring/integration/integration.doc.mjs
@@ -23,48 +23,49 @@ export const doc = {
name: 'providerId',
type: 'string',
description:
- 'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
+ 'The name that marks this package as the source of everything it contributes. Leave it out to use the package name from package.json. Set it to the old name only during a rename, so the IDs of what the package already contributed stay the same. If two packages use the same name here, the one you are working on wins; otherwise the one the CLI reads first wins, and the CLI warns about the other.',
example: "'@acme/widgets'",
},
{
name: 'components',
type: 'string',
description:
- 'Relative path to the components/docs root (resolved to absolute).',
+ 'The folder that holds your components and their docs, relative to package.json.',
example: "'./src/components'",
},
{
name: 'templates',
type: 'string',
description:
- 'Relative path to the templates root (resolved to absolute).',
+ 'The folder that holds your templates, relative to package.json.',
example: "'./src/templates'",
},
{
name: 'codemods',
type: 'string',
- description: 'Relative path to the codemods root (resolved to absolute).',
+ description:
+ 'The folder that holds your codemods, relative to package.json.',
example: "'./codemods'",
},
{
name: 'docs',
type: 'string',
description:
- 'Relative path to the reference-docs (topics) root (resolved to absolute). Every {topic}.doc.{ts,mjs,js} under it is served by `astryx docs` beside the built-in topics; a topic may also declare `replaces` or `extends` to take the place of a built-in one or merge onto it.',
+ 'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
example: "'./docs'",
},
{
name: 'themes',
type: 'string',
description:
- 'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
+ 'The folder that holds your themes, relative to package.json, with one folder per theme. Each theme folder has the theme source and a matching .doc.mjs file with the same name. Installed themes show up in `astryx theme list` and can be copied with `astryx theme add`.',
example: "'./themes'",
},
{
name: 'agentDocs',
type: '{ append?: readonly string[] }',
description:
- 'Static package guidance appended to the end of the managed agent block. The CLI owns the section heading, package labels, bullets, target files, and writes.',
+ 'Lines of guidance your package adds to the end of the agent instructions the CLI manages. The CLI owns the heading, labels, bullets, and which files it writes.',
example: "{ append: ['Run acme verify.'] }",
},
{
@@ -94,9 +95,10 @@ export const doc = {
{
type: 'prose',
text:
- 'Provider identity defaults to package.json#name. During an explicit ' +
- 'package rename, set `providerId` to the prior canonical package name so ' +
- 'existing artifact IDs remain stable. Package version always comes from package.json.',
+ 'The provider name defaults to the package name in package.json. ' +
+ 'During a rename, set `providerId` to the old package name so the IDs ' +
+ 'of what the package already contributed stay the same. The package ' +
+ 'version always comes from package.json.',
},
{
type: 'prose',
diff --git a/packages/cli/clients/cli/commands/component.doc.mjs b/packages/cli/clients/cli/commands/component.doc.mjs
index 59f8b15b09..2352004877 100644
--- a/packages/cli/clients/cli/commands/component.doc.mjs
+++ b/packages/cli/clients/cli/commands/component.doc.mjs
@@ -37,12 +37,13 @@ export const doc = {
{
flag: '--list',
param: 'options.list',
- description: 'List all components grouped by category',
+ description: 'List every component (the same as giving no name)',
},
{
flag: '--category <category>',
param: 'options.category',
- description: 'List components in a specific category',
+ description:
+ 'List one component group, e.g. --category Layout or --category Avatar (an unknown group lists the valid ones)',
},
{
flag: '--props',
@@ -79,7 +80,7 @@ export const doc = {
},
{
label: 'Props table as JSON',
- cli: 'astryx component XDSButton --props --json',
+ cli: 'astryx component Button --props --json',
},
],
exitCodes: [
diff --git a/packages/cli/clients/cli/commands/docs.doc.mjs b/packages/cli/clients/cli/commands/docs.doc.mjs
index c1a592f693..dedb18f245 100644
--- a/packages/cli/clients/cli/commands/docs.doc.mjs
+++ b/packages/cli/clients/cli/commands/docs.doc.mjs
@@ -47,7 +47,7 @@ export const doc = {
{label: 'One section', cli: 'astryx docs theme quick-start'},
{label: 'The CLI docs tree', cli: 'astryx docs cli'},
{label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
- {label: 'A whole guide', cli: 'astryx docs cli/integrations --full'},
+ {label: 'A whole guide', cli: 'astryx docs cli/integrations/quick-start --full'},
],
exitCodes: [
{code: 0, when: 'success'},
diff --git a/packages/cli/clients/cli/commands/docs.mjs b/packages/cli/clients/cli/commands/docs.mjs
index a2901c3658..b719855de0 100644
--- a/packages/cli/clients/cli/commands/docs.mjs
+++ b/packages/cli/clients/cli/commands/docs.mjs
@@ -7,7 +7,8 @@
* open one section by its key, and `--full` prints the whole topic. `--json`
* keeps the docs() contract: a topic returns its whole doc, and `--index` its
* sections.
- * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
+ * Supports --detail (full|compact|brief) and --lang (en|zh|dense). A code
+ * block's label prints above its fence, and table cells escape their pipes.
*
* Usage:
* astryx docs List available topics
@@ -42,21 +43,35 @@ import {doc as docsFn} from '../../../api/docs/docs.doc.mjs';
// ─── Formatting ──────────────────────────────────────────────────────────────
+/**
+ * A table cell with its pipes escaped. Columns are separated by ` | `, and a
+ * union type such as `'light' | 'dark'` is spelled with the same character,
+ * so an unescaped cell reads as extra columns. `astryx component` escapes its
+ * prop tables the same way.
+ * @param {string | undefined} cell
+ * @returns {string}
+ */
+function tableCell(cell) {
+ return (cell || '').replaceAll('|', '\\|');
+}
+
/**
* @param {string[]} headers
* @param {string[][]} rows
* @returns {string}
*/
function formatTable(headers, rows) {
- const widths = headers.map((h, i) =>
- Math.max(h.length, ...rows.map(r => (r[i] || '').length)),
+ const head = headers.map(tableCell);
+ const cells = rows.map(r => r.map(tableCell));
+ const widths = head.map((h, i) =>
+ Math.max(h.length, ...cells.map(r => (r[i] || '').length)),
);
const sep = widths.map(w => '-'.repeat(w)).join(' | ');
- const head = headers.map((h, i) => h.padEnd(widths[i])).join(' | ');
- const body = rows
- .map(r => r.map((c, i) => (c || '').padEnd(widths[i])).join(' | '))
+ const top = head.map((h, i) => h.padEnd(widths[i])).join(' | ');
+ const body = cells
+ .map(r => r.map((c, i) => c.padEnd(widths[i])).join(' | '))
.join('\n');
- return `${head}\n${sep}\n${body}`;
+ return `${top}\n${sep}\n${body}`;
}
/**
@@ -65,15 +80,19 @@ function formatTable(headers, rows) {
* @returns {string}
*/
function formatTableCompact(headers, rows) {
- return rows.map(r => r.join(' = ')).join('\n');
+ // An empty cell, such as a Default with none, adds nothing to the line.
+ return rows
+ .map(r => r.filter(cell => String(cell ?? '').trim() !== '').join(' = '))
+ .join('\n');
}
/**
+ * One content block as text. Exported for its tests.
* @param {import('@astryxdesign/cli/authoring').ReferenceContentBlock} block
* @param {'full' | 'compact' | 'brief'} detail
* @returns {string | null}
*/
-function formatBlock(block, detail) {
+export function formatBlock(block, detail) {
switch (block.type) {
case 'prose':
return block.text;
@@ -84,13 +103,20 @@ function formatBlock(block, detail) {
case 'code':
if (detail === 'compact' || detail === 'brief') return null;
{
- const label = block.label ? `// ${block.label}\n` : '';
- return `\`\`\`${block.lang}\n${label}${block.code}\n\`\`\``;
+ // The label names the block, so it prints above the fence, not
+ // inside it: `// label` is not a comment in bash, CSS, JSON, or
+ // HTML, and a reader who copies the block would copy it too.
+ const label = block.label
+ ? `${block.label.replace(/:\s*$/, '')}:\n`
+ : '';
+ return `${label}\`\`\`${block.lang}\n${block.code}\n\`\`\``;
}
case 'table':
if (detail === 'brief') {
- return block.rows.map(r => r.slice(0, 2).join('=')).join(' | ');
+ return block.rows
+ .map(r => r.slice(0, 2).map(tableCell).join('='))
+ .join(' | ');
}
if (detail === 'compact') {
return formatTableCompact(block.headers, block.rows);
@@ -202,16 +228,23 @@ function emitIndex(index, run) {
}
/**
- * One child row of a namespace: its route name, then the doc's own title when
- * it is not the route name (`assertResponse()`, `search()`), then its summary.
+ * One child row of a namespace. Namespace and guide route names are already
+ * readable, so repeating their titles adds noise (`start-a-template Start a
+ * template`). Typed docs keep a distinct title when it carries the real symbol
+ * name (`assert-response assertResponse()`).
* @param {import('../../../api/docs/docs.type.mjs').DocsNodeChild} child
* @returns {{name: string, summary: string}}
*/
function childRow(child) {
+ const titleAddsIdentity =
+ child.kind !== 'namespace' &&
+ child.kind !== 'generic' &&
+ child.title !== child.name;
return {
name: child.name,
- summary:
- child.title === child.name ? child.summary : `${child.title}: ${child.summary}`,
+ summary: titleAddsIdentity
+ ? `${child.title}: ${child.summary}`
+ : child.summary,
};
}
@@ -227,6 +260,17 @@ function emitNode(node, detail, run) {
if (node.kind === 'namespace') {
emit(
section(node.title, wrapText(node.summary)),
+ // A namespace may author intro `blocks`; they render above its children.
+ ...(node.content?.length
+ ? [
+ text(
+ node.content
+ .map(b => formatBlock(b, detail))
+ .filter(Boolean)
+ .join('\n\n'),
+ ),
+ ]
+ : []),
...node.slots.flatMap(slot => [
// A namespace with one slot titled like itself needs no second heading.
...(node.slots.length === 1 && slot.title === node.title
@@ -235,7 +279,6 @@ function emitNode(node, detail, run) {
records(slot.children.map(childRow), {
fields: ['name', 'summary'],
layout: 'inline',
- overflow: 'truncate',
}),
]),
text(
diff --git a/packages/cli/clients/cli/commands/docs.test.mjs b/packages/cli/clients/cli/commands/docs.test.mjs
deleted file mode 100644
index f350598bbd..0000000000
--- a/packages/cli/clients/cli/commands/docs.test.mjs
+++ /dev/null
@@ -1,323 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import {Command} from 'commander';
-import {registerDocs} from './docs.mjs';
-import {runCli} from '../../../test-utils/run-cli.mjs';
-import {displayWidth} from '../formatters/index.mjs';
-
-let tmpDir;
-
-beforeEach(() => {
- tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-docs-test-'));
- vi.spyOn(console, 'log').mockImplementation(() => {});
- vi.spyOn(console, 'error').mockImplementation(() => {});
-});
-
-afterEach(() => {
- fs.rmSync(tmpDir, {recursive: true, force: true});
- vi.restoreAllMocks();
-});
-
-function createProgram() {
- const program = new Command();
- program.exitOverride(); // Throw instead of calling process.exit
- registerDocs(program);
- return program;
-}
-
-describe('registerDocs', () => {
- it('lists available topics when no topic given', async () => {
- const program = createProgram();
- await program.parseAsync(['node', 'astryx', 'docs']);
-
- const output = console.log.mock.calls.map(c => c[0]).join('\n');
- expect(output).toContain('principles');
- expect(output).toContain('tokens');
- expect(output).not.toContain('shadcn-compatibility');
- });
-
- it('errors for unknown topic', async () => {
- const program = createProgram();
- vi.spyOn(process, 'exit').mockImplementation(code => {
- throw new Error(`exit ${code}`);
- });
-
- await expect(
- program.parseAsync(['node', 'astryx', 'docs', 'nonexistent']),
- ).rejects.toThrow('exit 1');
-
- const errorOutput = console.error.mock.calls.map(c => c[0]).join('\n');
- expect(errorOutput).toContain('Unknown topic');
- });
-});
-
-describe('hyphenated doc filenames', () => {
- it('lists hyphenated topics like getting-started', async () => {
- const program = createProgram();
- await program.parseAsync(['node', 'astryx', 'docs']);
-
- const output = console.log.mock.calls.map(c => c[0]).join('\n');
- expect(output).toContain('getting-started');
- });
-
- it('loads a hyphenated topic by name', async () => {
- const program = createProgram();
- await program.parseAsync(['node', 'astryx', 'docs', 'getting-started']);
-
- const output = console.log.mock.calls.map(c => c[0]).join('\n');
- expect(output.length).toBeGreaterThan(0);
- expect(console.error).not.toHaveBeenCalled();
- });
-
- it('returns docs.detail via API for hyphenated topic', async () => {
- const {docs: docsApi} = await import('../../../api/docs/docs.mjs');
- const result = await docsApi('getting-started', undefined, {full: true});
- expect(result.type).toBe('docs.detail');
- expect(result.data).toBeDefined();
- expect(result.data.description).toBeDefined();
- });
-});
-
-describe('migration docs', () => {
- it('lists the migration topic', async () => {
- const program = createProgram();
- await program.parseAsync(['node', 'astryx', 'docs']);
-
- const output = console.log.mock.calls.map(c => c[0]).join('\n');
- expect(output).toContain('migration');
- expect(output).toContain('Tailwind');
- });
-
- it('loads migration docs by topic name', async () => {
- const program = createProgram();
- await program.parseAsync(['node', 'astryx', 'docs', 'migration']);
-
- const output = console.log.mock.calls.map(c => c[0]).join('\n');
- expect(output).toContain('Migration Guide');
- expect(output).toContain('Recommended Order');
- expect(output).toContain('Map shadcn and Radix Primitives');
- });
-});
-
-describe('progressive reads', () => {
- const SLOW = 60_000;
- /** @param {string} out */
- const widest = out => Math.max(...out.split('\n').map(line => line.length));
-
- it('lists every topic on one line each', async () => {
- const {status, stdout} = await runCli(['docs']);
- expect(status).toBe(0);
- expect(stdout).toMatch(/^principles +\S/m);
- expect(widest(stdout)).toBeLessThanOrEqual(120);
- expect(stdout).toContain('Usage: pnpm exec astryx docs <topic>');
- }, SLOW);
-
- it("prints a topic's section index with the keys to read by", async () => {
- const {status, stdout} = await runCli(['docs', 'theme', '--index']);
- expect(status).toBe(0);
- expect(stdout).toMatch(/^quick-start +Quick Start/m);
- expect(stdout).toContain('docs theme <section>');
- expect(stdout).toMatch(/Read everything: +\S.* docs theme --full$/m);
- expect(widest(stdout)).toBeLessThanOrEqual(120);
- }, SLOW);
-
- it('prints one section by its key', async () => {
- const {status, stdout} = await runCli(['docs', 'theme', 'quick-start']);
- expect(status).toBe(0);
- expect(stdout).toMatch(/^## Quick Start/m);
- }, SLOW);
-
- it("lists a topic's sections by default; --full prints the whole topic", async () => {
- const index = await runCli(['docs', 'theme', '--index']);
- expect((await runCli(['docs', 'theme'])).stdout).toBe(index.stdout);
- const full = await runCli(['docs', 'theme', '--full']);
- expect(full.status).toBe(0);
- expect(full.stdout).toMatch(/^## Quick Start/m);
- expect(full.stdout.length).toBeGreaterThan(index.stdout.length * 3);
- expect((await runCli(['--detail', 'full', 'docs', 'theme', '--full'])).stdout).toBe(
- full.stdout,
- );
- }, SLOW);
-
- it('returns the matching envelopes as JSON', async () => {
- const envelope = async args => JSON.parse((await runCli([...args, '--json'])).stdout);
- // JSON keeps docs(): a bare read is the whole topic.
- expect((await envelope(['docs', 'theme'])).type).toBe('docs.detail');
- expect((await envelope(['docs', 'theme', '--full'])).type).toBe('docs.detail');
- expect((await envelope(['docs', 'theme', '--index'])).type).toBe(
- 'docs.index',
- );
- expect((await envelope(['docs', 'theme', 'quick-start'])).type).toBe(
- 'docs.detail.section',
- );
- }, SLOW);
-});
-
-describe('the docs tree, one level at a time', () => {
- const SLOW = 60_000;
- /** @param {string} out */
- const widest = out => Math.max(...out.split('\n').map(line => line.length));
-
- it('lists the docs tree first, under its own heading, then the topics', async () => {
- const {status, stdout} = await runCli(['docs']);
- expect(status).toBe(0);
- expect(stdout).toMatch(/^Docs tree$/m);
- expect(stdout).toMatch(/^Topics$/m);
- expect(stdout).toMatch(/^cli +Commands, programmatic APIs/m);
- expect(stdout.indexOf('\ncli ')).toBeLessThan(stdout.indexOf('\nprinciples '));
- expect(stdout).not.toMatch(/^cli-integrations /m);
- }, SLOW);
-
- it("shows a child's own name when its route name does not spell it", async () => {
- const {status, stdout} = await runCli(['docs', 'cli/api/functions']);
- expect(status).toBe(0);
- expect(stdout).toMatch(/^assert-response +assertResponse\(\): \S/m);
- expect(stdout).toMatch(/^search +search\(\): Unified ranked search/m);
- }, SLOW);
-
- it('prints a namespace: each slot, its children, and how to go down and up', async () => {
- const {status, stdout} = await runCli(['docs', 'cli/api']);
- expect(status).toBe(0);
- expect(stdout).toMatch(/^API$/m);
- expect(stdout).toMatch(/^Reference$/m);
- expect(stdout).toMatch(/^functions +Functions: Every function/m);
- expect(stdout).toMatch(/^schemas +/m);
- expect(stdout).toMatch(/^enums +/m);
- // One level only: no function is listed on the api page.
- expect(stdout).not.toMatch(/^search +/m);
- expect(stdout).toMatch(/Open one: .*docs cli\/api\/<name>$/m);
- expect(stdout).toMatch(/Up: .*docs cli$/m);
- expect(widest(stdout)).toBeLessThanOrEqual(120);
- }, SLOW);
-
- it('prints a typed doc and the way back up', async () => {
- const {status, stdout} = await runCli(['docs', 'cli/api/functions/search']);
- expect(status).toBe(0);
- expect(stdout).toMatch(/^## search\(\)/m);
- expect(stdout).toContain('Read it with `astryx docs cli/commands/search`.');
- expect(stdout).toMatch(/Up: .*docs cli\/api\/functions$/m);
- }, SLOW);
-
- it('reads the dense variant whole, asked with --dense or with --lang dense', async () => {
- for (const args of [['--dense', 'docs', 'theme'], ['--lang', 'dense', 'docs', 'theme']]) {
- const {status, stdout} = await runCli(args);
- expect(status).toBe(0);
- expect(stdout).not.toContain('Read one section:');
- }
- }, SLOW);
-
- it('refuses --index with --full', async () => {
- const both = await runCli(['docs', 'theme', '--index', '--full', '--json']);
- expect(both.status).toBe(1);
- expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');
- }, SLOW);
-
- it('reads the component lookup guide and its output/API examples', async () => {
- const index = await runCli([
- 'docs',
- 'cli/component-lookups',
- '--index',
- ]);
- expect(index.status).toBe(0);
- expect(index.stdout).toContain('several');
- expect(index.stdout).toContain('selectors');
- expect(index.stdout).toContain('output');
- expect(index.stdout).toContain('api');
-
- const output = await runCli([
- 'docs',
- 'cli/component-lookups',
- 'output',
- ]);
- expect(output.status).toBe(0);
- expect(output.stdout).toContain('component.batch');
- expect(output.stdout).toContain('ERR_UNKNOWN_COMPONENT');
- expect(output.stdout).toContain('exits 1');
-
- const api = await runCli(['docs', 'cli/component-lookups', 'api']);
- expect(api.status).toBe(0);
- expect(api.stdout).toContain('component([])');
- expect(api.stdout).toContain("component(['Button'])");
- }, SLOW);
-
- it('reads the integration guide by its route, and not by its old name', async () => {
- const guide = await runCli(['docs', 'cli/integrations', '--index']);
- expect(guide.status).toBe(0);
- expect(guide.stdout).toMatch(/Read one section: .*docs cli\/integrations <section>/);
- // A bare read is one level too: the sections, and how to read it all.
- const bare = await runCli(['docs', 'cli/integrations']);
- expect(bare.status).toBe(0);
- expect(bare.stdout).toBe(guide.stdout);
- expect(bare.stdout).toMatch(/Read everything: +.*docs cli\/integrations --full$/m);
- const one = await runCli(['docs', 'cli/integrations', 'codemods']);
- expect(one.status).toBe(0);
- expect(one.stdout).toMatch(/^## Codemods$/m);
- expect(one.stdout).toMatch(/^Up: .*docs cli\/integrations --index$/m);
- expect(one.stdout).toMatch(/^Previous: .*docs cli\/integrations agent-docs$/m);
- expect(one.stdout).toMatch(/^Next: .*docs cli\/integrations recording-runs$/m);
- const full = await runCli(['docs', 'cli/integrations', '--full']);
- expect(full.status).toBe(0);
- expect(full.stdout).toMatch(/^## Overview$/m);
- expect(full.stdout.length).toBeGreaterThan(bare.stdout.length * 4);
- const old = await runCli(['docs', 'cli-integrations']);
- expect(old.status).toBe(1);
- expect(old.stderr).toContain('Unknown topic "cli-integrations"');
- }, SLOW);
-
- it('returns docs.node as JSON, and fails a section of a namespace', async () => {
- const node = JSON.parse((await runCli(['docs', 'cli', '--json'])).stdout);
- expect(node).toMatchObject({
- type: 'docs.node',
- data: {route: 'cli', kind: 'namespace', breadcrumb: []},
- });
- expect(node.data.slots.map(slot => slot.name)).toEqual(['guides', 'reference']);
- const section = await runCli(['docs', 'cli', 'commands', '--json']);
- expect(section.status).toBe(1);
- const error = JSON.parse(section.stdout);
- expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
- expect(error.suggestions.map(s => s.name)).toEqual([
- 'cli/component-lookups',
- 'cli/integrations',
- 'cli/writing-docs',
- 'cli/commands',
- 'cli/api',
- ]);
- }, SLOW);
-});
-
-describe('text width in every language', () => {
- const SLOW = 60_000;
- /** Widest line outside code blocks, in terminal columns. */
- const widest = out => {
- let inCode = false;
- let max = 0;
- for (const line of out.split('\n')) {
- if (/^\s*```/.test(line)) {
- inCode = !inCode;
- continue;
- }
- // A single unbreakable token (a long URL) cannot wrap without breaking it.
- const oneToken = !/\s/.test(line.trim());
- if (!inCode && !line.startsWith('#') && !oneToken) {
- max = Math.max(max, displayWidth(line));
- }
- }
- return max;
- };
-
- it('keeps the additive section index within 120 columns', async () => {
- const {status, stdout} = await runCli([
- 'docs',
- 'theme',
- '--index',
- '--lang',
- 'zh',
- ]);
- expect(status).toBe(0);
- expect(widest(stdout)).toBeLessThanOrEqual(120);
- }, SLOW);
-});
diff --git a/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs b/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs
index 1ba8eab2ee..b45a3cd19b 100644
--- a/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration-docs.doc.mjs
@@ -10,9 +10,10 @@ export const doc = {
namespace: 'cli/commands',
summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
description:
- 'Reports intentional Core topic replacements and extensions as information. ' +
+ 'Checks the docs tree the package adds, every link in its docs, and overlaps with Core topics. ' +
+ 'Intentional replacements and extensions are information. ' +
'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
- 'and fails until the author declares the relationship or renames it.',
+ 'and fails until the author declares the relationship or renames it. See {@link generic:check-your-docs}.',
fn: 'integrationDocConflicts',
args: [
{
diff --git a/packages/cli/clients/cli/commands/doctor-integration.test.mjs b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
index f470f61f8d..2d7d2b3e39 100644
--- a/packages/cli/clients/cli/commands/doctor-integration.test.mjs
+++ b/packages/cli/clients/cli/commands/doctor-integration.test.mjs
@@ -13,6 +13,7 @@ vi.mock('../../../foundation/discovery/template-conflict-release.mjs', () => ({
expandedTemplateConflictSchemaActive: () => true,
}));
import * as fs from 'node:fs';
+import * as os from 'node:os';
import * as path from 'node:path';
import {Command} from 'commander';
import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
@@ -344,6 +345,35 @@ describe('doctor integration — command', () => {
expect(process.exitCode).toBe(1);
});
+ it('components exits 1 when Core is missing, with no [ok] after the failure', async () => {
+ // Outside the repo, so nothing above the package resolves Core.
+ const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-core-'));
+ const previousTmp = tmpDir;
+ tmpDir = outside;
+ try {
+ writeComponentIntegration('AcmeCarousel');
+ expect(findCoreDir(outside)).toBeNull();
+ process.chdir(outside);
+
+ await createProgram().parseAsync([
+ 'node',
+ 'astryx',
+ 'doctor',
+ 'integration',
+ 'components',
+ ]);
+
+ const printed = logCalls.join('\n');
+ expect(printed).toContain('core_not_found');
+ expect(printed).not.toContain('[ok]');
+ expect(process.exitCode).toBe(1);
+ } finally {
+ tmpDir = previousTmp;
+ process.chdir(previousCwd);
+ fs.rmSync(outside, {recursive: true, force: true});
+ }
+ });
+
it('components warns with the exact package-qualified command', async () => {
const coreDir = findCoreDir(tmpDir);
expect(coreDir).not.toBeNull();
@@ -433,6 +463,29 @@ describe('doctor integration — command', () => {
expect(process.exitCode).toBeUndefined();
});
+ it('docs exits 1 for a placement that hides a guide, with no [ok] after the failure', async () => {
+ writeDocIntegration({name: 'deploying'});
+ fs.writeFileSync(
+ path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
+ "export default {type: 'generic', name: 'deploying', title: 'Deploying', description: 'Deploy.', placement: {parent: 'namespace:nope', slot: 'guides'}, sections: [{title: 'Deploy', content: [{type: 'prose', text: 'Deploy.'}]}]};\n",
+ );
+ process.chdir(tmpDir);
+
+ await createProgram().parseAsync([
+ 'node',
+ 'astryx',
+ 'doctor',
+ 'integration',
+ 'docs',
+ ]);
+
+ const printed = logCalls.join('\n');
+ expect(printed).toContain('[fail]');
+ expect(printed).toContain('invalid_doc_graph');
+ expect(printed).not.toContain('[ok]');
+ expect(process.exitCode).toBe(1);
+ });
+
it('docs exits 1 for an accidental same-name Core topic', async () => {
const [coreTopic] = Object.keys(discoverBuiltinTopics());
writeDocIntegration({name: coreTopic});
diff --git a/packages/cli/clients/cli/commands/doctor.doc.mjs b/packages/cli/clients/cli/commands/doctor.doc.mjs
index 30dda6904c..71416b24e9 100644
--- a/packages/cli/clients/cli/commands/doctor.doc.mjs
+++ b/packages/cli/clients/cli/commands/doctor.doc.mjs
@@ -16,7 +16,9 @@ export const doc = {
summary: 'Diagnose Astryx projects and integration packages',
description:
'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
- 'install and version alignment, themes, config, agent docs, and package manager. ' +
+ 'install and version alignment, themes, config, integrations (linked without a config entry, ' +
+ 'provider identity, contribution issues), agent docs, core peer dependencies, package manager, ' +
+ "and the docs the CLI reads. It writes nothing, but loading astryx.config runs that file's code. " +
'The `integration` subcommands provide authoring checks for one integration package.',
fn: 'doctor',
subcommands: ['integration'],
diff --git a/packages/cli/clients/cli/commands/doctor.mjs b/packages/cli/clients/cli/commands/doctor.mjs
index 90860d6407..547a583bff 100644
--- a/packages/cli/clients/cli/commands/doctor.mjs
+++ b/packages/cli/clients/cli/commands/doctor.mjs
@@ -36,6 +36,8 @@ import {doc as integrationTemplateConflictsFn} from '../../../api/integration/in
import {doc as integrationComponentConflictsFn} from '../../../api/integration/integrationComponentConflicts.doc.mjs';
import {doc as integrationDocConflictsFn} from '../../../api/integration/integrationDocConflicts.doc.mjs';
import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
const STATUS = {
pass: '[ok]',
@@ -181,8 +183,10 @@ function printComponentConflicts(data) {
),
...issueBlocks(data.issues),
];
+ // An [ok] after a failed check reads as a pass: say nothing it could not check.
+ const failed = data.issues.some(issue => issue.severity === 'error');
if (data.conflicts.length === 0) {
- output.push(text('[ok] No component names conflict with Core.'));
+ if (!failed) output.push(text('[ok] No component names conflict with Core.'));
} else {
output.push(
records(data.conflicts, {
@@ -224,7 +228,9 @@ function printDocConflicts(data) {
);
}
if (data.findings.length === 0) {
- output.push(text('[ok] No doc topics overlap with Core.'));
+ if (!data.issues.some(issue => issue.severity === 'error')) {
+ output.push(text('[ok] No doc topics overlap with Core.'));
+ }
} else {
output.push(
records(data.findings, {
@@ -315,19 +321,57 @@ async function runAuthoringCheck(program, pkg, kind) {
return NO_RESULT_SET;
}
+/**
+ * The first word after a command group, which names a subcommand it does not
+ * have, or null.
+ * @param {import('commander').Command | undefined} invoked
+ * @returns {string | null}
+ */
+function unknownWord(invoked) {
+ const word = (invoked?.args ?? []).find(arg => !String(arg).startsWith('-'));
+ return word == null ? null : String(word);
+}
+
+/**
+ * Report an unknown subcommand, in text as in JSON, with the ones the group has.
+ * @param {import('commander').Command} group
+ * @param {string} label the group's full name
+ * @param {string} word
+ */
+function unknownSubcommand(group, label, word) {
+ return cliError(`unknown subcommand '${label} ${word}'`, {
+ suggestions: group.commands.map(child => ({
+ name: child.name(),
+ reason: 'available subcommand',
+ })),
+ code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
+ });
+}
+
/**
* Register `astryx doctor` and its integration-authoring leaves.
* @param {import('commander').Command} program
*/
export function registerDoctor(program) {
- const doctorCmd = defineCommand(program, doctorCommand, {
+ /** @type {import('commander').Command} */
+ let doctorCmd;
+ doctorCmd = defineCommand(program, doctorCommand, {
fn: doctorFn,
- action: async () => runProjectDoctor(program),
+ // `doctor integrations` is a mistyped subcommand, not a project check.
+ action: async (options, invoked) => {
+ const word = unknownWord(invoked);
+ if (word != null) return unknownSubcommand(doctorCmd, 'doctor', word);
+ return runProjectDoctor(program);
+ },
});
/** @type {import('commander').Command} */
let integrationCmd;
integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {
- action: () => {
+ action: (options, invoked) => {
+ const word = unknownWord(invoked);
+ if (word != null) {
+ return unknownSubcommand(integrationCmd, 'doctor integration', word);
+ }
integrationCmd.outputHelp();
return NO_RESULT_SET;
},
diff --git a/packages/cli/clients/cli/commands/gap-report.doc.mjs b/packages/cli/clients/cli/commands/gap-report.doc.mjs
index e74414e2f4..d9fc6ef2b0 100644
--- a/packages/cli/clients/cli/commands/gap-report.doc.mjs
+++ b/packages/cli/clients/cli/commands/gap-report.doc.mjs
@@ -11,9 +11,12 @@ export const doc = {
name: 'gap-report',
displayName: 'astryx gap-report',
namespace: 'cli/commands',
- summary: 'Route a design-system gap to its owning package',
+ summary: 'Report a missing component or feature to the package that owns it',
description:
- 'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',
+ 'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability to the package that owns it: the --package you name, else the one package that provides the component, else Core. ' +
+ 'Every configured handler receives the report: the project config handler first, then each integration handler in config order. Public handlers run only with --confirm-public; internal handlers always run. A failing handler does not stop the others. ' +
+ "With no handler it files a GitHub issue for the owning package, only with --confirm-public (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+ 'The report records whether an agent or a person ran it.',
fn: 'gapReport',
args: [
{
@@ -45,12 +48,14 @@ export const doc = {
{
flag: '--package <pkg>',
param: 'options.package',
- description: 'Route to a specific loaded package',
+ description:
+ 'Package that owns the gap: @astryxdesign/core or a loaded integration. Overrides automatic routing; needed when more than one package provides the component',
},
{
flag: '--confirm-public',
param: 'options.confirmPublic',
- description: 'Consent to public handlers or GitHub issue creation',
+ description:
+ 'Allow public delivery: public handlers run, and with no handler it files a GitHub issue with your gh login',
},
{
flag: '--list-categories',
@@ -62,13 +67,9 @@ export const doc = {
examples: [
{label: 'List categories', cli: 'astryx gap-report --list-categories'},
{
- label: 'Route an agent report',
+ label: 'Prepare a report (nothing public happens without --confirm-public)',
cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size'",
},
- {
- label: 'Confirm public filing',
- cli: "astryx gap-report Button --category docs_gap --reason 'Missing keyboard example' --confirm-public",
- },
],
exitCodes: [
{
diff --git a/packages/cli/clients/cli/commands/init.doc.mjs b/packages/cli/clients/cli/commands/init.doc.mjs
index cfa0954283..e657564947 100644
--- a/packages/cli/clients/cli/commands/init.doc.mjs
+++ b/packages/cli/clients/cli/commands/init.doc.mjs
@@ -18,21 +18,22 @@ export const doc = {
'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +
'agents, and CI). By default it installs the AGENTS.md/CLAUDE.md agent-docs, ' +
'including guidance from configured integrations, and prints getting-started ' +
- 'guidance; features/--all add theme and page-building ' +
- 'guidance and write an annotated theme template.',
+ "steps. --features and --all print only the chosen features' guidance (no " +
+ 'getting-started steps); the theme feature also writes an annotated theme template.',
fn: 'init',
options: [
{
flag: '--features <list>',
param: 'options.features',
description:
- 'Comma-separated features to install (agents, theme, template). An unknown feature exits 1 with ERR_UNKNOWN_FEATURE. ' +
- 'Ignored with --all or --remove-agents',
+ 'Comma-separated features: agents (agent docs), theme (writes theme.template.ts), template (prints the page-building commands; writes no file). ' +
+ 'An unknown feature exits 1 with ERR_UNKNOWN_FEATURE. Ignored with --all or --remove-agents',
},
{
flag: '--all',
param: 'options.all',
- description: 'Install all features (agents, theme, template); overrides --features',
+ description:
+ 'Install all features (agents, theme, template); overrides --features. Prints their guidance instead of the getting-started steps',
},
{
flag: '--remove-agents',
@@ -47,7 +48,9 @@ export const doc = {
param: 'options.agent',
choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
description:
- 'Target AI tool for agent docs: claude, cursor, codex, hermes, muse, all. An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
+ 'Target AI tool for agent docs: claude (CLAUDE.md or .claude/CLAUDE.md, else creates .claude/CLAUDE.md), cursor (.cursorrules if present, else AGENTS.md), ' +
+ 'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc, else AGENTS.md and .claude/CLAUDE.md). ' +
+ 'An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence',
},
{
diff --git a/packages/cli/clients/cli/commands/integration-add.doc.mjs b/packages/cli/clients/cli/commands/integration-add.doc.mjs
index 4655b761b4..25d1ae9acf 100644
--- a/packages/cli/clients/cli/commands/integration-add.doc.mjs
+++ b/packages/cli/clients/cli/commands/integration-add.doc.mjs
@@ -8,7 +8,7 @@ export const doc = {
namespace: 'cli/commands',
summary: 'Add one working contribution to an integration package',
description:
- 'Writes the complete minimum shape the selected contribution needs, creates the integration manifest on first use, declares the root only after a valid contribution exists, and verifies the result through the same discovery contract the packed-package check uses.',
+ 'Writes the files one contribution needs, creates the integration manifest on first use, and declares a root only after a contribution the CLI can read exists behind it. A component or template import also needs an `exports` entry: add writes one only when package.json already has an `exports` map, so start a new package with `"exports": {}`. See {@link generic:quick-start}.',
fn: 'integrationAdd',
args: [
{
@@ -60,10 +60,14 @@ export const doc = {
flag: '--to <version>',
param: 'options.to',
description:
- 'Exact semver the codemod migrates to (e.g. 1.2.0); required for codemod and only valid there',
+ 'Exact semver of the @astryxdesign/core version whose upgrade runs the codemod (e.g. 0.7.0); required for codemod and only valid there',
},
],
examples: [
+ {
+ label: 'Preview',
+ cli: 'astryx integration add component AcmeWidget --dry-run --json',
+ },
{
label: 'Add a component',
cli: 'astryx integration add component AcmeWidget',
@@ -71,7 +75,7 @@ export const doc = {
{label: 'Add a doc topic', cli: 'astryx integration add doc deploying'},
{
label: 'Add a page template',
- cli: 'astryx integration add template dashboard',
+ cli: 'astryx integration add template acme-dashboard',
},
{
label: 'Add a block template',
@@ -87,7 +91,7 @@ export const doc = {
},
{
label: 'Add a guide to the package\'s own docs section',
- cli: 'astryx integration add doc deploying --parent acme',
+ cli: 'astryx integration add doc releasing --parent acme',
},
{
label: 'Add a codemod',
@@ -98,10 +102,6 @@ export const doc = {
cli: "astryx integration add agent-doc 'Run acme verify before finishing.'",
},
{label: 'Add a source theme', cli: 'astryx integration add theme ocean'},
- {
- label: 'Preview',
- cli: 'astryx integration add component AcmeWidget --dry-run --json',
- },
],
exitCodes: [
{code: 0, when: 'the contribution is written or the dry run succeeds'},
@@ -110,5 +110,5 @@ export const doc = {
when: 'the kind, name, options, package, or target files are invalid or conflict',
},
],
- related: ['integration pack', 'doctor integration validate', 'theme add'],
+ related: ['integration verify', 'doctor integration validate', 'theme add'],
};
diff --git a/packages/cli/clients/cli/commands/integration-authoring.test.mjs b/packages/cli/clients/cli/commands/integration-authoring.test.mjs
index 5610432c3a..47493833e7 100644
--- a/packages/cli/clients/cli/commands/integration-authoring.test.mjs
+++ b/packages/cli/clients/cli/commands/integration-authoring.test.mjs
@@ -127,10 +127,7 @@ describe('integration authoring CLI', () => {
);
expect(added.status).toBe(0);
- const checked = await runCli(
- ['integration', 'pack', '--check', '--json'],
- tmpDir,
- );
+ const checked = await runCli(['integration', 'verify', '--json'], tmpDir);
// Without an exports map, the extensionless import cannot resolve —
// pack-check must fail, not false-green.
expect(checked.status).not.toBe(0);
@@ -150,13 +147,67 @@ describe('integration authoring CLI', () => {
);
});
- it('requires the explicit --check gate on pack', async () => {
- const result = await runCli(['integration', 'pack', '--json'], tmpDir);
- expect(result.status).not.toBe(0);
- expect(parseEnvelope(result.stdout)).toMatchObject({
- code: 'ERR_INVALID_ARGUMENT',
- error: 'Pass --check to verify the integration tarball.',
+ it('keeps `integration pack --check` as a deprecated alias of `integration verify`', async () => {
+ // The old spelling runs the same check: the same JSON, the same exit code.
+ const verify = await runCli(['integration', 'verify', '--json'], tmpDir);
+ const old = await runCli(
+ ['integration', 'pack', '--check', '--json'],
+ tmpDir,
+ );
+ expect(old.status).toBe(verify.status);
+ const verifyEnvelope = parseEnvelope(verify.stdout);
+ const oldEnvelope = parseEnvelope(old.stdout);
+ expect(oldEnvelope.type).toBe('integration.pack-check');
+ expect(oldEnvelope.type).toBe(verifyEnvelope.type);
+ expect(oldEnvelope.data.packable).toBe(verifyEnvelope.data.packable);
+ expect(oldEnvelope.data.issues).toEqual(verifyEnvelope.data.issues);
+ // The global flag may come first, as agents usually write it.
+ const lead = await runCli(
+ ['--json', 'integration', 'pack', '--check'],
+ tmpDir,
+ );
+ expect(parseEnvelope(lead.stdout).type).toBe('integration.pack-check');
+ // In text, it says to use the new name, on stderr, so stdout is the same.
+ const text = await runCli(['integration', 'pack', '--check'], tmpDir);
+ const verifyText = await runCli(['integration', 'verify'], tmpDir);
+ expect(text.status).toBe(verifyText.status);
+ expect(text.stdout).toBe(verifyText.stdout);
+ expect(text.stderr).toContain('`integration pack --check` is deprecated');
+ expect(text.stderr).toContain('astryx integration verify');
+ // Without --check it fails, as it did, and names both spellings.
+ const bare = await runCli(['integration', 'pack'], tmpDir);
+ expect(bare.status).not.toBe(0);
+ expect(bare.stderr).toContain('--check');
+ expect(bare.stderr).toContain('astryx integration verify');
+ // Help lists it, marked deprecated: nothing is hidden.
+ const help = await runCli(['integration', '--help'], tmpDir);
+ expect(help.stdout).toMatch(
+ /pack .*Deprecated: the old name of `integration verify`/,
+ );
+ // `verify` itself takes no --check.
+ const flag = await runCli(['integration', 'verify', '--check'], tmpDir);
+ expect(flag.status).not.toBe(0);
+ expect(flag.stderr).toContain("unknown option '--check'");
+ // An unknown subcommand with a flag names the subcommand, in text and JSON.
+ const unknown = await runCli(['integration', 'bogus', '--check'], tmpDir);
+ expect(unknown.status).not.toBe(0);
+ expect(unknown.stderr).toContain("unknown subcommand 'integration bogus'");
+ expect(unknown.stderr).toMatch(/verify\s+\(available subcommand\)/);
+ const unknownJson = await runCli(
+ ['integration', 'bogus', '--check', '--json'],
+ tmpDir,
+ );
+ expect(parseEnvelope(unknownJson.stdout)).toMatchObject({
+ code: 'ERR_UNKNOWN_SUBCOMMAND',
+ error: "unknown subcommand 'integration bogus'",
+ suggestions: expect.arrayContaining([
+ expect.objectContaining({name: 'verify'}),
+ ]),
});
+ // A flag alone is an unknown option, not an unknown subcommand.
+ const flagOnly = await runCli(['integration', '--bogus'], tmpDir);
+ expect(flagOnly.status).not.toBe(0);
+ expect(flagOnly.stderr).toContain("unknown option '--bogus'");
});
it('refuses kind-specific options on another kind', async () => {
diff --git a/packages/cli/clients/cli/commands/integration-pack.doc.mjs b/packages/cli/clients/cli/commands/integration-pack.doc.mjs
index 460b36f719..022e57731a 100644
--- a/packages/cli/clients/cli/commands/integration-pack.doc.mjs
+++ b/packages/cli/clients/cli/commands/integration-pack.doc.mjs
@@ -6,22 +6,18 @@ export const doc = {
name: 'integration pack',
displayName: 'astryx integration pack',
namespace: 'cli/commands',
- summary: 'Prove the packed integration is what consumers receive',
+ summary: 'Deprecated: the old name of `integration verify`',
description:
- 'Runs the package lifecycle, packs with npm, checks every required contribution file against the real tarball, extracts it into a scratch consumer, and compares the local and packed contribution inventories through one shared contract.',
+ '`astryx integration pack --check` is the name this check had before {@link command:integration verify}. It still runs the same check, with the same output, JSON, and exit codes, and prints a note that names `integration verify`. It will be removed in a later release.',
fn: 'integrationPackCheck',
options: [
{
flag: '--check',
- description: 'Run the packed-package verification gate',
+ description: 'Run the check. Required, as before.',
},
],
examples: [
- {label: 'Verify before publishing', cli: 'astryx integration pack --check'},
- {
- label: 'Machine-readable result',
- cli: 'astryx integration pack --check --json',
- },
+ {label: 'The old spelling', cli: 'astryx integration pack --check'},
],
exitCodes: [
{code: 0, when: 'the packed package exposes the same valid contributions'},
@@ -30,5 +26,5 @@ export const doc = {
when: '--check is omitted or the tarball is incomplete or invalid',
},
],
- related: ['integration add', 'doctor integration validate'],
+ related: ['integration verify'],
};
diff --git a/packages/cli/clients/cli/commands/integration-real-world.test.mjs b/packages/cli/clients/cli/commands/integration-real-world.test.mjs
index 4f5a887246..021e067b43 100644
--- a/packages/cli/clients/cli/commands/integration-real-world.test.mjs
+++ b/packages/cli/clients/cli/commands/integration-real-world.test.mjs
@@ -214,7 +214,7 @@ export const oceanTheme = defineTheme({
]);
const checked = await runCli(
- ['integration', 'pack', '--check', '--json'],
+ ['integration', 'verify', '--json'],
providerDir,
);
expect(checked.status, checked.stderr).toBe(0);
diff --git a/packages/cli/clients/cli/commands/integration-verify.doc.mjs b/packages/cli/clients/cli/commands/integration-verify.doc.mjs
new file mode 100644
index 0000000000..71080d04cd
--- /dev/null
+++ b/packages/cli/clients/cli/commands/integration-verify.doc.mjs
@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+ type: 'command',
+ name: 'integration verify',
+ displayName: 'astryx integration verify',
+ namespace: 'cli/commands',
+ summary: 'Check the package the way npm will publish it, before you publish',
+ description:
+ 'Packs the package with npm, unpacks the tarball into a temporary app without installing its dependencies, and checks that the app sees the same components, templates, themes, docs, and codemods as the package, that every public import resolves, and that the package declares a CLI new enough to read it. It publishes nothing and leaves no tarball behind. It runs the package\'s own pack lifecycle scripts, as `npm pack` does.',
+ fn: 'integrationPackCheck',
+ examples: [
+ {label: 'Check before publishing', cli: 'astryx integration verify'},
+ {label: 'Machine-readable result', cli: 'astryx integration verify --json'},
+ ],
+ exitCodes: [
+ {code: 0, when: 'the packed package exposes the same valid contributions'},
+ {code: 1, when: 'the tarball is incomplete or invalid'},
+ ],
+ related: ['integration add', 'doctor integration validate'],
+};
diff --git a/packages/cli/clients/cli/commands/integration.doc.mjs b/packages/cli/clients/cli/commands/integration.doc.mjs
index d7eec724ad..2d3a546c64 100644
--- a/packages/cli/clients/cli/commands/integration.doc.mjs
+++ b/packages/cli/clients/cli/commands/integration.doc.mjs
@@ -8,16 +8,16 @@ export const doc = {
namespace: 'cli/commands',
summary: 'Author and verify an Astryx integration package',
description:
- 'Add contributions that are valid on arrival, then prove the packed package exposes the same contributions a consumer will receive.',
- subcommands: ['add', 'pack'],
+ 'Add contributions to your package, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
+ subcommands: ['add', 'verify', 'pack'],
examples: [
{
label: 'Add a component',
cli: 'astryx integration add component AcmeWidget',
},
{
- label: 'Check the package tarball',
- cli: 'astryx integration pack --check',
+ label: 'Check the package before publishing',
+ cli: 'astryx integration verify',
},
],
exitCodes: [
diff --git a/packages/cli/clients/cli/commands/integration.mjs b/packages/cli/clients/cli/commands/integration.mjs
index 6da9164e8f..0f5a8de5ac 100644
--- a/packages/cli/clients/cli/commands/integration.mjs
+++ b/packages/cli/clients/cli/commands/integration.mjs
@@ -12,6 +12,7 @@ import {cliError} from '../lib/cli-error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {doc as integrationGroup} from './integration.doc.mjs';
import {doc as integrationAddCommand} from './integration-add.doc.mjs';
+import {doc as integrationVerifyCommand} from './integration-verify.doc.mjs';
import {doc as integrationPackCommand} from './integration-pack.doc.mjs';
import {doc as integrationAddFn} from '../../../api/integration/integrationAdd.doc.mjs';
import {doc as integrationPackCheckFn} from '../../../api/integration/integrationPackCheck.doc.mjs';
@@ -24,8 +25,16 @@ import {doc as integrationPackCheckFn} from '../../../api/integration/integratio
*/
function showGroupOrUnknown(command, label, options, invoked) {
const extras = invoked?.args ?? [];
- if (extras.length > 0) {
- return cliError(`unknown subcommand '${label} ${String(extras[0])}'`, {
+ // allowUnknownOption keeps an unknown flag among the args: a word there is
+ // an unknown subcommand, and a flag alone is an unknown option.
+ const word = extras.find(arg => !String(arg).startsWith('-'));
+ if (word == null && extras.length > 0) {
+ return cliError(`unknown option '${String(extras[0])}'`, {
+ code: ERROR_CODES.ERR_INVALID_OPTION,
+ });
+ }
+ if (word != null) {
+ return cliError(`unknown subcommand '${label} ${String(word)}'`, {
suggestions: (command.commands ?? []).map(child => ({
name: child.name(),
reason: 'available subcommand',
@@ -37,6 +46,48 @@ function showGroupOrUnknown(command, label, options, invoked) {
return NO_RESULT_SET;
}
+/**
+ * Run `integration verify` and print its result, as text or JSON.
+ * @param {import('commander').Command} program
+ */
+async function verifyPackage(program) {
+ const result = await integrationPackCheck({cwd: process.cwd()});
+ if (program.opts().json) {
+ jsonOut(result);
+ } else {
+ const {name, version, packable, tarball, inventory, issues} = result.data;
+ const identity = [name, version].filter(Boolean).join('@');
+ const blocks = [
+ section(
+ packable
+ ? 'Integration package ready'
+ : 'Integration package check failed',
+ ),
+ text(`${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`),
+ ];
+ if (tarball != null) {
+ blocks.push(
+ text(
+ `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
+ ),
+ );
+ }
+ if (issues.length > 0) {
+ blocks.push(
+ list(
+ issues.map(
+ issue =>
+ `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
+ ),
+ ),
+ );
+ }
+ emit(...blocks);
+ }
+ if (!result.data.packable) process.exitCode = 1;
+ return NO_RESULT_SET;
+}
+
/** @param {import('commander').Command} program */
export function registerIntegration(program) {
/** @type {import('commander').Command} */
@@ -45,6 +96,10 @@ export function registerIntegration(program) {
action: (options, command) =>
showGroupOrUnknown(integration, 'integration', options, command),
});
+ // An unknown subcommand given with a flag reports the unknown subcommand
+ // and lists the ones the group has, not the unknown option. Each subcommand
+ // still parses its own options.
+ integration.allowUnknownOption(true);
defineCommand(integration, integrationAddCommand, {
fn: integrationAddFn,
@@ -102,53 +157,29 @@ export function registerIntegration(program) {
},
});
+ defineCommand(integration, integrationVerifyCommand, {
+ fn: integrationPackCheckFn,
+ action: async () => verifyPackage(program),
+ });
+ // The name this check had before `integration verify`. It stays as a
+ // deprecated alias, listed as one in help, so scripts that call it keep
+ // working; it runs the same check with the same output and exit codes.
defineCommand(integration, integrationPackCommand, {
fn: integrationPackCheckFn,
action: async options => {
if (!options.check) {
- return cliError('Pass --check to verify the integration tarball.', {
- code: ERROR_CODES.ERR_INVALID_ARGUMENT,
- });
+ return cliError(
+ 'Pass --check to verify the integration tarball, or run `astryx integration verify`.',
+ {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
+ );
}
-
- const result = await integrationPackCheck({cwd: process.cwd()});
- if (program.opts().json) {
- jsonOut(result);
- } else {
- const {name, version, packable, tarball, inventory, issues} =
- result.data;
- const identity = [name, version].filter(Boolean).join('@');
- const blocks = [
- section(
- packable
- ? 'Integration package ready'
- : 'Integration package check failed',
- ),
- text(
- `${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`,
- ),
- ];
- if (tarball != null) {
- blocks.push(
- text(
- `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
- ),
- );
- }
- if (issues.length > 0) {
- blocks.push(
- list(
- issues.map(
- issue =>
- `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
- ),
- ),
- );
- }
- emit(...blocks);
+ // stderr, and only in text: JSON callers get the same envelope as verify.
+ if (!program.opts().json) {
+ console.error(
+ 'Note: `integration pack --check` is deprecated. Run `astryx integration verify`: it runs the same check.',
+ );
}
- if (!result.data.packable) process.exitCode = 1;
- return NO_RESULT_SET;
+ return verifyPackage(program);
},
});
}
diff --git a/packages/cli/clients/cli/commands/manifest.doc.mjs b/packages/cli/clients/cli/commands/manifest.doc.mjs
index 99f1c6c630..0b29bf13ac 100644
--- a/packages/cli/clients/cli/commands/manifest.doc.mjs
+++ b/packages/cli/clients/cli/commands/manifest.doc.mjs
@@ -20,7 +20,7 @@ export const doc = {
'tooling to introspect. Intended to be run with --json.',
examples: [
{label: 'Full manifest', cli: 'astryx manifest --json'},
- {label: 'Shorthand', cli: 'astryx --json'},
+ {label: 'The same manifest, under data.manifest (type "help")', cli: 'astryx --json'},
],
exitCodes: [
{code: 0, when: 'success'},
diff --git a/packages/cli/clients/cli/commands/search.doc.mjs b/packages/cli/clients/cli/commands/search.doc.mjs
index e567f5b9b6..cdf397112b 100644
--- a/packages/cli/clients/cli/commands/search.doc.mjs
+++ b/packages/cli/clients/cli/commands/search.doc.mjs
@@ -16,9 +16,12 @@ export const doc = {
summary: 'Search components, hooks, docs, and templates in one ranked list',
description:
'Terminal front-end to search(): prints one ranked, greppable list across ' +
- 'every content domain, each row carrying a follow-up command to act on it.',
+ 'every content domain, each row carrying a follow-up command to act on it. ' +
+ 'Outside an app, where @astryxdesign/core is not installed, it searches the docs.',
fn: 'search',
- args: [{name: 'query', param: 'query', required: true}],
+ // Every word after `search` is the query: `astryx search dark mode` searches
+ // for "dark mode", with no quotes needed.
+ args: [{name: 'query', param: 'query', required: true, variadic: true}],
options: [
{
flag: '--type <domain>',
@@ -38,6 +41,10 @@ export const doc = {
],
examples: [
{label: 'Ranked results', cli: 'astryx search button'},
+ {
+ label: 'Several words, no quotes',
+ cli: 'astryx search dark mode --type doc',
+ },
{
label: 'Filter + JSON',
cli: 'astryx search "data table" --type template --json',
@@ -47,7 +54,7 @@ export const doc = {
{code: 0, when: 'success (including zero matches)'},
{
code: 1,
- when: 'invalid --type, a --limit that is not a positive integer, or @astryxdesign/core cannot be found',
+ when: 'invalid --type, a --limit that is not a positive integer, or --type component, hook, or template where @astryxdesign/core cannot be found',
},
],
related: ['component', 'hook', 'docs', 'template', 'build'],
diff --git a/packages/cli/clients/cli/commands/search.mjs b/packages/cli/clients/cli/commands/search.mjs
index ba7130a254..d9142fc4a4 100644
--- a/packages/cli/clients/cli/commands/search.mjs
+++ b/packages/cli/clients/cli/commands/search.mjs
@@ -14,6 +14,7 @@
*
* Usage:
* astryx search button Ranked results across all domains
+ * astryx search dark mode Every word is part of the query
* astryx search modal --type component Filter to a single domain
* astryx search forms --limit 5 Cap the result count
* astryx search button --verbose Also print score / reason
@@ -31,6 +32,7 @@ import {cliError} from '../lib/cli-error.mjs';
import {defineCommand} from '../lib/define-command.mjs';
import {search as searchApi} from '../../../api/search/search.mjs';
import {Project} from '../../../foundation/config/project.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
import {doc as searchCommand} from './search.doc.mjs';
import {doc as searchFn} from '../../../api/search/search.doc.mjs';
@@ -42,10 +44,13 @@ export function registerSearch(program) {
defineCommand(program, searchCommand, {
fn: searchFn,
action: async (
- /** @type {string} */ query,
+ /** @type {string[] | string} */ words,
/** @type {{type?: import('../../../api/search/search.type.mjs').SearchDomain, limit?: string, verbose?: boolean}} */ options,
) => {
const json = program.opts().json || false;
+ // The query is variadic: `astryx search dark mode` is one query, "dark
+ // mode". Taking only the first word dropped the rest without a word.
+ const query = Array.isArray(words) ? words.join(' ') : words;
try {
const project = await Project.load(process.cwd());
@@ -99,12 +104,25 @@ export function registerSearch(program) {
// ── Text output ──────────────────────────────────────────────
const run = getCliInvocation();
const {query: q, matchCount, results} = result.data;
+ // Outside an app an open search covers the docs alone. Say so, so a
+ // docs-only list does not read as "Astryx has no such component".
+ const note =
+ !options.type && !findCoreDir(process.cwd())
+ ? [
+ text(
+ '@astryxdesign/core is not installed here, so only the docs were searched.',
+ ),
+ ]
+ : [];
// No matches is a valid, successful outcome — clean message, exit 0.
if (results.length === 0) {
emit(
text(`No results for "${q}".`),
- text(`Try a broader term, or browse: ${run} component --list`),
+ ...note,
+ text(
+ `Try a broader term, or browse: ${run} ${note.length > 0 ? 'docs' : 'component --list'}`,
+ ),
);
return answered;
}
@@ -155,6 +173,7 @@ export function registerSearch(program) {
fields,
format: {command: formatCliCommand, parent: formatCliCommand},
}),
+ ...note,
);
return answered;
},
diff --git a/packages/cli/clients/cli/commands/search.test.mjs b/packages/cli/clients/cli/commands/search.test.mjs
index 8c1c668c32..38e35f37a5 100644
--- a/packages/cli/clients/cli/commands/search.test.mjs
+++ b/packages/cli/clients/cli/commands/search.test.mjs
@@ -191,6 +191,18 @@ describe('search CLI — exit codes + JSON contract', () => {
expect(r.stdout).toContain('No results');
});
+ it('takes every word after `search` as one query', async () => {
+ // Commander took only the first word, so `search dark mode` searched for
+ // "dark" and dropped "mode" without a word.
+ const json = await runCli(['--json', 'search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
+ expect(json.status).toBe(0);
+ const env = JSON.parse(json.stdout);
+ expect(env.data.query).toBe('dark mode');
+ expect(env.data.results[0]).toMatchObject({name: 'theme', section: 'light-dark-mode'});
+ const text = await runCli(['search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
+ expect(text.stdout).toContain('Results for "dark mode"');
+ }, SCAN_TIMEOUT);
+
it('exits 1 for an invalid --type', async () => {
const r = await runCli(['search', 'x', '--type', 'bogus'], REPO_ROOT);
expect(r.status).toBe(1);
@@ -299,14 +311,19 @@ describe('search CLI — exit codes + JSON contract', () => {
expect(r.stdout).toContain('reason:');
});
- it('exits 1 with ERR_CORE_NOT_FOUND when no @astryxdesign/core is reachable', async () => {
+ it('searches the docs when no @astryxdesign/core is reachable, and exits 1 for --type component', async () => {
const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-cli-no-core-'));
try {
- const json = await runCli(['--json', 'search', 'button'], empty);
+ const open = await runCli(['--json', 'search', 'make', 'an', 'integration'], empty);
+ expect(open.status).toBe(0);
+ expect(JSON.parse(open.stdout).data.results[0]).toMatchObject({domain: 'doc'});
+ // The text says the search covered the docs alone.
+ const text = await runCli(['search', 'button'], empty);
+ expect(text.status).toBe(0);
+ expect(text.stdout).toContain('only the docs were searched');
+ const json = await runCli(['--json', 'search', 'button', '--type', 'component'], empty);
expect(json.status).toBe(1);
expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
- const text = await runCli(['search', 'button'], empty);
- expect(text.status).toBe(1);
} finally {
fs.rmSync(empty, {recursive: true, force: true});
}
diff --git a/packages/cli/clients/cli/commands/swizzle.doc.mjs b/packages/cli/clients/cli/commands/swizzle.doc.mjs
index f324b811a4..72fa1391b6 100644
--- a/packages/cli/clients/cli/commands/swizzle.doc.mjs
+++ b/packages/cli/clients/cli/commands/swizzle.doc.mjs
@@ -46,7 +46,7 @@ export const doc = {
],
examples: [
{label: 'List swizzlable components', cli: 'astryx swizzle --list'},
- {label: 'Eject a component', cli: 'astryx swizzle XDSButton'},
+ {label: 'Eject a component', cli: 'astryx swizzle Button'},
],
exitCodes: [
{code: 0, when: 'success'},
diff --git a/packages/cli/clients/cli/commands/template.doc.mjs b/packages/cli/clients/cli/commands/template.doc.mjs
index b47b7000fb..395a3b5ab0 100644
--- a/packages/cli/clients/cli/commands/template.doc.mjs
+++ b/packages/cli/clients/cli/commands/template.doc.mjs
@@ -14,7 +14,7 @@ export const doc = {
name: 'template',
displayName: 'astryx template',
namespace: 'cli/commands',
- summary: 'Inject a page or block template',
+ summary: 'List, show, or scaffold page and block templates',
description:
'One entry point for the template family: with no name it lists the discovered ' +
'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +
diff --git a/packages/cli/clients/cli/commands/text-json-parity.test.mjs b/packages/cli/clients/cli/commands/text-json-parity.test.mjs
index fa5c258661..b58c960942 100644
--- a/packages/cli/clients/cli/commands/text-json-parity.test.mjs
+++ b/packages/cli/clients/cli/commands/text-json-parity.test.mjs
@@ -372,9 +372,15 @@ const CASES = [
skipFieldChecks: true,
},
{
+ name: 'integration verify',
+ args: ['integration', 'verify'],
+ // Needs a packable project; pack itself may exit differently.
+ skipFieldChecks: true,
+ },
+ {
+ // The deprecated alias of `integration verify`.
name: 'integration pack',
args: ['integration', 'pack', '--check'],
- // Needs a packable project; pack itself may exit differently.
skipFieldChecks: true,
},
{
diff --git a/packages/cli/clients/cli/commands/theme-add.doc.mjs b/packages/cli/clients/cli/commands/theme-add.doc.mjs
index ff0afae2fb..a90eb96970 100644
--- a/packages/cli/clients/cli/commands/theme-add.doc.mjs
+++ b/packages/cli/clients/cli/commands/theme-add.doc.mjs
@@ -41,7 +41,7 @@ export const doc = {
examples: [
{label: 'Scaffold a theme', cli: 'astryx theme add matcha'},
{
- label: 'Select an integration theme',
+ label: 'Pick the owner when two packages ship the same slug',
cli: 'astryx theme add ocean --package @acme/themes',
},
],
diff --git a/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjs b/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjs
index bcbeecc4f0..c9bb168377 100644
--- a/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjs
+++ b/packages/cli/clients/cli/commands/theme-palette-generate.doc.mjs
@@ -35,12 +35,13 @@ export const doc = {
{
flag: '--preview <path>',
param: 'options.preview',
- description: 'Write a standardized self-contained HTML preview',
+ description: 'Write a self-contained HTML preview page; the path must end in .html',
},
{
flag: '-f, --overwrite',
param: 'options.overwrite',
- description: 'Replace existing candidate and receipt files',
+ description:
+ 'Replace existing candidate, receipt, and preview files. Without it, if any of them exists, nothing is written',
},
],
examples: [
diff --git a/packages/cli/clients/cli/commands/theme-palette.doc.mjs b/packages/cli/clients/cli/commands/theme-palette.doc.mjs
index 2ed11b54a9..3784ad0052 100644
--- a/packages/cli/clients/cli/commands/theme-palette.doc.mjs
+++ b/packages/cli/clients/cli/commands/theme-palette.doc.mjs
@@ -8,8 +8,7 @@ export const doc = {
namespace: 'cli/commands',
summary: 'Create and work with theme-owned color palettes',
description:
- 'Palette authoring tools. The initial generate command creates reviewable candidates. ' +
- 'Palette inspection and diagnostic commands are intentionally deferred to follow-up work.',
+ 'Palette authoring tools. generate writes a palette candidate for you to review before a theme uses it.',
subcommands: ['generate'],
examples: [
{
diff --git a/packages/cli/clients/cli/commands/theme-targets.doc.mjs b/packages/cli/clients/cli/commands/theme-targets.doc.mjs
index 0bc5ef2a55..954b7dc5cb 100644
--- a/packages/cli/clients/cli/commands/theme-targets.doc.mjs
+++ b/packages/cli/clients/cli/commands/theme-targets.doc.mjs
@@ -20,8 +20,8 @@ export const doc = {
'the component that declares it, and the props and states that are legal override keys ' +
'under it. This is the whole themeable surface in one command: what auditing a theme, or ' +
'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
- 'component to assemble. Pass a component name to scope it; pass any substring to search ' +
- 'keys. `--json` for a list a repo can lint its own theme against.',
+ 'component to assemble. Pass a component name to scope it; pass any other text to search ' +
+ 'target keys, classes, and components. `--json` for a list a repo can lint its own theme against.',
fn: 'themeTargets',
args: [{name: 'filter', param: 'filter', required: false}],
examples: [
diff --git a/packages/cli/clients/cli/commands/theme.doc.mjs b/packages/cli/clients/cli/commands/theme.doc.mjs
index 476b04c606..df0dfb8baf 100644
--- a/packages/cli/clients/cli/commands/theme.doc.mjs
+++ b/packages/cli/clients/cli/commands/theme.doc.mjs
@@ -13,7 +13,8 @@ export const doc = {
name: 'theme',
displayName: 'astryx theme',
namespace: 'cli/commands',
- summary: 'Theme tools: build, export, and manage themes',
+ summary:
+ 'Create and build themes: add a shipped one, compile to CSS, or list what a theme can override',
description:
'The theme command group. Running astryx theme with no subcommand prints the ' +
'subcommand list; the work happens in the subcommands: compile a theme (build), ' +
diff --git a/packages/cli/clients/cli/commands/upgrade.doc.mjs b/packages/cli/clients/cli/commands/upgrade.doc.mjs
index 94b695fb89..c0bb17ba23 100644
--- a/packages/cli/clients/cli/commands/upgrade.doc.mjs
+++ b/packages/cli/clients/cli/commands/upgrade.doc.mjs
@@ -13,7 +13,8 @@ export const doc = {
name: 'upgrade',
displayName: 'astryx upgrade',
namespace: 'cli/commands',
- summary: 'Migrate versions and update ShadCN-copied compositions',
+ summary:
+ 'Update your code after upgrading Astryx, and refresh ShadCN-copied components',
description:
'Migrates project source from a previous Astryx version to the installed one by ' +
'running the registered codemods, and refreshes the fully rendered managed ' +
@@ -33,7 +34,7 @@ export const doc = {
{
flag: '--apply',
param: 'options.apply',
- description: 'Write changes to disk (default: dry-run)',
+ description: 'Write changes to disk; without it, the run is a dry run',
default: false,
},
{
@@ -80,7 +81,8 @@ export const doc = {
flag: '--registry',
param: 'options.registry',
description:
- 'Only reconcile ShadCN-copied compositions; --from is not required. ' +
+ 'Only update ShadCN-copied compositions from their install receipts: unchanged files are updated, ' +
+ 'edits that do not overlap are merged, and conflicts are left untouched; --from is not required. ' +
'Combining it with --list, --from, --force, --codemod, --skip-codemod, --integration or --install-deps exits 1 with ERR_INVALID_ARGUMENT',
default: false,
},
@@ -113,4 +115,61 @@ export const doc = {
},
],
related: ['init', 'doctor'],
+ notes: [
+ {type: 'heading', level: 3, text: 'Protected files'},
+ {
+ type: 'prose',
+ text:
+ 'Codemods never write to a file your project marks as generated, vendored, or ignored. ' +
+ 'upgrade reads these marks from the files on disk, so the answer is the same with any version control, or none. ' +
+ 'A file is protected when:',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ 'a `.gitattributes` file marks it `linguist-generated` or `linguist-vendored`',
+ 'its leading comment says `@generated`, `@partially-generated`, or `Code generated ... DO NOT EDIT.`',
+ 'a `.gitignore`, or the `.hgignore` at the project root, excludes it',
+ 'it is an installed dependency (such as anything in `node_modules`), is inside `.git`, `.hg`, or `.sl`, is a symbolic link, or is outside the project',
+ ],
+ },
+ {
+ type: 'prose',
+ text:
+ 'Rules work as they do in Git: a later rule wins, so `linguist-generated=false` or a `!` line in an ignore file ' +
+ 'returns a file to normal handling. A folder name such as `dist` or `generated` protects nothing by itself. ' +
+ 'If a protection file cannot be read or parsed, upgrade stops with ERR_CODEMOD_PROTECTION_SOURCE before it writes anything.',
+ },
+ {
+ type: 'code',
+ lang: 'text',
+ code:
+ '# .gitattributes\n' +
+ 'generated/** linguist-generated=true\n' +
+ 'vendor/** linguist-vendored=true\n' +
+ '\n' +
+ '# A later rule returns one authored file to normal handling\n' +
+ 'generated/hand-authored.ts linguist-generated=false',
+ },
+ {
+ type: 'prose',
+ text:
+ 'When a codemod would change a protected file, upgrade makes the change only in memory and leaves the file as it is. ' +
+ 'The rest of the upgrade goes ahead. With --apply, your other files are written, then upgrade runs the ' +
+ '`hooks.postCodemod` commands from astryx.config (see `astryx docs authoring config`) and checks the protected ' +
+ 'files again. If one still needs the change, the run is incomplete: it exits 1, prints ' +
+ 'ERR_CODEMOD_PROTECTED with each file and the rule that protects it, and does not refresh the agent docs. ' +
+ 'Regenerate or edit those files, then run the same upgrade again. A dry run reports the same files and writes nothing.',
+ },
+ {
+ type: 'prose',
+ text:
+ 'With --json, the receipt says `complete: false` and `errorCode: "ERR_CODEMOD_PROTECTED"`. `modifiedFiles` lists the files ' +
+ 'upgrade changed (or would change), and `protectedFiles` lists each blocked file with its `reasons`, `declarations` ' +
+ '(the rules that protect it), `codemods`, and `commands`. A generated file can name the command that rebuilds it on a ' +
+ '`Command:` line in its header, such as `// Command: pnpm run gen:panel`; upgrade prints it as ' +
+ '`Regenerate with: <command>` and lists it in `commands`.',
+ },
+ ],
};
diff --git a/packages/cli/clients/cli/index.mjs b/packages/cli/clients/cli/index.mjs
index f54bae78fb..59e1f94d60 100644
--- a/packages/cli/clients/cli/index.mjs
+++ b/packages/cli/clients/cli/index.mjs
@@ -24,7 +24,7 @@ import {emit, section, text, records} from './formatters/index.mjs';
import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
import {installJsonShim} from './lib/json-shim.mjs';
-import {addExitCodesHelp, markReportsResult} from './lib/define-command.mjs';
+import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
import {doc as manifestDoc} from './commands/manifest.doc.mjs';
import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
import * as debug from '../../foundation/debug/index.mjs';
@@ -95,6 +95,7 @@ export const JSON_SUPPORTED = new Set([
'theme targets',
'theme palette generate',
'integration add',
+ 'integration verify',
'integration pack',
'upgrade',
'manifest',
@@ -338,16 +339,24 @@ export async function createProgram() {
.name('astryx')
.description('Design system CLI — components, themes, and tooling')
.version(pkg.version)
- .option('--zh', 'Output docs in Chinese Simplified')
- .option('--dense', 'Output docs in compressed dense format (token-efficient)')
+ // These four change only the reads named in their text; every other
+ // command ignores them.
+ .option(
+ '--zh',
+ 'Simplified Chinese for component reads and for docs topics that have a translation (English otherwise)',
+ )
+ .option('--dense', 'Token-efficient dense text for component <Name> and docs <topic> reads')
.addOption(
new Option(
'--lang <locale>',
- 'Output docs in specified language/format (en, zh, dense)',
+ 'Language or format for component and docs reads: en (default), zh (as --zh), or dense (as --dense)',
).choices(['en', 'zh', 'dense']),
)
.addOption(
- new Option('--detail <level>', 'Output detail level (full, compact, brief)')
+ new Option(
+ '--detail <level>',
+ 'Detail level for component, hook, and docs tree reads (e.g. docs cli/commands/build). Lists default to brief',
+ )
.choices(['full', 'compact', 'brief'])
.default('full'),
)
@@ -467,6 +476,19 @@ export async function createProgram() {
const fullName = fullCommandName(actionCommand, program);
if (JSON_SUPPORTED.has(fullName)) return;
process.__xdsJsonHandled = true;
+ // A group given a word it does not have reports an unknown subcommand and
+ // lists the ones it has, in JSON as in text, even when a flag follows it.
+ const extras = actionCommand.commands.length > 0 ? actionCommand.args : [];
+ const unknown = extras.find(arg => !String(arg).startsWith('-'));
+ if (unknown != null) {
+ cliError(`unknown subcommand '${fullName} ${unknown}'`, {
+ code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
+ suggestions: actionCommand.commands.map(child => ({
+ name: child.name(),
+ reason: 'available subcommand',
+ })),
+ });
+ }
debug.setOutcome('rejected', {
exitCode: 1,
code: ERROR_CODES.ERR_INVALID_OPTION,
@@ -601,7 +623,7 @@ export async function createProgram() {
text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
);
});
- addExitCodesHelp(manifestCommand, manifestDoc.exitCodes);
+ addDocHelp(manifestCommand, manifestDoc);
markReportsResult(manifestCommand);
// Hidden command used by package.json postinstall scripts
diff --git a/packages/cli/clients/cli/lib/define-command.mjs b/packages/cli/clients/cli/lib/define-command.mjs
index d772cd2edb..7d63ef5ccd 100644
--- a/packages/cli/clients/cli/lib/define-command.mjs
+++ b/packages/cli/clients/cli/lib/define-command.mjs
@@ -25,6 +25,8 @@
*/
import {recordCommandResult} from '../../../foundation/debug/index.mjs';
+import {routeSegment} from '../../../foundation/discovery/docs-section-key.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
import {text} from '../formatters/index.mjs';
/**
@@ -143,10 +145,11 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
cmd.addOption(option);
}
- // Help ends with the documented exit codes. `choices` stay in the option
- // text: Commander `.choices()` would replace the api layer's
- // ERR_INVALID_ARGUMENT validation.
- addExitCodesHelp(cmd, doc.exitCodes);
+ // Help ends with the documented exit codes, the examples, and the docs
+ // route that reads the whole command. `choices` stay in the option text:
+ // Commander `.choices()` would replace the api layer's ERR_INVALID_ARGUMENT
+ // validation.
+ addDocHelp(cmd, doc);
if (action) {
// The recording seam. An action's job ends at "here is what I answered
@@ -165,6 +168,27 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
return cmd;
}
+/**
+ * End `cmd`'s help with what its CommandDoc says: the exit codes, then the
+ * examples, then `More:`, the `astryx docs` route that reads the whole command.
+ * @param {import('commander').Command} cmd
+ * @param {import('@astryxdesign/cli/authoring').CommandDoc} doc
+ */
+export function addDocHelp(cmd, doc) {
+ addExitCodesHelp(cmd, doc.exitCodes);
+ // Rendered when help is shown, so the run prefix (npx astryx, pnpm astryx,
+ // ...) is looked up then, not on every start.
+ cmd.addHelpText('after', () => {
+ const examples = (doc.examples ?? []).flatMap(({label, cli}) => [
+ ...(label ? [` # ${label}`] : []),
+ ` ${formatCliCommand(cli)}`,
+ ]);
+ const more = `More: ${formatCliCommand(`docs cli/commands/${routeSegment(doc.name)}`)}`;
+ const blocks = examples.length > 0 ? [['Examples:', ...examples].join('\n'), more] : [more];
+ return `\n${text(blocks.join('\n\n')).toString()}`;
+ });
+}
+
/**
* End `cmd`'s help with a CommandDoc's exit codes.
* @param {import('commander').Command} cmd
diff --git a/packages/cli/clients/cli/lib/define-command.test.mjs b/packages/cli/clients/cli/lib/define-command.test.mjs
index 37b5b543c2..315bda511d 100644
--- a/packages/cli/clients/cli/lib/define-command.test.mjs
+++ b/packages/cli/clients/cli/lib/define-command.test.mjs
@@ -7,6 +7,7 @@
import {Command} from 'commander';
import {describe, it, expect} from 'vitest';
import {defineCommand} from './define-command.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
import {doc as searchCommand} from '../commands/search.doc.mjs';
import {doc as searchFn} from '../../../api/search/search.doc.mjs';
@@ -46,4 +47,57 @@ describe('defineCommand', () => {
expect(cmd.name()).toBe('build');
expect(cmd.registeredArguments.map(a => a.name())).toEqual(['file']);
});
+
+ it('ends help with the exit codes, the examples, and the docs route', () => {
+ const program = new Command();
+ const group = program.command('grp');
+ const cmd = defineCommand(
+ group,
+ {
+ type: 'command',
+ name: 'grp sub',
+ displayName: 'astryx grp sub',
+ summary: 'Sub.',
+ examples: [
+ {label: 'Run it', cli: 'astryx grp sub x'},
+ {cli: 'astryx grp sub y --json'},
+ ],
+ exitCodes: [{code: 0, when: 'it works'}],
+ },
+ {action: () => {}},
+ );
+ let out = '';
+ cmd.configureOutput({writeOut: s => (out += s)});
+ cmd.outputHelp();
+ const stem = formatCliCommand('');
+ expect(out.slice(out.indexOf('\nExit codes:\n'))).toBe(
+ [
+ '',
+ 'Exit codes:',
+ ' 0 it works',
+ '',
+ 'Examples:',
+ ' # Run it',
+ ` ${stem} grp sub x`,
+ ` ${stem} grp sub y --json`,
+ '',
+ `More: ${stem} docs cli/commands/grp-sub`,
+ '',
+ ].join('\n'),
+ );
+ });
+
+ it('still names the docs route when a command has no examples', () => {
+ const program = new Command();
+ const cmd = defineCommand(
+ program,
+ {type: 'command', name: 'solo', summary: 'Solo.', exitCodes: [{code: 0, when: 'ok'}]},
+ {action: () => {}},
+ );
+ let out = '';
+ cmd.configureOutput({writeOut: s => (out += s)});
+ cmd.outputHelp();
+ expect(out).not.toContain('Examples:');
+ expect(out.endsWith(`\n\nMore: ${formatCliCommand('docs cli/commands/solo')}\n`)).toBe(true);
+ });
});
diff --git a/packages/cli/clients/cli/lib/exit-codes.test.mjs b/packages/cli/clients/cli/lib/exit-codes.test.mjs
index 60aff25fb4..6ed1ef9b14 100644
--- a/packages/cli/clients/cli/lib/exit-codes.test.mjs
+++ b/packages/cli/clients/cli/lib/exit-codes.test.mjs
@@ -41,7 +41,7 @@ describe('command exit codes', () => {
});
it.each(commandDocs.map((d) => [d.name, d]))(
- '`astryx %s --help` lists the documented exit codes',
+ '`astryx %s --help` lists the documented exit codes, then the examples and the docs route',
async (name, doc) => {
const {status, stdout} = await runCli([...name.split(' '), '--help']);
expect(status).toBe(0);
@@ -51,6 +51,22 @@ describe('command exit codes', () => {
for (const {code, when} of doc.exitCodes) {
expect(section).toContain(`\n ${code} ${when}\n`);
}
+ // Examples follow the exit codes, each under its label, and a `More:`
+ // line names the route that reads the whole command.
+ const examples = section.indexOf('\nExamples:\n');
+ expect(examples > 0, stdout).toBe((doc.examples ?? []).length > 0);
+ for (const {label, cli} of doc.examples ?? []) {
+ const line = ` ${cli.replace(/^astryx\s+/, '')}\n`;
+ expect(section.slice(examples), stdout).toContain(
+ label ? `\n # ${label}\n` : line,
+ );
+ expect(section.slice(examples)).toContain(line);
+ }
+ const route = `docs cli/commands/${name.replace(/ /g, '-')}`;
+ expect(section, stdout).toMatch(
+ new RegExp(`\\n\\nMore: \\S.* ${route}\\n`),
+ );
+ expect(section.indexOf('\nMore: ')).toBeGreaterThan(examples);
},
);
diff --git a/packages/cli/clients/cli/lib/manifest.mjs b/packages/cli/clients/cli/lib/manifest.mjs
index 402a6027cb..af72ad89bc 100644
--- a/packages/cli/clients/cli/lib/manifest.mjs
+++ b/packages/cli/clients/cli/lib/manifest.mjs
@@ -14,7 +14,8 @@
* `type` discriminators it can emit — are layered on from:
*
* - JSON_SUPPORTED (the allowlist in index.mjs), and
- * - RESPONSE_TYPES (the declarative map below).
+ * - RESPONSE_TYPES (the declarative map below; ROOT_RESPONSE_TYPES names the
+ * two, help and version, that no single command owns).
*
* A drift-guard test (manifest.test.mjs) asserts every registered command
* appears in the manifest and every JSON-supported command has a response-type
@@ -92,8 +93,9 @@ export const RESPONSE_TYPES = {
'theme targets': ['theme.targets'],
'theme palette generate': ['theme.palette.generate'],
'integration add': ['integration.add'],
+ 'integration verify': ['integration.pack-check'],
'integration pack': ['integration.pack-check'],
- upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
+ upgrade: ['upgrade.list', 'upgrade.registry', 'upgrade.status', 'upgrade.run'],
manifest: ['manifest'],
doctor: ['doctor'],
'doctor integration validate': ['integration.validate'],
@@ -102,6 +104,14 @@ export const RESPONSE_TYPES = {
'doctor integration docs': ['integration.doc-conflicts'],
};
+/**
+ * Response types no single command owns: `help` (a bare `astryx --json`, and
+ * `--help --json` on any command) and `version` (`astryx --version --json`).
+ * The response-types enum lists them beside {@link RESPONSE_TYPES}.
+ * @type {readonly string[]}
+ */
+export const ROOT_RESPONSE_TYPES = Object.freeze(['help', 'version']);
+
/**
* Example invocations per fully-qualified command. Optional, agent-facing.
* @type {Record<string, string[]>}
@@ -118,7 +128,7 @@ const EXAMPLES = {
'astryx docs spacing --json',
'astryx docs theme',
'astryx docs theme quick-start',
- 'astryx docs cli/integrations --full',
+ 'astryx docs cli/integrations/quick-start --full',
],
discover: ['astryx discover --json'],
search: [
@@ -126,7 +136,7 @@ const EXAMPLES = {
'astryx search button --type component --json',
],
build: ['astryx build', 'astryx build "analytics dashboard" --json'],
- swizzle: ['astryx swizzle XDSButton'],
+ swizzle: ['astryx swizzle Button'],
'gap-report': [
'astryx gap-report --list-categories',
"astryx gap-report Button --category docs_gap --reason 'Missing keyboard example'",
@@ -159,7 +169,7 @@ const EXAMPLES = {
'astryx integration add component AcmeWidget',
'astryx integration add doc deploying --dry-run --json',
],
- 'integration pack': ['astryx integration pack --check --json'],
+ 'integration verify': ['astryx integration verify --json'],
upgrade: ['astryx upgrade --json'],
manifest: ['astryx manifest --json', 'astryx --json'],
doctor: ['astryx doctor', 'astryx doctor --json'],
diff --git a/packages/cli/foundation/agent-docs/agent-docs.mjs b/packages/cli/foundation/agent-docs/agent-docs.mjs
index 22308c0e63..8ebccb34ca 100644
--- a/packages/cli/foundation/agent-docs/agent-docs.mjs
+++ b/packages/cli/foundation/agent-docs/agent-docs.mjs
@@ -491,7 +491,7 @@ export function generateCompressedIndex(
}
lines.push(' docs cli commands, API reference, integration authoring (one level at a time)');
lines.push(' swizzle <Name> eject component source for deep customization');
- lines.push(' upgrade --apply run after any Astryx or integration dependency bump');
+ lines.push(' upgrade --from <old version> --apply run after any Astryx or integration dependency bump');
const appendCount = agentDocs.reduce(
(count, contribution) => count + contribution.append.length,
0,
diff --git a/packages/cli/foundation/agent-docs/agent-docs.test.mjs b/packages/cli/foundation/agent-docs/agent-docs.test.mjs
deleted file mode 100644
index 4b6ac3bd1f..0000000000
--- a/packages/cli/foundation/agent-docs/agent-docs.test.mjs
+++ /dev/null
@@ -1,1159 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import * as os from 'node:os';
-import {
- generateCompressedIndex,
- detectStylingSystem,
- getXdsVersion,
- installAgentDocs,
- injectAgentsMd,
- injectClaudeMd,
- injectXdsBlock,
- removeAgentDocs,
- removeXdsBlock,
- discoverAgentDocs,
- resolveAgentPaths,
- parseBlockVersion,
- renderAgentDocsBlock,
- inspectAgentDocs,
- isAstryxInitialized,
-} from './agent-docs.mjs';
-
-let tmpDir;
-
-beforeEach(() => {
- tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-test-'));
-});
-
-afterEach(() => {
- fs.rmSync(tmpDir, {recursive: true, force: true});
- vi.restoreAllMocks();
-});
-
-describe('generateCompressedIndex', () => {
- it('includes the version number', () => {
- const result = generateCompressedIndex('1.2.3');
- expect(result).toContain('Astryx v1.2.3');
- expect(result).toContain('<!-- ASTRYX:START -->');
- expect(result).toContain('<!-- ASTRYX:END -->');
- });
-
- it('includes theme nudge rule', () => {
- const result = generateCompressedIndex('1.0.0');
- expect(result).toMatch(/astryx theme/);
- expect(result).toMatch(/never override --color-/);
- });
-
- it('sends frame choice to the layout doc rather than naming a shell', () => {
- const result = generateCompressedIndex('1.0.0');
- const frameRule = result.split('\n').find(l => l.includes('Frame first'));
- expect(frameRule).toContain('astryx docs layout');
- expect(result).not.toMatch(/AppShell/);
- expect(frameRule).not.toMatch(/https?:/);
- });
-
- it('starts every page from a template before any component', () => {
- const lines = generateCompressedIndex('1.0.0').split('\n');
- const workflow = lines.findIndex(l => l.startsWith('WORKFLOW'));
- expect(lines[workflow]).toMatch(/start every page from a template/);
- expect(lines[workflow + 1]).toMatch(/^1\. `astryx build /);
- expect(lines[workflow + 2]).toMatch(/^2\. `astryx template <name> <path>`/);
- expect(lines.join('\n')).not.toMatch(/reference code/);
- });
-
- it('includes the post-generation self-check rule', () => {
- const result = generateCompressedIndex('1.0.0');
- expect(result).toContain('SELF-CHECK before you finish');
- expect(result).toMatch(/re-read the file/);
- expect(result).toMatch(/don't hand-roll CSS/);
- });
-
- it('tailors the self-check to the styling system (xstyle for StyleX, not className for Tailwind)', () => {
- // StyleX path: className/inline style are veers; the fix is the xstyle prop + a token
- const stylex = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
- const stylexSelfCheck = stylex.split('\n').find(l => l.includes('SELF-CHECK'));
- expect(stylexSelfCheck).toMatch(/xstyle/);
- expect(stylexSelfCheck).toMatch(/className=/);
- // className IS the system in Tailwind — it must NOT be flagged
- const tailwind = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
- const tailwindSelfCheck = tailwind.split('\n').find(l => l.includes('SELF-CHECK'));
- expect(tailwindSelfCheck).toBeDefined();
- expect(tailwindSelfCheck).not.toMatch(/className=/);
- });
-
- it('defaults to the CSS-variable styling path (no compiler)', () => {
- const result = generateCompressedIndex('1.0.0');
- expect(result).toMatch(/style\/className with tokens/);
- expect(result).toMatch(/var\(--color-\*/);
- // Must NOT push xstyle when no StyleX compiler is present.
- expect(result).not.toMatch(/xstyle prop/);
- });
-
- it('recommends xstyle when StyleX is configured', () => {
- const result = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
- expect(result).toMatch(/xstyle prop \/ StyleX tokens/);
- });
-
- it('recommends Tailwind utilities when Tailwind is configured', () => {
- const result = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
- expect(result).toMatch(/Tailwind utilities backed by tokens/);
- expect(result).toMatch(/tailwind-theme\.css/);
- });
-
- it('includes upgrade command and migration rule', () => {
- const result = generateCompressedIndex('1.0.0');
- expect(result).toContain('upgrade --apply');
- expect(result).toMatch(/after any Astryx or integration dependency bump/);
- });
-
- it('states the invocation once in the CLI header (yarn)', () => {
- const result = generateCompressedIndex('1.0.0', {invocation: 'yarn astryx'});
- expect(result).toContain('yarn astryx <cmd>');
- expect(result).not.toContain('npx astryx');
- });
-
- it('uses the pnpm exec invocation', () => {
- const result = generateCompressedIndex('1.0.0', {invocation: 'pnpm exec astryx'});
- expect(result).toContain('pnpm exec astryx <cmd>');
- expect(result).not.toContain('npx astryx');
- });
-
- it('uses the scoped package for one-off (uninstalled) runs so agents never hit the bare name', () => {
- const result = generateCompressedIndex('1.0.0', {invocation: 'npx @astryxdesign/cli'});
- expect(result).toContain('npx @astryxdesign/cli <cmd>');
- // The header defines the mapping; the bare "run every command as `npx astryx`" footgun must be absent.
- expect(result).not.toContain('npx astryx <cmd>');
- });
-
- /** The `docs <topic> a, b, c` line of the block. */
- function topicLine(block) {
- return (
- block.split('\n').find(line => line.trimStart().startsWith('docs <topic>')) ?? ''
- );
- }
-
- it('names the hyphenated topics, which the scan used to drop', () => {
- // The fallback scan matched `\w+`, which does not match `-`, so five real
- // topics were missing from every block ever written. An agent cannot ask
- // for a topic it was never told about, and `getting-started` — the one it
- // should reach for first — was one of them.
- const line = topicLine(generateCompressedIndex('1.0.0'));
- for (const topic of [
- 'getting-started',
- 'browser-support',
- 'styling-libraries',
- 'working-with-ai',
- ]) {
- expect(line).toContain(topic);
- }
- });
-
- it('points to the CLI docs tree on a line of its own', () => {
- // The integration guide lives in the docs tree now (cli/integrations), so
- // the topic line no longer names it; the tree's entry point does.
- const block = generateCompressedIndex('1.0.0');
- expect(block).toContain(
- ' docs cli commands, API reference, integration authoring (one level at a time)',
- );
- expect(topicLine(block)).not.toContain('cli-integrations');
- });
-
- it('lists the topics it is given, so an integration’s reach the agent', () => {
- const line = topicLine(
- generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),
- );
- expect(line).toContain('tokens, deploying');
- // The project's catalog replaces the built-in scan rather than adding to it:
- // a topic an integration replaced must not also be listed under its old name.
- expect(line).not.toContain('typography');
- });
-
- it('omits the line entirely when the project has no topics', () => {
- expect(topicLine(generateCompressedIndex('1.0.0', {topics: []}))).toBe('');
- });
-
- it('is byte-identical when integrations contribute no lines', () => {
- const options = {
- invocation: 'npx @astryxdesign/cli',
- stylingSystem: 'css',
- topics: ['tokens', 'working-with-ai'],
- };
- expect(generateCompressedIndex('1.0.0', {...options, agentDocs: []})).toBe(
- generateCompressedIndex('1.0.0', options),
- );
- });
-
- it('appends package-labeled lines after core guidance in config order', () => {
- const result = generateCompressedIndex('1.0.0', {
- topics: [],
- agentDocs: [
- {
- package: '@acme/second',
- append: ['second one', 'second two'],
- },
- {
- package: '@acme/first',
- append: ['first one'],
- },
- ],
- });
-
- expect(result.indexOf('upgrade --apply')).toBeLessThan(
- result.indexOf('INTEGRATIONS:'),
- );
- expect(result.indexOf('INTEGRATIONS:')).toBeLessThan(
- result.indexOf('<!-- ASTRYX:END -->'),
- );
- expect(result).toContain(
- 'INTEGRATIONS:\n' +
- '- `@acme/second`: second one\n' +
- '- `@acme/second`: second two\n' +
- '- `@acme/first`: first one',
- );
- });
-
- it('caps the configured project at 32 integration lines', () => {
- const agentDocs = Array.from({length: 5}, (_, packageIndex) => ({
- package: `@acme/package-${packageIndex}`,
- append: Array.from(
- {length: packageIndex === 4 ? 1 : 8},
- (_, lineIndex) => `line ${lineIndex}`,
- ),
- }));
- expect(() => generateCompressedIndex('1.0.0', {agentDocs})).toThrow(
- /32-line project limit/,
- );
- });
-});
-
-describe('renderAgentDocsBlock', () => {
- it('produces repeatable target bytes from configured manifests', async () => {
- const projectDir = fs.mkdtempSync(
- path.join(process.cwd(), '.astryx-agent-doc-render-'),
- );
- try {
- fs.writeFileSync(
- path.join(projectDir, 'package.json'),
- JSON.stringify({name: 'consumer'}),
- );
- fs.writeFileSync(
- path.join(projectDir, 'astryx.config.mjs'),
- `export default {integrations: ['@acme/second', '@acme/first']};\n`,
- );
- const coreDir = path.join(
- projectDir,
- 'node_modules',
- '@astryxdesign',
- 'core',
- );
- fs.mkdirSync(coreDir, {recursive: true});
- fs.writeFileSync(
- path.join(coreDir, 'package.json'),
- JSON.stringify({name: '@astryxdesign/core', version: '1.0.0'}),
- );
- for (const [name, agentDocs] of [
- ['@acme/second', {append: ['second one', 'second two']}],
- ['@acme/first', {append: ['first one']}],
- ]) {
- const packageDir = path.join(
- projectDir,
- 'node_modules',
- ...name.split('/'),
- );
- fs.mkdirSync(packageDir, {recursive: true});
- fs.writeFileSync(
- path.join(packageDir, 'package.json'),
- JSON.stringify({name}),
- );
- fs.writeFileSync(
- path.join(packageDir, 'astryx.integration.mjs'),
- `export default {agentDocs: ${JSON.stringify(agentDocs)}};\n`,
- );
- }
- fs.writeFileSync(path.join(projectDir, 'AGENTS.md'), '# Agents\n');
- fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), '# Claude\n');
-
- const renderedBlock = await renderAgentDocsBlock(projectDir);
- expect(renderedBlock.indexOf('second one')).toBeLessThan(
- renderedBlock.indexOf('second two'),
- );
- expect(renderedBlock.indexOf('second two')).toBeLessThan(
- renderedBlock.indexOf('first one'),
- );
-
- installAgentDocs(projectDir, {renderedBlock});
- const firstAgents = fs.readFileSync(
- path.join(projectDir, 'AGENTS.md'),
- 'utf-8',
- );
- const firstClaude = fs.readFileSync(
- path.join(projectDir, 'CLAUDE.md'),
- 'utf-8',
- );
- expect(firstAgents).toContain(renderedBlock);
- expect(firstClaude).toContain(renderedBlock);
-
- installAgentDocs(projectDir, {renderedBlock});
- expect(fs.readFileSync(path.join(projectDir, 'AGENTS.md'), 'utf-8')).toBe(
- firstAgents,
- );
- expect(fs.readFileSync(path.join(projectDir, 'CLAUDE.md'), 'utf-8')).toBe(
- firstClaude,
- );
- } finally {
- fs.rmSync(projectDir, {recursive: true, force: true});
- }
- });
- it('rejects a package label that could alter managed block structure', async () => {
- const projectDir = fs.mkdtempSync(
- path.join(process.cwd(), '.astryx-agent-doc-label-'),
- );
- try {
- fs.writeFileSync(
- path.join(projectDir, 'package.json'),
- JSON.stringify({name: 'consumer'}),
- );
- fs.writeFileSync(
- path.join(projectDir, 'astryx.config.mjs'),
- `export default {integrations: ['@acme/widgets']};\n`,
- );
- const packageDir = path.join(
- projectDir,
- 'node_modules',
- '@acme',
- 'widgets',
- );
- fs.mkdirSync(packageDir, {recursive: true});
- fs.writeFileSync(
- path.join(packageDir, 'package.json'),
- JSON.stringify({name: '@acme/widgets\nASTRYX:END'}),
- );
- fs.writeFileSync(
- path.join(packageDir, 'astryx.integration.mjs'),
- `export default {agentDocs: {append: ['safe line']}};\n`,
- );
-
- await expect(renderAgentDocsBlock(projectDir)).rejects.toThrow(
- /not safe to render/,
- );
- } finally {
- fs.rmSync(projectDir, {recursive: true, force: true});
- }
- });
-});
-
-describe('detectStylingSystem', () => {
- function writePkg(deps) {
- fs.writeFileSync(
- path.join(tmpDir, 'package.json'),
- JSON.stringify({name: 'x', devDependencies: deps}),
- );
- }
-
- it('defaults to css when no package.json', () => {
- expect(detectStylingSystem(tmpDir)).toBe('css');
- });
-
- it('returns css for a plain project', () => {
- writePkg({react: '19.0.0', vite: '6.0.0'});
- expect(detectStylingSystem(tmpDir)).toBe('css');
- });
-
- it('detects stylex when the compiler plugin is present', () => {
- writePkg({'@stylexjs/babel-plugin': '0.0.1'});
- expect(detectStylingSystem(tmpDir)).toBe('stylex');
- });
-
- it('detects tailwind when tailwindcss is present', () => {
- writePkg({tailwindcss: '4.0.0'});
- expect(detectStylingSystem(tmpDir)).toBe('tailwind');
- });
-
- it('does NOT treat the StyleX runtime alone as a compiler', () => {
- // Only the runtime, no compiler plugin → must stay on the safe css path.
- writePkg({'@stylexjs/stylex': '0.0.1'});
- expect(detectStylingSystem(tmpDir)).toBe('css');
- });
-
- it('prefers stylex over tailwind when both are configured', () => {
- writePkg({'@stylexjs/babel-plugin': '0.0.1', tailwindcss: '4.0.0'});
- expect(detectStylingSystem(tmpDir)).toBe('stylex');
- });
-});
-
-describe('getXdsVersion', () => {
- it('reads version from core package.json', () => {
- const coreDir = path.join(tmpDir, 'core');
- fs.mkdirSync(coreDir, {recursive: true});
- fs.writeFileSync(
- path.join(coreDir, 'package.json'),
- JSON.stringify({version: '3.4.5'}),
- );
-
- expect(getXdsVersion(coreDir)).toBe('3.4.5');
- });
-});
-
-describe('injectXdsBlock', () => {
- it('injects into an existing file without markers', () => {
- const filePath = path.join(tmpDir, 'test.md');
- fs.writeFileSync(filePath, '# Existing content\n');
-
- const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
-
- expect(result).toBe(true);
- const content = fs.readFileSync(filePath, 'utf-8');
- expect(content).toContain('# Existing content');
- expect(content).toContain('<!-- ASTRYX:START -->');
- });
-
- it('replaces existing markers', () => {
- const filePath = path.join(tmpDir, 'test.md');
- fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
-
- injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
-
- const content = fs.readFileSync(filePath, 'utf-8');
- expect(content).toContain('new');
- expect(content).not.toContain('old');
- expect(content).toContain('before');
- expect(content).toContain('after');
- });
-
- it('returns false and does not create file when createIfMissing is false', () => {
- const filePath = path.join(tmpDir, 'nonexistent.md');
-
- const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->');
-
- expect(result).toBe(false);
- expect(fs.existsSync(filePath)).toBe(false);
- });
-
- it('skips files without markers when onlyReplace is true', () => {
- const filePath = path.join(tmpDir, 'test.md');
- fs.writeFileSync(filePath, '# Existing content\n\nNo XDS markers here.\n');
-
- const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
-
- expect(result).toBe(false);
- const content = fs.readFileSync(filePath, 'utf-8');
- expect(content).not.toContain('<!-- ASTRYX:START -->');
- expect(content).toBe('# Existing content\n\nNo XDS markers here.\n');
- });
-
- it('replaces existing markers even when onlyReplace is true', () => {
- const filePath = path.join(tmpDir, 'test.md');
- fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
-
- const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
-
- expect(result).toBe(true);
- const content = fs.readFileSync(filePath, 'utf-8');
- expect(content).toContain('new');
- expect(content).not.toContain('old');
- });
-
- it('creates file when createIfMissing is true', () => {
- const filePath = path.join(tmpDir, 'new.md');
-
- const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->', {
- createIfMissing: true,
- header: '# Header',
- });
-
- expect(result).toBe(true);
- const content = fs.readFileSync(filePath, 'utf-8');
- expect(content).toContain('# Header');
- expect(content).toContain('<!-- ASTRYX:START -->');
- });
-});
-
-describe('injectAgentsMd', () => {
- it('creates new AGENTS.md when none exists', () => {
- injectAgentsMd(tmpDir, '1.0.0');
-
- const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- expect(content).toContain('# AGENTS.md');
- expect(content).toContain('<!-- ASTRYX:START -->');
- expect(content).toContain('Astryx v1.0.0');
- expect(content).toContain('<!-- ASTRYX:END -->');
- });
-
- it('updates existing AGENTS.md by replacing XDS markers', () => {
- const existing = `# My Project
-
-Some content.
-
-<!-- XDS:START -->
-old content
-<!-- XDS:END -->
-
-More stuff.
-`;
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), existing);
-
- injectAgentsMd(tmpDir, '2.0.0');
-
- const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- expect(content).toContain('Astryx v2.0.0');
- expect(content).not.toContain('old content');
- expect(content).toContain('Some content.');
- expect(content).toContain('More stuff.');
- });
-
- it('appends to existing AGENTS.md without markers', () => {
- const existing = `# My Project
-
-Existing agent docs.
-`;
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), existing);
-
- injectAgentsMd(tmpDir, '1.0.0');
-
- const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- expect(content).toContain('Existing agent docs.');
- expect(content).toContain('<!-- ASTRYX:START -->');
- expect(content).toContain('Astryx v1.0.0');
- });
-});
-
-describe('injectClaudeMd', () => {
- it('injects into existing CLAUDE.md', () => {
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude Config\n\nExisting rules.\n');
-
- const result = injectClaudeMd(tmpDir, '1.0.0');
-
- expect(result).toBe(true);
- const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(content).toContain('# Claude Config');
- expect(content).toContain('Existing rules.');
- expect(content).toContain('<!-- ASTRYX:START -->');
- expect(content).toContain('Astryx v1.0.0');
- });
-
- it('does not create CLAUDE.md when it does not exist', () => {
- const result = injectClaudeMd(tmpDir, '1.0.0');
-
- expect(result).toBe(false);
- expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);
- });
-
- it('updates existing markers in CLAUDE.md', () => {
- const existing = `# Claude Config
-
-<!-- XDS:START -->
-old content
-<!-- XDS:END -->
-
-Other rules.
-`;
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), existing);
-
- injectClaudeMd(tmpDir, '2.0.0');
-
- const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(content).toContain('Astryx v2.0.0');
- expect(content).not.toContain('old content');
- expect(content).toContain('Other rules.');
- });
-});
-
-describe('removeAgentDocs', () => {
- it('removes XDS section from AGENTS.md', () => {
- const content = `# My Project
-
-Custom content here.
-
-<!-- XDS:START -->
-XDS index stuff
-<!-- XDS:END -->
-
-More custom content.
-`;
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), content);
- vi.spyOn(console, 'log').mockImplementation(() => {});
-
- removeAgentDocs(tmpDir);
-
- const result = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- expect(result).toContain('Custom content here.');
- expect(result).toContain('More custom content.');
- expect(result).not.toContain('<!-- XDS:START -->');
- expect(result).not.toContain('XDS index stuff');
- });
-
- it('removes the file entirely when only XDS content remains', () => {
- const content = `# AGENTS.md
-
-Project-specific guidance for AI coding agents.
-
-<!-- XDS:START -->
-XDS index stuff
-<!-- XDS:END -->
-`;
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), content);
- vi.spyOn(console, 'log').mockImplementation(() => {});
-
- removeAgentDocs(tmpDir);
-
- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
- });
-
- it('removes XDS section from CLAUDE.md when present', () => {
- fs.writeFileSync(
- path.join(tmpDir, 'AGENTS.md'),
- '# AGENTS.md\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n',
- );
- fs.writeFileSync(
- path.join(tmpDir, 'CLAUDE.md'),
- '# Claude\n\nRules.\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n\nMore rules.\n',
- );
- vi.spyOn(console, 'log').mockImplementation(() => {});
-
- removeAgentDocs(tmpDir);
-
- const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(claudeContent).toContain('Rules.');
- expect(claudeContent).toContain('More rules.');
- expect(claudeContent).not.toContain('<!-- XDS:START -->');
- });
-});
-
-describe('installAgentDocs', () => {
- function setupCorePackage(dir, version = '1.0.0') {
- // Create a minimal @astryxdesign/core so getXdsVersion works
- const coreDir = path.join(dir, 'node_modules', '@astryxdesign', 'core');
- fs.mkdirSync(coreDir, {recursive: true});
- fs.writeFileSync(
- path.join(coreDir, 'package.json'),
- JSON.stringify({version}),
- );
- }
-
- it('creates AGENTS.md when no agent docs exist (tool-agnostic default)', () => {
- setupCorePackage(tmpDir);
-
- const written = installAgentDocs(tmpDir);
-
- expect(written).toEqual(['AGENTS.md']);
- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
- // Must NOT create the Claude-specific file by default.
- expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
- const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- expect(content).toContain('# AGENTS.md');
- expect(content).toContain('<!-- ASTRYX:START -->');
- });
-
- it('defaults to AGENTS.md but writes .claude/CLAUDE.md only when --agent claude is explicit', () => {
- // Default (no agent): tool-agnostic AGENTS.md, never the Claude file.
- setupCorePackage(tmpDir);
- expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md']);
- expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
-
- // Explicit Claude: the Claude-specific file, in a fresh project.
- const claudeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-claude-'));
- setupCorePackage(claudeDir);
- try {
- expect(installAgentDocs(claudeDir, {agent: 'claude'})).toEqual(['.claude/CLAUDE.md']);
- expect(fs.existsSync(path.join(claudeDir, 'AGENTS.md'))).toBe(false);
- } finally {
- fs.rmSync(claudeDir, {recursive: true, force: true});
- }
- });
-
- it('injects into CLAUDE.md at root when it exists', () => {
- setupCorePackage(tmpDir);
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');
-
- const written = installAgentDocs(tmpDir);
-
- expect(written).toEqual(['CLAUDE.md']);
- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
- const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(claudeContent).toContain('<!-- ASTRYX:START -->');
- expect(claudeContent).toContain('Project rules.');
- });
-
- it('injects into all existing agent doc files', () => {
- setupCorePackage(tmpDir);
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nAgent rules.\n');
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nClaude rules.\n');
-
- const written = installAgentDocs(tmpDir);
-
- expect(written).toContain('AGENTS.md');
- expect(written).toContain('CLAUDE.md');
- const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(agentsContent).toContain('<!-- ASTRYX:START -->');
- expect(claudeContent).toContain('<!-- ASTRYX:START -->');
- });
-
- it('preserves import wrappers while initializing standalone files', () => {
- setupCorePackage(tmpDir);
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');
- fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
- const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');
- const wrapper = '@../AGENTS.md\n';
- fs.writeFileSync(wrapperPath, wrapper);
- fs.writeFileSync(path.join(tmpDir, '.cursorrules'), 'Cursor rules.\n');
-
- const written = installAgentDocs(tmpDir);
-
- expect(written).toEqual(['AGENTS.md', '.cursorrules']);
- expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);
- expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toContain(
- '<!-- ASTRYX:START -->',
- );
- expect(fs.readFileSync(path.join(tmpDir, '.cursorrules'), 'utf-8')).toContain(
- '<!-- ASTRYX:START -->',
- );
- });
-
- it('keeps cyclic imports standalone when another file exists', () => {
- setupCorePackage(tmpDir);
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '@CLAUDE.md\n');
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '@AGENTS.md\n');
- fs.writeFileSync(path.join(tmpDir, '.cursorrules'), 'Cursor rules.\n');
-
- const written = installAgentDocs(tmpDir);
-
- expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', '.cursorrules']);
- for (const rel of written) {
- expect(fs.readFileSync(path.join(tmpDir, rel), 'utf-8')).toContain(
- '<!-- ASTRYX:START -->',
- );
- }
- });
-
- it('removes a managed block previously expanded into an import wrapper', () => {
- setupCorePackage(tmpDir);
- installAgentDocs(tmpDir, {agent: 'codex'});
- fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
- const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');
- const wrapper = '@../AGENTS.md\n';
- fs.writeFileSync(wrapperPath, wrapper);
- installAgentDocs(tmpDir, {agent: 'claude'});
- expect(fs.readFileSync(wrapperPath, 'utf-8')).toContain(
- '<!-- ASTRYX:START -->',
- );
-
- const written = installAgentDocs(tmpDir, {onlyReplace: true});
-
- expect(written).toContain('AGENTS.md');
- expect(written).toContain('.claude/CLAUDE.md');
- expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);
- });
-
- it('refuses a malformed managed block inside an import wrapper', () => {
- setupCorePackage(tmpDir);
- installAgentDocs(tmpDir, {agent: 'codex'});
- fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
- fs.writeFileSync(
- path.join(tmpDir, '.claude', 'CLAUDE.md'),
- '@../AGENTS.md\n<!-- ASTRYX:START -->\nincomplete\n',
- );
-
- expect(() => installAgentDocs(tmpDir)).toThrow(/malformed|no matching/i);
- });
-
- it('updates existing .claude/CLAUDE.md', () => {
- setupCorePackage(tmpDir);
- fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
- fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '# Project\n\nExisting content.\n');
-
- const written = installAgentDocs(tmpDir);
-
- expect(written).toEqual(['.claude/CLAUDE.md']);
- const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
- expect(content).toContain('Existing content.');
- expect(content).toContain('<!-- ASTRYX:START -->');
- });
-
- it('respects --agent claude preset: finds existing CLAUDE.md', () => {
- setupCorePackage(tmpDir);
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nRules.\n');
-
- const written = installAgentDocs(tmpDir, {agent: 'claude'});
-
- expect(written).toEqual(['CLAUDE.md']);
- });
-
- it('respects --agent claude preset: creates .claude/CLAUDE.md when nothing exists', () => {
- setupCorePackage(tmpDir);
-
- const written = installAgentDocs(tmpDir, {agent: 'claude'});
-
- expect(written).toEqual(['.claude/CLAUDE.md']);
- expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);
- });
-
- it('respects --agent codex preset: creates AGENTS.md', () => {
- setupCorePackage(tmpDir);
-
- const written = installAgentDocs(tmpDir, {agent: 'codex'});
-
- expect(written).toEqual(['AGENTS.md']);
- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
- });
-
- it('respects --agent hermes preset: creates AGENTS.md', () => {
- setupCorePackage(tmpDir);
-
- const written = installAgentDocs(tmpDir, {agent: 'hermes'});
-
- expect(written).toEqual(['AGENTS.md']);
- const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
- expect(content).toContain('<!-- ASTRYX:START -->');
- expect(fs.existsSync(path.join(tmpDir, '.claude'))).toBe(false);
- });
-
- it('respects --agent muse preset: creates AGENTS.md', () => {
- setupCorePackage(tmpDir);
-
- const written = installAgentDocs(tmpDir, {agent: 'muse'});
-
- expect(written).toEqual(['AGENTS.md']);
- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
- });
-
- it('respects explicit --paths', () => {
- setupCorePackage(tmpDir);
-
- const written = installAgentDocs(tmpDir, {paths: ['custom/AGENT.md']});
-
- expect(written).toEqual(['custom/AGENT.md']);
- expect(fs.existsSync(path.join(tmpDir, 'custom', 'AGENT.md'))).toBe(true);
- });
-
- it('onlyReplace: skips files without XDS markers', () => {
- setupCorePackage(tmpDir);
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules only.\n');
-
- const written = installAgentDocs(tmpDir, {onlyReplace: true});
-
- expect(written).toEqual([]);
- const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(content).not.toContain('<!-- ASTRYX:START -->');
- expect(content).toBe('# Claude\n\nProject rules only.\n');
- });
-
- it('onlyReplace: updates files that have XDS markers', () => {
- setupCorePackage(tmpDir, '2.0.0');
- fs.writeFileSync(
- path.join(tmpDir, 'CLAUDE.md'),
- '# Claude\n\n<!-- XDS:START -->\nPLACEHOLDER_STALE_CONTENT\n<!-- XDS:END -->\n\nOther rules.\n',
- );
-
- const written = installAgentDocs(tmpDir, {onlyReplace: true});
-
- expect(written).toEqual(['CLAUDE.md']);
- const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
- expect(content).toContain('Astryx v2.0.0');
- expect(content).not.toContain('PLACEHOLDER_STALE_CONTENT');
- expect(content).toContain('Other rules.');
- });
-
- it('onlyReplace: does not create the default AGENTS.md when nothing exists', () => {
- setupCorePackage(tmpDir);
-
- const written = installAgentDocs(tmpDir, {onlyReplace: true});
-
- expect(written).toEqual([]);
- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
- expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
- });
-});
-
-describe('discoverAgentDocs', () => {
- it('finds AGENTS.md and CLAUDE.md at root', () => {
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');
-
- const found = discoverAgentDocs(tmpDir);
-
- expect(found).toContain('AGENTS.md');
- expect(found).toContain('CLAUDE.md');
- });
-
- it('finds .claude/CLAUDE.md', () => {
- fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
- fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '');
-
- const found = discoverAgentDocs(tmpDir);
-
- expect(found).toContain('.claude/CLAUDE.md');
- });
-
- it('returns empty when nothing exists', () => {
- expect(discoverAgentDocs(tmpDir)).toEqual([]);
- });
-});
-
-describe('resolveAgentPaths', () => {
- it('claude preset finds existing CLAUDE.md at root', () => {
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');
- const result = resolveAgentPaths(tmpDir, 'claude');
- expect(result).toEqual({inject: ['CLAUDE.md'], create: []});
- });
-
- it('claude preset falls back to .claude/CLAUDE.md', () => {
- const result = resolveAgentPaths(tmpDir, 'claude');
- expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});
- });
-
- it('all preset discovers existing files', () => {
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '');
- fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '');
- const result = resolveAgentPaths(tmpDir, 'all');
- expect(result.inject).toContain('AGENTS.md');
- expect(result.inject).toContain('CLAUDE.md');
- expect(result.create).toEqual([]);
- });
-
- it('all preset creates defaults when nothing exists', () => {
- const result = resolveAgentPaths(tmpDir, 'all');
- expect(result.inject).toEqual([]);
- expect(result.create).toContain('AGENTS.md');
- expect(result.create).toContain('.claude/CLAUDE.md');
- });
-
- it('hermes preset creates AGENTS.md when nothing exists', () => {
- const result = resolveAgentPaths(tmpDir, 'hermes');
- expect(result).toEqual({inject: [], create: ['AGENTS.md']});
- });
-
- it('hermes preset finds existing .hermes.md', () => {
- fs.writeFileSync(path.join(tmpDir, '.hermes.md'), '');
- const result = resolveAgentPaths(tmpDir, 'hermes');
- expect(result).toEqual({inject: ['.hermes.md'], create: []});
- });
-
- it('hermes preset finds existing HERMES.md when no .hermes.md', () => {
- fs.writeFileSync(path.join(tmpDir, 'HERMES.md'), '');
- const result = resolveAgentPaths(tmpDir, 'hermes');
- expect(result).toEqual({inject: ['HERMES.md'], create: []});
- });
-
- it('muse preset creates AGENTS.md when nothing exists', () => {
- const result = resolveAgentPaths(tmpDir, 'muse');
- expect(result).toEqual({inject: [], create: ['AGENTS.md']});
- });
-
- it('claude preset still creates .claude/CLAUDE.md when nothing exists (hermes is additive)', () => {
- const result = resolveAgentPaths(tmpDir, 'claude');
- expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});
- });
-});
-
-describe('parseBlockVersion', () => {
- it('reads the version from the header of a generated block', () => {
- expect(parseBlockVersion(generateCompressedIndex('1.2.3'))).toBe('1.2.3');
- });
-
- it('reads prerelease versions', () => {
- expect(parseBlockVersion('Astryx v1.2.3-beta.4 · 10 components')).toBe(
- '1.2.3-beta.4',
- );
- });
-
- it('returns null when no versioned header is present', () => {
- expect(parseBlockVersion('<!-- XDS:START -->\nold\n<!-- XDS:END -->')).toBeNull();
- expect(parseBlockVersion('')).toBeNull();
- expect(parseBlockVersion(undefined)).toBeNull();
- });
-});
-
-describe('inspectAgentDocs', () => {
- function writeBlock(rel, version) {
- const filePath = path.join(tmpDir, rel);
- fs.mkdirSync(path.dirname(filePath), {recursive: true});
- fs.writeFileSync(filePath, `# Doc\n\n${generateCompressedIndex(version)}\n`);
- }
-
- it('reports missing when no agent docs exist at all', () => {
- const res = inspectAgentDocs(tmpDir, '1.0.0');
- expect(res.status).toBe('missing');
- expect(res.files).toEqual([]);
- expect(res.staleFiles).toEqual([]);
- });
-
- it('reports missing when agent files exist but carry no Astryx marker', () => {
- fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nHand-written notes.\n');
- expect(inspectAgentDocs(tmpDir, '1.0.0').status).toBe('missing');
- });
-
- it('reports current when the only block matches the installed version', () => {
- writeBlock('AGENTS.md', '1.0.0');
- const res = inspectAgentDocs(tmpDir, '1.0.0');
- expect(res.status).toBe('current');
- expect(res.staleFiles).toEqual([]);
- expect(res.blockVersions).toEqual([]);
- });
-
- it.each([
- ['append addition', [], [{package: '@acme/a', append: ['added']}]],
- ['append removal', [{package: '@acme/a', append: ['removed']}], []],
- [
- 'integration reorder',
- [
- {package: '@acme/a', append: ['a']},
- {package: '@acme/b', append: ['b']},
- ],
- [
- {package: '@acme/b', append: ['b']},
- {package: '@acme/a', append: ['a']},
- ],
- ],
- [
- 'line content change',
- [{package: '@acme/a', append: ['old']}],
- [{package: '@acme/a', append: ['new']}],
- ],
- ])(
- 'reports stale at the same Core version after %s',
- (_label, current, expected) => {
- const actualBlock = generateCompressedIndex('1.0.0', {
- agentDocs: current,
- });
- fs.writeFileSync(
- path.join(tmpDir, 'AGENTS.md'),
- `# Doc\n\n${actualBlock}\n`,
- );
- const expectedBlock = generateCompressedIndex('1.0.0', {
- agentDocs: expected,
- });
-
- expect(inspectAgentDocs(tmpDir, '1.0.0', expectedBlock)).toMatchObject({
- status: 'stale',
- staleFiles: ['AGENTS.md'],
- });
- },
- );
-
- it('reports stale (with the old version) when the block is behind', () => {
- writeBlock('AGENTS.md', '1.0.0');
- const res = inspectAgentDocs(tmpDir, '2.0.0');
- expect(res.status).toBe('stale');
- expect(res.staleFiles).toEqual(['AGENTS.md']);
- expect(res.blockVersions).toEqual(['1.0.0']);
- expect(res.installedVersion).toBe('2.0.0');
- });
-
- it('treats a legacy XDS block as stale even with no parseable version', () => {
- fs.writeFileSync(
- path.join(tmpDir, 'CLAUDE.md'),
- '# Claude\n\n<!-- XDS:START -->\nlegacy index\n<!-- XDS:END -->\n',
- );
- const res = inspectAgentDocs(tmpDir, '1.0.0');
- expect(res.status).toBe('stale');
- expect(res.files[0].legacy).toBe(true);
- expect(res.blockVersions).toEqual([]);
- });
-
- it('is stale if ANY marked file is behind (mixed current + stale)', () => {
- writeBlock('AGENTS.md', '2.0.0');
- writeBlock('CLAUDE.md', '1.0.0');
- const res = inspectAgentDocs(tmpDir, '2.0.0');
- expect(res.status).toBe('stale');
- expect(res.staleFiles).toEqual(['CLAUDE.md']);
- });
-
- it('defaults the installed version to the core package when omitted', () => {
- const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
- fs.mkdirSync(coreDir, {recursive: true});
- fs.writeFileSync(path.join(coreDir, 'package.json'), JSON.stringify({version: '3.0.0'}));
- writeBlock('AGENTS.md', '3.0.0');
- const res = inspectAgentDocs(tmpDir);
- expect(res.installedVersion).toBe('3.0.0');
- expect(res.status).toBe('current');
- });
-});
-
-describe('injectXdsBlock / removeXdsBlock — malformed managed blocks (no user-content loss)', () => {
- const S = '<!-- ASTRYX:START -->';
- const E = '<!-- ASTRYX:END -->';
- const BLOCK = `${S}\nNEW\n${E}`;
-
- it('does not duplicate user content when END precedes START', () => {
- const f = path.join(tmpDir, 'a.md');
- fs.writeFileSync(f, `# Doc\nUSER-A\n${E}\nUSER-B\n${S}\nUSER-C\n`);
- removeXdsBlock(f);
- const c = fs.readFileSync(f, 'utf-8');
- expect((c.match(/USER-B/g) || []).length).toBeLessThanOrEqual(1);
- });
-
- it('refuses (throws) instead of orphaning a second block when duplicates exist', () => {
- const f = path.join(tmpDir, 'b.md');
- fs.writeFileSync(f, `# Doc\n${S}\nB1\n${E}\nMID\n${S}\nB2\n${E}\nTAIL\n`);
- expect(() => injectXdsBlock(f, BLOCK)).toThrow(/multiple|malformed/i);
- // file left untouched for the user to fix
- expect(fs.readFileSync(f, 'utf-8')).toContain('MID');
- expect(fs.readFileSync(f, 'utf-8')).toContain('TAIL');
- });
-
- it('refuses to append a second block when a START has no matching END', () => {
- const f = path.join(tmpDir, 'c.md');
- fs.writeFileSync(f, `# Doc\nUSER1\n${S}\nOLD (no end)\nUSER2\n`);
- expect(() => injectXdsBlock(f, BLOCK)).toThrow(/end marker|malformed|no matching/i);
- expect((fs.readFileSync(f, 'utf-8').match(/ASTRYX:START/g) || []).length).toBe(1);
- });
-
- it('replaces a single well-formed block idempotently, preserving surrounding content', () => {
- const f = path.join(tmpDir, 'ok.md');
- fs.writeFileSync(f, `# Doc\nUSER\n${S}\nOLD\n${E}\nTAIL\n`);
- injectXdsBlock(f, BLOCK);
- const c = fs.readFileSync(f, 'utf-8');
- expect((c.match(/ASTRYX:START/g) || []).length).toBe(1);
- expect(c).toContain('NEW');
- expect(c).toContain('USER');
- expect(c).toContain('TAIL');
- expect(c).not.toContain('OLD');
- });
-});
-
-describe('isAstryxInitialized — resilient to malformed markers (postinstall hot path)', () => {
- // isAstryxInitialized runs on every consumer `npm install` (via postinstall).
- // It must never throw — even on a half-written or garbage-marker file — so it
- // uses a plain `.includes(MARKER_START)`, never the strict findManagedBlock.
- const START = '<!-- ASTRYX:START -->';
- const END = '<!-- ASTRYX:END -->';
-
- it('returns true (never throws) on duplicate START markers', () => {
- fs.writeFileSync(
- path.join(tmpDir, 'AGENTS.md'),
- `${START}\na\n${START}\nb\n${END}\n`,
- );
- expect(() => isAstryxInitialized(tmpDir)).not.toThrow();
- expect(isAstryxInitialized(tmpDir)).toBe(true);
- });
-
- it('returns true on an END-before-START file without throwing', () => {
- fs.writeFileSync(
- path.join(tmpDir, 'AGENTS.md'),
- `${END}\nuser\n${START}\nblock\n`,
- );
- expect(() => isAstryxInitialized(tmpDir)).not.toThrow();
- expect(isAstryxInitialized(tmpDir)).toBe(true);
- });
-
- it('returns true on a START with no END (half-written block)', () => {
- fs.writeFileSync(
- path.join(tmpDir, 'AGENTS.md'),
- `# Doc\nuser\n${START}\ntruncated block, no end\n`,
- );
- expect(() => isAstryxInitialized(tmpDir)).not.toThrow();
- expect(isAstryxInitialized(tmpDir)).toBe(true);
- });
-
- it('returns false for a directory with no agent docs', () => {
- expect(isAstryxInitialized(tmpDir)).toBe(false);
- });
-
- it('returns false for a nonexistent directory', () => {
- expect(isAstryxInitialized(path.join(tmpDir, 'does-not-exist'))).toBe(false);
- });
-});
diff --git a/packages/cli/foundation/discovery/authoring-self-docs.test.mjs b/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
index 091f68e1e4..4e6c5860ad 100644
--- a/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
+++ b/packages/cli/foundation/discovery/authoring-self-docs.test.mjs
@@ -63,7 +63,9 @@ describe('authoring self-docs', () => {
describe('what the authoring docs say about the docs tree', () => {
it('marks exactly the fields the docs tree does not read yet', () => {
const notReadYet = graphFieldsDoc.fields
- .filter(field => /Not read yet/.test(field.description))
+ .filter(field =>
+ /^Reserved: .*Nothing reads it today/.test(field.description),
+ )
.map(field => field.name);
// The tree reads `placement` for every guide (spec:AST-046); the other
// graph fields are still refused by every topic reader.
@@ -79,7 +81,9 @@ describe('what the authoring docs say about the docs tree', () => {
expect(placement.description).toMatch(
/Read for every guide, the CLI's and each integration's/,
);
- expect(graphFieldsDoc.description).toMatch(/not built yet/);
+ expect(graphFieldsDoc.description).toMatch(
+ /Nothing reads `aliases` or `audience` today/,
+ );
});
it('keeps graph blocks behind the separate GraphContentBlock type, and a section takes a reference block', () => {
diff --git a/packages/cli/foundation/discovery/cli-self-docs.mjs b/packages/cli/foundation/discovery/cli-self-docs.mjs
index 803b71a220..c56d296b7e 100644
--- a/packages/cli/foundation/discovery/cli-self-docs.mjs
+++ b/packages/cli/foundation/discovery/cli-self-docs.mjs
@@ -315,12 +315,20 @@ function functionSection(fn, index) {
}
const params = fn.params ?? [];
if (params.length > 0) {
+ // A Default column only when some parameter declares a default, so a
+ // function with none keeps a three-column table.
+ const defaults = params.some(
+ (/** @type {any} */ p) => typeof p.default === 'string' && p.default !== '',
+ );
content.push({
type: 'table',
- headers: ['Parameter', 'Type', 'Description'],
+ headers: defaults
+ ? ['Parameter', 'Type', 'Default', 'Description']
+ : ['Parameter', 'Type', 'Description'],
rows: params.map((/** @type {any} */ p) => [
- `\`${p.name}\``,
+ `\`${p.name}\`${p.required ? ' (required)' : ''}`,
`\`${p.type ?? ''}\``,
+ ...(defaults ? [p.default ?? ''] : []),
p.description ?? '',
]),
});
@@ -405,6 +413,12 @@ export function cliDocSection(doc, index) {
if (doc.type === 'command') return commandSection(doc, index);
if (doc.type === 'function') return functionSection(doc, index);
if (doc.type === 'enum') return enumSection(doc);
+ if (doc.type === 'namespace')
+ return {
+ id: routeSegment(doc.name),
+ title: doc.title,
+ content: doc.blocks ?? [],
+ };
return {...selfDocSection(doc), id: routeSegment(doc.name)};
}
diff --git a/packages/cli/foundation/discovery/cli-self-docs.test.mjs b/packages/cli/foundation/discovery/cli-self-docs.test.mjs
index b65c0138d4..f1d851bf7f 100644
--- a/packages/cli/foundation/discovery/cli-self-docs.test.mjs
+++ b/packages/cli/foundation/discovery/cli-self-docs.test.mjs
@@ -315,6 +315,26 @@ describe('cliDocSection', () => {
]);
});
+ it('marks required parameters and adds a Default column when a parameter has a default', () => {
+ const beta = fn('beta', {
+ params: [
+ {name: 'slug', type: 'string', description: 'The slug.', required: true},
+ {name: 'options.limit', type: 'number', description: 'How many.', default: '20'},
+ ],
+ });
+ const table = cliDocSection(beta, indexOf([beta])).content.find(
+ (/** @type {any} */ block) => block.type === 'table',
+ );
+ expect(table).toEqual({
+ type: 'table',
+ headers: ['Parameter', 'Type', 'Default', 'Description'],
+ rows: [
+ ['`slug` (required)', '`string`', '', 'The slug.'],
+ ['`options.limit`', '`number`', '20', 'How many.'],
+ ],
+ });
+ });
+
it('renders an API function, an enum, and a schema', () => {
const alpha = fn('alpha', {
description: 'Longer.',
diff --git a/packages/cli/foundation/discovery/docs-discovery.mjs b/packages/cli/foundation/discovery/docs-discovery.mjs
index b3902c0464..597dd85542 100644
--- a/packages/cli/foundation/discovery/docs-discovery.mjs
+++ b/packages/cli/foundation/discovery/docs-discovery.mjs
@@ -626,7 +626,11 @@ function findMergeTarget(sections, section) {
const sameTitle = sections.findIndex(
candidate => sourceTitle(candidate) === title,
);
- return sameTitle;
+ if (sameTitle !== -1) return sameTitle;
+ // A base section retitled later keeps its old key as its `id`, so an
+ // extension that still names it by the old title finds it by that id. A
+ // title variant of a section with no id stays a separate section.
+ return sections.findIndex(candidate => candidate.id === key);
}
/**
diff --git a/packages/cli/foundation/discovery/docs-discovery.test.mjs b/packages/cli/foundation/discovery/docs-discovery.test.mjs
index 5fe4efc609..a746c5ecf9 100644
--- a/packages/cli/foundation/discovery/docs-discovery.test.mjs
+++ b/packages/cli/foundation/discovery/docs-discovery.test.mjs
@@ -509,6 +509,27 @@ describe('mergeTopic', () => {
expect(base.sections[0].content[0].text).toBe('npm i');
});
+ it('finds a retitled base section by the key its old title derives', () => {
+ // A base section retitled later keeps its old key as its `id`; an
+ // extension that still names it by the old title replaces it.
+ const merged = mergeTopic(
+ {
+ ...base,
+ sections: [
+ {id: 'quick-start', title: 'Wrap your app in a theme', content: []},
+ {id: 'tokens', title: 'Tokens', content: []},
+ ],
+ },
+ {sections: [{title: 'Quick Start', content: []}]},
+ );
+ expect(merged.sections.map(section => [section.id, section.title])).toEqual(
+ [
+ ['quick-start', 'Quick Start'],
+ ['tokens', 'Tokens'],
+ ],
+ );
+ });
+
it('replaces a section by stable ID even when its title changes', () => {
const merged = mergeTopic(
{
diff --git a/packages/cli/foundation/discovery/docs-section-key.mjs b/packages/cli/foundation/discovery/docs-section-key.mjs
index 7deff958c8..77a396a58a 100644
--- a/packages/cli/foundation/discovery/docs-section-key.mjs
+++ b/packages/cli/foundation/discovery/docs-section-key.mjs
@@ -95,7 +95,7 @@ function legacyTitleMatchIndex(sections, query) {
/**
* A name as a docs-tree route segment: lowercase words joined by hyphens, so
- * `integrationPackCheck` and `integration pack` both read naturally.
+ * `integrationPackCheck` and `integration verify` both read naturally.
* @param {string} name
* @returns {string}
*/
diff --git a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
index bd76c1bfab..c0a8863326 100644
--- a/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
+++ b/packages/cli/foundation/doc-compiler/doc-loads.test.mjs
@@ -53,8 +53,8 @@ const RUNNERS = {
sites: ['import(node:child_process)', 'worker_threads.Worker'],
},
'api/integration/pack-check.mjs': {
- runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published',
- sites: ['child_process.spawnSync ×3'],
+ runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published, and the package\'s doc modules, to see which need a newer CLI',
+ sites: ['child_process.spawnSync ×3', 'loadTopicModule'],
},
'api/swizzle/_github.mjs': {
runs: '`gh auth status`, to check the GitHub CLI is signed in',
@@ -188,6 +188,7 @@ const RUNNERS = {
'import ../../../api/integration/integrationPackCheck.doc.mjs',
'import ./integration-add.doc.mjs',
'import ./integration-pack.doc.mjs',
+ 'import ./integration-verify.doc.mjs',
'import ./integration.doc.mjs',
],
},
diff --git a/packages/cli/foundation/doc-compiler/tree.mjs b/packages/cli/foundation/doc-compiler/tree.mjs
index 72fdfbd339..c30c9ba570 100644
--- a/packages/cli/foundation/doc-compiler/tree.mjs
+++ b/packages/cli/foundation/doc-compiler/tree.mjs
@@ -58,7 +58,7 @@ export const KIND_GROUPS = Object.freeze({
schema: {
segment: 'schemas',
title: 'Schemas',
- summary: 'Every shape the CLI reads or returns, field by field.',
+ summary: 'Data shapes, field by field.',
},
enum: {
segment: 'enums',
@@ -140,6 +140,7 @@ export const UNORGANIZED = 'unorganized';
* @property {string} name
* @property {string} title
* @property {string} summary
+ * @property {string[]} [keywords] an authored namespace's search keywords
* @property {string | null} parent the parent's route; null at the top
* @property {string | null} slot the parent slot this node sits in
* @property {number | null} order
@@ -420,10 +421,14 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
name: input.doc.name,
title: input.doc.title,
summary: input.doc.summary,
+ ...(Array.isArray(input.doc.keywords)
+ ? {keywords: input.doc.keywords}
+ : {}),
parent: parentRoute,
slot: home?.slot ?? null,
order: home?.order ?? null,
generated: false,
+ ref: {selfDoc: input.doc},
slots: Object.entries(input.doc.slots).map(([name, slot]) => ({
name,
title: slot.title,
diff --git a/packages/cli/foundation/doc-compiler/tree.test.mjs b/packages/cli/foundation/doc-compiler/tree.test.mjs
deleted file mode 100644
index 64e0bfe2df..0000000000
--- a/packages/cli/foundation/doc-compiler/tree.test.mjs
+++ /dev/null
@@ -1,606 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Tests for the docs tree (spec:AST-046): one home per doc, decided by
- * explicit placement, then one adoption rule; every way a placement can fail;
- * generated kind levels; deterministic order; and the CLI's own tree.
- *
- * @input Plain fixture inputs for the pure builder, and this package's own
- * tree files and typed docs for the loader.
- * @output Assertions on routes, parents, slots, children order, and
- * diagnostics.
- * @position packages/cli/foundation/doc-compiler — tests for tree.mjs.
- */
-
-import {describe, expect, it} from 'vitest';
-import {
- buildDocsTree,
- KIND_GROUPS,
- loadDocsTree,
- loadTreeInputs,
- routeSegment,
-} from './tree.mjs';
-import {loadCliSelfDocs} from '../discovery/cli-self-docs.mjs';
-import * as api from '../../api/index.mjs';
-import {createDocId} from '../identity/provider-identity.mjs';
-import {CLI_PROVIDER_ID} from '../identity/providers.mjs';
-
-const SLOW = 60_000;
-const P = '@acme/kit';
-
-/**
- * @param {string} name
- * @param {object} [extra]
- * @returns {import('./tree.mjs').TreeNamespaceInput}
- */
-const ns = (name, extra = {}) => ({
- provider: P,
- providerId: P,
- source: `${P}/tree/${name}.doc.mjs`,
- doc: /** @type {any} */ ({
- type: 'namespace',
- name,
- title: name.toUpperCase(),
- summary: `The ${name} level.`,
- slots: {
- items: {title: 'Items', accepts: {kinds: ['generic', 'namespace']}},
- },
- ...extra,
- }),
-});
-
-/**
- * @param {string} name
- * @param {object} [extra]
- * @returns {import('./tree.mjs').TreeDocInput}
- */
-const guide = (name, extra = {}) => ({
- provider: P,
- providerId: P,
- source: `${P}/tree/${name}.doc.mjs`,
- kind: 'generic',
- name,
- title: `Guide ${name}`,
- summary: `About ${name}.`,
- group: null,
- placement: undefined,
- ...extra,
-});
-
-/**
- * @param {string} kind
- * @param {string} name
- * @param {string} group
- * @returns {import('./tree.mjs').TreeDocInput}
- */
-const typed = (kind, name, group) => ({
- provider: P,
- providerId: P,
- source: `${P}/api/${name}.doc.mjs`,
- kind,
- name,
- title: name,
- summary: `The ${name} ${kind}.`,
- group,
- placement: undefined,
-});
-
-/** @param {ReturnType<typeof buildDocsTree>} tree */
-const routes = tree => [...tree.nodes.keys()];
-
-/** @param {ReturnType<typeof buildDocsTree>} tree */
-const problems = tree => tree.diagnostics.map(d => [d.code, d.message]);
-
-describe('buildDocsTree', () => {
-
- it('withdraws a namespace placed in a withdrawn namespace, and what is placed in it', () => {
- const CLI = '@astryxdesign/cli';
- const tree = buildDocsTree({
- namespaces: [
- ns('tokens'),
- ns('alpha', {placement: {parent: 'namespace:tokens', slot: 'items'}}),
- ],
- docs: [guide('deep', {placement: {parent: 'namespace:alpha', slot: 'items'}})],
- topics: [
- {provider: CLI, providerId: CLI, name: 'tokens', title: 'Tokens', summary: 'Tokens.', source: `${CLI}/tokens.doc.mjs`},
- ],
- });
- expect(tree.get('tokens')?.provider).toBe(CLI);
- expect(routes(tree).filter(route => route.startsWith('tokens/'))).toEqual([]);
- expect(problems(tree)).toEqual(
- expect.arrayContaining([
- ['duplicate_route', expect.stringContaining('takes the route "tokens"')],
- ['invalid_placement', 'Namespace "alpha" has no route: the namespace it is placed in was withdrawn.'],
- ['invalid_placement', expect.stringContaining('names a namespace that has no route')],
- ]),
- );
- });
-
- it("keeps a name a topic answers to through replaces as that topic's route", () => {
- const tree = buildDocsTree({
- namespaces: [ns('tokens')],
- docs: [],
- topics: [
- {provider: '@acme/a', providerId: '@acme/a', name: 'acme-tokens', title: 'Acme tokens', summary: 'Acme tokens.', source: '@acme/a:acme-tokens', aliases: ['tokens', 'old-tokens']},
- ],
- });
- expect(tree.get('tokens')).toBeUndefined();
- expect(tree.get('acme-tokens')?.provider).toBe('@acme/a');
- expect(problems(tree)).toEqual([
- ['duplicate_route', expect.stringContaining('takes the route "tokens", which the topic "acme-tokens" also answers to')],
- ]);
- // Every name it answers to is reserved, not only the last one it replaced.
- const older = buildDocsTree({
- namespaces: [ns('old-tokens')],
- docs: [],
- topics: [
- {provider: '@acme/a', providerId: '@acme/a', name: 'acme-tokens', title: 'Acme tokens', summary: 'Acme tokens.', source: '@acme/a:acme-tokens', aliases: ['tokens', 'old-tokens']},
- ],
- });
- expect(older.get('old-tokens')).toBeUndefined();
- });
-
- it("keeps the CLI's own routes from an integration, compared without case", () => {
- const CLI = '@astryxdesign/cli';
- /** @param {string} name @param {string} [provider] */
- const topic = (name, provider = P) => ({
- provider,
- providerId: provider,
- name,
- title: name,
- summary: `The ${name} topic.`,
- source: `${provider}/${name}.doc.mjs`,
- });
- const cliNs = {...ns('cli'), provider: CLI, providerId: CLI, source: `${CLI}/tree/cli.doc.mjs`};
- // An integration's topics named `CLI` and `UNORGANIZED` claim the CLI's
- // namespace and the generated level; both are withdrawn.
- const tree = buildDocsTree({
- namespaces: [cliNs],
- docs: [],
- topics: [topic('theme', CLI), topic('CLI'), topic('UNORGANIZED')],
- });
- expect(tree.get('cli')?.provider).toBe(CLI);
- expect(tree.get('unorganized')?.provider).toBe(CLI);
- expect(routes(tree)).not.toContain('CLI');
- expect(routes(tree)).not.toContain('UNORGANIZED');
- expect(problems(tree)).toEqual(
- expect.arrayContaining([
- ['duplicate_route', expect.stringContaining('both have the route "CLI"')],
- ['duplicate_route', expect.stringContaining('takes the route "UNORGANIZED", which the CLI\'s own docs keep')],
- ]),
- );
- expect(tree.getFolded('THEME')?.provider).toBe(CLI);
- // A CLI topic whose own name has capitals keeps its route against a
- // lowercase namespace, although namespaces go into the tree first.
- const caps = buildDocsTree({namespaces: [ns('tokens')], docs: [], topics: [topic('Tokens', CLI)]});
- expect(caps.get('Tokens')?.provider).toBe(CLI);
- expect(caps.get('tokens')).toBeUndefined();
- expect(problems(caps)).toEqual([
- ['duplicate_route', expect.stringContaining('takes the route "tokens", which the CLI\'s own docs keep')],
- ]);
- });
- it('builds three authored levels and a guide below them', () => {
- const tree = buildDocsTree({
- namespaces: [
- ns('top'),
- ns('middle', {placement: {parent: 'namespace:top', slot: 'items'}}),
- ns('bottom', {placement: {parent: 'namespace:middle'}}),
- ],
- docs: [
- guide('deep', {placement: {parent: 'namespace:bottom', order: 1}}),
- ],
- });
- expect(problems(tree)).toEqual([]);
- expect(routes(tree)).toEqual([
- 'top',
- 'top/middle',
- 'top/middle/bottom',
- 'top/middle/bottom/deep',
- ]);
- const deep = /** @type {any} */ (tree.get('top/middle/bottom/deep'));
- expect(deep).toMatchObject({
- id: 'astryx:artifact:v1/%40acme%2Fkit/generic/deep',
- parent: 'top/middle/bottom',
- slot: 'items',
- order: 1,
- generated: false,
- });
- expect(tree.ancestors(deep).map(node => node.route)).toEqual([
- 'top',
- 'top/middle',
- 'top/middle/bottom',
- ]);
- expect(tree.roots().map(node => node.route)).toEqual(['top']);
- });
-
- it('adopts typed docs by group, with one generated level per kind', () => {
- const tree = buildDocsTree({
- namespaces: [
- ns('api', {
- slots: {kinds: {title: 'Reference', accepts: {kinds: ['namespace']}}},
- adopts: [
- {
- source: {group: 'kit/api', kinds: ['function', 'enum']},
- into: 'kinds',
- groupBy: 'kind',
- },
- ],
- }),
- ],
- docs: [
- typed('enum', 'errorCodes', 'kit/api'),
- typed('function', 'search', 'kit/api'),
- typed('function', 'build', 'kit/api'),
- typed('schema', 'config', 'kit/api'),
- typed('function', 'other', 'kit/elsewhere'),
- ],
- });
- expect(problems(tree)).toEqual([]);
- expect(routes(tree)).toEqual([
- 'api',
- 'api/enums',
- 'api/enums/error-codes',
- 'api/functions',
- 'api/functions/build',
- 'api/functions/search',
- ]);
- const functions = /** @type {any} */ (tree.get('api/functions'));
- expect(functions).toMatchObject({
- id: null,
- kind: 'namespace',
- title: KIND_GROUPS.function.title,
- generated: true,
- parent: 'api',
- slot: 'kinds',
- });
- // Kind levels follow the rule's kind order; docs inside sort by title.
- expect(tree.get('api')?.slots[0].children).toEqual([
- 'api/functions',
- 'api/enums',
- ]);
- expect(functions.slots[0].children).toEqual([
- 'api/functions/build',
- 'api/functions/search',
- ]);
- });
-
- it('adopts without grouping straight into the named slot', () => {
- const tree = buildDocsTree({
- namespaces: [
- ns('commands', {
- slots: {all: {title: 'All', accepts: {kinds: ['command']}}},
- adopts: [{source: {group: 'kit/commands'}, into: 'all'}],
- }),
- ],
- docs: [typed('command', 'theme add', 'kit/commands')],
- });
- expect(routes(tree)).toEqual(['commands', 'commands/theme-add']);
- expect(tree.get('commands')?.slots[0].children).toEqual([
- 'commands/theme-add',
- ]);
- });
-
- it('prefers explicit placement over adoption, and never falls back', () => {
- const namespaces = [
- ns('guides'),
- ns('api', {
- slots: {all: {title: 'All', accepts: {kinds: ['generic']}}},
- adopts: [{source: {group: 'kit/api'}, into: 'all'}],
- }),
- ];
- const placed = buildDocsTree({
- namespaces,
- docs: [
- guide('intro', {
- group: 'kit/api',
- placement: {parent: 'namespace:guides'},
- }),
- ],
- });
- expect(routes(placed)).toContain('guides/intro');
- expect(routes(placed)).not.toContain('api/intro');
-
- const broken = buildDocsTree({
- namespaces,
- docs: [
- guide('intro', {
- group: 'kit/api',
- placement: {parent: 'namespace:nope'},
- }),
- ],
- });
- expect(routes(broken).some(route => route.endsWith('/intro'))).toBe(false);
- expect(problems(broken)).toEqual([
- [
- 'invalid_placement',
- 'placement.parent "namespace:nope" names no namespace; @acme/kit declares "api", "guides".',
- ],
- ]);
- });
-
- it('reports every way a placement can fail', () => {
- const tree = buildDocsTree({
- namespaces: [
- ns('home', {
- slots: {
- one: {title: 'One', accepts: {kinds: ['generic']}},
- two: {title: 'Two', accepts: {kinds: ['command']}},
- },
- }),
- ],
- docs: [
- guide('no-slot', {placement: {parent: 'namespace:home'}}),
- guide('bad-slot', {
- placement: {parent: 'namespace:home', slot: 'three'},
- }),
- guide('wrong-kind', {
- placement: {parent: 'namespace:home', slot: 'two'},
- }),
- guide('other-package', {
- placement: {parent: '@other/pkg/namespace/home'},
- }),
- guide('not-a-ref', {placement: {parent: 'home'}}),
- ],
- });
- expect(routes(tree)).toEqual(['home']);
- expect(
- problems(tree)
- .map(([, message]) => message)
- .sort(),
- ).toEqual(
- [
- 'placement names no slot, and namespace "home" has 2 (one, two). Name one with placement.slot.',
- 'placement.slot "three" is not a slot of namespace "home"; it declares one, two.',
- 'slot "two" of namespace "home" does not accept generic docs; it accepts command.',
- 'placement.parent "@other/pkg/namespace/home" belongs to @other/pkg. A doc can only be placed in a namespace of its own package (@acme/kit).',
- 'placement.parent "home" is not a namespace reference. Write "namespace:<name>".',
- ].sort(),
- );
- expect(tree.diagnostics.every(d => d.code === 'invalid_placement')).toBe(
- true,
- );
- expect(tree.diagnostics.every(d => d.severity === 'error')).toBe(true);
- });
-
- it('fails a doc two namespaces adopt, naming both', () => {
- const rule = {source: {group: 'kit/api'}, into: 'items'};
- const tree = buildDocsTree({
- namespaces: [ns('a', {adopts: [rule]}), ns('b', {adopts: [rule]})],
- docs: [guide('shared', {group: 'kit/api'})],
- });
- expect(routes(tree)).toEqual(['a', 'b']);
- expect(problems(tree)).toEqual([
- [
- 'overlapping_adoption',
- '@acme/kit/generic/shared is adopted by "a" and "b"; exactly one namespace may adopt a doc.',
- ],
- ]);
- });
-
- it('fails two docs at one route, keeping the first by identity', () => {
- const tree = buildDocsTree({
- namespaces: [ns('home')],
- docs: [
- guide('fooBar', {placement: {parent: 'namespace:home'}}),
- guide('foo_bar', {placement: {parent: 'namespace:home'}}),
- ],
- });
- expect(routes(tree)).toEqual(['home', 'home/foo-bar']);
- expect(tree.get('home/foo-bar')?.id).toBe(
- 'astryx:artifact:v1/%40acme%2Fkit/generic/fooBar',
- );
- expect(problems(tree)).toEqual([
- [
- 'duplicate_route',
- 'astryx:artifact:v1/%40acme%2Fkit/generic/foo_bar and astryx:artifact:v1/%40acme%2Fkit/generic/fooBar both have the route "home/foo-bar". Rename or move one of them.',
- ],
- ]);
- });
-
- it('fails a namespace cycle and everything under it', () => {
- const tree = buildDocsTree({
- namespaces: [
- ns('a', {placement: {parent: 'namespace:b'}}),
- ns('b', {placement: {parent: 'namespace:a'}}),
- ],
- docs: [guide('lost', {placement: {parent: 'namespace:a'}})],
- });
- expect(routes(tree)).toEqual([]);
- expect(problems(tree).map(([code]) => code)).toEqual([
- 'invalid_placement',
- 'invalid_placement',
- 'invalid_placement',
- ]);
- });
-
- it('fails a duplicate or unsafe namespace name', () => {
- const tree = buildDocsTree({
- namespaces: [
- ns('twice'),
- {...ns('twice'), source: `${P}/other.doc.mjs`},
- ns('Bad Name'),
- ],
- docs: [],
- });
- expect(routes(tree)).toEqual(['twice']);
- expect(tree.diagnostics.map(d => d.code)).toEqual([
- 'invalid_namespace',
- 'invalid_namespace',
- ]);
- });
-
- it('leaves a doc with no placement and no adoption out, in phase 1', () => {
- const tree = buildDocsTree({
- namespaces: [ns('home')],
- docs: [guide('loose'), typed('function', 'free', 'kit/nowhere')],
- });
- expect(routes(tree)).toEqual(['home']);
- expect(tree.diagnostics).toEqual([]);
- });
-
- it('is the same tree whatever order its inputs arrive in', () => {
- const namespaces = [
- ns('top'),
- ns('child', {placement: {parent: 'namespace:top'}}),
- ];
- const docs = [
- guide('b', {placement: {parent: 'namespace:child'}}),
- guide('a', {placement: {parent: 'namespace:child'}}),
- ];
- const one = buildDocsTree({namespaces, docs});
- const two = buildDocsTree({
- namespaces: [...namespaces].reverse(),
- docs: [...docs].reverse(),
- });
- expect(JSON.stringify([...two.nodes])).toBe(JSON.stringify([...one.nodes]));
- });
-
- it('orders children by order, then title', () => {
- const tree = buildDocsTree({
- namespaces: [ns('home')],
- docs: [
- guide('z', {
- title: 'Zed',
- placement: {parent: 'namespace:home', order: 1},
- }),
- guide('b', {title: 'Beta', placement: {parent: 'namespace:home'}}),
- guide('a', {title: 'Alpha', placement: {parent: 'namespace:home'}}),
- ],
- });
- expect(tree.get('home')?.slots[0].children).toEqual([
- 'home/z',
- 'home/a',
- 'home/b',
- ]);
- });
-});
-
-describe('routeSegment', () => {
- it('joins lowercase words with hyphens, whatever the name looks like', () => {
- expect(routeSegment('integrationPackCheck')).toBe('integration-pack-check');
- expect(routeSegment('doctor integration validate')).toBe(
- 'doctor-integration-validate',
- );
- expect(routeSegment('error-codes')).toBe('error-codes');
- expect(routeSegment('isError')).toBe('is-error');
- expect(routeSegment('!!')).toBe('');
- });
-});
-
-describe("the CLI's own docs tree", () => {
- it(
- 'builds with no diagnostic, rooted at cli',
- async () => {
- const tree = await loadDocsTree({fresh: true});
- expect(tree.diagnostics).toEqual([]);
- expect(tree.roots().map(node => node.route)).toEqual(['cli']);
- expect(
- tree.get('cli')?.slots.map(slot => [slot.name, slot.children]),
- ).toEqual([
- [
- 'guides',
- [
- 'cli/component-lookups',
- 'cli/integrations',
- 'cli/writing-docs',
- ],
- ],
- ['reference', ['cli/commands', 'cli/api']],
- ]);
- expect(tree.get('cli/api')?.slots[0].children).toEqual([
- 'cli/api/functions',
- 'cli/api/schemas',
- 'cli/api/enums',
- ]);
- },
- SLOW,
- );
-
- it(
- 'gives every CLI typed doc in a cli group one route, by its kind',
- async () => {
- const tree = await loadDocsTree();
- const {loaded} = await loadCliSelfDocs();
- const inTree = loaded.filter(({doc}) =>
- String(doc.namespace).startsWith('cli/'),
- );
- expect(inTree.length).toBeGreaterThan(0);
- const expected = inTree.map(({doc}) =>
- doc.type === 'command'
- ? `cli/commands/${routeSegment(doc.name)}`
- : `cli/api/${KIND_GROUPS[doc.type].segment}/${routeSegment(doc.name)}`,
- );
- expect(expected.filter(route => tree.get(route) == null)).toEqual([]);
- // A doc in the authoring group stays a section of `astryx docs authoring`.
- const authoring = loaded.filter(({doc}) => doc.namespace === 'authoring');
- expect(authoring.length).toBeGreaterThan(0);
- const ids = new Set([...tree.nodes.values()].map(node => node.id));
- expect(
- authoring.filter(({doc}) =>
- ids.has(createDocId(CLI_PROVIDER_ID, doc.type, doc.name)),
- ),
- ).toEqual([]);
- },
- SLOW,
- );
-
- it(
- 'gives every function @astryxdesign/cli/api exports a route',
- async () => {
- const tree = await loadDocsTree();
- const exported = Object.entries(api)
- .filter(
- ([, value]) =>
- typeof value === 'function' &&
- Object.getOwnPropertyDescriptor(value, 'prototype')?.writable !==
- false,
- )
- .map(([name]) => `cli/api/functions/${routeSegment(name)}`);
- expect(exported.length).toBeGreaterThan(0);
- expect(exported.filter(route => tree.get(route) == null)).toEqual([]);
- },
- SLOW,
- );
-
- it(
- 'reads only namespace and generic docs from the tree directory, each named after its file',
- async () => {
- const inputs = await loadTreeInputs({selfDocs: false});
- expect(inputs.diagnostics).toEqual([]);
- expect(inputs.namespaces.map(n => n.doc.name).sort()).toEqual([
- 'api',
- 'cli',
- 'commands',
- ]);
- expect(inputs.docs.map(d => [d.name, d.placement?.parent])).toEqual([
- ['component-lookups', 'namespace:cli'],
- ['integrations', 'namespace:cli'],
- ['writing-docs', 'namespace:cli'],
- ]);
- },
- SLOW,
- );
-});
-
-describe('doc identity', () => {
- it('builds each id from the provider id, never the package name', () => {
- const provider = '@acme/tree-provider';
- const tree = buildDocsTree({
- namespaces: [{...ns('home'), providerId: provider}],
- docs: [
- {
- ...guide('intro', {placement: {parent: 'namespace:home'}}),
- providerId: provider,
- },
- ],
- });
- expect(problems(tree)).toEqual([]);
- expect(tree.get('home')?.id).toBe(
- 'astryx:artifact:v1/%40acme%2Ftree-provider/namespace/home',
- );
- expect(tree.get('home/intro')).toMatchObject({
- id: 'astryx:artifact:v1/%40acme%2Ftree-provider/generic/intro',
- provider: P,
- });
- });
-});
diff --git a/packages/cli/foundation/integrations/cli-requirement.mjs b/packages/cli/foundation/integrations/cli-requirement.mjs
index 94408ab677..b70ac949dd 100644
--- a/packages/cli/foundation/integrations/cli-requirement.mjs
+++ b/packages/cli/foundation/integrations/cli-requirement.mjs
@@ -6,8 +6,9 @@
* @input A package.json object.
* @output Whether its `peerDependencies` range for `@astryxdesign/cli` admits
* only CLIs that read namespace docs, and the package.json that declares it.
- * @position foundation/integrations; read by `integration add doc --parent`,
- * which declares the peer, and `integration pack --check`, which requires it.
+ * @position foundation/integrations; read by `integration add doc --parent`
+ * and `integration add theme`, which declare the peer, and
+ * `integration verify`, which requires it.
*/
import {semverCompare} from '../env/semver.mjs';
@@ -16,10 +17,12 @@ export const CLI_PACKAGE = '@astryxdesign/cli';
/**
* The first CLI release that reads an integration's docs tree (namespace docs
- * and placed guides) and its templates' `replaces`. A release before it can
- * hide every doc topic a package with a namespace doc or a placed guide
- * ships, with no warning, and it rejects `replaces` and withholds the
- * package's templates and doc topics.
+ * and placed guides), its templates' `replaces`, and its typed theme
+ * descriptors. A release before it can hide every doc topic a package with a
+ * namespace doc or a placed guide ships, with no warning; it rejects
+ * `replaces`, drops that template, and hides the package's doc topics; and it
+ * rejects a themes root without the `manifest.json` catalog the CLI no longer
+ * writes, withholding the package's themes and doc topics.
*/
export const DOCS_TREE_CLI = '0.7.0';
@@ -92,11 +95,11 @@ function cliRangeProblem(pkg, feature, loss) {
const range = pkg?.peerDependencies?.[CLI_PACKAGE];
const fix = `"${CLI_PACKAGE}": ">=${DOCS_TREE_CLI}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
if (typeof range !== 'string') {
- return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A CLI older than ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
+ return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A stable CLI before ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
}
const lowest = lowestAdmitted(range);
if (lowest == null || semverCompare(lowest, DOCS_TREE_CLI) < 0) {
- return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a CLI older than ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
+ return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a stable CLI before ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
}
return null;
}
@@ -119,8 +122,8 @@ export function docsTreeCliProblem(pkg) {
}
/**
- * Why a package with a template that sets `replaces` would lose its templates
- * and doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * Why a package with a template that sets `replaces` would lose templates and
+ * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
* range admits only CLIs that read the field.
* @param {any} pkg package.json
* @returns {string | null}
@@ -129,7 +132,39 @@ export function replacesCliProblem(pkg) {
return cliRangeProblem(
pkg,
'has a template that sets `replaces`',
- "rejects the field, and withholds the package's templates and doc topics",
+ "rejects the field, drops that template, and hides the package's doc topics",
+ );
+}
+
+/**
+ * Why a package with a doc section that sets `id` would lose its doc topics on
+ * an older CLI, or null when its declared CLI range admits only CLIs that read
+ * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
+ * the package ships.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg) {
+ return cliRangeProblem(
+ pkg,
+ 'has a doc section that sets `id`',
+ 'rejects the field, and can hide every doc topic the package ships',
+ );
+}
+
+/**
+ * Why a package that ships a theme would lose its themes and doc topics on an
+ * older CLI, or null when its declared CLI range admits only CLIs that read
+ * typed theme descriptors. Published 0.6.3 rejects a themes root with no
+ * `manifest.json` catalog, which `integration add theme` no longer writes.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg) {
+ return cliRangeProblem(
+ pkg,
+ 'ships a theme',
+ "cannot read typed theme descriptors, and can drop the package's themes and hide its doc topics",
);
}
diff --git a/packages/cli/foundation/integrations/cli-requirement.test.mjs b/packages/cli/foundation/integrations/cli-requirement.test.mjs
index df61e24b8c..54f24cbf20 100644
--- a/packages/cli/foundation/integrations/cli-requirement.test.mjs
+++ b/packages/cli/foundation/integrations/cli-requirement.test.mjs
@@ -32,6 +32,11 @@ describe('docsTreeCliProblem', () => {
expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
'declares no @astryxdesign/cli peer',
);
+ // Stable releases: a canary built from main before its release reports
+ // the older version and reads every feature.
+ expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
+ 'A stable CLI before 0.7.0 does not read the docs tree',
+ );
});
it.each(['^0.6.0', '^0.6.0 || >=0.7.0', '*', '>=0.6.3'])(
@@ -39,7 +44,7 @@ describe('docsTreeCliProblem', () => {
range => {
expect(
docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
- ).toContain('admits a CLI older than');
+ ).toContain('admits a stable CLI before');
},
);
@@ -76,7 +81,7 @@ describe('replacesCliProblem', () => {
);
expect(
replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '^0.6.0'}}),
- ).toContain('admits a CLI older than');
+ ).toContain('admits a stable CLI before');
expect(
replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
).toBeNull();
diff --git a/packages/cli/foundation/integrations/contribution-inventory.mjs b/packages/cli/foundation/integrations/contribution-inventory.mjs
index 47e60addd9..79d08ec4f3 100644
--- a/packages/cli/foundation/integrations/contribution-inventory.mjs
+++ b/packages/cli/foundation/integrations/contribution-inventory.mjs
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Contribution inventory for integration pack-check.
+ * @file Contribution inventory for `astryx integration verify`.
*
* Enumerates the files and contribution identities an integration package
* declares, for cross-referencing against the npm tarball. The file inventory
diff --git a/packages/cli/foundation/response/error-codes.doc.mjs b/packages/cli/foundation/response/error-codes.doc.mjs
index 052b1a70bc..1a180fb0ad 100644
--- a/packages/cli/foundation/response/error-codes.doc.mjs
+++ b/packages/cli/foundation/response/error-codes.doc.mjs
@@ -36,17 +36,16 @@ export const doc = {
{
value: 'ERR_INVALID_OPTION',
description:
- 'An unknown flag/option was passed (Commander `unknownOption`).',
+ 'An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto.',
},
{
value: 'ERR_INVALID_ARGUMENT',
description:
- "An option/argument had a value Commander's parser rejected.",
+ 'An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination.',
},
{
value: 'ERR_MISSING_ARGUMENT',
- description:
- 'A required positional argument was omitted (Commander `missingArgument`).',
+ description: 'A required argument or option value was omitted.',
},
{
value: 'ERR_INVALID_LANG',
@@ -134,12 +133,11 @@ export const doc = {
},
{
value: 'ERR_UNKNOWN_PACKAGE',
- description: 'No package matched the requested name (discover).',
+ description: 'No package matched the requested name.',
},
{
value: 'ERR_UNKNOWN_AGENT',
- description:
- 'An unrecognized `--agent` value was passed to agent-docs/init.',
+ description: 'An unrecognized `--agent` value was passed to init.',
},
{
value: 'ERR_UNKNOWN_FEATURE',
@@ -272,7 +270,7 @@ export const doc = {
{
value: 'ERR_UNCLASSIFIED_EXIT',
description:
- 'Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available.',
+ 'Recorded in the debug log, never printed: a command exited non-zero without reporting an error code.',
},
{
value: 'ERR_SIGNAL_TERMINATED',
diff --git a/packages/cli/foundation/response/error-codes.test.mjs b/packages/cli/foundation/response/error-codes.test.mjs
index 58ab5b0313..2081cac252 100644
--- a/packages/cli/foundation/response/error-codes.test.mjs
+++ b/packages/cli/foundation/response/error-codes.test.mjs
@@ -195,9 +195,16 @@ describe('error codes: end-to-end JSON envelopes', () => {
// is rejected at the preAction gate with a stable invalid-option code.
{
name: 'json not supported',
- args: ['theme', 'bogus-sub', '--json'],
+ args: ['theme', '--json'],
code: 'ERR_INVALID_OPTION',
},
+ // A group given a word it does not have names the unknown subcommand,
+ // in JSON as in text.
+ {
+ name: 'unknown subcommand of a group',
+ args: ['theme', 'bogus-sub', '--json'],
+ code: 'ERR_UNKNOWN_SUBCOMMAND',
+ },
];
for (const {name, args, code} of cases) {
@@ -249,13 +256,31 @@ describe('error codes: human mode stays clean', () => {
expect(stdout).not.toContain('ERR_UNKNOWN_COMPONENT');
});
- it('unknown subcommand exits 1 in human mode (code carried internally)', async () => {
- // `theme` is not JSON-capable, so this path is human-only; we assert the
- // failure surfaces with exit 1 and a helpful message. The stable
- // ERR_UNKNOWN_SUBCOMMAND code rides along on the cliError call.
+ it('unknown subcommand exits 1, with the code in JSON and not in text', async () => {
+ // A group that is not JSON-capable itself still answers an unknown
+ // subcommand in JSON, so a JSON caller learns the subcommands it has.
const {status, stderr} = await runCli(['theme', 'bogus-sub']);
expect(status).toBe(1);
expect(stderr).toContain("unknown subcommand 'theme bogus-sub'");
expect(stderr).not.toContain('ERR_UNKNOWN_SUBCOMMAND');
+ for (const args of [
+ ['--json', 'theme', 'bogus-sub'],
+ ['theme', 'bogus-sub', '--json'],
+ ['--json', 'doctor', 'integration', 'bogus-sub'],
+ ]) {
+ const json = await runCli(args);
+ expect(json.status, args.join(' ')).toBe(1);
+ expect(JSON.parse(json.stdout), args.join(' ')).toMatchObject({
+ code: 'ERR_UNKNOWN_SUBCOMMAND',
+ suggestions: expect.arrayContaining([expect.objectContaining({reason: 'available subcommand'})]),
+ });
+ }
+ // Text and JSON agree for a group that shows help when run bare.
+ const text = await runCli(['doctor', 'integration', 'bogus-sub']);
+ expect(text.status).toBe(1);
+ expect(text.stderr).toContain("unknown subcommand 'doctor integration bogus-sub'");
+ const doctor = await runCli(['doctor', 'integrations']);
+ expect(doctor.status).toBe(1);
+ expect(doctor.stderr).toContain("unknown subcommand 'doctor integrations'");
});
});
diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjs
index 355cb020b3..8420310613 100644
--- a/packages/cli/foundation/response/response-types.doc.mjs
+++ b/packages/cli/foundation/response/response-types.doc.mjs
@@ -3,9 +3,10 @@
/**
* @file EnumDoc for the `type` discriminant carried on every --json success
* envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload. Descriptions follow the
- * currently published response projection, not a future package-version boundary.
+ * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
+ * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
+ * `data` payload. Descriptions follow the currently published response
+ * projection, not a future package-version boundary.
*
* @input Public response discriminants and their currently released payloads.
* @output Generated consumer reference for every typed JSON success response.
@@ -35,7 +36,7 @@ export const doc = {
{
value: 'component.list',
description:
- 'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.',
+ "The component catalog grouped by component group (each component's group field): `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.",
},
{
value: 'component.batch',
@@ -160,7 +161,7 @@ export const doc = {
{
value: 'swizzle.copy',
description:
- 'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.',
+ 'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
},
// gap reports
@@ -262,6 +263,11 @@ export const doc = {
description:
'Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.',
},
+ {
+ value: 'upgrade.registry',
+ description:
+ 'The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.',
+ },
{
value: 'upgrade.status',
description:
@@ -280,11 +286,24 @@ export const doc = {
'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
},
+ // help and version, which no single command owns
+ {
+ value: 'help',
+ description:
+ 'Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). ' +
+ "`--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). " +
+ 'data.manifest marks the first shape; data.usage marks the second.',
+ },
+ {
+ value: 'version',
+ description: 'The CLI version, for `astryx --version --json`: {version}.',
+ },
+
// doctor
{
value: 'doctor',
description:
- 'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and a fix when not passing) plus a `summary` of counts per status.',
+ 'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.',
},
// integration authoring
diff --git a/packages/cli/foundation/response/response.doc.mjs b/packages/cli/foundation/response/response.doc.mjs
index 51e7c19626..a985216196 100644
--- a/packages/cli/foundation/response/response.doc.mjs
+++ b/packages/cli/foundation/response/response.doc.mjs
@@ -39,16 +39,13 @@ export const doc = {
name: 'type',
type: 'string',
description:
- 'Discriminator naming the payload shape. Each command guarantees ' +
- 'its own `type` at its return; there is no central union.',
+ 'Names the payload shape. Every value is listed in the response-types enum.',
required: true,
},
{
name: 'data',
type: 'unknown',
- description:
- "The command's payload. Structural by design, narrowed by the " +
- 'per-command return type, not by a map in the serializer.',
+ description: "The command's payload; its shape depends on `type`.",
required: true,
},
{
@@ -64,7 +61,7 @@ export const doc = {
type: '{ apiVersion: number; error: string; code: ErrorCode; suggestions?: Suggestion[] }',
description:
'Emitted for every failure in --json mode, including uncaught throws ' +
- 'and Commander parse errors, which are converted to this shape.',
+ 'and command-line parse errors, which are converted to this shape.',
fields: [
{
name: 'apiVersion',
@@ -121,7 +118,7 @@ export const doc = {
label: 'Success',
code: `{
"apiVersion": 1,
- "type": "component",
+ "type": "component.detail",
"data": { "name": "Button" }
}`,
},
@@ -153,9 +150,13 @@ export const doc = {
{
type: 'prose',
text:
- 'The process exit code is part of the contract too: successful commands ' +
- 'exit 0, and a JSON error envelope is accompanied by a non-zero exit ' +
- '(jsonError exits 1).',
+ 'The process exit code is part of the contract too. Exit 0 means success, ' +
+ 'and every error envelope exits 1. Some commands also exit 1 with a success ' +
+ 'envelope when what they report failed: a failed check (layout check, doctor ' +
+ 'and its integration subcommands, integration verify, theme build ' +
+ '--check), a gap report that was not delivered, an upgrade left incomplete, ' +
+ 'or init agent docs refused for a path outside the project. Read the ' +
+ 'envelope, not the exit code, to tell them apart.',
},
],
};
diff --git a/packages/cli/test/cli-integrations-doc-drift.test.mjs b/packages/cli/test/cli-integrations-doc-drift.test.mjs
deleted file mode 100644
index 6497b9c7f6..0000000000
--- a/packages/cli/test/cli-integrations-doc-drift.test.mjs
+++ /dev/null
@@ -1,391 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Documentation drift tests for the cli-integrations guide and related
- * CommandDocs/FunctionDocs. Tests verify against executable sources of truth
- * (parseDoc dispatch, resolvePackageDir, theme-discovery validators, schema
- * shapes) rather than only prose-to-prose assertions, so a behavioral change
- * that invalidates a documented claim is caught at CI time.
- */
-
-import {afterEach, beforeEach, describe, it, expect} from 'vitest';
-import {docs as integrationGuide} from '../assets/docs/tree/integrations.doc.mjs';
-import {doc as upgradeCommandDoc} from '../clients/cli/commands/upgrade.doc.mjs';
-import {doc as upgradeFnDoc} from '../api/upgrade/upgrade.doc.mjs';
-import {doc as paletteGenerateDoc} from '../clients/cli/commands/theme-palette-generate.doc.mjs';
-import {doc as integrationAddDoc} from '../clients/cli/commands/integration-add.doc.mjs';
-import {parseDoc} from '../authoring/doctypes/parse.mjs';
-import {parseCodemod} from '../authoring/codemod/parse.mjs';
-import {resolvePackageDir} from '../foundation/integrations/integrations.mjs';
-import {discoverThemeDirectory} from '../foundation/discovery/theme-discovery.mjs';
-import {integrationAddTheme} from '../api/integration/add-theme.mjs';
-import {themePaletteGenerate} from '../api/theme/palette/generate/generate.mjs';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-
-/** Flatten all text content from a ReferenceDoc's sections into one string. */
-function guideText(doc) {
- const parts = [];
- for (const section of doc.sections ?? []) {
- for (const block of section.content ?? []) {
- if (block.type === 'prose') parts.push(block.text);
- if (block.type === 'code') parts.push(block.code);
- if (block.type === 'list') parts.push((block.items ?? []).join('\n'));
- }
- }
- return parts.join('\n');
-}
-
-// ── Executable source-of-truth tests ────────────────────────────────────
-
-describe('parseDoc dispatches on documented type stamps', () => {
- it('routes type: component to the component parser', () => {
- const doc = parseDoc({
- type: 'component',
- name: 'Test',
- description: 'x',
- props: [],
- });
- expect(doc.type).toBe('component');
- });
-
- it('routes type: generic to the reference parser', () => {
- const doc = parseDoc({type: 'generic', name: 'test', description: 'x'});
- expect(doc.type).toBe('generic');
- });
-
- it('routes type: page to the template parser', () => {
- const doc = parseDoc({
- type: 'page',
- name: 'TestPage',
- description: 'x',
- });
- expect(doc.type).toBe('page');
- });
-
- it('routes type: block to the template parser', () => {
- const doc = parseDoc({
- type: 'block',
- name: 'TestBlock',
- description: 'x',
- });
- expect(doc.type).toBe('block');
- });
-
- it('a wrong stamp misroutes: generic on a component-shaped doc drops props', () => {
- // Demonstrates the guide's claim that a wrong stamp parses under the wrong schema
- const doc = parseDoc({
- type: 'generic',
- name: 'Mislabeled',
- description: 'x',
- props: [{name: 'a', type: 'string', description: 'x'}],
- });
- // generic schema uses passthrough so props survive, but the type is generic not component
- expect(doc.type).toBe('generic');
- });
-});
-
-describe('resolvePackageDir keeps integration specs beneath node_modules', () => {
- it('rejects absolute paths', () => {
- expect(() => resolvePackageDir('/etc/passwd')).toThrow(
- /invalid integration package name/i,
- );
- });
-
- it('rejects relative segments', () => {
- expect(() => resolvePackageDir('../escape')).toThrow(
- /invalid integration package name/i,
- );
- });
-
- it('rejects dot segments', () => {
- expect(() => resolvePackageDir('./local')).toThrow(
- /invalid integration package name/i,
- );
- });
-
- it('accepts scoped and nested slash-separated values', () => {
- expect(() => resolvePackageDir('@acme/widgets')).not.toThrow();
- expect(() => resolvePackageDir('foo/bar')).not.toThrow();
- });
-});
-
-describe('a theme descriptor carries every documented field', () => {
- let tmpDir;
-
- const descriptor = (/** @type {object} */ fields = {}) => ({
- type: 'theme',
- name: 'ocean',
- displayName: 'Ocean',
- description: 'Ocean theme.',
- maintained: true,
- ...fields,
- });
-
- beforeEach(() => {
- tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'doc-drift-'));
- });
- afterEach(() => {
- fs.rmSync(tmpDir, {recursive: true, force: true});
- });
-
- it('accepts a descriptor with every documented field', () => {
- expect(parseDoc(descriptor(), 'oceanTheme.doc.mjs').type).toBe('theme');
- });
-
- it.each(['name', 'displayName', 'description', 'maintained'])(
- 'rejects a descriptor without %s',
- field => {
- const {[field]: _, ...rest} = descriptor();
- expect(() => parseDoc(rest, 'oceanTheme.doc.mjs')).toThrow(field);
- },
- );
-
- it('rejects a slug that is not lowercase kebab-case', () => {
- expect(() =>
- parseDoc(descriptor({name: 'Ocean'}), 'oceanTheme.doc.mjs'),
- ).toThrow(/kebab-case/);
- });
-
- it('rejects a theme directory without its same-stem descriptor', () => {
- const dir = path.join(tmpDir, 'themes', 'ocean');
- fs.mkdirSync(dir, {recursive: true});
- fs.writeFileSync(
- path.join(dir, 'oceanTheme.ts'),
- 'export const oceanTheme = {};\n',
- );
- expect(() =>
- discoverThemeDirectory(path.join(tmpDir, 'themes'), '@test/pkg'),
- ).toThrow();
- });
-});
-
-describe('documented theme palette workflow', () => {
- let tmpDir;
-
- beforeEach(() => {
- tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'documented-theme-flow-'));
- fs.writeFileSync(
- path.join(tmpDir, 'package.json'),
- JSON.stringify({name: '@acme/brand-integration', version: '1.0.0'}),
- );
- });
-
- afterEach(() => {
- fs.rmSync(tmpDir, {recursive: true, force: true});
- });
-
- it('generates and discovers the exact documented theme directory', async () => {
- await integrationAddTheme('ocean', {cwd: tmpDir});
- const themeDir = path.join(tmpDir, 'themes', 'ocean');
- fs.mkdirSync(path.join(themeDir, 'tokens'), {recursive: true});
- fs.writeFileSync(
- path.join(themeDir, 'palette.config.json'),
- JSON.stringify({
- modeStrategy: 'light-only',
- stops: [20, 50, 80],
- families: [{id: 'blue', seed: '#0074e2'}],
- }),
- );
-
- const result = themePaletteGenerate(
- 'themes/ocean/palette.config.json',
- {out: 'themes/ocean/tokens/ocean.palette.ts'},
- {cwd: tmpDir},
- );
- expect(result.data).toMatchObject({
- output: 'themes/ocean/tokens/ocean.palette.ts',
- receipt: 'themes/ocean/tokens/ocean.palette.receipt.json',
- written: true,
- });
-
- fs.writeFileSync(
- path.join(themeDir, 'oceanTheme.ts'),
- "import {palette} from './tokens/ocean.palette';\nexport const oceanTheme = {palette};\n",
- );
- const [theme] = discoverThemeDirectory(
- path.join(tmpDir, 'themes'),
- '@acme/brand-integration',
- );
- expect(theme).toMatchObject({slug: 'ocean', entry: 'oceanTheme.ts'});
- const documented = [
- 'oceanTheme.ts',
- 'oceanTheme.doc.mjs',
- 'palette.config.json',
- 'tokens/ocean.palette.receipt.json',
- 'tokens/ocean.palette.ts',
- ];
- // The documented layout is exactly what the theme directory ships, entry
- // first.
- expect(theme.files).toEqual(documented);
-
- const text = guideText(integrationGuide);
- for (const documentedPath of documented) {
- expect(text).toContain(documentedPath.split('/').pop());
- }
- expect(
- paletteGenerateDoc.examples.some(
- example =>
- example.cli ===
- 'astryx theme palette generate themes/ocean/palette.config.json --out themes/ocean/tokens/ocean.palette.ts',
- ),
- ).toBe(true);
- });
-});
-
-// ── Guide prose content tests (verified against the executable tests above) ──
-
-describe('cli-integrations guide required content', () => {
- const text = guideText(integrationGuide);
-
- it('documents all four type stamps used by parseDoc', () => {
- for (const stamp of ["'component'", "'generic'", "'page'", "'block'"]) {
- expect(text).toContain(stamp);
- }
- });
-
- it('documents both type stamps accepted by parseCodemod', () => {
- for (const type of ['code', 'config']) {
- expect(
- parseCodemod({type, title: `${type} migration`, transform() {}}).type,
- ).toBe(type);
- expect(text).toContain(`'${type}'`);
- }
- });
-
- it('names .doc.mjs as the authoring suffix and the released ones it still reads', () => {
- expect(text).toContain('strongly typed `.doc.mjs`');
- expect(text).toContain(
- 'Released `.doc.js` docs remain readable for compatibility. A `.doc.ts` component doc reads only when the package is linked from outside node_modules, not once it is installed.',
- );
- expect(text).toContain('Released `.template.*` files remain readable');
- });
-
- it('says which released suffixes still load for each kind', () => {
- expect(text).toContain(
- 'Released .doc.js files, template .doc.ts files, and .template.{ts,mjs,js}\ntemplates still load.',
- );
- expect(text).toContain(
- 'A component or topic .doc.ts loads only from a package\nlinked from outside node_modules; installed, it is listed but cannot be read.',
- );
- expect(text).not.toContain(
- 'Released `.doc.ts` and `.doc.js` inputs remain readable',
- );
- });
-
- it('documents the codemod version-directory layout', () => {
- expect(text).toMatch(/version-folder/i);
- expect(text).toMatch(/no `v` prefix/i);
- expect(text).toContain('0.2.0/');
- });
-
- it('documents that upgrade is dry-run by default with no --dry-run flag', () => {
- expect(text).toMatch(/dry-run by default/i);
- expect(text).toContain('--apply');
- expect(text).toMatch(/no `--dry-run` flag/i);
- });
-
- it('documents every ThemeDoc field and the same-stem source rule', () => {
- for (const field of [
- '`ThemeDoc`',
- '`name`',
- '`displayName`',
- '`description`',
- '`maintained`',
- ]) {
- expect(text).toContain(field);
- }
- expect(text).toMatch(/stem supplies the source entry/);
- expect(text).not.toContain('manifest.json entry');
- });
-
- it('documents the generated palette inventory exactly', () => {
- expect(text).toMatch(/already importable/i);
- expect(text).toContain('tokens/ocean.palette.ts');
- expect(text).toContain('tokens/ocean.palette.receipt.json');
- expect(text).toContain('palette.config.json');
- });
-
- it('documents extensionless package export subpaths', () => {
- expect(text).toMatch(/extensionless/i);
- });
-
- it('warns against npx for integration authoring', () => {
- expect(text).toMatch(/not.*npx/i);
- });
-
- it('documents that --integration resolves beneath node_modules', () => {
- expect(text).toMatch(/beneath.*node_modules/i);
- });
-
- it('documents integration pack --check', () => {
- expect(text).toContain('integration pack --check');
- });
-
- it('explains type stamp as required for new docs with legacy fallback', () => {
- expect(text).toMatch(/legacy.*stamp.*load/i);
- });
-});
-
-// ── CommandDoc / FunctionDoc consistency ─────────────────────────────────
-
-describe('upgrade CommandDoc --integration flag', () => {
- const integrationOpt = upgradeCommandDoc.options.find(o =>
- o.flag.includes('--integration'),
- );
-
- it('exists', () => {
- expect(integrationOpt).toBeDefined();
- });
-
- it('states the actual resolver boundary', () => {
- expect(integrationOpt.description).toMatch(/beneath node_modules/i);
- expect(integrationOpt.description).toMatch(/absolute paths/i);
- expect(integrationOpt.description).toMatch(/`\.` or `\.\.`/);
- });
-
- it('flag placeholder does not say package-or-file', () => {
- expect(integrationOpt.flag).not.toContain('package-or-file');
- });
-});
-
-describe('upgrade FunctionDoc --integration param', () => {
- const integrationParam = upgradeFnDoc.params.find(
- p => p.name === 'options.integration',
- );
-
- it('exists', () => {
- expect(integrationParam).toBeDefined();
- });
-
- it('states the actual resolver boundary', () => {
- expect(integrationParam.description).toMatch(/beneath node_modules/i);
- expect(integrationParam.description).toMatch(/absolute paths/i);
- expect(integrationParam.description).toMatch(/`\.` or `\.\.`/);
- });
-});
-
-describe('palette generate doc says where its outputs ship', () => {
- it('keeps the outputs in the theme directory that theme add copies', () => {
- expect(paletteGenerateDoc.description).toMatch(/theme directory/i);
- expect(paletteGenerateDoc.description).not.toMatch(/catalog/i);
- });
-});
-
-describe('integration add doc has all contribution kinds', () => {
- const kindsArg = integrationAddDoc.args.find(a => a.name === 'kind');
-
- it('lists component, doc, template, codemod, agent-doc, and theme', () => {
- for (const kind of [
- 'component',
- 'doc',
- 'template',
- 'codemod',
- 'agent-doc',
- 'theme',
- ]) {
- expect(kindsArg.description).toContain(kind);
- }
- });
-});
diff --git a/packages/cli/test/doc-routes.ids.json b/packages/cli/test/doc-routes.ids.json
index 63916c4f78..333e0b97df 100644
--- a/packages/cli/test/doc-routes.ids.json
+++ b/packages/cli/test/doc-routes.ids.json
@@ -991,6 +991,11 @@
"integration",
"integration add",
"integration pack",
+ "integration verify",
+ "layout",
+ "layout check",
+ "layout expand",
+ "layout grammar",
"manifest",
"search",
"swizzle",
@@ -1029,6 +1034,9 @@
"integrationPackCheck",
"integrationTemplateConflicts",
"isError",
+ "layoutCheck",
+ "layoutExpand",
+ "layoutGrammar",
"listThemes",
"parseResponse",
"search",
diff --git a/packages/cli/test/doc-routes.json b/packages/cli/test/doc-routes.json
index dea5a35f62..520785771e 100644
--- a/packages/cli/test/doc-routes.json
+++ b/packages/cli/test/doc-routes.json
@@ -97,16 +97,6 @@
"rationale": "Stays a section of authoring under the same key. Its content is the schema self-doc `gap-report-handler` (schema row), which the topic renders as one section.",
"status": "proposed"
},
- {
- "kind": "section",
- "id": "authoring#discover-source",
- "oldCliRoute": "astryx docs authoring discover-source",
- "oldDocsiteUrl": "/docs/authoring#discoversource",
- "placement": "keep-flat",
- "aliasNeeded": false,
- "rationale": "Stays a section of authoring under the same key. Its content is the schema self-doc `discover-source` (schema row), which the topic renders as one section.",
- "status": "proposed"
- },
{
"kind": "section",
"id": "authoring#codemod",
@@ -244,484 +234,2354 @@
"oldDocsiteUrl": null,
"placement": "namespace:cli",
"aliasNeeded": false,
- "evidence": "assets/docs/tree/cli.doc.mjs declares it; astryx doctor fails when the tree does not build or a CLI doc in a cli group has no route.",
- "rationale": "The top of the CLI docs tree: its guides (cli/integrations, cli/writing-docs) and its reference (cli/commands and cli/api), one level at a time. The docsite does not publish it yet, because /docs/cli is the @astryxdesign/cli package page.",
+ "evidence": "assets/docs/tree/cli.doc.mjs declares it; astryx doctor fails when the tree does not build or a CLI doc in a cli group has no route.",
+ "rationale": "The top of the CLI docs tree: its guides (cli/integrations) and its reference (cli/commands and cli/api), one level at a time. The docsite does not publish it yet, because /docs/cli is the @astryxdesign/cli package page.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/commands",
+ "oldCliRoute": "astryx docs cli/commands",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/commands",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/commands.doc.mjs declares it.",
+ "rationale": "Adopts every command doc whose namespace is cli/commands, one leaf each at cli/commands/<name>. The docsite does not publish it yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/api",
+ "oldCliRoute": "astryx docs cli/api",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/api",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/api.doc.mjs declares it.",
+ "rationale": "Adopts every function, schema, and enum doc whose namespace is cli/api, one generated level per kind. The docsite does not publish it yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/api/functions",
+ "oldCliRoute": "astryx docs cli/api/functions",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/api/functions",
+ "aliasNeeded": false,
+ "evidence": "The api namespace adopts cli/api with groupBy kind.",
+ "rationale": "Generated by the api namespace for its function docs, one leaf each at cli/api/functions/<name>. The docsite does not publish it yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/api/schemas",
+ "oldCliRoute": "astryx docs cli/api/schemas",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/api/schemas",
+ "aliasNeeded": false,
+ "evidence": "The api namespace adopts cli/api with groupBy kind.",
+ "rationale": "Generated by the api namespace for its schema docs (the JSON output envelope). The docsite does not publish it yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/api/enums",
+ "oldCliRoute": "astryx docs cli/api/enums",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/api/enums",
+ "aliasNeeded": false,
+ "evidence": "The api namespace adopts cli/api with groupBy kind.",
+ "rationale": "Generated by the api namespace for its enum docs (error codes and response types). The docsite does not publish it yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "unorganized",
+ "oldCliRoute": "astryx docs unorganized",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:unorganized",
+ "aliasNeeded": false,
+ "evidence": "The docs tree generates it: every flat topic sits in it, in the order the topic list reads.",
+ "rationale": "The home of every topic that no section places yet. Each keeps its own name, so no route changes; placing a topic in a real section takes it out.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "browser-support",
+ "oldCliRoute": "astryx docs browser-support",
+ "oldDocsiteUrl": "/docs/browser-support",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Standalone guide: no topic links to it, and nothing authored places it under another topic.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "browser-support#overview",
+ "oldCliRoute": "astryx docs browser-support overview",
+ "oldDocsiteUrl": "/docs/browser-support#overview",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of browser-support under the same key.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "browser-support#support-tiers",
+ "oldCliRoute": "astryx docs browser-support support-tiers",
+ "oldDocsiteUrl": "/docs/browser-support#support-tiers",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of browser-support under the same key.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "browser-support#which-features-set-the-floor",
+ "oldCliRoute": "astryx docs browser-support which-features-set-the-floor",
+ "oldDocsiteUrl": "/docs/browser-support#which-features-set-the-floor",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of browser-support under the same key.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "browser-support#which-components-are-affected",
+ "oldCliRoute": "astryx docs browser-support which-components-are-affected",
+ "oldDocsiteUrl": "/docs/browser-support#which-components-are-affected",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of browser-support under the same key.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "browser-support#what-astryx-guarantees",
+ "oldCliRoute": "astryx docs browser-support what-astryx-guarantees",
+ "oldDocsiteUrl": "/docs/browser-support#what-astryx-guarantees",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of browser-support under the same key.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "browser-support#supporting-older-browsers",
+ "oldCliRoute": "astryx docs browser-support supporting-older-browsers",
+ "oldDocsiteUrl": "/docs/browser-support#supporting-older-browsers",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of browser-support under the same key.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "browser-support#how-these-tiers-move-over-time",
+ "oldCliRoute": "astryx docs browser-support how-these-tiers-move-over-time",
+ "oldDocsiteUrl": "/docs/browser-support#how-these-tiers-move-over-time",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of browser-support under the same key.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations",
+ "oldCliRoute": "astryx docs cli/integrations",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/integrations.doc.mjs declares it, and places it in cli's guides slot.",
+ "rationale": "The integration guides, one short guide per task in four slots: start, contribute, ship, and help. It replaced the single cli/integrations guide, whose docsite page /docs/cli-integrations redirects to cli/integrations/overview. The docsite does not publish the namespace itself yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/overview",
+ "oldCliRoute": "astryx docs cli/integrations/overview",
+ "oldDocsiteUrl": "/docs/cli-integrations-overview",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'start', order: 10}.",
+ "rationale": "Overview: An integration is an npm package that hooks into the Astryx CLI and makes it your own. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/overview#what-you-can-do",
+ "oldCliRoute": "astryx docs cli/integrations/overview what-you-can-do",
+ "oldDocsiteUrl": "/docs/cli-integrations-overview#what-you-can-do",
+ "placement": "namespace:cli/integrations/overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/overview.",
+ "rationale": "A section of cli/integrations/overview: What you can do.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/overview#how-an-app-finds-it",
+ "oldCliRoute": "astryx docs cli/integrations/overview how-an-app-finds-it",
+ "oldDocsiteUrl": "/docs/cli-integrations-overview#find-and-install-an-integration",
+ "placement": "namespace:cli/integrations/overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/overview.",
+ "rationale": "A section of cli/integrations/overview: Find and install an integration.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/make-a-package",
+ "oldCliRoute": "astryx docs cli/integrations/make-a-package",
+ "oldDocsiteUrl": "/docs/cli-integrations-make-a-package",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'start', order: 20}.",
+ "rationale": "Make a package: Create a new integration package and understand the package files the CLI maintains. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/make-a-package#quick-start",
+ "oldCliRoute": "astryx docs cli/integrations/make-a-package quick-start",
+ "oldDocsiteUrl": "/docs/cli-integrations-make-a-package#quick-start",
+ "placement": "namespace:cli/integrations/make-a-package",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/make-a-package.",
+ "rationale": "A section of cli/integrations/make-a-package: Quick start.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/make-a-package#fill-in-package-json",
+ "oldCliRoute": "astryx docs cli/integrations/make-a-package fill-in-package-json",
+ "oldDocsiteUrl": "/docs/cli-integrations-make-a-package#fill-in-package-json",
+ "placement": "namespace:cli/integrations/make-a-package",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/make-a-package.",
+ "rationale": "A section of cli/integrations/make-a-package: Fill in package.json.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/make-a-package#the-integration-file",
+ "oldCliRoute": "astryx docs cli/integrations/make-a-package the-integration-file",
+ "oldDocsiteUrl": "/docs/cli-integrations-make-a-package#the-integration-file",
+ "placement": "namespace:cli/integrations/make-a-package",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/make-a-package.",
+ "rationale": "A section of cli/integrations/make-a-package: The integration file.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations/components",
+ "oldCliRoute": "astryx docs cli/integrations/components",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/components",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/components.doc.mjs declares it and places it in cli/integrations' contribute slot.",
+ "rationale": "The guides for adding, documenting, exporting, replacing, and checking integration components, one level at a time. The docsite does not publish the namespace itself yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/add-a-component",
+ "oldCliRoute": "astryx docs cli/integrations/components/add-a-component",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-add-a-component",
+ "placement": "namespace:cli/integrations/components",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:components', slot: 'build', order: 10}.",
+ "rationale": "Add a component: Choose a stable component name and generate its source, doc, package export, and integration entry. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/add-a-component#pick-a-component-name",
+ "oldCliRoute": "astryx docs cli/integrations/components/add-a-component pick-a-component-name",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-add-a-component#pick-a-component-name",
+ "placement": "namespace:cli/integrations/components/add-a-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/add-a-component.",
+ "rationale": "A section of cli/integrations/components/add-a-component: Pick a component name.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/add-a-component#run-the-add-command",
+ "oldCliRoute": "astryx docs cli/integrations/components/add-a-component run-the-add-command",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-add-a-component#run-the-add-command",
+ "placement": "namespace:cli/integrations/components/add-a-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/add-a-component.",
+ "rationale": "A section of cli/integrations/components/add-a-component: Run the add command.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations/components/describe-the-component",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/components/describe-the-component",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/describe-the-component.doc.mjs declares it and places it in Components' build slot.",
+ "rationale": "The component-documentation guides: an overview, the default single-component doc, and adaptations for a family or subcomponent. The docsite does not publish the namespace itself yet.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/describe-the-component/component-doc-overview",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-doc-overview",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-doc-overview",
+ "placement": "namespace:cli/integrations/components/describe-the-component",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:describe-the-component', slot: 'guides', order: 10}.",
+ "rationale": "Component doc overview: Treat the component doc as a public contract, keep it synchronized with source, and inspect the result consumers receive. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/component-doc-overview#treat-the-doc-as-public-api",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-doc-overview treat-the-doc-as-public-api",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-doc-overview#treat-the-doc-as-public-api",
+ "placement": "namespace:cli/integrations/components/describe-the-component/component-doc-overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/component-doc-overview.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/component-doc-overview: Treat the doc as public API.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/component-doc-overview#fill-in-the-shared-fields",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-doc-overview fill-in-the-shared-fields",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-doc-overview#fill-in-the-shared-fields",
+ "placement": "namespace:cli/integrations/components/describe-the-component/component-doc-overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/component-doc-overview.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/component-doc-overview: Fill in the shared fields.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/component-doc-overview#read-the-doc-back",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-doc-overview read-the-doc-back",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-doc-overview#read-the-doc-back",
+ "placement": "namespace:cli/integrations/components/describe-the-component/component-doc-overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/component-doc-overview.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/component-doc-overview: Read the doc back.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/describe-the-component/single-component",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/single-component",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-single-component",
+ "placement": "namespace:cli/integrations/components/describe-the-component",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:describe-the-component', slot: 'guides', order: 20}.",
+ "rationale": "Single component: Write the default component doc: explain when to use the component, document every public prop, and add focused examples. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/single-component#start-from-the-generated-doc",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/single-component start-from-the-generated-doc",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-single-component#start-from-the-generated-doc",
+ "placement": "namespace:cli/integrations/components/describe-the-component/single-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/single-component.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/single-component: Start from the generated doc.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/single-component#explain-when-to-use-it",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/single-component explain-when-to-use-it",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-single-component#explain-when-to-use-it",
+ "placement": "namespace:cli/integrations/components/describe-the-component/single-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/single-component.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/single-component: Explain when to use it.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/single-component#document-every-public-prop",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/single-component document-every-public-prop",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-single-component#document-every-public-prop",
+ "placement": "namespace:cli/integrations/components/describe-the-component/single-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/single-component.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/single-component: Document every public prop.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/single-component#add-focused-examples",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/single-component add-focused-examples",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-single-component#add-focused-examples",
+ "placement": "namespace:cli/integrations/components/describe-the-component/single-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/single-component.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/single-component: Add focused examples.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/single-component#read-the-result",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/single-component read-the-result",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-single-component#read-the-result",
+ "placement": "namespace:cli/integrations/components/describe-the-component/single-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/single-component.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/single-component: Read the result.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/describe-the-component/component-family",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-family",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-family",
+ "placement": "namespace:cli/integrations/components/describe-the-component",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:describe-the-component', slot: 'guides', order: 30}.",
+ "rationale": "Component family: Adapt a single-component doc when one module exposes several public components or hooks that belong to one family. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/component-family#choose-the-family-shape",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-family choose-the-family-shape",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-family#choose-the-family-shape",
+ "placement": "namespace:cli/integrations/components/describe-the-component/component-family",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/component-family.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/component-family: Choose the family shape.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/component-family#document-the-family-inline",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-family document-the-family-inline",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-family#document-the-family-inline",
+ "placement": "namespace:cli/integrations/components/describe-the-component/component-family",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/component-family.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/component-family: Document the family inline.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/component-family#give-a-member-its-own-file",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/component-family give-a-member-its-own-file",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-component-family#give-a-member-its-own-file",
+ "placement": "namespace:cli/integrations/components/describe-the-component/component-family",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/component-family.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/component-family: Give a member its own file.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/describe-the-component/subcomponent",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/subcomponent",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-subcomponent",
+ "placement": "namespace:cli/integrations/components/describe-the-component",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:describe-the-component', slot: 'guides', order: 40}.",
+ "rationale": "Subcomponent: Move one member of a component family into its own sibling doc without duplicating it in the parent. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/subcomponent#choose-a-separate-doc",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/subcomponent choose-a-separate-doc",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-subcomponent#choose-a-separate-doc",
+ "placement": "namespace:cli/integrations/components/describe-the-component/subcomponent",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/subcomponent.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/subcomponent: Choose a separate doc.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/subcomponent#reference-it-from-the-parent",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/subcomponent reference-it-from-the-parent",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-subcomponent#reference-it-from-the-parent",
+ "placement": "namespace:cli/integrations/components/describe-the-component/subcomponent",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/subcomponent.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/subcomponent: Reference it from the parent.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/describe-the-component/subcomponent#write-the-subcomponent-doc",
+ "oldCliRoute": "astryx docs cli/integrations/components/describe-the-component/subcomponent write-the-subcomponent-doc",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-describe-the-component-subcomponent#write-the-subcomponent-doc",
+ "placement": "namespace:cli/integrations/components/describe-the-component/subcomponent",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/describe-the-component/subcomponent.",
+ "rationale": "A section of cli/integrations/components/describe-the-component/subcomponent: Write the subcomponent doc.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/component-imports",
+ "oldCliRoute": "astryx docs cli/integrations/components/component-imports",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-component-imports",
+ "placement": "namespace:cli/integrations/components",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:components', slot: 'build', order: 30}.",
+ "rationale": "Resolve the import: Keep the component doc import and package exports map aligned, then verify the packed package. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/component-imports#export-the-component",
+ "oldCliRoute": "astryx docs cli/integrations/components/component-imports export-the-component",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-component-imports#export-the-component",
+ "placement": "namespace:cli/integrations/components/component-imports",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/component-imports.",
+ "rationale": "A section of cli/integrations/components/component-imports: Export the component.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/component-imports#verify-the-packed-import",
+ "oldCliRoute": "astryx docs cli/integrations/components/component-imports verify-the-packed-import",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-component-imports#verify-the-packed-import",
+ "placement": "namespace:cli/integrations/components/component-imports",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/component-imports.",
+ "rationale": "A section of cli/integrations/components/component-imports: Verify the packed import.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/see-it-in-an-app",
+ "oldCliRoute": "astryx docs cli/integrations/components/see-it-in-an-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-see-it-in-an-app",
+ "placement": "namespace:cli/integrations/components",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:components', slot: 'build', order: 40}.",
+ "rationale": "See it in an app: Confirm that an app discovers the component, its package, its public import, and its documentation. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/see-it-in-an-app#read-the-installed-component",
+ "oldCliRoute": "astryx docs cli/integrations/components/see-it-in-an-app read-the-installed-component",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-see-it-in-an-app#read-the-installed-component",
+ "placement": "namespace:cli/integrations/components/see-it-in-an-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/see-it-in-an-app.",
+ "rationale": "A section of cli/integrations/components/see-it-in-an-app: Read the installed component.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/see-it-in-an-app#test-the-packed-package",
+ "oldCliRoute": "astryx docs cli/integrations/components/see-it-in-an-app test-the-packed-package",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-see-it-in-an-app#test-the-packed-package",
+ "placement": "namespace:cli/integrations/components/see-it-in-an-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/see-it-in-an-app.",
+ "rationale": "A section of cli/integrations/components/see-it-in-an-app: Test the packed package.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/components/replace-a-core-component",
+ "oldCliRoute": "astryx docs cli/integrations/components/replace-a-core-component",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-replace-a-core-component",
+ "placement": "namespace:cli/integrations/components",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:components', slot: 'advanced', order: 10}.",
+ "rationale": "Replace a Core component: Use a component replacement only when an integration must intentionally own a Core component identity. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/replace-a-core-component#decide-whether-to-replace",
+ "oldCliRoute": "astryx docs cli/integrations/components/replace-a-core-component decide-whether-to-replace",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-replace-a-core-component#decide-whether-to-replace",
+ "placement": "namespace:cli/integrations/components/replace-a-core-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/replace-a-core-component.",
+ "rationale": "A section of cli/integrations/components/replace-a-core-component: Decide whether to replace.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/replace-a-core-component#set-the-replacement",
+ "oldCliRoute": "astryx docs cli/integrations/components/replace-a-core-component set-the-replacement",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-replace-a-core-component#set-the-replacement",
+ "placement": "namespace:cli/integrations/components/replace-a-core-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/replace-a-core-component.",
+ "rationale": "A section of cli/integrations/components/replace-a-core-component: Set the replacement.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/components/replace-a-core-component#check-replacement-resolution",
+ "oldCliRoute": "astryx docs cli/integrations/components/replace-a-core-component check-replacement-resolution",
+ "oldDocsiteUrl": "/docs/cli-integrations-components-replace-a-core-component#check-replacement-resolution",
+ "placement": "namespace:cli/integrations/components/replace-a-core-component",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/components/replace-a-core-component.",
+ "rationale": "A section of cli/integrations/components/replace-a-core-component: Check replacement resolution.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations/templates",
+ "oldCliRoute": "astryx docs cli/integrations/templates",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/templates",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/templates.doc.mjs declares this namespace and places it with placement {parent: 'namespace:integrations', slot: 'contribute', order: 20}.",
+ "rationale": "Templates: Templates are ready-made UI pages or page sections built with Astryx. Apps copy them into their code and adapt them to their product. The route stays the same while the former flat guide becomes a navigable namespace.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/start-a-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/start-a-template",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-start-a-template",
+ "placement": "namespace:cli/integrations/templates",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:templates', slot: 'build', order: 10}.",
+ "rationale": "Start a template: Help others build apps faster and share a consistent visual language by turning your UI idea into a full page or page section. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/start-a-template#what-a-template-is",
+ "oldCliRoute": "astryx docs cli/integrations/templates/start-a-template what-a-template-is",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-start-a-template#what-a-template-is",
+ "placement": "namespace:cli/integrations/templates/start-a-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/start-a-template.",
+ "rationale": "A section of cli/integrations/templates/start-a-template: What a template is.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/start-a-template#why-share-one",
+ "oldCliRoute": "astryx docs cli/integrations/templates/start-a-template why-share-one",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-start-a-template#why-share-one",
+ "placement": "namespace:cli/integrations/templates/start-a-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/start-a-template.",
+ "rationale": "A section of cli/integrations/templates/start-a-template: Why share one.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/start-a-template#choose-page-or-block",
+ "oldCliRoute": "astryx docs cli/integrations/templates/start-a-template choose-page-or-block",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-start-a-template#choose-a-page-or-block",
+ "placement": "namespace:cli/integrations/templates/start-a-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/start-a-template.",
+ "rationale": "A section of cli/integrations/templates/start-a-template: Choose a page or block.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/start-a-template#pick-a-template-id",
+ "oldCliRoute": "astryx docs cli/integrations/templates/start-a-template pick-a-template-id",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-start-a-template#pick-a-template-id",
+ "placement": "namespace:cli/integrations/templates/start-a-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/start-a-template.",
+ "rationale": "A section of cli/integrations/templates/start-a-template: Pick a template id.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/start-a-template#run-the-add-command",
+ "oldCliRoute": "astryx docs cli/integrations/templates/start-a-template run-the-add-command",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-start-a-template#run-the-add-command",
+ "placement": "namespace:cli/integrations/templates/start-a-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/start-a-template.",
+ "rationale": "A section of cli/integrations/templates/start-a-template: Run the add command.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations/templates/document-the-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/templates/document-the-template",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/document-the-template.doc.mjs declares this namespace and places it with placement {parent: 'namespace:templates', slot: 'build', order: 20}.",
+ "rationale": "Document the template: Write the doc that helps people and agents find, choose, and trust your template: its name, description, readiness, preview, and any Core replacement. This namespace is new in this change, so it has no older route or docsite page.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/document-the-template/template-doc-overview",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/template-doc-overview",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-template-doc-overview",
+ "placement": "namespace:cli/integrations/templates/document-the-template",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:document-the-template', slot: 'guides', order: 10}.",
+ "rationale": "Template doc overview: Understand what the template doc controls, keep it accurate as the UI changes, and check how Astryx lists the template. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/template-doc-overview#understand-the-two-files",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/template-doc-overview understand-the-two-files",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-template-doc-overview#understand-the-two-files",
+ "placement": "namespace:cli/integrations/templates/document-the-template/template-doc-overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/template-doc-overview.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/template-doc-overview: Understand the two files.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/template-doc-overview#document-the-shared-fields",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/template-doc-overview document-the-shared-fields",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-template-doc-overview#document-the-shared-fields",
+ "placement": "namespace:cli/integrations/templates/document-the-template/template-doc-overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/template-doc-overview.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/template-doc-overview: Document the shared fields.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/template-doc-overview#check-how-astryx-lists-it",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/template-doc-overview check-how-astryx-lists-it",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-template-doc-overview#check-how-astryx-lists-it",
+ "placement": "namespace:cli/integrations/templates/document-the-template/template-doc-overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/template-doc-overview.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/template-doc-overview: Check how Astryx lists it.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/document-the-template/page-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/page-template",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-page-template",
+ "placement": "namespace:cli/integrations/templates/document-the-template",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:document-the-template', slot: 'guides', order: 20}.",
+ "rationale": "Page template: Help people find a page: give it a category for `astryx search` and template listings, and flag a sparse starting shell as a scaffold. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/page-template#start-from-the-generated-page-doc",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/page-template start-from-the-generated-page-doc",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-page-template#start-from-the-generated-page-doc",
+ "placement": "namespace:cli/integrations/templates/document-the-template/page-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/page-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/page-template: Start from the generated page doc.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/page-template#help-people-find-the-page",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/page-template help-people-find-the-page",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-page-template#help-people-find-the-page",
+ "placement": "namespace:cli/integrations/templates/document-the-template/page-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/page-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/page-template: Help people find the page.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/document-the-template/block-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/block-template",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-block-template",
+ "placement": "namespace:cli/integrations/templates/document-the-template",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:document-the-template', slot: 'guides', order: 30}.",
+ "rationale": "Block template: Describe a smaller composition, choose its preview shape, and connect it to component examples only when that relationship is real. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/block-template#start-with-a-standalone-block",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/block-template start-with-a-standalone-block",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-block-template#start-with-a-standalone-block",
+ "placement": "namespace:cli/integrations/templates/document-the-template/block-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/block-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/block-template: Start with a standalone block.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/block-template#choose-the-component-relationship",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/block-template choose-the-component-relationship",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-block-template#choose-the-component-relationship",
+ "placement": "namespace:cli/integrations/templates/document-the-template/block-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/block-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/block-template: Choose the component relationship.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/block-template#choose-a-useful-preview",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/block-template choose-a-useful-preview",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-block-template#choose-a-useful-preview",
+ "placement": "namespace:cli/integrations/templates/document-the-template/block-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/block-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/block-template: Choose a useful preview.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/document-the-template/replace-a-core-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/replace-a-core-template",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-replace-a-core-template",
+ "placement": "namespace:cli/integrations/templates/document-the-template",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:document-the-template', slot: 'guides', order: 40}.",
+ "rationale": "Replace a Core template: Use a template replacement only when an integration intentionally changes the default source returned for one Core template id. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/replace-a-core-template#replace-only-on-purpose",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/replace-a-core-template replace-only-on-purpose",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-replace-a-core-template#replace-only-on-purpose",
+ "placement": "namespace:cli/integrations/templates/document-the-template/replace-a-core-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/replace-a-core-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/replace-a-core-template: Replace only on purpose.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/replace-a-core-template#declare-the-replacement",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/replace-a-core-template declare-the-replacement",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-replace-a-core-template#declare-the-replacement",
+ "placement": "namespace:cli/integrations/templates/document-the-template/replace-a-core-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/replace-a-core-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/replace-a-core-template: Declare the replacement.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/replace-a-core-template#require-a-compatible-cli",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/replace-a-core-template require-a-compatible-cli",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-replace-a-core-template#require-a-compatible-cli",
+ "placement": "namespace:cli/integrations/templates/document-the-template/replace-a-core-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/replace-a-core-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/replace-a-core-template: Require a compatible CLI.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/replace-a-core-template#what-apps-receive",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/replace-a-core-template what-apps-receive",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-replace-a-core-template#what-apps-receive",
+ "placement": "namespace:cli/integrations/templates/document-the-template/replace-a-core-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/replace-a-core-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/replace-a-core-template: What apps receive.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/document-the-template/replace-a-core-template#check-the-replacement",
+ "oldCliRoute": "astryx docs cli/integrations/templates/document-the-template/replace-a-core-template check-the-replacement",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-document-the-template-replace-a-core-template#check-the-replacement",
+ "placement": "namespace:cli/integrations/templates/document-the-template/replace-a-core-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/document-the-template/replace-a-core-template.",
+ "rationale": "A section of cli/integrations/templates/document-the-template/replace-a-core-template: Check the replacement.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations/templates/build-the-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/templates/build-the-template",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/build-the-template.doc.mjs declares this namespace and places it with placement {parent: 'namespace:templates', slot: 'build', order: 30}.",
+ "rationale": "Build the template: Make sure your template works when an app copies it: write the template file, set up its styles, fonts, icons, and images, then package and test it. This namespace is new in this change, so it has no older route or docsite page.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/write-the-template-file",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/write-the-template-file",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-write-the-template-file",
+ "placement": "namespace:cli/integrations/templates/build-the-template",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:build-the-template', slot: 'guides', order: 10}.",
+ "rationale": "Write the template file: Astryx copies just this one file into an app, so write it to work on its own there: where it lands, what it can import, and what it exports. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/write-the-template-file#know-what-gets-copied",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/write-the-template-file know-what-gets-copied",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-write-the-template-file#know-what-gets-copied",
+ "placement": "namespace:cli/integrations/templates/build-the-template/write-the-template-file",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/write-the-template-file.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/write-the-template-file: Know what gets copied.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/write-the-template-file#keep-edited-code-in-one-file",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/write-the-template-file keep-edited-code-in-one-file",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-write-the-template-file#keep-edited-code-in-one-file",
+ "placement": "namespace:cli/integrations/templates/build-the-template/write-the-template-file",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/write-the-template-file.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/write-the-template-file: Keep edited code in one file.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/write-the-template-file#use-imports-that-work",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/write-the-template-file use-imports-that-work",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-write-the-template-file#use-imports-that-work-in-the-app",
+ "placement": "namespace:cli/integrations/templates/build-the-template/write-the-template-file",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/write-the-template-file.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/write-the-template-file: Use imports that work in the app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/write-the-template-file#export-one-component",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/write-the-template-file export-one-component",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-write-the-template-file#export-one-component",
+ "placement": "namespace:cli/integrations/templates/build-the-template/write-the-template-file",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/write-the-template-file.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/write-the-template-file: Export one component.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations/templates/build-the-template/template-assets",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/template-assets.doc.mjs declares this namespace and places it with placement {parent: 'namespace:build-the-template', slot: 'guides', order: 20}.",
+ "rationale": "Assets: Make sure the template's styles, fonts, icons, images, and video still show up after an app copies it. This namespace is new in this change, so it has no older route or docsite page.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-assets-overview",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-assets-overview",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-assets-overview",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:template-assets', slot: 'guides', order: 10}.",
+ "rationale": "Asset overview: Decide whether each style, font, icon, image, or video travels in the copied file, stays in your package, or comes from the app. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-assets-overview#choose-the-owner",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-assets-overview choose-the-owner",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-assets-overview#choose-the-owner",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-assets-overview",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-assets-overview.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-assets-overview: Choose the owner.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-styles",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-styles",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:template-assets', slot: 'guides', order: 20}.",
+ "rationale": "Styles: Keep the copied UI on the app's theme: use Astryx props and tokens first, keep editable styles in the file, and ship shared CSS from your package. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-styles#start-with-astryx",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles start-with-astryx",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-styles#start-with-astryx",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-styles",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-styles.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-styles: Start with Astryx.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-styles#keep-editable-styles-with-the-source",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles keep-editable-styles-with-the-source",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-styles#keep-editable-styles-with-the-source",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-styles",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-styles.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-styles: Keep editable styles with the source.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-styles#publish-shared-css",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-styles publish-shared-css",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-styles#publish-shared-css-deliberately",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-styles",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-styles.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-styles: Publish shared CSS deliberately.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-fonts",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-fonts",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:template-assets', slot: 'guides', order: 30}.",
+ "rationale": "Fonts: Keep text in the app's typeface unless the template truly needs its own, and ship every font file it uses when it does. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-fonts#prefer-host-typography",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts prefer-host-typography",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-fonts#prefer-host-typography",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-fonts",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-fonts.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-fonts: Prefer host typography.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-fonts#package-a-required-font",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts package-a-required-font",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-fonts#package-a-required-font",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-fonts",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-fonts.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-fonts: Package a required font.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-fonts#check-fonts-in-the-app",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-fonts check-fonts-in-the-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-fonts#check-fonts-in-the-app",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-fonts",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-fonts.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-fonts: Check fonts in the app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-icons",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-icons",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:template-assets', slot: 'guides', order: 40}.",
+ "rationale": "Icons: Keep icons consistent and accessible by rendering them through Astryx, and ship custom product icons from your package. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-icons#use-astryx-icon",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons use-astryx-icon",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-icons#use-astryx-icon",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-icons",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-icons.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-icons: Use Astryx Icon.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-icons#ship-a-custom-icon",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons ship-a-custom-icon",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-icons#ship-a-custom-icon-deliberately",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-icons",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-icons.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-icons: Ship a custom icon deliberately.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-icons#check-icons-in-the-app",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-icons check-icons-in-the-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-icons#check-icons-in-the-app",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-icons",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-icons.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-icons: Check icons in the app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-images-media",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-images-media",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:template-assets', slot: 'guides', order: 50}.",
+ "rationale": "Images and media: Make sure every image and video still works after the copy, or becomes a clear placeholder the app replaces. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-images-media#do-not-copy-relative-media",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media do-not-copy-relative-media",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-images-media#do-not-rely-on-sibling-media",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-images-media",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-images-media.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-images-media: Do not rely on sibling media.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-images-media#understand-template-assets",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media understand-template-assets",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-images-media#understand-template-assets",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-images-media",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-images-media.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-images-media: Understand `/template-assets`.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-images-media#design-a-useful-placeholder",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media design-a-useful-placeholder",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-images-media#design-a-useful-placeholder",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-images-media",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-images-media.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-images-media: Design a useful placeholder.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/template-assets/template-images-media#check-media-in-the-app",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/template-assets/template-images-media check-media-in-the-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-template-assets-template-images-media#check-media-in-the-app",
+ "placement": "namespace:cli/integrations/templates/build-the-template/template-assets/template-images-media",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/template-assets/template-images-media.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/template-assets/template-images-media: Check media in the app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "namespace",
+ "id": "cli/integrations/templates/build-the-template/package-and-test",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test",
+ "aliasNeeded": false,
+ "evidence": "assets/docs/tree/package-and-test.doc.mjs declares this namespace and places it with placement {parent: 'namespace:build-the-template', slot: 'guides', order: 30}.",
+ "rationale": "Package and test: Publish a package that works the first time: include everything the template needs, check the package before you publish, and try the template in a real app. This namespace is new in this change, so it has no older route or docsite page.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/export-template-assets",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-export-template-assets",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:package-and-test', slot: 'guides', order: 10}.",
+ "rationale": "Export the template and assets: Make sure the published package contains and exposes everything the copied template imports. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/export-template-assets#keep-the-generated-template-export",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets keep-the-generated-template-export",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-export-template-assets#keep-the-generated-template-export",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/export-template-assets",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/export-template-assets.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/export-template-assets: Keep the generated template export.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/export-template-assets#export-package-owned-support-files",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets export-package-owned-support-files",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-export-template-assets#export-package-owned-support-files",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/export-template-assets",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/export-template-assets.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/export-template-assets: Export package-owned support files.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/export-template-assets#include-every-file",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets include-every-file",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-export-template-assets#include-every-file",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/export-template-assets",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/export-template-assets.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/export-template-assets: Include every file.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/export-template-assets#declare-what-the-copied-file-imports",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/export-template-assets declare-what-the-copied-file-imports",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-export-template-assets#declare-what-the-copied-file-imports",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/export-template-assets",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/export-template-assets.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/export-template-assets: Declare what the copied file imports.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/verify-packed-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/verify-packed-template",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-verify-packed-template",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:package-and-test', slot: 'guides', order: 20}.",
+ "rationale": "Verify the packed package: Catch missing files, exports, and CLI requirements before you publish, and know what still needs the app test. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/verify-packed-template#run-the-package-check",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/verify-packed-template run-the-package-check",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-verify-packed-template#run-the-package-check",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/verify-packed-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/verify-packed-template.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/verify-packed-template: Run the package check.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/verify-packed-template#know-what-it-does-not-prove",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/verify-packed-template know-what-it-does-not-prove",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-verify-packed-template#know-what-it-does-not-prove",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/verify-packed-template",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/verify-packed-template.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/verify-packed-template: Know what it does not prove.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/test-template-in-app",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-test-template-in-app",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:package-and-test', slot: 'guides', order: 30}.",
+ "rationale": "Test in an app: Prove the template works the way apps use it: installed from the packed package, copied, built, and rendered. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/test-template-in-app#install-the-packed-package",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app install-the-packed-package",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-test-template-in-app#install-the-packed-package",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/test-template-in-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/test-template-in-app.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/test-template-in-app: Install the packed package.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/test-template-in-app#copy-the-template",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app copy-the-template",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-test-template-in-app#copy-the-template",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/test-template-in-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/test-template-in-app.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/test-template-in-app: Copy the template.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/test-template-in-app#build-every-supported-app",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app build-every-supported-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-test-template-in-app#build-every-supported-app",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/test-template-in-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/test-template-in-app.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/test-template-in-app: Build every supported app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/test-template-in-app#render-the-behavior-matrix",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app render-the-behavior-matrix",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-test-template-in-app#render-the-behavior-matrix",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/test-template-in-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/test-template-in-app.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/test-template-in-app: Render the behavior matrix.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/build-the-template/package-and-test/test-template-in-app#grade-the-result",
+ "oldCliRoute": "astryx docs cli/integrations/templates/build-the-template/package-and-test/test-template-in-app grade-the-result",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-build-the-template-package-and-test-test-template-in-app#grade-the-result",
+ "placement": "namespace:cli/integrations/templates/build-the-template/package-and-test/test-template-in-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/build-the-template/package-and-test/test-template-in-app.",
+ "rationale": "A section of cli/integrations/templates/build-the-template/package-and-test/test-template-in-app: Grade the result.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/template-quality",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-quality",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-quality",
+ "placement": "namespace:cli/integrations/templates",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:templates', slot: 'quality', order: 10}.",
+ "rationale": "Quality overview: Learn what makes a template useful, reliable, and ready to publish, and review those qualities throughout authoring. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-quality#what-good-means",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-quality what-good-means",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-quality#what-good-means",
+ "placement": "namespace:cli/integrations/templates/template-quality",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-quality.",
+ "rationale": "A section of cli/integrations/templates/template-quality: What good means.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-quality#understand-the-score",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-quality understand-the-score",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-quality#understand-the-score",
+ "placement": "namespace:cli/integrations/templates/template-quality",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-quality.",
+ "rationale": "A section of cli/integrations/templates/template-quality: Understand the score.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-quality#review-while-you-build",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-quality review-while-you-build",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-quality#review-while-you-build",
+ "placement": "namespace:cli/integrations/templates/template-quality",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-quality.",
+ "rationale": "A section of cli/integrations/templates/template-quality: Review while you build.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/template-grading-rubric",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric",
+ "placement": "namespace:cli/integrations/templates",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:templates', slot: 'quality', order: 20}.",
+ "rationale": "Full grading rubric: Use a shared set of heuristics to score template quality consistently across Astryx usage, icons, CSS, layout, metadata, images, and code quality. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-grading-rubric#component-purity",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric component-purity",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric#astryx-component-purity-30-points",
+ "placement": "namespace:cli/integrations/templates/template-grading-rubric",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-grading-rubric.",
+ "rationale": "A section of cli/integrations/templates/template-grading-rubric: Astryx component purity: 30 points.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-grading-rubric#icon-purity",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric icon-purity",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric#icon-purity-15-points",
+ "placement": "namespace:cli/integrations/templates/template-grading-rubric",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-grading-rubric.",
+ "rationale": "A section of cli/integrations/templates/template-grading-rubric: Icon purity: 15 points.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-grading-rubric#custom-css",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric custom-css",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric#custom-css-15-points",
+ "placement": "namespace:cli/integrations/templates/template-grading-rubric",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-grading-rubric.",
+ "rationale": "A section of cli/integrations/templates/template-grading-rubric: Custom CSS: 15 points.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-grading-rubric#layout-and-structure",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric layout-and-structure",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric#layout-and-structure-15-points",
+ "placement": "namespace:cli/integrations/templates/template-grading-rubric",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-grading-rubric.",
+ "rationale": "A section of cli/integrations/templates/template-grading-rubric: Layout and structure: 15 points.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-grading-rubric#doc-metadata",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric doc-metadata",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric#doc-metadata-10-points",
+ "placement": "namespace:cli/integrations/templates/template-grading-rubric",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-grading-rubric.",
+ "rationale": "A section of cli/integrations/templates/template-grading-rubric: Doc metadata: 10 points.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-grading-rubric#image-handling",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric image-handling",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric#image-handling-5-points",
+ "placement": "namespace:cli/integrations/templates/template-grading-rubric",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-grading-rubric.",
+ "rationale": "A section of cli/integrations/templates/template-grading-rubric: Image handling: 5 points.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/template-grading-rubric#code-quality",
+ "oldCliRoute": "astryx docs cli/integrations/templates/template-grading-rubric code-quality",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-template-grading-rubric#code-quality-10-points",
+ "placement": "namespace:cli/integrations/templates/template-grading-rubric",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/template-grading-rubric.",
+ "rationale": "A section of cli/integrations/templates/template-grading-rubric: Code quality: 10 points.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/templates/grade-template-with-agent",
+ "oldCliRoute": "astryx docs cli/integrations/templates/grade-template-with-agent",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-grade-template-with-agent",
+ "placement": "namespace:cli/integrations/templates",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:templates', slot: 'quality', order: 30}.",
+ "rationale": "Grade and improve with an agent: Give an agent the rubric and evidence it needs to find problems, produce a reproducible scorecard, and improve the template. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/grade-template-with-agent#give-the-agent-the-rubric",
+ "oldCliRoute": "astryx docs cli/integrations/templates/grade-template-with-agent give-the-agent-the-rubric",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-grade-template-with-agent#give-the-agent-the-rubric",
+ "placement": "namespace:cli/integrations/templates/grade-template-with-agent",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/grade-template-with-agent.",
+ "rationale": "A section of cli/integrations/templates/grade-template-with-agent: Give the agent the rubric.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/grade-template-with-agent#require-a-scorecard",
+ "oldCliRoute": "astryx docs cli/integrations/templates/grade-template-with-agent require-a-scorecard",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-grade-template-with-agent#require-a-scorecard",
+ "placement": "namespace:cli/integrations/templates/grade-template-with-agent",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/grade-template-with-agent.",
+ "rationale": "A section of cli/integrations/templates/grade-template-with-agent: Require a scorecard.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/templates/grade-template-with-agent#improve-and-regrade",
+ "oldCliRoute": "astryx docs cli/integrations/templates/grade-template-with-agent improve-and-regrade",
+ "oldDocsiteUrl": "/docs/cli-integrations-templates-grade-template-with-agent#improve-and-regrade",
+ "placement": "namespace:cli/integrations/templates/grade-template-with-agent",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/templates/grade-template-with-agent.",
+ "rationale": "A section of cli/integrations/templates/grade-template-with-agent: Improve and regrade.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/themes",
+ "oldCliRoute": "astryx docs cli/integrations/themes",
+ "oldDocsiteUrl": "/docs/cli-integrations-themes",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'contribute', order: 30}.",
+ "rationale": "Themes: Ship an editable source theme with a generated palette that apps copy into their code and build. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/themes#add-a-theme",
+ "oldCliRoute": "astryx docs cli/integrations/themes add-a-theme",
+ "oldDocsiteUrl": "/docs/cli-integrations-themes#add-a-theme",
+ "placement": "namespace:cli/integrations/themes",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/themes.",
+ "rationale": "A section of cli/integrations/themes: Add a theme.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/themes#generate-a-palette",
+ "oldCliRoute": "astryx docs cli/integrations/themes generate-a-palette",
+ "oldDocsiteUrl": "/docs/cli-integrations-themes#generate-a-palette",
+ "placement": "namespace:cli/integrations/themes",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/themes.",
+ "rationale": "A section of cli/integrations/themes: Generate a palette.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/themes#use-the-palette",
+ "oldCliRoute": "astryx docs cli/integrations/themes use-the-palette",
+ "oldDocsiteUrl": "/docs/cli-integrations-themes#use-the-palette-in-the-theme",
+ "placement": "namespace:cli/integrations/themes",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/themes.",
+ "rationale": "A section of cli/integrations/themes: Use the palette in the theme.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/themes#use-a-theme-in-an-app",
+ "oldCliRoute": "astryx docs cli/integrations/themes use-a-theme-in-an-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-themes#use-the-theme-in-an-app",
+ "placement": "namespace:cli/integrations/themes",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/themes.",
+ "rationale": "A section of cli/integrations/themes: Use the theme in an app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/themes#themes-on-older-clis",
+ "oldCliRoute": "astryx docs cli/integrations/themes themes-on-older-clis",
+ "oldDocsiteUrl": "/docs/cli-integrations-themes#fix-missing-themes-on-older-clis",
+ "placement": "namespace:cli/integrations/themes",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/themes.",
+ "rationale": "A section of cli/integrations/themes: Fix missing themes on older CLIs.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/codemods",
+ "oldCliRoute": "astryx docs cli/integrations/codemods",
+ "oldDocsiteUrl": "/docs/cli-integrations-codemods",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'contribute', order: 50}.",
+ "rationale": "Codemods: Ship codemods that `astryx upgrade` runs to migrate app code, and know which of them an app runs. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/codemods#add-a-codemod",
+ "oldCliRoute": "astryx docs cli/integrations/codemods add-a-codemod",
+ "oldDocsiteUrl": "/docs/cli-integrations-codemods#add-a-codemod",
+ "placement": "namespace:cli/integrations/codemods",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/codemods.",
+ "rationale": "A section of cli/integrations/codemods: Add a codemod.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/codemods#write-the-transform",
+ "oldCliRoute": "astryx docs cli/integrations/codemods write-the-transform",
+ "oldDocsiteUrl": "/docs/cli-integrations-codemods#write-the-transform",
+ "placement": "namespace:cli/integrations/codemods",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/codemods.",
+ "rationale": "A section of cli/integrations/codemods: Write the transform.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/codemods#which-codemods-run",
+ "oldCliRoute": "astryx docs cli/integrations/codemods which-codemods-run",
+ "oldDocsiteUrl": "/docs/cli-integrations-codemods#choose-when-a-codemod-runs",
+ "placement": "namespace:cli/integrations/codemods",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/codemods.",
+ "rationale": "A section of cli/integrations/codemods: Choose when a codemod runs.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/codemods#run-codemods-in-an-app",
+ "oldCliRoute": "astryx docs cli/integrations/codemods run-codemods-in-an-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-codemods#run-codemods-in-an-app",
+ "placement": "namespace:cli/integrations/codemods",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/codemods.",
+ "rationale": "A section of cli/integrations/codemods: Run codemods in an app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/agent-guidance",
+ "oldCliRoute": "astryx docs cli/integrations/agent-guidance",
+ "oldDocsiteUrl": "/docs/cli-integrations-agent-guidance",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'contribute', order: 60}.",
+ "rationale": "Agent guidance: Add a few lines of guidance that apps put in front of the AI agents working in their code. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/agent-guidance#add-a-guidance-line",
+ "oldCliRoute": "astryx docs cli/integrations/agent-guidance add-a-guidance-line",
+ "oldDocsiteUrl": "/docs/cli-integrations-agent-guidance#add-a-line-of-guidance",
+ "placement": "namespace:cli/integrations/agent-guidance",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/agent-guidance.",
+ "rationale": "A section of cli/integrations/agent-guidance: Add a line of guidance.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/agent-guidance#keep-within-the-limits",
+ "oldCliRoute": "astryx docs cli/integrations/agent-guidance keep-within-the-limits",
+ "oldDocsiteUrl": "/docs/cli-integrations-agent-guidance#keep-within-the-limits",
+ "placement": "namespace:cli/integrations/agent-guidance",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/agent-guidance.",
+ "rationale": "A section of cli/integrations/agent-guidance: Keep within the limits.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/agent-guidance#see-what-agents-read",
+ "oldCliRoute": "astryx docs cli/integrations/agent-guidance see-what-agents-read",
+ "oldDocsiteUrl": "/docs/cli-integrations-agent-guidance#see-what-agents-read",
+ "placement": "namespace:cli/integrations/agent-guidance",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/agent-guidance.",
+ "rationale": "A section of cli/integrations/agent-guidance: See what agents read.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/agent-guidance#refresh-the-block",
+ "oldCliRoute": "astryx docs cli/integrations/agent-guidance refresh-the-block",
+ "oldDocsiteUrl": "/docs/cli-integrations-agent-guidance#refresh-the-block-in-an-app",
+ "placement": "namespace:cli/integrations/agent-guidance",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/agent-guidance.",
+ "rationale": "A section of cli/integrations/agent-guidance: Refresh the block in an app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/debug-and-gap-reports",
+ "oldCliRoute": "astryx docs cli/integrations/debug-and-gap-reports",
+ "oldDocsiteUrl": "/docs/cli-integrations-debug-and-gap-reports",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'contribute', order: 70}.",
+ "rationale": "Debug and gap reports: Receive a record of each CLI run in apps that use your package, and handle the gap reports they send about it. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/debug-and-gap-reports#record-runs-with-debug",
+ "oldCliRoute": "astryx docs cli/integrations/debug-and-gap-reports record-runs-with-debug",
+ "oldDocsiteUrl": "/docs/cli-integrations-debug-and-gap-reports#record-runs-with-debug",
+ "placement": "namespace:cli/integrations/debug-and-gap-reports",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/debug-and-gap-reports.",
+ "rationale": "A section of cli/integrations/debug-and-gap-reports: Record runs with debug.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/debug-and-gap-reports#turn-off-debug-in-an-app",
+ "oldCliRoute": "astryx docs cli/integrations/debug-and-gap-reports turn-off-debug-in-an-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-debug-and-gap-reports#turn-off-debug-in-an-app",
+ "placement": "namespace:cli/integrations/debug-and-gap-reports",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/debug-and-gap-reports.",
+ "rationale": "A section of cli/integrations/debug-and-gap-reports: Turn off debug in an app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/debug-and-gap-reports#handle-gap-reports",
+ "oldCliRoute": "astryx docs cli/integrations/debug-and-gap-reports handle-gap-reports",
+ "oldDocsiteUrl": "/docs/cli-integrations-debug-and-gap-reports#handle-gap-reports",
+ "placement": "namespace:cli/integrations/debug-and-gap-reports",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/debug-and-gap-reports.",
+ "rationale": "A section of cli/integrations/debug-and-gap-reports: Handle gap reports.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/debug-and-gap-reports#ask-before-filing-in-public",
+ "oldCliRoute": "astryx docs cli/integrations/debug-and-gap-reports ask-before-filing-in-public",
+ "oldDocsiteUrl": "/docs/cli-integrations-debug-and-gap-reports#ask-before-filing-in-public",
+ "placement": "namespace:cli/integrations/debug-and-gap-reports",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/debug-and-gap-reports.",
+ "rationale": "A section of cli/integrations/debug-and-gap-reports: Ask before filing in public.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/debug-and-gap-reports#fall-back-to-issues-url",
+ "oldCliRoute": "astryx docs cli/integrations/debug-and-gap-reports fall-back-to-issues-url",
+ "oldDocsiteUrl": "/docs/cli-integrations-debug-and-gap-reports#fall-back-to-issuesurl",
+ "placement": "namespace:cli/integrations/debug-and-gap-reports",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/debug-and-gap-reports.",
+ "rationale": "A section of cli/integrations/debug-and-gap-reports: Fall back to issuesUrl.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/test-in-an-app",
+ "oldCliRoute": "astryx docs cli/integrations/test-in-an-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-test-in-an-app",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'ship', order: 10}.",
+ "rationale": "Test an integration in an app: Install your packed package in an app and run the commands its users will run. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/test-in-an-app#install-the-tarball",
+ "oldCliRoute": "astryx docs cli/integrations/test-in-an-app install-the-tarball",
+ "oldDocsiteUrl": "/docs/cli-integrations-test-in-an-app#install-the-tarball-in-an-app",
+ "placement": "namespace:cli/integrations/test-in-an-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/test-in-an-app.",
+ "rationale": "A section of cli/integrations/test-in-an-app: Install the tarball in an app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/test-in-an-app#check-what-the-app-sees",
+ "oldCliRoute": "astryx docs cli/integrations/test-in-an-app check-what-the-app-sees",
+ "oldDocsiteUrl": "/docs/cli-integrations-test-in-an-app#check-what-the-app-sees",
+ "placement": "namespace:cli/integrations/test-in-an-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/test-in-an-app.",
+ "rationale": "A section of cli/integrations/test-in-an-app: Check what the app sees.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/test-in-an-app#run-doctor-in-the-app",
+ "oldCliRoute": "astryx docs cli/integrations/test-in-an-app run-doctor-in-the-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-test-in-an-app#run-doctor-in-the-app",
+ "placement": "namespace:cli/integrations/test-in-an-app",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/test-in-an-app.",
+ "rationale": "A section of cli/integrations/test-in-an-app: Run doctor in the app.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/checks",
+ "oldCliRoute": "astryx docs cli/integrations/checks",
+ "oldDocsiteUrl": "/docs/cli-integrations-checks",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'ship', order: 20}.",
+ "rationale": "Check an integration: Pick the check for each problem, learn what fails and what only warns, and run every check in CI. New in this change, so it has no older route.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/checks#pick-a-check",
+ "oldCliRoute": "astryx docs cli/integrations/checks pick-a-check",
+ "oldDocsiteUrl": "/docs/cli-integrations-checks#pick-a-check",
+ "placement": "namespace:cli/integrations/checks",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/checks.",
+ "rationale": "A section of cli/integrations/checks: Pick a check.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/checks#run-every-check-in-ci",
+ "oldCliRoute": "astryx docs cli/integrations/checks run-every-check-in-ci",
+ "oldDocsiteUrl": "/docs/cli-integrations-checks#run-every-check-in-ci",
+ "placement": "namespace:cli/integrations/checks",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/checks.",
+ "rationale": "A section of cli/integrations/checks: Run every check in CI.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "cli/integrations/checks#what-integration-verify-does",
+ "oldCliRoute": "astryx docs cli/integrations/checks what-integration-verify-does",
+ "oldDocsiteUrl": "/docs/cli-integrations-checks#verify-the-packed-package",
+ "placement": "namespace:cli/integrations/checks",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/checks.",
+ "rationale": "A section of cli/integrations/checks: Verify the packed package.",
"status": "proposed"
},
{
- "kind": "namespace",
- "id": "cli/commands",
- "oldCliRoute": "astryx docs cli/commands",
- "oldDocsiteUrl": null,
- "placement": "namespace:cli/commands",
+ "kind": "topic",
+ "id": "cli/integrations/versioning",
+ "oldCliRoute": "astryx docs cli/integrations/versioning",
+ "oldDocsiteUrl": "/docs/cli-integrations-versioning",
+ "placement": "namespace:cli/integrations",
"aliasNeeded": false,
- "evidence": "assets/docs/tree/commands.doc.mjs declares it.",
- "rationale": "Adopts every command doc whose namespace is cli/commands, one leaf each at cli/commands/<name>. The docsite does not publish it yet.",
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'ship', order: 30}.",
+ "rationale": "Versioning: Version your package, declare its peers, and keep apps on older CLIs working. New in this change, so it has no older route.",
"status": "proposed"
},
{
- "kind": "namespace",
- "id": "cli/api",
- "oldCliRoute": "astryx docs cli/api",
- "oldDocsiteUrl": null,
- "placement": "namespace:cli/api",
+ "kind": "section",
+ "id": "cli/integrations/versioning#pick-a-version",
+ "oldCliRoute": "astryx docs cli/integrations/versioning pick-a-version",
+ "oldDocsiteUrl": "/docs/cli-integrations-versioning#pick-a-version",
+ "placement": "namespace:cli/integrations/versioning",
"aliasNeeded": false,
- "evidence": "assets/docs/tree/api.doc.mjs declares it.",
- "rationale": "Adopts every function, schema, and enum doc whose namespace is cli/api, one generated level per kind. The docsite does not publish it yet.",
+ "evidence": "Moves with cli/integrations/versioning.",
+ "rationale": "A section of cli/integrations/versioning: Pick a version.",
"status": "proposed"
},
{
- "kind": "namespace",
- "id": "cli/api/functions",
- "oldCliRoute": "astryx docs cli/api/functions",
- "oldDocsiteUrl": null,
- "placement": "namespace:cli/api/functions",
+ "kind": "section",
+ "id": "cli/integrations/versioning#know-what-breaks-apps",
+ "oldCliRoute": "astryx docs cli/integrations/versioning know-what-breaks-apps",
+ "oldDocsiteUrl": "/docs/cli-integrations-versioning#know-what-breaks-apps",
+ "placement": "namespace:cli/integrations/versioning",
"aliasNeeded": false,
- "evidence": "The api namespace adopts cli/api with groupBy kind.",
- "rationale": "Generated by the api namespace for its function docs, one leaf each at cli/api/functions/<name>. The docsite does not publish it yet.",
+ "evidence": "Moves with cli/integrations/versioning.",
+ "rationale": "A section of cli/integrations/versioning: Know what breaks apps.",
"status": "proposed"
},
{
- "kind": "namespace",
- "id": "cli/api/schemas",
- "oldCliRoute": "astryx docs cli/api/schemas",
- "oldDocsiteUrl": null,
- "placement": "namespace:cli/api/schemas",
+ "kind": "section",
+ "id": "cli/integrations/versioning#declare-peer-ranges",
+ "oldCliRoute": "astryx docs cli/integrations/versioning declare-peer-ranges",
+ "oldDocsiteUrl": "/docs/cli-integrations-versioning#declare-peer-ranges",
+ "placement": "namespace:cli/integrations/versioning",
"aliasNeeded": false,
- "evidence": "The api namespace adopts cli/api with groupBy kind.",
- "rationale": "Generated by the api namespace for its schema docs (the JSON output envelope). The docsite does not publish it yet.",
+ "evidence": "Moves with cli/integrations/versioning.",
+ "rationale": "A section of cli/integrations/versioning: Declare peer ranges.",
"status": "proposed"
},
{
- "kind": "namespace",
- "id": "cli/api/enums",
- "oldCliRoute": "astryx docs cli/api/enums",
- "oldDocsiteUrl": null,
- "placement": "namespace:cli/api/enums",
+ "kind": "section",
+ "id": "cli/integrations/versioning#support-older-clis",
+ "oldCliRoute": "astryx docs cli/integrations/versioning support-older-clis",
+ "oldDocsiteUrl": "/docs/cli-integrations-versioning#support-older-clis",
+ "placement": "namespace:cli/integrations/versioning",
"aliasNeeded": false,
- "evidence": "The api namespace adopts cli/api with groupBy kind.",
- "rationale": "Generated by the api namespace for its enum docs (error codes and response types). The docsite does not publish it yet.",
+ "evidence": "Moves with cli/integrations/versioning.",
+ "rationale": "A section of cli/integrations/versioning: Support older CLIs.",
"status": "proposed"
},
{
- "kind": "namespace",
- "id": "unorganized",
- "oldCliRoute": "astryx docs unorganized",
- "oldDocsiteUrl": null,
- "placement": "namespace:unorganized",
+ "kind": "section",
+ "id": "cli/integrations/versioning#codemods-and-versions",
+ "oldCliRoute": "astryx docs cli/integrations/versioning codemods-and-versions",
+ "oldDocsiteUrl": "/docs/cli-integrations-versioning#name-codemod-folders-after-core-versions",
+ "placement": "namespace:cli/integrations/versioning",
"aliasNeeded": false,
- "evidence": "The docs tree generates it: every flat topic sits in it, in the order the topic list reads.",
- "rationale": "The home of every topic that no section places yet. Each keeps its own name, so no route changes; placing a topic in a real section takes it out.",
+ "evidence": "Moves with cli/integrations/versioning.",
+ "rationale": "A section of cli/integrations/versioning: Name codemod folders after Core versions.",
"status": "proposed"
},
{
"kind": "topic",
- "id": "browser-support",
- "oldCliRoute": "astryx docs browser-support",
- "oldDocsiteUrl": "/docs/browser-support",
- "placement": "keep-flat",
+ "id": "cli/integrations/publishing",
+ "oldCliRoute": "astryx docs cli/integrations/publishing",
+ "oldDocsiteUrl": "/docs/cli-integrations-publishing",
+ "placement": "namespace:cli/integrations",
"aliasNeeded": false,
- "rationale": "Standalone guide: no topic links to it, and nothing authored places it under another topic.",
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'ship', order: 40}.",
+ "rationale": "Publish an integration: Publish your package to npm under the right release tag, and check it before and after. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "browser-support#overview",
- "oldCliRoute": "astryx docs browser-support overview",
- "oldDocsiteUrl": "/docs/browser-support#overview",
- "placement": "keep-flat",
+ "id": "cli/integrations/publishing#check-before-you-publish",
+ "oldCliRoute": "astryx docs cli/integrations/publishing check-before-you-publish",
+ "oldDocsiteUrl": "/docs/cli-integrations-publishing#check-before-you-publish",
+ "placement": "namespace:cli/integrations/publishing",
"aliasNeeded": false,
- "rationale": "Stays a section of browser-support under the same key.",
+ "evidence": "Moves with cli/integrations/publishing.",
+ "rationale": "A section of cli/integrations/publishing: Check before you publish.",
"status": "proposed"
},
{
"kind": "section",
- "id": "browser-support#support-tiers",
- "oldCliRoute": "astryx docs browser-support support-tiers",
- "oldDocsiteUrl": "/docs/browser-support#support-tiers",
- "placement": "keep-flat",
+ "id": "cli/integrations/publishing#keep-private-files-out",
+ "oldCliRoute": "astryx docs cli/integrations/publishing keep-private-files-out",
+ "oldDocsiteUrl": "/docs/cli-integrations-publishing#keep-private-files-out",
+ "placement": "namespace:cli/integrations/publishing",
"aliasNeeded": false,
- "rationale": "Stays a section of browser-support under the same key.",
+ "evidence": "Moves with cli/integrations/publishing.",
+ "rationale": "A section of cli/integrations/publishing: Keep private files out.",
"status": "proposed"
},
{
"kind": "section",
- "id": "browser-support#which-features-set-the-floor",
- "oldCliRoute": "astryx docs browser-support which-features-set-the-floor",
- "oldDocsiteUrl": "/docs/browser-support#which-features-set-the-floor",
- "placement": "keep-flat",
+ "id": "cli/integrations/publishing#publish-to-npm",
+ "oldCliRoute": "astryx docs cli/integrations/publishing publish-to-npm",
+ "oldDocsiteUrl": "/docs/cli-integrations-publishing#publish-to-npm",
+ "placement": "namespace:cli/integrations/publishing",
"aliasNeeded": false,
- "rationale": "Stays a section of browser-support under the same key.",
+ "evidence": "Moves with cli/integrations/publishing.",
+ "rationale": "A section of cli/integrations/publishing: Publish to npm.",
"status": "proposed"
},
{
"kind": "section",
- "id": "browser-support#which-components-are-affected",
- "oldCliRoute": "astryx docs browser-support which-components-are-affected",
- "oldDocsiteUrl": "/docs/browser-support#which-components-are-affected",
- "placement": "keep-flat",
+ "id": "cli/integrations/publishing#check-the-published-package",
+ "oldCliRoute": "astryx docs cli/integrations/publishing check-the-published-package",
+ "oldDocsiteUrl": "/docs/cli-integrations-publishing#check-the-published-package",
+ "placement": "namespace:cli/integrations/publishing",
"aliasNeeded": false,
- "rationale": "Stays a section of browser-support under the same key.",
+ "evidence": "Moves with cli/integrations/publishing.",
+ "rationale": "A section of cli/integrations/publishing: Check the published package.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/upgrading",
+ "oldCliRoute": "astryx docs cli/integrations/upgrading",
+ "oldDocsiteUrl": "/docs/cli-integrations-upgrading",
+ "placement": "namespace:cli/integrations",
+ "aliasNeeded": false,
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'ship', order: 50}.",
+ "rationale": "Upgrading: Update your package for each Astryx release, and help apps upgrade with it. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "browser-support#what-astryx-guarantees",
- "oldCliRoute": "astryx docs browser-support what-astryx-guarantees",
- "oldDocsiteUrl": "/docs/browser-support#what-astryx-guarantees",
- "placement": "keep-flat",
+ "id": "cli/integrations/upgrading#update-for-a-new-astryx-release",
+ "oldCliRoute": "astryx docs cli/integrations/upgrading update-for-a-new-astryx-release",
+ "oldDocsiteUrl": "/docs/cli-integrations-upgrading#update-for-a-new-astryx-release",
+ "placement": "namespace:cli/integrations/upgrading",
"aliasNeeded": false,
- "rationale": "Stays a section of browser-support under the same key.",
+ "evidence": "Moves with cli/integrations/upgrading.",
+ "rationale": "A section of cli/integrations/upgrading: Update for a new Astryx release.",
"status": "proposed"
},
{
"kind": "section",
- "id": "browser-support#supporting-older-browsers",
- "oldCliRoute": "astryx docs browser-support supporting-older-browsers",
- "oldDocsiteUrl": "/docs/browser-support#supporting-older-browsers",
- "placement": "keep-flat",
+ "id": "cli/integrations/upgrading#upgrade-an-app",
+ "oldCliRoute": "astryx docs cli/integrations/upgrading upgrade-an-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-upgrading#upgrade-an-app",
+ "placement": "namespace:cli/integrations/upgrading",
"aliasNeeded": false,
- "rationale": "Stays a section of browser-support under the same key.",
+ "evidence": "Moves with cli/integrations/upgrading.",
+ "rationale": "A section of cli/integrations/upgrading: Upgrade an app.",
"status": "proposed"
},
{
"kind": "section",
- "id": "browser-support#how-these-tiers-move-over-time",
- "oldCliRoute": "astryx docs browser-support how-these-tiers-move-over-time",
- "oldDocsiteUrl": "/docs/browser-support#how-these-tiers-move-over-time",
- "placement": "keep-flat",
+ "id": "cli/integrations/upgrading#know-which-files-upgrades-skip",
+ "oldCliRoute": "astryx docs cli/integrations/upgrading know-which-files-upgrades-skip",
+ "oldDocsiteUrl": "/docs/cli-integrations-upgrading#know-which-files-upgrades-skip",
+ "placement": "namespace:cli/integrations/upgrading",
"aliasNeeded": false,
- "rationale": "Stays a section of browser-support under the same key.",
+ "evidence": "Moves with cli/integrations/upgrading.",
+ "rationale": "A section of cli/integrations/upgrading: Know which files upgrades skip.",
"status": "proposed"
},
{
"kind": "topic",
- "id": "cli/component-lookups",
- "oldCliRoute": "astryx docs cli/component-lookups",
- "oldDocsiteUrl": "/docs/cli-component-lookups",
- "placement": "namespace:cli/component-lookups",
+ "id": "cli/integrations/troubleshooting",
+ "oldCliRoute": "astryx docs cli/integrations/troubleshooting",
+ "oldDocsiteUrl": "/docs/cli-integrations-troubleshooting",
+ "placement": "namespace:cli/integrations",
"aliasNeeded": false,
- "evidence": "It places itself: placement {parent: 'namespace:cli', slot: 'guides'}. Its four sections document the component command's exact selectors, batch receipt, exit status and programmatic API.",
- "rationale": "Caller guide for exact single and batch component lookup. This is a new route, so no previous CLI or docsite identity needs an alias.",
+ "evidence": "It places itself: placement {parent: 'namespace:integrations', slot: 'help', order: 10}.",
+ "rationale": "Troubleshooting: Find the message the CLI printed while you build, verify, or install an integration, and apply its fix. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/component-lookups#several",
- "oldCliRoute": "astryx docs cli/component-lookups several",
- "oldDocsiteUrl": "/docs/cli-component-lookups#look-up-several-components",
- "placement": "namespace:cli/component-lookups",
+ "id": "cli/integrations/troubleshooting#fix-setup-errors",
+ "oldCliRoute": "astryx docs cli/integrations/troubleshooting fix-setup-errors",
+ "oldDocsiteUrl": "/docs/cli-integrations-troubleshooting#fix-setup-errors",
+ "placement": "namespace:cli/integrations/troubleshooting",
"aliasNeeded": false,
- "evidence": "Moves with cli/component-lookups.",
- "rationale": "Stays a section of cli/component-lookups under the stable key several.",
+ "evidence": "Moves with cli/integrations/troubleshooting.",
+ "rationale": "A section of cli/integrations/troubleshooting: Fix setup errors.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/component-lookups#selectors",
- "oldCliRoute": "astryx docs cli/component-lookups selectors",
- "oldDocsiteUrl": "/docs/cli-component-lookups#selector-forms",
- "placement": "namespace:cli/component-lookups",
+ "id": "cli/integrations/troubleshooting#fix-verify-failures",
+ "oldCliRoute": "astryx docs cli/integrations/troubleshooting fix-verify-failures",
+ "oldDocsiteUrl": "/docs/cli-integrations-troubleshooting#fix-integration-verify-failures",
+ "placement": "namespace:cli/integrations/troubleshooting",
"aliasNeeded": false,
- "evidence": "Moves with cli/component-lookups.",
- "rationale": "Stays a section of cli/component-lookups under the stable key selectors.",
+ "evidence": "Moves with cli/integrations/troubleshooting.",
+ "rationale": "A section of cli/integrations/troubleshooting: Fix integration verify failures.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/component-lookups#output",
- "oldCliRoute": "astryx docs cli/component-lookups output",
- "oldDocsiteUrl": "/docs/cli-component-lookups#batch-output-and-exit-status",
- "placement": "namespace:cli/component-lookups",
+ "id": "cli/integrations/troubleshooting#fix-problems-in-an-app",
+ "oldCliRoute": "astryx docs cli/integrations/troubleshooting fix-problems-in-an-app",
+ "oldDocsiteUrl": "/docs/cli-integrations-troubleshooting#fix-problems-in-an-app",
+ "placement": "namespace:cli/integrations/troubleshooting",
"aliasNeeded": false,
- "evidence": "Moves with cli/component-lookups.",
- "rationale": "Stays a section of cli/component-lookups under the stable key output.",
+ "evidence": "Moves with cli/integrations/troubleshooting.",
+ "rationale": "A section of cli/integrations/troubleshooting: Fix problems in an app.",
"status": "proposed"
},
{
- "kind": "section",
- "id": "cli/component-lookups#api",
- "oldCliRoute": "astryx docs cli/component-lookups api",
- "oldDocsiteUrl": "/docs/cli-component-lookups#programmatic-api",
- "placement": "namespace:cli/component-lookups",
+ "kind": "namespace",
+ "id": "cli/integrations/docs",
+ "oldCliRoute": "astryx docs cli/integrations/docs",
+ "oldDocsiteUrl": null,
+ "placement": "namespace:cli/integrations/docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/component-lookups.",
- "rationale": "Stays a section of cli/component-lookups under the stable key api.",
+ "evidence": "assets/docs/tree/docs.doc.mjs declares it, and places it in cli/integrations' contribute slot.",
+ "rationale": "The guides to writing docs for an integration package. They replace cli/writing-docs, whose docsite page /docs/cli-writing-docs redirects to cli/integrations/docs/add-a-topic. The docsite does not publish the namespace itself yet.",
"status": "proposed"
},
{
"kind": "topic",
- "id": "cli/integrations",
- "oldCliRoute": "astryx docs cli/integrations",
- "oldDocsiteUrl": "/docs/cli-integrations",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/add-a-topic",
+ "oldCliRoute": "astryx docs cli/integrations/docs/add-a-topic",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-add-a-topic",
+ "placement": "namespace:cli/integrations/docs",
"aliasNeeded": false,
- "evidence": "It places itself: placement {parent: 'namespace:cli', slot: 'guides'}. Its subject is the CLI's integration surface: 10 of its 14 sections drive `astryx integration add|pack`, `astryx doctor integration ...`, `astryx init` or `astryx upgrade`.",
- "rationale": "Guide for integration authors, read only by its route. `astryx docs cli-integrations` is gone: every reference now names cli/integrations. The docsite keeps /docs/cli-integrations (its route with \"/\" as \"-\") until the site renders the tree.",
+ "evidence": "It places itself: placement {parent: 'namespace:docs', slot: 'guides', order: 10}.",
+ "rationale": "Add a topic: Add a doc topic to your package and write its sections. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#overview",
- "oldCliRoute": "astryx docs cli/integrations overview",
- "oldDocsiteUrl": "/docs/cli-integrations#overview",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/add-a-topic#add-a-topic-with-the-cli",
+ "oldCliRoute": "astryx docs cli/integrations/docs/add-a-topic add-a-topic-with-the-cli",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-add-a-topic#add-a-topic-with-the-cli",
+ "placement": "namespace:cli/integrations/docs/add-a-topic",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/add-a-topic.",
+ "rationale": "A section of cli/integrations/docs/add-a-topic: Add a topic with the CLI.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#authoring-with-the-cli",
- "oldCliRoute": "astryx docs cli/integrations authoring-with-the-cli",
- "oldDocsiteUrl": "/docs/cli-integrations#authoring-with-the-cli",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/add-a-topic#write-the-sections",
+ "oldCliRoute": "astryx docs cli/integrations/docs/add-a-topic write-the-sections",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-add-a-topic#write-the-sections",
+ "placement": "namespace:cli/integrations/docs/add-a-topic",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/add-a-topic.",
+ "rationale": "A section of cli/integrations/docs/add-a-topic: Write the sections.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#theme-package-walkthrough",
- "oldCliRoute": "astryx docs cli/integrations theme-package-walkthrough",
- "oldDocsiteUrl": "/docs/cli-integrations#theme-package-walkthrough",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/add-a-topic#pick-the-doc-kind",
+ "oldCliRoute": "astryx docs cli/integrations/docs/add-a-topic pick-the-doc-kind",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-add-a-topic#pick-the-doc-kind",
+ "placement": "namespace:cli/integrations/docs/add-a-topic",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/add-a-topic.",
+ "rationale": "A section of cli/integrations/docs/add-a-topic: Pick the doc kind.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#contribution-kinds-at-a-glance",
- "oldCliRoute": "astryx docs cli/integrations contribution-kinds-at-a-glance",
- "oldDocsiteUrl": "/docs/cli-integrations#contribution-kinds-at-a-glance",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/add-a-topic#keep-topics-in-the-docs-root",
+ "oldCliRoute": "astryx docs cli/integrations/docs/add-a-topic keep-topics-in-the-docs-root",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-add-a-topic#keep-topics-in-the-docs-root",
+ "placement": "namespace:cli/integrations/docs/add-a-topic",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/add-a-topic.",
+ "rationale": "A section of cli/integrations/docs/add-a-topic: Keep topics in the docs root.",
"status": "proposed"
},
{
- "kind": "section",
- "id": "cli/integrations#the-integration-file",
- "oldCliRoute": "astryx docs cli/integrations the-integration-file",
- "oldDocsiteUrl": "/docs/cli-integrations#the-integration-file",
- "placement": "namespace:cli/integrations",
+ "kind": "topic",
+ "id": "cli/integrations/docs/sections-and-placement",
+ "oldCliRoute": "astryx docs cli/integrations/docs/sections-and-placement",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-sections-and-placement",
+ "placement": "namespace:cli/integrations/docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "It places itself: placement {parent: 'namespace:docs', slot: 'guides', order: 20}.",
+ "rationale": "Sections and placement: Give your package its own docs section and place guides in it. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#components",
- "oldCliRoute": "astryx docs cli/integrations components",
- "oldDocsiteUrl": "/docs/cli-integrations#components",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/sections-and-placement#add-a-docs-section",
+ "oldCliRoute": "astryx docs cli/integrations/docs/sections-and-placement add-a-docs-section",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-sections-and-placement#add-a-docs-section",
+ "placement": "namespace:cli/integrations/docs/sections-and-placement",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/sections-and-placement.",
+ "rationale": "A section of cli/integrations/docs/sections-and-placement: Add a docs section.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#templates",
- "oldCliRoute": "astryx docs cli/integrations templates",
- "oldDocsiteUrl": "/docs/cli-integrations#templates",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/sections-and-placement#place-a-doc",
+ "oldCliRoute": "astryx docs cli/integrations/docs/sections-and-placement place-a-doc",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-sections-and-placement#place-a-doc",
+ "placement": "namespace:cli/integrations/docs/sections-and-placement",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/sections-and-placement.",
+ "rationale": "A section of cli/integrations/docs/sections-and-placement: Place a doc.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#docs",
- "oldCliRoute": "astryx docs cli/integrations docs",
- "oldDocsiteUrl": "/docs/cli-integrations#docs",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/sections-and-placement#fix-a-failed-placement",
+ "oldCliRoute": "astryx docs cli/integrations/docs/sections-and-placement fix-a-failed-placement",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-sections-and-placement#fix-a-failed-placement",
+ "placement": "namespace:cli/integrations/docs/sections-and-placement",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/sections-and-placement.",
+ "rationale": "A section of cli/integrations/docs/sections-and-placement: Fix a failed placement.",
"status": "proposed"
},
{
- "kind": "section",
- "id": "cli/integrations#themes",
- "oldCliRoute": "astryx docs cli/integrations themes",
- "oldDocsiteUrl": "/docs/cli-integrations#themes",
- "placement": "namespace:cli/integrations",
+ "kind": "topic",
+ "id": "cli/integrations/docs/links",
+ "oldCliRoute": "astryx docs cli/integrations/docs/links",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-links",
+ "placement": "namespace:cli/integrations/docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "It places itself: placement {parent: 'namespace:docs', slot: 'guides', order: 30}.",
+ "rationale": "Links: Link one doc to another so the link keeps working when the doc moves. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#agent-docs",
- "oldCliRoute": "astryx docs cli/integrations agent-docs",
- "oldDocsiteUrl": "/docs/cli-integrations#agent-docs",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/links#link-another-doc",
+ "oldCliRoute": "astryx docs cli/integrations/docs/links link-another-doc",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-links#link-another-doc",
+ "placement": "namespace:cli/integrations/docs/links",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/links.",
+ "rationale": "A section of cli/integrations/docs/links: Link another doc.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#codemods",
- "oldCliRoute": "astryx docs cli/integrations codemods",
- "oldDocsiteUrl": "/docs/cli-integrations#codemods",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/links#link-another-packages-docs",
+ "oldCliRoute": "astryx docs cli/integrations/docs/links link-another-packages-docs",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-links#link-another-package-s-docs",
+ "placement": "namespace:cli/integrations/docs/links",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/links.",
+ "rationale": "A section of cli/integrations/docs/links: Link another package's docs.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#recording-runs",
- "oldCliRoute": "astryx docs cli/integrations recording-runs",
- "oldDocsiteUrl": "/docs/cli-integrations#recording-runs",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/links#fix-a-link-that-names-no-doc",
+ "oldCliRoute": "astryx docs cli/integrations/docs/links fix-a-link-that-names-no-doc",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-links#fix-a-link-that-names-no-doc",
+ "placement": "namespace:cli/integrations/docs/links",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/docs/links.",
+ "rationale": "A section of cli/integrations/docs/links: Fix a link that names no doc.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/docs/extend-or-replace",
+ "oldCliRoute": "astryx docs cli/integrations/docs/extend-or-replace",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-extend-or-replace",
+ "placement": "namespace:cli/integrations/docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "It places itself: placement {parent: 'namespace:docs', slot: 'guides', order: 40}.",
+ "rationale": "Extend or replace a topic: Take over a topic, or merge sections into it. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#gap-report-handler",
- "oldCliRoute": "astryx docs cli/integrations gap-report-handler",
- "oldDocsiteUrl": "/docs/cli-integrations#gap-report-handler",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/extend-or-replace#replace-a-topic",
+ "oldCliRoute": "astryx docs cli/integrations/docs/extend-or-replace replace-a-topic",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-extend-or-replace#replace-a-topic",
+ "placement": "namespace:cli/integrations/docs/extend-or-replace",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/extend-or-replace.",
+ "rationale": "A section of cli/integrations/docs/extend-or-replace: Replace a topic.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#discover-source",
- "oldCliRoute": "astryx docs cli/integrations discover-source",
- "oldDocsiteUrl": "/docs/cli-integrations#discover-source",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/extend-or-replace#extend-a-topic",
+ "oldCliRoute": "astryx docs cli/integrations/docs/extend-or-replace extend-a-topic",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-extend-or-replace#extend-a-topic",
+ "placement": "namespace:cli/integrations/docs/extend-or-replace",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/extend-or-replace.",
+ "rationale": "A section of cli/integrations/docs/extend-or-replace: Extend a topic.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/integrations#how-it-works",
- "oldCliRoute": "astryx docs cli/integrations how-it-works",
- "oldDocsiteUrl": "/docs/cli-integrations#how-it-works",
- "placement": "namespace:cli/integrations",
+ "id": "cli/integrations/docs/extend-or-replace#check-overlaps-with-core-topics",
+ "oldCliRoute": "astryx docs cli/integrations/docs/extend-or-replace check-overlaps-with-core-topics",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-extend-or-replace#check-overlaps-with-core-topics",
+ "placement": "namespace:cli/integrations/docs/extend-or-replace",
"aliasNeeded": false,
- "evidence": "Moves with cli/integrations.",
- "rationale": "Stays a section of cli/integrations under the same key.",
+ "evidence": "Moves with cli/integrations/docs/extend-or-replace.",
+ "rationale": "A section of cli/integrations/docs/extend-or-replace: Check overlaps with Core topics.",
"status": "proposed"
},
{
"kind": "topic",
- "id": "cli/writing-docs",
- "oldCliRoute": "astryx docs cli/writing-docs",
- "oldDocsiteUrl": "/docs/cli-writing-docs",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/short-and-findable",
+ "oldCliRoute": "astryx docs cli/integrations/docs/short-and-findable",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-short-and-findable",
+ "placement": "namespace:cli/integrations/docs",
"aliasNeeded": false,
- "evidence": "It places itself: placement {parent: 'namespace:cli', slot: 'guides', order: 20}.",
- "rationale": "Guide to writing docs in the docs graph: homes, links by identity, short reads, search, and the doctor checks. New in this change, so it has no older route.",
+ "evidence": "It places itself: placement {parent: 'namespace:docs', slot: 'guides', order: 50}.",
+ "rationale": "Short and findable: Write short sections that people and agents find by search. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#how-the-docs-work",
- "oldCliRoute": "astryx docs cli/writing-docs how-the-docs-work",
- "oldDocsiteUrl": "/docs/cli-writing-docs#how-the-docs-work",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/short-and-findable#keep-each-read-short",
+ "oldCliRoute": "astryx docs cli/integrations/docs/short-and-findable keep-each-read-short",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-short-and-findable#keep-each-read-short",
+ "placement": "namespace:cli/integrations/docs/short-and-findable",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: How the docs work.",
+ "evidence": "Moves with cli/integrations/docs/short-and-findable.",
+ "rationale": "A section of cli/integrations/docs/short-and-findable: Keep each read short.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#add-a-doc",
- "oldCliRoute": "astryx docs cli/writing-docs add-a-doc",
- "oldDocsiteUrl": "/docs/cli-writing-docs#add-a-doc",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/short-and-findable#lead-with-the-summary",
+ "oldCliRoute": "astryx docs cli/integrations/docs/short-and-findable lead-with-the-summary",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-short-and-findable#lead-with-the-summary",
+ "placement": "namespace:cli/integrations/docs/short-and-findable",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: Add a doc.",
+ "evidence": "Moves with cli/integrations/docs/short-and-findable.",
+ "rationale": "A section of cli/integrations/docs/short-and-findable: Lead with the summary.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#place-a-doc",
- "oldCliRoute": "astryx docs cli/writing-docs place-a-doc",
- "oldDocsiteUrl": "/docs/cli-writing-docs#place-a-doc",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/short-and-findable#make-docs-findable",
+ "oldCliRoute": "astryx docs cli/integrations/docs/short-and-findable make-docs-findable",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-short-and-findable#make-docs-findable",
+ "placement": "namespace:cli/integrations/docs/short-and-findable",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: Place a doc.",
+ "evidence": "Moves with cli/integrations/docs/short-and-findable.",
+ "rationale": "A section of cli/integrations/docs/short-and-findable: Make docs findable.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#link-docs",
- "oldCliRoute": "astryx docs cli/writing-docs link-docs",
- "oldDocsiteUrl": "/docs/cli-writing-docs#link-docs",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/short-and-findable#test-with-search",
+ "oldCliRoute": "astryx docs cli/integrations/docs/short-and-findable test-with-search",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-short-and-findable#test-with-search",
+ "placement": "namespace:cli/integrations/docs/short-and-findable",
+ "aliasNeeded": false,
+ "evidence": "Moves with cli/integrations/docs/short-and-findable.",
+ "rationale": "A section of cli/integrations/docs/short-and-findable: Test with search.",
+ "status": "proposed"
+ },
+ {
+ "kind": "topic",
+ "id": "cli/integrations/docs/check-your-docs",
+ "oldCliRoute": "astryx docs cli/integrations/docs/check-your-docs",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-check-your-docs",
+ "placement": "namespace:cli/integrations/docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: Link docs.",
+ "evidence": "It places itself: placement {parent: 'namespace:docs', slot: 'guides', order: 60}.",
+ "rationale": "Check your docs: Check the docs tree, links, overlaps, read size, and CLI peer. New in this change, so it has no older route.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#keep-reads-short",
- "oldCliRoute": "astryx docs cli/writing-docs keep-reads-short",
- "oldDocsiteUrl": "/docs/cli-writing-docs#keep-reads-short",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/check-your-docs#run-the-docs-check",
+ "oldCliRoute": "astryx docs cli/integrations/docs/check-your-docs run-the-docs-check",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-check-your-docs#run-the-docs-check",
+ "placement": "namespace:cli/integrations/docs/check-your-docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: Keep reads short.",
+ "evidence": "Moves with cli/integrations/docs/check-your-docs.",
+ "rationale": "A section of cli/integrations/docs/check-your-docs: Run the docs check.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#make-docs-findable",
- "oldCliRoute": "astryx docs cli/writing-docs make-docs-findable",
- "oldDocsiteUrl": "/docs/cli-writing-docs#make-docs-findable",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/check-your-docs#know-what-fails-the-check",
+ "oldCliRoute": "astryx docs cli/integrations/docs/check-your-docs know-what-fails-the-check",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-check-your-docs#know-what-fails-the-check",
+ "placement": "namespace:cli/integrations/docs/check-your-docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: Make docs findable.",
+ "evidence": "Moves with cli/integrations/docs/check-your-docs.",
+ "rationale": "A section of cli/integrations/docs/check-your-docs: Know what fails the check.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#docs-from-an-integration",
- "oldCliRoute": "astryx docs cli/writing-docs docs-from-an-integration",
- "oldDocsiteUrl": "/docs/cli-writing-docs#docs-from-an-integration",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/check-your-docs#check-read-size",
+ "oldCliRoute": "astryx docs cli/integrations/docs/check-your-docs check-read-size",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-check-your-docs#check-read-size",
+ "placement": "namespace:cli/integrations/docs/check-your-docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: Docs from an integration.",
+ "evidence": "Moves with cli/integrations/docs/check-your-docs.",
+ "rationale": "A section of cli/integrations/docs/check-your-docs: Check read size.",
"status": "proposed"
},
{
"kind": "section",
- "id": "cli/writing-docs#check-your-docs",
- "oldCliRoute": "astryx docs cli/writing-docs check-your-docs",
- "oldDocsiteUrl": "/docs/cli-writing-docs#check-your-docs",
- "placement": "namespace:cli/writing-docs",
+ "id": "cli/integrations/docs/check-your-docs#check-the-cli-peer",
+ "oldCliRoute": "astryx docs cli/integrations/docs/check-your-docs check-the-cli-peer",
+ "oldDocsiteUrl": "/docs/cli-integrations-docs-check-your-docs#check-the-cli-peer",
+ "placement": "namespace:cli/integrations/docs/check-your-docs",
"aliasNeeded": false,
- "evidence": "Moves with cli/writing-docs.",
- "rationale": "A section of cli/writing-docs: Check your docs.",
+ "evidence": "Moves with cli/integrations/docs/check-your-docs.",
+ "rationale": "A section of cli/integrations/docs/check-your-docs: Check the CLI peer.",
"status": "proposed"
},
{
@@ -748,7 +2608,7 @@
"kind": "section",
"id": "color#surface-colors",
"oldCliRoute": "astryx docs color surface-colors",
- "oldDocsiteUrl": "/docs/color#surface-colors",
+ "oldDocsiteUrl": "/docs/color#color-tokens",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of color under the same key.",
@@ -758,7 +2618,7 @@
"kind": "section",
"id": "color#usage",
"oldCliRoute": "astryx docs color usage",
- "oldDocsiteUrl": "/docs/color#usage",
+ "oldDocsiteUrl": "/docs/color#use-color-tokens-in-stylex",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of color under the same key.",
@@ -974,16 +2834,6 @@
"rationale": "Stays a section of icons under the same key.",
"status": "proposed"
},
- {
- "kind": "section",
- "id": "icons#adding-new-icons",
- "oldCliRoute": "astryx docs icons adding-new-icons",
- "oldDocsiteUrl": "/docs/icons#adding-new-icons",
- "placement": "keep-flat",
- "aliasNeeded": false,
- "rationale": "Stays a section of icons under the same key.",
- "status": "proposed"
- },
{
"kind": "topic",
"id": "illustrations",
@@ -1038,7 +2888,7 @@
"kind": "section",
"id": "internationalization#quick-start",
"oldCliRoute": "astryx docs internationalization quick-start",
- "oldDocsiteUrl": "/docs/internationalization#quick-start",
+ "oldDocsiteUrl": "/docs/internationalization#set-the-locale",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of internationalization under the same key.",
@@ -1048,7 +2898,7 @@
"kind": "section",
"id": "internationalization#runtime-language-swap",
"oldCliRoute": "astryx docs internationalization runtime-language-swap",
- "oldDocsiteUrl": "/docs/internationalization#runtime-language-swap",
+ "oldDocsiteUrl": "/docs/internationalization#change-the-language-at-runtime",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of internationalization under the same key.",
@@ -1066,32 +2916,32 @@
},
{
"kind": "section",
- "id": "internationalization#overriding-astryx-s-default-text",
- "oldCliRoute": "astryx docs internationalization overriding-astryx-s-default-text",
+ "id": "internationalization#override-text",
+ "oldCliRoute": "astryx docs internationalization override-text",
"oldDocsiteUrl": "/docs/internationalization#overriding-astryx-s-default-text",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of internationalization under the same key.",
+ "rationale": "Stays a section of internationalization, under a shorter key (was `overriding-astryx-s-default-text`).",
"status": "proposed"
},
{
"kind": "section",
- "id": "internationalization#using-astryx-with-your-own-i18n-library",
- "oldCliRoute": "astryx docs internationalization using-astryx-with-your-own-i18n-library",
+ "id": "internationalization#own-i18n-library",
+ "oldCliRoute": "astryx docs internationalization own-i18n-library",
"oldDocsiteUrl": "/docs/internationalization#using-astryx-with-your-own-i18n-library",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of internationalization under the same key.",
+ "rationale": "Stays a section of internationalization, under a shorter key (was `using-astryx-with-your-own-i18n-library`).",
"status": "proposed"
},
{
"kind": "section",
- "id": "internationalization#using-astryx-as-your-i18n-library",
- "oldCliRoute": "astryx docs internationalization using-astryx-as-your-i18n-library",
+ "id": "internationalization#astryx-as-i18n",
+ "oldCliRoute": "astryx docs internationalization astryx-as-i18n",
"oldDocsiteUrl": "/docs/internationalization#using-astryx-as-your-i18n-library",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of internationalization under the same key.",
+ "rationale": "Stays a section of internationalization, under a shorter key (was `using-astryx-as-your-i18n-library`).",
"status": "proposed"
},
{
@@ -1104,16 +2954,6 @@
"rationale": "Stays a section of internationalization under the same key.",
"status": "proposed"
},
- {
- "kind": "section",
- "id": "internationalization#for-contributors",
- "oldCliRoute": "astryx docs internationalization for-contributors",
- "oldDocsiteUrl": "/docs/internationalization#for-contributors",
- "placement": "keep-flat",
- "aliasNeeded": false,
- "rationale": "Stays a section of internationalization under the same key.",
- "status": "proposed"
- },
{
"kind": "topic",
"id": "layout",
@@ -1144,6 +2984,26 @@
"rationale": "Stays a section of layout under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "layout#shell",
+ "oldCliRoute": "astryx docs layout shell",
+ "oldDocsiteUrl": "/docs/layout#shell",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Scaffold, where it was the Shell heading.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "layout#navigation",
+ "oldCliRoute": "astryx docs layout navigation",
+ "oldDocsiteUrl": "/docs/layout#navigation",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Scaffold, where it was the Navigation heading.",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "layout#structure",
@@ -1154,6 +3014,46 @@
"rationale": "Stays a section of layout under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "layout#type-hierarchy",
+ "oldCliRoute": "astryx docs layout type-hierarchy",
+ "oldDocsiteUrl": "/docs/layout#type-hierarchy",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Structure, where it was the Type hierarchy heading.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "layout#containers",
+ "oldCliRoute": "astryx docs layout containers",
+ "oldDocsiteUrl": "/docs/layout#card-or-rows",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Structure, where it was the Containers heading.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "layout#headers-and-footers",
+ "oldCliRoute": "astryx docs layout headers-and-footers",
+ "oldDocsiteUrl": "/docs/layout#headers-and-footers",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Structure, where it was the Headers and footers heading.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "layout#side-panels",
+ "oldCliRoute": "astryx docs layout side-panels",
+ "oldDocsiteUrl": "/docs/layout#side-panels",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Structure, where it was the Side panels heading.",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "layout#spacing",
@@ -1164,6 +3064,36 @@
"rationale": "Stays a section of layout under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "layout#alignment",
+ "oldCliRoute": "astryx docs layout alignment",
+ "oldDocsiteUrl": "/docs/layout#alignment",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Spacing, where it was the Alignment heading.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "layout#rhythm",
+ "oldCliRoute": "astryx docs layout rhythm",
+ "oldDocsiteUrl": "/docs/layout#rhythm",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Spacing, where it was the Rhythm heading.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "layout#density",
+ "oldCliRoute": "astryx docs layout density",
+ "oldDocsiteUrl": "/docs/layout#density-and-size",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Spacing, where it was the Density and size heading.",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "layout#breakpoints",
@@ -1174,6 +3104,16 @@
"rationale": "Stays a section of layout under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "layout#responsive-contract",
+ "oldCliRoute": "astryx docs layout responsive-contract",
+ "oldDocsiteUrl": "/docs/layout#responsive-contract",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of layout: split out of Breakpoints, where it was the Responsive contract heading.",
+ "status": "proposed"
+ },
{
"kind": "topic",
"id": "migration",
@@ -1228,12 +3168,22 @@
"kind": "section",
"id": "migration#cascade-layer-safety",
"oldCliRoute": "astryx docs migration cascade-layer-safety",
- "oldDocsiteUrl": "/docs/migration#cascade-layer-safety",
+ "oldDocsiteUrl": "/docs/migration#why-resets-break-cascade-layers",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of migration under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "migration#layer-audit",
+ "oldCliRoute": "astryx docs migration layer-audit",
+ "oldDocsiteUrl": "/docs/migration#cascade-layer-audit",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of migration: split out of Cascade Layer Safety (its audit checklist).",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "migration#foundation-smoke-test",
@@ -1266,12 +3216,12 @@
},
{
"kind": "section",
- "id": "migration#command-palette-settings-and-theme",
- "oldCliRoute": "astryx docs migration command-palette-settings-and-theme",
+ "id": "migration#command-palette",
+ "oldCliRoute": "astryx docs migration command-palette",
"oldDocsiteUrl": "/docs/migration#command-palette-settings-and-theme",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of migration under the same key.",
+ "rationale": "Stays a section of migration, under a shorter key (was `command-palette-settings-and-theme`).",
"status": "proposed"
},
{
@@ -1378,7 +3328,7 @@
"kind": "section",
"id": "motion#usage",
"oldCliRoute": "astryx docs motion usage",
- "oldDocsiteUrl": "/docs/motion#usage",
+ "oldDocsiteUrl": "/docs/motion#animate-with-motion-tokens",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of motion under the same key.",
@@ -1626,12 +3576,12 @@
},
{
"kind": "section",
- "id": "styling-libraries#panda-chakra-and-other-semantic-token-systems",
- "oldCliRoute": "astryx docs styling-libraries panda-chakra-and-other-semantic-token-systems",
+ "id": "styling-libraries#semantic-token-systems",
+ "oldCliRoute": "astryx docs styling-libraries semantic-token-systems",
"oldDocsiteUrl": "/docs/styling-libraries#panda-chakra-and-other-semantic-token-systems",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of styling-libraries under the same key.",
+ "rationale": "Stays a section of styling-libraries, under a shorter key (was `panda-chakra-and-other-semantic-token-systems`).",
"status": "proposed"
},
{
@@ -1646,22 +3596,22 @@
},
{
"kind": "section",
- "id": "styling-libraries#emotion-styled-components-theme-ui-and-styled-system",
- "oldCliRoute": "astryx docs styling-libraries emotion-styled-components-theme-ui-and-styled-system",
+ "id": "styling-libraries#css-in-js",
+ "oldCliRoute": "astryx docs styling-libraries css-in-js",
"oldDocsiteUrl": "/docs/styling-libraries#emotion-styled-components-theme-ui-and-styled-system",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of styling-libraries under the same key.",
+ "rationale": "Stays a section of styling-libraries, under a shorter key (was `emotion-styled-components-theme-ui-and-styled-system`).",
"status": "proposed"
},
{
"kind": "section",
- "id": "styling-libraries#unocss-and-custom-utility-systems",
- "oldCliRoute": "astryx docs styling-libraries unocss-and-custom-utility-systems",
+ "id": "styling-libraries#unocss",
+ "oldCliRoute": "astryx docs styling-libraries unocss",
"oldDocsiteUrl": "/docs/styling-libraries#unocss-and-custom-utility-systems",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of styling-libraries under the same key.",
+ "rationale": "Stays a section of styling-libraries, under a shorter key (was `unocss-and-custom-utility-systems`).",
"status": "proposed"
},
{
@@ -1676,12 +3626,12 @@
},
{
"kind": "section",
- "id": "styling-libraries#non-css-processing-best-practices",
- "oldCliRoute": "astryx docs styling-libraries non-css-processing-best-practices",
+ "id": "styling-libraries#non-css-best-practices",
+ "oldCliRoute": "astryx docs styling-libraries non-css-best-practices",
"oldDocsiteUrl": "/docs/styling-libraries#non-css-processing-best-practices",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of styling-libraries under the same key.",
+ "rationale": "Stays a section of styling-libraries, under a shorter key (was `non-css-processing-best-practices`).",
"status": "proposed"
},
{
@@ -1768,7 +3718,7 @@
"kind": "section",
"id": "styling#preferred-selector-surface-data-attributes",
"oldCliRoute": "astryx docs styling preferred-selector-surface-data-attributes",
- "oldDocsiteUrl": "/docs/styling#preferred-selector-surface-data-attributes",
+ "oldDocsiteUrl": "/docs/styling#data-attribute-selectors",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of styling under the same key.",
@@ -1776,12 +3726,12 @@
},
{
"kind": "section",
- "id": "styling#deprecated-bare-prop-and-state-classes",
- "oldCliRoute": "astryx docs styling deprecated-bare-prop-and-state-classes",
+ "id": "styling#deprecated-classes",
+ "oldCliRoute": "astryx docs styling deprecated-classes",
"oldDocsiteUrl": "/docs/styling#deprecated-bare-prop-and-state-classes",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of styling under the same key.",
+ "rationale": "Stays a section of styling, under a shorter key (was `deprecated-bare-prop-and-state-classes`).",
"status": "proposed"
},
{
@@ -1796,12 +3746,12 @@
},
{
"kind": "section",
- "id": "styling#stylex-build-setup-required-for-swizzled-components",
- "oldCliRoute": "astryx docs styling stylex-build-setup-required-for-swizzled-components",
+ "id": "styling#stylex-setup",
+ "oldCliRoute": "astryx docs styling stylex-setup",
"oldDocsiteUrl": "/docs/styling#stylex-build-setup-required-for-swizzled-components",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of styling under the same key.",
+ "rationale": "Stays a section of styling, under a shorter key (was `stylex-build-setup-required-for-swizzled-components`).",
"status": "proposed"
},
{
@@ -1828,7 +3778,7 @@
"kind": "section",
"id": "theme#quick-start",
"oldCliRoute": "astryx docs theme quick-start",
- "oldDocsiteUrl": "/docs/theme#quick-start",
+ "oldDocsiteUrl": "/docs/theme#wrap-your-app-in-a-theme",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of theme under the same key.",
@@ -1856,19 +3806,19 @@
},
{
"kind": "section",
- "id": "theme#using-a-theme-from-an-integration",
- "oldCliRoute": "astryx docs theme using-a-theme-from-an-integration",
+ "id": "theme#integration-themes",
+ "oldCliRoute": "astryx docs theme integration-themes",
"oldDocsiteUrl": "/docs/theme#using-a-theme-from-an-integration",
"placement": "keep-flat",
"aliasNeeded": false,
- "rationale": "Stays a section of theme under the same key.",
+ "rationale": "Stays a section of theme, under a shorter key (was `using-a-theme-from-an-integration`).",
"status": "proposed"
},
{
"kind": "section",
"id": "theme#creating-a-custom-theme",
"oldCliRoute": "astryx docs theme creating-a-custom-theme",
- "oldDocsiteUrl": "/docs/theme#creating-a-custom-theme",
+ "oldDocsiteUrl": "/docs/theme#custom-themes",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of theme under the same key.",
@@ -1904,6 +3854,16 @@
"rationale": "Stays a section of theme under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "theme#adaptation-rules",
+ "oldCliRoute": "astryx docs theme adaptation-rules",
+ "oldDocsiteUrl": "/docs/theme#adaptation-order-and-validation",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of theme: split out of Theme Adaptations (rule order and validation).",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "theme#component-style-overrides",
@@ -1928,12 +3888,22 @@
"kind": "section",
"id": "theme#building-themes-for-production",
"oldCliRoute": "astryx docs theme building-themes-for-production",
- "oldDocsiteUrl": "/docs/theme#building-themes-for-production",
+ "oldDocsiteUrl": "/docs/theme#build-a-theme",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of theme under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "theme#icon-registry",
+ "oldCliRoute": "astryx docs theme icon-registry",
+ "oldDocsiteUrl": "/docs/theme#built-themes-with-an-icon-registry",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of theme: split out of Building Themes for Production (the icon registry sidecar).",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "theme#building-a-theme-family",
@@ -1958,7 +3928,7 @@
"kind": "section",
"id": "theme#light-dark-mode",
"oldCliRoute": "astryx docs theme light-dark-mode",
- "oldDocsiteUrl": "/docs/theme#light-dark-mode",
+ "oldDocsiteUrl": "/docs/theme#dark-mode",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of theme under the same key.",
@@ -1968,7 +3938,7 @@
"kind": "section",
"id": "theme#nesting-themes",
"oldCliRoute": "astryx docs theme nesting-themes",
- "oldDocsiteUrl": "/docs/theme#nesting-themes",
+ "oldDocsiteUrl": "/docs/theme#nested-themes",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of theme under the same key.",
@@ -2014,6 +3984,26 @@
"rationale": "Stays a section of tokens under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "tokens#data-visualization-tokens",
+ "oldCliRoute": "astryx docs tokens data-visualization-tokens",
+ "oldDocsiteUrl": "/docs/tokens#data-visualization-tokens",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of tokens: the data visualization token group, which the token docs generator now emits.",
+ "status": "proposed"
+ },
+ {
+ "kind": "section",
+ "id": "tokens#syntax-tokens",
+ "oldCliRoute": "astryx docs tokens syntax-tokens",
+ "oldDocsiteUrl": "/docs/tokens#syntax-tokens",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of tokens: the syntax token group, which the token docs generator now emits.",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "tokens#spacing-tokens",
@@ -2178,7 +4168,7 @@
"kind": "section",
"id": "typography#loading-custom-fonts",
"oldCliRoute": "astryx docs typography loading-custom-fonts",
- "oldDocsiteUrl": "/docs/typography#loading-custom-fonts",
+ "oldDocsiteUrl": "/docs/typography#custom-fonts",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of typography under the same key.",
@@ -2238,12 +4228,22 @@
"kind": "section",
"id": "typography#usage",
"oldCliRoute": "astryx docs typography usage",
- "oldDocsiteUrl": "/docs/typography#usage",
+ "oldDocsiteUrl": "/docs/typography#headings-and-text",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of typography under the same key.",
"status": "proposed"
},
+ {
+ "kind": "section",
+ "id": "typography#custom-type-scale",
+ "oldCliRoute": "astryx docs typography custom-type-scale",
+ "oldDocsiteUrl": "/docs/typography#custom-type-scale",
+ "placement": "keep-flat",
+ "aliasNeeded": false,
+ "rationale": "Stays a section of typography: split out of Usage (the defineTheme type scale).",
+ "status": "proposed"
+ },
{
"kind": "section",
"id": "typography#best-practices",
@@ -2278,7 +4278,7 @@
"kind": "section",
"id": "working-with-ai#quick-start",
"oldCliRoute": "astryx docs working-with-ai quick-start",
- "oldDocsiteUrl": "/docs/working-with-ai#quick-start",
+ "oldDocsiteUrl": "/docs/working-with-ai#set-up-agent-docs",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of working-with-ai under the same key.",
@@ -2328,7 +4328,7 @@
"kind": "section",
"id": "working-with-ai#the-dense-flag",
"oldCliRoute": "astryx docs working-with-ai the-dense-flag",
- "oldDocsiteUrl": "/docs/working-with-ai#the-dense-flag",
+ "oldDocsiteUrl": "/docs/working-with-ai#shorter-output-detail-and-dense",
"placement": "keep-flat",
"aliasNeeded": false,
"rationale": "Stays a section of working-with-ai under the same key.",
@@ -2444,7 +4444,7 @@
"kind": "command",
"id": "@astryxdesign/cli/command",
"provider": "@astryxdesign/cli",
- "count": 30,
+ "count": 35,
"oldCliRoute": "astryx <id> --help",
"oldDocsiteUrl": null,
"placement": "namespace:cli/commands",
@@ -2457,7 +4457,7 @@
"kind": "function",
"id": "@astryxdesign/cli/function",
"provider": "@astryxdesign/cli",
- "count": 38,
+ "count": 41,
"oldCliRoute": null,
"oldDocsiteUrl": null,
"placement": "namespace:cli/api/functions",
@@ -2470,13 +4470,13 @@
"kind": "schema",
"id": "@astryxdesign/cli/schema",
"provider": "@astryxdesign/cli",
- "count": 19,
+ "count": 18,
"oldCliRoute": null,
"oldDocsiteUrl": null,
"placement": "generated:@astryxdesign/cli/schema",
"aliasNeeded": false,
- "evidence": "No schema doc authors a placement; output declares cli/api and the other 18 declare authoring.",
- "rationale": "18 declare namespace 'authoring' and are read as sections of `astryx docs authoring`; `output` declares cli/api and is read as the leaf cli/api/schemas/output. Their home in the tree for authoring is a later phase.",
+ "evidence": "No schema doc authors a placement; output declares cli/api and the other 17 declare authoring.",
+ "rationale": "17 declare namespace 'authoring' and are read as sections of `astryx docs authoring`; `output` declares cli/api and is read as the leaf cli/api/schemas/output. Their home in the tree for authoring is a later phase.",
"status": "proposed"
},
{
diff --git a/packages/cli/test/doc-routes.test.mjs b/packages/cli/test/doc-routes.test.mjs
deleted file mode 100644
index f765be3126..0000000000
--- a/packages/cli/test/doc-routes.test.mjs
+++ /dev/null
@@ -1,650 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Every current doc route has one reviewed row in doc-routes.json.
- *
- * @input doc-routes.json and doc-routes.ids.json beside this file, and the
- * routes the CLI answers today: its built-in doc topics and their section
- * keys, the docsite pages built from those topic files, and every typed
- * descriptor the doc compiler reads, with the read that reaches each one.
- * @output Failures naming each route the table misses, each row naming a
- * route that no longer exists, and each row without a rationale or with a
- * placement the proposal does not define.
- * @position Guard for the docs-graph migration. The table is a proposal a
- * person reviews; this test keeps it complete and well formed, so a new
- * route cannot land unmapped. It reads the CLI and changes nothing.
- */
-
-import {afterAll, beforeAll, describe, expect, it} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
-import {component} from '../api/component/component.mjs';
-import {docs} from '../api/docs/docs.mjs';
-import {hook} from '../api/hook/hook.mjs';
-import {template} from '../api/template/template.mjs';
-import {themeListAvailable} from '../api/theme/list/list.mjs';
-import {program} from '../clients/cli/index.mjs';
-import {Project} from '../foundation/config/project.mjs';
-import {loadDocs} from '../foundation/discovery/component-loader.mjs';
-import {collectDocInputs} from '../foundation/doc-compiler/inputs.mjs';
-import {loadDocsTree} from '../foundation/doc-compiler/tree.mjs';
-import {CLI_ROOT} from '../foundation/fs/paths.mjs';
-
-const REPO_ROOT = path.resolve(CLI_ROOT, '..', '..');
-const TABLE_FILE = path.join(CLI_ROOT, 'test', 'doc-routes.json');
-const SLOW = 120_000;
-
-/**
- * How the CLI reaches one typed descriptor today, by kind. A kind missing
- * here is new: decide its route before mapping it.
- * @type {Record<string, string | null>}
- */
-const DESCRIPTOR_ROUTES = {
- component: 'astryx component <id>',
- 'component-member': 'astryx component <id>',
- hook: 'astryx hook <id>',
- page: 'astryx template <id> --type page',
- block: 'astryx template <id> --type block',
- theme: 'astryx theme add <id>',
- command: 'astryx <id> --help',
- function: null,
- schema: null,
- enum: null,
-};
-
-const SEGMENT = '[a-z0-9]+(?:-[a-z0-9]+)*';
-const PACKAGE = '(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*';
-const PLACEMENT = new RegExp(
- `^(?:keep-flat|namespace:(${SEGMENT})(?:/${SEGMENT})*|generated:(${PACKAGE})/(${SEGMENT}))$`,
-);
-
-/**
- * @typedef {object} RouteRow
- * @property {string} kind
- * @property {string} id
- * @property {string} [provider]
- * @property {number} [count]
- * @property {string | null} oldCliRoute
- * @property {string | null} oldDocsiteUrl
- * @property {Record<string, string>} [docsiteExceptions]
- * @property {string} placement
- * @property {unknown} aliasNeeded
- * @property {string} [evidence]
- * @property {string} rationale
- * @property {string} status
- */
-
-/**
- * A topic, section, or docs-tree namespace route as the CLI and the docsite
- * answer it today.
- * @typedef {object} Route
- * @property {'topic' | 'section' | 'namespace'} kind
- * @property {string} id `topic`, `topic#key`, or a namespace's route
- * @property {string} oldCliRoute
- * @property {string | null} oldDocsiteUrl
- */
-
-/**
- * Typed descriptors of one provider and kind.
- * @typedef {object} Group
- * @property {string} id `<provider>/<kind>`
- * @property {string} provider
- * @property {string} kind
- * @property {Set<string>} ids
- * @property {Set<string>} unreachable ids the kind's route does not reach
- * @property {Set<string>} placed ids whose descriptor authors a placement
- */
-
-/** @type {string} */
-let tmpDir;
-/** @type {Map<string, Route>} */
-let routes;
-/** @type {Map<string, Group>} */
-let groups;
-/** @type {{idsFile: string, namespaces: any[], rows: RouteRow[]}} */
-let table;
-/** @type {Record<string, string[]>} */
-let idsFile;
-
-beforeAll(async () => {
- // Inside the repo, so the project finds this checkout's Core, and bare, so
- // no integration adds a route.
- tmpDir = fs.mkdtempSync(path.join(REPO_ROOT, '.astryx-doc-routes-'));
- fs.writeFileSync(
- path.join(tmpDir, 'package.json'),
- JSON.stringify({name: 'consumer', version: '1.0.0'}),
- );
- table = JSON.parse(fs.readFileSync(TABLE_FILE, 'utf-8'));
- idsFile = JSON.parse(
- fs.readFileSync(
- path.join(path.dirname(TABLE_FILE), table.idsFile),
- 'utf-8',
- ),
- );
- routes = await currentTopicRoutes(tmpDir);
- groups = await currentDescriptorGroups(tmpDir);
-}, SLOW);
-
-afterAll(() => {
- if (tmpDir) fs.rmSync(tmpDir, {recursive: true, force: true});
-});
-
-/**
- * Every built-in topic and section key, with the docsite URL for each.
- * @param {string} cwd
- * @returns {Promise<Map<string, Route>>}
- */
-async function currentTopicRoutes(cwd) {
- /** @type {Map<string, Route>} */
- const found = new Map();
- const list = /** @type {any} */ (await docs(undefined, undefined, {cwd}));
- /** @type {Array<{topic: string, file: string, page: string | null}>} */
- const topics = [];
- /** @type {string[]} */
- const namespaces = [];
- for (const {topic} of list.meta?.namespaces ?? []) namespaces.push(topic);
- for (const {topic} of list.data) {
- // The docsite builds one page per topic file the CLI ships.
- const file = path.join(CLI_ROOT, 'assets', 'docs', `${topic}.doc.mjs`);
- topics.push({
- topic,
- file,
- page: fs.existsSync(file) ? `/docs/${topic}` : null,
- });
- }
- // Down the docs tree, one level at a time. A namespace is a route; a guide
- // is a topic read by its route, published on the docsite at its route with
- // "/" as "-"; a typed doc is its descriptor group's row.
- while (namespaces.length > 0) {
- const route = /** @type {string} */ (namespaces.shift());
- found.set(route, {
- kind: 'namespace',
- id: route,
- oldCliRoute: `astryx docs ${route}`,
- oldDocsiteUrl: null,
- });
- const node = /** @type {any} */ (await docs(route, undefined, {cwd}));
- for (const slot of node.data.slots) {
- for (const child of slot.children) {
- if (child.kind === 'namespace') namespaces.push(child.route);
- // A flat topic in the Unorganized level is listed as a topic below.
- if (child.kind !== 'generic' || !child.route.includes('/')) continue;
- topics.push({
- topic: child.route,
- file: path.join(
- CLI_ROOT,
- 'assets',
- 'docs',
- 'tree',
- `${child.name}.doc.mjs`,
- ),
- page: `/docs/${child.route.replaceAll('/', '-')}`,
- });
- }
- }
- }
- for (const {topic, file, page} of topics) {
- found.set(topic, {
- kind: 'topic',
- id: topic,
- oldCliRoute: `astryx docs ${topic}`,
- oldDocsiteUrl: page,
- });
- const index = /** @type {any} */ (
- await docs(topic, undefined, {index: true, cwd})
- );
- const authored = page ? (await authoredDoc(file)).sections : [];
- const anchors = docsiteAnchors(authored);
- index.data.sections.forEach(
- (
- /** @type {{id: string, title: string}} */ section,
- /** @type {number} */ i,
- ) => {
- const anchored = page != null && authored[i]?.title === section.title;
- found.set(`${topic}#${section.id}`, {
- kind: 'section',
- id: `${topic}#${section.id}`,
- oldCliRoute: `astryx docs ${topic} ${section.id}`,
- oldDocsiteUrl: anchored ? `${page}#${anchors[i]}` : null,
- });
- },
- );
- }
- return found;
-}
-
-/**
- * The docsite's outline ids for a topic's sections, in order. Mirrors
- * apps/docsite ReferenceDocView: slugged titles, deduped across sections and
- * their heading blocks in reading order.
- * @param {Array<{title: string, content?: Array<{type: string, text?: string}>}>} sections
- * @returns {string[]}
- */
-function docsiteAnchors(sections) {
- /** @type {Map<string, number>} */
- const seen = new Map();
- /** @param {string} value @param {string} fallback */
- const unique = (value, fallback) => {
- const slug =
- value
- .toLowerCase()
- .trim()
- .replace(/[^a-z0-9]+/g, '-')
- .replace(/^-+|-+$/g, '') || fallback;
- const count = seen.get(slug) ?? 0;
- seen.set(slug, count + 1);
- return count === 0 ? slug : `${slug}-${count + 1}`;
- };
- return sections.map(section => {
- const id = unique(section.title, 'section');
- for (const block of section.content ?? []) {
- if (block.type === 'heading' && block.text) {
- unique(`${section.title} ${block.text}`, `${id}-heading`);
- }
- }
- return id;
- });
-}
-
-/**
- * The authored object a descriptor file exports. Fails closed: a file with
- * none would otherwise pass every check on the fields it lacks.
- * @param {string} file
- * @returns {Promise<Record<string, any>>}
- */
-async function authoredDoc(file) {
- const mod = await import(pathToFileURL(file).href);
- const doc = mod.docs ?? mod.doc ?? mod.default;
- if (doc == null || typeof doc !== 'object') {
- throw new Error(`${path.relative(REPO_ROOT, file)} exports no doc object`);
- }
- return doc;
-}
-
-/**
- * @param {Map<string, Group>} found
- * @param {string} provider
- * @param {string} kind
- * @returns {Group}
- */
-function groupOf(found, provider, kind) {
- const id = `${provider}/${kind}`;
- let group = found.get(id);
- if (!group) {
- group = {
- id,
- provider,
- kind,
- ids: new Set(),
- unreachable: new Set(),
- placed: new Set(),
- };
- found.set(id, group);
- }
- return group;
-}
-
-/**
- * Every typed descriptor the compiler reads, grouped by provider and kind,
- * plus the component names that read into another component's doc.
- * @param {string} cwd
- * @returns {Promise<Map<string, Group>>}
- */
-async function currentDescriptorGroups(cwd) {
- const {inputs, problems} = await collectDocInputs(await Project.load(cwd));
- if (problems.length > 0) throw new Error(JSON.stringify(problems));
-
- /** @type {Map<string, Group>} */
- const found = new Map();
- for (const input of inputs) {
- // A topic's own file is a topic route, and a docs-tree file is a
- // namespace or guide route; everything else is a descriptor.
- if (input.root === 'docs' && input.role === 'base') continue;
- if (input.root === 'tree') continue;
- const doc = await authoredDoc(input.file);
- let kind = input.root.replace(/s$/u, '');
- let id = input.name;
- if (input.root === 'templates') [kind, id] = input.name.split('/');
- if (input.root === 'self-docs') [kind, id] = [doc.type, doc.name];
- const group = groupOf(found, input.owner, kind);
- if (group.ids.has(id)) throw new Error(`${group.id} reads "${id}" twice`);
- group.ids.add(id);
- if ('placement' in doc) group.placed.add(id);
- }
-
- await addComponentMembers(found, inputs, cwd);
- await markUnreachable(found, cwd);
- return found;
-}
-
-/**
- * Names `component <Name>` resolves into another component's doc: a member
- * of its `components` list, or the name the doc declares for itself. Only a
- * name the read answers under that name is a route.
- * @param {Map<string, Group>} found
- * @param {import('../foundation/doc-compiler/inputs.mjs').DocInput[]} inputs
- * @param {string} cwd
- */
-async function addComponentMembers(found, inputs, cwd) {
- const own = new Set(
- inputs
- .filter(input => input.root === 'components' || input.root === 'hooks')
- .map(input => input.name),
- );
- for (const input of inputs) {
- if (input.root !== 'components') continue;
- const doc = /** @type {any} */ (await loadDocs(input.file));
- const names = (doc.components ?? [])
- .filter((/** @type {object} */ entry) => Object.keys(entry).length > 1)
- .map((/** @type {{name?: string}} */ entry) => String(entry.name ?? ''));
- if (typeof doc.name === 'string') names.push(doc.name);
- for (const raw of names) {
- const name = raw.replace(/^XDS/u, '');
- if (!name || name === input.name || own.has(name)) continue;
- const read = await component(name, {cwd}).catch(() => null);
- if (read?.type === 'component.detail' && read.data?.name === name) {
- groupOf(found, input.owner, 'component-member').ids.add(name);
- }
- }
- }
-}
-
-/**
- * Record every id its kind's route does not reach.
- * @param {Map<string, Group>} found
- * @param {string} cwd
- */
-async function markUnreachable(found, cwd) {
- const list = /** @type {any} */ (
- await template(undefined, {list: true, cwd})
- );
- const templates = new Set(
- list.data.map(
- (/** @type {{type: string, id: string}} */ t) => `${t.type}/${t.id}`,
- ),
- );
- const themes = new Set(
- (await themeListAvailable({cwd})).data.map(theme => theme.slug),
- );
- const commands = commandPaths();
- for (const group of found.values()) {
- for (const id of group.ids) {
- let reached = true;
- if (group.kind === 'component') {
- const read = await component(id, {cwd}).catch(() => null);
- reached = read?.type === 'component.detail';
- } else if (group.kind === 'hook') {
- const read = await hook(id, {cwd}).catch(() => null);
- reached = read?.type === 'hook.detail';
- } else if (group.kind === 'page' || group.kind === 'block') {
- // `template <id> --type <kind>` resolves against this same list.
- reached = templates.has(`${group.kind}/${id}`);
- } else if (group.kind === 'theme') {
- reached = themes.has(id);
- } else if (group.kind === 'command') {
- reached = commands.has(id);
- }
- if (!reached) group.unreachable.add(id);
- }
- }
-}
-
-/** Every command path the CLI registers, as typed after `astryx`. */
-function commandPaths() {
- /** @type {Set<string>} */
- const paths = new Set();
- /** @param {import('commander').Command} parent @param {string} prefix */
- const walk = (parent, prefix) => {
- for (const cmd of parent.commands) {
- const name = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
- paths.add(name);
- walk(cmd, name);
- }
- };
- walk(program, '');
- return paths;
-}
-
-/** @param {RouteRow} row @returns {boolean} */
-const isDescriptorRow = row =>
- row.kind !== 'topic' && row.kind !== 'section' && row.kind !== 'namespace';
-
-/**
- * A row to paste and complete: the rationale and placement stay empty, so
- * the table fails until a person decides them.
- * @param {Route | Group} route
- */
-function skeleton(route) {
- const fields =
- 'provider' in route
- ? {provider: route.provider, count: route.ids.size}
- : {oldCliRoute: route.oldCliRoute, oldDocsiteUrl: route.oldDocsiteUrl};
- return JSON.stringify({
- kind: route.kind,
- id: route.id,
- ...fields,
- placement: '',
- aliasNeeded: false,
- rationale: '',
- status: 'proposed',
- });
-}
-
-describe('doc route inventory', () => {
- it('(a) maps every current route', () => {
- const rows = new Map(table.rows.map(row => [row.id, row]));
- /** @type {string[]} */
- const missing = [];
- for (const route of routes.values()) {
- if (rows.get(route.id)?.kind !== route.kind) {
- missing.push(`no row for ${route.oldCliRoute}: ${skeleton(route)}`);
- }
- }
- for (const group of groups.values()) {
- if (rows.get(group.id)?.kind !== group.kind) {
- missing.push(`no row for ${group.id}: ${skeleton(group)}`);
- continue;
- }
- const listed = new Set(idsFile[group.id] ?? []);
- for (const id of group.ids) {
- if (!listed.has(id)) {
- missing.push(`${group.id} "${id}" is missing from ${table.idsFile}`);
- }
- }
- }
- expect(missing).toEqual([]);
- });
-
- it('(b) names only routes that exist', () => {
- /** @type {string[]} */
- const stale = [];
- for (const row of table.rows) {
- if (!isDescriptorRow(row)) {
- const route = routes.get(row.id);
- if (route?.kind !== row.kind) {
- stale.push(`${row.id}: no such ${row.kind}`);
- continue;
- }
- if (row.oldCliRoute !== route.oldCliRoute) {
- stale.push(`${row.id}: the CLI route is ${route.oldCliRoute}`);
- }
- if (row.oldDocsiteUrl !== route.oldDocsiteUrl) {
- stale.push(`${row.id}: the docsite URL is ${route.oldDocsiteUrl}`);
- }
- continue;
- }
- const group = groups.get(row.id);
- if (group?.kind !== row.kind) {
- stale.push(`${row.id}: no ${row.kind} descriptors under this id`);
- continue;
- }
- if (!(row.kind in DESCRIPTOR_ROUTES)) {
- stale.push(`${row.id}: no known route for kind ${row.kind}`);
- } else if (row.oldCliRoute !== DESCRIPTOR_ROUTES[row.kind]) {
- stale.push(
- `${row.id}: the CLI route is ${DESCRIPTOR_ROUTES[row.kind]}`,
- );
- }
- if (row.provider !== group.provider) {
- stale.push(`${row.id}: the provider is ${group.provider}`);
- }
- const listed = idsFile[row.id] ?? [];
- if (row.count !== listed.length) {
- stale.push(
- `${row.id}: count ${row.count}, ${table.idsFile} lists ${listed.length}`,
- );
- }
- const seen = new Set();
- for (const id of listed) {
- if (seen.has(id)) stale.push(`${row.id} "${id}" is listed twice`);
- seen.add(id);
- if (!group.ids.has(id)) {
- stale.push(`${row.id} "${id}" no longer exists`);
- } else if (group.unreachable.has(id)) {
- stale.push(`${row.id} "${id}": ${row.oldCliRoute} does not reach it`);
- }
- }
- for (const id of Object.keys(row.docsiteExceptions ?? {})) {
- if (!group.ids.has(id)) {
- stale.push(
- `${row.id}: docsite exception for "${id}", which no longer exists`,
- );
- }
- }
- }
- const rowIds = new Set(table.rows.map(row => row.id));
- for (const key of Object.keys(idsFile)) {
- if (!rowIds.has(key)) stale.push(`${table.idsFile}: "${key}" has no row`);
- }
- expect(stale).toEqual([]);
- });
-
- it('(c) gives every row a rationale and a known placement', () => {
- const created = new Set(
- table.namespaces
- .filter(ns => ns.decision === 'create')
- .map(ns => ns.name),
- );
- const topics = new Map(
- table.rows.filter(row => row.kind === 'topic').map(row => [row.id, row]),
- );
- /** @type {string[]} */
- const bad = [];
- const seen = new Set();
- for (const row of table.rows) {
- const at = row.id;
- if (seen.has(at)) bad.push(`${at}: two rows`);
- seen.add(at);
- if (typeof row.rationale !== 'string' || row.rationale.trim() === '') {
- bad.push(`${at}: no rationale`);
- }
- if (row.status !== 'proposed') {
- bad.push(`${at}: status is not "proposed"`);
- }
- if (typeof row.aliasNeeded !== 'boolean') {
- bad.push(`${at}: aliasNeeded is not a boolean`);
- }
- const form = PLACEMENT.exec(row.placement ?? '');
- if (!form) {
- bad.push(`${at}: unknown placement "${row.placement}"`);
- continue;
- }
- const [, namespace, provider, kind] = form;
- if (row.placement === 'keep-flat') {
- if (row.aliasNeeded === true) {
- bad.push(`${at}: keep-flat needs no alias`);
- }
- } else if (
- typeof row.evidence !== 'string' ||
- row.evidence.trim() === ''
- ) {
- bad.push(`${at}: ${row.placement} needs an evidence note`);
- }
- if (namespace != null && !created.has(namespace)) {
- bad.push(`${at}: namespace "${namespace}" is not decided "create"`);
- }
- if (provider != null) {
- // A member has no doc of its own; it goes where its parent doc goes.
- const placedAs =
- row.kind === 'component-member' ? 'component' : row.kind;
- const placed = [...(groups.get(at)?.placed ?? [])];
- if (!isDescriptorRow(row)) {
- bad.push(`${at}: generated placement is for typed descriptors`);
- } else if (provider !== row.provider || kind !== placedAs) {
- bad.push(
- `${at}: generated placement must be ${row.provider}/${placedAs}`,
- );
- } else if (placed.length > 0) {
- bad.push(`${at}: ${placed.join(', ')} author a placement`);
- }
- }
- if (row.kind === 'section') {
- const hash = at.indexOf('#');
- const topic = hash > 0 ? topics.get(at.slice(0, hash)) : undefined;
- if (topic && row.placement !== topic.placement && !row.evidence) {
- bad.push(`${at}: leaves its topic without an evidence note`);
- }
- if (topic?.aliasNeeded === true && row.aliasNeeded !== true) {
- bad.push(`${at}: its topic moves, so its old route needs an alias`);
- }
- }
- }
- for (const ns of table.namespaces) {
- const at = `namespace "${ns.name}"`;
- if (!new RegExp(`^${SEGMENT}$`).test(ns.name)) {
- bad.push(`${at}: not a path segment`);
- }
- if (ns.decision !== 'create' && ns.decision !== 'reject') {
- bad.push(`${at}: decision must be create or reject`);
- }
- if (typeof ns.evidence !== 'string' || ns.evidence.trim() === '') {
- bad.push(`${at}: no evidence`);
- }
- const used = table.rows.some(
- row =>
- row.placement === `namespace:${ns.name}` ||
- row.placement?.startsWith(`namespace:${ns.name}/`),
- );
- if (ns.decision === 'create' && !used) {
- bad.push(`${at}: created, but no row is placed in it`);
- }
- }
- expect(bad).toEqual([]);
- });
-
- it(
- '(d) puts every descriptor a namespace row names where the tree does',
- async () => {
- const tree = await loadDocsTree();
- /** @type {Map<string, string>} */
- const routeOf = new Map(
- [...tree.nodes.values()].map(node => [
- `${node.provider}/${node.kind}/${node.name}`,
- node.route,
- ]),
- );
- /** @type {string[]} */
- const bad = [];
- for (const row of table.rows) {
- if (!isDescriptorRow(row) || !row.placement.startsWith('namespace:')) {
- continue;
- }
- const under = row.placement.slice('namespace:'.length);
- for (const id of idsFile[row.id] ?? []) {
- const route = routeOf.get(`${row.provider}/${row.kind}/${id}`);
- if (
- route == null ||
- route.slice(0, route.lastIndexOf('/')) !== under
- ) {
- bad.push(
- `${row.id} "${id}": the tree puts it at ${route ?? 'no route'}, not under ${under}`,
- );
- }
- }
- }
- expect(bad).toEqual([]);
- },
- SLOW,
- );
-});
diff --git a/packages/cli/test/docs-graph.test.mjs b/packages/cli/test/docs-graph.test.mjs
deleted file mode 100644
index eaf125ec4b..0000000000
--- a/packages/cli/test/docs-graph.test.mjs
+++ /dev/null
@@ -1,537 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file The docs graph stays walkable (spec:AST-047, spec:AST-046).
- *
- * The walk starts at the topic list and opens every topic, topic index,
- * section, namespace, and typed doc the CLI ships, the way a reader would: it
- * follows each child and each move a read offers (`up`, `previous`, `next`),
- * and fails on any move that does not open. It then checks the moves agree
- * with each other, opens every `astryx docs ...` command written in a doc's
- * own text, and opens every search hit's command and parent. Nothing stores
- * the moves, so this is what proves they stay right as docs are added, moved,
- * or removed.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {fileURLToPath} from 'node:url';
-import {describe, it, expect, beforeAll} from 'vitest';
-import {docs} from '../api/docs/docs.mjs';
-import {typedEdges} from '../api/docs/node/node.mjs';
-import {
- builtinCatalog,
- docsLinkProblems,
- projectTree,
-} from '../api/docs/_adapter.mjs';
-import {loadDocsCatalog} from '../api/docs/_adapter.mjs';
-import {search} from '../api/search/search.mjs';
-import {loadDocsTree} from '../foundation/doc-compiler/tree.mjs';
-import {
- discoverCliSelfDocSources,
- loadCliSelfDocs,
-} from '../foundation/discovery/cli-self-docs.mjs';
-import {routeSegment} from '../foundation/discovery/docs-section-key.mjs';
-import {program, JSON_SUPPORTED} from '../clients/cli/index.mjs';
-import {buildManifest} from '../clients/cli/lib/manifest.mjs';
-import {runCli} from '../test-utils/run-cli.mjs';
-
-const CLI = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-const SLOW = 180_000;
-const TOP = 'astryx docs';
-
-/**
- * Open one `astryx docs ...` command through the API, as the CLI would.
- * @param {string} command
- */
-function open(command) {
- const words = command.trim().split(/\s+/);
- if (words[0] !== 'astryx' || words[1] !== 'docs') {
- throw new Error(`not a docs command: ${command}`);
- }
- const rest = words.slice(2);
- const [topic, section] = rest.filter(w => !w.startsWith('--'));
- return docs(topic, section, {
- index: rest.includes('--index'),
- full: rest.includes('--full'),
- });
-}
-
-/**
- * Every place a read leads: its children, and its moves.
- * @param {any} res
- * @returns {Array<[string, string]>} [kind of move, command]
- */
-function movesOf(res) {
- /** @type {Array<[string, string]>} */
- const out = [];
- const {type, data} = res;
- if (type === 'docs.list') {
- for (const entry of data) {
- out.push(['down', `${TOP} ${entry.topic}`]);
- out.push(['down', `${TOP} ${entry.topic} --index`]);
- }
- for (const entry of res.meta?.namespaces ?? []) {
- out.push(['down', `${TOP} ${entry.topic}`]);
- }
- }
- if (type === 'docs.node') {
- for (const slot of data.slots) {
- for (const child of slot.children) out.push(['down', `${TOP} ${child.route}`]);
- }
- }
- if (type === 'docs.index') {
- for (const section of data.sections) {
- out.push(['down', `${TOP} ${data.name} ${section.id}`]);
- }
- }
- for (const [kind, value] of Object.entries(data?.links ?? {})) {
- for (const command of [value].flat()) {
- out.push([kind, /** @type {string} */ (command)]);
- }
- }
- // Links between docs are moves too: each reference block, and each
- // workflow step's references.
- const blocks = [
- ...(data?.content ?? []),
- ...(data?.sections ?? []).flatMap((/** @type {any} */ s) => s.content ?? []),
- ];
- for (const block of blocks) {
- if (block?.type === 'reference' && block.link) {
- out.push(['reference', block.link.command]);
- }
- for (const step of block?.type === 'workflow' ? block.steps : []) {
- for (const link of step.links ?? []) {
- if (link) out.push(['reference', link.command]);
- }
- }
- }
- return out;
-}
-
-/**
- * The words a read says: prose, list items, and table cells.
- * @param {any} res
- * @returns {string[]}
- */
-function textOf(res) {
- /** @type {string[]} */
- const out = [];
- /** @param {any[]} blocks */
- const scan = blocks => {
- for (const block of blocks ?? []) {
- if (block.type === 'prose' && block.text) out.push(block.text);
- if (block.type === 'list') {
- for (const item of block.items ?? []) {
- out.push(typeof item === 'string' ? item : (item?.text ?? ''));
- }
- }
- if (block.type === 'table') {
- for (const row of block.rows ?? []) out.push(...row.map(String));
- }
- if (block.type === 'code' && typeof block.code === 'string') {
- out.push(block.code);
- }
- }
- };
- const {type, data} = res;
- if (type === 'docs.detail') {
- out.push(data.description ?? '');
- for (const section of data.sections ?? []) scan(section.content);
- }
- if (type === 'docs.index') out.push(data.description ?? '');
- if (type === 'docs.detail.section') scan(data.content);
- if (type === 'docs.node') scan(data.content);
- return out;
-}
-
-/**
- * Every `astryx ...` command a text shows: in code ticks, or on a line of its
- * own (a code block line, or a hint line such as `Up: npx astryx docs cli`).
- * A hint's description, after two spaces or a `#`, is cut off.
- * @param {string} text
- * @returns {string[]}
- */
-function shownCommands(text) {
- const RUN = '(?:npx |pnpm exec |pnpm dlx |yarn |bunx )?astryx(?: [^`\\n]*)?';
- /** @param {string} s */
- const clean = s => s.replace(/\s{2,}.*$/, '').replace(/\s+#.*$/, '').trim();
- /** @type {Set<string>} */
- const out = new Set();
- for (const m of text.matchAll(new RegExp('`(' + RUN + ')`', 'g'))) {
- out.add(clean(m[1]));
- }
- for (const line of text.split('\n')) {
- const m = new RegExp('^\\s*(?:\\$\\s+|[A-Z][A-Za-z ]*:\\s+)?(' + RUN + ')$').exec(line);
- if (m) out.add(clean(m[1]));
- }
- return [...out];
-}
-
-/**
- * The CLI's commands and options, from the live manifest: nothing here is a
- * list someone keeps.
- */
-function cliSurface() {
- const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED});
- /** @param {Array<{flag: string}>} options */
- const flagsOf = options => {
- /** @type {Map<string, boolean>} flag -> takes a value */
- const flags = new Map();
- for (const option of options ?? []) {
- const takes = /[<[]/.test(option.flag);
- for (const flag of option.flag.split(/[\s,]+/)) {
- if (flag.startsWith('-')) flags.set(flag, takes);
- }
- }
- return flags;
- };
- /** @type {Map<string, Map<string, boolean>>} */
- const commands = new Map();
- /** @param {any[]} list */
- const add = list => {
- for (const command of list ?? []) {
- commands.set(command.name, flagsOf(command.options));
- add(command.subcommands);
- }
- };
- add(manifest.commands);
- return {commands, global: flagsOf(manifest.globalOptions)};
-}
-
-/**
- * What is wrong with one shown command, or null: an unknown command, or an
- * option its command does not take. Positional arguments are not checked
- * here; `astryx docs` routes are, by the walk.
- * @param {string} shown
- * @param {ReturnType<typeof cliSurface>} surface
- * @returns {string | null}
- */
-function problemWith(shown, {commands, global}) {
- const words = shown.split(/\s+/);
- const rest = words.slice(words.indexOf('astryx') + 1).filter(Boolean);
- /** @param {Map<string, boolean>} flags @param {string} token */
- const known = (flags, token) => {
- const flag = token.split('=')[0];
- return (
- flag === '--help' ||
- flag === '-h' ||
- flags.has(flag) ||
- (flag.startsWith('--no-') && flags.has(`--${flag.slice(5)}`))
- );
- };
- let i = 0;
- while (i < rest.length && rest[i].startsWith('-')) {
- if (!known(global, rest[i])) return `unknown global option ${rest[i]}`;
- if (global.get(rest[i]) && !rest[i].includes('=')) i++;
- i++;
- }
- // `help` is Commander's own command; a placeholder names no command.
- if (i >= rest.length || rest[i] === 'help' || /^[<[]/.test(rest[i])) return null;
- let name = null;
- for (let n = rest.length - i; n > 0; n--) {
- const candidate = rest.slice(i, i + n).join(' ');
- if (commands.has(candidate)) {
- name = candidate;
- i += n;
- break;
- }
- }
- if (name == null) return `unknown command "${rest[i]}"`;
- const flags = new Map([...global, ...(commands.get(name) ?? [])]);
- for (; i < rest.length; i++) {
- const token = rest[i];
- if (!/^--?[a-zA-Z]/.test(token)) continue;
- if (!known(flags, token)) {
- return `\`astryx ${name}\` has no option ${token.split('=')[0]}`;
- }
- if (flags.get(token) && !token.includes('=')) i++;
- }
- return null;
-}
-
-/**
- * Commands a doc shows on purpose as wrong: the error codes they trigger. Each
- * must still appear in a doc, or the entry is stale.
- */
-const WRONG_ON_PURPOSE = new Map([
- ['astryx bogus', 'the ERR_UNKNOWN_COMMAND example'],
- ['astryx theme bogus', 'the ERR_UNKNOWN_SUBCOMMAND example'],
-]);
-
-/** The CLI's own reads whose hint lines show commands. */
-const HINT_READS = [
- ['docs'],
- ['docs', 'cli'],
- ['docs', 'cli/api/functions/search'],
- ['docs', 'theme'],
- ['docs', 'cli/integrations', 'codemods'],
- ['search', 'token-ref', '--type', 'doc'],
- ['--help'],
- ['docs', '--help'],
-];
-
-/** The `astryx docs ...` commands written in text, placeholders skipped. */
-function docsCommandsIn(text) {
- /** @type {string[]} */
- const out = [];
- for (const m of text.matchAll(/`(?:npx |pnpm exec |yarn |bunx )?astryx docs( [^`]*)?`/g)) {
- const args = (m[1] ?? '').trim();
- if (/[<>…]|\.\.\.|\|/.test(args)) continue;
- out.push(args ? `${TOP} ${args}` : TOP);
- }
- return out;
-}
-
-describe('the docs graph', () => {
- /** @type {Map<string, any>} */
- const reads = new Map();
- /** @type {Array<[string, string, string]>} */
- const moves = [];
- /** @type {string[]} */
- const dead = [];
-
- beforeAll(async () => {
- const queue = [TOP];
- while (queue.length > 0) {
- const command = /** @type {string} */ (queue.shift());
- if (reads.has(command)) continue;
- let res;
- try {
- res = await open(command);
- } catch (e) {
- dead.push(`${command}: ${/** @type {Error} */ (e).message}`);
- reads.set(command, null);
- continue;
- }
- reads.set(command, res);
- for (const [kind, to] of movesOf(res)) {
- moves.push([command, kind, to]);
- if (!reads.has(to)) queue.push(to);
- }
- }
- }, SLOW);
-
- it('opens every move a read offers, from the top down', () => {
- expect(dead).toEqual([]);
- expect(reads.size).toBeGreaterThan(200);
- });
-
- it('reaches every node of the tree', async () => {
- const tree = await loadDocsTree();
- const missed = [...tree.nodes.values()]
- .map(node => `${TOP} ${node.route}`)
- .filter(command => !reads.get(command));
- expect(missed).toEqual([]);
- });
-
- it('reaches every doc file the CLI ships, and every doc file is one the CLI reads', async () => {
- const tree = await loadDocsTree();
- const reached = (/** @type {string} */ command) => Boolean(reads.get(command));
- /** @type {string[]} */
- const unreached = [];
- // Command, API, schema, enum, and authoring docs: a tree leaf, or a section
- // of `astryx docs authoring`.
- const {loaded, failed} = await loadCliSelfDocs(discoverCliSelfDocSources(CLI), CLI);
- expect(failed).toEqual([]);
- const authoring = reads.get(`${TOP} authoring --index`)?.data.sections ?? [];
- for (const {source, doc} of loaded) {
- const leaf = [...tree.nodes.values()].find(
- node => node.kind === doc.type && node.name === doc.name,
- );
- const section = authoring.find(
- (/** @type {any} */ s) => s.id === routeSegment(doc.name) || s.title === doc.displayName,
- );
- const ok = leaf
- ? reached(`${TOP} ${leaf.route}`)
- : section
- ? reached(`${TOP} authoring ${section.id}`)
- : false;
- if (!ok) unreached.push(source);
- }
- // Topics, and the tree's own files.
- const catalog = await loadDocsCatalog(CLI);
- const topicFiles = new Set();
- for (const entry of catalog.entries()) {
- topicFiles.add(path.resolve(entry.path));
- if (!reached(`${TOP} ${entry.name}`)) unreached.push(`topic ${entry.name}`);
- }
- const treeFiles = fs
- .readdirSync(path.join(CLI, 'assets/docs/tree'))
- .filter(name => name.endsWith('.doc.mjs'))
- .map(name => `assets/docs/tree/${name}`);
- for (const file of treeFiles) {
- const node = [...tree.nodes.values()].find(n =>
- [n.source, n.ref?.topicFile].some(s => String(s ?? '').endsWith(file)),
- );
- if (!node || !reached(`${TOP} ${node.route}`)) unreached.push(file);
- }
- expect(unreached).toEqual([]);
-
- // Every doc file under the docs directory is a topic, an overlay of one
- // (`.doc.<variant>.mjs`), or a tree file: none sits where nothing reads it.
- const orphans = fs
- .readdirSync(path.join(CLI, 'assets/docs'))
- .filter(name => /\.doc\.mjs$/.test(name))
- .filter(name => !topicFiles.has(path.resolve(CLI, 'assets/docs', name)));
- expect(orphans).toEqual([]);
- // A floor, not an exact count: it fails if the walk stops finding the tree.
- expect(loaded.length).toBeGreaterThan(80);
- });
-
- it('resolves every typed edge a doc declares: command, fn, and related', async () => {
- const tree = await loadDocsTree();
- /** @type {string[]} */
- const broken = [];
- for (const node of tree.nodes.values()) {
- for (const edge of typedEdges(tree, node).unresolved) {
- broken.push(`${node.route}: ${edge}`);
- }
- }
- expect(broken).toEqual([]);
- });
-
- it('resolves every link written in a doc: inline, reference, and workflow', async () => {
- // The walk opens each resolved link as a move; a link that names no doc
- // has no command to open, so it is caught here, by the same resolver
- // `astryx doctor` uses.
- const catalog = builtinCatalog();
- expect(await docsLinkProblems(catalog, await projectTree(catalog))).toEqual(
- [],
- );
- for (const [command, res] of reads) {
- const blocks = [
- ...(res?.data?.content ?? []),
- ...(res?.data?.sections ?? []).flatMap(
- (/** @type {any} */ s) => s.content ?? [],
- ),
- ];
- for (const block of blocks) {
- if (block?.type === 'reference') {
- expect(block.link, `${command}: ${block.target}`).toBeTruthy();
- }
- for (const text of [block?.text, ...(block?.items ?? [])]) {
- if (typeof text === 'string') {
- expect(
- text.replace(/`[^`]*`/g, ''),
- `${command} shows an unresolved link`,
- ).not.toMatch(/\{@link /);
- }
- }
- }
- }
- }, SLOW);
-
- it('offers a way up from every read but the top, and up always ends at the top', () => {
- const noUp = [...reads]
- .filter(([command, res]) => res && command !== TOP && !res.data?.links?.up)
- .map(([command]) => command);
- expect(noUp).toEqual([]);
- /** @type {string[]} */
- const lost = [];
- for (const [command, res] of reads) {
- let at = res;
- let steps = 0;
- while (at?.data?.links?.up && steps < 10) {
- at = reads.get(at.data.links.up);
- steps++;
- }
- if (at?.type !== 'docs.list') lost.push(command);
- }
- expect(lost).toEqual([]);
- });
-
- it('agrees on neighbors: the next read names this one as its previous', async () => {
- /** @type {string[]} */
- const broken = [];
- // A topic's section list and its whole read are one place.
- /** @param {string | undefined} command */
- const place = command => command?.replace(/ --index$/, '');
- for (const [from, kind, to] of moves) {
- if (kind !== 'next') continue;
- const back = reads.get(to)?.data?.links?.previous;
- if (place(back) !== place(from)) broken.push(`${from} -> ${to} <- ${back}`);
- }
- expect(broken).toEqual([]);
- });
-
- it('opens every `astryx docs ...` command written in a doc', async () => {
- /** @type {string[]} */
- const stale = [];
- const checked = new Set();
- for (const [command, res] of reads) {
- if (!res) continue;
- for (const text of textOf(res)) {
- for (const link of docsCommandsIn(text)) {
- if (checked.has(link)) continue;
- checked.add(link);
- try {
- await open(link);
- } catch (e) {
- stale.push(`${command} names \`${link}\`: ${/** @type {Error} */ (e).message}`);
- }
- }
- }
- }
- expect(stale).toEqual([]);
- expect(checked.size).toBeGreaterThan(10);
- }, SLOW);
-
- it('shows only real commands with real options, in docs, hints, and the agent prompt', async () => {
- const surface = cliSurface();
- /** @type {Map<string, string>} command -> where it is shown */
- const shown = new Map();
- for (const [command, res] of reads) {
- if (!res) continue;
- for (const text of textOf(res)) {
- for (const each of shownCommands(text)) {
- if (!shown.has(each)) shown.set(each, command);
- }
- }
- }
- for (const args of HINT_READS) {
- const {stdout} = await runCli(args);
- for (const each of shownCommands(stdout)) {
- if (!shown.has(each)) shown.set(each, `astryx ${args.join(' ')}`);
- }
- }
- const prompt = fs.readFileSync(path.join(CLI, '..', '..', 'AGENTS.md'), 'utf8');
- const block = /<!-- ASTRYX-CLI:START -->([\s\S]*?)<!-- ASTRYX-CLI:END -->/.exec(prompt)?.[1] ?? '';
- for (const each of shownCommands(block)) {
- if (!shown.has(each)) shown.set(each, 'the agent prompt in AGENTS.md');
- }
- /** @type {string[]} */
- const wrong = [];
- for (const [command, where] of shown) {
- if (WRONG_ON_PURPOSE.has(command.replace(/^(?:npx |pnpm exec |yarn |bunx )/, ''))) continue;
- const problem = problemWith(command, surface);
- if (problem) wrong.push(`${where} shows \`${command}\`: ${problem}`);
- }
- expect(wrong).toEqual([]);
- const stale = [...WRONG_ON_PURPOSE.keys()].filter(
- command => ![...shown.keys()].some(each => each.endsWith(command)),
- );
- expect(stale).toEqual([]);
- expect(shown.size).toBeGreaterThan(50);
- }, SLOW);
-
- it("opens every search hit's command and parent", async () => {
- /** @type {string[]} */
- const broken = [];
- for (const query of ['assertResponse', 'token-ref', 'codemod protected files', 'agent docs', 'ERR_UNKNOWN_SECTION', 'theme', 'unorganized', 'Astryx CLI']) {
- const {data} = await search(query, {type: 'doc', limit: 20});
- for (const hit of data.results) {
- if (!hit.parent) broken.push(`"${query}": ${hit.name} has no parent`);
- for (const command of [hit.command, hit.parent].filter(Boolean)) {
- try {
- await open(command);
- } catch (e) {
- broken.push(`"${query}": ${command}: ${/** @type {Error} */ (e).message}`);
- }
- }
- }
- }
- expect(broken).toEqual([]);
- }, SLOW);
-});
diff --git a/packages/cli/test/drift/docs-drift.mjs b/packages/cli/test/drift/docs-drift.mjs
index f68d75cd3c..52cd547a22 100644
--- a/packages/cli/test/drift/docs-drift.mjs
+++ b/packages/cli/test/drift/docs-drift.mjs
@@ -7,7 +7,8 @@
* - each CommandDoc's `fn` resolves to a FunctionDoc, its arg/option `param`s
* exist on that function, and its `name` is a real manifest command;
* - the error-codes EnumDoc == ERROR_CODES exactly;
- * - the response-types EnumDoc == the manifest's response discriminants.
+ * - the response-types EnumDoc == the manifest's response discriminants plus
+ * the root types (help, version) no single command owns.
*
* @position packages/cli/test/drift — colocated-docs drift harness
*/
@@ -18,6 +19,7 @@ import * as path from 'node:path';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {parseDoc} from '../../authoring/index.mjs';
import {allErrorCodes} from '../../foundation/response/error-codes.mjs';
+import {ROOT_RESPONSE_TYPES} from '../../clients/cli/lib/manifest.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
const CLI_ROOT = path.resolve(HERE, '../..');
@@ -177,13 +179,14 @@ export async function runDrift() {
errors.push(`${file}: subcommand "${s}" is in the doc but not the CLI`);
}
- // Enum drift: error-codes == ERROR_CODES; response-types == manifest set.
+ // Enum drift: error-codes == ERROR_CODES; response-types == the manifest's
+ // per-command set plus the root types (help, version) no command owns.
checkEnumSet(errors, docs, 'error-codes', new Set(allErrorCodes()));
checkEnumSet(
errors,
docs,
'response-types',
- new Set(Object.values(manifest.responseTypes).flat()),
+ new Set([...Object.values(manifest.responseTypes).flat(), ...ROOT_RESPONSE_TYPES]),
);
return {count: docs.length, errors};
diff --git a/scripts/generate-token-docs.mjs b/scripts/generate-token-docs.mjs
index b02c3c4832..f67b24caf2 100644
--- a/scripts/generate-token-docs.mjs
+++ b/scripts/generate-token-docs.mjs
@@ -3,13 +3,15 @@
/**
* @file generate-token-docs.mjs
- * @description Generates packages/cli/assets/docs/tokens.doc.mjs from the source of
- * truth: packages/core/src/theme/tokens.stylex.ts
+ * @description Generates packages/cli/assets/docs/tokens.doc.mjs from the sources
+ * of truth: packages/core/src/theme/tokens.stylex.ts, plus the domain tokens in
+ * packages/core/src/theme/domainTokens/dataTokens.ts (data visualization) and
+ * packages/core/src/theme/syntax/tokens.ts (code syntax).
*
* Run: node scripts/generate-token-docs.mjs
- * CI: Add to lint or build to catch drift.
+ * CI: `node scripts/generate-token-docs.mjs --check` fails on drift.
*
- * Reads the *Defaults export objects from tokens.stylex.ts, groups them by
+ * Reads the *Defaults export objects from those files, groups them by
* category, and writes a ReferenceDoc-shaped .doc.mjs file.
*/
@@ -20,19 +22,37 @@ import {fileURLToPath} from 'node:url';
const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(__dirname, '..');
const TOKENS_SRC = resolve(ROOT, 'packages/core/src/theme/tokens.stylex.ts');
+const DATA_TOKENS_SRC = resolve(
+ ROOT,
+ 'packages/core/src/theme/domainTokens/dataTokens.ts',
+);
+const SYNTAX_TOKENS_SRC = resolve(
+ ROOT,
+ 'packages/core/src/theme/syntax/tokens.ts',
+);
const TOKENS_DOC = resolve(ROOT, 'packages/cli/assets/docs/tokens.doc.mjs');
// ---------------------------------------------------------------------------
// 1. Parse token groups from source
// ---------------------------------------------------------------------------
-const src = readFileSync(TOKENS_SRC, 'utf-8');
+/** Each source file's text, read once. */
+const sources = new Map();
+
+/** @param {string} file */
+function sourceText(file) {
+ if (!sources.has(file)) sources.set(file, readFileSync(file, 'utf-8'));
+ return sources.get(file);
+}
/**
* Extract key-value pairs from a `const xxxDefaults = { ... } as const;` block.
* Returns array of [tokenName, defaultValue].
+ * @param {string} name
+ * @param {string} [file] the source that exports it (default tokens.stylex.ts)
*/
-function extractDefaults(name) {
+function extractDefaults(name, file = TOKENS_SRC) {
+ const src = sourceText(file);
// Match: `export const <name> = {` ... `} as const;`
const re = new RegExp(
`export const ${name}\\s*=\\s*\\{([^}]+(?:\\{[^}]*\\}[^}]*)*)\\}\\s*as const`,
@@ -52,7 +72,29 @@ function extractDefaults(name) {
return pairs;
}
-/** Map of group name → { exportName, title, description, headers } */
+/**
+ * A `light-dark(<light>, <dark>)` value as its two halves. Splits at the
+ * comma at nesting depth 0, so a half that holds its own commas, such as
+ * `rgba(0, 0, 0, 0.1)`, stays whole. Anything else is the same in both modes.
+ * @param {string} name
+ * @param {string} value
+ * @returns {[string, string, string]}
+ */
+function lightDarkRow(name, value) {
+ const inner = value.match(/^light-dark\((.*)\)$/s)?.[1];
+ let depth = 0;
+ for (let i = 0; inner != null && i < inner.length; i++) {
+ const c = inner[i];
+ if (c === '(') depth++;
+ else if (c === ')') depth--;
+ else if (c === ',' && depth === 0) {
+ return [name, inner.slice(0, i).trim(), inner.slice(i + 1).trim()];
+ }
+ }
+ return [name, value, value];
+}
+
+/** Map of group name → { exportName, file?, title, description, headers } */
const groups = [
{
key: 'color',
@@ -62,11 +104,29 @@ const groups = [
description:
'Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching.',
headers: ['Token', 'Light', 'Dark'],
- formatRow(name, value) {
- const ldMatch = value.match(/^light-dark\(([^,]+),\s*([^)]+)\)$/);
- if (ldMatch) return [name, ldMatch[1].trim(), ldMatch[2].trim()];
- return [name, value, value];
- },
+ formatRow: lightDarkRow,
+ },
+ {
+ key: 'data',
+ previewType: 'swatch',
+ exportName: 'dataTokenDefaults',
+ file: DATA_TOKENS_SRC,
+ title: 'Data Visualization Tokens',
+ description:
+ 'Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps.',
+ headers: ['Token', 'Light', 'Dark'],
+ formatRow: lightDarkRow,
+ },
+ {
+ key: 'syntax',
+ previewType: 'swatch',
+ exportName: 'syntaxTokenDefaults',
+ file: SYNTAX_TOKENS_SRC,
+ title: 'Syntax Tokens',
+ description:
+ 'Code highlighting colors used by CodeBlock. Each defaults to a palette token, so syntax colors follow the theme; defineTheme({syntax}) sets a syntax theme instead.',
+ headers: ['Token', 'Value'],
+ formatRow: (name, value) => [name, value],
},
{
key: 'spacing',
@@ -192,7 +252,7 @@ const groups = [
const sections = [];
for (const group of groups) {
- const pairs = extractDefaults(group.exportName);
+ const pairs = extractDefaults(group.exportName, group.file);
if (pairs.length === 0) continue;
const rows = pairs.map(([name, value]) => group.formatRow(name, value));
@@ -217,7 +277,7 @@ sections.push({
lang: 'tsx',
label: 'Using token imports',
code: `import * as stylex from '@stylexjs/stylex';
-import {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core';
+import {colorVars, spacingVars, sizeVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';
const styles = stylex.create({
card: {
@@ -245,7 +305,7 @@ const isCheck = process.argv.includes('--check');
// Count total tokens for the header comment
const totalTokens = groups.reduce(
- (sum, g) => sum + extractDefaults(g.exportName).length,
+ (sum, g) => sum + extractDefaults(g.exportName, g.file).length,
0,
);
@@ -253,7 +313,8 @@ const output = `\
// Copyright (c) Meta Platforms, Inc. and affiliates.
// AUTO-GENERATED — do not edit manually.
-// Source: packages/core/src/theme/tokens.stylex.ts
+// Source: packages/core/src/theme/tokens.stylex.ts,
+// domainTokens/dataTokens.ts, and syntax/tokens.ts
// Run: node scripts/generate-token-docs.mjs
// Total: ${totalTokens} tokens across ${groups.length} categories.
@@ -265,7 +326,9 @@ export const docs = ${JSON.stringify(
title: 'All Tokens',
category: 'foundations',
description:
- 'Complete reference for spacing, color, radius, typography, shadow, motion, and size tokens.',
+ 'Complete reference for color, data visualization, syntax, spacing, size, border, focus, radius, shadow, motion, and typography tokens.',
+ // Words readers search for that the titles do not use (`astryx search`).
+ keywords: ['design tokens', 'css variables', 'custom properties'],
sections,
},
null,
diff --git a/scripts/template-score-ledger.mjs b/scripts/template-score-ledger.mjs
index e320c9f60e..f54d5f570b 100644
--- a/scripts/template-score-ledger.mjs
+++ b/scripts/template-score-ledger.mjs
@@ -3,9 +3,13 @@
/**
* @file Template audit ledger reader, writer, queue, stats, and wiki publisher.
- * @input Template scorecards plus page/block templates under packages/cli/assets/templates.
- * @output Validated template-scores.json updates, summaries, and optional wiki pushes.
- * @position Standalone source of truth for recording template audits.
+ * @input Template scorecards, the canonical rubric exported by
+ * packages/cli/assets/docs/tree/template-quality.doc.mjs, and page/block
+ * templates under packages/cli/assets/templates.
+ * @output Validated template-scores.json updates, summaries, and optional wiki
+ * pushes.
+ * @position Ledger persistence for the public rubric. Category ids, weights,
+ * version, and grade bands are owned by the shipped template-quality doc.
*
* SYNC: Keep this schema aligned with apps/sandbox/src/data/templateAudits.ts.
*/
@@ -15,6 +19,7 @@ import os from 'node:os';
import path from 'node:path';
import {execFileSync} from 'node:child_process';
import {fileURLToPath} from 'node:url';
+import {TEMPLATE_RUBRIC} from '../packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -31,15 +36,11 @@ export const WIKI_CACHE_DIR = path.join(
'astryx-template-score-ledger-wiki',
);
-export const TEMPLATE_CATEGORIES = Object.freeze([
- {id: 'component_purity', title: 'Astryx component purity', max: 30},
- {id: 'icon_purity', title: 'Icon purity', max: 15},
- {id: 'custom_css', title: 'Custom CSS', max: 15},
- {id: 'layout_structure', title: 'Layout & structure', max: 15},
- {id: 'doc_metadata', title: 'Doc metadata', max: 10},
- {id: 'image_handling', title: 'Image handling', max: 5},
- {id: 'code_quality', title: 'Code quality', max: 10},
-]);
+export const TEMPLATE_CATEGORIES = Object.freeze(
+ TEMPLATE_RUBRIC.categories.map(({id, title, max}) =>
+ Object.freeze({id, title, max}),
+ ),
+);
const CATEGORY_BY_ID = new Map(
TEMPLATE_CATEGORIES.map(category => [category.id, category]),
@@ -124,11 +125,7 @@ function assertNonEmptyString(value, label) {
}
export function templateGrade(score) {
- if (score >= 90) return 'A';
- if (score >= 75) return 'B';
- if (score >= 60) return 'C';
- if (score >= 40) return 'D';
- return 'F';
+ return TEMPLATE_RUBRIC.grades.find(({min}) => score >= min)?.grade ?? 'F';
}
export function isTemplateId(id) {
diff --git a/scripts/template-score-ledger.test.mjs b/scripts/template-score-ledger.test.mjs
index dec671cf9b..9605117ef7 100644
--- a/scripts/template-score-ledger.test.mjs
+++ b/scripts/template-score-ledger.test.mjs
@@ -15,6 +15,7 @@ import os from 'node:os';
import path from 'node:path';
import {describe, expect, it} from 'vitest';
+import {TEMPLATE_RUBRIC} from '../packages/cli/assets/docs/tree/template-grading-rubric.doc.mjs';
import {
TEMPLATE_CATEGORIES,
@@ -101,11 +102,18 @@ describe('the public ledger contract', () => {
});
it('uses the rubric grade boundaries', () => {
+ expect(TEMPLATE_RUBRIC.version).toBe('1.4');
expect(
[100, 90, 89.9, 75, 74.9, 60, 59.9, 40, 39.9, 0].map(templateGrade),
).toEqual(['A', 'A', 'B', 'B', 'C', 'C', 'D', 'D', 'F', 'F']);
});
+ it('reads category ids and weights from the shipped rubric doc', () => {
+ expect(TEMPLATE_CATEGORIES).toEqual(
+ TEMPLATE_RUBRIC.categories.map(({id, title, max}) => ({id, title, max})),
+ );
+ });
+
it('carries the complete 100-point category vocabulary', () => {
expect(TEMPLATE_CATEGORIES.map(category => category.id)).toEqual([
'component_purity',