@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

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

@@ -2,9 +2,16 @@
 
 /**
  * @file Hermetic integration authoring checks against the real Core catalogs.
+ * @input Integration fixtures and the post-0.7 conflict projection.
+ * @output Coverage for replacement validation and public diagnostics.
+ * @position Unit coverage; the 0.6.x compatibility shape has its own fixture.
  */
 
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+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 {discoverCoreTemplates} from '../../foundation/discovery/template-adapter.mjs';
@@ -20,7 +27,14 @@ import {
 
 let tmpDir;
 
-function writeIntegration({id, name, type = 'block', root = tmpDir}) {
+function writeIntegration({
+  id,
+  name,
+  type = 'block',
+  root = tmpDir,
+  replacements,
+  withSource = true,
+}) {
   fs.mkdirSync(root, {recursive: true});
   fs.writeFileSync(
     path.join(root, 'package.json'),
@@ -33,9 +47,10 @@ function writeIntegration({id, name, type = 'block', root = tmpDir}) {
   const stem = path.join(root, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
-    `export default {type: '${type}', 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`,
   );
+  if (!withSource) return;
   fs.writeFileSync(
     `${stem}.tsx`,
     'export default function Fixture() { return null; }\n',
@@ -158,6 +173,159 @@ describe('integrationTemplateConflicts', () => {
     );
   });
 
+  it('classifies a valid replacement and points to the Core original', async () => {
+    const core = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      name: 'Acme app shell',
+      type: core.type,
+      replacements: {'acme-app-shell': core.dirName},
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual([]);
+    expect(result.data.conflicts).toEqual([
+      expect.objectContaining({
+        id: 'acme-app-shell',
+        severity: 'info',
+        relationship: 'replaces',
+        replaces: core.dirName,
+      }),
+    ]);
+    expect(result.data.conflicts[0].command).toContain(
+      `template ${core.dirName} --package @astryxdesign/core`,
+    );
+  });
+
+  it('reports a replacement target that Core does not provide', async () => {
+    writeIntegration({
+      id: 'acme-app-shell',
+      name: 'Acme app shell',
+      type: 'page',
+      replacements: {'acme-app-shell': 'missing-core-shell'},
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          severity: 'error',
+        }),
+      ]),
+    );
+  });
+
+  it('reports a replacement declared by a template that cannot be used', async () => {
+    const [core] = await discoverCoreTemplates();
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'broken-template',
+      name: 'Broken template',
+      type: core.type,
+      replacements: {'broken-template': core.dirName},
+      withSource: false,
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'invalid_template_replacement',
+          severity: 'error',
+          message: expect.stringContaining('cannot be used'),
+        }),
+      ]),
+    );
+  });
+
+  it('reports two templates that replace the same Core target as ambiguous', async () => {
+    const [core] = await discoverCoreTemplates();
+    expect(core).toBeDefined();
+    const replacements = {
+      'acme-app-shell-a': core.dirName,
+      'acme-app-shell-b': core.dirName,
+    };
+    writeIntegration({
+      id: 'acme-app-shell-a',
+      name: 'Acme app shell A',
+      type: core.type,
+      replacements,
+    });
+    writeIntegration({
+      id: 'acme-app-shell-b',
+      name: 'Acme app shell B',
+      type: core.type,
+      replacements,
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'ambiguous_template_replacement',
+          severity: 'error',
+        }),
+      ]),
+    );
+  });
+
+  it('reports a replacement whose template kind differs from Core', async () => {
+    const corePage = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(corePage).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      name: 'Acme app shell',
+      type: 'block',
+      replacements: {'acme-app-shell': corePage.dirName},
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+
+    expect(result.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'invalid_template_replacement',
+          severity: 'error',
+          message: expect.stringContaining('same type'),
+        }),
+      ]),
+    );
+  });
+
+  it('does not recommend an impossible replacement for a different Core kind', async () => {
+    const corePage = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(corePage).toBeDefined();
+    writeIntegration({
+      id: corePage.dirName,
+      name: 'Acme block with a page id',
+      type: 'block',
+    });
+
+    const result = await integrationTemplateConflicts(undefined, {cwd: tmpDir});
+    const conflict = result.data.conflicts.find(
+      item => item.id === corePage.dirName,
+    );
+
+    expect(conflict?.relationship).toBe('accidental');
+    expect(conflict?.message).toContain(
+      'cannot replace a different template kind',
+    );
+    expect(conflict?.message).toContain('Rename');
+    expect(conflict?.message).not.toContain('set replaces');
+  });
+
   it('shell-quotes unusual ids instead of allowing command substitution', () => {
     expect(shellArg('safe/id')).toBe('safe/id');
     expect(shellArg('my$thing')).toBe("'my$thing'");
@@ -176,7 +344,7 @@ describe('integrationTemplateConflicts', () => {
     );
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
     fs.writeFileSync(
-      path.join(tmpDir, 'templates', 'broken.template.mjs'),
+      path.join(tmpDir, 'templates', 'broken.doc.mjs'),
       `throw new Error('broken fixture');\n`,
     );
     fs.writeFileSync(
@@ -221,7 +389,9 @@ describe('integrationComponentConflicts', () => {
     expect(core).toBeDefined();
     writeComponentIntegration(core.name);
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.type).toBe('integration.component-conflicts');
     expect(result.data.issues).toEqual([]);
@@ -240,7 +410,9 @@ describe('integrationComponentConflicts', () => {
   it('does not flag an integration-only component name', async () => {
     writeComponentIntegration('AcmeOnlyWidget');
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.data.conflicts).toEqual([]);
     expect(result.data.issues).toEqual([]);

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

@@ -1,6 +1,11 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @file Colocated types for integration authoring diagnostics. */
+/**
+ * @file Colocated public types for integration authoring diagnostics.
+ * @input Stable response fields exposed by integration-authoring APIs.
+ * @output JSDoc typedefs consumed by declarations, commands, and callers.
+ * @position Public type boundary for integration diagnostics.
+ */
 
 /**
  * @typedef {object} IntegrationAuthoringOptions

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,14 +5,15 @@ export const doc = {
   type: 'function',
   kind: 'api',
   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.",
+    "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',
@@ -30,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.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,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');
+  });
+});