@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/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.',
+    },
+  ],
+};

package/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}.',
+        },
+      ],
+    },
+  ],
+};

package/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}
+}`,
+        },
+      ],
+    },
+  ],
+};

package/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',
+    },
+  ],
+};

package/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']}},
+  },
+};

package/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']},
+    },
+  },
+};

package/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}.',
+        },
+      ],
+    },
+  ],
+};

package/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.',
+        },
+      ],
+    },
+  ],
+};