@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/assets/docs/tree/use-a-theme-in-an-app.doc.mjs

@@ -1,51 +0,0 @@
-// 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}.',
-        },
-      ],
-    },
-  ],
-};

package/assets/docs/tree/verify-packed-template.doc.mjs

@@ -1,77 +0,0 @@
-// 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.',
-          ],
-        },
-      ],
-    },
-  ],
-};

package/assets/docs/tree/versioning.doc.mjs

@@ -1,161 +0,0 @@
-// 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}.',
-        },
-      ],
-    },
-  ],
-};

package/assets/docs/tree/write-good-templates.doc.mjs

@@ -1,64 +0,0 @@
-// 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']},
-    },
-  },
-};

package/assets/docs/tree/write-the-template-file.doc.mjs

@@ -1,154 +0,0 @@
-// 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.',
-          ],
-        },
-      ],
-    },
-  ],
-};

package/authoring/discover/discover.doc.d.mts

@@ -1,13 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * @file SchemaDoc for DiscoverSource, the function `astryx discover` calls to
- * learn which integrations a project could add.
- * @input The DiscoverSource type and the catalog types beside it (`type.ts`),
- *   which `parse.mjs` validates.
- * @output The `discover-source` section of `astryx docs authoring`.
- * @position packages/cli/authoring/discover — schema documentation
- */
-/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
-export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/discover/discover.doc.mjs

@@ -1,138 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file SchemaDoc for DiscoverSource, the function `astryx discover` calls to
- * learn which integrations a project could add.
- * @input The DiscoverSource type and the catalog types beside it (`type.ts`),
- *   which `parse.mjs` validates.
- * @output The `discover-source` section of `astryx docs authoring`.
- * @position packages/cli/authoring/discover — schema documentation
- */
-
-/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
-export const doc = {
-  type: 'schema',
-  name: 'discover-source',
-  displayName: 'DiscoverSource',
-  namespace: 'authoring',
-  description:
-    'A source for `astryx discover`: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as `discover` in astryx.config, or export it as `discover` from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer it saved for that source. Discover only reads: it prints the command that adds a package and never runs it.',
-  appliesTo:
-    '`discover` in astryx.config.*, or the `discover` named export of astryx.integration.*',
-  fields: [
-    {
-      name: 'context',
-      type: 'DiscoverSourceContext',
-      description: 'The one argument the source is called with.',
-      required: true,
-      fields: [
-        {
-          name: 'context.signal',
-          type: 'AbortSignal',
-          description: 'Aborted when the source runs past 30 seconds.',
-          required: true,
-        },
-        {
-          name: 'context.package',
-          type: 'string',
-          description:
-            'Set when discover shows one package: return that package with every version.',
-        },
-        {
-          name: 'context.version',
-          type: 'string',
-          description:
-            "With `package`: return that version's contributions. Without it, the latest release's.",
-        },
-      ],
-    },
-    {
-      name: 'returns',
-      type: 'Promise<DiscoverCatalog>',
-      description:
-        'The catalog. Discover checks it, ignores fields and item kinds it does not know, and refuses any schemaVersion but 1.',
-      required: true,
-      fields: [
-        {
-          name: 'schemaVersion',
-          type: '1',
-          description: 'Version of the catalog shape.',
-          required: true,
-        },
-        {
-          name: 'source',
-          type: '{name: string, generatedAt: string, complete: boolean}',
-          description:
-            'Who answered, when the data was produced (ISO 8601), and false when the source knows its list is partial.',
-          required: true,
-        },
-        {
-          name: 'packages',
-          type: 'DiscoverPackage[]',
-          description:
-            'One entry per npm package. When two sources list the same package, the earlier source wins.',
-          required: true,
-          fields: [
-            {
-              name: 'packages[].package',
-              type: 'string',
-              description: 'The npm name.',
-              required: true,
-            },
-            {
-              name: 'packages[].integration',
-              type: 'string',
-              description:
-                'Shared by every npm name that publishes the same integration. Discover lists an integration once.',
-              required: true,
-            },
-            {
-              name: 'packages[].aliases',
-              type: 'string[]',
-              description:
-                "The integration's other npm names. Discover never offers a package the project has under another name.",
-              required: true,
-            },
-            {
-              name: 'packages[].description',
-              type: 'string',
-              description: 'One line, for the list and search.',
-            },
-            {
-              name: 'packages[].latest',
-              type: 'string | null',
-              description: 'The latest release. Null when there are only prereleases.',
-              required: true,
-            },
-            {
-              name: 'packages[].versions',
-              type: 'DiscoverVersion[]',
-              description:
-                'Every version, newest first: `{version, publishedAt, prerelease, status}`, where status is `ok` or why the version could not be read.',
-              required: true,
-            },
-            {
-              name: 'packages[].contributions',
-              type: 'DiscoverContribution[]',
-              description:
-                "What the requested (else latest) version adds: `{kind, name, title?, summary?, keywords?}`, where kind is `component`, `template`, `doc`, `theme`, `codemod`, or `agent-doc` (a DiscoverKind) and name is the name the CLI uses for it.",
-              required: true,
-            },
-          ],
-        },
-      ],
-    },
-  ],
-  examples: [
-    {
-      label: 'A project source in astryx.config',
-      code:
-        'export default {\n' +
-        '  async discover({signal, package: name, version}) {\n' +
-        '    const res = await fetch(catalogUrl(name, version), {signal});\n' +
-        '    return res.json();\n' +
-        '  },\n' +
-        '};',
-    },
-  ],
-};