@astryxdesign/cli 0.3.0-canary.c857354 → 0.3.0-canary.ccb5ca9

package/README.md

@@ -72,7 +72,7 @@ Options:
 | `search`               | Search components, hooks, docs, and templates in one ranked list              |
 | `swizzle`              | Copy component source for customization                                       |
 | `template`             | Inject a page or block template                                               |
-| `theme`                | Theme tools — build, export, and manage themes                                |
+| `theme`                | Theme tools: build, export, and manage themes                                 |
 | `upgrade`              | Run codemods to migrate between versions                                      |
 | `validate-integration` | Validate an Astryx integration package (manifest + contributions)             |
 
@@ -385,7 +385,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 | Type                        | What `data` carries                                                                                                                                                                                                                  |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `component.list`            | The component catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                      |
+| `component.list`            | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                       |
 | `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                    |
 | `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                               |
 | `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                 |
@@ -393,12 +393,12 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                           |
 | `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                              |
 | `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                        |
-| `docs.detail.section`       | A single ReferenceSection of a topic — the first whose title contains the section query.                                                                                                                                             |
-| `blog.list`                 | The feed URL plus every post parsed from the RSS feed — each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                            |
+| `docs.detail.section`       | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                              |
+| `blog.list`                 | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                             |
 | `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                            |
 | `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                   |
 | `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                           |
-| `discover.detail.doc`       | The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                      |
+| `discover.detail.doc`       | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                       |
 | `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                     |
 | `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                    |
 | `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                         |
@@ -409,15 +409,15 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                  |
 | `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                         |
 | `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                |
-| `hook.list`                 | The hook catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                   |
+| `hook.list`                 | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                    |
 | `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                    |
 | `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                   |
 | `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                    |
 | `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                 |
-| `theme.list`                | Every bundled theme as a ThemeListEntry[] — each with slug, displayName, description, and a maintained flag.                                                                                                                         |
+| `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                          |
 | `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                           |
 | `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                           |
-| `upgrade.status`            | A short-circuit outcome with no codemods run — up_to_date, no_codemods, or config_fixable — each carrying the agent-docs summary.                                                                                                    |
+| `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                     |
 | `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                          |
 | `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.        |
 | `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                          |

package/api/blog/blog.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:
-    'Reads the design system blog the same way any feed reader does — over the ' +
+    'Reads the design system blog the same way any feed reader does, over the ' +
     "published RSS feed, never the blog's source files. With no slug it lists every " +
     "post parsed from the feed; with a slug it reads that post's full plaintext body " +
     'via the .txt alternate the feed advertises. Both envelopes carry feedUrl so a ' +
@@ -35,7 +35,7 @@ export const doc = {
     {
       type: 'blog.list',
       description:
-        'The feed URL plus every post parsed from the feed — each with slug, title, description, date, type, authors, link, and its plaintext URL.',
+        'The feed URL plus every post parsed from the feed, each with slug, title, description, date, type, authors, link, and its plaintext URL.',
     },
     {
       type: 'blog.detail',

package/api/build/build.doc.mjs

@@ -54,7 +54,7 @@ export const doc = {
     {
       type: 'build.help',
       description:
-        'Emitted when the query is omitted — a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
+        'Emitted when the query is omitted: a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
     },
     {
       type: 'build.kit',

package/api/component/_adapter.mjs

@@ -270,6 +270,9 @@ export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
   let resolvedName = dirName;
   // Track the resolving owner so the detail payload can carry ownership info.
   // Defaults to core; the legacy-external fallback below may reassign it.
+  // Annotated because CORE_PACKAGE's generated declaration carries the literal
+  // type, which (unlike a fresh literal) does not widen on assignment.
+  /** @type {string} */
   let resolvedOwnerPackage = CORE_PACKAGE;
   let resolvedSourcePath = readmePath ? findComponentSource(coreDir, dirName) : null;
 

package/api/component/component.doc.mjs

@@ -108,7 +108,7 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — names+package, brief entries, or full ComponentDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names+package, brief entries, or full ComponentDoc per entry.",
     },
     {
       type: 'component.detail',

package/api/discover/discover.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   summary: 'Browse and search components from configured external packages.',
   description:
     'Explores components contributed by configured external packages and integrations ' +
-    '— the ones that declare a components root. With no query it lists those packages; ' +
+    'the ones that declare a components root. With no query it lists those packages; ' +
     'an @scope/name query browses one package; @scope/name/Component (or a free-text ' +
     "term that resolves to a single component) returns that component's validated doc; " +
     'a free-text term with several matches returns the candidate list.',
@@ -68,7 +68,7 @@ export const doc = {
     {
       type: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
     },
     {
       type: 'discover.search',

package/api/docs/docs.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   name: 'docs',
   displayName: 'docs()',
   summary:
-    'Read the reference docs — list every topic, one topic, or a single section of a topic.',
+    'Read the reference docs: list every topic, one topic, or a single section of a topic.',
   description:
     'Routes on its arguments: no topic lists every reference-doc topic; a topic ' +
     'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
@@ -75,7 +75,7 @@ export const doc = {
     {
       type: 'docs.detail.section',
       description:
-        'A single ReferenceSection of the topic — the first whose title contains the section query.',
+        'A single ReferenceSection of the topic: the first whose title contains the section query.',
     },
   ],
   throws: [

package/api/doctor/doctor.doc.mjs

@@ -14,10 +14,10 @@ export const doc = {
   displayName: 'doctor()',
   summary: 'Read-only project + environment health check.',
   description:
-    'Runs a series of side-effect-free diagnostics — Node version, ' +
+    'Runs a series of side-effect-free diagnostics: Node version, ' +
     '@astryxdesign/core install and version alignment with the CLI, installed ' +
     'themes and wiring, astryx.config validity, agent docs, core peer ' +
-    'dependencies, and the detected package manager — and returns a structured ' +
+    'dependencies, and the detected package manager, and returns a structured ' +
     'report. It only reads (never installs, writes, or mutates), so it is safe ' +
     'as a CI gate and for agents to invoke.',
   importPath: '@astryxdesign/cli/api',
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'doctor',
       description:
-        'The diagnostic report: `data.checks` — each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass` — plus `data.summary` with counts per status.',
+        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass`; plus `data.summary` with counts per status.',
     },
   ],
   examples: [

package/api/hook/hook.doc.mjs

@@ -70,7 +70,7 @@ export const doc = {
     {
       type: 'hook.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — hook names, brief entries, or full HookDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: hook names, brief entries, or full HookDoc per entry.",
     },
     {
       type: 'hook.detail',

package/api/init/init.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
     {
       type: 'init.remove',
       description:
-        'Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when `removeAgents` is set.',
+        'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
     },
   ],
   throws: [

package/api/integration/summarizeIssues.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'Tally integration issues by severity into error and warning counts.',
   description:
     'A synchronous helper that reduces an AstryxIntegrationIssue[] (as returned ' +
-    'by validateIntegration) to counts of errors and warnings — the seam a ' +
+    'by validateIntegration) to counts of errors and warnings: the seam a ' +
     'caller uses to decide an exit code or print a summary line. Issues of any ' +
     'other severity are ignored.',
   importPath: '@astryxdesign/cli/api',

package/api/integration/validate-integration.d.mts

@@ -1,24 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * Validate an already-LOADED integration (as produced by
- * `loadIntegrations` in lib/integrations.mjs — absolute contribution roots
- * plus identity) and return its issues. This is the reuse seam for everyday
- * commands that have already loaded the configured integrations and want the
- * SAME validators that `validate-integration` runs, without re-resolving the
- * manifest from disk.
- *
- * The manifest schema is intentionally NOT re-validated here: `loadIntegrations`
- * already validated it (and throws otherwise), so by the time a command holds a
- * loaded integration the manifest is known-good. We re-run the on-disk
- * contribution checks (roots + codemods/templates/components) because those can
- * regress independently of the manifest (a deleted directory, a broken template).
- *
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} loaded loaded-integration-shaped object
- * @returns {Promise<Issue[]>}
- */
-export function validateLoadedIntegration(loaded: import("./validate-integration.type.mjs").LoadedIntegration): Promise<Issue[]>;
 /**
  * Validate the LOCAL integration package rooted at `cwd`: nearest package.json
  * + a single sibling astryx.integration.{ts,mjs,js}. A missing manifest yields
@@ -59,6 +41,7 @@ export function summarizeIssues(issues: Issue[]): {
     errors: number;
     warnings: number;
 };
+export { validateLoadedIntegration };
 export type Issue = import("../../foundation/integrations/issue").AstryxIntegrationIssue;
 export type ValidateResult = {
     /**
@@ -79,3 +62,4 @@ export type ValidateResult = {
     manifestFile?: string | undefined;
     issues: Issue[];
 };
+import { validateLoadedIntegration } from '../../foundation/integrations/validate-contributions.mjs';

package/api/integration/validate-integration.mjs

@@ -17,6 +17,14 @@
  * is false only for the no-manifest local case, which is guidance (not an
  * error) so `validate-integration` can stay exit-0 in a non-integration dir.
  *
+ * The on-disk contribution validators themselves (roots + codemods/templates/
+ * components, behind `validateLoadedIntegration`) live in
+ * `foundation/integrations/validate-contributions.mjs`, because foundation also
+ * runs them: `Project` collects integration issues and `integration-warnings`
+ * nudges about them on ordinary commands. This file re-exports
+ * `validateLoadedIntegration` so existing importers are unaffected, and keeps
+ * the command-level entry points that resolve a manifest from disk.
+ *
  * Validators are intentionally small and independent so more checks can be
  * appended without reshaping the result. Issue `code`s are stable public
  * strings.
@@ -30,9 +38,14 @@ import {
   loadManifestObject,
   resolvePackageDir,
 } from '../../foundation/integrations/integrations.mjs';
-import {discoverIntegrationCodemods} from '../../assets/codemods/integration-discovery.mjs';
-import {discoverIntegrationTemplatesForOne} from '../template/template.mjs';
-import * as componentDiscovery from '../../foundation/discovery/component-discovery.mjs';
+// The on-disk contribution validators live in foundation: Project and
+// integration-warnings need them too, and foundation must not depend on api.
+import {
+  validateLoadedIntegration,
+  issueError as error,
+} from '../../foundation/integrations/validate-contributions.mjs';
+
+export {validateLoadedIntegration};
 
 /**
  * @typedef {import('../../foundation/integrations/issue').AstryxIntegrationIssue} Issue
@@ -63,144 +76,6 @@ function findNearestPackageJson(cwd) {
   }
 }
 
-/** @param {string} code @param {string} message @returns {Issue} */
-function error(code, message) {
-  return {code, severity: 'error', message};
-}
-
-/**
- * Verify each declared contribution root exists on disk. A declared-but-missing
- * root is a `missing_root` error.
- * @param {{components?: string, templates?: string, codemods?: string}} resolved
- *   absolute resolved roots (undefined when not declared)
- * @param {Issue[]} issues
- */
-function checkRoots(resolved, issues) {
-  const kinds = /** @type {const} */ (['components', 'templates', 'codemods']);
-  for (const kind of kinds) {
-    const root = resolved[kind];
-    if (root == null) continue;
-    if (!fs.existsSync(root)) {
-      issues.push(
-        error(
-          'missing_root',
-          `Declared ${kind} root does not exist on disk: ${root}`,
-        ),
-      );
-    }
-  }
-}
-
-/**
- * Validate the integration's codemods via the landed discovery. Discovery is
- * strict (throws on bad export / duplicate id); we convert any throw into an
- * `invalid_codemod` error.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
- * @param {Issue[]} issues
- */
-async function checkCodemods(integration, issues) {
-  if (!integration.codemods || !fs.existsSync(integration.codemods)) return;
-  try {
-    await discoverIntegrationCodemods([integration]);
-  } catch (err) {
-    issues.push(error('invalid_codemod', /** @type {any} */ (err).message));
-  }
-}
-
-/**
- * Validate the integration's templates via the landed discovery. Per-template
- * problems are reported as `invalid_template` errors.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
- * @param {Issue[]} issues
- */
-async function checkTemplates(integration, issues) {
-  if (!integration.templates || !fs.existsSync(integration.templates)) return;
-  try {
-    const {errors} = await discoverIntegrationTemplatesForOne(integration);
-    for (const e of errors) {
-      issues.push(error('invalid_template', e.message));
-    }
-  } catch (err) {
-    issues.push(error('invalid_template', /** @type {any} */ (err).message));
-  }
-}
-
-/**
- * Validate the integration's components via the landed ownership discovery.
- * Feature-detected: if the component-ownership export isn't present in this
- * build (sibling PR not yet merged), component validation is skipped rather
- * than hard-failing.
- *
- * `discoverIntegrationComponents` returns ownership records and does not throw
- * on a missing same-stem source — it records `sourcePath: null`. We surface
- * each such record as an `invalid_component` error.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
- * @param {Issue[]} issues
- */
-async function checkComponents(integration, issues) {
-  if (!integration.components || !fs.existsSync(integration.components)) return;
-  const discover = componentDiscovery.discoverIntegrationComponents;
-  if (typeof discover !== 'function') return; // feature not present yet
-  try {
-    const records = (await discover(integration)) ?? [];
-    for (const record of records) {
-      if (record?.sourcePath == null) {
-        issues.push(
-          error(
-            'invalid_component',
-            `Component "${record?.name}" is missing its same-stem source file ${record?.name}.tsx.`,
-          ),
-        );
-      }
-    }
-  } catch (err) {
-    issues.push(error('invalid_component', /** @type {any} */ (err).message));
-  }
-}
-
-/**
- * Run every contribution validator against a loaded-integration-shaped object.
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration
- * @param {Issue[]} issues
- */
-async function runContributionChecks(integration, issues) {
-  await checkCodemods(integration, issues);
-  await checkTemplates(integration, issues);
-  await checkComponents(integration, issues);
-}
-
-/**
- * Validate an already-LOADED integration (as produced by
- * `loadIntegrations` in lib/integrations.mjs — absolute contribution roots
- * plus identity) and return its issues. This is the reuse seam for everyday
- * commands that have already loaded the configured integrations and want the
- * SAME validators that `validate-integration` runs, without re-resolving the
- * manifest from disk.
- *
- * The manifest schema is intentionally NOT re-validated here: `loadIntegrations`
- * already validated it (and throws otherwise), so by the time a command holds a
- * loaded integration the manifest is known-good. We re-run the on-disk
- * contribution checks (roots + codemods/templates/components) because those can
- * regress independently of the manifest (a deleted directory, a broken template).
- *
- * @param {import('./validate-integration.type.mjs').LoadedIntegration} loaded loaded-integration-shaped object
- * @returns {Promise<Issue[]>}
- */
-export async function validateLoadedIntegration(loaded) {
-  /** @type {Issue[]} */
-  const issues = [];
-  if (!loaded || typeof loaded !== 'object') return issues;
-  checkRoots(
-    {
-      components: loaded.components,
-      templates: loaded.templates,
-      codemods: loaded.codemods,
-    },
-    issues,
-  );
-  await runContributionChecks(loaded, issues);
-  return issues;
-}
 
 /**
  * Validate a single integration given its package directory and identity.

package/api/integration/validateIntegration.doc.mjs

@@ -45,7 +45,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues` — an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [

package/api/json/assertResponse.doc.mjs

@@ -27,7 +27,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
     {
@@ -42,7 +42,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped — cast to the matching *Response type for typed access.',
+        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped; cast to the matching *Response type for typed access.',
     },
   ],
   throws: [

package/api/json/isError.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:
-    'Tests a parsed response for an `error` key. Branch on this before touching `data` — ' +
+    'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
     'and prefer the stable `code` field over matching the human-readable message, which is ' +
     'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
     'it does not narrow on its own: cast to the matching *Response type to get typed access.',

package/api/json/parseResponse.doc.mjs

@@ -26,7 +26,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
   ],
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped — narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/layout/layoutCheck.doc.mjs

@@ -18,7 +18,7 @@ export const doc = {
     'The validator behind `astryx layout check`. Parses and validates a compressed XLE/XLO ' +
     'expression without generating any TSX, and echoes it back in both canonical surfaces ' +
     '(compact and outline). Validation failures are reported in the layout.check envelope ' +
-    '(valid: false) with line/col and suggestions — not thrown — so callers can lint an ' +
+    '(valid: false) with line/col and suggestions (not thrown) so callers can lint an ' +
     'expression and surface fixes.',
   importPath: '@astryxdesign/cli/api',
   signature:

package/api/layout/layoutExpand.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Expand a validated layout expression into XDS TSX.',
   description:
     'The generator behind `astryx layout expand`. Parses and validates a compressed XLE/XLO ' +
-    'expression, then expands it into ready-to-use XDS TSX — auto-routing structural children ' +
+    'expression, then expands it into ready-to-use XDS TSX, auto-routing structural children ' +
     'into the right slots, scaffolding typed useState for interactive controls, and splicing or ' +
     'importing any referenced template blocks. Returns the code (and metadata) in a layout.expand ' +
     'envelope, optionally writing it to a path within cwd.',

package/api/layout/layoutGrammar.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'layoutGrammar()',
   summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
   description:
-    'The reference behind `astryx layout grammar` — the agent cheatsheet for writing XLE/XLO ' +
+    'The reference behind `astryx layout grammar`: the agent cheatsheet for writing XLE/XLO ' +
     "layout expressions, with the alias table generated from this branch's registry rather than " +
     'hand-maintained, so short names always reflect the components actually installed.',
   importPath: '@astryxdesign/cli/api',

package/api/swizzle/swizzle.doc.mjs

@@ -88,7 +88,7 @@ export const doc = {
     },
     {
       code: 'ERR_AMBIGUOUS_COMPONENT',
-      when: 'more than one package provides the component — choose one with package',
+      when: 'more than one package provides the component; choose one with package',
     },
     {
       code: 'ERR_NO_SOURCE',

package/api/template/copy/copy.d.mts

@@ -4,11 +4,11 @@
 /**
  * Scaffold an already-resolved template to `targetPath` (relative to `cwd`) and
  * return the `template.copy` receipt.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @param {{targetPath: string, cwd: string, overwrite?: boolean}} ctx
  * @returns {import('../template.type.mjs').TemplateCopyResponse}
  */
-export function templateCopy(match: import("../_adapter.mjs").DiscoveredTemplate, { targetPath, cwd, overwrite }: {
+export function templateCopy(match: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate, { targetPath, cwd, overwrite }: {
     targetPath: string;
     cwd: string;
     overwrite?: boolean;

package/api/template/copy/copy.mjs

@@ -18,12 +18,12 @@ import {
 } from '../../../foundation/fs/path-safety.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {stripTemplateAssetRefs} from '../_adapter.mjs';
+import {stripTemplateAssetRefs} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Scaffold an already-resolved template to `targetPath` (relative to `cwd`) and
  * return the `template.copy` receipt.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @param {{targetPath: string, cwd: string, overwrite?: boolean}} ctx
  * @returns {import('../template.type.mjs').TemplateCopyResponse}
  */

package/api/template/list/list.d.mts

@@ -3,11 +3,11 @@
 
 /**
  * Project a discovered template set into the `template.list` envelope.
- * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate[]} templates
  * @param {{type?: 'page' | 'block', package?: string}} [options]
  * @returns {import('../template.type.mjs').TemplateListResponse}
  */
-export function templateList(templates: import("../_adapter.mjs").DiscoveredTemplate[], options?: {
+export function templateList(templates: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate[], options?: {
     type?: "page" | "block";
     package?: string;
 }): import("../template.type.mjs").TemplateListResponse;

package/api/template/list/list.mjs

@@ -9,11 +9,11 @@
  *   no-skeleton default) here.
  */
 
-import {pkgOf} from '../_adapter.mjs';
+import {pkgOf} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Project a discovered template set into the `template.list` envelope.
- * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate[]} templates
  * @param {{type?: 'page' | 'block', package?: string}} [options]
  * @returns {import('../template.type.mjs').TemplateListResponse}
  */

package/api/template/show/show.d.mts

@@ -3,7 +3,7 @@
 
 /**
  * Build the `template.show` envelope for an already-resolved template.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @returns {import('../template.type.mjs').TemplateShowResponse}
  */
-export function templateShow(match: import("../_adapter.mjs").DiscoveredTemplate): import("../template.type.mjs").TemplateShowResponse;
+export function templateShow(match: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate): import("../template.type.mjs").TemplateShowResponse;

package/api/template/show/show.mjs

@@ -11,11 +11,11 @@
 import * as fs from 'node:fs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
-import {extractComponents} from '../_adapter.mjs';
+import {extractComponents} from '../../../foundation/discovery/template-adapter.mjs';
 
 /**
  * Build the `template.show` envelope for an already-resolved template.
- * @param {import('../_adapter.mjs').DiscoveredTemplate} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate} match
  * @returns {import('../template.type.mjs').TemplateShowResponse}
  */
 export function templateShow(match) {

package/api/template/skeleton/skeleton.d.mts

@@ -5,8 +5,8 @@
  * Build the `template.skeleton` envelope for an already-resolved template.
  * `match` may be undefined when `--skeleton` is run without a name — the same
  * "specify a template name" error the dispatcher's resolution would surface.
- * @param {import('../_adapter.mjs').DiscoveredTemplate | undefined} match
- * @param {import('../_adapter.mjs').DiscoveredTemplate[]} templates
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate | undefined} match
+ * @param {import('../../../foundation/discovery/template-adapter.mjs').DiscoveredTemplate[]} templates
  * @returns {import('../template.type.mjs').TemplateSkeletonResponse}
  */
-export function templateSkeleton(match: import("../_adapter.mjs").DiscoveredTemplate | undefined, templates: import("../_adapter.mjs").DiscoveredTemplate[]): import("../template.type.mjs").TemplateSkeletonResponse;
+export function templateSkeleton(match: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate | undefined, templates: import("../../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate[]): import("../template.type.mjs").TemplateSkeletonResponse;