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

package/dist/testing/hostile-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostile-tree.d.ts","sourceRoot":"","sources":["../../src/testing/hostile-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH,8EAA8E;AAC9E,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAW1C,CAAC;AAEF,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iHAAiH;IACjH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,yEAAyE;IACzE,OAAO,IAAI,IAAI,CAAC;CACjB;AAuBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA8D1D;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,WAAW,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAuBrE"}

package/dist/testing/hostile-tree.js

@@ -0,0 +1,164 @@
+/**
+ * One hostile fixture tree, built the same way for every sink.
+ *
+ * A correctness sweep found a delete, a copy and an uninstall that
+ * each walked out of their root, and found them by hand-building the same
+ * shapes — a symlink pointing out, a symlink pointing back at the root, a
+ * `..`-named entry, an unreadable directory, a traversal name — one throwaway
+ * fixture per probe. This module
+ * is that fixture, once, so a sink's test says `buildHostileTree(base)` and
+ * `it.each(HOSTILE_NAMES)` and is refusing the shapes the next sink's test is
+ * refusing too. A shape added here reaches every sink that uses it.
+ *
+ * ⛔ Framework-free, like everything under `testing/`: no `vitest` import, so
+ * the `./testing` subpath keeps the empty third-party set its purity pin
+ * asserts. Fields that the host cannot build are `null` — route those through
+ * the suite's own `skip()` so the skip is visible in the report.
+ */
+import { chmodSync, rmSync, writeFileSync } from 'node:fs';
+import { isFilesystemAccessError } from '../errors/errno.js';
+import { mkdirSyncReal, safePath } from '../path-utils.js';
+import { createSymlink, symlinkCapability } from '../test-helpers.js';
+import { CANNOT_DENY_READS } from './platform-gates.js';
+import { createTempDir, removeTempDir } from './temp-dir.js';
+/** The names a sink must refuse when they arrive as "the entry to act on". */
+export const HOSTILE_NAMES = [
+    '..',
+    '../victim',
+    '../../victim',
+    'a/../../victim',
+    String.raw `..\victim`,
+    '.',
+    '',
+    '/victim',
+    String.raw `C:\victim`,
+    `nul${String.fromCodePoint(0)}byte`,
+];
+/** A link, or `null` when this host cannot make one (the capability probe said so). */
+function tryLink(cap, target, link, type) {
+    if (cap === null)
+        return null;
+    createSymlink(cap, target, link, type);
+    return link;
+}
+function tryMkdir(dir) {
+    try {
+        mkdirSyncReal(dir);
+        return dir;
+    }
+    catch (error) {
+        // Only a name the OS will not take is "cannot build" — `ENAMETOOLONG` on
+        // a host with a shorter limit. Anything else is a broken fixture.
+        if (error instanceof Error && 'code' in error && error.code === 'ENAMETOOLONG') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Plant the hostile tree under `base`, which must exist and be empty enough
+ * to take `root`, `outside` and `root-alias` as direct children.
+ *
+ * @param base - A scratch directory the caller owns (a per-test temp dir)
+ * @returns The tree, with `null` for every shape this host cannot build
+ */
+export function buildHostileTree(base) {
+    const root = safePath.join(base, 'root');
+    const member = safePath.join(root, 'member');
+    const dotdotNamed = safePath.join(root, '..cache');
+    const outside = safePath.join(base, 'outside');
+    const victim = safePath.join(outside, 'victim');
+    mkdirSyncReal(member, { recursive: true });
+    mkdirSyncReal(safePath.join(root, 'nested', 'deep'), { recursive: true });
+    mkdirSyncReal(dotdotNamed);
+    mkdirSyncReal(victim, { recursive: true });
+    writeFileSync(safePath.join(victim, 'secret.txt'), 'TOKEN=abc\n');
+    writeFileSync(safePath.join(member, 'file.txt'), 'member\n');
+    const cap = symlinkCapability();
+    const linkOut = tryLink(cap, victim, safePath.join(root, 'link-out'), 'dir');
+    const linkIn = tryLink(cap, member, safePath.join(root, 'link-in'), 'dir');
+    const dangling = tryLink(cap, safePath.join(root, 'does-not-exist'), safePath.join(root, 'dangling'), 'file');
+    const linkLoop = tryLink(cap, root, safePath.join(root, 'loop'), 'dir');
+    const rootAlias = tryLink(cap, root, safePath.join(base, 'root-alias'), 'dir');
+    let unreadable = null;
+    if (!CANNOT_DENY_READS) {
+        unreadable = safePath.join(root, 'unreadable');
+        mkdirSyncReal(unreadable);
+        writeFileSync(safePath.join(unreadable, 'hidden.txt'), 'x');
+        chmodSync(unreadable, 0o000);
+    }
+    const longPath = tryMkdir(safePath.join(root, 'L'.repeat(200)));
+    let cleaned = false;
+    return {
+        root,
+        member,
+        dotdotNamed,
+        outside,
+        victim,
+        linkOut,
+        linkIn,
+        dangling,
+        linkLoop,
+        rootAlias,
+        unreadable,
+        longPath,
+        cleanup: () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            if (unreadable !== null) {
+                try {
+                    chmodSync(unreadable, 0o700);
+                }
+                catch (error) {
+                    // Already removed by the subject under test, which a delete sink is
+                    // entitled to do; a refusal to restore anything else stays loud.
+                    if (!isFilesystemAccessError(error))
+                        throw error;
+                }
+            }
+            for (const dir of [root, outside, rootAlias]) {
+                if (dir !== null)
+                    rmSync(dir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+/**
+ * Hold a per-test hostile tree, so a suite's wiring is three lines:
+ * `const hostile = hostileTreePerTest('x'); beforeEach(hostile.plant); afterEach(hostile.clear);`.
+ *
+ * Same shape and same reasons as `replantableCorpus`: the tree comes back
+ * through a GETTER because it is reminted per test, `plant` clears any tree
+ * still standing so nested `describe`s do not leak one, and `tree()` before
+ * `plant()` throws by name rather than surfacing as an undefined read.
+ *
+ * @param prefix - `mkdtemp` prefix for the scratch root, so a leak names its suite
+ * @returns Plant/clear/tree, to be driven from the caller's own hooks
+ */
+export function hostileTreePerTest(prefix) {
+    let scratch;
+    let planted;
+    const clear = () => {
+        planted?.cleanup();
+        planted = undefined;
+        if (scratch !== undefined)
+            removeTempDir(scratch);
+        scratch = undefined;
+    };
+    return {
+        plant: () => {
+            clear();
+            scratch = createTempDir(prefix);
+            planted = buildHostileTree(scratch);
+        },
+        clear,
+        tree: () => {
+            if (planted === undefined) {
+                throw new Error(`hostileTreePerTest('${prefix}'): tree() before plant() — the suite is missing its beforeEach`);
+            }
+            return planted;
+        },
+    };
+}
+//# sourceMappingURL=hostile-tree.js.map

package/dist/testing/hostile-tree.js.map

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

package/dist/testing/platform-gates.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The host facts a fixture has to ask before it can build a refusal.
+ *
+ * ⛔ Framework-free, like everything under `testing/`: no `vitest` import, so
+ * the `./testing` subpath keeps the empty third-party set its purity pin
+ * asserts. Route a `true` here through the suite's own `skip()` so the skip is
+ * visible in the report — a fixture that silently no-ops is a passing test for
+ * a property nobody exercised.
+ */
+/**
+ * Whether a `chmod 000` on this host denies anything.
+ *
+ * Two hosts read every mode as readable: Windows, where POSIX mode bits do not
+ * bind at all, and a POSIX process running as root, which bypasses them. On
+ * either, a fixture directory made unreadable is still readable, so a test of
+ * "the walker refuses what it cannot list" would pass by listing it.
+ *
+ * ⚠️ Evaluated ONCE at module load, as a constant rather than a function, on
+ * purpose: the answer is a property of the process's identity and platform,
+ * neither of which changes mid-run, and a constant is what `it.skipIf(...)`
+ * takes. This one line used to be spelled in 28 test files under three names
+ * (`CANNOT_DENY_READS`, `PERMISSIONS_ENFORCED`, inline), which is 28 places
+ * for the `getuid` guard to drift.
+ */
+export declare const CANNOT_DENY_READS: boolean;
+/**
+ * The positive spelling, for the suites that phrase the gate as "only run
+ * where modes bind". Same fact, no second evaluation.
+ */
+export declare const PERMISSIONS_ENFORCED: boolean;
+//# sourceMappingURL=platform-gates.d.ts.map

package/dist/testing/platform-gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-gates.d.ts","sourceRoot":"","sources":["../../src/testing/platform-gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,EAAE,OACkE,CAAC;AAEnG;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAA4B,CAAC"}

package/dist/testing/platform-gates.js

@@ -0,0 +1,31 @@
+/**
+ * The host facts a fixture has to ask before it can build a refusal.
+ *
+ * ⛔ Framework-free, like everything under `testing/`: no `vitest` import, so
+ * the `./testing` subpath keeps the empty third-party set its purity pin
+ * asserts. Route a `true` here through the suite's own `skip()` so the skip is
+ * visible in the report — a fixture that silently no-ops is a passing test for
+ * a property nobody exercised.
+ */
+/**
+ * Whether a `chmod 000` on this host denies anything.
+ *
+ * Two hosts read every mode as readable: Windows, where POSIX mode bits do not
+ * bind at all, and a POSIX process running as root, which bypasses them. On
+ * either, a fixture directory made unreadable is still readable, so a test of
+ * "the walker refuses what it cannot list" would pass by listing it.
+ *
+ * ⚠️ Evaluated ONCE at module load, as a constant rather than a function, on
+ * purpose: the answer is a property of the process's identity and platform,
+ * neither of which changes mid-run, and a constant is what `it.skipIf(...)`
+ * takes. This one line used to be spelled in 28 test files under three names
+ * (`CANNOT_DENY_READS`, `PERMISSIONS_ENFORCED`, inline), which is 28 places
+ * for the `getuid` guard to drift.
+ */
+export const CANNOT_DENY_READS = process.platform === 'win32' || (typeof process.getuid === 'function' && process.getuid() === 0);
+/**
+ * The positive spelling, for the suites that phrase the gate as "only run
+ * where modes bind". Same fact, no second evaluation.
+ */
+export const PERMISSIONS_ENFORCED = !CANNOT_DENY_READS;
+//# sourceMappingURL=platform-gates.js.map

package/dist/testing/platform-gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-gates.js","sourceRoot":"","sources":["../../src/testing/platform-gates.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAC5B,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAEnG;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAY,CAAC,iBAAiB,CAAC"}

package/dist/testing/temp-dir.d.ts

@@ -0,0 +1,255 @@
+/**
+ * The ONE temp-directory helper family.
+ *
+ * Every shape a suite needs to mint scratch space lives here: a per-call
+ * `createTempDir`, a tracker that removes what it minted, and the per-suite
+ * sync/async suite helpers with their bounded teardown. The audit counted
+ * eleven definitions of "give me a temp dir that cleans itself up" across
+ * eight modules, six of them named differently and none of them visible to
+ * the duplication gate; this module is where they were collapsed to.
+ *
+ * ⛔ Framework-free, like everything under `testing/`: nothing here imports
+ * `vitest`, so the `./testing` subpath keeps the empty third-party set its
+ * purity pin asserts. Each suite owns its own hooks and calls these from
+ * inside them.
+ */
+/**
+ * Mint a fresh temp directory under the host's (short-name-resolved) tmpdir.
+ *
+ * The one-liner that used to be spelled in three packages as
+ * `createTestTempDir`. Pair with {@link removeTempDir}, or let
+ * {@link tempDirTracker} pair them for you.
+ *
+ * @param prefix - `mkdtemp` prefix, so a leaked directory names its own suite
+ * @returns Absolute, forward-slashed path of the new directory
+ */
+export declare function createTempDir(prefix: string): string;
+/** The async counterpart of {@link createTempDir}, for suites already on `fs/promises`. */
+export declare function createTempDirAsync(prefix: string): Promise<string>;
+/**
+ * Remove a directory {@link createTempDir} minted — and ONLY such a directory.
+ *
+ * Refuses, by name, to remove anything that is not strictly under the host
+ * tmpdir as the filesystem sees it. A teardown is the one place test code
+ * runs `rm -rf` on a variable, and a variable that was never assigned (a
+ * `beforeAll` that threw), or was assigned a fixture INSIDE the repo, must
+ * not become `rm -rf ''` or `rm -rf packages/`. The `dev-tools` copy of this
+ * helper carried that guard as a lexical `startsWith`; the guard here asks
+ * the filesystem, so a symlinked tmpdir (macOS) still passes.
+ *
+ * `force: true` tolerates a directory already gone; the retries are Node's
+ * own remedy for the transient `EBUSY` / `EPERM` a just-closed handle
+ * produces on Windows. Anything left after that is a real teardown failure
+ * and stays loud — a teardown that swallows it hides a leaking fixture.
+ *
+ * @param dir - The directory to remove
+ * @throws When `dir` is not strictly under the host tmpdir
+ */
+export declare function removeTempDir(dir: string): void;
+/**
+ * A factory that remembers every directory it minted, so one `afterEach`
+ * removes them all.
+ *
+ * @param prefix - `mkdtemp` prefix for every directory this tracker mints
+ * @returns `create` to mint one more, `cleanupAll` to remove every one so far
+ *
+ * @example
+ * ```typescript
+ * const scratch = tempDirTracker('my-suite-');
+ * afterEach(() => scratch.cleanupAll());
+ * it('…', () => { const dir = scratch.create(); … });
+ * ```
+ */
+export declare function tempDirTracker(prefix: string): {
+    create: () => string;
+    cleanupAll: () => void;
+};
+/** Knobs for {@link removeScratchDir}; all three exist so the behaviour is testable. */
+export interface RemoveScratchDirOptions {
+    /** Deadline before the removal is abandoned. Default {@link SCRATCH_REMOVAL_BUDGET_MS}. */
+    readonly budgetMs?: number;
+    /** Where the give-up notice goes. Default `console.warn`. */
+    readonly onWarn?: (message: string) => void;
+    /**
+     * The removal itself. Defaults to `fs.rm` with recursive/force/retries.
+     *
+     * Injectable because the *contract* — a removal that fails must warn rather
+     * than throw — cannot otherwise be tested on every platform. Driving a real
+     * `fs.rm` failure needs a path the OS refuses, and those diverge: a path
+     * whose parent component is a regular file yields `ENOTDIR` on POSIX, and
+     * resolves silently on Windows. A test written against the POSIX shape
+     * passes locally and fails in CI, which is exactly what it did once.
+     */
+    readonly remove?: (dir: string) => Promise<void>;
+}
+/**
+ * Delete a scratch directory as *best effort* — never failing the suite that
+ * created it, and never taking longer than its own budget to say so.
+ *
+ * ## Why this is not just `await rm(dir, { recursive: true, force: true })`
+ *
+ * A teardown hook that can redden a suite whose every assertion passed is a
+ * defect in the harness, not a flake. `packages/lab/test/instrument.test.ts`
+ * timed out here on two consecutive Windows runs with all 655 assertions
+ * green — only the cleanup lost.
+ *
+ * The measurement is what rules out the obvious fixes: that scratch dir holds
+ * 490 files / 378 KiB across 14 fixture git repos, and deletes in **59 ms**
+ * idle. Against vitest's 10,000 ms unit-hook budget that is 170x of headroom,
+ * and Windows blew through it anyway. No quantity of real work explains that,
+ * so the cause is scheduling — contention from a fully parallel `validate`,
+ * plus per-unlink antivirus on Windows — which is unbounded by nature. Hence:
+ *
+ * - **Raising `hookTimeout` cannot be argued.** You would be picking a number
+ *   to beat an unbounded quantity, when 10s of 170x headroom already lost. It
+ *   also punches a hole in the deliberate policy in `vitest.shared.ts` ("no
+ *   hookTimeout override here on purpose") for every unit hook, to fix one.
+ * - **`try`/`catch` around the `rm` cannot work.** A vitest hook timeout is a
+ *   race decided on the *timer* side; the hook's own catch never sees it. It
+ *   addresses a failure mode we did not observe and leaves the one we did.
+ * - **`maxRetries` alone makes it worse.** Retries target transient
+ *   `EPERM`/`EBUSY`, which fail *fast*; our failure was *slow*, and retry
+ *   backoff only adds to it. Kept below as a cheap inner win, not as the fix.
+ *
+ * So the deadline is taken away from vitest: the removal races a timer of our
+ * own, well inside the hook budget, and expiry is a warning rather than a
+ * failure. The hook therefore always resolves in time, which makes it
+ * *structurally* incapable of reddening a green suite on any machine at any
+ * load — rather than merely unlikely to.
+ *
+ * The cost, stated plainly: under pathological contention the directory
+ * survives in the OS temp dir, which the OS reclaims, and the warning names
+ * the path. It can never surface as an unhandled rejection, because the only
+ * rejection handler is installed before the race.
+ *
+ * ⚠️ **Abandoning the removal does not stop it, and does not free the worker.**
+ * A pending libuv `fs` request is an active handle, so the `rm` runs to
+ * completion regardless — measured at 2,407 ms on an 8,000-file tree after the
+ * race was decided at 5 ms — and the process cannot exit until it does.
+ * `timer.unref()` below unrefs the *timer*, not the removal. So what this buys
+ * is bounded: the **hook** always resolves in time, which is what stops a green
+ * suite going red. It does **not** shed the work, and under the contention it
+ * targets the abandoned removal competes for disk with whatever runs next in
+ * the same worker. That is the trade, and it is why the budget wants to be as
+ * large as the tier's hook allows rather than as small as possible.
+ *
+ * @param dir - Directory to remove. An empty string is a no-op, so a suite
+ *   whose `beforeAll` never ran can call this unconditionally.
+ * @param options - Deadline and warning sink
+ *
+ * @example
+ * ```typescript
+ * afterAll(async () => {
+ *   await removeScratchDir(scratch);
+ * });
+ * ```
+ */
+export declare function removeScratchDir(dir: string, options?: RemoveScratchDirOptions): Promise<void>;
+/**
+ * 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
+ * ```
+ */
+export declare function getTestOutputDir(packageName: string, testType: 'unit' | 'integration' | 'system', ...subdirs: string[]): string;
+/**
+ * Get the base test output directory for a package
+ * Useful for cleanup operations that need to remove all test output
+ *
+ * @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
+ * ```
+ */
+export declare function getTestOutputBase(packageName: string): string;
+/**
+ * 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
+ * @param teardown - Forwarded to {@link removeScratchDir}. Raise `budgetMs` for a
+ *   suite whose fixture tree is heavy or whose tier allows a longer hook than the
+ *   unit tier this default is sized against — see {@link SCRATCH_REMOVAL_BUDGET_MS}.
+ * @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);
+ *
+ *   it('test 1', async () => {
+ *     const tempDir = suite.getTempDir();
+ *     // Use tempDir...
+ *   });
+ * });
+ * ```
+ */
+export declare function setupAsyncTempDirSuite(prefix: string, teardown?: RemoveScratchDirOptions): {
+    beforeAll: () => Promise<void>;
+    afterAll: () => Promise<void>;
+    beforeEach: () => Promise<void>;
+    afterEach: () => Promise<void>;
+    getTempDir: () => string;
+};
+/**
+ * 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
+ * @param teardown - Forwarded to {@link removeScratchDir}. Raise `budgetMs` for a
+ *   suite whose fixture tree is heavy or whose tier allows a longer hook than the
+ *   unit tier this default is sized against — see {@link SCRATCH_REMOVAL_BUDGET_MS}.
+ * @returns Suite helper with beforeAll, afterAll, beforeEach, afterEach, and getTempDir
+ *
+ * @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...
+ *   });
+ * });
+ * ```
+ */
+export declare function setupSyncTempDirSuite(prefix: string, teardown?: RemoveScratchDirOptions): {
+    beforeAll: () => void;
+    afterAll: () => Promise<void>;
+    beforeEach: () => void;
+    afterEach: () => void;
+    getTempDir: () => string;
+};
+//# sourceMappingURL=temp-dir.d.ts.map

package/dist/testing/temp-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-dir.d.ts","sourceRoot":"","sources":["../../src/testing/temp-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,2FAA2F;AAC3F,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAExE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAK/C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,IAAI,CAAA;CAAE,CAa/F;AAuBD,wFAAwF;AACxF,MAAM,WAAW,uBAAuB;IACtC,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAED;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,uBAA4B,GAAG;IAC9F,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,CAsBA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,uBAA4B,GAAG;IAC7F,SAAS,EAAE,MAAM,IAAI,CAAC;IAItB,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,MAAM,CAAC;CAC1B,CAsBA"}