@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/monorepos`: how a folder's project is found, in
+ * workspaces and nested folders (spec AST-081 FR2).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'monorepos',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 7,
+  },
+  title: 'Monorepos and nested folders',
+  category: 'guide',
+  keywords: [
+    'monorepo',
+    'workspace',
+    'nested folder',
+    'nested project',
+    'subfolder',
+    'packages folder',
+    'which project',
+    'yarn pnp',
+    'hoisting',
+  ],
+  description:
+    'How Astryx finds the project a folder belongs to, and which version answers in a monorepo, a nested app, or a cloned repository inside another project.',
+  sections: [
+    {
+      id: 'find',
+      title: 'How a project is found',
+      content: [
+        {
+          type: 'prose',
+          text: 'Astryx searches upward from the current folder: `@astryxdesign/core` or `@astryxdesign/cli` installed there or a few folders above, else the nearest `package.json` declaring either, up to the repository root. Folders without any are outside projects.',
+        },
+      ],
+    },
+    {
+      id: 'workspaces',
+      title: 'Workspaces',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'A workspace member declaring Astryx is its own project, even with packages hoisted to the repository root. A root CLI answers it, as always; a member with its own Core and no CLI anywhere gets answered by the astryx command you started.',
+            'A folder without its own `package.json`, such as `src/` or `scripts/`, belongs to the project above it.',
+            'A repository that builds the CLI itself, with the CLI in `packages/cli` next to Core in `packages/core`, runs that CLI.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'nested',
+      title: 'Nested folders',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Folders inside another project, such as nested apps or cloned repositories, answer with the enclosing project's release.",
+            'Folder names compare as your file system compares them: a folder reached through a link, or typed in different letter case on macOS or Windows, answers like the folder itself.',
+            "In a Yarn Plug'n'Play project, Astryx cannot see the project's own CLI, so the astryx command you started answers. Run the project's CLI through Yarn (`yarn astryx`) to use it directly.",
+          ],
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'Part of {@link namespace:global}: what global mode is and how each part works.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/package-and-test.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/package-and-test`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test`:
  * expose a template from its package and prove the copied result in an app.
  */
 

package/assets/docs/tree/page-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/document-the-template/page-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/document-the-template/page-template`:
  * the page-only fields that help people find a page.
  */
 
@@ -31,7 +31,7 @@ export const docs = {
           type: 'code',
           lang: 'javascript',
           label: 'templates/acme-dashboard.doc.mjs',
-          code: `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+          code: `/** @type {import('@astryxdesign/cli/authoring').IntegrationTemplateDoc} */
 export default {
   type: 'page',
   name: 'acme-dashboard',
@@ -49,12 +49,8 @@ export default {
       title: 'Help people find the page',
       content: [
         {
-          type: 'reference',
-          target: 'schema:template-doc',
-          projection: {
-            fields: ['category', 'scaffold'],
-          },
-          presentation: 'full',
+          type: 'prose',
+          text: 'Every field is in {@link schema:template-doc}.',
         },
         {
           type: 'list',

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

@@ -0,0 +1,205 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/problems`: every line global mode prints, with its
+ * cause and fix, quoted from the CLI's own strings (test/global-mode-docs.test.mjs
+ * fails when they differ); install problems package managers cause.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'problems',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 9,
+  },
+  title: 'Troubleshooting global mode',
+  category: 'guide',
+  keywords: [
+    'troubleshooting',
+    'error',
+    'not working',
+    'command not found',
+    'ERR_VERSIONS_UNAVAILABLE',
+    'ERR_PROJECT_REQUIRED',
+    'proxy',
+    'registry',
+    'corepack',
+    'windows',
+    'PATH',
+    'wrong astryx',
+    'fallback',
+    'could not get Astryx',
+  ],
+  description:
+    'Every line Astryx prints in global mode, what it means, and what to do. Plus the install problems package managers cause: permissions, PATH, Corepack, and Windows.',
+  sections: [
+    {
+      id: 'answered-by',
+      title: '"astryx: answered by …"',
+      content: [
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'astryx: answered by CLI 0.7.2 with Core 0.7.2, outside a project',
+        },
+        {
+          type: 'prose',
+          text: 'Information, not an error: it names the version that answered and why. It prints in text mode only, never with `--json`. The other forms: {@link generic:who-answers}.',
+        },
+      ],
+    },
+    {
+      id: 'installing',
+      title: '"installing CLI release … into the per-user cache"',
+      content: [
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'astryx: installing CLI release 0.6.8 into the per-user cache (once)...\nastryx: waiting for another run to finish installing CLI release 0.6.8...',
+        },
+        {
+          type: 'prose',
+          text: "The project's own CLI cannot start, so Astryx is installing the CLI version equal to its Core into its cache once. The second line means another run is installing it; this one waits, up to 15 minutes. To avoid the wait, install the project's dependencies.",
+        },
+      ],
+    },
+    {
+      id: 'notices',
+      title: '"A new release of Astryx is available"',
+      content: [
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'A new release of Astryx is available: 0.7.2 → 0.7.3\nTo upgrade, run: npm i -g @astryxdesign/cli@latest\nTo upgrade, install Node >=22 (this computer runs Node 20.11.0), then run: npm i -g @astryxdesign/cli@latest',
+        },
+        {
+          type: 'prose',
+          text: 'A newer version is out; run the command shown. When the newest version needs a newer Node, the second line names it first. To stop notices, set `NO_UPDATE_NOTIFIER`: {@link generic:updates}.',
+        },
+      ],
+    },
+    {
+      id: 'old-astryx',
+      title: '"The astryx command on this computer runs CLI …"',
+      content: [
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'The astryx command on this computer runs CLI 0.6.4, which answers every folder itself.\nTo upgrade, run: npm i -g @astryxdesign/cli@latest',
+        },
+        {
+          type: 'prose',
+          text: "The first astryx command on your PATH is a version from before global mode, so it ignores your projects' versions. Run the command shown, or remove that install. `astryx doctor` lists every astryx command on your PATH in its `cli-on-path` check.",
+        },
+      ],
+    },
+    {
+      id: 'fallback',
+      title: '"could not get Astryx … to match this project\'s Core"',
+      content: [
+        {
+          type: 'code',
+          lang: 'text',
+          code: "astryx: could not get Astryx 0.6.8 to match this project's Core (the registry could not be reached); answering with CLI 0.7.2 instead\nastryx: could not get Astryx 0.6.8 to match this project's Core (the registry does not have it); answering with CLI 0.7.2 instead\nastryx: could not get Astryx 0.6.8 to match this project's Core (the release cache /home/me/.cache/astryx/releases cannot be written (EACCES)); answering with CLI 0.7.2 instead",
+        },
+        {
+          type: 'prose',
+          text: "The project's own CLI cannot start, so Astryx needs the CLI version equal to its Core, and could not get it, so the command still runs: the astryx command you started answers, as before global mode. Its answers may not match the project's Core until you fix the cause. With `--json`, `meta.answeredBy.copy` is `fallback`. Astryx waits 2 minutes before trying the download again, and 10 minutes after a second failure in a row; reinstalling the project's dependencies fixes the project's own CLI.",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "The registry could not be reached: you are offline, or a proxy blocks it. Astryx installs with npm, so set npm's `proxy`, `https-proxy`, or `registry` in your `.npmrc`, or add the CLI to the project and install its dependencies.",
+            "The registry does not have it: a private registry without the Astryx packages. Point npm's registry for `@astryxdesign` at one that has them.",
+            'The cache cannot be written: a read-only home folder, as in some containers. Point `XDG_CACHE_HOME` at a writable folder: {@link generic:ci-and-containers}.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'not-global',
+      title: 'A global install that gets no update notice or agent guide',
+      content: [
+        {
+          type: 'prose',
+          text: "Astryx treats a copy as installed for your computer only when your package manager's own settings name its folder: npm's global prefix, Bun's `BUN_INSTALL`, Yarn's `global-folder`, pnpm's `PNPM_HOME`, or their defaults. A folder chosen only with a one-off flag, such as `yarn global add --global-folder ~/mine`, is not in any setting, so Astryx treats that copy like a project's: no daily update check and no agent guide. Save the folder in your settings so Astryx knows it is a global install:",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'yarn config set global-folder ~/mine   # writes ~/.yarnrc\nexport BUN_INSTALL=~/mybun              # in your shell profile, for Bun',
+        },
+      ],
+    },
+    {
+      id: 'core-offline',
+      title: '"Core … could not be installed" outside a project',
+      content: [
+        {
+          type: 'prose',
+          text: "Outside a project, commands that read components (`component`, `search`, `template`, `build`, and the like) use your global version's Core. It ships beside the CLI only for some installs; otherwise your global install downloads it once into its cache in the background after a command you run online (on Windows, the first component command downloads it), and a component command before that, offline, fails with `ERR_VERSIONS_UNAVAILABLE`. Reinstalling the CLI does not help: run any command once online, and component reads work offline from then on. In CI nothing downloads in the background, so the first component command there needs the registry. The global-mode pages ({@link namespace:global}) read offline either way.",
+        },
+        {
+          type: 'prose',
+          text: "In a project with nothing installed yet, such as a fresh clone, the same commands use that Core too, and offline the error reads `This project has no Core installed, and Core <version> could not be downloaded`: install the project's dependencies (`npm install`, or your package manager's), and the project's own Core answers from then on.",
+        },
+      ],
+    },
+    {
+      id: 'unavailable',
+      title: 'ERR_VERSIONS_UNAVAILABLE',
+      content: [
+        {
+          type: 'prose',
+          text: 'A run fails with `ERR_VERSIONS_UNAVAILABLE` only when nothing can answer: a command that needs Core outside a project cannot install it, or a version you requested exactly cannot be found.',
+        },
+      ],
+    },
+    {
+      id: 'needs-a-project',
+      title: 'Commands that need a project',
+      content: [
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'Error: No package.json found. Run this command inside an app project.\nError: No package.json found. Run this command inside an integration package.\nError: Could not find @astryxdesign/core package. Make sure you are inside the design system monorepo or have @astryxdesign/core installed.\nError: Could not find installed @astryxdesign/core (or legacy @xds/core). This folder is outside a project; upgrade migrates the code of an app project that installs @astryxdesign/core.',
+        },
+        {
+          type: 'prose',
+          text: "Commands that change an app or a package, such as `theme use`, `integration add`, `swizzle`, and `upgrade`, write nothing outside a project and say what they need. Run them in that project. Each command's doc says what it does outside a project ({@link namespace:commands}); a newer command that refuses uses `ERR_PROJECT_REQUIRED`.",
+        },
+      ],
+    },
+    {
+      id: 'install-problems',
+      title: 'Install problems',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`npm i -g` fails with `EACCES` (permission denied): do not use `sudo`. Use a Node version manager, or give npm a global folder you own: `npm config set prefix ~/.npm-global`, then add `~/.npm-global/bin` to your PATH.',
+            "`astryx: command not found` after installing: your package manager's global bin folder is not on your PATH. `npm prefix -g` shows npm's (its `bin` folder on macOS and Linux); `pnpm setup` adds pnpm's.",
+            '`pnpm add -g` stops with `ERR_PNPM_NO_GLOBAL_BIN_DIR`, often with Corepack: run `pnpm setup`, open a new terminal, and try again. Yarn 2 and later have no `yarn global`; use `npm i -g` instead.',
+            'Windows: npm puts `astryx.cmd` in `%APPDATA%\\npm`, which must be on your PATH. If PowerShell says running scripts is disabled, run `astryx.cmd`, or allow scripts for your user with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.',
+            'Two installs, and the wrong one runs: `astryx doctor` outside a project lists every astryx command on your PATH, in the order your shell tries them.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'This page is part of {@link namespace:global}, which explains what global mode is and how each part works.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/project-global-or-both.doc.mjs

@@ -0,0 +1,131 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/project-global-or-both`: which setup to use, project,
+ * global, or both (recommended), with what each costs and how to set it up.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'project-global-or-both',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 1,
+  },
+  title: 'Project, global, or both',
+  category: 'guide',
+  keywords: [
+    'which setup',
+    'project or global',
+    'global or project',
+    'both',
+    'install in project',
+    'npx @astryxdesign/cli',
+    'dev dependency',
+    'recommended setup',
+    'should i install globally',
+  ],
+  description:
+    'Install Astryx in each project and once for your computer: both is the recommended setup, and the two never conflict. What each side gives you, and how to set it up.',
+  sections: [
+    {
+      id: 'both',
+      title: 'Both (recommended)',
+      content: [
+        {
+          type: 'prose',
+          text: 'Install the CLI in each project and once for your computer. Each side does something the other cannot, and they never conflict:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '**In the project**, the CLI version is pinned in `package.json` and the lockfile, so teammates and CI run exactly that version, with nothing fetched at run time.',
+            '**Globally**, the astryx command works in every folder, including an empty one before a project exists, and every coding agent on your computer knows Astryx through its agent guide.',
+            "**Together**, in a project the project's version always answers, even when you type the global astryx command; outside a project your global version does. Global mode never makes the project's CLI unnecessary.",
+          ],
+        },
+      ],
+    },
+    {
+      id: 'compare',
+      title: 'At a glance',
+      content: [
+        {
+          type: 'table',
+          headers: ['Setup', 'What you get', 'What it costs', 'Who it is for'],
+          rows: [
+            [
+              'Both',
+              'A pinned version in each project, plus docs, components, and search in any folder, and an agent guide for every agent',
+              'Two installs to keep current',
+              'Most people',
+            ],
+            [
+              'Project only',
+              'A version pinned in the repo, the same for the team and CI',
+              "No astryx command outside the project; agents elsewhere don't know Astryx",
+              'CI machines and build servers',
+            ],
+            [
+              'Global only',
+              'Docs, components, and search in any folder; every agent knows Astryx',
+              'Nothing pinned for a team; a project without its own CLI gets whatever version you started',
+              'Agents, prototypes, and quick lookups',
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'set-up',
+      title: 'How to set up each',
+      content: [
+        {
+          type: 'prose',
+          text: 'In the project folder (the getting-started guide lists the other packages an app installs):',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm install @astryxdesign/core @astryxdesign/cli\nastryx init',
+        },
+        {
+          type: 'prose',
+          text: 'Once for your computer:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm i -g @astryxdesign/cli',
+        },
+        {
+          type: 'prose',
+          text: 'For both, do both, in either order.',
+        },
+      ],
+    },
+    {
+      id: 'what-happens',
+      title: 'What happens when you have both',
+      content: [
+        {
+          type: 'prose',
+          text: "In a project, the project's version always answers, even when you type the global astryx command; outside a project, your global version does. {@link generic:who-answers}",
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'This page is part of {@link namespace:global}, which explains what global mode is and how each part works. To start an app: {@link generic:getting-started}.',
+        },
+      ],
+    },
+  ],
+};

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/publishing`: publish an integration to
+ * @file `astryx docs cli/integrations/ship/publishing`: publish an integration to
  * npm, use release tags, and check the package before and after.
  */
 
@@ -14,7 +14,7 @@ export const docs = {
   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.',
+    'Publish your package to npm under the right release tag, checking it before and after.',
   sections: [
     {
       id: 'check-before-you-publish',
@@ -27,7 +27,7 @@ export const docs = {
         {
           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',
+          code: 'astryx doctor integration validate && astryx doctor integration components && astryx doctor integration templates && astryx doctor integration docs && astryx integration verify\nnpm publish --dry-run --access public',
         },
         {
           type: 'code',
@@ -59,7 +59,7 @@ export const docs = {
           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.`',
+            '`integration verify` fails when a root is missing from the list, and names the root to add to `files` (the message is in {@link generic:troubleshooting}).',
           ],
         },
       ],
@@ -79,7 +79,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'To let apps try a release first, publish it under `next`, then point `latest` at it when it is ready.',
+          text: 'To let apps try a release first, publish it under `next`, then point `latest` at it once ready.',
         },
         {
           type: 'code',
@@ -99,7 +99,7 @@ export const docs = {
         {
           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',
+          code: 'mkdir check-release && cd check-release\nnpm init -y\nnpm install @astryxdesign/core @astryxdesign/cli @acme/astryx-widgets@1.0.0\nastryx component AcmeCarousel\nastryx doctor integration validate @acme/astryx-widgets',
         },
         {
           type: 'prose',