@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/assets/docs/tree/tokens-data.doc.mjs

@@ -17,14 +17,14 @@ export const docs = {
     "order": 20
   },
   "category": "foundations",
-  "description": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Retaining any member emits the complete 56-variable group; an unused graph emits none.",
+  "description": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Source compilation emits the complete 56-variable group when any member is retained and none for an unused graph. Prebuilt CSS consumers load @astryxdesign/core/astryx.css, which defines the complete group for the already-compiled dataVars entry.",
   "sections": [
     {
       "title": "Data Visualization Tokens",
       "content": [
         {
           "type": "prose",
-          "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Retaining any member emits the complete 56-variable group; an unused graph emits none."
+          "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Source compilation emits the complete 56-variable group when any member is retained and none for an unused graph. Prebuilt CSS consumers load @astryxdesign/core/astryx.css, which defines the complete group for the already-compiled dataVars entry."
         },
         {
           "type": "table",

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/help/troubleshooting`: the messages the CLI
+ * @file `astryx docs authoring/help/troubleshooting`: the messages the CLI
  * prints while you build, verify, and install an integration, and the fix
  * for each.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/ship/upgrading`: update an integration
+ * @file `astryx docs authoring/ship/upgrading`: update an integration
  * package for each Astryx release, and the command apps run to upgrade with
  * it.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app`:
+ * @file `astryx docs authoring/building-blocks/themes/use-a-theme-in-an-app`:
  * an app installs the integration and applies or extends the theme, like any theme.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/verify-packed-template`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/package-and-test/verify-packed-template`:
  * what `integration verify` checks for templates, and what it leaves to the
  * app test.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/ship/versioning`: version an integration
+ * @file `astryx docs authoring/ship/versioning`: version an integration
  * package, know which changes break apps, declare peer ranges, keep apps on
  * older CLIs working, and match codemod folders to versions.
  */

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates`:
+ * @file `astryx docs authoring/building-blocks/templates/write-good-templates`:
  * what makes a template good, the rubric that scores it, and grading with an agent.
  */
 

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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/write-the-template-file`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/write-the-template-file`:
  * what gets copied, where the copied file lands, and the imports and
  * export a copied template needs.
  */

package/assets/docs/use-integrations.doc.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+  type: 'generic',
+  name: 'use-integrations',
+  title: 'Use integrations',
+  category: 'guide',
+  description:
+    'Install, discover, and use integration packages that add components, templates, themes, and docs to your app.',
+  keywords: [
+    'install an integration',
+    'add an integration',
+    'install a package',
+    'use an integration',
+    'discover integrations',
+    'integration',
+    'package',
+    'third party',
+    'plugin',
+    'extension',
+  ],
+
+  sections: [
+    {
+      title: 'Discover integrations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Integration packages extend Astryx with extra components, templates, themes, docs, and codemods. They are published as regular npm packages.',
+        },
+        {
+          type: 'prose',
+          text: 'Search for what you need:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx search carousel\nastryx discover',
+        },
+        {
+          type: 'prose',
+          text: '`search` looks across everything the CLI knows (components, docs, templates, themes, and hooks), so a word like "carousel" finds it whether it is a component, a template, or a doc page. `discover` lists every integration the project has, and, with a discover source, packages it could add.',
+        },
+      ],
+    },
+    {
+      title: 'Install an integration',
+      content: [
+        {
+          type: 'prose',
+          text: 'Install the package with your package manager. Integrations autolink: the CLI finds them among your dependencies, so installing is all it takes:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm install @acme/brand-integration',
+        },
+        {
+          type: 'prose',
+          text: 'Run `astryx doctor` to confirm everything is wired up. If you need to load a package that is not a direct dependency, add it explicitly to `astryx.config.mjs`:',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'Optional: explicit config entry',
+          code: "export default {\n  integrations: ['@acme/brand-integration'],\n};",
+        },
+      ],
+    },
+    {
+      title: 'Use what it adds',
+      content: [
+        {
+          type: 'prose',
+          text: 'Once installed, the integration\'s contributions appear alongside Core:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`astryx component --list` shows its components next to Core components.',
+            '`astryx template --list` includes its page and block templates.',
+            '`astryx theme list` lists its themes; add one with `astryx theme add <slug> --package @acme/brand-integration`.',
+            '`astryx docs` shows any guides it provides.',
+            '`astryx search <query>` finds everything, from every installed integration.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Import components at the subpath the integration documents. Run `astryx component <Name>` to see the exact import:',
+        },
+        {
+          type: 'code',
+          lang: 'jsx',
+          code: "import {AcmeCarousel} from '@acme/brand-integration/components/AcmeCarousel';",
+        },
+        {
+          type: 'prose',
+          text: 'For themes, see {@link generic:use-a-theme}. To build an integration of your own, see {@link namespace:authoring}.',
+        },
+      ],
+    },
+    {
+      title: 'Check for problems',
+      content: [
+        {
+          type: 'prose',
+          text: 'Run `astryx doctor` to see integration issues: missing roots, invalid contributions, or a CLI version mismatch. The doctor check is the one place every issue for every package is listed.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx doctor',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/working-with-ai.doc.mjs

@@ -44,7 +44,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "By default this creates `AGENTS.md` (the tool-agnostic standard most agents read). To target a specific tool's file instead:",
+          text: "By default this writes the instructions to `AGENTS.md` (the tool-agnostic standard most agents read), in the project root: the nearest folder whose `package.json` declares an Astryx package, else the nearest with any `package.json`. The search stops at the repository root. In the home folder, or in a settings folder in it outside a project, init writes no agent docs: every folder of the home folder whose name starts with a dot (`~/.claude`, `~/.gemini`, `~/.codex`) is a settings folder, and such a folder itself never counts as a project, even with a `package.json`; a project below it with its own `package.json`, such as an agent worktree, is set up normally. Claude Code skips `AGENTS.md` when the project has a `CLAUDE.md` or `.claude/CLAUDE.md`, so init also writes them to that file, even when it imports `AGENTS.md`: Claude Code does not follow that import in a session started in a subfolder. When both files exist, root `CLAUDE.md` gets the copy and a copy in `.claude/CLAUDE.md` is removed, unless the project ignores `CLAUDE.md`, in which case a `.claude/CLAUDE.md` the project commits keeps a copy. Gemini CLI reads only `GEMINI.md`, so init adds a one-line import of `AGENTS.md` there, unless `GEMINI.md` already imports it. `upgrade` keeps the copies in sync. The block between the Astryx markers belongs to Astryx: init and `upgrade` write, refresh, and remove it whatever the project's ignore rules or generated markers say, and never change the text around it. To target a specific tool's file instead:",
         },
         {
           type: 'code',
@@ -55,7 +55,11 @@ astryx init --features agents --agent cursor    # .cursorrules if present, else
 astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
 astryx init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
 astryx init --features agents --agent muse      # AGENTS.md (Muse)
-astryx init --features agents --agent all       # every agent file present, else AGENTS.md and .claude/CLAUDE.md`,
+astryx init --features agents --agent all       # every agent file present except GEMINI.md, else AGENTS.md and .claude/CLAUDE.md`,
+        },
+        {
+          type: 'prose',
+          text: 'With `--agent all`, `GEMINI.md` keeps its one-line import of `AGENTS.md`. With `--agent claude` or `--agent all`, as by default, when `CLAUDE.md` gets the instructions, `.claude/CLAUDE.md` gets none and a copy already there is removed, unless the project ignores `CLAUDE.md`: a fresh clone does not have it, so a `.claude/CLAUDE.md` the project commits gets a copy too, with `--agent claude` and `--agent all` alike. `init --remove-agents` removes them at the project root and in the folder it runs in.',
         },
         {
           type: 'prose',

package/assets/templates/themes/butter/butterTheme.ts

@@ -81,7 +81,8 @@ const SECONDARY_SELECTOR = {
 
 /**
  * The secondary Button treatment on ComplexSelector triggers (AST-079 FR2), with
- * the hover kept off a disabled trigger, whose inner button is disabled.
+ * the hover kept off a disabled trigger, whose inner button is disabled
+ * (natively or, keeping its tab stop, with `aria-disabled`).
  */
 const SECONDARY_COMPLEX_SELECTOR = {
   backgroundColor: SECONDARY_BUTTON.backgroundColor,
@@ -89,7 +90,8 @@ const SECONDARY_COMPLEX_SELECTOR = {
   borderStyle: SECONDARY_BUTTON.borderStyle,
   borderColor: SECONDARY_BUTTON.borderColor,
   color: SECONDARY_BUTTON.color,
-  ':hover:not(:has(> :disabled))': SECONDARY_BUTTON[':hover'],
+  ':hover:not(:has(> :is(:disabled, [aria-disabled="true"])))':
+    SECONDARY_BUTTON[':hover'],
 } as const;
 
 export const butterTheme = defineTheme({

package/assets/templates/themes/stone/stoneTheme.ts

@@ -100,14 +100,16 @@ const SECONDARY_SELECTOR = {
 
 /**
  * The secondary Button treatment on ComplexSelector triggers (AST-079 FR2), with
- * the hover kept off a disabled trigger, whose inner button is disabled.
+ * the hover kept off a disabled trigger, whose inner button is disabled
+ * (natively or, keeping its tab stop, with `aria-disabled`).
  */
 const SECONDARY_COMPLEX_SELECTOR = {
   backgroundColor: SECONDARY_BUTTON.backgroundColor,
   borderWidth: SECONDARY_BUTTON.borderWidth,
   borderStyle: SECONDARY_BUTTON.borderStyle,
   borderColor: SECONDARY_BUTTON.borderColor,
-  ':hover:not(:has(> :disabled))': SECONDARY_BUTTON[':hover'],
+  ':hover:not(:has(> :is(:disabled, [aria-disabled="true"])))':
+    SECONDARY_BUTTON[':hover'],
 } as const;
 
 export const stoneTheme = defineTheme({

package/assets/templates/themes/y2k/y2kTheme.ts

@@ -76,7 +76,8 @@ const SECONDARY_SELECTOR = {
 
 /**
  * The secondary Button treatment on ComplexSelector triggers (AST-079 FR2), with
- * the hover kept off a disabled trigger, whose inner button is disabled.
+ * the hover kept off a disabled trigger, whose inner button is disabled
+ * (natively or, keeping its tab stop, with `aria-disabled`).
  */
 const SECONDARY_COMPLEX_SELECTOR = {
   backgroundColor: SECONDARY_BUTTON.backgroundColor,
@@ -84,7 +85,8 @@ const SECONDARY_COMPLEX_SELECTOR = {
   borderStyle: SECONDARY_BUTTON.borderStyle,
   borderColor: SECONDARY_BUTTON.borderColor,
   color: SECONDARY_BUTTON.color,
-  ':hover:not(:has(> :disabled))': SECONDARY_BUTTON[':hover'],
+  ':hover:not(:has(> :is(:disabled, [aria-disabled="true"])))':
+    SECONDARY_BUTTON[':hover'],
 } as const;
 
 export const y2kTheme = defineTheme({

package/authoring/debug/parse.d.mts

@@ -79,9 +79,9 @@ declare const eventSchema: z.ZodObject<{
             none: "none";
             component: "component";
             hook: "hook";
+            theme: "theme";
             doc: "doc";
             template: "template";
-            theme: "theme";
             integration: "integration";
             migration: "migration";
             mixed: "mixed";

package/authoring/doctypes/schema/schema.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+        "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:field-reference}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',

package/authoring/integration/integration.doc.mjs

@@ -131,7 +131,7 @@ export const doc = {
     },
     {
       type: 'prose',
-      text: "Set `cliCommand` only when your users run the CLI with a command other than their package manager's, such as `acme astryx`. The CLI picks the command it prints in this order: the `cliCommand` of the loaded integrations when they name one command, then the command a host tool names, then the package manager's. Two different `cliCommand` values cancel out, and `astryx doctor` warns in its `cli-command` check. See `astryx docs cli/integrations/building-blocks/configuration/cli-command`.",
+      text: "Set `cliCommand` only when your users run the CLI with a command other than their package manager's, such as `acme astryx`. The CLI picks the command it prints in this order: the `cliCommand` of the loaded integrations when they name one command, then the command a host tool names, then the package manager's. Two different `cliCommand` values cancel out, and `astryx doctor` warns in its `cli-command` check. See `astryx docs authoring/building-blocks/configuration/cli-command`.",
     },
     {
       type: 'prose',

package/authoring/integration/type.ts

@@ -11,7 +11,7 @@
  * The manifest module may also carry `debug` and `gapReport` NAMED exports.
  * They are not fields here on purpose: a CLI released before a given manifest
  * field existed could reject it and lose every contribution, while an unknown
- * named export is simply not read. See `astryx docs cli/integrations`.
+ * named export is simply not read. See `astryx docs authoring`.
  */
 export interface AstryxIntegration {
   /** Stable logical provider ID. Omit to use package.json#name. Set this only

package/clients/cli/bin/astryx.mjs

@@ -53,84 +53,13 @@ if (!isNodeVersionSupported(process.versions.node)) {
   process.exit(1);
 }
 
-// Global mode: choose the release that answers this folder and, when it is
-// not this copy, hand the run to it before anything the project provides (its
-// astryx.config, integrations, or Core) is loaded. Returns only when this copy
-// answers. See foundation/release/handoff.mjs and spec AST-081 FR2 and FR9.
-const {startRun} = await importSrc('../../foundation/release/handoff.mjs');
-await startRun({
+// Global mode: the run chooses the release that answers this folder and, when
+// it is not this copy, hands the run to it before anything the project
+// provides (its astryx.config, integrations, or Core) is loaded; only then
+// does it load and dispatch the command. See clients/cli/run.mjs,
+// foundation/release/handoff.mjs, and spec AST-081 FR2 and FR9.
+const {runCli} = await importSrc('run.mjs');
+await runCli({
   cliRoot: join(binDir, '..', '..', '..'),
   argv: process.argv.slice(2),
 });
-
-// Imports that transitively load `styleText` must happen AFTER the gate above,
-// so they are dynamically imported here rather than at the top of the module.
-const {
-  program,
-  loadProjectDebugHandler,
-  loadProjectForHelp,
-  handleVersionJsonPreflight,
-} = await importSrc('index.mjs');
-const {isJsonMode, toErrorEnvelope} = await importSrc('../../foundation/response/json.mjs');
-const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
-const {setOutcome} = await importSrc('../../foundation/debug/index.mjs');
-
-/**
- * Top-level error boundary (contract guarantee #4): an uncaught throw must
- * never reach a --json consumer as a raw stack trace. If we're in JSON mode,
- * convert it to the contract's error envelope on stdout and exit 1; otherwise
- * preserve the normal human-facing behavior.
- *
- * We detect JSON mode two ways: the global flag (set once root options are
- * parsed) and a raw argv check, since a throw can occur during parsing/command
- * load — before the preAction hook engages the flag.
- */
-function inJsonMode() {
-  return isJsonMode() || process.argv.slice(2).includes('--json');
-}
-
-/** @param {unknown} err */
-function handleFatal(err) {
-  // CommanderError (parse errors, --help, unknown command) routes
-  // through the JSON shim so that a --json consumer always gets a
-  // valid envelope and the right exit code. handleCommanderError
-  // calls process.exit when it owns the error.
-  if (handleCommanderError(err)) return;
-
-  // Anything still here is an uncaught throw or an unhandled rejection —
-  // a bug rather than a user error, and the class of failure most worth
-  // having a record of.
-  setOutcome('fatal', {exitCode: 1, error: err});
-
-  if (inJsonMode()) {
-    // Only emit if a command didn't already produce an envelope.
-    if (!process.__xdsJsonHandled) {
-      process.__xdsJsonHandled = true;
-      console.log(JSON.stringify(toErrorEnvelope(err), null, 2));
-    }
-    process.exit(1);
-  }
-  // Human mode: preserve Commander/Node default-ish behavior.
-  console.error(err instanceof Error ? err.stack || err.message : String(err));
-  process.exit(1);
-}
-
-process.on('unhandledRejection', handleFatal);
-process.on('uncaughtException', handleFatal);
-
-// Pick up the project's `debug` function before parsing, so parse errors and
-// `--help` — which short-circuit before any hook runs — are reported too.
-await loadProjectDebugHandler();
-// Help prints its commands while Commander parses, so a help run reads the
-// project's declared `cliCommand` here.
-await loadProjectForHelp();
-
-// `--version --json` answers and exits without Commander, so it runs here —
-// after the handler exists, or the run would go unrecorded.
-handleVersionJsonPreflight();
-
-try {
-  await program.parseAsync(process.argv);
-} catch (err) {
-  handleFatal(err);
-}

package/clients/cli/command-result-coverage.test.mjs

@@ -44,12 +44,13 @@ const NO_ACTION_OF_THEIR_OWN = [];
 /**
  * Commands that record for themselves instead of returning a descriptor.
  *
- * They cannot come from a CommandDoc — `manifest` introspects the live program,
- * `postinstall` is a package-script hook — so they carry the mark by hand. The
- * mark is a hatch, and a hatch nobody watches is a hole: this list is the
- * watch. The root program is checked separately below.
+ * Empty: every command, `manifest` and the hidden `postinstall` hook included,
+ * registers through defineCommand. The mark is a hatch, and a hatch nobody
+ * watches is a hole: this list is the watch. The root program is checked
+ * separately below.
+ * @type {string[]}
  */
-const RECORD_FOR_THEMSELVES = ['manifest', 'postinstall'];
+const RECORD_FOR_THEMSELVES = [];
 
 /**
  * Every command in the program, depth first, with its fully qualified name.

package/clients/cli/commands/build-theme.color-scheme.test.mjs

@@ -73,7 +73,7 @@ describe('theme build color-scheme output', () => {
     const project = path.join(tmpDir, 'project');
     const themesDir = path.join(project, 'themes');
     // A raw light-dark() token value is what triggers the color-scheme
-    // injection in build-theme.mjs. `defineTheme.test.ts` already covers the
+    // injection in theme.mjs. `defineTheme.test.ts` already covers the
     // separate [light, dark] tuple -> light-dark() conversion; this fixture
     // writes the string directly so this test stays focused on the CLI's own
     // color-scheme decision, not on that conversion.

package/clients/cli/commands/{component/index.mjs → component.mjs}

@@ -6,30 +6,30 @@
  * Global options: --detail full|compact|brief, --lang en|zh|dense
  */
 
-import {findCoreDir} from '../../../../foundation/fs/paths.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {
   resolveImportPath,
-} from '../../../../foundation/discovery/component-discovery.mjs';
+} from '../../../foundation/discovery/component-discovery.mjs';
 import {
   formatFull,
   formatCompact,
   formatBrief,
   formatProps,
   formatBriefAll,
-} from '../../lib/component-format.mjs';
-import {resolveTheme} from '../../lib/resolve-theme.mjs';
-import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';
-import {jsonOut} from '../../../../foundation/response/json.mjs';
-import {emit, section, text, list, record, records, code} from '../../formatters/index.mjs';
-import {cliError} from '../../lib/cli-error.mjs';
-import {defineCommand} from '../../lib/define-command.mjs';
-import {resultSet} from '../../../../foundation/debug/index.mjs';
-import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {component as componentApi} from '../../../../api/component/component.mjs';
-import {Project} from '../../../../foundation/config/project.mjs';
-import {warnOnIntegrationIssues} from '../../../../foundation/integrations/integration-warnings.mjs';
-import {doc as componentCommand} from '../component.doc.mjs';
-import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
+} from '../lib/component-format.mjs';
+import {resolveTheme} from '../lib/resolve-theme.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, record, records, code} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {component as componentApi} from '../../../api/component/component.mjs';
+import {Project} from '../../../foundation/config/project.mjs';
+import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
+import {doc as componentCommand} from './component.doc.mjs';
+import {doc as componentFn} from '../../../api/component/component.doc.mjs';
 
 /**
  * The api layer's component() widens its return to `{type: string, data: unknown}`,
@@ -37,13 +37,13 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
  * src/types/component to get narrowing + typed data.
  *
  * @typedef {(
- *   | import('../../../../api/component/component.type.mjs').ComponentListResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentBatchResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailPropsResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailSourceResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailShowcaseResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailBlocksResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentListResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentBatchResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailPropsResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailSourceResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailShowcaseResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailBlocksResponse
  * )} ComponentResult
  */
 
@@ -57,7 +57,7 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
  * the thing that resolved (the component) is not the thing being counted.
  *
  * @param {ComponentResult} result
- * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}
+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
  */
 function summarize(result) {
   switch (result.type) {
@@ -90,11 +90,11 @@ function summarize(result) {
 
 /**
  * Project one single-component API result through the existing formatter kit.
- * @param {import('../../../../api/component/component.type.mjs').ComponentSingleResponse} result
+ * @param {import('../../../api/component/component.type.mjs').ComponentSingleResponse} result
  * @param {string} requestedName
  * @param {'full'|'compact'|'brief'} detail
  * @param {Awaited<ReturnType<typeof resolveTheme>>} themeData
- * @returns {import('../../formatters/index.mjs').Block[]}
+ * @returns {import('../formatters/index.mjs').Block[]}
  */
 function componentDetailBlocks(result, requestedName, detail, themeData) {
   const requested = (requestedName.split('/').pop() ?? requestedName).replace(
@@ -111,7 +111,7 @@ function componentDetailBlocks(result, requestedName, detail, themeData) {
       : requested;
   switch (result.type) {
     case 'component.detail': {
-      /** @type {import('../../formatters/index.mjs').Block[]} */
+      /** @type {import('../formatters/index.mjs').Block[]} */
       const out = [record({package: result.package})];
       if (result.data.parentDoc) {
         out.push(record(result.data, {fields: ['parentDoc']}));
@@ -150,7 +150,7 @@ function componentDetailBlocks(result, requestedName, detail, themeData) {
       /** @param {{package: string}} block @param {string} label */
       const owned = (block, label) =>
         block.package === result.package ? label : `${label} (${block.package})`;
-      /** @type {import('../../formatters/index.mjs').Block[]} */
+      /** @type {import('../formatters/index.mjs').Block[]} */
       const out = [record({package: result.package})];
       if (showcase) {
         out.push(
@@ -243,7 +243,7 @@ export function registerComponent(program) {
           lang, zh, dense,
         }));
       } catch (e) {
-        const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
         return cliError(err.message, {suggestions: err.suggestions, code: err.code});
       }
 
@@ -326,7 +326,7 @@ export function registerComponent(program) {
             // description), grouped by category. Fields mirror the JSON keys.
             const groups = result.data.components;
             const entries = Object.entries(groups);
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [cat, items] of entries) {
               // Skip the synthetic group header when there's only one ungrouped category
@@ -362,7 +362,7 @@ export function registerComponent(program) {
               nameCounts.set(item.name, set);
             }
           }
-          /** @param {import('../../../../api/component/component.type.mjs').ComponentListEntry} item */
+          /** @param {import('../../../api/component/component.type.mjs').ComponentListEntry} item */
           const importCell = item => {
             // Use a precomputed import when the API supplies one (integration
             // components carry it); only fall back to the core resolver for
@@ -392,7 +392,7 @@ export function registerComponent(program) {
         }
 
         case 'component.batch': {
-          /** @type {import('../../formatters/index.mjs').Block[]} */
+          /** @type {import('../formatters/index.mjs').Block[]} */
           const out = [
             section('Component batch'),
             record({count: result.data.count}),
@@ -474,8 +474,8 @@ export function registerComponent(program) {
 
 // Re-export lib functions for backward compatibility
 // (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
-export {discoverComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../../foundation/discovery/component-discovery.mjs';
-export {discoverExternalPackages} from '../../../../foundation/fs/paths.mjs';
-export {loadDocs} from '../../../../foundation/discovery/component-loader.mjs';
-export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
-export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../../foundation/text/string-utils.mjs';
+export {discoverComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../foundation/discovery/component-discovery.mjs';
+export {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
+export {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../lib/component-format.mjs';
+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../foundation/text/string-utils.mjs';