@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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

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

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

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/api`: the programmatic API of `@astryxdesign/cli/api`.
+ *
+ * Adopts each function, schema, and enum doc whose `namespace` is `cli/api`,
+ * one generated level per kind: `cli/api/functions`, `cli/api/schemas`, and
+ * `cli/api/enums`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'api',
+  title: 'API',
+  summary:
+    'The programmatic API: functions, the JSON output envelope, error codes, and response types.',
+  keywords: ['api', 'functions', 'schemas', 'enums', 'json'],
+  placement: {parent: 'namespace:cli', slot: 'reference', order: 20},
+  slots: {
+    kinds: {title: 'Reference', accepts: {kinds: ['namespace']}},
+  },
+  adopts: [
+    {
+      source: {group: 'cli/api', kinds: ['function', 'schema', 'enum']},
+      into: 'kinds',
+      groupBy: 'kind',
+    },
+  ],
+};

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

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

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

package/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/astryx-widgets@1.0.0\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}.',
+          ],
+        },
+      ],
+    },
+  ],
+};