@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/integration/integration-authoring.type.d.mts

@@ -10,6 +10,7 @@ export type IntegrationAddComponentOptions = IntegrationAddBaseOptions;
 export type IntegrationAddDocOptions = IntegrationAddBaseOptions & {
     replaces?: string;
     extends?: string;
+    parent?: string;
 };
 export type IntegrationAddTemplateOptions = IntegrationAddBaseOptions & {
     type?: "page" | "block";
@@ -26,9 +27,10 @@ export type IntegrationAddThemeOptions = IntegrationAddBaseOptions;
 export type IntegrationAddOptions = {
     cwd?: string | undefined;
     dryRun?: boolean | undefined;
-    templateType?: "block" | "page" | undefined;
+    templateType?: "page" | "block" | undefined;
     replaces?: string | undefined;
     extends?: string | undefined;
+    parent?: string | undefined;
     to?: string | undefined;
 };
 /**

package/api/integration/integration-authoring.type.mjs

@@ -20,6 +20,7 @@
  * @typedef {IntegrationAddBaseOptions & {
  *   replaces?: string,
  *   extends?: string,
+ *   parent?: string,
  * }} IntegrationAddDocOptions
  */
 
@@ -48,6 +49,7 @@
  * @property {'page'|'block'} [templateType]
  * @property {string} [replaces]
  * @property {string} [extends]
+ * @property {string} [parent]
  * @property {string} [to]
  */
 

package/api/integration/integration-block-exports.test.mjs

@@ -51,7 +51,7 @@ const ESBUILD_BIN = resolveBin('esbuild/bin/esbuild');
 let tmpDir;
 
 /**
- * Build an @acme/widgets fixture: a block template (`.template.ts` doc +
+ * Build an @acme/widgets fixture: a block template (released `.template.ts` compatibility descriptor +
  * same-stem `.tsx` source) under `templates/`, plus an astryx.integration
  * manifest, plus a caller-supplied `exports` map.
  * @param {Record<string, string> | undefined} exportsMap
@@ -71,7 +71,7 @@ function makeWidgets(exportsMap) {
     path.join(pkgDir, 'astryx.integration.mjs'),
     `export default { templates: './templates' };\n`,
   );
-  // The template-spec doc (canonical `.template.*` family).
+  // The released `.template.*` compatibility form remains resolvable.
   fs.writeFileSync(
     path.join(blockDir, 'GaugeShowcase.template.ts'),
     `export default { name: 'Gauge showcase', description: 'A gauge.' };\n`,
@@ -127,10 +127,14 @@ function writeTsconfig() {
 /** @returns {{ok: boolean, out: string}} */
 function runTsc() {
   try {
-    execFileSync(process.execPath, [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'], {
-      cwd: tmpDir,
-      stdio: 'pipe',
-    });
+    execFileSync(
+      process.execPath,
+      [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'],
+      {
+        cwd: tmpDir,
+        stdio: 'pipe',
+      },
+    );
     return {ok: true, out: ''};
   } catch (e) {
     return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};

package/api/integration/integrationAdd.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAdd',
+  namespace: 'cli/api',
   displayName: 'integrationAdd()',
   summary: 'Add one working contribution to an integration package.',
   description:
@@ -33,7 +34,8 @@ export const doc = {
     {
       name: 'name',
       type: 'string',
-      description: 'Contribution name, or the literal agent-doc line.',
+      description:
+        'Contribution name: PascalCase for component, lowercase kebab-case for template, codemod, and theme, letters, digits, _ and - for doc, or the literal agent-doc line.',
       required: true,
     },
     {
@@ -56,17 +58,25 @@ export const doc = {
     {
       name: 'options.replaces',
       type: 'string',
-      description: 'Existing topic to replace. Only valid for doc.',
+      description:
+        'Existing topic to replace. Only valid for doc, and not with options.extends.',
     },
     {
       name: 'options.extends',
       type: 'string',
-      description: 'Existing topic to extend. Only valid for doc.',
+      description:
+        'Existing topic to extend. Only valid for doc, and not with options.replaces.',
+    },
+    {
+      name: 'options.parent',
+      type: 'string',
+      description:
+        "Namespace of this package to place the doc in, as a guide in its `guides` slot; the namespace doc is written when missing. Only valid for doc, and not with options.replaces or options.extends.",
     },
     {
       name: 'options.to',
       type: 'string',
-      description: 'Exact target semver. Required for codemod.',
+      description: 'Exact target semver (e.g. 1.2.0). Required for codemod and only valid there.',
     },
   ],
   returns: [

package/api/integration/integrationAddAgentDoc.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddAgentDoc',
+  namespace: 'cli/api',
   displayName: 'integrationAddAgentDoc()',
   summary: 'Append one validated agent-guidance line.',
   description:

package/api/integration/integrationAddCodemod.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddCodemod',
+  namespace: 'cli/api',
   displayName: 'integrationAddCodemod()',
   summary: 'Add a safe identity codemod at an exact target version.',
   description:

package/api/integration/integrationAddComponent.doc.mjs

@@ -5,10 +5,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddComponent',
+  namespace: 'cli/api',
   displayName: 'integrationAddComponent()',
   summary: 'Add a complete component contribution.',
   description:
-    'Creates the same-stem component source and metadata pair, declares the components root on first use, preserves existing package allowlists, and publishes an exact source subpath when the package already has an exports map.',
+    'Creates the same-stem component source and metadata pair, declares the components root on first use, preserves existing package allowlists, and publishes an exact source subpath when the package already has an exports map. Refuses with ERR_FILE_EXISTS when a component doc anywhere under the components root already uses the name.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationAddComponent(name: string, options?: IntegrationAddComponentOptions): Promise<IntegrationAddResponse>',

package/api/integration/integrationAddDoc.doc.mjs

@@ -5,10 +5,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddDoc',
+  namespace: 'cli/api',
   displayName: 'integrationAddDoc()',
   summary: 'Add a complete reference-doc contribution.',
   description:
-    'Creates a valid generic topic, declares the docs root on first use, and supports an intentional replaces or extends relationship.',
+    'Creates a valid generic topic, declares the docs root on first use, and supports an intentional replaces or extends relationship, or places the doc as a guide in a namespace of the package.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationAddDoc(name: string, options?: IntegrationAddDocOptions): Promise<IntegrationAddResponse>',
@@ -41,6 +42,12 @@ export const doc = {
       type: 'string',
       description: 'Existing topic this topic extends.',
     },
+    {
+      name: 'options.parent',
+      type: 'string',
+      description:
+        "Namespace of this package to place the doc in, as a guide in its `guides` slot; the namespace doc is written when missing, and package.json declares the CLI that reads it as an optional `@astryxdesign/cli` peer. Only valid for doc, and not with options.replaces or options.extends.",
+    },
   ],
   returns: [
     {

package/api/integration/integrationAddTemplate.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddTemplate',
+  namespace: 'cli/api',
   displayName: 'integrationAddTemplate()',
   summary: 'Add a complete page or block template contribution.',
   description:

package/api/integration/integrationAddTheme.doc.mjs

@@ -5,10 +5,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddTheme',
+  namespace: 'cli/api',
   displayName: 'integrationAddTheme()',
   summary: 'Add a source theme to an integration package.',
   description:
-    'Creates an integration manifest when the package has none, writes a minimal named-export defineTheme source file, adds its entry to the root theme catalog, declares the optional themes root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. Every path is confined to the package and existing theme files are never overwritten.',
+    'Creates an integration manifest when the package has none, writes a minimal named-export defineTheme source file plus its strongly typed same-stem ThemeDoc, declares the optional themes root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. Every path is confined to the package and existing theme directories are never overwritten.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationAddTheme(name: string, options?: IntegrationAddThemeOptions): Promise<IntegrationAddResponse>',
@@ -17,7 +18,7 @@ export const doc = {
     {
       name: 'name',
       type: 'string',
-      description: 'Lowercase kebab-case theme name and catalog slug.',
+      description: 'Lowercase kebab-case theme name and directory slug.',
       required: true,
     },
     {
@@ -51,7 +52,7 @@ export const doc = {
     },
     {
       code: 'ERR_FILE_EXISTS',
-      when: 'the theme slug or source file already exists',
+      when: 'the theme slug directory already exists',
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
@@ -63,7 +64,7 @@ export const doc = {
     },
     {
       code: 'ERR_THEME_INVALID',
-      when: 'the package, integration manifest, or theme catalog is invalid',
+      when: 'the package, integration manifest, or theme descriptor is invalid',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -80,6 +81,6 @@ export const doc = {
       code: "await integrationAddTheme('ocean', {dryRun: true});",
     },
   ],
-  command: 'integration add',
+  command: 'integration add theme',
   related: ['themeList', 'themeAdd', 'validateIntegration'],
 };

package/api/integration/integrationComponentConflicts.doc.mjs

@@ -7,6 +7,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationComponentConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationComponentConflicts()',
   summary: 'Find integration component names that also exist in Core.',
   description:

package/api/integration/integrationDocConflicts.doc.mjs

@@ -7,8 +7,9 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationDocConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationDocConflicts()',
-  summary: 'Classify integration doc overlaps with Core topics.',
+  summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics.',
   description:
     'Loads one local or installed integration and classifies Core doc overlaps as ' +
     'intentional replacements, intentional extensions, or accidental same-name ' +

package/api/integration/integrationPackCheck.doc.mjs

@@ -5,10 +5,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationPackCheck',
+  namespace: 'cli/api',
   displayName: 'integrationPackCheck()',
   summary: 'Prove an integration package survives npm packing.',
   description:
-    "Validates the local integration, runs the package lifecycle, packs with npm, checks required files against npm's authoritative tarball list, extracts the real tarball into a scratch consumer, compares local and packed contribution inventories, and resolves every packed component through its documented public import to verify that module exports the component.",
+    "Validates the local integration, runs the package lifecycle, packs with npm, checks required files against npm's authoritative tarball list, extracts the real tarball into a scratch consumer, compares local and packed contribution inventories, and resolves every packed component through its documented public import to verify that module exports the component. A package that ships a namespace doc or a placed guide, or has a template that sets `replaces`, fails unless its `@astryxdesign/cli` peer range admits only CLIs that read them.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationPackCheck(options?: IntegrationPackCheckOptions): Promise<IntegrationPackCheckResponse>',

package/api/integration/integrationTemplateConflicts.doc.d.mts

@@ -3,6 +3,9 @@
 
 /**
  * @file FunctionDoc for integration template-conflict diagnostics.
+ * @input The stable 0.6.x `integrationTemplateConflicts` API contract.
+ * @output Generated CLI API reference metadata.
+ * @position Consumer-facing documentation for the public authoring API.
  */
 /** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
 export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/integration/integrationTemplateConflicts.doc.mjs

@@ -2,6 +2,9 @@
 
 /**
  * @file FunctionDoc for integration template-conflict diagnostics.
+ * @input The stable 0.6.x `integrationTemplateConflicts` API contract.
+ * @output Generated CLI API reference metadata.
+ * @position Consumer-facing documentation for the public authoring API.
  */
 
 /** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
@@ -9,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationTemplateConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationTemplateConflicts()',
   summary: 'Find integration template ids that also exist in Core.',
   description:

package/api/integration/pack-check.lifecycle-output.test.mjs

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {integrationPackCheck} from './pack-check.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-pack-check-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {Record<string, string>} scripts */
+function writeThemePackage(scripts) {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    `${JSON.stringify(
+      {
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'themes'],
+        scripts,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+  const root = path.join(tmpDir, 'themes');
+  fs.mkdirSync(path.join(root, 'ocean'), {recursive: true});
+  fs.writeFileSync(
+    path.join(root, 'ocean', 'oceanTheme.ts'),
+    "import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const oceanTheme = defineTheme({name: 'ocean'});\n",
+  );
+  fs.writeFileSync(
+    path.join(root, 'ocean', 'oceanTheme.doc.mjs'),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: 'ocean', displayName: 'Ocean', description: 'Ocean theme.', maintained: true};
+`,
+  );
+}
+
+describe('integrationPackCheck with lifecycle script output', () => {
+  it('checks the tarball when lifecycle scripts print to stdout', async () => {
+    writeThemePackage({
+      prepack: 'node -e "console.log(\'building the package\')"',
+      prepare: 'node -e "console.log(\'preparing\')"',
+      postpack: 'node -e "console.log(\'packed\')"',
+    });
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.packable).toBe(true);
+    expect(result.data.tarball?.filename).toBe('acme-widgets-1.0.0.tgz');
+    expect(result.data.contributions.packed).toEqual(
+      result.data.contributions.local,
+    );
+  });
+
+  it('still runs a chatty lifecycle script and compares what it packed', async () => {
+    const renameTheme = [
+      "console.log('renaming ocean to storm')",
+      "const fs=require('fs')",
+      "fs.renameSync('themes/ocean','themes/storm')",
+      "const p='themes/storm/oceanTheme.doc.mjs'",
+      "let x=fs.readFileSync(p,'utf8')",
+      "x=x.replace(/name: 'ocean'/, 'name: '+String.fromCharCode(39)+'storm'+String.fromCharCode(39))",
+      'fs.writeFileSync(p,x)',
+    ].join(';');
+    writeThemePackage({prepack: `node -e "${renameTheme}"`});
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const codes = result.data.issues.map(issue => issue.code);
+
+    expect(codes).not.toContain('pack_failed');
+    expect(codes).toContain('identity_not_packed');
+    expect(codes).toContain('packed_identity_unexpected');
+    expect(result.data.packable).toBe(false);
+  });
+
+  it('keeps a failing lifecycle script output in the pack_failed issue', async () => {
+    writeThemePackage({
+      prepack:
+        'node -e "console.error(\'prepack exploded\'); process.exit(3)"',
+    });
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+    const failure = result.data.issues.find(
+      issue => issue.code === 'pack_failed',
+    );
+
+    expect(result.data.packable).toBe(false);
+    expect(failure?.message).toContain('npm pack failed (exit 3)');
+    expect(failure?.message).toContain('prepack exploded');
+  });
+});

package/api/integration/pack-check.mjs

@@ -27,6 +27,11 @@ import {spawnSync} from 'node:child_process';
 import jscodeshift from 'jscodeshift';
 import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';
+import {
+  docsTreeCliProblem,
+  replacesCliProblem,
+} from '../../foundation/integrations/cli-requirement.mjs';
+import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
 import {
   discoverIntegrationComponents,
   resolveIntegrationImportPath,
@@ -157,6 +162,22 @@ export function parseNpmPackOutput(output) {
   };
 }
 
+/**
+ * Summarize the JSON error npm prints on stdout when `--json` pack fails.
+ * @param {string} output
+ * @returns {string}
+ */
+function npmPackErrorDetail(output) {
+  try {
+    const error = JSON.parse(output)?.error;
+    return [error?.summary, error?.detail]
+      .filter(part => typeof part === 'string' && part.trim() !== '')
+      .join(': ');
+  } catch {
+    return (output || '').trim();
+  }
+}
+
 /**
  * Run `npm pack --json` with output directed to `destDir` so no preexisting
  * tgz is overwritten. This intentionally runs the package lifecycle, matching
@@ -170,16 +191,25 @@ export function parseNpmPackOutput(output) {
 function runNpmPack(packageDir, destDir) {
   const result = spawnSync(
     'npm',
-    ['pack', '--json', '--silent', `--pack-destination=${destDir}`],
+    [
+      'pack',
+      '--json',
+      '--silent',
+      // Lifecycle scripts still run; background mode keeps their output off
+      // the stdout that carries the JSON result.
+      '--foreground-scripts=false',
+      `--pack-destination=${destDir}`,
+    ],
     {cwd: packageDir, encoding: 'utf-8', timeout: 60_000},
   );
   if (result.error) {
     throw new Error(`Could not start npm pack: ${result.error.message}`);
   }
   if (result.status !== 0) {
-    const stderr = (result.stderr || '').trim();
+    const detail =
+      (result.stderr || '').trim() || npmPackErrorDetail(result.stdout);
     throw new Error(
-      `npm pack failed (exit ${result.status})${stderr ? `: ${stderr}` : ''}.`,
+      `npm pack failed (exit ${result.status})${detail ? `: ${detail}` : ''}.`,
     );
   }
   return parseNpmPackOutput(result.stdout);
@@ -388,6 +418,14 @@ async function validatePackedComponentExports(integration, scratchBase) {
     components.map(component => component.specifier),
     scratchBase,
   );
+  issues.push(
+    ...validateSpecifierExtensions(
+      components.map(({name, specifier}) => ({
+        label: `Component "${name}"`,
+        specifier,
+      })),
+    ),
+  );
   for (const {name, specifier} of components) {
     const result = resolved.get(specifier);
     if (!result?.url || result.error) {
@@ -427,19 +465,27 @@ async function validatePackedComponentExports(integration, scratchBase) {
  */
 async function validatePackedTemplateExports(integration, scratchBase) {
   const {templates} = await discoverIntegrationTemplatesForOne(integration);
-  const entries = templates.map(template => ({
-    id: template.dirName,
-    specifier: `${integration.name}/${path
+  const entries = templates.map(template => {
+    const relPath = path
       .relative(integration.__packageDir, template.filePath)
       .split(path.sep)
-      .join('/')}`,
-  }));
+      .join('/');
+    const extensionless = relPath.replace(/\.tsx?$/u, '');
+    return {
+      id: template.dirName,
+      specifier: `${integration.name}/${extensionless}`,
+    };
+  });
   const resolved = resolveConsumerSpecifiers(
     entries.map(entry => entry.specifier),
     scratchBase,
   );
-  /** @type {Issue[]} */
-  const issues = [];
+  const issues = validateSpecifierExtensions(
+    entries.map(({id, specifier}) => ({
+      label: `Template "${id}"`,
+      specifier,
+    })),
+  );
   for (const {id, specifier} of entries) {
     const result = resolved.get(specifier);
     if (!result?.url || result.error) {
@@ -469,6 +515,32 @@ async function validatePackedTemplateExports(integration, scratchBase) {
   return issues;
 }
 
+const TS_EXTENSION_RE = /\.tsx?$/u;
+
+/**
+ * Reject specifiers that end in a TypeScript extension — they fail under
+ * default `moduleResolution` with TS5097/TS2307 unless the consumer enables
+ * `allowImportingTsExtensions`.
+ *
+ * @param {Array<{label: string, specifier: string}>} entries
+ * @returns {Issue[]}
+ */
+function validateSpecifierExtensions(entries) {
+  /** @type {Issue[]} */
+  const issues = [];
+  for (const {label, specifier} of entries) {
+    if (TS_EXTENSION_RE.test(specifier)) {
+      issues.push(
+        error(
+          'typescript_extension_in_specifier',
+          `${label} advertises import "${specifier}", which ends in a TypeScript extension. A consumer with default moduleResolution will reject it (TS5097). Use an extensionless specifier mapped through the package exports.`,
+        ),
+      );
+    }
+  }
+  return issues;
+}
+
 /**
  * Verify an integration package is ready to publish.
  *
@@ -549,6 +621,35 @@ export async function integrationPackCheck(options = {}) {
       );
     }
   }
+  // A namespace doc or a placed guide needs a CLI that reads the docs tree
+  // (spec:AST-046 FR11): an older CLI can hide every doc topic the package
+  // ships, so the declared CLI range must admit only CLIs that read it.
+  if (loaded.docs) {
+    const {namespaces, guides} = await discoverIntegrationDocs(loaded).catch(
+      () => ({namespaces: [], guides: []}),
+    );
+    const problem =
+      namespaces.length > 0 || guides.length > 0
+        ? docsTreeCliProblem(pkg)
+        : null;
+    if (problem != null) {
+      issues.push(error('docs_tree_needs_cli', problem));
+    }
+  }
+  // A template that sets `replaces` needs a CLI that reads the field
+  // (spec:AST-035): an older CLI withholds the package's templates and docs.
+  if (loaded.templates) {
+    const found = await discoverIntegrationTemplatesForOne(loaded).catch(
+      () => ({templates: [], errors: []}),
+    );
+    const setsReplaces =
+      found.templates.some(template => template.replaces != null) ||
+      found.errors.some(
+        (/** @type {any} */ issue) => issue.replacementTarget != null,
+      );
+    const problem = setsReplaces ? replacesCliProblem(pkg) : null;
+    if (problem != null) issues.push(error('replaces_needs_cli', problem));
+  }
 
   // Temp resources — always cleaned up
   const tgzTmpDir = fs.mkdtempSync(