@vibe-agent-toolkit/utils 0.2.0-rc.1 → 0.2.0-rc.11

package/dist/skill-test/transcript.d.ts

@@ -5,7 +5,10 @@
  *
  * The stream-json schema is informally documented and may shift between
  * Claude Code releases. This parser is intentionally tolerant of unknown
- * event kinds — anything we don't recognise is appended to `raw`.
+ * event kinds — an event whose `type` we do not recognise is simply not
+ * consumed. Tolerance stops at unknown SHAPES: a line that is not JSON at all is
+ * counted into {@link ParsedTranscript.malformedLineCount}, because that is data
+ * loss, not forward compatibility.
  *
  * Shape notes (empirically verified):
  * - `tool_use` content blocks carry `input.command` for Bash calls.
@@ -23,11 +26,40 @@ export interface ParsedTranscript {
         inputSummary: string;
     }>;
     errors: string[];
-    raw: string[];
+    /**
+     * How many non-empty lines failed `JSON.parse` and were therefore NOT consumed.
+     *
+     * This is the only thing that distinguishes "parsed fine, nothing found" from
+     * "we lost the evidence". A corrupted line drops its whole event — the tool call
+     * in it, and any contamination it proves — while every other line, including the
+     * terminal `result`, still parses. Every downstream "did this transcript decode?"
+     * test is an any-of over the populated fields, so the surviving `result` line on
+     * its own certifies the transcript as decoded and the loss goes unremarked.
+     *
+     * Non-zero means the scan that consumed this transcript ran on less than the
+     * whole transcript and its verdict must be reported as DEGRADED, never clean.
+     * Zero is a positive statement, not an absence: every line was accounted for.
+     */
+    malformedLineCount: number;
     toolUses: Array<{
         id: string | null;
         name: string;
         command?: string;
+        /**
+         * The FULL, unsummarized tool input.
+         *
+         * `inputSummary` beside it is truncated to 200 characters by
+         * {@link summarizeValue}, which is fine for an observation record a human
+         * skims and useless for anything that has to REASON about what the call did
+         * — a path 200 characters into a `Read` input simply is not there. The
+         * baseline-integrity detector walks tool inputs to decide whether the
+         * skill-absent arm reached the skill, so it needs the whole value; the
+         * summary stays for the consumers that only ever display it.
+         *
+         * `unknown` because the shape is per-tool and informally documented — every
+         * consumer narrows it itself rather than trusting a type we invented.
+         */
+        input: unknown;
         inputSummary: string;
         parentToolUseId: string | null;
     }>;
@@ -35,6 +67,13 @@ export interface ParsedTranscript {
         toolUseId: string | null;
         isError: boolean;
         contentSummary: string;
+        /**
+         * The FULL tool result, flattened to text. Same reason as `input` above:
+         * `contentSummary` is truncated to 200 characters, so scanning a tool RESULT
+         * for evidence (a file's contents echoed back, a grep hit line) cannot be
+         * done through it. Never truncated — the caller bounds what it keeps.
+         */
+        content: string;
     }>;
     result?: {
         subtype?: string;

package/dist/skill-test/transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/skill-test/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC,CAAC,CAAC;IACH,WAAW,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3F,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1F,WAAW,EAAE,OAAO,CAAC;CACtB;AA4HD,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CA4B9E;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,gBAAgB,EACxB,iBAAiB,EAAE,SAAS,MAAM,EAAE,GACnC,OAAO,CAOT"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/skill-test/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;;;;;;;;OAaG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;;;;;;;;;;;;;WAaG;QACH,KAAK,EAAE,OAAO,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;KAChC,CAAC,CAAC;IACH,WAAW,EAAE,KAAK,CAAC;QACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,OAAO,EAAE,OAAO,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB;;;;;WAKG;QACH,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1F,WAAW,EAAE,OAAO,CAAC;CACtB;AA+JD,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAiC9E;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,gBAAgB,EACxB,iBAAiB,EAAE,SAAS,MAAM,EAAE,GACnC,OAAO,CAOT"}

package/dist/skill-test/transcript.js

@@ -5,7 +5,10 @@
  *
  * The stream-json schema is informally documented and may shift between
  * Claude Code releases. This parser is intentionally tolerant of unknown
- * event kinds — anything we don't recognise is appended to `raw`.
+ * event kinds — an event whose `type` we do not recognise is simply not
+ * consumed. Tolerance stops at unknown SHAPES: a line that is not JSON at all is
+ * counted into {@link ParsedTranscript.malformedLineCount}, because that is data
+ * loss, not forward compatibility.
  *
  * Shape notes (empirically verified):
  * - `tool_use` content blocks carry `input.command` for Bash calls.
@@ -16,14 +19,48 @@
  * - The terminal `result` event carries `subtype`, `is_error`, `num_turns`,
  *   and `total_cost_usd`.
  */
+/**
+ * Every value these two see is a fragment of a `JSON.parse` result — plain
+ * data, no cycles, no BigInt, no `toJSON` — so `JSON.stringify` cannot fail on
+ * it, and neither wraps it in a catch. The one thing it CAN answer with is
+ * `undefined`, for an absent field (a `tool_use` with no `input`); that used
+ * to trip a `.length` inside a blind catch and surface as `<unserializable>`,
+ * a parser accident reported as a property of the event.
+ */
 function summarizeValue(value) {
-    try {
-        const json = JSON.stringify(value);
-        return json.length > 200 ? `${json.slice(0, 197)}...` : json;
-    }
-    catch {
-        return '<unserializable>';
+    const json = stringifyValue(value);
+    return json.length > 200 ? `${json.slice(0, 197)}...` : json;
+}
+function stringifyValue(value) {
+    return JSON.stringify(value) ?? '';
+}
+/**
+ * Flatten a `tool_result` `content` field to plain text, WITHOUT truncating.
+ *
+ * Three shapes occur in practice: a bare string (most Bash results), an array of
+ * content blocks (`{type:'text',text}` and friends), and — for a tool that
+ * returns structured data — an arbitrary object. The array case is the one that
+ * matters: `JSON.stringify` of it would bury the text behind escaped quotes, and
+ * a consumer scanning for a verbatim sentence would never find it.
+ */
+function contentToText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.map((block) => contentBlockToText(block)).join('\n');
+    if (value === undefined || value === null)
+        return '';
+    return stringifyValue(value);
+}
+function contentBlockToText(block) {
+    if (typeof block === 'string')
+        return block;
+    if (block !== null && typeof block === 'object') {
+        const { text } = block;
+        if (typeof text === 'string')
+            return text;
     }
+    return stringifyValue(block);
 }
 function extractCommand(input) {
     if (input !== null && typeof input === 'object' && typeof input.command === 'string') {
@@ -44,6 +81,7 @@ function consumeAssistantBlocks(blocks, parentToolUseId, out) {
                 id: typeof block.id === 'string' ? block.id : null,
                 name: block.name,
                 ...(command === undefined ? {} : { command }),
+                input: block.input,
                 inputSummary,
                 parentToolUseId,
             });
@@ -57,6 +95,7 @@ function consumeUserBlocks(blocks, out) {
                 toolUseId: typeof block.tool_use_id === 'string' ? block.tool_use_id : null,
                 isError: block.is_error === true,
                 contentSummary: summarizeValue(block.content),
+                content: contentToText(block.content),
             });
         }
     }
@@ -114,22 +153,28 @@ export function parseStreamJsonTranscript(streamText) {
         text: '',
         toolUseEvents: [],
         errors: [],
-        raw: [],
         toolUses: [],
         toolResults: [],
         rateLimited: false,
+        malformedLineCount: 0,
     };
     const lines = streamText.split('\n');
     for (const line of lines) {
         const trimmed = line.trim();
         if (trimmed.length === 0)
             continue;
-        out.raw.push(trimmed);
         let parsed;
         try {
             parsed = JSON.parse(trimmed);
         }
-        catch {
+        catch (error) {
+            // A line that is not JSON is counted, not thrown on, and never pushed
+            // into `errors`: `errors` reports what the AGENT hit, this reports what
+            // the PARSER lost. Conflating them would make a harness defect look like
+            // a run failure and vice versa. Only a parse failure is a lost line.
+            if (!(error instanceof SyntaxError))
+                throw error;
+            out.malformedLineCount += 1;
             continue;
         }
         applyEvent(parsed, out);

package/dist/skill-test/transcript.js.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/skill-test/transcript.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/skill-test/transcript.ts"],"names":[],"mappings":"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"}

package/dist/spawn-hardened.js

@@ -28,7 +28,6 @@ export function spawnHardened(command, args, options = {}) {
     // Windows shell path (.cmd/.bat/.ps1). Token selection is shared with the sync
     // `safeExecSync` path so the two cannot drift — see `resolveShellCommandToken`.
     const shellLine = buildWindowsShellLine(resolveShellCommandToken(command, resolved), args);
-    // eslint-disable-next-line sonarjs/os-command -- Windows DEP0190 workaround: command is a PATH-resolved bare name or an explicit path; args are per-arg shell-quoted via windowsShellQuote()
     return spawn(shellLine, { ...options, shell: true });
 }
 //# sourceMappingURL=spawn-hardened.js.map

package/dist/spawn-hardened.js.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-hardened.js","sourceRoot":"","sources":["../src/spawn-hardened.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAwC,MAAM,oBAAoB,CAAC;AAEjF,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,wBAAwB,EACxB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,IAAc,EACd,UAAwB,EAAE;IAE1B,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAErE,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,+EAA+E;IAC/E,gFAAgF;IAChF,MAAM,SAAS,GAAG,qBAAqB,CAAC,wBAAwB,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;IAC3F,6LAA6L;IAC7L,OAAO,KAAK,CAAC,SAAS,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"spawn-hardened.js","sourceRoot":"","sources":["../src/spawn-hardened.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAwC,MAAM,oBAAoB,CAAC;AAEjF,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,UAAU,EACV,wBAAwB,EACxB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,IAAc,EACd,UAAwB,EAAE;IAE1B,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAErE,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,+EAA+E;IAC/E,gFAAgF;IAChF,MAAM,SAAS,GAAG,qBAAqB,CAAC,wBAAwB,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;IAE3F,OAAO,KAAK,CAAC,SAAS,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACvD,CAAC"}

package/dist/stdio-blocking.js

@@ -10,23 +10,22 @@
 /**
  * Switch one stream's underlying handle into blocking mode.
  *
- * @returns `true` only if `setBlocking` was present AND completed without
- * throwing. Both failure modes are real: a handle can be absent (stdio replaced,
- * or a shape libuv does not wrap), and `setBlocking` can throw on a handle type
- * that does not support it.
+ * @returns `true` only if `setBlocking` was present AND reported success. Both
+ * failure modes are real: a handle can be absent (stdio replaced, or a shape
+ * libuv does not wrap), and libuv can refuse the switch for a handle type that
+ * does not support it. It reports that refusal as a negative errno RETURN VALUE
+ * — `LibuvStreamWrap::SetBlocking` hands back `uv_stream_set_blocking`'s int,
+ * and a Windows TTY answers `UV_EINVAL` — never as a throw. This used to sit in
+ * a `try` that read a throw as the failure and the return value as nothing, so
+ * a refused switch reported `true` and the debug line said truncation could
+ * not happen on a stream it could happen on. A throw from in here would be a
+ * bug in Node's internals, and stays loud.
  */
 function setStreamBlocking(stream) {
-    try {
-        const handle = stream._handle;
-        if (typeof handle?.setBlocking !== 'function')
-            return false;
-        handle.setBlocking(true);
-        return true;
-    }
-    catch {
-        // Best-effort: never let a startup nicety take down the process.
+    const handle = stream._handle;
+    if (typeof handle?.setBlocking !== 'function')
         return false;
-    }
+    return handle.setBlocking(true) === 0;
 }
 /**
  * Make stdout/stderr BLOCKING, so that `process.exit()` can never discard output.

package/dist/stdio-blocking.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdio-blocking.js","sourceRoot":"","sources":["../src/stdio-blocking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,MAA0B;IACpD,IAAI,CAAC;QACJ,MAAM,MAAM,GACX,MACA,CAAC,OAAO,CAAC;QACV,IAAI,OAAO,MAAM,EAAE,WAAW,KAAK,UAAU;YAAE,OAAO,KAAK,CAAC;QAC5D,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACR,iEAAiE;QACjE,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,iBAAiB;IAChC,OAAO;QACN,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC;QACzC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC;KACzC,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA2B;IAChE,MAAM,MAAM,GAAI,CAAC,QAAQ,EAAE,QAAQ,CAAW,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,4EAA4E,CAAC;IACrF,CAAC;IACD,OAAO,yBAAyB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,yBAAyB,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,yDAAyD,CAAC;AAC7L,CAAC"}
+{"version":3,"file":"stdio-blocking.js","sourceRoot":"","sources":["../src/stdio-blocking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;;;;;;;;;GAaG;AACH,SAAS,iBAAiB,CAAC,MAA0B;IACpD,MAAM,MAAM,GACX,MACA,CAAC,OAAO,CAAC;IACV,IAAI,OAAO,MAAM,EAAE,WAAW,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC5D,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,iBAAiB;IAChC,OAAO;QACN,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC;QACzC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,MAAM,CAAC;KACzC,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAA2B;IAChE,MAAM,MAAM,GAAI,CAAC,QAAQ,EAAE,QAAQ,CAAW,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,4EAA4E,CAAC;IACrF,CAAC;IACD,OAAO,yBAAyB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,yBAAyB,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,yDAAyD,CAAC;AAC7L,CAAC"}

package/dist/test-helpers.d.ts

@@ -1,118 +1,153 @@
+declare const symlinkCapabilityBrand: unique symbol;
 /**
- * Get isolated test output directory for current test run
- *
- * Creates a unique directory under `packages/{packageName}/.test-output/{testType}/{runId}`
- * where runId is `{timestamp}-{randomId}` to ensure isolation across parallel test runs.
- *
- * @param packageName - Name of package (e.g., 'rag-lancedb')
- * @param testType - Type of test ('unit', 'integration', 'system')
- * @param subdirs - Optional subdirectories to create within the test output directory
- * @returns Absolute path to the created directory
- *
- * @example
- * ```typescript
- * // Create isolated database directory for system tests
- * const dbPath = getTestOutputDir('rag-lancedb', 'system', 'databases', 'test-db');
- * // Result: packages/rag-lancedb/.test-output/system/20260105-143022-abc123/databases/test-db
- *
- * // Create temporary file directory for integration tests
- * const tempDir = getTestOutputDir('agent-skills', 'integration', 'temp-files');
- * // Result: packages/agent-skills/.test-output/integration/20260105-143022-def456/temp-files
- * ```
+ * Proof that this process can create filesystem symlinks.
+ *
+ * The only way to obtain one is {@link symlinkCapability}, and it exists at
+ * all only when a real probe already succeeded — so a function that requires
+ * this as a parameter cannot be reached by code that skipped the check. That
+ * is the point of branding it rather than passing a `boolean`: forgetting the
+ * check becomes a type error instead of a runtime `EPERM` on a machine you
+ * don't control.
  */
-export declare function getTestOutputDir(packageName: string, testType: 'unit' | 'integration' | 'system', ...subdirs: string[]): string;
+export type SymlinkCapability = {
+    readonly [symlinkCapabilityBrand]: true;
+};
 /**
- * Get the base test output directory for a package
- * Useful for cleanup operations that need to remove all test output
+ * Whether this PROCESS can create symlinks — probed once and memoized.
  *
- * @param packageName - Name of package (e.g., 'rag-lancedb')
- * @returns Absolute path to packages/{packageName}/.test-output
- *
- * @example
- * ```typescript
- * const baseDir = getTestOutputBase('rag-lancedb');
- * // Result: packages/rag-lancedb/.test-output
- * ```
+ * On Windows, `symlink()` needs either Developer Mode or
+ * `SeCreateSymbolicLinkPrivilege`. That privilege lives on the process's
+ * security token, not on any one directory: it cannot change between calls
+ * within a single run, so probing it once and reusing the result is a
+ * memoization, not a shortcut that risks a stale answer. (A filesystem that
+ * itself has no symlinks — some network shares, some FAT variants — answers
+ * `ENOTSUP` and is read as the same "no"; every fixture in this repo creates
+ * its roots under {@link normalizedTmpdir}, so it never arises here.)
+ *
+ * Because the answer is memoized for the whole process, what reads as "no"
+ * matters more than usual: a `null` here silently `skip()`s every symlink test
+ * for the rest of the run. So ONLY {@link SYMLINK_UNSUPPORTED_ERRNOS} is a
+ * no. A tmpdir that is unwritable or missing, or a bug, is not an answer about
+ * symlinks at all and stays loud rather than becoming a process-wide skip for
+ * a reason nothing reported.
+ *
+ * Fixtures that depend on symlinks must ask rather than assume — and, having
+ * asked, must SAY they skipped. A symlink case that silently no-ops reads as
+ * a passing test for a property nobody exercised.
+ *
+ * @returns A {@link SymlinkCapability} token when this process can create
+ *   symlinks, else `null`. Route the `null` case through vitest's `skip()`
+ *   rather than a plain `return`, so the skip is visible in the report.
  */
-export declare function getTestOutputBase(packageName: string): string;
+export declare function symlinkCapability(): SymlinkCapability | null;
 /**
- * Per-suite temp directory pattern (async version)
- * Creates a single temp directory for the entire test suite,
- * with subdirectories for each test. This is 3-5x faster on Windows
- * than creating a new mkdtemp for each test.
- *
- * @param prefix - Prefix for the suite temp directory name
- * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
- *
- * @example
- * ```typescript
- * const suite = setupAsyncTempDirSuite('my-test');
- *
- * describe('my tests', () => {
- *   beforeAll(suite.beforeAll);
- *   afterAll(suite.afterAll);
- *   beforeEach(suite.beforeEach);
+ * Create a symlink — the one sanctioned call site for `fs.symlinkSync` in
+ * test code. Requires a {@link SymlinkCapability}, which only
+ * {@link symlinkCapability} can mint, so a test cannot reach the real
+ * syscall without first proving (or explicitly bypassing via `skip()`) that
+ * this host supports it.
+ *
+ * @param _cap - Proof from {@link symlinkCapability} that this host can create symlinks
+ * @param target - The existing path the new link should point at
+ * @param path - Where to create the link
+ * @param type - Windows-only link-type hint (`'file'` \| `'dir'` \| `'junction'`); ignored on POSIX
+ */
+export declare function createSymlink(_cap: SymlinkCapability, target: string, path: string, type?: 'dir' | 'file' | 'junction'): void;
+/**
+ * The async counterpart of {@link createSymlink}, for fixtures already using
+ * `node:fs/promises`. Same capability requirement, same reasoning.
  *
- *   it('test 1', async () => {
- *     const tempDir = suite.getTempDir();
- *     // Use tempDir...
- *   });
- * });
- * ```
+ * @param _cap - Proof from {@link symlinkCapability} that this host can create symlinks
+ * @param target - The existing path the new link should point at
+ * @param path - Where to create the link
+ * @param type - Windows-only link-type hint (`'file'` \| `'dir'` \| `'junction'`); ignored on POSIX
  */
-export declare function setupAsyncTempDirSuite(prefix: string): {
-    beforeAll: () => Promise<void>;
-    afterAll: () => Promise<void>;
-    beforeEach: () => Promise<void>;
-    afterEach: () => Promise<void>;
-    getTempDir: () => string;
-};
+export declare function createSymlinkAsync(_cap: SymlinkCapability, target: string, path: string, type?: 'dir' | 'file' | 'junction'): Promise<void>;
 /**
- * Per-suite temp directory pattern (sync version)
- * Creates a single temp directory for the entire test suite,
- * with subdirectories for each test. This is 3-5x faster on Windows
- * than creating a new mkdtemp for each test.
+ * The variables git exports into a hook, which a fixture must clear before it
+ * can fabricate its own.
  *
- * @param prefix - Prefix for the suite temp directory name
- * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ * These are the ones git sets *for* you. Deliberately **not** the operator's own
+ * `GIT_CONFIG_COUNT`/`KEY_n`/`VALUE_n`/`GLOBAL`/`SYSTEM` channel — a test may be
+ * using that on purpose to point a clone at a local path, and clearing it sends
+ * the clone to the network instead.
+ */
+export declare const INHERITED_GIT_ENV: readonly ["GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CEILING_DIRECTORIES", "GIT_COMMON_DIR", "GIT_CONFIG_PARAMETERS", "GIT_DIR", "GIT_DISCOVERY_ACROSS_FILESYSTEM", "GIT_GRAFT_FILE", "GIT_INDEX_FILE", "GIT_INDEX_VERSION", "GIT_NAMESPACE", "GIT_NOTES_REF", "GIT_OBJECT_DIRECTORY", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_WORK_TREE"];
+/**
+ * Remove every inherited git redirection from `process.env`, and hand back the
+ * undo.
+ *
+ * A test that fabricates a hook environment has to start from a known-clean one,
+ * or it inherits whatever the *outer* runner exported and can no longer tell its
+ * own fixture apart from the ambient state — it then passes or fails for reasons
+ * it never set up. Restoring afterwards matters just as much: these are
+ * process-global, so a test that leaks `GIT_DIR` silently redirects every later
+ * test sharing the worker.
+ *
+ * ⚠️ **The key list is restated here on purpose, not by oversight.** Deriving it
+ * from `@vibe-validate/git`'s `stripGitEnv()` would be tidier, and it is exactly
+ * what this function did for one revision — but this module is the `./testing`
+ * subpath, which `subpath-purity.test.ts` pins as reaching **no third-party
+ * package at all** so it stays importable with zero dependencies installed. One
+ * import cost that property. The drift risk the derivation was avoiding is
+ * handled instead by {@link "../test/test-helpers-git-env.test".default}, which
+ * asserts this list equals what the shipped scrub removes.
+ *
+ * @returns A function restoring every variable to its prior value, putting back
+ *   "was not set" as unset rather than as an empty string
  *
  * @example
  * ```typescript
- * const suite = setupSyncTempDirSuite('my-test');
- *
- * describe('my tests', () => {
- *   beforeAll(suite.beforeAll);
- *   afterAll(suite.afterAll);
- *   beforeEach(suite.beforeEach);
- *
- *   it('test 1', () => {
- *     const tempDir = suite.getTempDir();
- *     // Use tempDir...
- *   });
- * });
+ * let restoreGitEnv: () => void;
+ * beforeEach(() => { restoreGitEnv = detachGitEnv(); });
+ * afterEach(() => { restoreGitEnv(); });
  * ```
  */
-export declare function setupSyncTempDirSuite(prefix: string): {
-    beforeAll: () => void;
-    afterAll: () => void;
-    beforeEach: () => void;
-    afterEach: () => void;
-    getTempDir: () => string;
-};
+export declare function detachGitEnv(): () => void;
 /**
- * Probe whether this host can create symbolic links inside `dir`.
- *
- * On Windows, `symlink()` needs either Developer Mode or
- * `SeCreateSymbolicLinkPrivilege`; CI agents frequently have neither. Fixtures
- * that depend on symlinks must therefore ask rather than assume — and, having
- * asked, must SAY they skipped. A symlink case that silently no-ops reads as a
- * passing test for a property nobody exercised.
- *
- * The probe creates and removes one link, because the privilege cannot be
- * inferred from `process.platform` alone.
- *
- * @param dir - An existing directory to probe in (the probe cleans up after itself)
- * @returns True when a symlink was created successfully
+ * The errno-shaped error a refused `fs` call throws: a message, the `code`,
+ * and the `syscall`, exactly as Node shapes one.
+ */
+export declare function errnoError(code: string, syscall: string, target: string): NodeJS.ErrnoException;
+/** The sync `node:fs` calls a refusal can be injected into. */
+export type RefusableSyncFsMethod = 'readdirSync' | 'readFileSync' | 'statSync' | 'lstatSync' | 'realpathSync' | 'renameSync' | 'rmSync' | 'unlinkSync';
+/** The `node:fs/promises` calls a refusal can be injected into. */
+export type RefusableAsyncFsMethod = 'readdir' | 'readFile' | 'stat' | 'lstat' | 'access';
+/**
+ * Make `fs[method]` throw `code` for exactly `targetPath` until the returned
+ * restore is called; every other path, and every other method, stays real.
+ *
+ * A patch rather than a `chmod`: `chmod` reaches one errno (`EACCES`), only
+ * where POSIX modes bind, and not as root — and the property under test is
+ * "any refusal that is not an absence", so `EACCES`, `ELOOP`, `EMFILE` must all
+ * be reachable. What a walk under test meets is ONE refused call inside an
+ * otherwise ordinary tree; a walk that gave up entirely would pass a test where
+ * everything was refused.
+ *
+ * Lives in the shipped helpers because consumers in five packages each need to
+ * refuse a call, and the duplication gate refuses five copies.
+ */
+export declare function refuseSyncFs(method: RefusableSyncFsMethod, targetPath: string, code: string): () => void;
+/**
+ * `fs/promises[method]` rejects with `code` for exactly `targetPath` until the
+ * returned restore is called; every other path, and every other method, is real.
+ */
+export declare function refuseAsyncFs(method: RefusableAsyncFsMethod, targetPath: string, code: string): () => void;
+/**
+ * Run `body` while `fs[method]` throws `code` for exactly `targetPath`; the
+ * patch is lifted however `body` exits. See {@link refuseSyncFs}.
+ */
+export declare function withSyncFsRefused<T>(method: RefusableSyncFsMethod, targetPath: string, code: string, body: () => T | Promise<T>): Promise<T>;
+/**
+ * Run `body` with `fs.readdirSync` of exactly `directory` throwing an error
+ * carrying errno `code`. The listing case of {@link withSyncFsRefused}, named
+ * because refusing a LISTING is the question the crawler's consumers ask.
+ *
+ * @param directory - Absolute path of the one directory to refuse
+ * @param code - The errno to reject with
+ * @param body - Runs while the refusal is in force; may be async
+ * @returns Whatever `body` returned
  */
-export declare function canCreateSymlinks(dir: string): boolean;
+export declare function withReaddirSyncRefused<T>(directory: string, code: string, body: () => T | Promise<T>): Promise<T>;
+export {};
 //# sourceMappingURL=test-helpers.d.ts.map

package/dist/test-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ,EAC3C,GAAG,OAAO,EAAE,MAAM,EAAE,GACnB,MAAM,CAuBR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG;IACtD,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B,CAyBA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG;IACrD,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B,CAwBA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUtD"}
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAQA,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAe5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,GAAG,IAAI,CAwB5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,UAAU,GACjC,IAAI,CAEN;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,UAAU,GACjC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,yUAgBpB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,IAAI,MAAM,IAAI,CAoBzC;AAGD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,cAAc,CAE/F;AAED,+DAA+D;AAC/D,MAAM,MAAM,qBAAqB,GAC7B,aAAa,GACb,cAAc,GACd,UAAU,GACV,WAAW,GACX,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,YAAY,CAAC;AAEjB,mEAAmE;AACnE,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAiB1F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,qBAAqB,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAQxG;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAQ1G;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,MAAM,EAAE,qBAAqB,EAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAEZ"}