@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.dea6813

package/api/init/init.test.mjs

@@ -230,13 +230,40 @@ describe('init() — logger', () => {
       errSpy.mockRestore();
     }
     const text = lines.join('\n');
-    expect(text).toContain('✓ AI agent docs installed → AGENTS.md');
+    expect(text).toContain('[ok] AI agent docs installed -> AGENTS.md');
     expect(text).toContain('  Next steps:');
     // The exact next-steps block the CLI prints comes from getNextSteps().
     expect(text).toContain(getNextSteps('npx astryx')[2].slice(0, 20));
   });
 });
 
+describe('init() — ASCII output', () => {
+  it('prints only ASCII on the default, all-features, re-run, template, and remove paths', async () => {
+    /** @type {string[]} */
+    const lines = [];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation((...a) => lines.push(a.join(' ')));
+    const empty = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-remove-'));
+    logger.setSilent(false);
+    try {
+      await init({}, {cwd: tmpDir});
+      await init({all: true}, {cwd: tmpDir});
+      await init({all: true}, {cwd: tmpDir});
+      await init({features: 'template', templateName: 'blank'}, {cwd: tmpDir});
+      await init({removeAgents: true}, {cwd: tmpDir});
+      await init({removeAgents: true}, {cwd: empty});
+    } finally {
+      logger.setSilent(true);
+      logSpy.mockRestore();
+      errSpy.mockRestore();
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+    expect(lines.length).toBeGreaterThan(0);
+    expect(lines.some(line => line.startsWith('[ok] Removed'))).toBe(true);
+    expect(lines.filter(line => /[\u0080-\uFFFF]/.test(line))).toEqual([]);
+  });
+});
+
 describe('init() — write-path safety', () => {
   it('template scaffold refuses to clobber an existing page.tsx', async () => {
     const dest = path.join(tmpDir, 'src', 'pages', 'blank');
@@ -260,4 +287,17 @@ describe('init() — write-path safety', () => {
       init({features: 'template', templateName: '../../etc/evil'}, {cwd: tmpDir}),
     ).rejects.toMatchObject({code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
   });
+
+  it('refuses a template write that a symlinked src would carry outside cwd (ERR_PATH_TRAVERSAL)', async () => {
+    const outside = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-outside-'));
+    try {
+      fs.symlinkSync(outside, path.join(tmpDir, 'src'), 'dir');
+      await expect(
+        init({features: 'template', templateName: 'blank'}, {cwd: tmpDir}),
+      ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+      expect(fs.readdirSync(outside)).toEqual([]);
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
 });

package/api/init/remove/remove.mjs

@@ -24,6 +24,6 @@ import {logger} from '../../logger.mjs';
  */
 export async function remove({cwd = process.cwd()} = {}) {
   removeAgentDocs(cwd);
-  logger.log('✓ AI agent docs removed.');
+  logger.log('[ok] AI agent docs removed.');
   return {type: 'init.remove', data: {removed: true}};
 }

package/api/init/run/run.mjs

@@ -17,7 +17,7 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
-import {PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {
   installAgentDocs,
@@ -98,7 +98,7 @@ async function applyAgents(cwd, options, invocation, data) {
       renderedBlock,
     });
     data.docsWritten = written;
-    logger.log(`✓ AI agent docs installed → ${written.join(', ')}`);
+    logger.log(`[ok] AI agent docs installed -> ${written.join(', ')}`);
   } catch (err) {
     // PathSafetyError carries a precise, user-actionable message — surface it
     // (and flag exit 1) instead of the generic "could not install" warning so
@@ -132,8 +132,8 @@ function applyTheme(cwd, invocation, data) {
     data.themeTemplatePath = didWrite ? written : null;
     logger.log(
       didWrite
-        ? `✓ Theme template written → ${written}`
-        : `• ${written} already exists — left as is.`,
+        ? `[ok] Theme template written -> ${written}`
+        : `- ${written} already exists - left as is.`,
     );
   } catch {
     // Soft failure, like agent docs: the guidance below is still useful.
@@ -166,16 +166,16 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
     // Point agents at the build workflow rather than dumping page-template
     // names — `build` surfaces pages AND blocks AND components for an idea,
     // and `build` with no args is the full how-to-build playbook.
-    logger.log('✓ To build UI, use these commands:');
+    logger.log('[ok] To build UI, use these commands:');
     logger.log('');
     logger.log(
-      `    ${invocation} build "<what you're building>"   build a page — kit: closest template + blocks + components`,
+      `    ${invocation} build "<what you're building>"   build a page - kit: closest template + blocks + components`,
     );
     logger.log(
       `    ${invocation} build                            the how-to-build workflow (read this first)`,
     );
     logger.log(
-      `    ${invocation} search <query>                   find anything — components, docs, templates, blocks`,
+      `    ${invocation} search <query>                   find anything - components, docs, templates, blocks`,
     );
     logger.log('');
     data.template = 'workflow';
@@ -190,9 +190,19 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
     );
   }
 
-  const outputDir = path.resolve(cwd, `./src/pages/${templateName}`);
+  let destFile;
+  try {
+    destFile = assertWithin(path.join('src', 'pages', templateName, 'page.tsx'), cwd, {
+      label: 'template output path',
+    });
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+  const outputDir = path.dirname(destFile);
   const srcPath = path.join(CLI_ROOT, 'assets', 'templates', 'pages', templateName, 'page.tsx');
-  const destFile = path.join(outputDir, 'page.tsx');
   // Don't clobber a user's existing page — same guard the peer template/copy and
   // theme/add write-leaves apply (init is a public API surface too).
   if (fs.existsSync(destFile)) {
@@ -206,7 +216,7 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
   fs.mkdirSync(outputDir, {recursive: true});
   fs.copyFileSync(srcPath, destFile);
   const rel = path.relative(cwd, outputDir);
-  logger.log(`✓ Template created at ${rel}/page.tsx`);
+  logger.log(`[ok] Template created at ${rel}/page.tsx`);
   data.template = 'created';
   data.templatePath = rel;
 }

package/api/integration/add-contribution.component-names.test.mjs

@@ -0,0 +1,120 @@
+// 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 {integrationAdd, integrationAddComponent} from './add-contribution.mjs';
+import {discoverIntegrationComponents} from '../../foundation/discovery/component-discovery.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-add-component-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist']}, null, 2)}\n`,
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {\n  components: './components',\n};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} relativeDoc */
+function writeAuthoredComponent(relativeDoc) {
+  const doc = path.join(tmpDir, relativeDoc);
+  fs.mkdirSync(path.dirname(doc), {recursive: true});
+  fs.writeFileSync(
+    doc,
+    "export default {\n  type: 'component',\n  name: 'AcmeWidget',\n  description: 'The authored AcmeWidget.',\n  props: [],\n};\n",
+  );
+  fs.writeFileSync(
+    doc.replace(/\.doc\.(?:ts|mjs|js)$/u, '.tsx'),
+    'export function AcmeWidget() {\n  return <div>Authored</div>;\n}\n',
+  );
+}
+
+/** Every file under the package, with its bytes. */
+function snapshot() {
+  /** @type {Record<string, string>} */
+  const files = {};
+  /** @param {string} dir */
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else files[path.relative(tmpDir, full)] = fs.readFileSync(full, 'utf-8');
+    }
+  };
+  walk(tmpDir);
+  return files;
+}
+
+describe('integrationAddComponent name collisions', () => {
+  it('refuses a name a nested component doc already defines', async () => {
+    writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
+    const before = snapshot();
+
+    await expect(
+      integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_FILE_EXISTS',
+      message: expect.stringContaining(
+        'components/AcmeWidget/AcmeWidget.doc.mjs',
+      ),
+    });
+    expect(snapshot()).toEqual(before);
+    expect(
+      discoverIntegrationComponents({
+        name: '@acme/widgets',
+        components: path.join(tmpDir, 'components'),
+      }).map(component => path.relative(tmpDir, component.docPath)),
+    ).toEqual([path.join('components', 'AcmeWidget', 'AcmeWidget.doc.mjs')]);
+  });
+
+  it('refuses the same collision under --dry-run', async () => {
+    writeAuthoredComponent('components/widgets/AcmeWidget.doc.mjs');
+
+    await expect(
+      integrationAdd('component', 'AcmeWidget', {cwd: tmpDir, dryRun: true}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+  });
+
+  it('refuses a same-stem doc with another extension in the root', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.doc.ts'),
+      "export default {type: 'component', name: 'AcmeWidget', props: []};\n",
+    );
+    const before = snapshot();
+
+    await expect(
+      integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+    expect(snapshot()).toEqual(before);
+  });
+
+  it('still adds a component whose name is free', async () => {
+    writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
+
+    const result = await integrationAddComponent('AcmeBadge', {cwd: tmpDir});
+
+    expect(result.data.files).toEqual([
+      'components/AcmeBadge.doc.mjs',
+      'components/AcmeBadge.tsx',
+      'package.json',
+    ]);
+    expect(
+      discoverIntegrationComponents({
+        name: '@acme/widgets',
+        components: path.join(tmpDir, 'components'),
+      })
+        .map(component => component.name)
+        .sort(),
+    ).toEqual(['AcmeBadge', 'AcmeWidget']);
+  });
+});

package/api/integration/add-contribution.mjs

@@ -35,6 +35,7 @@ import {
 } from '../../foundation/integrations/integrations.mjs';
 import {isValidSemver} from '../../foundation/env/semver.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {findIntegrationComponentDoc} from '../../foundation/discovery/component-discovery.mjs';
 import {parseAgentDocsField} from '../../authoring/integration/schema.mjs';
 import {integrationAddTheme} from './add-theme.mjs';
 import {
@@ -248,6 +249,16 @@ async function addComponent(name, options) {
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
+  // Discovery keys components by doc stem anywhere under the root, so a second
+  // doc with this name would shadow one of the two.
+  const existingDoc = findIntegrationComponentDoc({components: root}, name);
+  if (existingDoc != null) {
+    throw new AstryxError(
+      `Refusing to add component "${name}": ${projectPath(path.relative(packageDir, existingDoc))} already defines it.`,
+      undefined,
+      ERROR_CODES.ERR_FILE_EXISTS,
+    );
+  }
 
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');

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

@@ -731,3 +731,83 @@ describe('public dispatcher', () => {
     ).rejects.toThrow(/component, doc, template, codemod, agent-doc, or theme/);
   });
 });
+
+describe('dry-run receipts match the real write', () => {
+  /** Package states each writer has to plan for. */
+  const STATES = {
+    'no manifest': {pkg: {files: ['dist']}},
+    'an empty manifest': {pkg: {}, manifest: 'export default {};\n'},
+    'declared roots and an exports map': {
+      pkg: {files: ['dist'], exports: {'.': './dist/index.js'}},
+      manifest:
+        "export default {\n  components: './components',\n  docs: './docs',\n  templates: './templates',\n  codemods: './codemods',\n  themes: './themes',\n};\n",
+    },
+  };
+  /** @type {Array<[any, string, Record<string, unknown>]>} */
+  const KINDS = [
+    ['component', 'AcmeWidget', {}],
+    ['doc', 'deploying', {}],
+    ['template', 'account-page', {}],
+    ['template', 'account-card', {templateType: 'block'}],
+    ['codemod', 'rename-widget', {to: '1.2.0'}],
+    ['agent-doc', 'Run acme verify before finishing.', {}],
+    ['theme', 'ocean', {}],
+  ];
+
+  /** Every file under the package, keyed by project path, with its bytes. */
+  function snapshot() {
+    /** @type {Record<string, string>} */
+    const files = {};
+    /** @param {string} dir */
+    const walk = dir => {
+      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else {
+          files[path.relative(tmpDir, full).split(path.sep).join('/')] =
+            fs.readFileSync(full, 'base64');
+        }
+      }
+    };
+    walk(tmpDir);
+    return files;
+  }
+
+  for (const [stateName, state] of Object.entries(STATES)) {
+    for (const [kind, name, options] of KINDS) {
+      it(`${kind} ${name} in a package with ${stateName}`, async () => {
+        fs.writeFileSync(
+          path.join(tmpDir, 'package.json'),
+          `${JSON.stringify({name: '@acme/integration', version: '1.0.0', ...state.pkg}, null, 2)}\n`,
+        );
+        if (state.manifest != null) {
+          fs.writeFileSync(
+            path.join(tmpDir, 'astryx.integration.mjs'),
+            state.manifest,
+          );
+        }
+        const before = snapshot();
+
+        const plan = await integrationAdd(kind, name, {
+          cwd: tmpDir,
+          dryRun: true,
+          ...options,
+        });
+        expect(snapshot()).toEqual(before);
+
+        const written = await integrationAdd(kind, name, {
+          cwd: tmpDir,
+          ...options,
+        });
+        const after = snapshot();
+        const changed = Object.keys(after)
+          .filter(file => after[file] !== before[file])
+          .sort();
+
+        expect(written.data.root).toEqual(plan.data.root);
+        expect(written.data.files).toEqual(plan.data.files);
+        expect([...written.data.files].sort()).toEqual(changed);
+      });
+    }
+  }
+});

package/api/integration/integrationAdd.doc.mjs

@@ -33,7 +33,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 +57,19 @@ 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.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/integrationAddComponent.doc.mjs

@@ -8,7 +8,7 @@ export const doc = {
   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/validate-integration.mjs

@@ -400,8 +400,10 @@ export async function validateLocalIntegration(cwd = process.cwd()) {
   try {
     pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
   } catch (err) {
+    // A null name means "no manifest here"; this package has one.
     return {
       found: true,
+      name: '(local package)',
       manifestFile: manifests[0],
       issues: [
         error(

package/api/integration/validate-integration.test.mjs

@@ -13,10 +13,16 @@ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
+  validateIntegration,
   validateLocalIntegration,
   validateInstalledIntegration,
   summarizeIssues,
 } from './validate-integration.mjs';
+import {
+  integrationComponentConflicts,
+  integrationDocConflicts,
+  integrationTemplateConflicts,
+} from './authoring-checks.mjs';
 
 let tmpDir;
 
@@ -472,3 +478,88 @@ describe('validate-integration API', () => {
     expect(byCode(result.issues, 'invalid_package_spec')).toHaveLength(1);
   });
 });
+
+describe('integration diagnostics are read-only', () => {
+  /** Every directory and file under `dir`, with file bytes. */
+  function snapshot(dir) {
+    /** @type {Record<string, string>} */
+    const entries = {};
+    /** @param {string} current */
+    const walk = current => {
+      for (const entry of fs.readdirSync(current, {withFileTypes: true})) {
+        const full = path.join(current, entry.name);
+        const key = path.relative(dir, full);
+        if (entry.isDirectory()) {
+          entries[`${key}/`] = '';
+          walk(full);
+        } else {
+          entries[key] = fs.readFileSync(full, 'base64');
+        }
+      }
+    };
+    walk(dir);
+    return entries;
+  }
+
+  /** A package with valid, broken, conflicting, and unreachable contributions. */
+  function writeDiagnosedPackage(dir) {
+    writePackage(dir, {
+      manifest:
+        "export default {\n  components: './components',\n  templates: './templates',\n  docs: './docs',\n  codemods: './gone',\n  themes: './themes',\n};\n",
+    });
+    const write = (relative, contents) => {
+      fs.mkdirSync(path.dirname(path.join(dir, relative)), {recursive: true});
+      fs.writeFileSync(path.join(dir, relative), contents);
+    };
+    write(
+      'components/Card.doc.mjs',
+      "export default {type: 'component', name: 'Card', props: []};\n",
+    );
+    write('components/Card.tsx', 'export function Card() { return null; }\n');
+    write(
+      'components/Orphan.doc.mjs',
+      "export default {type: 'component', name: 'Orphan', props: []};\n",
+    );
+    write('templates/dash.doc.mjs', "export default {type: 'page', name: 'Dash'};\n");
+    write(
+      'docs/theme.doc.mjs',
+      "export default {type: 'generic', name: 'theme', title: 'Theme', description: 'x', sections: [{title: 'A', content: [{type: 'prose', text: 'x'}]}]};\n",
+    );
+    write('themes/manifest.json', '{"version": 1, "themes": [{"slug": 7}]}\n');
+    write(
+      'stray/Stray.doc.mjs',
+      "export default {type: 'component', name: 'Stray', props: []};\n",
+    );
+  }
+
+  it('leaves local and installed packages byte-for-byte unchanged', async () => {
+    const pkgDir = path.join(tmpDir, 'pkg');
+    writeDiagnosedPackage(pkgDir);
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    writeDiagnosedPackage(path.join(consumer, 'node_modules', '@acme', 'widgets'));
+    const before = {pkg: snapshot(pkgDir), consumer: snapshot(consumer)};
+
+    const local = await validateIntegration(undefined, {cwd: pkgDir});
+    const installed = await validateIntegration('@acme/widgets', {
+      cwd: consumer,
+    });
+    for (const [pkg, cwd] of [
+      [undefined, pkgDir],
+      ['@acme/widgets', consumer],
+    ]) {
+      await integrationTemplateConflicts(pkg, {cwd});
+      await integrationComponentConflicts(pkg, {cwd});
+      await integrationDocConflicts(pkg, {cwd});
+    }
+
+    expect(summarizeIssues(local.data.issues).errors).toBeGreaterThan(0);
+    expect(byCode(local.data.issues, 'unreachable_contribution')).toHaveLength(1);
+    expect(summarizeIssues(installed.data.issues).errors).toBeGreaterThan(0);
+    expect({pkg: snapshot(pkgDir), consumer: snapshot(consumer)}).toEqual(before);
+  });
+});

package/api/integration/validateIntegration.doc.mjs

@@ -45,7 +45,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.name` and `data.version` of the validated package (both null only when no local manifest is found; `data.name` is `(local package)` when the local package.json has no readable name), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [

package/api/json/envelope-types.test.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The published `@astryxdesign/cli/json` envelope types carry
+ * `apiVersion`, the field every `--json` envelope has. Type-checks a consumer
+ * fixture that reads it from each envelope shape.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
+
+const INDEX = fileURLToPath(new URL('./index.ts', import.meta.url));
+const TSC = createRequire(import.meta.url).resolve('typescript/bin/tsc');
+
+const FIXTURE = `
+import type {
+  assertResponse,
+  CLIError,
+  CLIUnsupportedError,
+  parseResponse,
+} from ${JSON.stringify(INDEX)};
+
+declare const error: CLIError;
+declare const unsupported: CLIUnsupportedError;
+declare const parsed: Exclude<ReturnType<typeof parseResponse>, CLIError | CLIUnsupportedError>;
+declare const asserted: ReturnType<typeof assertResponse<'manifest'>>;
+
+export const versions: number[] = [
+  error.apiVersion,
+  unsupported.apiVersion,
+  parsed.apiVersion,
+  asserted.apiVersion,
+];
+`;
+
+describe('@astryxdesign/cli/json envelope types', () => {
+  it('declare apiVersion on the success and error envelopes', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-envelope-types-'));
+    try {
+      fs.writeFileSync(path.join(dir, 'fixture.ts'), FIXTURE);
+      fs.writeFileSync(
+        path.join(dir, 'tsconfig.json'),
+        JSON.stringify({
+          compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'bundler',
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+            allowImportingTsExtensions: true,
+            // index.ts re-exports JSDoc types from .type.mjs files; read them
+            // from source, as tsconfig.json-api.json does, not from generated
+            // declarations that exist only after a build.
+            allowJs: true,
+            types: [],
+          },
+          files: ['fixture.ts'],
+        }),
+      );
+      const res = spawnSync(process.execPath, [TSC, '-p', dir], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+      });
+      expect(res.stdout + res.stderr).toBe('');
+      expect(res.status).toBe(0);
+    } finally {
+      fs.rmSync(dir, {recursive: true, force: true});
+    }
+  });
+});

package/api/json/parseResponse.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   description:
     'The entry point for consuming the CLI as a subprocess. A JSON string is parsed; ' +
     'an already-parsed object is passed through unchanged, so it is safe to call on ' +
-    'either. It returns the structural { type, data, meta? } envelope without narrowing: ' +
+    'either. It returns the structural { apiVersion, type, data, meta? } envelope without narrowing: ' +
     '`data` stays unknown until you discriminate on `type` (or use assertResponse).',
   importPath: '@astryxdesign/cli/json',
   signature: 'parseResponse(raw: unknown): any',
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { apiVersion, type, data, meta? } envelope, or a CLIError envelope ({ apiVersion, error, code, suggestions? }). The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/layout/expand/expand.mjs

@@ -120,18 +120,20 @@ export async function layoutExpand(expression, options = {}) {
 
   let written = null;
   if (targetPath) {
-    let resolved;
+    // The guard sees the file that will be written, not only its directory:
+    // a symlink at that name would otherwise carry the write outside the root.
+    const fileTarget = isFilePathArg(targetPath)
+      ? targetPath
+      : path.join(targetPath, `${componentName}.tsx`);
+    let filePath;
     try {
-      resolved = assertWithin(targetPath, cwd, {label: 'layout target path'});
+      filePath = assertWithin(fileTarget, cwd, {label: 'layout target path'});
     } catch (err) {
       if (err instanceof PathSafetyError) {
         throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
       }
       throw err;
     }
-    const filePath = isFilePathArg(targetPath)
-      ? resolved
-      : path.join(resolved, `${componentName}.tsx`);
     fs.mkdirSync(path.dirname(filePath), {recursive: true});
     fs.writeFileSync(filePath, result.code);
     written = path.relative(cwd, filePath);