@vibe-agent-toolkit/utils 0.2.0-rc.10 → 0.2.0-rc.12

package/eslint/rules/no-literal-test-timeout.cjs

@@ -0,0 +1,214 @@
+/**
+ * ESLint rule: no-literal-test-timeout
+ *
+ * Flags a per-test, per-suite or per-hook timeout written as a number:
+ * `it(name, fn, 60_000)`, `beforeAll(fn, 3_600_000)`, `it(name, { timeout: 30_000 }, fn)`.
+ * A test runner's tier config scales its default to the platform — this repo's
+ * integration tier allows 15 minutes per test on Windows and 1 on Unix — and a
+ * literal at the call site replaces that with one number for every machine. So
+ * the literal that is generous on a fast runner is the timeout on a slow one: a
+ * `60_000` that was 1× the Unix default was 1/15 of the Windows one, and failed
+ * there on runner speed alone, with no code change.
+ *
+ * A multiple of the default (`inject('tierTestTimeout') * 60`) fails the other
+ * way: it scales an hour-sized Unix budget by the Windows factor too — 15 hours —
+ * so a hang burns the CI job's whole allowance and names no test.
+ *
+ * The allowed shapes: omit it (the tier default applies), pass the tier's own
+ * value (`inject('tierTestTimeout')`, `vitest.shared.ts`), or ask for a budget
+ * over it with `atLeastTierTimeout(inject('tierTestTimeout'), 3_600_000)` from
+ * `@vibe-agent-toolkit/utils/testing` — the default is the floor and the budget
+ * a ceiling over it. A number is accepted ONLY as that helper's budget; its first
+ * argument (the floor) is walked like any other timeout.
+ *
+ * A literal is found anywhere in the timeout expression — arithmetic, either arm
+ * of a conditional, another call's arguments, a cast or parentheses — and behind
+ * a same-file `const`. A parameter, an import, a member read or a call result
+ * with no literal argument is accepted.
+ *
+ * ⚠️ STILL BLIND (syntax-only rule): a literal behind an IMPORTED constant, a
+ * `let`, an object property, or an options object held in a `const`. There is
+ * deliberately no escape-hatch comment: a hang guard that must stay short is a
+ * property of the code under test, and belongs in that code's own timeout (a
+ * spawn's `timeout`, an `AbortSignal`), not in the runner's wall clock.
+ *
+ * Not in `recommended`: the remedy names a value the adopter's runner config
+ * must provide, which this pack cannot supply.
+ *
+ * @example
+ * // BAD — one number for every machine
+ * it('populates the corpus', async () => { ... }, 60_000);
+ *
+ * // GOOD — the tier default
+ * it('populates the corpus', async () => { ... });
+ *
+ * // GOOD — a measured budget, never below this machine's allowance
+ * beforeAll(async () => { ... }, atLeastTierTimeout(inject('tierHookTimeout'), 3_600_000));
+ */
+
+'use strict';
+
+/** Runner globals whose call takes a timeout. */
+const TIMED_ROOTS = new Set(['it', 'test', 'describe', 'suite']);
+const HOOK_ROOTS = new Set(['beforeAll', 'afterAll', 'beforeEach', 'afterEach']);
+
+/** Members that return a test function after taking a table or a condition. */
+const FACTORY_MEMBERS = new Set(['each', 'for', 'skipIf', 'runIf']);
+
+/** Members that ARE a test function. */
+const MODIFIER_MEMBERS = new Set(['concurrent', 'sequential', 'only', 'skip', 'fails', 'todo', 'shuffle']);
+
+/** Wrappers that change a value's type or grouping, not its value. */
+const TRANSPARENT = new Set(['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'ChainExpression']);
+
+function unwrap(node) {
+  let current = node;
+  while (current && TRANSPARENT.has(current.type)) current = current.expression;
+  return current;
+}
+
+/**
+ * The root runner name a callee calls as a test function, or null.
+ *
+ * `it`, `it.concurrent`, `it.skipIf(c)`, `it.each(t)`, `it.each\`…\`` all qualify; `it.each`
+ * itself (the table call) does not, because its arguments are not a timeout.
+ */
+function testFunctionRoot(callee) {
+  const node = unwrap(callee);
+  if (!node) return null;
+  if (node.type === 'Identifier') return TIMED_ROOTS.has(node.name) || HOOK_ROOTS.has(node.name) ? node.name : null;
+  if (node.type === 'MemberExpression' && !node.computed && node.property.type === 'Identifier'
+    && MODIFIER_MEMBERS.has(node.property.name)) {
+    return testFunctionRoot(node.object);
+  }
+  if (node.type === 'CallExpression' || node.type === 'TaggedTemplateExpression') {
+    const factory = unwrap(node.type === 'CallExpression' ? node.callee : node.tag);
+    if (factory?.type === 'MemberExpression' && !factory.computed
+      && factory.property.type === 'Identifier' && FACTORY_MEMBERS.has(factory.property.name)) {
+      return testFunctionRoot(factory.object);
+    }
+  }
+  return null;
+}
+
+/** The `const` initializer an identifier names in this file, or null. */
+function constInitializer(sourceCode, identifier) {
+  let scope = sourceCode.getScope(identifier);
+  while (scope) {
+    const variable = scope.set.get(identifier.name);
+    if (variable) {
+      const definition = variable.defs[0];
+      if (definition?.type === 'Variable' && definition.parent.kind === 'const'
+        && definition.node.id.type === 'Identifier') {
+        return definition.node.init;
+      }
+      return null;
+    }
+    scope = scope.upper;
+  }
+  return null;
+}
+
+/** The one call whose numeric argument is accepted: its budget, over the tier's floor. */
+const BUDGET_HELPER = 'atLeastTierTimeout';
+
+function isBudgetHelper(callee) {
+  const node = unwrap(callee);
+  if (!node) return false;
+  if (node.type === 'Identifier') return node.name === BUDGET_HELPER;
+  return node.type === 'MemberExpression' && !node.computed && node.property.type === 'Identifier'
+    && node.property.name === BUDGET_HELPER;
+}
+
+/**
+ * The first numeric literal a timeout expression decides its value with, or null.
+ *
+ * Walks arithmetic, both arms of a conditional (not its test), call arguments and
+ * same-file `const` initializers. The budget helper contributes only its first
+ * argument: its second is the one place a number is the contract.
+ */
+function findLiteral(sourceCode, node, seen) {
+  const value = unwrap(node);
+  if (!value) return null;
+  switch (value.type) {
+    case 'Literal':
+      return typeof value.value === 'number' ? value : null;
+    case 'UnaryExpression':
+      return findLiteral(sourceCode, value.argument, seen);
+    case 'BinaryExpression':
+    case 'LogicalExpression':
+      return findLiteral(sourceCode, value.left, seen) ?? findLiteral(sourceCode, value.right, seen);
+    case 'ConditionalExpression':
+      return findLiteral(sourceCode, value.consequent, seen) ?? findLiteral(sourceCode, value.alternate, seen);
+    case 'CallExpression': {
+      const walked = isBudgetHelper(value.callee) ? value.arguments.slice(0, 1) : value.arguments;
+      for (const argument of walked) {
+        const found = findLiteral(sourceCode, argument, seen);
+        if (found !== null) return found;
+      }
+      return null;
+    }
+    case 'Identifier': {
+      if (seen.has(value.name)) return null;
+      seen.add(value.name);
+      const init = constInitializer(sourceCode, value);
+      return init === null ? null : findLiteral(sourceCode, init, seen);
+    }
+    default:
+      // A function (the test body), a member read, a template: not a number decided here.
+      return null;
+  }
+}
+
+/** The literal a timeout argument carries — in itself, or in its `timeout` property. */
+function literalTimeoutIn(sourceCode, argument) {
+  const node = unwrap(argument);
+  if (!node) return null;
+  if (node.type !== 'ObjectExpression') return findLiteral(sourceCode, node, new Set());
+  for (const property of node.properties) {
+    if (property.type === 'Property' && !property.computed && property.key.type === 'Identifier'
+      && property.key.name === 'timeout') {
+      return findLiteral(sourceCode, property.value, new Set());
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow a numeric per-test or per-hook timeout — omit it, or pass a budget through ' +
+        'atLeastTierTimeout(tier, budget), so the platform-scaled default is the floor and the budget a ceiling',
+      category: 'Code and test hygiene',
+      bans: '`it(name, fn, 60_000)`, `beforeAll(fn, tier * 12)`, `{ timeout: isWin ? 900_000 : 60_000 }`',
+      useInstead: 'the tier default, or `atLeastTierTimeout(inject(\'tierTestTimeout\'), budget)`',
+      // Not recommended: the remedy names a value the adopter's runner config must provide.
+      recommended: false,
+    },
+    schema: [],
+    messages: {
+      literalTimeout:
+        'A number in a timeout replaces or scales the tier\'s platform-scaled default. Omit it, or write ' +
+        'atLeastTierTimeout(inject(\'tierTestTimeout\' | \'tierHookTimeout\'), budget).',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode;
+    return {
+      CallExpression(node) {
+        const root = testFunctionRoot(node.callee);
+        if (root === null) return;
+        // A hook's timeout is its second argument; a test's or suite's is any
+        // argument after the name (vitest takes options before or after the body).
+        const candidates = HOOK_ROOTS.has(root) ? node.arguments.slice(1, 2) : node.arguments.slice(1);
+        for (const argument of candidates) {
+          const literal = literalTimeoutIn(sourceCode, argument);
+          if (literal !== null) context.report({ node: literal, messageId: 'literalTimeout' });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-raw-signal-listener.cjs

@@ -0,0 +1,224 @@
+/**
+ * ESLint rule: no-raw-signal-listener
+ *
+ * Flags every way of adding — or removing — a listener for a SIGNAL on the process by hand. The
+ * event is a signal when it is a string literal (or template) naming one, or any event name that
+ * is not a literal at all (a loop variable over a signal list, a parameter). Caught shapes:
+ *
+ * - `process.on` / `once` / `addListener` / `prependListener` / `prependOnceListener` — and
+ *   `off` / `removeListener` / `removeAllListeners`, which can strip a guard (`removeAllListeners()`
+ *   with no event strips every one);
+ * - the same method reached as `process['on']`, through `globalThis.process` / `global.process`,
+ *   through a local alias (`const p = process`), through a `node:process` (or `process`) default
+ *   or namespace import, or as a named import of the method from it (`import { on } from
+ *   'node:process'`);
+ * - `once(process, <signal>)` / `on(process, <signal>)` — `node:events`' promise and iterator
+ *   forms, called bare or as a member (`events.once`, `EventEmitter.on`) — with any of the process
+ *   references above as the emitter.
+ *
+ * NOT caught: a process reference that only reaches the call through a function's parameter, an
+ * object property, or any value the rule cannot follow to its declaration in the same file.
+ *
+ * Why: a terminating-signal handler written by hand is the shape that leaked a clone and a lock.
+ * It removed itself on the first signal and started an asynchronous cleanup, so the second — a
+ * terminal Ctrl-C under a wrapper that forwards signals delivers two — met the default disposition
+ * and killed the process half-way through the cleanup. `handleTerminatingSignals` (on
+ * `@vibe-agent-toolkit/utils/process`) is the one installation: it swallows the duplicate that
+ * arrives with the first signal, composes with every other live guard, and dies of the signal. A
+ * removal by hand can strip that guard's listener out from under it.
+ *
+ * An event name that is not a literal is flagged because a signal list spread into a loop is how
+ * the second-commonest hand-written handler looks, and nothing at the call site says whether the
+ * variable holds a signal. Name the event literally when it is not one.
+ *
+ * Option `allow: string[]` — repo-relative paths of the files permitted to listen directly (the one
+ * file that implements the helper). Matched at a path-segment boundary via `exempt-path-matcher.cjs`.
+ *
+ * @example
+ * // BAD
+ * process.on('SIGINT', () => cleanup().then(() => process.exit(130)));
+ * for (const signal of TERMINATING_SIGNALS) process.on(signal, onSignal);
+ * await once(process, 'SIGTERM');
+ *
+ * // GOOD
+ * const guard = handleTerminatingSignals({ cleanup, fallbackExitCode: ExitCode.ERROR });
+ * // ...
+ * guard.release();
+ */
+
+'use strict';
+
+const { createExemptPathMatcher } = require('./exempt-path-matcher.cjs');
+
+const ADD_METHODS = new Set(['on', 'once', 'addListener', 'prependListener', 'prependOnceListener']);
+const REMOVE_METHODS = new Set(['off', 'removeListener', 'removeAllListeners']);
+/** `node:events`' static forms that take the emitter as their first argument. */
+const EVENTS_STATIC_METHODS = new Set(['on', 'once']);
+const PROCESS_MODULES = new Set(['process', 'node:process']);
+const GLOBAL_OBJECTS = new Set(['globalThis', 'global']);
+/** How many aliases deep a process reference is followed — `const a = process; const b = a;`. */
+const MAX_ALIAS_DEPTH = 8;
+
+/** The member name of `node` — `x.name` or `x['name']` — or null when it is not static. */
+function memberName(node) {
+  if (node.type !== 'MemberExpression') return null;
+  if (!node.computed && node.property.type === 'Identifier') return node.property.name;
+  if (node.computed && node.property.type === 'Literal' && typeof node.property.value === 'string') {
+    return node.property.value;
+  }
+  return null;
+}
+
+/** The variable `identifier` refers to, through the scope chain, or null for an unresolved global. */
+function resolveVariable(sourceCode, identifier) {
+  let scope = sourceCode.getScope(identifier);
+  while (scope) {
+    const variable = scope.set.get(identifier.name);
+    if (variable) return variable;
+    scope = scope.upper;
+  }
+  return null;
+}
+
+/** The import a variable is bound to: `{ module, imported }`, imported being 'default', '*' or a name. */
+function importBinding(variable) {
+  const def = variable?.defs?.[0];
+  if (def?.type !== 'ImportBinding') return null;
+  switch (def.node.type) {
+    case 'ImportNamespaceSpecifier':
+      return { module: def.parent?.source?.value, imported: '*' };
+    case 'ImportDefaultSpecifier':
+      return { module: def.parent?.source?.value, imported: 'default' };
+    case 'ImportSpecifier': {
+      const { imported } = def.node;
+      return { module: def.parent?.source?.value, imported: imported.type === 'Identifier' ? imported.name : imported.value };
+    }
+    // `import p = require('node:process')` — the module object itself.
+    case 'TSImportEqualsDeclaration':
+      return { module: def.node.moduleReference?.expression?.value, imported: 'default' };
+    default:
+      return null;
+  }
+}
+
+/** Whether `node` evaluates to the `process` object, as far as this file can tell. */
+function isProcessRef(sourceCode, node, depth = 0) {
+  if (depth > MAX_ALIAS_DEPTH) return false;
+  if (node.type === 'MemberExpression') {
+    return node.object.type === 'Identifier' && GLOBAL_OBJECTS.has(node.object.name) && memberName(node) === 'process';
+  }
+  if (node.type !== 'Identifier') return false;
+  const variable = resolveVariable(sourceCode, node);
+  if (variable === null || variable.defs.length === 0) return node.name === 'process';
+  const binding = importBinding(variable);
+  if (binding !== null) return PROCESS_MODULES.has(binding.module) && (binding.imported === 'default' || binding.imported === '*');
+  const def = variable.defs[0];
+  if (def.type !== 'Variable' || def.node.id.type !== 'Identifier' || def.node.init == null) return false;
+  return isProcessRef(sourceCode, def.node.init, depth + 1);
+}
+
+/** The process method `callee` names — `process.on`, `p['once']`, an imported `on` — or null. */
+function processMethod(sourceCode, callee) {
+  const name = memberName(callee);
+  if (name !== null) return isProcessRef(sourceCode, callee.object) ? name : null;
+  if (callee.type !== 'Identifier') return null;
+  const binding = importBinding(resolveVariable(sourceCode, callee));
+  return binding !== null && PROCESS_MODULES.has(binding.module) ? binding.imported : null;
+}
+
+/** The literal text of an event-name argument, or null when it is not literal. */
+function literalEventName(arg) {
+  if (arg.type === 'Literal' && typeof arg.value === 'string') return arg.value;
+  if (arg.type === 'TemplateLiteral' && arg.expressions.length === 0) return arg.quasis[0].value.cooked;
+  if (arg.type === 'TemplateLiteral') return arg.quasis[0].value.cooked.startsWith('SIG') ? 'SIG' : null;
+  return null;
+}
+
+/**
+ * What `node` does to a signal listener — `{ method, eventArg, removal }` — or null when it is
+ * not a listener call on the process at all.
+ */
+function listenerCall(sourceCode, node) {
+  const { callee } = node;
+  const method = processMethod(sourceCode, callee);
+  if (method !== null && (ADD_METHODS.has(method) || REMOVE_METHODS.has(method))) {
+    return { method, eventArg: node.arguments[0], removal: REMOVE_METHODS.has(method) };
+  }
+  const staticName = callee.type === 'Identifier' ? callee.name : memberName(callee);
+  const [emitter, eventArg] = node.arguments;
+  if (staticName !== null && EVENTS_STATIC_METHODS.has(staticName) && emitter !== undefined && isProcessRef(sourceCode, emitter)) {
+    return { method: staticName, eventArg, removal: false };
+  }
+  return null;
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow adding or removing a process listener for a signal (or for any event not named ' +
+        'literally) by hand — install a terminating-signal handler through handleTerminatingSignals',
+      category: 'Filesystem and process',
+      bans: '`process.on(<signal>, …)`, `process.off(<signal>, …)`, `once(process, <signal>)` and `process.on(<non-literal>, …)`',
+      useInstead: '`handleTerminatingSignals()`',
+      subpath: '/process',
+      // Not recommended: it names a helper an adopter may not use, and the one file allowed to
+      // listen directly is a fact about each repo's layout (the `allow` option).
+      recommended: false,
+      recommendedSeverity: 'error',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allow: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      signalListener:
+        'process.{{method}}(\'{{event}}\') installs a signal handler by hand. Use ' +
+        'handleTerminatingSignals from @vibe-agent-toolkit/utils/process: it swallows the ' +
+        'duplicate that arrives with the first signal, composes with every other guard, and dies ' +
+        'of the signal.',
+      computedEvent:
+        'process.{{method}}(<non-literal>) may be a signal handler installed by hand. Name the ' +
+        'event literally, or — for a signal — use handleTerminatingSignals from ' +
+        '@vibe-agent-toolkit/utils/process.',
+      signalRemoval:
+        'process.{{method}}({{event}}) removes a signal listener by hand, which can strip a ' +
+        'handleTerminatingSignals guard out from under it. Release the guard instead.',
+    },
+  },
+
+  create(context) {
+    const allow = context.options?.[0]?.allow ?? [];
+    const filename = context.filename ?? context.getFilename();
+    if (createExemptPathMatcher(allow)(filename)) return {};
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    return {
+      CallExpression(node) {
+        const call = listenerCall(sourceCode, node);
+        if (call === null) return;
+        const { method, eventArg, removal } = call;
+        if (eventArg === undefined) {
+          // `removeAllListeners()` strips every listener, every guard's included.
+          if (method === 'removeAllListeners') context.report({ node, messageId: 'signalRemoval', data: { method, event: '' } });
+          return;
+        }
+        const event = literalEventName(eventArg);
+        if (event !== null && !event.startsWith('SIG')) return;
+        if (removal) {
+          context.report({ node, messageId: 'signalRemoval', data: { method, event: event === null ? '<non-literal>' : `'${event}'` } });
+        } else if (event === null) {
+          context.report({ node, messageId: 'computedEvent', data: { method } });
+        } else {
+          context.report({ node, messageId: 'signalListener', data: { method, event } });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-stdout-outside-writer.cjs

@@ -0,0 +1,135 @@
+/**
+ * ESLint rule: no-stdout-outside-writer
+ *
+ * Under the configured `paths` (a CLI's command directory), stdout belongs to
+ * ONE writer. A command that writes its own bytes publishes a shape nothing
+ * validates, in a format it chose, beside an exit code it decided — which is
+ * how a CLI grows one document contract per verb. The writer validates the
+ * document against its registered schema before a byte leaves and derives the
+ * exit code from what it wrote; this rule makes it the only way out.
+ *
+ * Reported under `paths` (test files excepted):
+ *
+ * - `process.stdout.write(…)`;
+ * - `console.log|info|debug|dir|table(…)` — the console methods that write
+ *   stdout (`console.error` / `console.warn` are stderr, the human channel,
+ *   and are not this rule's business);
+ * - a call to a stdout-writing helper BY NAME — `writeStdoutSync`,
+ *   `writeAllSync`, bare or as a member — and one HANDED ON as an argument
+ *   (`render(result, writeStdoutSync)`), which writes stdout just the
+ *   same. A rule that saw only the primitives was blind to every command that
+ *   writes through a helper.
+ *
+ * Option `allowFiles: string[]` — repo-relative files whose stdout is not a
+ * document (a protocol leaf). Asserted both ways: a listed file with no
+ * violation left is itself an error (`staleAllow`), so the list never holds a
+ * dead entry.
+ *
+ * @example
+ * // BAD — a shape nothing validates, beside a code decided here
+ * writeStdoutSync(yaml.stringify(result));
+ * process.stdout.write(`${JSON.stringify(result)}\n`);
+ *
+ * // GOOD — validated against the registry, exit derived from what was written
+ * endWithReport('okf validate', report, format);
+ */
+
+'use strict';
+
+const { createExemptDirectoryMatcher, createExemptPathMatcher, isTestFile } = require('./exempt-path-matcher.cjs');
+
+/** The `console` methods that write stdout. */
+const STDOUT_CONSOLE_METHODS = new Set(['log', 'info', 'debug', 'dir', 'table']);
+
+/** Helpers that write stdout, recognised by name wherever they are imported from. */
+const STDOUT_HELPERS = new Set([
+  'writeStdoutSync',
+  'writeAllSync',
+]);
+
+/** Whether `node` is `<object>.<property>` (non-computed) with an identifier object. */
+function isMember(node, object, property) {
+  return (
+    node.type === 'MemberExpression' &&
+    !node.computed &&
+    node.property.type === 'Identifier' &&
+    (property === undefined || node.property.name === property) &&
+    (object === undefined || (node.object.type === 'Identifier' && node.object.name === object))
+  );
+}
+
+/** Whether `callee` is `process.stdout.write`. */
+function isProcessStdoutWrite(callee) {
+  return isMember(callee, undefined, 'write') && isMember(callee.object, 'process', 'stdout');
+}
+
+/** The called function's own name — `f(…)` or `x.f(…)` — or null. */
+function calleeName(callee) {
+  if (callee.type === 'Identifier') return callee.name;
+  if (isMember(callee)) return callee.property.name;
+  return null;
+}
+
+/** Whether a call writes stdout by one of the routes this rule reports. */
+function writesStdout(callee) {
+  if (isProcessStdoutWrite(callee)) return true;
+  if (isMember(callee, 'console') && STDOUT_CONSOLE_METHODS.has(callee.property.name)) return true;
+  return STDOUT_HELPERS.has(calleeName(callee));
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow writing stdout under a command directory except through the one document writer — ' +
+        'process.stdout.write, console.log and the stdout helpers publish a shape nothing validates',
+      // A position on one CLI's architecture: it names that CLI's command
+      // directory and its writer, which no adopter's layout shares.
+      recommended: false,
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          paths: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+          allowFiles: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        },
+        required: ['paths', 'allowFiles'],
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      stdoutOutsideWriter:
+        'stdout is written by the document writer only (endWithReport / endWithRefusal / ' +
+        'writeExternalDocument / writeArtifact). A command that writes its own bytes publishes a ' +
+        'shape nothing validates, beside an exit code it decided.',
+      staleAllow:
+        'This file is listed in no-stdout-outside-writer allowFiles but writes stdout by no ' +
+        'reported route any more. Remove it from the list — the ratchet only shrinks.',
+    },
+  },
+
+  create(context) {
+    const options = context.options?.[0] ?? { paths: [], allowFiles: [] };
+    const filename = context.filename ?? context.getFilename();
+    if (isTestFile(filename) || !createExemptDirectoryMatcher(options.paths)(filename)) {
+      return {};
+    }
+    const allowed = createExemptPathMatcher(options.allowFiles)(filename);
+    let violations = 0;
+
+    return {
+      CallExpression(node) {
+        const handedOn = node.arguments.filter((arg) => arg.type === 'Identifier' && STDOUT_HELPERS.has(arg.name));
+        const sites = writesStdout(node.callee) ? [node, ...handedOn] : handedOn;
+        violations += sites.length;
+        if (allowed) return;
+        for (const site of sites) context.report({ node: site, messageId: 'stdoutOutsideWriter' });
+      },
+      'Program:exit'(node) {
+        if (allowed && violations === 0) context.report({ node, messageId: 'staleAllow' });
+      },
+    };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.2.0-rc.10",
+  "version": "0.2.0-rc.12",
   "type": "module",
   "description": "Core utility functions shared across the vibe-agent-toolkit packages",
   "sideEffects": [
@@ -17,7 +17,7 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=22.16.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -66,6 +66,10 @@
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
     },
+    "./archive": {
+      "types": "./dist/archive.d.ts",
+      "import": "./dist/archive.js"
+    },
     "./asset": {
       "types": "./dist/asset.d.ts",
       "import": "./dist/asset.js"
@@ -93,14 +97,17 @@
     "build": "tsx ../dev-tools/src/tsc-clean-build.ts",
     "test:unit": "vitest run",
     "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:system": "vitest run --config vitest.system.config.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "clean": "rimraf --glob dist \"*.tsbuildinfo\" .tsc-staging"
   },
   "dependencies": {
     "@vibe-validate/git": "0.20.1",
+    "adm-zip": "^0.6.1",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.3",
+    "tar": "^7.5.7",
     "which": "^5.0.0",
     "yaml": "^2.9.0"
   },
@@ -113,6 +120,7 @@
     }
   },
   "devDependencies": {
+    "@types/adm-zip": "^0.5.8",
     "@types/which": "^3.0.4",
     "zod": "^3.25.0"
   },

package/dist/errors/errno.d.ts

@@ -1,51 +0,0 @@
-/**
- * Errno predicates — the two questions every catch site asks of an OS error,
- * answered by the `code` on the error or down its `cause` chain.
- *
- * ⚠️ This module imports NOTHING. It is the leaf that `fs-utils.ts`,
- * `path-utils.ts`, `dirent-kind.ts`, `path-containment.ts` and the rest of the
- * package share; it lived in `fs-utils.ts` until that put three of them in an
- * import cycle (`fs-utils → path-utils → fs-utils` and two more), and a leaf
- * is the one place a shared predicate cannot re-open one. (The cycle was once
- * blamed for a platform-dependent knip verdict on these two names; breaking it
- * changed nothing there — the cause was a missing knip entry, see
- * `docs/contributing/traps.md`, "A subpath module's re-exports flap by platform".)
- */
-/**
- * Whether `error` is the filesystem refusing a path rather than a bug.
- *
- * Deliberately NOT `error instanceof Error`: the point of every caller is to
- * degrade on a hostile tree, and a `TypeError` from a validator is not that.
- * Treating one as environmental turns a real defect into a warning about
- * whichever file it happened on — which makes a tool quietest exactly when it is
- * most wrong.
- *
- * Walks `cause`, because the errno is routinely re-wrapped on its way up. The CLI
- * config loader turns a read failure into `new Error('Failed to load config: …')`;
- * without following the chain the predicate answered "not a filesystem error" for
- * a plain `EACCES`, and an unreadable config aborted a whole `vat audit` run. Any
- * layer that adds context to an OS error defeats a `code`-only check, so the check
- * cannot be `code`-only.
- */
-export declare function isFilesystemAccessError(error: unknown): boolean;
-/**
- * Whether `error` means **there is nothing at this path** — `ENOENT`, or
- * `ENOTDIR` for a path whose component turned out to be a file — and nothing
- * else.
- *
- * This is the narrowing a `try { stat(p) } catch { return null }` is rewritten
- * to under the `no-blind-catch` lint rule: the sentinel stands for *absent*,
- * so only an absence may produce it; a refusal (`EACCES`, `EPERM`, `ELOOP`) or
- * a bug (`TypeError`) is rethrown and stays loud.
- *
- * ⚠️ Deliberately NOT {@link isFilesystemAccessError}. That predicate answers
- * "is this the environment's fault?" and to answer it groups `ENOENT` with
- * `EACCES` — the exact conflation that once turned an unreadable directory
- * into an empty one. The two questions have two predicates on purpose; see
- * also {@link listingFailure}, which makes the same split for `readdir`.
- *
- * Walks `cause` for the same reason its sibling does: the errno is routinely
- * re-wrapped on its way up.
- */
-export declare function isPathAbsentError(error: unknown): boolean;
-//# sourceMappingURL=errno.d.ts.map