@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

package/api/integration/add-helpers.mjs

@@ -5,7 +5,8 @@
  *
  * Hosts the atomic staged-write transaction, package.json files-array
  * maintenance, package-dir resolution, and project-path normalization that
- * every `integration add <kind>` command needs. Stateless and side-effect-free
+ * every `integration add <kind>` command needs. `theme add` and `theme build`
+ * write through the same transaction. Stateless and side-effect-free
  * outside of {@link applyWrites}.
  */
 
@@ -40,7 +41,7 @@ export function findPackageDir(startDir) {
 /**
  * @typedef {object} WritePlan
  * @property {string} path
- * @property {string} contents
+ * @property {string | Buffer} contents a Buffer is written byte for byte
  * @property {boolean} createOnly
  * @property {Buffer} [expectedOriginal] bytes captured before validation;
  *   a different current file is a concurrent edit and must never be overwritten
@@ -192,21 +193,29 @@ export function packageJsonUpdate(
 
 // ── Atomic staged-write transaction ─────────────────────────────────
 
-/** @param {string} file */
+/**
+ * @param {string} file
+ * @returns {boolean} false when the file is still there
+ */
 function removeTemporary(file) {
   try {
     fs.rmSync(file, {force: true});
+    return true;
   } catch {
     // Best effort. The transaction error remains the actionable failure.
+    return false;
   }
 }
 
 /**
  * Restore writes that already published.  Best-effort so callers preserve
- * the original actionable error.
+ * the original actionable error; returns every path it could not put back.
  * @param {Array<WritePlan & {temporary: string, original: Buffer|null, mode: number}>} published
+ * @returns {string[]}
  */
 function rollbackWrites(published) {
+  /** @type {string[]} */
+  const unrestored = [];
   for (const plan of [...published].reverse()) {
     let restore = null;
     try {
@@ -225,12 +234,18 @@ function rollbackWrites(published) {
         fs.renameSync(restore, plan.path);
         restore = null;
       }
-    } catch {
-      // Best effort. A concurrent edit belongs to its writer, not this rollback.
+    } catch (error) {
+      // A created file that is already gone needs nothing. Any other failure
+      // leaves this call's bytes, or no bytes, where the original was.
+      const gone =
+        error instanceof Error &&
+        /** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT';
+      if (!(gone && plan.original == null)) unrestored.push(plan.path);
     } finally {
       if (restore != null) removeTemporary(restore);
     }
   }
+  return unrestored;
 }
 
 /** @param {string} file */
@@ -325,10 +340,22 @@ export function applyWrites(plans) {
       }
       published.push(plan);
     }
-    return () => rollbackWrites(published);
+    return () => {
+      rollbackWrites(published);
+    };
   } catch (error) {
-    for (const plan of staged) removeTemporary(plan.temporary);
-    rollbackWrites(published);
+    const leftovers = staged
+      .filter(plan => !removeTemporary(plan.temporary))
+      .map(plan => plan.temporary);
+    const unrestored = rollbackWrites(published);
+    if (error instanceof Error) {
+      if (unrestored.length > 0) {
+        error.message += ` Could not restore: ${unrestored.join(', ')}.`;
+      }
+      if (leftovers.length > 0) {
+        error.message += ` Could not remove temporary files: ${leftovers.join(', ')}.`;
+      }
+    }
     throw error;
   }
 }

package/api/integration/add-theme.mjs

@@ -24,6 +24,10 @@ import {
 import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
 import {themeDescriptorSource} from '../../foundation/integrations/theme-descriptor.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {
+  themesCliProblem,
+  withDocsTreeCli,
+} from '../../foundation/integrations/cli-requirement.mjs';
 import {
   applyWrites,
   findPackageDir,
@@ -233,11 +237,28 @@ export async function integrationAddTheme(name, options = {}) {
       createOnly: true,
     },
   ];
-  const packageUpdate = packageJsonUpdate(
+  let packageUpdate = packageJsonUpdate(
     packageFile,
     rootPath,
     path.basename(manifestFile),
   );
+  // A CLI older than the one that reads typed theme descriptors rejects the
+  // themes root and withholds the package's themes and docs. Declare the CLI
+  // that reads them as a peer, so an older one is flagged at install instead.
+  {
+    const expectedOriginal =
+      packageUpdate?.expectedOriginal ?? fs.readFileSync(packageFile);
+    const text = packageUpdate?.contents ?? expectedOriginal.toString('utf-8');
+    const current = JSON.parse(text);
+    if (themesCliProblem(current) != null) {
+      packageUpdate = {
+        contents:
+          JSON.stringify(withDocsTreeCli(current), null, 2) +
+          (text.endsWith('\n') ? '\n' : ''),
+        expectedOriginal,
+      };
+    }
+  }
   if (packageUpdate != null) {
     plans.push({
       path: packageFile,

package/api/integration/add-theme.test.mjs

@@ -77,6 +77,40 @@ describe('integrationAddTheme', () => {
     expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
   });
 
+  it('declares the optional CLI peer that reads typed theme descriptors', async () => {
+    setup({includeFiles: false});
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).toContain('package.json');
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.7.0'});
+    expect(pkg.peerDependenciesMeta).toEqual({
+      '@astryxdesign/cli': {optional: true},
+    });
+  });
+
+  it('keeps a CLI peer that already reads typed theme descriptors', async () => {
+    const pkg = {
+      name: '@acme/themes',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^0.7.2'},
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify(pkg, null, 2)}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).not.toContain('package.json');
+    expect(
+      JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8')),
+    ).toEqual(pkg);
+  });
+
   it('dry-runs the identical receipt without writing anything', async () => {
     setup();
     const beforeManifest = fs.readFileSync(

package/api/integration/authoring-checks.mjs

@@ -368,11 +368,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

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/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.
  *
@@ -30,8 +30,13 @@ import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs'
 import {
   docsTreeCliProblem,
   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 +167,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 +196,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 +338,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 +647,31 @@ 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; the same peer range fixes both.
+      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.
+  // (spec:AST-035): an older CLI drops that template and hides the package's docs.
   if (loaded.templates) {
     const found = await discoverIntegrationTemplatesForOne(loaded).catch(
       () => ({templates: [], errors: []}),
@@ -625,6 +684,12 @@ export async function integrationPackCheck(options = {}) {
     const problem = setsReplaces ? replacesCliProblem(pkg) : null;
     if (problem != null) issues.push(error('replaces_needs_cli', problem));
   }
+  // 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
   const tgzTmpDir = fs.mkdtempSync(
@@ -657,6 +722,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)) {

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

@@ -36,6 +36,8 @@ function writePackage({
   scripts,
 } = {}) {
   const pkg = {name, version};
+  // A theme needs a CLI that reads typed theme descriptors.
+  if (themes) pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
   if (files !== undefined) pkg.files = files;
   if (scripts !== undefined) pkg.scripts = scripts;
   fs.writeFileSync(
@@ -94,6 +96,30 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('fails a package that ships a theme on a CLI range that cannot read it', async () => {
+    writePackage({files: ['astryx.integration.mjs', 'themes']});
+    const pkgFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    delete pkg.peerDependencies;
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+
+    const missing = await integrationPackCheck({cwd: tmpDir});
+    expect(missing.data.packable).toBe(false);
+    expect(missing.data.issues).toContainEqual(
+      expect.objectContaining({
+        code: 'themes_need_cli',
+        message: expect.stringContaining('ships a theme'),
+      }),
+    );
+
+    pkg.peerDependencies = {'@astryxdesign/cli': '^0.6.3'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    const old = await integrationPackCheck({cwd: tmpDir});
+    expect(old.data.issues).toContainEqual(
+      expect.objectContaining({code: 'themes_need_cli'}),
+    );
+  });
+
   it('fails when a theme entry omits its inferred runtime export', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
     fs.writeFileSync(
@@ -193,6 +219,39 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('resolves public imports in the packed package, not the source', async () => {
+    // The root export's target is left out of `files`: the source package
+    // resolves it, but an app that installs the tarball cannot.
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs'],
+        exports: {'.': './index.mjs'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      "export {AcmeWidget} from './components/AcmeWidget.tsx';\n",
+    );
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+    const docFile = path.join(tmpDir, 'components', 'AcmeWidget.doc.mjs');
+    const doc = fs.readFileSync(docFile, 'utf-8');
+    expect(doc).toContain('@acme/widgets/components/AcmeWidget');
+    fs.writeFileSync(
+      docFile,
+      doc.replace('@acme/widgets/components/AcmeWidget', '@acme/widgets'),
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+  });
+
   it('fails when packed template source is hidden by package exports', async () => {
     writePackage({
       manifest: "export default {templates: './templates'};\n",
@@ -336,6 +395,37 @@ describe('integrationPackCheck', () => {
     expect(await codes()).not.toContain('docs_tree_needs_cli');
   }, 120_000);
 
+  it('fails a package whose doc section sets id on a CLI range that rejects the field', async () => {
+    writePackage({manifest: "export default {docs: './docs'};\n", themes: false});
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const topic = (/** @type {string} */ section) =>
+      `export default {type: 'generic', name: 'notes', title: 'Notes', description: 'Notes.', sections: [${section}]};\n`;
+    const file = path.join(tmpDir, 'docs', 'notes.doc.mjs');
+    const codes = async () =>
+      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+        (/** @type {{code: string}} */ issue) => issue.code,
+      );
+    fs.writeFileSync(
+      file,
+      topic("{title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}"),
+    );
+    expect(await codes()).not.toContain('section_ids_need_cli');
+    // A fresh file name: the module loader caches a path once it is imported.
+    fs.rmSync(file);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'notes-with-ids.doc.mjs'),
+      topic(
+        "{id: 'take-notes', title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}",
+      ),
+    );
+    expect(await codes()).toContain('section_ids_need_cli');
+    const pkgFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    expect(await codes()).not.toContain('section_ids_need_cli');
+  }, 120_000);
+
   it('fails a package with a template that sets replaces on a CLI range that rejects the field', async () => {
     writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});

package/api/integration/pack-check.type.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Colocated types for `astryx integration pack --check`.
+ * @file Colocated types for `astryx integration verify`.
  */
 
 /**

package/api/json/assertResponse.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
   throws: [
     {
       code: 'Error',
-      when: 'the CLI returned an error envelope (the CLI message is rethrown), or the response `type` is not expectedType',
+      when: 'a plain Error with no code: the CLI returned an error envelope (its message is rethrown; code and suggestions are dropped), or the response `type` is not expectedType',
     },
   ],
   examples: [

package/api/json/isError.doc.mjs

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