@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.f04b501

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;

package/foundation/fs/path-safety.mjs

@@ -14,6 +14,7 @@
 
 import * as path from 'node:path';
 import * as fs from 'node:fs';
+import {ERROR_CODES} from '../response/error-codes.mjs';
 
 /**
  * Error thrown by path-safety guards. Carries a stable `code`
@@ -38,7 +39,7 @@ export class PathSafetyError extends Error {
  *
  *   - 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.
  *
@@ -50,7 +51,8 @@ export class PathSafetyError extends Error {
  * @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, rootDir, options = {}) {
   const {allowAbsolute = false, label = 'path'} = options;
@@ -83,42 +85,70 @@ export function assertWithin(targetPath, rootDir, options = {}) {
     throw new PathSafetyError(
       `Invalid ${label} "${targetPath}": resolves outside the project root ` +
         `(${absRoot}). Path traversal is not allowed.`,
-      'PATH_TRAVERSAL',
+      ERROR_CODES.ERR_PATH_TRAVERSAL,
     );
   }
 
   // path.resolve is purely lexical — it does NOT follow symlinks, so a symlink
   // INSIDE the root that points outside would pass the check above while the
-  // real write lands outside root. Canonicalize the deepest EXISTING ancestor
-  // (the target itself usually doesn't exist yet) and re-check against the
-  // realpath'd root. This closes the symlink-escape hole for every command that
-  // writes through this guard.
+  // real write lands outside root. Canonicalize both paths through every
+  // symlink, dangling ones included (a write through a dangling link creates
+  // its target), and re-check.
   try {
-    const realRoot = fs.realpathSync(absRoot);
-    let existing = resolved;
-    while (!fs.existsSync(existing)) {
-      const parent = path.dirname(existing);
-      if (parent === existing) break;
-      existing = parent;
-    }
-    const realExisting = fs.realpathSync(existing);
+    const realRoot = canonicalPath(absRoot);
+    const realTarget = canonicalPath(resolved);
     const realRootWithSep = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
-    if (realExisting !== realRoot && !realExisting.startsWith(realRootWithSep)) {
+    if (realTarget !== realRoot && !realTarget.startsWith(realRootWithSep)) {
       throw new PathSafetyError(
         `Invalid ${label} "${targetPath}": resolves outside the project root ` +
           `(${absRoot}) via a symlink. Path traversal is not allowed.`,
-        'PATH_TRAVERSAL',
+        ERROR_CODES.ERR_PATH_TRAVERSAL,
       );
     }
   } catch (err) {
     if (err instanceof PathSafetyError) throw err;
-    // realpath can fail if the root doesn't exist (ENOENT) or on a race; fall
-    // back to the lexical result already validated above rather than crash.
+    // A symlink loop, a permission error, or a race; fall back to the lexical
+    // result already validated above rather than crash.
   }
 
   return resolved;
 }
 
+/** Linux's MAXSYMLINKS; a longer chain is treated as a loop. */
+const MAX_SYMLINK_HOPS = 40;
+
+/**
+ * `target` with every symlink resolved, including a dangling one, which
+ * `fs.realpathSync` refuses. Components below the deepest existing entry are
+ * appended as given.
+ *
+ * @param {string} target absolute path
+ * @param {number} [hops] symlinks followed so far
+ * @returns {string}
+ * @throws when the chain exceeds {@link MAX_SYMLINK_HOPS} or `lstat` fails
+ *   for a reason other than a missing entry
+ */
+function canonicalPath(target, hops = 0) {
+  if (hops > MAX_SYMLINK_HOPS) throw new Error(`Too many symlinks: ${target}`);
+  let stat;
+  try {
+    stat = fs.lstatSync(target);
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+    const parent = path.dirname(target);
+    if (parent === target) return target;
+    return path.join(canonicalPath(parent, hops), path.basename(target));
+  }
+  try {
+    return fs.realpathSync(target);
+  } catch (err) {
+    if (!stat.isSymbolicLink()) throw err;
+  }
+  const link = fs.readlinkSync(target);
+  return canonicalPath(path.resolve(fs.realpathSync(path.dirname(target)), link), hops + 1);
+}
+
 /**
  * Validate a "name" argument (e.g. theme name, component name) that will
  * be embedded in a generated filename. Rejects names containing path

package/foundation/fs/path-safety.test.mjs

@@ -19,6 +19,19 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
+/**
+ * The code a guard rejected with, or 'accepted'.
+ * @param {() => unknown} fn
+ */
+function rejectionCode(fn) {
+  try {
+    fn();
+  } catch (err) {
+    return err instanceof PathSafetyError ? err.code : err;
+  }
+  return 'accepted';
+}
+
 describe('assertWithin', () => {
   it('accepts a relative path that stays inside root', () => {
     const result = assertWithin('subdir/file.txt', tmpDir);
@@ -38,6 +51,14 @@ describe('assertWithin', () => {
     expect(() => assertWithin('a/b/../../../c', tmpDir)).toThrow(PathSafetyError);
   });
 
+  it('reports an escape with the registered ERR_PATH_TRAVERSAL code', () => {
+    // An uncaught guard error reaches the JSON envelope with this code as-is.
+    expect(rejectionCode(() => assertWithin('../escaped', tmpDir))).toBe('ERR_PATH_TRAVERSAL');
+    expect(
+      rejectionCode(() => assertWithin('/etc/passwd', tmpDir, {allowAbsolute: true})),
+    ).toBe('ERR_PATH_TRAVERSAL');
+  });
+
   it('rejects absolute paths by default', () => {
     expect(() => assertWithin('/tmp/elsewhere', tmpDir)).toThrow(/absolute paths are not allowed/i);
   });
@@ -160,6 +181,7 @@ describe('assertWithin — symlink escape (realpath guard)', () => {
     // path.resolve is lexical and would pass this; the realpath check must catch it.
     expect(() => assertWithin('link/evil.txt', root)).toThrow(PathSafetyError);
     expect(() => assertWithin('link/evil.txt', root)).toThrow(/outside|symlink|traversal/i);
+    expect(rejectionCode(() => assertWithin('link/evil.txt', root))).toBe('ERR_PATH_TRAVERSAL');
   });
 
   it('still accepts a legit non-existent nested path inside root', () => {
@@ -169,4 +191,32 @@ describe('assertWithin — symlink escape (realpath guard)', () => {
   it('rejects a NUL byte in the path', () => {
     expect(() => assertWithin('a\u0000b', root)).toThrow(PathSafetyError);
   });
+
+  it('rejects a dangling symlink whose target is outside root', () => {
+    // A write through the link would create the missing target outside root.
+    fs.symlinkSync(path.join(outside, 'created.txt'), path.join(root, 'leaf'));
+    expect(rejectionCode(() => assertWithin('leaf', root))).toBe('ERR_PATH_TRAVERSAL');
+  });
+
+  it('rejects a path through a dangling directory symlink that points outside root', () => {
+    fs.symlinkSync(path.join(outside, 'missing-dir'), path.join(root, 'dir'));
+    expect(rejectionCode(() => assertWithin('dir/evil.txt', root))).toBe('ERR_PATH_TRAVERSAL');
+  });
+
+  it('follows a chain of links that ends in a dangling target outside root', () => {
+    fs.symlinkSync(path.join(outside, 'missing.txt'), path.join(root, 'second'));
+    fs.symlinkSync('second', path.join(root, 'first'));
+    expect(rejectionCode(() => assertWithin('first', root))).toBe('ERR_PATH_TRAVERSAL');
+  });
+
+  it('accepts a dangling symlink whose target stays inside root', () => {
+    fs.symlinkSync(path.join('sub', 'new.txt'), path.join(root, 'leaf'));
+    expect(assertWithin('leaf', root)).toBe(path.join(root, 'leaf'));
+  });
+
+  it('terminates on a symlink loop', () => {
+    fs.symlinkSync('loop', path.join(root, 'loop'));
+    const result = rejectionCode(() => assertWithin('loop', root));
+    expect(['accepted', 'ERR_PATH_TRAVERSAL']).toContain(result);
+  });
 });