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

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

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/publishing`: publish an integration to
+ * npm, use release tags, and check the package before and after.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'publishing',
+  placement: {parent: 'namespace:ship', slot: 'guides', order: 40},
+  title: 'Publish an integration',
+  category: 'guide',
+  keywords: ['publish an integration', 'npm publish', 'release'],
+  description:
+    'Publish your package to npm under the right release tag, and check it before and after.',
+  sections: [
+    {
+      id: 'check-before-you-publish',
+      title: 'Check before you publish',
+      content: [
+        {
+          type: 'prose',
+          text: 'Publish only a package that passes every check, then preview the upload with `npm publish --dry-run`. The dry run lists the files and the tag without uploading.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration validate && npx astryx doctor integration components && npx astryx doctor integration templates && npx astryx doctor integration docs && npx astryx integration verify\nnpm publish --dry-run --access public',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'npm notice Publishing to https://registry.npmjs.org/ with tag latest and public access (dry-run)\n+ @acme/astryx-widgets@1.0.0',
+        },
+        {
+          type: 'prose',
+          text: 'Set a new `version` for each release; {@link generic:versioning} covers what counts as breaking. What each check proves is in {@link generic:checks}.',
+        },
+      ],
+    },
+    {
+      id: 'keep-private-files-out',
+      title: 'Keep private files out',
+      content: [
+        {
+          type: 'prose',
+          text: 'With no `files` list, npm packs every file your ignore files do not exclude, including an old `.tgz` file or an `.env` file. List what ships instead.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: "npm pkg set 'files[]=components' 'files[]=templates' 'files[]=themes' 'files[]=docs' 'files[]=codemods' 'files[]=astryx.integration.mjs'\nnpm pack --dry-run",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'List only the roots you ship, and always `astryx.integration.mjs`. npm adds package.json, and a README and LICENSE when you have them.',
+            'Each later `integration add` appends its root to the list.',
+            '`integration verify` fails when a root is missing from the list: `Declared templates root "templates" has 0 of 2 expected files in the pack list. Add "templates" to "files" in package.json.`',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'publish-to-npm',
+      title: 'Publish to npm',
+      content: [
+        {
+          type: 'prose',
+          text: 'A scoped package is private by default, so publish it with `--access public`. Without `--tag`, npm tags the release `latest`, which is what `npm install @acme/astryx-widgets` installs.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: '# Publish a release\nnpm publish --access public\n\n# Or set the access once in package.json\nnpm pkg set publishConfig.access=public',
+        },
+        {
+          type: 'prose',
+          text: 'To let apps try a release first, publish it under `next`, then point `latest` at it when it is ready.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: '# Only apps that ask for next get it: npm install @acme/astryx-widgets@next\nnpm publish --tag next\n\n# Make that version the default\nnpm dist-tag add @acme/astryx-widgets@1.1.0 latest\nnpm dist-tag ls @acme/astryx-widgets',
+        },
+      ],
+    },
+    {
+      id: 'check-the-published-package',
+      title: 'Check the published package',
+      content: [
+        {
+          type: 'prose',
+          text: 'Install the version you published in a clean app, and run the same commands you ran against the `.tgz` file.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'mkdir check-release && cd check-release\nnpm init -y\nnpm install @astryxdesign/core @astryxdesign/cli @acme/astryx-widgets@1.0.0\nnpx astryx component AcmeCarousel\nnpx astryx doctor integration validate @acme/astryx-widgets',
+        },
+        {
+          type: 'prose',
+          text: 'The full list of commands to run in an app is in {@link generic:test-in-an-app}. To help apps move to the new version, see {@link generic:upgrading}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/quick-start.doc.mjs

@@ -0,0 +1,272 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'quick-start',
+  placement: {
+    parent: 'namespace:integrations',
+    slot: 'guides',
+    order: 10,
+  },
+  title: 'Quick Start',
+  category: 'guide',
+  keywords: [
+    'make a package',
+    'make an integration',
+    'first integration',
+    'integration tutorial',
+    'package.json',
+    'exports map',
+    'astryx.integration.mjs',
+  ],
+  description:
+    'Create a new integration package or add Astryx to one you already publish.',
+  sections: [
+    {
+      id: 'quick-start',
+      title: 'Quick start',
+      content: [
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Make the package',
+        },
+        {
+          type: 'prose',
+          text: 'An integration starts as a normal npm package. Make a folder for it, create a package.json inside that folder, give the package a name, then install the Astryx CLI and Core for development.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: "mkdir acme-widgets && cd acme-widgets\nnpm init -y\nnpm pkg set name=@acme/astryx-widgets\nnpm pkg set 'exports={}' --json\nnpm install -D @astryxdesign/cli @astryxdesign/core",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Start with `"exports": {}`: each component and template you add then writes the public import that `integration verify` resolves.',
+            'Run the CLI as `npx astryx`, which runs the `@astryxdesign/cli` you installed as a devDependency.',
+            'Component commands read Core, so they need `@astryxdesign/core` installed.',
+          ],
+        },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Add your first integration item',
+        },
+        {
+          type: 'prose',
+          text: 'An integration can ship several kinds of items. Start with a component named `AcmeCarousel`.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration add component AcmeCarousel',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'component contribution added\n\n[ok] AcmeCarousel\n\nDeclare component root ./components in astryx.integration.mjs.\n\n- components/AcmeCarousel.doc.mjs\n- components/AcmeCarousel.tsx\n- package.json\n- astryx.integration.mjs',
+        },
+        {
+          type: 'prose',
+          text: '`integration add` creates the component source, its `.doc.mjs`, the package export, and `astryx.integration.mjs`. Update the generated doc so the CLI understands the component, then write the component itself.',
+        },
+        {
+          type: 'prose',
+          text: 'Read it back the way an app will.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx component AcmeCarousel',
+        },
+        {
+          type: 'prose',
+          text: 'You now have an integration package with one exported component.',
+        },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Verify and pack the package',
+        },
+        {
+          type: 'prose',
+          text: 'Run `integration verify` to check that an app would see the component, then make the `.tgz` file you install next. `--pack-destination ..` writes it beside the package folder, so the next pack does not ship it.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx integration verify\nnpm pack --pack-destination ..',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'Integration package ready\n\n[ok] @acme/astryx-widgets@1.0.0\n\n4 packed files; 3/3 required files present.',
+        },
+        {
+          type: 'prose',
+          text: '`integration verify` packs the package, unpacks it into a temporary app, and checks that the component resolves through its public import there. It publishes nothing and leaves no `.tgz` file, so `npm pack` writes `../acme-astryx-widgets-1.0.0.tgz` for the next step.',
+        },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Use it in an app',
+        },
+        {
+          type: 'prose',
+          text: 'Install Core, the CLI, and your `.tgz` file in a new app. The app loads your package because it is a dependency, with no config.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'cd ..\nmkdir my-app && cd my-app\nnpm init -y\nnpm install @astryxdesign/core @astryxdesign/cli ../acme-astryx-widgets-1.0.0.tgz\nnpx astryx component AcmeCarousel',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: "**Import:** `import {AcmeCarousel} from '@acme/astryx-widgets/components/AcmeCarousel';`",
+        },
+        {
+          type: 'prose',
+          text: 'The next sections explain each package field and the integration file. To build the real component, continue with {@link namespace:components}.',
+        },
+      ],
+    },
+    {
+      id: 'fill-in-package-json',
+      title: 'Fill in package.json',
+      content: [
+        {
+          type: 'prose',
+          text: 'An integration is an ordinary npm package. These six fields control how it is named, developed, checked, and published.',
+        },
+        {
+          type: 'prose',
+          text: '`peerDependencies` are packages the app supplies. `devDependencies` are packages you use while building the integration.',
+        },
+        {
+          type: 'table',
+          headers: ['Field', 'Set it to', 'Why'],
+          rows: [
+            [
+              '`name`',
+              'Your package name, such as `@acme/astryx-widgets`',
+              'Each add writes it into the `import` of the doc it generates. Rename before you add, or update each `import` after.',
+            ],
+            [
+              '`version`',
+              'The release you publish, such as `1.0.0`',
+              'Apps see it; `astryx.integration.mjs` never repeats it.',
+            ],
+            [
+              '`exports`',
+              'Start with `{}`',
+              'Each component and template add writes its public import here, and `integration verify` resolves it.',
+            ],
+            [
+              '`files`',
+              'Optional: the paths to publish',
+              'Keeps private files out. When the list exists, each add appends its root and `astryx.integration.mjs`.',
+            ],
+            [
+              '`peerDependencies`',
+              '`@astryxdesign/cli`; add `@astryxdesign/core` when your code imports it',
+              'The app supplies these packages for your integration.',
+            ],
+            [
+              '`devDependencies`',
+              '`@astryxdesign/cli` and `@astryxdesign/core`',
+              'Lets you run the CLI and build components while working on the integration.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Peer ranges and releases are covered in {@link generic:versioning}; `files` and publishing in {@link generic:publishing}.',
+        },
+      ],
+    },
+    {
+      id: 'the-integration-file',
+      title: 'The integration file',
+      content: [
+        {
+          type: 'prose',
+          text: 'The first `integration add` creates `astryx.integration.mjs`, and each later add updates it. You do not need to write or edit this file during the quick start.',
+        },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Files in the package',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`package.json` defines the npm package, including its name, version, dependencies, published files, and exports.',
+            '`astryx.integration.mjs` tells the CLI where the package keeps each kind of integration item.',
+            'The integration item files live under those roots. For example, a component can have `AcmeWidget.tsx` for its source and `AcmeWidget.doc.mjs` for its documentation.',
+          ],
+        },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Fields in the integration file',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'astryx.integration.mjs',
+          code: "/** @type {import('@astryxdesign/cli/authoring').AstryxIntegration} */\nexport default {\n  components: './components',\n};",
+        },
+        {
+          type: 'prose',
+          text: 'The file tells the CLI where this package keeps its integration items. Edit it only when you want a custom root or another optional setting. Paths are relative to package.json, and later adds keep a custom path you already set.',
+        },
+        {
+          type: 'reference',
+          target: 'schema:integration',
+          projection: {
+            fields: [
+              'providerId',
+              'components',
+              'templates',
+              'codemods',
+              'docs',
+              'themes',
+              'agentDocs',
+              'issuesUrl',
+            ],
+          },
+          presentation: 'full',
+        },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Use the CLI',
+        },
+        {
+          type: 'prose',
+          text: 'You can edit the package files by hand, but the CLI handles the normal workflow. These links always open the canonical command docs.',
+        },
+        {
+          type: 'reference',
+          target: 'command:integration add',
+          presentation: 'summary',
+        },
+        {
+          type: 'reference',
+          target: 'command:integration verify',
+          presentation: 'summary',
+        },
+        {
+          type: 'reference',
+          target: 'command:doctor integration',
+          presentation: 'summary',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/replace-a-core-component.doc.mjs

@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/components/replace-a-core-component`:
+ * intentionally make an integration component the default for a Core identity.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'replace-a-core-component',
+  placement: {parent: 'namespace:components', slot: 'guides', order: 50},
+  title: 'Replace a Core component',
+  category: 'guide',
+  description:
+    'Use a component replacement only when an integration must intentionally own a Core component identity.',
+  sections: [
+    {
+      id: 'decide-whether-to-replace',
+      title: 'Decide whether to replace',
+      content: [
+        {
+          type: 'prose',
+          text: 'Most components should not use `replaces`. Give a new component its own name and let apps choose it explicitly. Replace Core only when your component must become the default for one Core identity everywhere the integration is active.',
+        },
+        {type: 'heading', level: 3, text: 'Use it when'},
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Your component intentionally serves the same role as one specific Core component.',
+            'Every app that loads the integration should get your component from unqualified component detail, lists, search, swizzle, and issue routing.',
+            'You have tested both the replacement and explicit access to the original Core component.',
+          ],
+        },
+        {type: 'heading', level: 3, text: 'Do not use it when'},
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Your component is an alternative, variant, wrapper, or product-specific extension. Give it a unique name instead.',
+            'You only need to resolve an accidental name collision.',
+            'You want the replacement in only one screen or workflow. Replacement applies across the app wherever the integration is active.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'set-the-replacement',
+      title: 'Set the replacement',
+      content: [
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'components/AcmeSideNav.doc.mjs',
+          code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export default {
+  type: 'component',
+  name: 'AcmeSideNav',
+  displayName: 'Acme Side Nav',
+  replaces: 'SideNav',
+  import: '@acme/astryx-widgets/components/AcmeSideNav',
+  usage: {description: 'Product navigation for Acme apps.'},
+  props: [],
+};`,
+        },
+        {
+          type: 'reference',
+          target: 'schema:component-doc',
+          projection: {fields: ['replaces']},
+          presentation: 'full',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`replaces` names the Core `ComponentDoc` identity, not its display label, import path, or a standalone hook.',
+            'Your component may keep a distinct name or use the same name as the target. A distinct name remains directly addressable on older CLIs that ignore `replaces`.',
+            '`--package @astryxdesign/core` always selects the original Core component.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'check-replacement-resolution',
+      title: 'Check replacement resolution',
+      content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration components\nnpx astryx component SideNav\nnpx astryx component AcmeSideNav\nnpx astryx component SideNav --package @astryxdesign/core',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'A missing target, invalid value, second replacement for one target in the same package, or a replacement named after a different Core component is an error.',
+            'When several integrations replace one target, explicit configuration beats the automatic pick. Among explicitly configured integrations, the later package wins and Doctor warns.',
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/replace-a-core-template.doc.mjs

@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/integrations/templates/document-the-template/replace-a-core-template`:
+ * deliberately replace one Core template through template metadata.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'replace-a-core-template',
+  placement: {
+    parent: 'namespace:document-the-template',
+    slot: 'guides',
+    order: 40,
+  },
+  title: 'Replace a Core template',
+  category: 'guide',
+  description:
+    'Use a template replacement only when an integration intentionally changes the default source returned for one Core template id.',
+  sections: [
+    {
+      id: 'replace-only-on-purpose',
+      title: 'Replace only on purpose',
+      content: [
+        {
+          type: 'prose',
+          text: 'Use with care: replace a Core template only when every app using this integration should receive your source for an existing Core id by default. An alternative, a product-specific variation, or a different kind of template gets its own id instead ({@link generic:start-a-template}).',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Sharing a Core id without `replaces` does not replace Core. It makes the bare id ambiguous, so `astryx template <id>` fails until the app adds `--package`, and `doctor integration templates` reports an accidental collision.',
+            'A replacement can keep the Core id or use its own. `replaces` is what makes it the default.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'declare-the-replacement',
+      title: 'Declare the replacement',
+      content: [
+        {
+          type: 'prose',
+          text: 'Find the exact Core id and kind first.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx --json template --list --package @astryxdesign/core',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'templates/acme-app-shell.doc.mjs',
+          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export default {
+  type: 'page',
+  name: 'acme-app-shell',
+  displayName: 'Acme App Shell',
+  description:
+    'An Acme application shell with product navigation, account controls, and a responsive content region.',
+  replaces: 'shell-side-nav',
+  isReady: true,
+  category: 'Shell - Left Sidebar',
+};`,
+        },
+        {
+          type: 'reference',
+          target: 'schema:template-doc',
+          projection: {fields: ['replaces']},
+          presentation: 'full',
+        },
+        {
+          type: 'prose',
+          text: 'Declare `replaces` on the template doc, never in `astryx.integration.mjs`.',
+        },
+      ],
+    },
+    {
+      id: 'require-a-compatible-cli',
+      title: 'Require a compatible CLI',
+      content: [
+        {
+          type: 'prose',
+          text: 'Declare the CLI floor from the field above as an optional peer ({@link generic:versioning}).',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'package.json',
+          code: `{
+  "peerDependencies": {
+    "@astryxdesign/cli": ">=0.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@astryxdesign/cli": {
+      "optional": true
+    }
+  }
+}`,
+        },
+        {
+          type: 'prose',
+          text: '`integration verify` reports `replaces_needs_cli` when that peer is missing or too old. Without it, an older CLI drops that template and hides your doc topics.',
+        },
+      ],
+    },
+    {
+      id: 'what-apps-receive',
+      title: 'What apps receive',
+      content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `# Receives the active replacement
+npx astryx template shell-side-nav src/app
+
+# Receives the original Core template
+npx astryx template shell-side-nav --package @astryxdesign/core src/app`,
+        },
+        {
+          type: 'prose',
+          text: 'When several integrations replace the same Core template, one wins:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'An integration explicitly listed in `astryx.config.mjs` wins over one that is only installed and picked automatically.',
+            'When several explicitly configured integrations replace the same target, the one listed later wins and Astryx reports the ambiguity.',
+            "When no integration is configured explicitly, the package listed later in the app's package.json dependencies wins. Configure the intended integration explicitly instead of relying on that order.",
+          ],
+        },
+      ],
+    },
+    {
+      id: 'check-the-replacement',
+      title: 'Check the replacement',
+      content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npx astryx doctor integration templates',
+        },
+        {
+          type: 'table',
+          headers: ['Issue', 'Meaning'],
+          rows: [
+            [
+              '`missing_template_replacement_target`',
+              '`replaces` does not name a Core template id.',
+            ],
+            [
+              '`invalid_template_replacement`',
+              'The replacement is unusable or its page/block kind differs from Core.',
+            ],
+            [
+              '`ambiguous_template_replacement`',
+              'One package declares two replacements for a target, or several active packages contend for it.',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Replacement resolution is safe by default. A missing source, invalid doc, missing target, wrong kind, or conflicting declaration never hands the Core id to a questionable replacement: Astryx reports the issue and keeps the Core template. Fix every issue before publishing.',
+        },
+      ],
+    },
+  ],
+};