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

package/dist/test-helpers.d.ts

@@ -1,102 +1,153 @@
+declare const symlinkCapabilityBrand: unique symbol;
 /**
- * Get isolated test output directory for current test run
+ * Proof that this process can create filesystem symlinks.
  *
- * Creates a unique directory under `packages/{packageName}/.test-output/{testType}/{runId}`
- * where runId is `{timestamp}-{randomId}` to ensure isolation across parallel test runs.
+ * 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 type SymlinkCapability = {
+    readonly [symlinkCapabilityBrand]: true;
+};
+/**
+ * Whether this PROCESS can create symlinks — probed once and memoized.
  *
- * @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
+ * 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.)
  *
- * @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
+ * 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.
  *
- * // 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
- * ```
+ * 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 getTestOutputDir(packageName: string, testType: 'unit' | 'integration' | 'system', ...subdirs: string[]): string;
+export declare function symlinkCapability(): SymlinkCapability | null;
 /**
- * Get the base test output directory for a package
- * Useful for cleanup operations that need to remove all test output
+ * 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 packageName - Name of package (e.g., 'rag-lancedb')
- * @returns Absolute path to packages/{packageName}/.test-output
+ * @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.
  *
- * @example
- * ```typescript
- * const baseDir = getTestOutputBase('rag-lancedb');
- * // Result: packages/rag-lancedb/.test-output
- * ```
+ * @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 createSymlinkAsync(_cap: SymlinkCapability, target: string, path: string, type?: 'dir' | 'file' | 'junction'): Promise<void>;
+/**
+ * The variables git exports into a hook, which a fixture must clear before it
+ * can fabricate its own.
+ *
+ * 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 function getTestOutputBase(packageName: string): string;
+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"];
 /**
- * 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.
+ * Remove every inherited git redirection from `process.env`, and hand back the
+ * undo.
  *
- * @param prefix - Prefix for the suite temp directory name
- * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ * 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.
  *
- * @example
- * ```typescript
- * const suite = setupAsyncTempDirSuite('my-test');
+ * ⚠️ **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.
  *
- * describe('my tests', () => {
- *   beforeAll(suite.beforeAll);
- *   afterAll(suite.afterAll);
- *   beforeEach(suite.beforeEach);
+ * @returns A function restoring every variable to its prior value, putting back
+ *   "was not set" as unset rather than as an empty string
  *
- *   it('test 1', async () => {
- *     const tempDir = suite.getTempDir();
- *     // Use tempDir...
- *   });
- * });
+ * @example
+ * ```typescript
+ * let restoreGitEnv: () => void;
+ * beforeEach(() => { restoreGitEnv = detachGitEnv(); });
+ * afterEach(() => { restoreGitEnv(); });
  * ```
  */
-export declare function setupAsyncTempDirSuite(prefix: string): {
-    beforeAll: () => Promise<void>;
-    afterAll: () => Promise<void>;
-    beforeEach: () => Promise<void>;
-    afterEach: () => Promise<void>;
-    getTempDir: () => string;
-};
+export declare function detachGitEnv(): () => 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.
- *
- * @param prefix - Prefix for the suite temp directory name
- * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ * 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.
  *
- * @example
- * ```typescript
- * const suite = setupSyncTempDirSuite('my-test');
+ * 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.
  *
- * describe('my tests', () => {
- *   beforeAll(suite.beforeAll);
- *   afterAll(suite.afterAll);
- *   beforeEach(suite.beforeEach);
+ * 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.
  *
- *   it('test 1', () => {
- *     const tempDir = suite.getTempDir();
- *     // Use tempDir...
- *   });
- * });
- * ```
+ * @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 setupSyncTempDirSuite(prefix: string): {
-    beforeAll: () => void;
-    afterAll: () => void;
-    beforeEach: () => void;
-    afterEach: () => void;
-    getTempDir: () => string;
-};
+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"}
+{"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"}

package/dist/test-helpers.js

@@ -1,155 +1,260 @@
 import { randomBytes } from 'node:crypto';
-import { mkdtempSync, rmSync } from 'node:fs';
+import nodeFs, { rmSync, symlinkSync } from 'node:fs';
 import fs from 'node:fs/promises';
-import { mkdirSyncReal, normalizedTmpdir, safePath } from './path-utils.js';
+import { syncBuiltinESMExports } from 'node:module';
+import { isFilesystemAccessError } from './errors/errno.js';
+import { normalizedTmpdir, safePath, toForwardSlash } from './path-utils.js';
+let cachedCapability;
 /**
- * Get isolated test output directory for current test run
+ * The errnos that mean "this host cannot create symlinks": Windows without
+ * Developer Mode or `SeCreateSymbolicLinkPrivilege` (`EPERM`), and a
+ * filesystem that has no symlinks to offer (`ENOTSUP` / `EOPNOTSUPP`).
+ */
+const SYMLINK_UNSUPPORTED_ERRNOS = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP']);
+function isSymlinkUnsupported(error) {
+    return error instanceof Error && 'code' in error && typeof error.code === 'string' && SYMLINK_UNSUPPORTED_ERRNOS.has(error.code);
+}
+/**
+ * Whether this PROCESS can create symlinks — probed once and memoized.
  *
- * Creates a unique directory under `packages/{packageName}/.test-output/{testType}/{runId}`
- * where runId is `{timestamp}-{randomId}` to ensure isolation across parallel test runs.
+ * 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.)
  *
- * @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
+ * 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.
  *
- * @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
+ * 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.
  *
- * // 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
- * ```
+ * @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 function getTestOutputDir(packageName, testType, ...subdirs) {
-    // Generate unique run ID: timestamp + random hex
-    const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-').slice(0, 19);
-    const randomId = randomBytes(4).toString('hex');
-    const runId = `${timestamp}-${randomId}`;
-    // Find project root (assuming we're always in packages/*/test/*)
-    const projectRoot = safePath.resolve(process.cwd());
-    // Build path: packages/{packageName}/.test-output/{testType}/{runId}/{...subdirs}
-    const testOutputDir = safePath.join(projectRoot, 'packages', packageName, '.test-output', testType, runId, ...subdirs);
-    // Create directory structure and return normalized path
-    return mkdirSyncReal(testOutputDir, { recursive: true });
+export function symlinkCapability() {
+    if (cachedCapability === undefined) {
+        const probe = safePath.join(normalizedTmpdir(), `.vat-symlink-probe-${randomBytes(4).toString('hex')}`);
+        try {
+            symlinkSync('.', probe);
+            cachedCapability = {};
+        }
+        catch (error) {
+            if (!isSymlinkUnsupported(error))
+                throw error;
+            cachedCapability = null;
+        }
+        if (cachedCapability !== null) {
+            // Best-effort: the capability answer comes from creation succeeding, not
+            // from cleanup — a probe left behind by a failed rmSync (e.g. a transient
+            // lock on the freshly-created reparse point) must not flip a real "yes"
+            // into a memoized, process-wide "no". Only the filesystem refusing the
+            // delete is that case; a bug is not, and stays loud.
+            try {
+                rmSync(probe, { force: true });
+            }
+            catch (error) {
+                if (!isFilesystemAccessError(error))
+                    throw error;
+            }
+        }
+    }
+    return cachedCapability;
 }
 /**
- * Get the base test output directory for a package
- * Useful for cleanup operations that need to remove all test output
+ * 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 packageName - Name of package (e.g., 'rag-lancedb')
- * @returns Absolute path to packages/{packageName}/.test-output
+ * @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 function createSymlink(_cap, target, path, type) {
+    symlinkSync(target, path, type);
+}
+/**
+ * The async counterpart of {@link createSymlink}, for fixtures already using
+ * `node:fs/promises`. Same capability requirement, same reasoning.
  *
- * @example
- * ```typescript
- * const baseDir = getTestOutputBase('rag-lancedb');
- * // Result: packages/rag-lancedb/.test-output
- * ```
+ * @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 function getTestOutputBase(packageName) {
-    const projectRoot = safePath.resolve(process.cwd());
-    return safePath.join(projectRoot, 'packages', packageName, '.test-output');
+export async function createSymlinkAsync(_cap, target, path, type) {
+    await fs.symlink(target, path, type);
 }
 /**
- * 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.
+ * 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 const INHERITED_GIT_ENV = [
+    '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.
  *
- * @example
- * ```typescript
- * const suite = setupAsyncTempDirSuite('my-test');
+ * 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.
  *
- * describe('my tests', () => {
- *   beforeAll(suite.beforeAll);
- *   afterAll(suite.afterAll);
- *   beforeEach(suite.beforeEach);
+ * @returns A function restoring every variable to its prior value, putting back
+ *   "was not set" as unset rather than as an empty string
  *
- *   it('test 1', async () => {
- *     const tempDir = suite.getTempDir();
- *     // Use tempDir...
- *   });
- * });
+ * @example
+ * ```typescript
+ * let restoreGitEnv: () => void;
+ * beforeEach(() => { restoreGitEnv = detachGitEnv(); });
+ * afterEach(() => { restoreGitEnv(); });
  * ```
  */
-export function setupAsyncTempDirSuite(prefix) {
-    let suiteDir = '';
-    let tempDir = '';
-    let testCounter = 0;
-    return {
-        beforeAll: async () => {
-            suiteDir = await fs.mkdtemp(safePath.join(normalizedTmpdir(), `${prefix}-suite-`));
-        },
-        afterAll: async () => {
-            if (suiteDir) {
-                await fs.rm(suiteDir, { recursive: true, force: true });
-            }
-        },
-        beforeEach: async () => {
-            testCounter++;
-            tempDir = safePath.join(suiteDir, `test-${testCounter}`);
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- tempDir is from mkdtemp
-            await fs.mkdir(tempDir, { recursive: true });
-        },
-        afterEach: async () => {
-            // Per-test cleanup handled by suite cleanup
-        },
-        getTempDir: () => tempDir,
+export function detachGitEnv() {
+    const saved = new Map();
+    const forget = (name) => {
+        saved.set(name, process.env[name]);
+        delete process.env[name];
     };
+    for (const name of INHERITED_GIT_ENV) {
+        forget(name);
+    }
+    return () => {
+        for (const [name, value] of saved) {
+            // Deleted first so an absent variable is restored as absent: assigning
+            // `undefined` would leave the literal string 'undefined' behind.
+            delete process.env[name];
+            if (value !== undefined)
+                process.env[name] = value;
+        }
+    };
+}
+/**
+ * The errno-shaped error a refused `fs` call throws: a message, the `code`,
+ * and the `syscall`, exactly as Node shapes one.
+ */
+export function errnoError(code, syscall, target) {
+    return Object.assign(new Error(`${code}: refused, ${syscall} '${target}'`), { code, syscall });
 }
 /**
- * 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.
+ * Assign `fn` over `module[method]` and republish the builtin's ESM bindings.
  *
- * @param prefix - Prefix for the suite temp directory name
- * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ * Assigning on the CJS object alone reaches ONLY a `import fs from 'node:fs'`
+ * caller — a named or namespace import reads the builtin's ESM bindings, which
+ * Node snapshots at import time. `syncBuiltinESMExports()` after each
+ * assignment republishes the patch (and the restore) to every import style;
+ * measured under vitest: without it, a spy on a named-import caller attached
+ * and counted zero, which reads exactly like "this function performs no I/O".
+ */
+function republish(module, method, fn) {
+    module[method] = fn;
+    syncBuiltinESMExports();
+}
+/**
+ * Make `fs[method]` throw `code` for exactly `targetPath` until the returned
+ * restore is called; every other path, and every other method, stays real.
  *
- * @example
- * ```typescript
- * const suite = setupSyncTempDirSuite('my-test');
+ * 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.
  *
- * describe('my tests', () => {
- *   beforeAll(suite.beforeAll);
- *   afterAll(suite.afterAll);
- *   beforeEach(suite.beforeEach);
+ * Lives in the shipped helpers because consumers in five packages each need to
+ * refuse a call, and the duplication gate refuses five copies.
+ */
+export function refuseSyncFs(method, targetPath, code) {
+    const original = nodeFs[method];
+    const refused = toForwardSlash(targetPath);
+    republish(nodeFs, method, (target, ...rest) => {
+        if (toForwardSlash(String(target)) === refused)
+            throw errnoError(code, method, String(target));
+        return original(target, ...rest);
+    });
+    return () => republish(nodeFs, method, original);
+}
+/**
+ * `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 function refuseAsyncFs(method, targetPath, code) {
+    const original = fs[method].bind(fs);
+    const refused = toForwardSlash(targetPath);
+    republish(fs, method, async (target, ...rest) => {
+        if (toForwardSlash(String(target)) === refused)
+            throw errnoError(code, method, String(target));
+        return original(target, ...rest);
+    });
+    return () => republish(fs, method, original);
+}
+/**
+ * Run `body` while `fs[method]` throws `code` for exactly `targetPath`; the
+ * patch is lifted however `body` exits. See {@link refuseSyncFs}.
+ */
+export async function withSyncFsRefused(method, targetPath, code, body) {
+    const restore = refuseSyncFs(method, targetPath, code);
+    try {
+        return await body();
+    }
+    finally {
+        restore();
+    }
+}
+/**
+ * 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.
  *
- *   it('test 1', () => {
- *     const tempDir = suite.getTempDir();
- *     // Use tempDir...
- *   });
- * });
- * ```
+ * @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 function setupSyncTempDirSuite(prefix) {
-    let suiteDir = '';
-    let tempDir = '';
-    let testCounter = 0;
-    return {
-        beforeAll: () => {
-            suiteDir = mkdtempSync(safePath.join(normalizedTmpdir(), `${prefix}-suite-`));
-        },
-        afterAll: () => {
-            if (suiteDir) {
-                rmSync(suiteDir, { recursive: true, force: true });
-            }
-        },
-        beforeEach: () => {
-            testCounter++;
-            tempDir = safePath.join(suiteDir, `test-${testCounter}`);
-            mkdirSyncReal(tempDir);
-        },
-        afterEach: () => {
-            // Per-test cleanup handled by suite cleanup
-        },
-        getTempDir: () => tempDir,
-    };
+export async function withReaddirSyncRefused(directory, code, body) {
+    return withSyncFsRefused('readdirSync', directory, code, body);
 }
 //# sourceMappingURL=test-helpers.js.map