@astryxdesign/cli 0.7.2-canary.e26723d → 0.7.2-canary.e4bdd70

package/authoring/doctypes/reference/reference.doc.mjs

@@ -18,7 +18,8 @@ export const doc = {
     'accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: ' +
     'drop a `.doc.mjs` in the docs directory and it shows up in `astryx docs`. Content is ' +
     'built from ordered sections of mixed content blocks.',
-  appliesTo: 'assets/docs/<topic>.doc.mjs',
+  appliesTo:
+    "<topic>.doc.{ts,mjs,js} in the folder the integration manifest's `docs` names",
   fields: [
     {
       name: 'type',
@@ -69,7 +70,7 @@ export const doc = {
       name: 'extends',
       type: 'string',
       description:
-        "Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
+        "Name of an existing topic this doc merges onto, section by section. A section replaces the base section with the same `id`, or else the one with exactly its title when either of the two has no `id`. A key derived from a title counts only against an `id`: a section without an `id` also matches a base section whose `id` is the key its title derives, and a section with an `id` also matches a base section without one whose title derives that `id`. Two different `id`s never match, two sections without an `id` whose titles differ only in case or punctuation stay separate, and a section that matches none is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
       example: "'theme'",
     },
     {
@@ -83,7 +84,7 @@ export const doc = {
           name: 'sections[].id',
           type: 'string',
           description:
-            'Stable section anchor. New docs should set this instead of relying on a mutable title.',
+            'Stable section anchor. New docs should set this instead of relying on a mutable title. Published @astryxdesign/cli 0.6.3 and earlier reject the field and hide every doc topic the package ships, so `astryx integration verify` fails an integration that sets one until it declares an `@astryxdesign/cli` peer of `>=0.6.4`.',
         },
         {
           name: 'sections[].title',
@@ -109,7 +110,7 @@ export const doc = {
           name: 'sections[].previewType',
           type: 'ReferenceTokenPreviewType',
           description:
-            "Preview type for token tables in this section. When set, the docsite renders a visual preview column from the token's computed value. Omit for non-token sections.",
+            'Preview type for token tables in this section. The CLI rejects a value not in the list below and returns the value in `astryx docs --json`, but draws no preview from it. Omit for non-token sections.',
         },
       ],
     },
@@ -117,17 +118,17 @@ export const doc = {
       name: 'tokenCategory',
       type: 'string',
       description:
-        "Token category for foundational docs that map to a token section (e.g. 'color'). Lets the tokens overview link to this doc for detailed guidance.",
+        "Token category for foundational docs that map to a token section (e.g. 'color'). `astryx docs --json` returns it as authored; no tokens page links to the doc through it.",
     },
   ],
   examples: [
     {
       label: 'A reference doc with one section',
       code: `/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
+export default {
   type: 'generic',
-  name: 'spacing',
-  title: 'Spacing',
+  name: 'acme-spacing',
+  title: 'Acme Spacing',
   description: 'Spacing tokens for gap, margin, and padding.',
   category: 'foundations',
   tokenCategory: 'spacing',
@@ -194,7 +195,7 @@ type ReferenceDocBlock = {
 
 type GraphContentBlock =
   | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
-  | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
+  | { type: 'collection'; title?: string; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
   | ReferenceDocBlock;`,
     },
     {
@@ -203,7 +204,7 @@ type GraphContentBlock =
     },
     {
       type: 'prose',
-      text: "A section may set `previewType` to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
+      text: "A section may set `previewType`, a hint for previewing its token table, to one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'; the CLI rejects any other value.",
     },
   ],
 };

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

@@ -55,7 +55,7 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Alternate slugs that also resolve to this doc (back-compat).',
+        'Reserved: alternate slugs for this doc. Nothing reads it yet: `astryx docs` finds a schema doc by its `name` only.',
     },
     {
       name: 'appliesTo',
@@ -141,7 +141,7 @@ export const doc = {
       name: 'notes',
       type: 'ReferenceContentBlock[]',
       description:
-        'Freeform prose/notes rendered after the field table. Same block union as ReferenceDoc (prose, heading, code, table, list, token-ref).',
+        'Freeform prose/notes rendered after the field table and examples. The stable ReferenceContentBlock union (prose, heading, code, table, list, token-ref), without the reference block a ReferenceDoc section also takes; a token-ref note is accepted but not rendered.',
     },
   ],
   examples: [
@@ -152,17 +152,17 @@ export const doc = {
   type: 'schema',
   name: 'integration',
   displayName: 'Astryx Integration',
-  namespace: 'cli',
-  description: 'The astryx.integration.* manifest that registers the components a package provides.',
+  namespace: 'authoring',
+  description: 'The astryx.integration.* manifest that points the CLI at what a package contributes.',
   appliesTo: 'astryx.integration.{ts,mjs,js}',
   fields: [
-    {name: 'name', type: 'string', description: 'Package name.', required: true},
+    {name: 'docs', type: 'string', description: 'The folder that holds your doc topics, relative to package.json.'},
     {
-      name: 'components',
-      type: '{ dir: string }',
-      description: 'Where component sources live.',
+      name: 'agentDocs',
+      type: '{ append?: readonly string[] }',
+      description: 'Guidance your package adds to the agent instructions the CLI manages.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
+        {name: 'agentDocs.append', type: 'readonly string[]', description: 'Lines added at the end, at most eight.'},
       ],
     },
   ],

package/authoring/doctypes/template/integration-template.doc.mjs

@@ -43,7 +43,7 @@ export default {
   notes: [
     {
       type: 'prose',
-      text: "Every other field, and the page and block variants, are TemplateDoc's. Core's own templates use TemplateDoc, whose `category` is a TemplateCategory value.",
+      text: "Every other field, and the page and block variants, are TemplateDoc's. Core's own templates use TemplateDoc, whose `category` is a TemplateCategory value. `astryx doctor integration validate` checks an integration's template docs against IntegrationTemplateDoc.",
     },
   ],
 };

package/authoring/doctypes/template/template.doc.mjs

@@ -31,14 +31,14 @@ export const doc = {
       name: 'name',
       type: 'string',
       description:
-        'Stable identifier for block templates; change `displayName`, not `name`, to edit their visible label. For page templates it is a human-readable label, while the existing template-directory/CLI slug owns the default registry path.',
+        "Stable identifier for block templates; change `displayName`, not `name`, to edit their visible label in the gallery. For page templates it is a human-readable label, while the existing template-directory/CLI slug owns the default registry path. `astryx template --list` and `astryx search` print `name` as the label of both, and `astryx template <id>` finds a template by its id, never by `name`: an integration template's id is its path under the templates folder without the `.doc.*` suffix.",
       required: true,
     },
     {
       name: 'displayName',
       type: 'string',
       description:
-        "Human-readable label for the gallery/CLI. Spaces out block names that mirror a PascalCase component ('ChatMessageMetadata' → 'Chat Message Metadata').",
+        "Human-readable label for the gallery. The CLI prints `name` instead; `astryx template --list --json` also returns an integration template's `displayName`. Spaces out block names that mirror a PascalCase component ('ChatMessageMetadata' → 'Chat Message Metadata').",
       required: true,
     },
     {
@@ -162,7 +162,7 @@ export default {
   notes: [
     {
       type: 'prose',
-      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract.',
+      text: 'When it loads, a template may leave out `displayName` and `aspectRatio` and use its own `category`, as integration templates already published do; a block with no `aspectRatio` previews at 1. Write to the type anyway; it is the contract, and `astryx doctor integration validate` warns about an integration template that leaves out `displayName` or `aspectRatio`.',
     },
     {
       type: 'prose',

package/authoring/doctypes/theme/theme.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'ThemeDoc',
   namespace: 'authoring',
   description:
-    'The strongly typed descriptor for one integration or CLI-bundled source theme.',
+    "The strongly typed descriptor for one source theme: bundled with the CLI, shipped by an integration, or kept in the project's src/themes, where `theme eject` writes one.",
   appliesTo: '<theme-source-stem>.doc.mjs',
   fields: [
     {
@@ -65,7 +65,7 @@ export default {
   notes: [
     {
       type: 'prose',
-      text: 'ThemeDoc is static metadata. Default-export one object with literal string and boolean fields; discovery validates it without executing the descriptor or theme source.',
+      text: "ThemeDoc is static metadata. The descriptor holds one default-exported object of literal string and boolean fields, directly under a `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */` comment, and nothing else: without that comment, or with any other statement, it fails to load. Discovery validates it without executing the descriptor or theme source.",
     },
     {
       type: 'prose',

package/authoring/gap-report/gap-report.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'GapReportHandler',
   namespace: 'authoring',
   description:
-    'A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Every handler runs: the project handler first, then each integration handler in config order.',
+    "A handler for `astryx gap-report`: a plain object with an `audience` and a `handle` function. Set it as `gapReport` in astryx.config, or export it as `gapReport` from an integration manifest. Handlers add up rather than replace each other: the project handler first, then each loaded integration's in load order (the `integrations` list, then autolinked ones), whichever package the report is about.",
   appliesTo:
     '`gapReport` in astryx.config.*, or the `gapReport` named export of astryx.integration.*',
   fields: [
@@ -104,7 +104,7 @@ export const doc = {
                   name: 'report.target.version',
                   type: 'string',
                   description:
-                    'The installed version. Null when it is not known.',
+                    "The integration's version from its package.json. Null for Core, and when the package.json has none.",
                   required: true,
                 },
                 {

package/authoring/identity/identity.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'Provider and artifact identity',
   namespace: 'authoring',
   description:
-    'Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI\'s own docs. Artifact, instance, and compiler-input identities are defined for every provider-owned artifact; no command reads them.',
+    "Separates stable provider/artifact identity from package instances and runtime lifecycle state. Provider identity names integration manifests and settles provider conflicts. Docs-tree nodes are identified by doc identity; the tree covers the CLI's docs and each integration's. Artifact IDs for kinds outside the docs tree, provider instances, and compiler-input entries are defined for every provider-owned artifact; no command builds them.",
   appliesTo:
     'Integration manifests, provider conflicts, and docs-tree node ids.',
   fields: [
@@ -41,14 +41,14 @@ export const doc = {
       name: 'ProviderInstance',
       type: '{ id; providerId; packageName; packageVersion; sourceDigest }',
       description:
-        'One immutable package version and source/content digest. Installed, configured, loaded, selected, and healthy state is a separate runtime overlay.',
+        'One immutable package version and source/content digest. It carries no installed, configured, loaded, selected, or healthy state.',
       required: true,
     },
     {
       name: 'AuthoredDocEntry',
       type: '{ id; provider; kind; stableName; source; authored }',
       description:
-        'Normalized compiler input. Discovery supplies stableName independently from the authored display name, source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
+        'Normalized compiler input. `stableName`, the key in its doc ID, is given separately from the authored display name; source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
       required: true,
     },
   ],

package/authoring/integration/integration.doc.mjs

@@ -51,7 +51,7 @@ export const doc = {
       name: 'docs',
       type: 'string',
       description:
-        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
+        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} under it shows up in `astryx docs`: a flat topic next to the built-in topics, where it can set `replaces` or `extends` to take over a built-in topic or add to it, and a guide with `placement` at its own route in the docs tree, under a namespace doc of the same package.',
       example: "'./docs'",
     },
     {
@@ -71,7 +71,8 @@ export const doc = {
     {
       name: 'issuesUrl',
       type: 'string',
-      description: 'Where to file issues/feedback for this integration.',
+      description:
+        "Where people file issues for this package: an absolute URL, such as its GitHub issues page. A value that is not a URL fails the whole manifest; the scheme is not checked. Nothing warns when it is missing, but without it `astryx gap-report` about this package fails unless the project or a loaded integration has a gapReport handler, and `astryx swizzle` prints no feedback link for this package's components. When no handler is loaded, a github.com issues URL is filed with the GitHub CLI once the reporter passes `--confirm-public`; any other URL is returned for the reporter to open.",
       example: "'https://github.com/acme/widgets/issues'",
     },
     {
@@ -118,7 +119,7 @@ export const doc = {
     },
     {
       type: 'prose',
-      text: 'A themes root is forward-compatible but version-gated: a CLI released before this field ignores it with a warning and continues loading every contribution kind it understands. That older CLI cannot list or add the contributed themes.',
+      text: 'A themes root is version-gated: an older CLI lists and adds none of its themes. Depending on its age, that CLI ignores `themes` with an `unknown_manifest_key` warning and loads every other contribution kind, reports the root as invalid because it expects the earlier `manifest.json` theme catalog, or, if it is old enough to treat an unknown field as an error, rejects the whole manifest, so the package contributes nothing there.',
     },
     {
       type: 'prose',

package/clients/cli/commands/build-theme.path-safety.test.mjs

@@ -9,9 +9,12 @@
  *   - Multi-file write is atomic: if one file fails, none are left behind.
  *   - An `--out` escape, or an output directory that cannot be created, fails
  *     with a registered error code.
- *   - Every output stays inside the working directory: an absolute `--out`
- *     path or a theme file outside it fails before anything is written, while
- *     absolute paths inside it build, also through a symlinked spelling.
+ *   - Every output a build writes stays inside the working directory: an
+ *     absolute `--out` path or a theme file outside it fails before anything
+ *     is written, while absolute paths inside it build, also through a
+ *     symlinked spelling. `--check` writes nothing, so it compares those
+ *     outside outputs read-only, and a stale report for them ends with a
+ *     remedy that works: the directory to build and check from.
  *
  * Runs the CLI in-process (shared runCli harness) against a tiny synthetic theme file.
  */
@@ -25,6 +28,7 @@ import {runCli} from '../../../test-utils/run-cli.mjs';
 import {themeBuild} from '../../../api/theme/build/build.mjs';
 import {AstryxError} from '../../../api/error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 
 function writeTheme(dir, name) {
   fs.mkdirSync(dir, {recursive: true});
@@ -62,7 +66,9 @@ describe('theme build path safety', () => {
     );
 
     expect(result.code).not.toBe(0);
-    expect(result.stderr + result.stdout).toMatch(/path separator|invalid theme name/i);
+    expect(result.stderr + result.stdout).toMatch(
+      /path separator|invalid theme name/i,
+    );
 
     // The traversal target must not exist.
     expect(fs.existsSync(path.join(tmpDir, 'escaped.js'))).toBe(false);
@@ -95,7 +101,10 @@ describe('theme build path safety', () => {
 
     const themeFile = writeTheme(themesDir, '../leak');
 
-    await runCli(['theme', 'build', path.relative(project, themeFile)], project);
+    await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
 
     // Neither the CSS nor any sibling JS should have been written.
     const entries = fs.readdirSync(themesDir).sort();
@@ -117,41 +126,88 @@ describe('theme build output-path failures carry registered codes', () => {
     return {result, envelope: JSON.parse(result.stdout)};
   }
 
-  it('reports an --out path outside the project as ERR_PATH_TRAVERSAL', async () => {
+  it('reports a relative --out path outside the project as ERR_PATH_TRAVERSAL, with --check too', async () => {
     const project = path.join(tmpDir, 'project');
     const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
 
+    for (const extra of [[], ['--check']]) {
+      const {result, envelope} = await buildJson(
+        [
+          path.relative(project, themeFile),
+          '--out',
+          '../escaped.css',
+          ...extra,
+        ],
+        project,
+      );
+
+      expect(result.code).toBe(1);
+      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+      expect(registered.has(envelope.code)).toBe(true);
+    }
+    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+  });
+
+  it('reports an absolute --out path outside the project as ERR_PATH_TRAVERSAL', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(outside, {recursive: true});
+    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const out = path.join(outside, 'ocean.css');
+
     const {result, envelope} = await buildJson(
-      [path.relative(project, themeFile), '--out', '../escaped.css'],
+      [path.relative(project, themeFile), '--out', out],
       project,
     );
 
     expect(result.code).toBe(1);
     expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
-    expect(registered.has(envelope.code)).toBe(true);
-    expect(fs.existsSync(path.join(tmpDir, 'escaped.css'))).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
   });
 
-  it('reports an absolute --out path outside the project as ERR_PATH_TRAVERSAL, with --check too', async () => {
+  it('checks an absolute --out path outside the project read-only', async () => {
     const project = path.join(tmpDir, 'project');
     const outside = path.join(tmpDir, 'outside');
     fs.mkdirSync(outside, {recursive: true});
-    const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
+    const themeFile = path.relative(
+      project,
+      writeTheme(path.join(project, 'themes'), 'ocean'),
+    );
     const out = path.join(outside, 'ocean.css');
 
-    for (const extra of [[], ['--check']]) {
-      const {result, envelope} = await buildJson(
-        [path.relative(project, themeFile), '--out', out, ...extra],
-        project,
-      );
+    const missing = await buildJson(
+      [themeFile, '--out', out, '--check'],
+      project,
+    );
+    expect(missing.result.code).toBe(1);
+    expect(missing.envelope.type).toBe('theme.build.check');
+    expect(missing.envelope.data.upToDate).toBe(false);
+    expect(fs.readdirSync(outside)).toEqual([]);
 
-      expect(result.code).toBe(1);
-      expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+    // Outputs built inside the project compare equal once copied outside:
+    // only the volatile Command line, which --check ignores, names --out.
+    const dist = path.join(project, 'dist');
+    const built = await buildJson(
+      [themeFile, '--out', path.join(dist, 'ocean.css')],
+      project,
+    );
+    expect(built.result.code).toBe(0);
+    for (const file of fs.readdirSync(dist)) {
+      fs.copyFileSync(path.join(dist, file), path.join(outside, file));
     }
-    expect(fs.readdirSync(outside)).toEqual([]);
+    const copied = fs.readdirSync(outside).sort();
+
+    const current = await buildJson(
+      [themeFile, '--out', out, '--check'],
+      project,
+    );
+    expect(current.result.code).toBe(0);
+    expect(current.envelope.type).toBe('theme.build.check');
+    expect(current.envelope.data.upToDate).toBe(true);
+    expect(fs.readdirSync(outside).sort()).toEqual(copied);
   });
 
-  it('reports a theme file outside the project as ERR_PATH_TRAVERSAL, because its outputs go beside it', async () => {
+  it('reports a theme file outside the project as ERR_PATH_TRAVERSAL, because its outputs go beside it; --check only compares them', async () => {
     const project = path.join(tmpDir, 'project');
     fs.mkdirSync(project, {recursive: true});
     const shared = path.join(tmpDir, 'shared');
@@ -162,10 +218,82 @@ describe('theme build output-path failures carry registered codes', () => {
 
       expect(result.code).toBe(1);
       expect(envelope.code).toBe(ERROR_CODES.ERR_PATH_TRAVERSAL);
+
+      const checked = await buildJson([file, '--check'], project);
+      expect(checked.result.code).toBe(1);
+      expect(checked.envelope.type).toBe('theme.build.check');
+      expect(checked.envelope.data.upToDate).toBe(false);
     }
     expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);
   });
 
+  /**
+   * Read the remedy that ends a stale report for outputs outside cwd: the
+   * directory to run from, then the build and check arguments after `theme
+   * build`. Each command starts with the install-aware invocation for it.
+   * @param {string} stderr
+   */
+  function readRemedy(stderr) {
+    const lines = stderr.split('\n').map(line => line.trim());
+    const cd = lines.find(line => line.startsWith('cd '));
+    expect(cd).toBeDefined();
+    const dir = /** @type {string} */ (cd).slice('cd '.length);
+    const stem = `${getCliInvocation(dir)} theme build `;
+    const commands = lines.filter(line => line.startsWith(stem));
+    expect(commands).toHaveLength(2);
+    const [build, check] = commands.map(line =>
+      line.slice(stem.length).split(' '),
+    );
+    expect(check).toEqual([...build, '--check']);
+    return {dir, build, check};
+  }
+
+  it('ends a stale report for outputs outside cwd with a remedy that works, and keeps the report for outputs inside it', async () => {
+    const project = path.join(tmpDir, 'project');
+    const inside = path.relative(
+      project,
+      writeTheme(path.join(project, 'themes'), 'ocean'),
+    );
+    const shared = writeTheme(path.join(tmpDir, 'shared'), 'ocean');
+    const outside = path.join(tmpDir, 'outside');
+
+    for (const args of [
+      [path.relative(project, shared)],
+      [inside, '--out', path.join(outside, 'ocean.css')],
+    ]) {
+      const stale = await runCli(
+        ['theme', 'build', ...args, '--check'],
+        project,
+      );
+      expect(stale.code).toBe(1);
+      // The old remedy ran the build from cwd, which refuses these outputs.
+      expect(stale.stderr).not.toContain('Rebuild with:');
+      expect(stale.stderr).not.toContain(`theme build ${args.join(' ')}`);
+
+      // Following the remedy builds, and the check from there passes.
+      const remedy = readRemedy(stale.stderr);
+      const built = await runCli(
+        ['theme', 'build', ...remedy.build],
+        remedy.dir,
+      );
+      expect(built.code).toBe(0);
+      const checked = await runCli(
+        ['--json', 'theme', 'build', ...remedy.check],
+        remedy.dir,
+      );
+      expect(checked.code).toBe(0);
+      expect(JSON.parse(checked.stdout).data.upToDate).toBe(true);
+    }
+
+    // Outputs inside cwd keep the plain rebuild line.
+    const local = await runCli(['theme', 'build', inside, '--check'], project);
+    expect(local.code).toBe(1);
+    expect(local.stderr).toContain(
+      `Rebuild with: astryx theme build ${inside}`,
+    );
+    expect(local.stderr).not.toMatch(/^\s*cd /m);
+  });
+
   it('builds absolute paths inside the project, also when they reach it through a symlink', async () => {
     const project = path.join(tmpDir, 'project');
     const themeFile = writeTheme(path.join(project, 'themes'), 'ocean');
@@ -243,7 +371,7 @@ describe('theme build output-path failures carry registered codes', () => {
     });
   });
 
-  it('themeBuild() rejects an output outside cwd: an absolute out path, or the default beside a theme file outside cwd', async () => {
+  it('themeBuild() rejects an output outside cwd, an absolute out path or the default beside a theme file outside cwd, and checks it read-only', async () => {
     const project = path.join(tmpDir, 'project');
     const inside = writeTheme(path.join(project, 'themes'), 'ocean');
     const shared = path.join(tmpDir, 'shared');
@@ -257,6 +385,12 @@ describe('theme build output-path failures carry registered codes', () => {
       await expect(
         themeBuild(file, options, {cwd: project}),
       ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+      await expect(
+        themeBuild(file, {...options, check: true}, {cwd: project}),
+      ).resolves.toMatchObject({
+        type: 'theme.build.check',
+        data: {upToDate: false},
+      });
     }
     expect(fs.existsSync(outDir)).toBe(false);
     expect(fs.readdirSync(shared)).toEqual(['theme.mjs']);

package/clients/cli/commands/doctor-integration-components.doc.mjs

@@ -21,8 +21,10 @@ export const doc = {
     'with a warning for each such component, naming the range to declare. ' +
     "Then it compares each component doc's props with the component's TypeScript " +
     "props, using the project's own `typescript`, and warns about a documented prop " +
-    'the code lacks, a prop the package declares that the doc omits, and a wrong ' +
-    '`required`. Without TypeScript it prints one ' +
+    'the code lacks, a prop the package declares that the doc omits, a wrong ' +
+    '`required`, and a type that does not match where both sides read exactly ' +
+    '(it lists every other documented type as not compared, with the reason). ' +
+    'Without TypeScript it prints one ' +
     'line saying the comparison was skipped.',
   fn: 'integrationComponentConflicts',
   args: [
@@ -35,7 +37,10 @@ export const doc = {
     },
   ],
   examples: [
-    {label: 'Check the local integration', cli: 'astryx doctor integration components'},
+    {
+      label: 'Check the local integration',
+      cli: 'astryx doctor integration components',
+    },
     {
       label: 'Check an installed integration',
       cli: 'astryx doctor integration components @acme/widgets --json',

package/clients/cli/commands/doctor-integration-validate.doc.mjs

@@ -14,7 +14,13 @@ export const doc = {
   description:
     'Validates one integration at a time: the local package rooted at cwd, or an ' +
     'installed package resolved by name. It schema-checks the manifest, verifies ' +
-    'every declared contribution root, and reports every finding. Safe as a CI gate.',
+    'every declared contribution root, and reports every finding. Safe as a CI gate. ' +
+    'It then checks every doc the package ships under its roots against the ' +
+    "published authoring type for its kind, with the project's own `typescript`, and " +
+    'warns about each field that does not match, naming the field and a fix. A doc ' +
+    'it cannot fully check is listed with the reason, and test fixtures under ' +
+    '`__tests__` in the components or docs root are counted, not checked. Without ' +
+    'TypeScript it prints one line saying the docs were not type-checked.',
   fn: 'validateIntegration',
   args: [
     {
@@ -36,7 +42,10 @@ export const doc = {
     },
   ],
   exitCodes: [
-    {code: 0, when: 'no error-severity issues (warnings are allowed)'},
+    {
+      code: 0,
+      when: 'no error-severity issues (warnings, including doc type findings, are allowed)',
+    },
     {code: 1, when: 'one or more error-severity issues'},
   ],
   related: ['doctor integration templates', 'template'],