@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

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

@@ -7,8 +7,8 @@ export const doc = {
   type: 'command',
   name: 'doctor integration docs',
   displayName: 'astryx doctor integration docs',
-  namespace: 'cli',
-  summary: 'Classify integration doc overlaps with Core topics',
+  namespace: 'cli/commands',
+  summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
   description:
     'Reports intentional Core topic replacements and extensions as information. ' +
     'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
@@ -32,7 +32,7 @@ export const doc = {
   ],
   exitCodes: [
     {code: 0, when: 'all Core overlaps are explicitly declared or no overlap exists'},
-    {code: 1, when: 'an overlap is accidental or the integration docs are invalid'},
+    {code: 1, when: 'an overlap is accidental, a doc is invalid, a namespace or placement fails, or a reference block cannot include what it names. A link that names no doc is a warning, and does not change the exit code'},
   ],
   related: ['doctor integration validate', 'docs'],
 };

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

@@ -9,13 +9,14 @@ export const doc = {
   type: 'command',
   name: 'doctor integration templates',
   displayName: 'astryx doctor integration templates',
-  namespace: 'cli',
-  summary: 'Warn when integration template ids conflict with Core',
+  namespace: 'cli/commands',
+  summary: 'Validate integration template replacements and Core id overlaps',
   description:
-    'Compares one local or installed integration with the built-in Core page and ' +
-    'block template ids. A conflict is allowed and exits successfully, but the ' +
-    'report recommends renaming and gives the exact --package command required ' +
-    'to select the integration template when the overlap is intentional.',
+    'Validates one local or installed integration against the built-in Core page ' +
+    'and block template ids. Intentional replacements are informational and name ' +
+    'the command for selecting the Core original. Missing targets, ambiguous ' +
+    'replacements, and invalid declarations are errors; undeclared same-id overlaps ' +
+    'remain warnings that require package selection.',
   fn: 'integrationTemplateConflicts',
   args: [
     {
@@ -37,8 +38,14 @@ export const doc = {
     },
   ],
   exitCodes: [
-    {code: 0, when: 'the check completed; template conflicts are warnings'},
-    {code: 1, when: 'the integration or one of its templates is invalid'},
+    {
+      code: 0,
+      when: 'replacement declarations are valid; undeclared id conflicts are warnings',
+    },
+    {
+      code: 1,
+      when: 'the integration, a template, or a replacement declaration is invalid',
+    },
   ],
   related: ['doctor integration validate', 'template'],
 };

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

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration validate',
   displayName: 'astryx doctor integration validate',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Validate an integration manifest and its contributions',
   description:
     'Validates one integration at a time: the local package rooted at cwd, or an ' +

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

@@ -9,7 +9,7 @@ export const doc = {
   type: 'command',
   name: 'doctor integration',
   displayName: 'astryx doctor integration',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Check an integration package while authoring it',
   description:
     'The integration-authoring diagnostics group. Validate a manifest and all ' +

package/clients/cli/commands/doctor-integration.test.mjs

@@ -2,9 +2,16 @@
 
 /**
  * @file Command-level coverage for `astryx doctor integration` authoring checks.
+ * @input Integration fixtures and the post-0.7 conflict projection.
+ * @output Assertions for human and typed command responses.
+ * @position CLI adapter coverage; 0.6.x API shape is verified separately.
  */
 
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+vi.mock('../../../foundation/discovery/template-conflict-release.mjs', () => ({
+  expandedTemplateConflictSchemaActive: () => true,
+}));
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {Command} from 'commander';
@@ -31,6 +38,8 @@ function writeIntegration({
   id,
   name = 'Integration template',
   missingRoot = false,
+  replacements,
+  type = 'page',
 }) {
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
@@ -44,8 +53,8 @@ function writeIntegration({
   const stem = path.join(tmpDir, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
-    `export default {type: 'page', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
+    `${stem}.doc.mjs`,
+    `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'${replacements?.[id] == null ? '' : `, replaces: ${JSON.stringify(replacements[id])}`}};\n`,
   );
   fs.writeFileSync(
     `${stem}.tsx`,
@@ -124,7 +133,12 @@ describe('doctor integration — command', () => {
       return true;
     });
 
-    await createProgram().parseAsync(['node', 'astryx', 'doctor', 'integration']);
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+    ]);
 
     const output = writes.join('');
     expect(output).toContain('validate [package]');
@@ -136,7 +150,9 @@ describe('doctor integration — command', () => {
 
   it('explains the optional package argument in every leaf help', () => {
     const program = createProgram();
-    const doctor = program.commands.find(command => command.name() === 'doctor');
+    const doctor = program.commands.find(
+      command => command.name() === 'doctor',
+    );
     const integration = doctor?.commands.find(
       command => command.name() === 'integration',
     );
@@ -152,7 +168,10 @@ describe('doctor integration — command', () => {
   });
 
   it('templates explains how to check an installed package when no local manifest exists', async () => {
-    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'plain'}));
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
     process.chdir(tmpDir);
 
     await createProgram().parseAsync([
@@ -239,6 +258,71 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('templates reports an intentional replacement and the Core-original command', async () => {
+    const core = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      type: core.type,
+      replacements: {'acme-app-shell': core.dirName},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual([]);
+    expect(parsed.data.conflicts).toEqual([
+      expect.objectContaining({
+        id: 'acme-app-shell',
+        relationship: 'replaces',
+        replaces: core.dirName,
+        severity: 'info',
+      }),
+    ]);
+    expect(parsed.data.conflicts[0].command).toContain(
+      `--package @astryxdesign/core`,
+    );
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('templates exits 1 for a missing replacement target', async () => {
+    writeIntegration({
+      id: 'acme-app-shell',
+      replacements: {'acme-app-shell': 'missing-core-shell'},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          severity: 'error',
+        }),
+      ]),
+    );
+    expect(process.exitCode).toBe(1);
+  });
+
   it('templates exits 1 when structural errors prevent a trustworthy check', async () => {
     writeIntegration({missingRoot: true});
     process.chdir(tmpDir);
@@ -278,9 +362,7 @@ describe('doctor integration — command', () => {
     const output = logCalls.join('\n');
     expect(output).toContain('[warn]');
     expect(output).toContain(core.name);
-    expect(output).toContain(
-      `component ${core.name} --package @acme/widgets`,
-    );
+    expect(output).toContain(`component ${core.name} --package @acme/widgets`);
     expect(process.exitCode).toBeUndefined();
   });
 

package/clients/cli/commands/doctor.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'doctor',
   displayName: 'astryx doctor',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Diagnose Astryx projects and integration packages',
   description:
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +

package/clients/cli/commands/doctor.mjs

@@ -3,7 +3,12 @@
 /**
  * @file `astryx doctor` project health and integration-authoring diagnostics.
  * Human output uses plain stable tokens; every leaf also has a typed JSON
- * response. Exit 1 means a check found an error, while warnings remain exit 0.
+ * response. Template-conflict fields follow the package release boundary.
+ * Exit 1 means a check found an error, while warnings remain exit 0.
+ *
+ * @input Typed Doctor and integration-authoring API responses.
+ * @output Human-readable records or pass-through typed JSON.
+ * @position CLI presentation adapter for project and integration health.
  */
 
 import {runChecks} from '../../../api/doctor/doctor.mjs';
@@ -125,25 +130,41 @@ function printTemplateConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
-  if (data.conflicts.length === 0) {
+  if (data.conflicts.length === 0 && data.issues.length === 0) {
     output.push(text('[ok] No template ids conflict with Core.'));
-  } else {
+  } else if (data.conflicts.length > 0) {
+    const expanded = data.conflicts.some(
+      conflict => 'relationship' in conflict,
+    );
     output.push(
       records(data.conflicts, {
-        fields: [
-          'severity',
-          'id',
-          'integrationPackage',
-          'integrationType',
-          'integrationName',
-          'message',
-          'command',
-        ],
+        fields: expanded
+          ? [
+              'severity',
+              'relationship',
+              'id',
+              'replaces',
+              'integrationPackage',
+              'integrationType',
+              'integrationName',
+              'message',
+              'command',
+            ]
+          : [
+              'severity',
+              'id',
+              'integrationPackage',
+              'integrationType',
+              'integrationName',
+              'message',
+              'command',
+            ],
         format: {severity: statusToken},
       }),
       text(
-        `${data.conflicts.length} Core template conflict(s). ` +
-          'Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.',
+        expanded
+          ? `${data.conflicts.length} Core template relationship(s).`
+          : `${data.conflicts.length} Core template conflict(s). Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.`,
       ),
     );
   }
@@ -165,7 +186,13 @@ function printComponentConflicts(data) {
   } else {
     output.push(
       records(data.conflicts, {
-        fields: ['severity', 'name', 'integrationPackage', 'message', 'command'],
+        fields: [
+          'severity',
+          'name',
+          'integrationPackage',
+          'message',
+          'command',
+        ],
         format: {severity: statusToken},
       }),
       text(
@@ -187,6 +214,15 @@ function printDocConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
+  if (
+    !data.issues.some(
+      issue => issue.severity === 'error' || issue.code === 'invalid_doc_graph',
+    )
+  ) {
+    output.push(
+      text('[ok] The docs tree and every link in these docs check out.'),
+    );
+  }
   if (data.findings.length === 0) {
     output.push(text('[ok] No doc topics overlap with Core.'));
   } else {
@@ -272,7 +308,8 @@ async function runAuthoringCheck(program, pkg, kind) {
   const structuralErrors = summarizeIssues(result.data.issues).errors;
   const docErrors =
     result.type === 'integration.doc-conflicts'
-      ? result.data.findings.filter(finding => finding.severity === 'error').length
+      ? result.data.findings.filter(finding => finding.severity === 'error')
+          .length
       : 0;
   if (structuralErrors > 0 || docErrors > 0) process.exitCode = 1;
   return NO_RESULT_SET;

package/clients/cli/commands/gap-report.doc.mjs

@@ -10,7 +10,7 @@ export const doc = {
   type: 'command',
   name: 'gap-report',
   displayName: 'astryx gap-report',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Route a design-system gap to its owning package',
   description:
     'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',

package/clients/cli/commands/hook.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'hook',
   displayName: 'astryx hook',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List hooks or print hook docs',
   description:
     'Resolves a hook by name and prints its authored doc, or lists the catalog grouped ' +

package/clients/cli/commands/init.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'init',
   displayName: 'astryx init',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +

package/clients/cli/commands/integration-add.controls.test.mjs

@@ -126,7 +126,7 @@ describe('integration add control definitions', () => {
     );
     expect(page.status).toBe(0);
     expect(
-      fs.readFileSync(path.join(tmpDir, 'templates', 'acme-page.template.mjs'), 'utf-8'),
+      fs.readFileSync(path.join(tmpDir, 'templates', 'acme-page.doc.mjs'), 'utf-8'),
     ).toContain("type: 'page'");
   });
 });

package/clients/cli/commands/integration-add.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration add',
   displayName: 'astryx integration add',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Add one working contribution to an integration package',
   description:
     'Writes the complete minimum shape the selected contribution needs, creates the integration manifest on first use, declares the root only after a valid contribution exists, and verifies the result through the same discovery contract the packed-package check uses.',
@@ -50,6 +50,12 @@ export const doc = {
       description:
         'Existing doc topic this one extends (letters, digits, _ and -); only valid for doc and not with --replaces',
     },
+    {
+      flag: '--parent <namespace>',
+      param: 'options.parent',
+      description:
+        "Namespace of this package to place the doc in, as a guide in its `guides` slot; writes the namespace doc when it is missing, and declares the CLI that reads it as an optional `@astryxdesign/cli` peer. Only valid for doc, and not with --replaces or --extends",
+    },
     {
       flag: '--to <version>',
       param: 'options.to',
@@ -79,6 +85,10 @@ export const doc = {
       label: 'Extend a doc topic',
       cli: 'astryx integration add doc acme-theming --extends theme',
     },
+    {
+      label: 'Add a guide to the package\'s own docs section',
+      cli: 'astryx integration add doc deploying --parent acme',
+    },
     {
       label: 'Add a codemod',
       cli: 'astryx integration add codemod rename-widget --to 1.2.0',

package/clients/cli/commands/integration-pack.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration pack',
   displayName: 'astryx integration pack',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Prove the packed integration is what consumers receive',
   description:
     'Runs the package lifecycle, packs with npm, checks every required contribution file against the real tarball, extracts it into a scratch consumer, and compares the local and packed contribution inventories through one shared contract.',

package/clients/cli/commands/integration-real-world.test.mjs

@@ -201,13 +201,6 @@ export const oceanTheme = defineTheme({
 });
 `,
     );
-    const catalogFile = path.join(providerDir, 'themes', 'manifest.json');
-    const catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
-    catalog.themes[0].files.push(
-      'tokens/ocean.palette.ts',
-      'tokens/ocean.palette.receipt.json',
-    );
-    writeJson(catalogFile, catalog);
 
     const providerPackage = JSON.parse(
       fs.readFileSync(path.join(providerDir, 'package.json'), 'utf-8'),
@@ -464,8 +457,9 @@ export const oceanTheme = defineTheme({
         outputDir: target,
         files: [
           'oceanTheme.ts',
-          'tokens/ocean.palette.ts',
+          'oceanTheme.doc.mjs',
           'tokens/ocean.palette.receipt.json',
+          'tokens/ocean.palette.ts',
         ],
       },
     });
@@ -612,7 +606,7 @@ export const oceanTheme = defineTheme({
     expect(corruptedInstall.status).not.toBe(0);
     expect(parseEnvelope(corruptedInstall.stdout)).toMatchObject({
       code: 'ERR_THEME_INVALID',
-      error: expect.stringContaining('ocean.palette.ts'),
+      error: expect.stringContaining('./tokens/ocean.palette'),
     });
   }, 120_000);
 });

package/clients/cli/commands/integration.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration',
   displayName: 'astryx integration',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
     'Add contributions that are valid on arrival, then prove the packed package exposes the same contributions a consumer will receive.',

package/clients/cli/commands/integration.mjs

@@ -58,6 +58,7 @@ export function registerIntegration(program) {
           templateType: options.type,
           replaces: options.replaces,
           extends: options.extends,
+          parent: options.parent,
           to: options.to,
         });
       } catch (error) {

package/clients/cli/commands/layout-check.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout check',
   displayName: 'astryx layout check',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Validate a layout expression and echo canonical compact/outline forms',
   description:

package/clients/cli/commands/layout-expand.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout expand',
   displayName: 'astryx layout expand',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +

package/clients/cli/commands/layout-grammar.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   type: 'command',
   name: 'layout grammar',
   displayName: 'astryx layout grammar',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary:
     'Print the XLE/XLO cheatsheet (alias table generated from this branch)',
   description:

package/clients/cli/commands/layout.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'layout',
   displayName: 'astryx layout',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
   description:
     'The layout command group. Running astryx layout with no subcommand prints the ' +

package/clients/cli/commands/manifest.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'manifest',
   displayName: 'astryx manifest',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
     'Emits the complete CLI surface: every command with its arguments, options, ' +

package/clients/cli/commands/search.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'search',
   displayName: 'astryx search',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
     'Terminal front-end to search(): prints one ranked, greppable list across ' +

package/clients/cli/commands/search.mjs

@@ -49,7 +49,7 @@ export function registerSearch(program) {
 
       try {
         const project = await Project.load(process.cwd());
-        await warnOnIntegrationIssues(project.loadedIntegrations, {json});
+        await warnOnIntegrationIssues(project, {json});
       } catch {
         // Never let the nudge break the command.
       }
@@ -115,7 +115,9 @@ export function registerSearch(program) {
       const fields = options.verbose
         ? [
             'name',
+            'section',
             'domain',
+            'package',
             'title',
             'displayName',
             'kind',
@@ -124,16 +126,20 @@ export function registerSearch(program) {
             'import',
             'description',
             'command',
+            'parent',
           ]
         : [
             'name',
+            'section',
             'domain',
+            'package',
             'title',
             'displayName',
             'kind',
             'import',
             'description',
             'command',
+            'parent',
           ];
 
       // The heading mirrors the JSON: `matchCount` is what matched, and the
@@ -145,7 +151,10 @@ export function registerSearch(program) {
             ? `Results for "${q}" (${results.length} of ${matchCount})`
             : `Results for "${q}" (${results.length})`,
         ),
-        records(results, {fields, format: {command: formatCliCommand}}),
+        records(results, {
+          fields,
+          format: {command: formatCliCommand, parent: formatCliCommand},
+        }),
       );
       return answered;
     },

package/clients/cli/commands/setup-nudge.test.mjs

@@ -89,6 +89,12 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
   });
 
+  it('is quiet in an integration package, which is not an app', async () => {
+    asProject();
+    write('astryx.integration.mjs', 'export default {};\n');
+    expect((await runCli(['docs', 'tokens'], tmp)).stderr).not.toMatch(NUDGE);
+  });
+
   it('does not nudge for the installer command itself', async () => {
     asProject();
     expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);

package/clients/cli/commands/swizzle.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'swizzle',
   displayName: 'astryx swizzle',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Copy component source for customization',
   description:
     "Ejects a component's source from the resolved @astryxdesign/core (or its owning " +