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

package/foundation/fs/file-protection.test.mjs

@@ -0,0 +1,250 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  createFileProtectionResolver,
+  ProtectionSourceError,
+} from './file-protection.mjs';
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-protection-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+function write(relative, contents = '') {
+  const file = path.join(root, relative);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, contents);
+  return file;
+}
+
+function declarations(relative) {
+  return createFileProtectionResolver(root)
+    .classify(path.join(root, relative))
+    .map(item => item.declaration);
+}
+
+describe('working-tree .gitattributes', () => {
+  it('honors nested later rules and explicit false or unset values', () => {
+    write(
+      '.gitattributes',
+      [
+        '*.css linguist-generated=true',
+        'vendor/** linguist-vendored',
+        'authored.css -linguist-generated',
+        'unset.css !linguist-generated',
+        '',
+      ].join('\n'),
+    );
+    write('generated.css', 'body {}');
+    write('authored.css', 'body {}');
+    write('unset.css', 'body {}');
+    write('nested/keep.css', 'body {}');
+    write('nested/.gitattributes', 'keep.css linguist-generated=false\n');
+    write('vendor/pkg/index.js', 'export {};');
+
+    expect(declarations('generated.css')).toContain(
+      'linguist-generated in .gitattributes:1',
+    );
+    expect(declarations('authored.css')).toEqual([]);
+    expect(declarations('unset.css')).toEqual([]);
+    expect(declarations('nested/keep.css')).toEqual([]);
+    expect(declarations('vendor/pkg/index.js')).toContain(
+      'linguist-vendored in .gitattributes:2',
+    );
+  });
+
+  it('expands top-level attribute macros, including forward definitions', () => {
+    write(
+      '.gitattributes',
+      'via-macro/** outer\n[attr]outer generated\n[attr]generated linguist-generated\n',
+    );
+    write('via-macro/output.js', 'export {};');
+    expect(declarations('via-macro/output.js')).toContain(
+      'linguist-generated in .gitattributes:1',
+    );
+  });
+
+  it('preserves escaped wildcards as literal path characters', () => {
+    write('.gitattributes', 'literal\\*.js linguist-generated\n');
+    write('literal*.js', 'export {};');
+    write('literalX.js', 'export {};');
+    expect(declarations('literal*.js')).toHaveLength(1);
+    expect(declarations('literalX.js')).toEqual([]);
+  });
+
+  it('supports quoted attribute patterns with spaces', () => {
+    write('.gitattributes', '"generated output/*.js" linguist-generated\n');
+    write('generated output/theme.js', 'export {};');
+    expect(declarations('generated output/theme.js')).toHaveLength(1);
+  });
+
+  it('matches basename patterns below the declaring directory', () => {
+    write('.gitattributes', '*.gen.ts linguist-generated\n');
+    write('src/deep/theme.gen.ts', 'export {};');
+    expect(declarations('src/deep/theme.gen.ts')).toHaveLength(1);
+  });
+});
+
+describe('working-tree ignore rules', () => {
+  it('honors gitignore negation and nested precedence', () => {
+    write('.gitignore', ['src/**/*.js', '!src/keep.js', ''].join('\n'));
+    write('src/drop.js', 'drop');
+    write('src/keep.js', 'keep');
+    write('src/deep/drop.js', 'drop');
+    write('src/.gitignore', '!deep/keep.js\n');
+    write('src/deep/keep.js', 'keep');
+
+    expect(declarations('src/drop.js')[0]).toBe('excluded by .gitignore');
+    expect(declarations('src/deep/drop.js')[0]).toBe('excluded by .gitignore');
+    expect(declarations('src/keep.js')).toEqual([]);
+    expect(declarations('src/deep/keep.js')).toEqual([]);
+  });
+
+  it('uses case-sensitive Git matching on case-sensitive platforms', () => {
+    write('.gitignore', 'FOO\n');
+    write('FOO', 'x');
+    write('foo', 'x');
+
+    expect(declarations('FOO')[0]).toBe('excluded by .gitignore');
+    expect(declarations('foo')).toEqual([]);
+  });
+
+  it('does not let a nested ignore file re-include beneath an excluded parent', () => {
+    write('.gitignore', 'ignored/\n');
+    write('ignored/.gitignore', '!keep.js\n');
+    write('ignored/keep.js', 'keep');
+
+    expect(declarations('ignored/keep.js')[0]).toBe('excluded by .gitignore');
+  });
+
+  it('ignores nested .hgignore files unless the root file includes them', () => {
+    write('sub/.hgignore', 'syntax: glob\n*.tmp\n');
+    write('sub/file.tmp', 'x');
+    expect(declarations('sub/file.tmp')).toEqual([]);
+  });
+
+  it('reads Mercurial glob and regexp syntax without a repository process', () => {
+    write(
+      '.hgignore',
+      ['syntax: glob', '**/*.generated.css', 're:^legacy/.+\\.js$', ''].join(
+        '\n',
+      ),
+    );
+    write('src/theme.generated.css', 'x');
+    write('legacy/file.js', 'x');
+    write('src/file.js', 'x');
+
+    expect(declarations('src/theme.generated.css')[0]).toMatch(/\.hgignore:2/);
+    expect(declarations('legacy/file.js')[0]).toMatch(/\.hgignore:3/);
+    expect(declarations('src/file.js')).toEqual([]);
+  });
+});
+
+describe('leading generated comments', () => {
+  it.each([
+    ['// @generated\nexport const x = 1;\n', '@generated'],
+    [
+      '/* @partially-generated */\nexport const x = 1;\n',
+      '@partially-generated',
+    ],
+    [
+      '// Code generated by Acme. DO NOT EDIT.\nconst x = 1;\n',
+      'Code generated',
+    ],
+    ['#!/usr/bin/env node\n// @generated\nconsole.log(1);\n', '@generated'],
+  ])('protects a recognized leading marker', (source, expected) => {
+    write('file.js', source);
+    expect(declarations('file.js')[0]).toContain(expected);
+  });
+
+  it('recognizes hash comments after a shebang in an extensionless file', () => {
+    write('script', '#!/bin/sh\n# @generated\necho hi\n');
+    expect(declarations('script')[0]).toContain('@generated');
+  });
+
+  it('does not treat a marker after authored code as protection', () => {
+    write('file.js', 'export const authored = true;\n// @generated\n');
+    expect(declarations('file.js')).toEqual([]);
+  });
+
+  it('does not accept longer generated-like annotations', () => {
+    write('file.js', '// @generated-code\nexport const authored = true;\n');
+    expect(declarations('file.js')).toEqual([]);
+  });
+
+  it('does not mistake a leading CSS id selector for a comment', () => {
+    write('file.css', '#root { color: red; }\n/* @generated */\n');
+    expect(declarations('file.css')).toEqual([]);
+  });
+
+  it('extracts an exact regeneration command from a generated header', () => {
+    const file = write(
+      'theme.css',
+      '/*\n * @generated\n * Command: pnpm astryx theme build src/theme.ts\n */\n',
+    );
+    const protection = createFileProtectionResolver(root).classify(file)[0];
+    expect(protection.command).toBe('pnpm astryx theme build src/theme.ts');
+  });
+});
+
+describe('hard boundaries and fail-closed parsing', () => {
+  it('protects dependency metadata, VCS metadata leaves, symlinks, and paths outside root', () => {
+    const dependency = write('node_modules/pkg/index.js', 'x');
+    const yarnDependency = write('.yarn/unplugged/pkg/index.js', 'x');
+    const yarnVirtual = write('.yarn/__virtual__/pkg/index.js', 'x');
+    const yarnInstallState = write('.yarn/install-state.gz', 'x');
+    const yarnPatch = write('.yarn/patches/pkg.patch', 'x');
+    const pnp = write('.pnp.cjs', 'x');
+    const pnpData = write('.pnp.data.json', '{}');
+    const metadata = write('.git', 'gitdir: elsewhere\n');
+    const target = write('target.js', 'x');
+    const link = path.join(root, 'link.js');
+    fs.symlinkSync(target, link);
+    const resolver = createFileProtectionResolver(root);
+
+    expect(resolver.classify(dependency)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnDependency)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnVirtual)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnInstallState)[0].reason).toBe('dependency');
+    expect(resolver.classify(yarnPatch)).toEqual([]);
+    expect(resolver.classify(pnp)[0].reason).toBe('dependency');
+    expect(resolver.classify(pnpData)[0].reason).toBe('dependency');
+    expect(resolver.classify(metadata)[0].reason).toBe('vcs');
+    expect(resolver.classify(link)[0].reason).toBe('symlink');
+    expect(
+      resolver.classify(path.join(root, '..', 'outside.js'))[0].reason,
+    ).toBe('outside-root');
+  });
+
+  it('rejects an .hgignore include reached through a symlink', () => {
+    const outside = path.join(
+      os.tmpdir(),
+      `astryx-ignore-${process.pid}-${Date.now()}`,
+    );
+    fs.writeFileSync(outside, 'syntax: glob\n*.generated\n');
+    try {
+      fs.symlinkSync(outside, path.join(root, 'rules'));
+      write('.hgignore', 'include:rules\n');
+      expect(() => createFileProtectionResolver(root)).toThrow(/symbolic link/);
+    } finally {
+      fs.rmSync(outside, {force: true});
+    }
+  });
+
+  it('fails before use when a protection source cannot be parsed', () => {
+    write('.hgignore', 'syntax: regexp\n[unterminated\n');
+    expect(() => createFileProtectionResolver(root)).toThrow(
+      ProtectionSourceError,
+    );
+    expect(() => createFileProtectionResolver(root)).toThrow(/\.hgignore/);
+  });
+});

package/foundation/fs/module-loader.d.mts

@@ -9,6 +9,7 @@
  * nearest package.json `type` decides `.js`, matching Node's package scopes.
  * Normal loads retain module caching. `fresh` is an explicit migration-only
  * escape hatch for rereading files that a codemod changed during this process.
+ * Anything the module writes to stdout while it loads goes to stderr.
  *
  * @param {string} file absolute path
  * @param {{fresh?: boolean}} [options]

package/foundation/fs/module-loader.mjs

@@ -7,7 +7,8 @@
  * user-authored module (`.ts` via jiti, `.mjs`/`.js` via native dynamic
  * import) and (b) find conventional files by basename in a fixed
  * load-precedence order. These helpers centralize that so the two callers stay
- * in lockstep.
+ * in lockstep. A module's stdout writes go to stderr while it loads, so
+ * project code that prints cannot corrupt a `--json` envelope.
  *
  * `loadModuleWithParser` builds on these primitives to provide the single
  * load/validation boundary shared by config, integration, codemod, and
@@ -16,6 +17,7 @@
  */
 
 import * as path from 'node:path';
+import {AsyncLocalStorage} from 'node:async_hooks';
 import {createRequire} from 'node:module';
 import {pathToFileURL} from 'node:url';
 import * as fs from 'node:fs';
@@ -56,6 +58,43 @@ function isCommonJsFile(file) {
   }
 }
 
+let loadsInFlight = 0;
+/** @type {typeof process.stdout.write | undefined} */
+let realStdoutWrite;
+/** Set in the async context of a module load, and only there. */
+const moduleLoad = new AsyncLocalStorage();
+
+/**
+ * Run a module load with the stdout writes made in its async context sent to
+ * stderr. Writes from any other context pass through, so the CLI's own output
+ * stays on stdout even while an abandoned load is still in flight. The gate
+ * is installed for the first overlapping load and removed after the last.
+ * @template T
+ * @param {() => Promise<T>} load
+ * @returns {Promise<T>}
+ */
+async function withStdoutOnStderr(load) {
+  if (loadsInFlight++ === 0) {
+    const write = process.stdout.write;
+    realStdoutWrite = write;
+    process.stdout.write = /** @type {any} */ (
+      function (/** @type {any} */ chunk, /** @type {any[]} */ ...rest) {
+        return moduleLoad.getStore()
+          ? process.stderr.write(chunk, ...rest)
+          : write.call(process.stdout, chunk, ...rest);
+      }
+    );
+  }
+  try {
+    return await moduleLoad.run(true, load);
+  } finally {
+    if (--loadsInFlight === 0 && realStdoutWrite) {
+      process.stdout.write = realStdoutWrite;
+      realStdoutWrite = undefined;
+    }
+  }
+}
+
 /**
  * Import a user-authored module. `.ts` is loaded via jiti; `.mjs`/`.js` use
  * native dynamic import for ordinary cached reads. A fresh `.ts` read uses a
@@ -64,12 +103,22 @@ function isCommonJsFile(file) {
  * nearest package.json `type` decides `.js`, matching Node's package scopes.
  * Normal loads retain module caching. `fresh` is an explicit migration-only
  * escape hatch for rereading files that a codemod changed during this process.
+ * Anything the module writes to stdout while it loads goes to stderr.
  *
  * @param {string} file absolute path
  * @param {{fresh?: boolean}} [options]
  * @returns {Promise<Record<string, unknown>>}
  */
 export async function importUserModule(file, {fresh = false} = {}) {
+  return await withStdoutOnStderr(() => importModule(file, fresh));
+}
+
+/**
+ * @param {string} file absolute path
+ * @param {boolean} fresh
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function importModule(file, fresh) {
   if (fresh && file.endsWith('.ts')) {
     return await createJiti(import.meta.url, {moduleCache: false}).import(file);
   }

package/foundation/fs/module-loader.stdout.test.mjs

@@ -0,0 +1,332 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A project module that prints while it loads must not reach stdout.
+ * Every `astryx.config.*` and integration manifest runs through
+ * `importUserModule`, so one stray `console.log` there used to corrupt every
+ * `--json` envelope. The loader cases run in a real Node process (vitest
+ * replaces `console`); the CLI cases spawn the real binary.
+ */
+
+import {afterEach, beforeEach, describe, expect, it} 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 {fileURLToPath, pathToFileURL} from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const LOADER_URL = pathToFileURL(path.join(HERE, 'module-loader.mjs')).href;
+const CLI = path.resolve(HERE, '..', '..', 'clients', 'cli', 'bin', 'astryx.mjs');
+
+const PRINTS =
+  "console.log('module log');\nprocess.stdout.write('module write\\n');\n";
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-module-stdout-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} rel @param {string} body @returns {string} */
+function write(rel, body) {
+  const file = path.join(tmpDir, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(file, body);
+  return file;
+}
+
+/**
+ * Run `body` as an ES module in a real Node process with `importUserModule`
+ * in scope.
+ * @param {string} body
+ */
+function runWithLoader(body) {
+  return spawnSync(
+    process.execPath,
+    [
+      '--input-type=module',
+      '-e',
+      `import {importUserModule} from ${JSON.stringify(LOADER_URL)};\n${body}`,
+    ],
+    {encoding: 'utf8', timeout: 60_000, stdio: ['ignore', 'pipe', 'pipe']},
+  );
+}
+
+describe('importUserModule keeps module output off stdout', () => {
+  it.each([
+    ['.mjs', 'mod.mjs', false, `${PRINTS}export default {answer: 42};\n`],
+    ['ESM .js', 'esm/mod.js', false, `${PRINTS}export default {answer: 42};\n`],
+    [
+      '.ts',
+      'mod.ts',
+      false,
+      `${PRINTS}const answer: number = 42;\nexport default {answer};\n`,
+    ],
+    ['fresh .mjs', 'mod.mjs', true, `${PRINTS}export default {answer: 42};\n`],
+    [
+      'fresh .ts',
+      'mod.ts',
+      true,
+      `${PRINTS}const answer: number = 42;\nexport default {answer};\n`,
+    ],
+    [
+      'fresh CommonJS .js',
+      'cjs/mod.js',
+      true,
+      `${PRINTS}module.exports = {answer: 42};\n`,
+    ],
+  ])('sends a printing %s module to stderr', (_label, rel, fresh, source) => {
+    write('esm/package.json', JSON.stringify({type: 'module'}));
+    write('cjs/package.json', JSON.stringify({type: 'commonjs'}));
+    const file = write(rel, source);
+
+    const r = runWithLoader(
+      `const before = process.stdout.write;
+const mod = await importUserModule(${JSON.stringify(file)}, {fresh: ${fresh}});
+process.stdout.write(JSON.stringify({answer: mod.default?.answer, restored: process.stdout.write === before}));`,
+    );
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual({answer: 42, restored: true});
+    expect(r.stderr).toContain('module log');
+    expect(r.stderr).toContain('module write');
+  });
+
+  it('keeps stdout redirected until the last overlapping load settles', () => {
+    const first = write(
+      'first.mjs',
+      "await new Promise(resolve => setTimeout(resolve, 20));\nprocess.stdout.write('first write\\n');\nexport default 'first';\n",
+    );
+    const second = write(
+      'second.mjs',
+      "await new Promise(resolve => setTimeout(resolve, 150));\nprocess.stdout.write('second write\\n');\nexport default 'second';\n",
+    );
+
+    const r = runWithLoader(
+      `const before = process.stdout.write;
+const mods = await Promise.all([
+  importUserModule(${JSON.stringify(first)}),
+  importUserModule(${JSON.stringify(second)}),
+]);
+process.stdout.write(JSON.stringify({loaded: mods.map(mod => mod.default), restored: process.stdout.write === before}));`,
+    );
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual({
+      loaded: ['first', 'second'],
+      restored: true,
+    });
+    expect(r.stderr).toContain('first write');
+    expect(r.stderr).toContain('second write');
+  });
+
+  it('leaves the caller on stdout while an abandoned load is still in flight', () => {
+    const slow = write(
+      'slow.mjs',
+      "await new Promise(resolve => setTimeout(resolve, 150));\nprocess.stdout.write('slow write\\n');\nexport default 'slow';\n",
+    );
+
+    const r = runWithLoader(
+      `const before = process.stdout.write;
+const slow = importUserModule(${JSON.stringify(slow)});
+const sibling = new Promise((_, reject) => setTimeout(() => reject(new Error('sibling failed')), 10));
+try {
+  await Promise.all([slow, sibling]);
+} catch (error) {
+  process.stdout.write('caught: ' + error.message + '\\n');
+}
+await slow;
+process.stdout.write('restored: ' + (process.stdout.write === before) + '\\n');`,
+    );
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.stdout).toBe('caught: sibling failed\nrestored: true\n');
+    expect(r.stderr).toContain('slow write');
+  });
+
+  it('restores stdout when the module throws', () => {
+    const file = write(
+      'boom.mjs',
+      "process.stdout.write('boom write\\n');\nthrow new Error('boom');\n",
+    );
+
+    const r = runWithLoader(
+      `const before = process.stdout.write;
+let message = null;
+try {
+  await importUserModule(${JSON.stringify(file)});
+} catch (error) {
+  message = error.message;
+}
+process.stdout.write(JSON.stringify({message, restored: process.stdout.write === before}));`,
+    );
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual({message: 'boom', restored: true});
+    expect(r.stderr).toContain('boom write');
+  });
+});
+
+/** @param {string[]} args */
+function runCli(args) {
+  return spawnSync(process.execPath, [CLI, ...args], {
+    cwd: tmpDir,
+    encoding: 'utf8',
+    timeout: 60_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {...process.env, FORCE_COLOR: '0', CI: ''},
+  });
+}
+
+/**
+ * Stdout must be exactly one envelope and the module's output must be on
+ * stderr.
+ * @param {ReturnType<typeof runCli>} r
+ * @param {string} printed
+ */
+function expectOneEnvelope(r, printed) {
+  expect(r.signal).toBeNull();
+  const envelope = JSON.parse(r.stdout);
+  expect(envelope.apiVersion).toBe(1);
+  expect(r.stdout).not.toContain(printed);
+  expect(r.stderr).toContain(printed);
+  return envelope;
+}
+
+/** A declared dependency that ships a printing manifest and one component. */
+function installNoisyIntegration() {
+  write(
+    'package.json',
+    JSON.stringify({
+      name: 'consumer',
+      private: true,
+      type: 'module',
+      dependencies: {'@acme/noisy': '1.0.0'},
+    }),
+  );
+  write(
+    'node_modules/@acme/noisy/package.json',
+    JSON.stringify({name: '@acme/noisy', version: '1.0.0'}),
+  );
+  write(
+    'node_modules/@acme/noisy/astryx.integration.mjs',
+    "console.log('manifest log');\nexport default {components: './components'};\n",
+  );
+  write(
+    'node_modules/@acme/noisy/components/Widget.doc.mjs',
+    "export const docs = {name: 'Widget', usage: {description: 'A widget'}};\n",
+  );
+  write(
+    'node_modules/@acme/noisy/components/Widget.tsx',
+    'export function Widget() { return null; }\n',
+  );
+}
+
+describe('--json stdout stays one envelope when project modules print', () => {
+  it.each([
+    [['--json', 'docs'], 'docs.list'],
+    [['--json', 'template', '--list'], 'template.list'],
+    [['--json', 'doctor'], 'doctor'],
+  ])('astryx.config.mjs: %j', (args, type) => {
+    write(
+      'package.json',
+      JSON.stringify({name: 'consumer', private: true, type: 'module'}),
+    );
+    write(
+      'astryx.config.mjs',
+      "console.log('config log');\nprocess.stdout.write('config write\\n');\nexport default {integrations: []};\n",
+    );
+
+    const r = runCli(args);
+
+    expect(expectOneEnvelope(r, 'config log').type).toBe(type);
+    expect(r.stderr).toContain('config write');
+  });
+
+  it('astryx.config.ts through jiti', () => {
+    write(
+      'package.json',
+      JSON.stringify({name: 'consumer', private: true, type: 'module'}),
+    );
+    write(
+      'astryx.config.ts',
+      "console.log('config log');\nconst config: {integrations: string[]} = {integrations: []};\nexport default config;\n",
+    );
+
+    const r = runCli(['--json', 'template', '--list']);
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(expectOneEnvelope(r, 'config log').type).toBe('template.list');
+  });
+
+  it('CommonJS astryx.config.js reloaded fresh by upgrade', () => {
+    write('package.json', JSON.stringify({name: 'consumer', private: true}));
+    write(
+      'node_modules/@astryxdesign/core/package.json',
+      JSON.stringify({name: '@astryxdesign/core', version: '0.6.3'}),
+    );
+    write(
+      'astryx.config.js',
+      "console.log('config log');\nmodule.exports = {integrations: []};\n",
+    );
+
+    const r = runCli(['--json', 'upgrade', '--from', '0.5.0']);
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(expectOneEnvelope(r, 'config log').type).toBe('upgrade.run');
+  });
+
+  it('an error envelope while sibling project loads are still in flight', () => {
+    // search rejects on a Core without sources before its parallel loads settle.
+    write(
+      'package.json',
+      JSON.stringify({name: 'consumer', private: true, type: 'module'}),
+    );
+    write(
+      'node_modules/@astryxdesign/core/package.json',
+      JSON.stringify({name: '@astryxdesign/core', version: '0.6.3'}),
+    );
+    write(
+      'astryx.config.mjs',
+      "console.log('config log');\nexport default {integrations: []};\n",
+    );
+
+    const r = runCli(['--json', 'search', 'button']);
+
+    expect(r.status).toBe(1);
+    expect(typeof expectOneEnvelope(r, 'config log').code).toBe('string');
+  });
+
+  it('an autolinked integration manifest', () => {
+    installNoisyIntegration();
+
+    const r = runCli(['--json', 'docs']);
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(expectOneEnvelope(r, 'manifest log').type).toBe('docs.list');
+  });
+
+  it.each([
+    [['--json', 'integration', 'add', 'doc', 'deploying'], 'integration.add'],
+    [['--json', 'doctor', 'integration', 'validate'], 'integration.validate'],
+  ])('the local package manifest: %j', (args, type) => {
+    write(
+      'package.json',
+      JSON.stringify({name: 'acme-kit', version: '1.0.0', type: 'module'}),
+    );
+    write(
+      'astryx.integration.mjs',
+      "console.log('manifest log');\nexport default {};\n",
+    );
+
+    const r = runCli(args);
+
+    expect(r.status, r.stderr).toBe(0);
+    expect(expectOneEnvelope(r, 'manifest log').type).toBe(type);
+  });
+});

package/foundation/fs/path-safety.d.mts

@@ -7,7 +7,7 @@
  *
  *   - Absolute paths (e.g. `/tmp/x`) — re-rooted by `path.join` is silent;
  *     better to fail loudly. Pass `{allowAbsolute: true}` to opt in.
- *   - Paths that escape via `..` segments.
+ *   - Paths that escape via `..` segments or a symlink, dangling or not.
  *
  * Returns the resolved absolute path on success.
  *
@@ -19,7 +19,8 @@
  * @param {string} [options.label='path'] - Human-readable name of the arg
  *   being checked (used in error messages, e.g. 'output directory').
  * @returns {string} Absolute resolved path inside `rootDir`.
- * @throws {PathSafetyError}
+ * @throws {PathSafetyError} An escape carries the registered
+ *   `ERR_PATH_TRAVERSAL`, so it reaches an envelope correctly even uncaught.
  */
 export function assertWithin(targetPath: string, rootDir: string, options?: {
     allowAbsolute?: boolean | undefined;