@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/assets/docs/tree/add-a-theme.doc.mjs

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

package/assets/docs/tree/add-a-topic.doc.mjs

@@ -1,144 +0,0 @@
-// 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

@@ -1,138 +0,0 @@
-// 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/block-template.doc.mjs

@@ -1,130 +0,0 @@
-// 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

@@ -1,28 +0,0 @@
-// 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

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