@astryxdesign/cli 0.6.3-canary.ebaebc4 → 0.6.3-canary.ee13359

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);
+  });
 });

package/foundation/fs/publish-file-hardlink-unavailable.test.mjs

@@ -1,107 +1,142 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Optional integration proof for filesystems that reject hard links.
- * Set ASTRYX_HARDLINK_UNAVAILABLE_TEST_ROOT to a writable directory on such a
- * filesystem to exercise the real fallback end to end.
+ * @file Integration proof for filesystems that reject hard links.
+ *
+ * A module mock makes `fs.linkSync` fail the way those filesystems do (EPERM,
+ * or EXDEV across devices), so `applyWrites` publishes through the
+ * exclusive-copy fallback on every run. Private tests use injected seams, not
+ * environment variables (AST-017 FR14, DEC-5); the last case holds the
+ * publish-file module and its proofs to that.
  */
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
-import * as fs from 'node:fs';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as path from 'node:path';
-import {applyWrites} from '../../api/integration/add-helpers.mjs';
-
-const testRoot = process.env.ASTRYX_HARDLINK_UNAVAILABLE_TEST_ROOT ?? null;
-
-describe.skipIf(!testRoot)(
-  'hard-link-unavailable filesystem integration proof',
-  () => {
-    let testDir;
-
-    beforeEach(() => {
-      testDir = fs.mkdtempSync(path.join(testRoot, '.astryx-publish-proof-'));
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import jscodeshift from 'jscodeshift';
+
+vi.mock('node:fs', async importOriginal => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    linkSync: vi.fn(() => {
+      throw Object.assign(new Error('EPERM: operation not permitted, link'), {code: 'EPERM'});
+    }),
+    copyFileSync: vi.fn(actual.copyFileSync),
+  };
+});
+
+const {applyWrites} = await import('../../api/integration/add-helpers.mjs');
+const fs = await import('node:fs');
+
+describe.each(['EPERM', 'EXDEV'])('hard links fail with %s', code => {
+  let testDir;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(fs.linkSync).mockImplementation(() => {
+      throw Object.assign(new Error(`${code}: cannot link`), {code});
     });
-
-    afterEach(() => {
-      fs.rmSync(testDir, {recursive: true, force: true});
-    });
-
-    it('confirms the configured filesystem rejects hard links', () => {
-      const source = path.join(testDir, '.tmp-source');
-      const destination = path.join(testDir, '.tmp-destination');
-      fs.writeFileSync(source, 'link-test');
-
-      expect(() => fs.linkSync(source, destination)).toThrow(
-        expect.objectContaining({code: expect.stringMatching(/^(EPERM|EXDEV)$/)}),
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), '.astryx-publish-proof-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, {recursive: true, force: true});
+  });
+
+  it('applyWrites creates files through the exclusive-copy fallback', () => {
+    const plans = [
+      {
+        path: path.join(testDir, 'MyComponent.tsx'),
+        contents: '// MyComponent\nexport default function MyComponent() {}\n',
+        createOnly: true,
+      },
+      {
+        path: path.join(testDir, 'MyComponent.test.tsx'),
+        contents: '// test\nimport MyComponent from "./MyComponent";\n',
+        createOnly: true,
+      },
+    ];
+
+    const rollback = applyWrites(plans);
+    expect(typeof rollback).toBe('function');
+    expect(fs.readFileSync(plans[0].path, 'utf-8')).toContain('MyComponent');
+    expect(fs.readFileSync(plans[1].path, 'utf-8')).toContain('test');
+    expect(fs.linkSync).toHaveBeenCalledTimes(plans.length);
+    for (const plan of plans) {
+      expect(fs.copyFileSync).toHaveBeenCalledWith(
+        expect.any(String),
+        plan.path,
+        fs.constants.COPYFILE_EXCL,
       );
-    });
+    }
+  });
 
-    it('applyWrites creates files through the fallback', () => {
-      const plans = [
-        {
-          path: path.join(testDir, 'MyComponent.tsx'),
-          contents: '// MyComponent\nexport default function MyComponent() {}\n',
-          createOnly: true,
-        },
-        {
-          path: path.join(testDir, 'MyComponent.test.tsx'),
-          contents: '// test\nimport MyComponent from "./MyComponent";\n',
-          createOnly: true,
-        },
-      ];
-
-      const rollback = applyWrites(plans);
-      expect(typeof rollback).toBe('function');
-      expect(fs.readFileSync(plans[0].path, 'utf-8')).toContain('MyComponent');
-      expect(fs.readFileSync(plans[1].path, 'utf-8')).toContain('test');
-    });
-
-    it('applyWrites preserves no-clobber behavior', () => {
-      const target = path.join(testDir, 'existing.tsx');
-      fs.writeFileSync(target, '// original\n');
-
-      expect(() =>
-        applyWrites([
-          {
-            path: target,
-            contents: '// replacement\n',
-            createOnly: true,
-          },
-        ]),
-      ).toThrow(/overwrite|exists/i);
-      expect(fs.readFileSync(target, 'utf-8')).toBe('// original\n');
-    });
+  it('applyWrites preserves no-clobber behavior', () => {
+    const target = path.join(testDir, 'existing.tsx');
+    fs.writeFileSync(target, '// original\n');
 
-    it('applyWrites rolls back partial publication', () => {
-      const good = path.join(testDir, 'good.tsx');
-      const bad = path.join(testDir, 'bad.tsx');
-      fs.writeFileSync(bad, '// preexisting\n');
-
-      expect(() =>
-        applyWrites([
-          {path: good, contents: '// good file\n', createOnly: true},
-          {path: bad, contents: '// replacement\n', createOnly: true},
-        ]),
-      ).toThrow();
-      expect(fs.existsSync(good)).toBe(false);
-      expect(fs.readFileSync(bad, 'utf-8')).toBe('// preexisting\n');
-    });
-
-    it('applyWrites keeps compare-and-swap replacement behavior', () => {
-      const target = path.join(testDir, 'config.json');
-      const original = '{"version": 1}\n';
-      fs.writeFileSync(target, original);
-
-      const rollback = applyWrites([
+    expect(() =>
+      applyWrites([
         {
           path: target,
-          contents: '{"version": 2}\n',
-          createOnly: false,
-          expectedOriginal: Buffer.from(original),
+          contents: '// replacement\n',
+          createOnly: true,
         },
-      ]);
-      expect(typeof rollback).toBe('function');
-      expect(fs.readFileSync(target, 'utf-8')).toBe('{"version": 2}\n');
-    });
-  },
-);
+      ]),
+    ).toThrow(/overwrite|exists/i);
+    expect(fs.readFileSync(target, 'utf-8')).toBe('// original\n');
+  });
+
+  it('applyWrites rolls back partial publication', () => {
+    const good = path.join(testDir, 'good.tsx');
+    const bad = path.join(testDir, 'bad.tsx');
+    fs.writeFileSync(bad, '// preexisting\n');
+
+    expect(() =>
+      applyWrites([
+        {path: good, contents: '// good file\n', createOnly: true},
+        {path: bad, contents: '// replacement\n', createOnly: true},
+      ]),
+    ).toThrow();
+    expect(fs.existsSync(good)).toBe(false);
+    expect(fs.readFileSync(bad, 'utf-8')).toBe('// preexisting\n');
+  });
+
+  it('applyWrites keeps compare-and-swap replacement behavior', () => {
+    const target = path.join(testDir, 'config.json');
+    const original = '{"version": 1}\n';
+    fs.writeFileSync(target, original);
+
+    const rollback = applyWrites([
+      {
+        path: target,
+        contents: '{"version": 2}\n',
+        createOnly: false,
+        expectedOriginal: Buffer.from(original),
+      },
+    ]);
+    expect(typeof rollback).toBe('function');
+    expect(fs.readFileSync(target, 'utf-8')).toBe('{"version": 2}\n');
+  });
+});
+
+describe('private test seams', () => {
+  it('no publish-file module or proof reads process.env', () => {
+    const self = fileURLToPath(import.meta.url);
+    const dir = path.dirname(self);
+    const files = fs.readdirSync(dir).filter(name => /^publish-file.*\.mjs$/.test(name));
+    const j = jscodeshift.withParser('babylon');
+    const reads = files.flatMap(name =>
+      j(fs.readFileSync(path.join(dir, name), 'utf8'))
+        .find(j.MemberExpression, {object: {name: 'process'}})
+        .filter(p => (p.node.computed ? p.node.property.value : p.node.property.name) === 'env')
+        .nodes()
+        .map(node => `${name}:${node.loc?.start.line}`),
+    );
+
+    expect(files).toEqual(expect.arrayContaining(['publish-file.mjs', path.basename(self)]));
+    expect(reads).toEqual([]);
+  });
+});

package/foundation/integrations/autolink.d.mts

@@ -35,6 +35,28 @@ export function resolveInstalledPackageDir(name: string, fromDir: string): {
     packageDir: string;
     hostDir: string;
 } | null;
+/**
+ * @typedef {object} AutolinkCandidate
+ * @property {string} spec
+ * @property {string} field
+ * @property {string} packageDir
+ * @property {string} hostDir
+ * @property {boolean} [repeat] the directory is already loaded or already a
+ *   candidate under another dependency key; it is not loaded again
+ */
+/**
+ * Every declared dependency that ships exactly one root manifest, in
+ * declaration order, including the ones whose directory is already loaded or
+ * already a candidate (`repeat`), so a caller can account for each of them.
+ *
+ * @param {string} projectDir directory holding the project's package.json
+ * @param {{exclude?: Iterable<string>}} [options] `exclude` — package
+ *   directories already loaded (from config); matched through symlinks
+ * @returns {AutolinkCandidate[]}
+ */
+export function scanAutolinkCandidates(projectDir: string, { exclude }?: {
+    exclude?: Iterable<string>;
+}): AutolinkCandidate[];
 /**
  * Declared dependencies that ship an integration manifest and are not already
  * loaded, in declaration order.
@@ -50,7 +72,7 @@ export function resolveInstalledPackageDir(name: string, fromDir: string): {
  *   directories already loaded (from config); matched through symlinks
  * @returns {Array<{spec: string, field: string, packageDir: string, hostDir: string}>}
  */
-export function findAutolinkCandidates(projectDir: string, { exclude }?: {
+export function findAutolinkCandidates(projectDir: string, options?: {
     exclude?: Iterable<string>;
 }): Array<{
     spec: string;
@@ -58,6 +80,24 @@ export function findAutolinkCandidates(projectDir: string, { exclude }?: {
     packageDir: string;
     hostDir: string;
 }>;
+/**
+ * Load every autolink candidate, each in isolation, as provider candidates for
+ * {@link resolveProviders}. Nothing is filtered here: a candidate whose load
+ * throws or whose manifest fails comes back with its error, and a repeated
+ * directory comes back unloaded, so the resolver records each one.
+ *
+ * @param {object} options
+ * @param {string} options.projectDir directory holding the project's package.json
+ * @param {import('./integrations.mjs').LoadedIntegration[]} [options.loaded]
+ *   integrations already loaded from config
+ * @param {boolean} [options.fresh]
+ * @returns {Promise<import('./provider-resolution.mjs').ProviderCandidate[]>}
+ */
+export function loadAutolinkCandidates({ projectDir, loaded, fresh, }: {
+    projectDir: string;
+    loaded?: import("./integrations.mjs").LoadedIntegration[] | undefined;
+    fresh?: boolean | undefined;
+}): Promise<import("./provider-resolution.mjs").ProviderCandidate[]>;
 /**
  * Load every declared dependency that ships an integration manifest and is not
  * already loaded from config.
@@ -72,6 +112,12 @@ export function findAutolinkCandidates(projectDir: string, { exclude }?: {
  * consuming project can neither fix nor silence, and which
  * `astryx doctor integration validate <package>` reports on demand.
  *
+ * One package reached twice (an alias beside the package it aliases, at the
+ * same version) loads once. The same name at another version is kept, so the
+ * provider pass reports it instead of dropping it. Project.load does not call
+ * this; it hands {@link loadAutolinkCandidates} to the resolver, whose ledger
+ * records every candidate dropped here.
+ *
  * @param {object} options
  * @param {string} options.projectDir directory holding the project's package.json
  * @param {import('./integrations.mjs').LoadedIntegration[]} [options.loaded]
@@ -94,3 +140,14 @@ export function autolinkIntegrations({ projectDir, loaded, fresh, }: {
  * @type {readonly string[]}
  */
 export const DEPENDENCY_FIELDS: readonly string[];
+export type AutolinkCandidate = {
+    spec: string;
+    field: string;
+    packageDir: string;
+    hostDir: string;
+    /**
+     * the directory is already loaded or already a
+     * candidate under another dependency key; it is not loaded again
+     */
+    repeat?: boolean | undefined;
+};