@sabaiway/agent-workflow-kit 1.6.0 → 1.7.0

package/tools/detect-backends.test.mjs

@@ -12,6 +12,7 @@ import {
   detectBackend,
   detectBackends,
   formatReport,
+  guideFor,
   KNOWN_BACKENDS,
 } from './detect-backends.mjs';
 
@@ -340,3 +341,104 @@ describe('detectBackends — live shape on this machine', () => {
     }
   });
 });
+
+// ── guideFor (axis-aware manual steps) ────────────────────────────────────────
+
+// A status with all axes satisfied; override per-case to drive each axis independently.
+const okStatus = (over = {}) => ({
+  name: 'codex-cli-bridge',
+  manifestState: 'ok',
+  manifestReason: 'ok',
+  skillDir: '/skills/codex-cli-bridge',
+  cli: { bin: 'codex', state: 'present', path: '/usr/bin/codex' },
+  credentials: { state: 'present', path: '/home/u/.codex/auth.json' },
+  wrappers: [{ name: 'codex-exec', state: 'present' }, { name: 'codex-review', state: 'present' }],
+  readiness: 'ready',
+  setupHint: { local: 'setup/README.md', url: 'https://example.test/codex' },
+  ...over,
+});
+
+describe('guideFor — axis-aware manual steps', () => {
+  it('returns [] when the backend is ready', () => {
+    assert.deepEqual(guideFor(okStatus()), []);
+  });
+
+  it('returns [] for a degraded backend (wrappers are the linker\'s job, not a manual step)', () => {
+    const s = okStatus({ readiness: 'degraded', wrappers: [{ name: 'codex-exec', state: 'missing' }] });
+    assert.deepEqual(guideFor(s), []);
+  });
+
+  it('returns BOTH cli and credentials steps when both are missing (multiple simultaneous)', () => {
+    const s = okStatus({
+      cli: { bin: 'codex', state: 'missing', path: null },
+      credentials: { state: 'missing', path: '/c/auth.json' },
+    });
+    const needs = guideFor(s).map((g) => g.need);
+    assert.deepEqual(needs, ['cli', 'credentials']);
+  });
+
+  it('credentials step carries the canonical loginCmd + verifyCmd from the registry', () => {
+    const s = okStatus({ credentials: { state: 'missing', path: '/c/auth.json' } });
+    const step = guideFor(s).find((g) => g.need === 'credentials');
+    assert.match(step.hint, /codex login/);
+    assert.match(step.hint, /codex login status/);
+  });
+
+  it('cli step references the setup README (no duplicated install channels)', () => {
+    const s = okStatus({ cli: { bin: 'codex', state: 'missing', path: null } });
+    const step = guideFor(s).find((g) => g.need === 'cli');
+    assert.match(step.hint, /codex-cli-bridge\/setup\/README\.md/);
+  });
+
+  it('manifestState not-installed → a placeable bundled-skill hint (+ any cli/creds owed)', () => {
+    const s = okStatus({ manifestState: 'not-installed', skillDir: null });
+    const skill = guideFor(s).find((g) => g.need === 'skill');
+    assert.ok(skill, 'expected a skill step');
+    assert.match(skill.hint, /bundled bridge skill/);
+    assert.match(skill.hint, /setup codex-cli-bridge/);
+  });
+
+  it('manifestState foreign/stub → a STOP hint (never auto-overwritten)', () => {
+    for (const state of ['foreign', 'stub', 'invalid-manifest', 'unsupported-schema', 'unknown']) {
+      const skill = guideFor(okStatus({ manifestState: state })).find((g) => g.need === 'skill');
+      assert.ok(skill, `expected a skill step for ${state}`);
+      assert.match(skill.hint, /STOP/);
+      assert.match(skill.hint, new RegExp(state.replace(/[-]/g, '\\$&')));
+    }
+  });
+
+  it('every step is {need, hint} with a non-empty hint', () => {
+    const s = okStatus({
+      manifestState: 'not-installed',
+      skillDir: null,
+      cli: { bin: 'codex', state: 'missing', path: null },
+      credentials: { state: 'missing', path: '/c/auth.json' },
+    });
+    const steps = guideFor(s);
+    assert.equal(steps.length, 3);
+    for (const step of steps) {
+      assert.ok(typeof step.need === 'string' && step.need.length > 0);
+      assert.ok(typeof step.hint === 'string' && step.hint.length > 0);
+    }
+  });
+});
+
+describe('KNOWN_BACKENDS — each entry exposes a guide', () => {
+  it('guide carries setupRef + loginCmd + verifyCmd (non-empty strings)', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      assert.ok(entry.guide, `${entry.name} missing guide`);
+      for (const key of ['setupRef', 'loginCmd', 'verifyCmd']) {
+        assert.ok(
+          typeof entry.guide[key] === 'string' && entry.guide[key].length > 0,
+          `${entry.name}.guide.${key} must be a non-empty string`,
+        );
+      }
+    }
+  });
+
+  it('guide.setupRef points at a real file in the repo', () => {
+    for (const entry of KNOWN_BACKENDS) {
+      assert.ok(existsSync(join(REPO, entry.guide.setupRef)), `${entry.guide.setupRef} (${entry.name})`);
+    }
+  });
+});

package/tools/fs-safe.mjs

@@ -0,0 +1,129 @@
+// fs-safe.mjs — pure, dependency-injectable filesystem-safety primitives shared by the kit installer
+// (bin/install.mjs) and the backend linker (tools/setup-backends.mjs). Importing this module has NO
+// side effects: it runs nothing. Every fs primitive is injectable via `deps.*` so the guards are
+// unit-testable without touching the real filesystem; the defaults are Node's SYNC fs (matching the
+// tools/ detector style). Dependency-free, Node >= 18.
+//
+// Three primitives:
+//   assertContainedRealPath — refuse to write through/into a symlink, or to a dest outside a root.
+//   copyTreeRefresh         — recursive copy that OVERWRITES regular files (refresh), SKIPS a symlink
+//                             whose dest already exists (additive), and guards every dest component.
+//   linkManaged             — create/keep ONLY a symlink we own; STOP (typed ManagedLinkConflict) on
+//                             a foreign symlink or a non-symlink dest; refuse a symlinked source.
+
+import {
+  lstatSync, existsSync, mkdirSync, readdirSync, copyFileSync, readlinkSync, symlinkSync,
+} from 'node:fs';
+import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
+
+// A managed-link conflict is a distinct, expected outcome (a foreign/non-symlink dest we refuse to
+// clobber) — callers branch on `.code`. Modelled as a tagged Error (no classes — §agent_rules 2.3),
+// the same `Object.assign(new Error(), { code })` idiom the codebase already uses for typed errors.
+export const MANAGED_LINK_CONFLICT = 'MANAGED_LINK_CONFLICT';
+const managedLinkConflict = (message, fields = {}) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), {
+    name: 'ManagedLinkConflict',
+    code: MANAGED_LINK_CONFLICT,
+    ...fields,
+  });
+
+// lstat without following symlinks; null when absent. A non-ENOENT fs error (EACCES/EIO) must NOT
+// fail open (be read as "not a symlink") — it propagates so the guard can never be bypassed.
+const lstatNoFollow = (path, lstat) => {
+  try {
+    return lstat(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// Symlink-traversal guard: refuse to write *through* any symlink at or above `dest` within `root`
+// (root / intermediate dir / leaf, including a dangling one), or to a dest outside `root`.
+export const assertContainedRealPath = (root, dest, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const ln = (p) => lstatNoFollow(p, lstat);
+  const rel = relative(root, dest);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
+  }
+  if (ln(root)?.isSymbolicLink()) {
+    throw new Error(`[agent-workflow-kit] refusing to install into a symlinked target dir: ${root}`);
+  }
+  const walk = (acc, part) => {
+    const cur = join(acc, part);
+    if (ln(cur)?.isSymbolicLink()) {
+      throw new Error(`[agent-workflow-kit] refusing to write through a symlink at ${cur} (would escape ${root}).`);
+    }
+    return cur;
+  };
+  rel.split(sep).filter(Boolean).reduce(walk, root);
+};
+
+// Recursive refresh copy. Guards every dest via assertContainedRealPath first, then:
+//   symlink src   → additive: skip if dest exists, else mirror the link target.
+//   directory src → mkdir -p dest, recurse.
+//   regular file  → mkdir -p parent, copyFile (OVERWRITE = refresh to the bundled version).
+export const copyTreeRefresh = (src, dest, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const exists = deps.exists ?? existsSync;
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
+  const readdir = deps.readdir ?? readdirSync;
+  const copyFile = deps.copyFile ?? copyFileSync;
+  const readlink = deps.readlink ?? readlinkSync;
+  const symlink = deps.symlink ?? symlinkSync;
+
+  assertContainedRealPath(root, dest, deps);
+  const stat = lstat(src);
+  if (stat.isSymbolicLink()) {
+    if (exists(dest)) return;
+    symlink(readlink(src), dest);
+  } else if (stat.isDirectory()) {
+    mkdir(dest);
+    for (const entry of readdir(src)) {
+      copyTreeRefresh(join(src, entry), join(dest, entry), root, deps);
+    }
+  } else {
+    mkdir(dirname(dest));
+    copyFile(src, dest);
+  }
+};
+
+// Create/keep ONLY a symlink we own. `src` must be a real regular file (never a symlink); `dest`
+// must stay within `root`. Outcomes: 'linked' (created), 'noop' (already points at our src), or a
+// thrown ManagedLinkConflict (a non-symlink, or a symlink pointing elsewhere — never clobbered).
+export const linkManaged = (src, dest, root, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }));
+  const readlink = deps.readlink ?? readlinkSync;
+  const symlink = deps.symlink ?? symlinkSync;
+
+  const srcStat = lstat(src);
+  if (srcStat.isSymbolicLink()) {
+    throw new Error(`[agent-workflow-kit] refusing to link a symlinked source (would escape our ownership): ${src}`);
+  }
+  if (!srcStat.isFile()) {
+    throw new Error(`[agent-workflow-kit] link source is not a regular file: ${src}`);
+  }
+
+  // Guard the PARENT chain (root + intermediate dirs), not the leaf: managing the leaf symlink is
+  // exactly this function's job, so it inspects the leaf itself rather than letting the traversal
+  // guard reject every symlinked dest. `dirname(dest)` within `root` ⇒ `dest` within `root` too.
+  assertContainedRealPath(root, dirname(dest), deps);
+  const existing = lstatNoFollow(dest, lstat);
+  if (existing === null) {
+    mkdir(dirname(dest));
+    symlink(src, dest);
+    return 'linked';
+  }
+  if (!existing.isSymbolicLink()) {
+    throw managedLinkConflict(`refusing to replace a non-symlink at ${dest}`, { dest, found: 'file' });
+  }
+  const target = readlink(dest);
+  const resolvedTarget = isAbsolute(target) ? target : resolve(dirname(dest), target);
+  if (resolvedTarget === resolve(src)) return 'noop';
+  throw managedLinkConflict(
+    `refusing to replace a foreign symlink at ${dest} (points at ${target}, not our ${src})`,
+    { dest, expected: src, found: target },
+  );
+};

package/tools/fs-safe.test.mjs

@@ -0,0 +1,200 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync, rmSync, mkdirSync, writeFileSync, symlinkSync, readlinkSync, readFileSync, existsSync, lstatSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  assertContainedRealPath,
+  copyTreeRefresh,
+  linkManaged,
+  MANAGED_LINK_CONFLICT,
+} from './fs-safe.mjs';
+
+// All three primitives are SYNC and operate on real tmp dirs here (the symlink behaviours are
+// fiddly enough that real fs is the honest test). The out-of-root case needs no fs at all.
+let dir;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'awf-fs-safe-'));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// ── assertContainedRealPath ───────────────────────────────────────────────────
+
+describe('assertContainedRealPath', () => {
+  it('rejects a dest outside the root (no fs needed — the relative check fires first)', () => {
+    assert.throws(() => assertContainedRealPath('/root', '/root/../etc/passwd'), /outside/);
+    assert.throws(() => assertContainedRealPath('/root', '/etc/passwd'), /outside/);
+  });
+
+  it('rejects writing INTO a symlinked root', () => {
+    const real = join(dir, 'real');
+    const root = join(dir, 'root');
+    mkdirSync(real);
+    symlinkSync(real, root);
+    assert.throws(() => assertContainedRealPath(root, join(root, 'x')), /symlink/i);
+  });
+
+  it('rejects writing THROUGH a symlinked intermediate component', () => {
+    const root = join(dir, 'root');
+    const elsewhere = join(dir, 'elsewhere');
+    mkdirSync(root);
+    mkdirSync(elsewhere);
+    symlinkSync(elsewhere, join(root, 'sub'));
+    assert.throws(() => assertContainedRealPath(root, join(root, 'sub', 'file')), /symlink/i);
+  });
+
+  it('rejects a symlinked leaf dest', () => {
+    const root = join(dir, 'root');
+    mkdirSync(root);
+    symlinkSync(join(dir, 'target'), join(root, 'leaf'));
+    assert.throws(() => assertContainedRealPath(root, join(root, 'leaf')), /symlink/i);
+  });
+
+  it('accepts a clean dest within the root', () => {
+    const root = join(dir, 'root');
+    mkdirSync(root);
+    assert.doesNotThrow(() => assertContainedRealPath(root, join(root, 'a', 'b', 'c')));
+  });
+
+  it('lstat is injectable (closes the install.mjs injectability gap)', () => {
+    let seen = 0;
+    const lstat = (p) => { seen += 1; return { isSymbolicLink: () => false }; };
+    assert.doesNotThrow(() => assertContainedRealPath('/root', '/root/a/b', { lstat }));
+    assert.ok(seen > 0, 'the injected lstat was used');
+  });
+});
+
+// ── copyTreeRefresh ───────────────────────────────────────────────────────────
+
+describe('copyTreeRefresh', () => {
+  it('overwrites an existing regular file (refresh)', () => {
+    const root = join(dir, 'dest');
+    mkdirSync(root);
+    const src = join(dir, 'src.txt');
+    const dest = join(root, 'f.txt');
+    writeFileSync(src, 'new');
+    writeFileSync(dest, 'old');
+    copyTreeRefresh(src, dest, root);
+    assert.equal(readFileSync(dest, 'utf8'), 'new');
+  });
+
+  it('copies a nested directory tree', () => {
+    const src = join(dir, 'src');
+    const root = join(dir, 'dest');
+    mkdirSync(join(src, 'a'), { recursive: true });
+    writeFileSync(join(src, 'top.txt'), 'T');
+    writeFileSync(join(src, 'a', 'deep.txt'), 'D');
+    mkdirSync(root);
+    copyTreeRefresh(src, join(root, 'src'), root);
+    assert.equal(readFileSync(join(root, 'src', 'top.txt'), 'utf8'), 'T');
+    assert.equal(readFileSync(join(root, 'src', 'a', 'deep.txt'), 'utf8'), 'D');
+  });
+
+  it('skips a symlink whose dest already exists (additive — never replace)', () => {
+    const root = join(dir, 'dest');
+    mkdirSync(root);
+    const linkSrc = join(dir, 'link');
+    symlinkSync(join(dir, 'whatever'), linkSrc); // src IS a symlink
+    const dest = join(root, 'f');
+    writeFileSync(dest, 'keep');
+    copyTreeRefresh(linkSrc, dest, root);
+    assert.equal(readFileSync(dest, 'utf8'), 'keep'); // untouched
+    assert.equal(lstatSync(dest).isSymbolicLink(), false);
+  });
+
+  it('STOPs on a symlinked dest component (never writes through it)', () => {
+    const root = join(dir, 'root');
+    const elsewhere = join(dir, 'elsewhere');
+    mkdirSync(root);
+    mkdirSync(elsewhere);
+    symlinkSync(elsewhere, join(root, 'sub'));
+    const src = join(dir, 's.txt');
+    writeFileSync(src, 'x');
+    assert.throws(() => copyTreeRefresh(src, join(root, 'sub', 'f.txt'), root), /symlink/i);
+    assert.equal(existsSync(join(elsewhere, 'f.txt')), false); // no leak
+  });
+});
+
+// ── linkManaged ───────────────────────────────────────────────────────────────
+
+describe('linkManaged', () => {
+  const makeSrc = () => {
+    const src = join(dir, 'src.sh');
+    writeFileSync(src, '#!/bin/sh\n');
+    return src;
+  };
+
+  it('creates a symlink when the dest is absent', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    const result = linkManaged(src, dest, root);
+    assert.equal(result, 'linked');
+    assert.equal(lstatSync(dest).isSymbolicLink(), true);
+    assert.equal(readlinkSync(dest), src);
+  });
+
+  it('creates the parent bindir if absent (mkdir -p)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'base');
+    mkdirSync(root);
+    const dest = join(root, 'newbin', 'cmd');
+    linkManaged(src, dest, root);
+    assert.equal(readlinkSync(dest), src);
+  });
+
+  it('is idempotent — a second call is a no-op', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    linkManaged(src, dest, root);
+    const again = linkManaged(src, dest, root);
+    assert.equal(again, 'noop');
+    assert.equal(readlinkSync(dest), src);
+  });
+
+  it('STOPs on a non-symlink dest (typed ManagedLinkConflict)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    writeFileSync(dest, 'someone-elses-file');
+    assert.throws(() => linkManaged(src, dest, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readFileSync(dest, 'utf8'), 'someone-elses-file'); // untouched
+  });
+
+  it('STOPs on a foreign symlink (points elsewhere)', () => {
+    const src = makeSrc();
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    const dest = join(root, 'cmd');
+    const foreign = join(dir, 'foreign.sh');
+    writeFileSync(foreign, '#!/bin/sh\n');
+    symlinkSync(foreign, dest);
+    assert.throws(() => linkManaged(src, dest, root), (err) => err.code === MANAGED_LINK_CONFLICT);
+    assert.equal(readlinkSync(dest), foreign); // untouched
+  });
+
+  it('refuses a symlinked source (never links through a symlink)', () => {
+    const realSrc = makeSrc();
+    const linkSrc = join(dir, 'link.sh');
+    symlinkSync(realSrc, linkSrc);
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    assert.throws(() => linkManaged(linkSrc, join(root, 'cmd'), root), /symlink/i);
+  });
+
+  it('refuses a non-regular-file source (e.g. a directory)', () => {
+    const srcDir = join(dir, 'src-dir');
+    mkdirSync(srcDir);
+    const root = join(dir, 'bin');
+    mkdirSync(root);
+    assert.throws(() => linkManaged(srcDir, join(root, 'cmd'), root), /regular file/i);
+  });
+});