@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/integration/authoring-checks.mjs

@@ -92,6 +92,7 @@ function addErrors(issues, errors, code) {
 export async function integrationTemplateConflicts(pkg, options = {}) {
   const {cwd = process.cwd()} = options;
   const resolved = await resolveIntegration(pkg, cwd);
+  const validated = resolved.found;
   const name = resolved.found ? (resolved.name ?? null) : null;
   const version = resolved.found ? (resolved.version ?? null) : null;
   const issues = [...resolved.issues];
@@ -99,7 +100,7 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
   if (!resolved.integration || name == null) {
     return {
       type: 'integration.template-conflicts',
-      data: {name, version, conflicts: [], issues},
+      data: {validated, name, version, conflicts: [], issues},
     };
   }
 
@@ -215,7 +216,7 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
 
   return {
     type: 'integration.template-conflicts',
-    data: {name, version, conflicts, issues},
+    data: {validated, name, version, conflicts, issues},
   };
 }
 
@@ -228,6 +229,7 @@ export async function integrationTemplateConflicts(pkg, options = {}) {
 export async function integrationComponentConflicts(pkg, options = {}) {
   const {cwd = process.cwd()} = options;
   const resolved = await resolveIntegration(pkg, cwd);
+  const validated = resolved.found;
   const name = resolved.found ? (resolved.name ?? null) : null;
   const version = resolved.found ? (resolved.version ?? null) : null;
   const issues = [...resolved.issues];
@@ -235,7 +237,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
   if (!resolved.integration?.components || name == null) {
     return {
       type: 'integration.component-conflicts',
-      data: {name, version, conflicts: [], issues},
+      data: {validated, name, version, conflicts: [], issues},
     };
   }
 
@@ -249,7 +251,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
     });
     return {
       type: 'integration.component-conflicts',
-      data: {name, version, conflicts: [], issues},
+      data: {validated, name, version, conflicts: [], issues},
     };
   }
 
@@ -274,7 +276,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
 
   return {
     type: 'integration.component-conflicts',
-    data: {name, version, conflicts, issues},
+    data: {validated, name, version, conflicts, issues},
   };
 }
 
@@ -287,6 +289,7 @@ export async function integrationComponentConflicts(pkg, options = {}) {
 export async function integrationDocConflicts(pkg, options = {}) {
   const {cwd = process.cwd()} = options;
   const resolved = await resolveIntegration(pkg, cwd);
+  const validated = resolved.found;
   const name = resolved.found ? (resolved.name ?? null) : null;
   const version = resolved.found ? (resolved.version ?? null) : null;
   const issues = [...resolved.issues];
@@ -294,7 +297,7 @@ export async function integrationDocConflicts(pkg, options = {}) {
   if (!resolved.integration?.docs || name == null) {
     return {
       type: 'integration.doc-conflicts',
-      data: {name, version, findings: [], issues},
+      data: {validated, name, version, findings: [], issues},
     };
   }
 
@@ -368,11 +371,11 @@ export async function integrationDocConflicts(pkg, options = {}) {
   // and placed guides this package adds to the docs tree, and every link in
   // its docs (spec:AST-046, spec:AST-047).
   if (errors.length === 0) {
-    for (const message of await packageDocsProblems(
+    for (const {severity, message} of await packageDocsProblems(
       /** @type {{name: string}} */ (resolved.integration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_graph', severity: 'warning', message});
+      issues.push({code: 'invalid_doc_graph', severity, message});
     }
 
     // A reference block includes content rather than linking to it, so one
@@ -388,6 +391,6 @@ export async function integrationDocConflicts(pkg, options = {}) {
 
   return {
     type: 'integration.doc-conflicts',
-    data: {name, version, findings, issues},
+    data: {validated, name, version, findings, issues},
   };
 }

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

@@ -32,9 +32,15 @@ export type IntegrationDocFinding = {
     coreTopic: string;
     message: string;
 };
+/**
+ * Each of the three authoring checks reports `validated`: false means no
+ * integration manifest was found, so nothing was inspected and the empty
+ * conflicts/findings list carries no information about the package.
+ */
 export type IntegrationTemplateConflictResponse = {
     type: "integration.template-conflicts";
     data: {
+        validated: boolean;
         name: string | null;
         version: string | null;
         conflicts: IntegrationTemplateConflict[];
@@ -44,6 +50,7 @@ export type IntegrationTemplateConflictResponse = {
 export type IntegrationComponentConflictResponse = {
     type: "integration.component-conflicts";
     data: {
+        validated: boolean;
         name: string | null;
         version: string | null;
         conflicts: IntegrationComponentConflict[];
@@ -53,6 +60,7 @@ export type IntegrationComponentConflictResponse = {
 export type IntegrationDocConflictResponse = {
     type: "integration.doc-conflicts";
     data: {
+        validated: boolean;
         name: string | null;
         version: string | null;
         findings: IntegrationDocFinding[];

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

@@ -49,21 +49,25 @@
  */
 
 /**
+ * Each of the three authoring checks reports `validated`: false means no
+ * integration manifest was found, so nothing was inspected and the empty
+ * conflicts/findings list carries no information about the package.
+ *
  * @typedef {object} IntegrationTemplateConflictResponse
  * @property {'integration.template-conflicts'} type
- * @property {{name: string | null, version: string | null, conflicts: IntegrationTemplateConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationTemplateConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
  */
 
 /**
  * @typedef {object} IntegrationComponentConflictResponse
  * @property {'integration.component-conflicts'} type
- * @property {{name: string | null, version: string | null, conflicts: IntegrationComponentConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, conflicts: IntegrationComponentConflict[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
  */
 
 /**
  * @typedef {object} IntegrationDocConflictResponse
  * @property {'integration.doc-conflicts'} type
- * @property {{name: string | null, version: string | null, findings: IntegrationDocFinding[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ * @property {{validated: boolean, name: string | null, version: string | null, findings: IntegrationDocFinding[], issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
  */
 
 export {};

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

@@ -19,7 +19,9 @@ export type IntegrationAddCodemodOptions = IntegrationAddBaseOptions & {
     to: string;
 };
 export type IntegrationAddAgentDocOptions = IntegrationAddBaseOptions;
-export type IntegrationAddThemeOptions = IntegrationAddBaseOptions;
+export type IntegrationAddThemeOptions = IntegrationAddBaseOptions & {
+    from?: string;
+};
 /**
  * Options for the generic `integrationAdd` dispatcher. Prefer a per-kind API
  * when the contribution kind is known so the accepted options stay narrow.
@@ -54,4 +56,5 @@ export type IntegrationAddData = {
     files: string[];
     written: boolean;
     dryRun: boolean;
+    from?: string | undefined;
 };

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

@@ -37,7 +37,11 @@
  */
 
 /** @typedef {IntegrationAddBaseOptions} IntegrationAddAgentDocOptions */
-/** @typedef {IntegrationAddBaseOptions} IntegrationAddThemeOptions */
+/**
+ * @typedef {IntegrationAddBaseOptions & {
+ *   from?: string,
+ * }} IntegrationAddThemeOptions
+ */
 
 /**
  * Options for the generic `integrationAdd` dispatcher. Prefer a per-kind API
@@ -73,6 +77,7 @@
  * @property {string[]} files
  * @property {boolean} written
  * @property {boolean} dryRun
+ * @property {string} [from]
  */
 
 export {};

package/api/integration/integrationAdd.doc.mjs

@@ -78,6 +78,12 @@ export const doc = {
       type: 'string',
       description: 'Exact target semver (e.g. 1.2.0). Required for codemod and only valid there.',
     },
+    {
+      name: 'options.from',
+      type: 'string',
+      description:
+        'Slug of an existing theme to fork as the starting point. Only valid for theme.',
+    },
   ],
   returns: [
     {

package/api/integration/integrationAddTheme.doc.mjs

@@ -33,6 +33,12 @@ export const doc = {
         'Validate and return the same receipt without writing; data.written is false and data.dryRun is true.',
       default: 'false',
     },
+    {
+      name: 'options.from',
+      type: 'string',
+      description:
+        'Slug of an existing theme to fork as the starting point. The new theme copies the base and has no link back.',
+    },
   ],
   returns: [
     {
@@ -76,6 +82,10 @@ export const doc = {
       label: 'Add a theme',
       code: "await integrationAddTheme('ocean');",
     },
+    {
+      label: 'Fork an existing theme',
+      code: "await integrationAddTheme('ocean', {from: 'neutral'});",
+    },
     {
       label: 'Preview writes',
       code: "await integrationAddTheme('ocean', {dryRun: true});",

package/api/integration/integrationComponentConflicts.doc.mjs

@@ -26,7 +26,7 @@ export const doc = {
     {
       type: 'integration.component-conflicts',
       description:
-        'Integration identity, structural issues, and Core component-name conflicts with package-qualified commands.',
+        '`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural issues, and Core component-name conflicts with package-qualified commands.',
     },
   ],
   examples: [

package/api/integration/integrationDocConflicts.doc.mjs

@@ -26,7 +26,7 @@ export const doc = {
     {
       type: 'integration.doc-conflicts',
       description:
-        'Integration identity, structural issues, and classified Core doc relationships.',
+        '`validated` (false when no integration manifest was found, so nothing was inspected), integration identity, structural issues, and classified Core doc relationships.',
     },
   ],
   examples: [

package/api/integration/integrationPackCheck.doc.mjs

@@ -7,13 +7,13 @@ export const doc = {
   name: 'integrationPackCheck',
   namespace: 'cli/api',
   displayName: 'integrationPackCheck()',
-  summary: 'Prove an integration package survives npm packing.',
+  summary: 'Check an integration package the way npm will publish it.',
   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. 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>',
-  keywords: ['integration', 'pack', 'check', 'publish', 'tarball', 'consumer'],
+  keywords: ['verify', 'pack', 'publish', 'tarball', 'consumer'],
   params: [
     {
       name: 'options.cwd',
@@ -31,6 +31,6 @@ export const doc = {
   examples: [
     {label: 'Check the local package', code: 'await integrationPackCheck();'},
   ],
-  command: 'integration pack',
+  command: 'integration verify',
   related: ['integrationAdd', 'validateIntegration'],
 };

package/api/integration/integrationTemplateConflicts.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
     {
       type: 'integration.template-conflicts',
       description:
-        'The integration identity, structural issues, and every Core template-id conflict with a package-qualified command.',
+        '`validated` (false when no integration manifest was found, so nothing was inspected and the empty conflict list carries no information), the integration identity, structural issues, and every Core template-id conflict with a package-qualified command.',
     },
   ],
   examples: [

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

@@ -0,0 +1,107 @@
+// 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'],
+        peerDependencies: {'@astryxdesign/cli': '>=0.7.0'},
+        peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
+        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

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx integration pack --check` — verify an integration package is
+ * @file `astryx integration verify` — verify an integration package is
  * ready to publish by cross-referencing its declared contributions against the
  * real npm tarball.
  *
@@ -29,9 +29,15 @@ import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs';
 import {
   docsTreeCliProblem,
+  keywordsCliProblem,
   replacesCliProblem,
+  sectionIdsCliProblem,
+  themesCliProblem,
 } from '../../foundation/integrations/cli-requirement.mjs';
-import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
+import {
+  discoverIntegrationDocs,
+  loadTopicModule,
+} from '../../foundation/discovery/docs-discovery.mjs';
 import {
   discoverIntegrationComponents,
   resolveIntegrationImportPath,
@@ -162,6 +168,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
@@ -175,16 +197,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);
@@ -308,6 +339,23 @@ function moduleExportsName(file, exportName, seen = new Set()) {
   return found;
 }
 
+/**
+ * Whether any of these doc files has a section that sets `id`.
+ * @param {string[]} files
+ * @returns {Promise<boolean>}
+ */
+async function setsSectionIds(files) {
+  for (const file of files) {
+    if (typeof file !== 'string') continue;
+    const doc = /** @type {any} */ (await loadTopicModule(file).catch(() => null));
+    const sections = Array.isArray(doc?.sections) ? doc.sections : [];
+    if (sections.some((/** @type {any} */ section) => section?.id != null)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Resolve package specifiers through Node's real ESM resolver from the scratch
  * consumer. Resolution does not execute the target module, so source `.tsx`
@@ -600,19 +648,32 @@ export async function integrationPackCheck(options = {}) {
   // (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 {records, namespaces, guides} = await discoverIntegrationDocs(
+      loaded,
+    ).catch(() => ({records: [], namespaces: [], guides: []}));
     const problem =
       namespaces.length > 0 || guides.length > 0
         ? docsTreeCliProblem(pkg)
         : null;
     if (problem != null) {
       issues.push(error('docs_tree_needs_cli', problem));
+    } else if (
+      await setsSectionIds([
+        ...records.map(record => record.path),
+        ...guides.map(guide => /** @type {any} */ (guide.ref).topicFile),
+      ])
+    ) {
+      // A section `id` is also a field an older CLI rejects, hiding the
+      // package's doc topics. It needs an older CLI than the docs tree does.
+      const idProblem = sectionIdsCliProblem(pkg);
+      if (idProblem != null) {
+        issues.push(error('section_ids_need_cli', idProblem));
+      }
     }
   }
-  // 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.
+  // A template that sets `replaces` (spec:AST-035) or `keywords` needs a CLI
+  // that reads the field: an older CLI drops that template and hides the
+  // package's docs.
   if (loaded.templates) {
     const found = await discoverIntegrationTemplatesForOne(loaded).catch(
       () => ({templates: [], errors: []}),
@@ -624,6 +685,19 @@ export async function integrationPackCheck(options = {}) {
       );
     const problem = setsReplaces ? replacesCliProblem(pkg) : null;
     if (problem != null) issues.push(error('replaces_needs_cli', problem));
+    const setsKeywords = found.templates.some(
+      template => template.keywords != null && template.keywords.length > 0,
+    );
+    const keywordsProblem = setsKeywords ? keywordsCliProblem(pkg) : null;
+    if (keywordsProblem != null) {
+      issues.push(error('keywords_needs_cli', keywordsProblem));
+    }
+  }
+  // A theme needs a CLI that reads typed theme descriptors: an older CLI
+  // rejects the themes root and withholds the package's themes and docs.
+  if (localIdentities.themes.length > 0) {
+    const problem = themesCliProblem(pkg);
+    if (problem != null) issues.push(error('themes_need_cli', problem));
   }
 
   // Temp resources — always cleaned up
@@ -657,6 +731,14 @@ export async function integrationPackCheck(options = {}) {
     // package's already-installed dependencies. The unique suffix makes
     // concurrent checks independent.
     scratchBase = fs.mkdtempSync(path.join(packageDir, '.astryx-pack-check-'));
+    // The consumer's own package.json makes it the package scope for its
+    // imports. Without one, Node resolves the package's name through the
+    // SOURCE package.json (self-reference), so an export target left out of
+    // the tarball would still resolve.
+    fs.writeFileSync(
+      path.join(scratchBase, 'package.json'),
+      `${JSON.stringify({name: 'astryx-verify-consumer', private: true})}\n`,
+    );
 
     // Cross-reference file inventory vs pack list
     if (!packResult.packedPaths.has(fileInv.manifest)) {