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

package/dist/text-file.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Read a file and decode it through the one content-decoding seam.
+ *
+ * The replacement for `readFile(path, 'utf-8')`, which decodes inside `fs` with
+ * no byte-order-mark handling and no way to express UTF-16BE at all. The
+ * *decision* about what the bytes say lives in `text-content.ts`, which is pure
+ * and reaches no `node:*` module; this file is only the two lines that get the
+ * bytes off disk, and it lives on the `./fs` entry with everything else here
+ * that touches the filesystem.
+ *
+ * Two functions rather than one, because the callers genuinely differ: an
+ * enumeration or parse lane is asynchronous throughout, while a manifest or
+ * config probe on a startup path is not, and handing the latter a Promise makes
+ * it worse rather than more consistent.
+ *
+ * A caller that needs the RAW bytes as well as the text — to hash them, key
+ * them, or report `stat().size` — must not use these: read the bytes once with
+ * {@link readDecodableBytes} and call `decodeTextContent` on them, so the digest
+ * and the characters come from the same read. `readContentWithKey` in
+ * `@vibe-agent-toolkit/resources` is that caller and is shaped exactly that way.
+ */
+import { type DecodedText } from './text-content.js';
+/**
+ * Read a file and decode it through {@link decodeTextContent}.
+ *
+ * @param filePath - Path to read
+ * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
+ * @throws Whatever `readFile` throws — callers decide whether that is fatal — and
+ *   {@link TextTooLargeError} for a file too large to decode, before reading it
+ *
+ * @example
+ * ```typescript
+ * const { text, encoding } = await readTextContent(docPath);
+ * // A PowerShell-written document: encoding 'utf-16le', text with no BOM
+ * ```
+ */
+export declare function readTextContent(filePath: string): Promise<DecodedText>;
+/**
+ * {@link readTextContent}, synchronously.
+ *
+ * @param filePath - Path to read
+ * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
+ * @throws Whatever `readFileSync` throws, and {@link TextTooLargeError} as {@link readDecodableBytes} does
+ */
+export declare function readTextContentSync(filePath: string): DecodedText;
+/**
+ * The most bytes that can be decoded into one JS string: the engine's own
+ * string-length limit, read from `node:buffer` rather than written down.
+ *
+ * A bound on BYTES stated in UTF-16 code units, which is exact-or-safe for UTF-8
+ * (a UTF-8 byte never yields more than one code unit) and conservative for
+ * UTF-16/UTF-32, whose bytes yield half or a quarter as many.
+ */
+export declare const MAX_DECODABLE_BYTES: number;
+/**
+ * Whether content of this many bytes is past what can be decoded to a string.
+ *
+ * @param byteLength - The content's size in bytes, as `stat` reports it
+ * @returns True when decoding it would exceed {@link MAX_DECODABLE_BYTES}
+ */
+export declare function exceedsDecodableLength(byteLength: number): boolean;
+/**
+ * Read a file's raw bytes for decoding — refusing, by `stat` and before reading
+ * a byte, one too large to decode at all.
+ *
+ * The one read path for "bytes that are about to go through
+ * {@link decodeTextContent}": {@link readTextContent} uses it, and so does
+ * `readContentWithKey` in `@vibe-agent-toolkit/resources`, which needs the raw
+ * bytes as well to key them. Without the stat, a 966 MB file is read whole and
+ * only then refused by the decoder, and past 2 GiB `readFile` fails first with
+ * its own `ERR_FS_FILE_TOO_LARGE` — two different errors for one fact.
+ *
+ * The size comes from `fstat` on the handle that is then read, not from a
+ * separate `stat` of the path, so a rename between the two cannot substitute
+ * another file. A file that GROWS past the limit after the `fstat` still reaches
+ * the decoder, which raises the same {@link TextTooLargeError}.
+ *
+ * @param filePath - Path to read
+ * @returns The file's bytes
+ * @throws {@link TextTooLargeError} when the file is past {@link MAX_DECODABLE_BYTES},
+ *   and whatever `open`/`readFile` throw otherwise
+ */
+export declare function readDecodableBytes(filePath: string): Promise<Buffer>;
+//# sourceMappingURL=text-file.d.ts.map

package/dist/text-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-file.d.ts","sourceRoot":"","sources":["../src/text-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE3F;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAQjE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAoC,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAElE;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1E"}

package/dist/text-file.js

@@ -0,0 +1,118 @@
+/**
+ * Read a file and decode it through the one content-decoding seam.
+ *
+ * The replacement for `readFile(path, 'utf-8')`, which decodes inside `fs` with
+ * no byte-order-mark handling and no way to express UTF-16BE at all. The
+ * *decision* about what the bytes say lives in `text-content.ts`, which is pure
+ * and reaches no `node:*` module; this file is only the two lines that get the
+ * bytes off disk, and it lives on the `./fs` entry with everything else here
+ * that touches the filesystem.
+ *
+ * Two functions rather than one, because the callers genuinely differ: an
+ * enumeration or parse lane is asynchronous throughout, while a manifest or
+ * config probe on a startup path is not, and handing the latter a Promise makes
+ * it worse rather than more consistent.
+ *
+ * A caller that needs the RAW bytes as well as the text — to hash them, key
+ * them, or report `stat().size` — must not use these: read the bytes once with
+ * {@link readDecodableBytes} and call `decodeTextContent` on them, so the digest
+ * and the characters come from the same read. `readContentWithKey` in
+ * `@vibe-agent-toolkit/resources` is that caller and is shaped exactly that way.
+ */
+import { constants } from 'node:buffer';
+import { closeSync, fstatSync, openSync, readFileSync } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { decodeTextContent, TextTooLargeError } from './text-content.js';
+/**
+ * Read a file and decode it through {@link decodeTextContent}.
+ *
+ * @param filePath - Path to read
+ * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
+ * @throws Whatever `readFile` throws — callers decide whether that is fatal — and
+ *   {@link TextTooLargeError} for a file too large to decode, before reading it
+ *
+ * @example
+ * ```typescript
+ * const { text, encoding } = await readTextContent(docPath);
+ * // A PowerShell-written document: encoding 'utf-16le', text with no BOM
+ * ```
+ */
+export async function readTextContent(filePath) {
+    return decodeTextContent(await readDecodableBytes(filePath));
+}
+/**
+ * {@link readTextContent}, synchronously.
+ *
+ * @param filePath - Path to read
+ * @returns The decoded text, the encoding used, whether that was a fact, and the replacement-character count
+ * @throws Whatever `readFileSync` throws, and {@link TextTooLargeError} as {@link readDecodableBytes} does
+ */
+export function readTextContentSync(filePath) {
+    const handle = openSync(filePath, 'r');
+    try {
+        refuseUndecodableSize(fstatSync(handle).size);
+        return decodeTextContent(readFileSync(handle));
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+/**
+ * The most bytes that can be decoded into one JS string: the engine's own
+ * string-length limit, read from `node:buffer` rather than written down.
+ *
+ * A bound on BYTES stated in UTF-16 code units, which is exact-or-safe for UTF-8
+ * (a UTF-8 byte never yields more than one code unit) and conservative for
+ * UTF-16/UTF-32, whose bytes yield half or a quarter as many.
+ */
+export const MAX_DECODABLE_BYTES = constants.MAX_STRING_LENGTH;
+/**
+ * Whether content of this many bytes is past what can be decoded to a string.
+ *
+ * @param byteLength - The content's size in bytes, as `stat` reports it
+ * @returns True when decoding it would exceed {@link MAX_DECODABLE_BYTES}
+ */
+export function exceedsDecodableLength(byteLength) {
+    return byteLength > MAX_DECODABLE_BYTES;
+}
+/**
+ * Throw {@link TextTooLargeError} for a size no decode can hold.
+ *
+ * @param byteLength - The content's size in bytes
+ */
+function refuseUndecodableSize(byteLength) {
+    if (exceedsDecodableLength(byteLength))
+        throw new TextTooLargeError(byteLength);
+}
+/**
+ * Read a file's raw bytes for decoding — refusing, by `stat` and before reading
+ * a byte, one too large to decode at all.
+ *
+ * The one read path for "bytes that are about to go through
+ * {@link decodeTextContent}": {@link readTextContent} uses it, and so does
+ * `readContentWithKey` in `@vibe-agent-toolkit/resources`, which needs the raw
+ * bytes as well to key them. Without the stat, a 966 MB file is read whole and
+ * only then refused by the decoder, and past 2 GiB `readFile` fails first with
+ * its own `ERR_FS_FILE_TOO_LARGE` — two different errors for one fact.
+ *
+ * The size comes from `fstat` on the handle that is then read, not from a
+ * separate `stat` of the path, so a rename between the two cannot substitute
+ * another file. A file that GROWS past the limit after the `fstat` still reaches
+ * the decoder, which raises the same {@link TextTooLargeError}.
+ *
+ * @param filePath - Path to read
+ * @returns The file's bytes
+ * @throws {@link TextTooLargeError} when the file is past {@link MAX_DECODABLE_BYTES},
+ *   and whatever `open`/`readFile` throw otherwise
+ */
+export async function readDecodableBytes(filePath) {
+    const handle = await open(filePath, 'r');
+    try {
+        refuseUndecodableSize((await handle.stat()).size);
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=text-file.js.map

package/dist/text-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-file.js","sourceRoot":"","sources":["../src/text-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAE3F;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,OAAO,iBAAiB,CAAC,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,qBAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9C,OAAO,iBAAiB,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACjD,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAW,SAAS,CAAC,iBAAiB,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,OAAO,UAAU,GAAG,mBAAmB,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,UAAkB;IAC/C,IAAI,sBAAsB,CAAC,UAAU,CAAC;QAAE,MAAM,IAAI,iBAAiB,CAAC,UAAU,CAAC,CAAC;AAClF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAgB;IACvD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,qBAAqB,CAAC,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/text.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @vibe-agent-toolkit/utils/text
+ *
+ * **The one way bytes become text.** Encoding detection from a byte-order mark,
+ * BOM stripping, and a stated default when there is no BOM — see
+ * `text-content.ts` for what is a fact, what is an assumption, and the two
+ * limitations that are deliberately not guessed around.
+ *
+ * Pure: this entry reaches no `node:*` builtin and no third-party package, so
+ * bytes from a git blob, an HTTP response or a zip entry decode through exactly
+ * the same function as bytes from disk. For the read-a-file case, import
+ * `readTextContent` from `@vibe-agent-toolkit/utils/fs`, which is this plus a
+ * `readFile`.
+ */
+export { decodeTextContent, type DecodedText, type EncodingSource, type TextEncoding, type TextProvenance, TextTooLargeError, } from './text-content.js';
+//# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/text.js

@@ -0,0 +1,16 @@
+/**
+ * @vibe-agent-toolkit/utils/text
+ *
+ * **The one way bytes become text.** Encoding detection from a byte-order mark,
+ * BOM stripping, and a stated default when there is no BOM — see
+ * `text-content.ts` for what is a fact, what is an assumption, and the two
+ * limitations that are deliberately not guessed around.
+ *
+ * Pure: this entry reaches no `node:*` builtin and no third-party package, so
+ * bytes from a git blob, an HTTP response or a zip entry decode through exactly
+ * the same function as bytes from disk. For the read-a-file case, import
+ * `readTextContent` from `@vibe-agent-toolkit/utils/fs`, which is this plus a
+ * `readFile`.
+ */
+export { decodeTextContent, TextTooLargeError, } from './text-content.js';
+//# sourceMappingURL=text.js.map

package/dist/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,iBAAiB,EAKjB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/timing-dump.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The on-disk plumbing every VAT timing seam shares.
+ *
+ * Two seams write per-process JSON dumps to an operator-named directory:
+ * `@vibe-agent-toolkit/resources`' `parse-timing.ts` (which pass inside a parser
+ * owns the time) and this package's `crawl-timing.ts` (which contributor or
+ * crawler owns the time). They sit in different packages because `crawl-timing`
+ * has to bracket `GitTracker`, which is here — so this module lives at the lower
+ * of the two and is exported for the higher one. What they
+ * MEASURE could not be less alike — one axis is a closed enum of parser passes,
+ * the other is an open set of contributor ids — but every property that makes
+ * the *file* trustworthy is identical between them, and the lab's
+ * `harness/dumps.ts` already says so from the reading end:
+ *
+ * 1. A directory that cannot be created is reported the moment the seam turns
+ *    on, while there is still a run to abandon — never at exit, where a failure
+ *    costs the whole measurement.
+ * 2. A dump failure is written to **stderr and never thrown**. These run from
+ *    an `exit` listener, where a throw changes the process's exit behaviour, and
+ *    they must never touch stdout, which carries vat's report.
+ * 3. A pid can file more than one dump, and the name is CLAIMED rather than
+ *    checked. `vat validate` spawns the vat binary once per phase and pids are
+ *    reused, so `<stem>-<pid>.json` genuinely collides; worse, worker threads
+ *    SHARE their parent's pid, so a thread pool's whole cohort competes for one
+ *    `<stem>-<pid>` sequence at the same instant. The name gains a counter
+ *    rather than overwriting, and the counter is settled by
+ *    {@link EXCLUSIVE_CREATE} so the OS — not a check-then-write gap — decides
+ *    who won it.
+ * 4. The process's own wall and CPU time is read ONCE, at dump time. It is a
+ *    lifetime figure for the process and never a duration of the measured work;
+ *    its value is the RATIO, which tells a reader whether the wall-timed
+ *    brackets above it were competing with a loaded machine.
+ *
+ *    ⚠️ **A reader must never SUM these across dumps.** Point 3 means one
+ *    command routinely files several, and a vat command's phase processes
+ *    overlap in time — so summing their lifetimes counts the same wall clock
+ *    more than once and produces a "total" longer than the command took. The
+ *    figure is per process, and the only honest aggregate over several is the
+ *    per-process ratio read one dump at a time. The `crawl` facet keeps one
+ *    record per dump and publishes no total for exactly this reason; `parse`
+ *    still sums, which is a known review finding annotated at
+ *    `facets/parse/dump.ts`. This list is where both seams learn what makes a
+ *    dump trustworthy, so the hazard belongs here rather than only beside the
+ *    consumer that already fixed it.
+ *
+ * Writing that twice would give two seams two chances to diverge on the one
+ * thing a reader has to be able to trust identically. What each seam keeps for
+ * itself is its accumulator shape, its dump body and the noun it is called by.
+ */
+/**
+ * Process-level wall and CPU time, read ONCE when a dump is written.
+ *
+ * All three are lifetime figures for the whole process, not for the measured
+ * work: the point of carrying them is the *ratio*. CPU well below wall means the
+ * process was waiting rather than computing, and every wall-timed bracket in the
+ * dump carries that waiting inside it. CPU above wall is normal and not an
+ * error — `process.cpuUsage()` sums every thread, including libuv's pool.
+ */
+export interface TimingProcess {
+    /** Wall clock since this process started. */
+    wallMs: number;
+    /** User CPU consumed by the process, across all its threads. */
+    cpuUserMs: number;
+    /** System CPU consumed by the process, across all its threads. */
+    cpuSystemMs: number;
+}
+/**
+ * Ceiling on the pid-collision search. A directory holding this many dumps for
+ * one pid is a runaway, not a collision, and giving up on a reported line is a
+ * better outcome than spinning.
+ *
+ * Exhausting it does NOT fall back to overwriting the last slot. That was the
+ * old behaviour, and it destroyed a dump for the same reason the check-then-
+ * write gap did — silently, and precisely when the directory was busiest.
+ */
+export declare const MAX_DUMP_COLLISIONS = 1000;
+/**
+ * Reduce a raw env value to a directory or `null`.
+ *
+ * An empty-string value counts as absent: `VAT_PARSE_TIMING=` in a shell profile
+ * is a variable somebody meant to unset, not a request to dump into the process's
+ * working directory.
+ *
+ * @param raw - The env var's value, if set
+ * @returns The dump directory, or `null` when the seam is off
+ */
+export declare function normalizeTimingDirectory(raw: string | undefined): string | null;
+/**
+ * Report a dump problem on stderr.
+ *
+ * Never throws and never touches stdout: vat's stdout carries a YAML report, and
+ * an exit handler that threw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, so a reader knows which instrument failed
+ * @param target - Path the failure concerns
+ * @param error - Whatever was caught
+ */
+export declare function reportTimingDumpFailure(noun: string, target: string, error: unknown): void;
+/**
+ * Create the dump directory, swallowing failure.
+ *
+ * Done once when the seam turns on rather than at exit, so a bad path is
+ * reported while there is still a run to abandon — and so the exit handler does
+ * the minimum possible work.
+ *
+ * @param noun - What the seam is called, for the failure line
+ * @param directory - Directory dumps will be written to
+ */
+export declare function ensureTimingDirectory(noun: string, directory: string): void;
+/**
+ * Read this process's lifetime wall and CPU time.
+ *
+ * Called ONCE per dump — two syscalls for a whole run, which is why the process
+ * level can afford a CPU reading that a per-bracket level cannot. Deliberately
+ * not an accumulator and deliberately not reset: it describes the process, not
+ * the measurement window.
+ *
+ * @returns Wall clock and CPU since process start, in milliseconds
+ */
+export declare function readTimingProcess(): TimingProcess;
+/**
+ * Write one seam's dump, if the seam is on.
+ *
+ * The body is built lazily, inside this call, so a disabled seam never pays to
+ * snapshot accumulators nobody will read — and a `build` that throws is reported
+ * like any other failure, because this runs from an `exit` listener where a
+ * throw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, for any failure line
+ * @param directory - Where to write, or `null` when the seam is off
+ * @param basename - Basename stem for the file
+ * @param build - Produces the dump body
+ * @returns The path written, or `null` when the seam is off or nothing was written
+ */
+export declare function writeTimingDump(noun: string, directory: string | null, basename: string, build: () => unknown): string | null;
+//# sourceMappingURL=timing-dump.d.ts.map

package/dist/timing-dump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing-dump.d.ts","sourceRoot":"","sources":["../src/timing-dump.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAOH;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AA6BxC;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAE/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAG1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAM3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,CAOjD;AAyDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,OAAO,GACnB,MAAM,GAAG,IAAI,CAoBf"}

package/dist/timing-dump.js

@@ -0,0 +1,229 @@
+/**
+ * The on-disk plumbing every VAT timing seam shares.
+ *
+ * Two seams write per-process JSON dumps to an operator-named directory:
+ * `@vibe-agent-toolkit/resources`' `parse-timing.ts` (which pass inside a parser
+ * owns the time) and this package's `crawl-timing.ts` (which contributor or
+ * crawler owns the time). They sit in different packages because `crawl-timing`
+ * has to bracket `GitTracker`, which is here — so this module lives at the lower
+ * of the two and is exported for the higher one. What they
+ * MEASURE could not be less alike — one axis is a closed enum of parser passes,
+ * the other is an open set of contributor ids — but every property that makes
+ * the *file* trustworthy is identical between them, and the lab's
+ * `harness/dumps.ts` already says so from the reading end:
+ *
+ * 1. A directory that cannot be created is reported the moment the seam turns
+ *    on, while there is still a run to abandon — never at exit, where a failure
+ *    costs the whole measurement.
+ * 2. A dump failure is written to **stderr and never thrown**. These run from
+ *    an `exit` listener, where a throw changes the process's exit behaviour, and
+ *    they must never touch stdout, which carries vat's report.
+ * 3. A pid can file more than one dump, and the name is CLAIMED rather than
+ *    checked. `vat validate` spawns the vat binary once per phase and pids are
+ *    reused, so `<stem>-<pid>.json` genuinely collides; worse, worker threads
+ *    SHARE their parent's pid, so a thread pool's whole cohort competes for one
+ *    `<stem>-<pid>` sequence at the same instant. The name gains a counter
+ *    rather than overwriting, and the counter is settled by
+ *    {@link EXCLUSIVE_CREATE} so the OS — not a check-then-write gap — decides
+ *    who won it.
+ * 4. The process's own wall and CPU time is read ONCE, at dump time. It is a
+ *    lifetime figure for the process and never a duration of the measured work;
+ *    its value is the RATIO, which tells a reader whether the wall-timed
+ *    brackets above it were competing with a loaded machine.
+ *
+ *    ⚠️ **A reader must never SUM these across dumps.** Point 3 means one
+ *    command routinely files several, and a vat command's phase processes
+ *    overlap in time — so summing their lifetimes counts the same wall clock
+ *    more than once and produces a "total" longer than the command took. The
+ *    figure is per process, and the only honest aggregate over several is the
+ *    per-process ratio read one dump at a time. The `crawl` facet keeps one
+ *    record per dump and publishes no total for exactly this reason; `parse`
+ *    still sums, which is a known review finding annotated at
+ *    `facets/parse/dump.ts`. This list is where both seams learn what makes a
+ *    dump trustworthy, so the hazard belongs here rather than only beside the
+ *    consumer that already fixed it.
+ *
+ * Writing that twice would give two seams two chances to diverge on the one
+ * thing a reader has to be able to trust identically. What each seam keeps for
+ * itself is its accumulator shape, its dump body and the noun it is called by.
+ */
+import { writeFileSync } from 'node:fs';
+import { safePath } from './path-core.js';
+import { mkdirSyncReal } from './path-utils.js';
+/** `process.cpuUsage()` reports microseconds; a dump reports milliseconds. */
+const MICROSECONDS_PER_MS = 1000;
+/** `process.uptime()` reports seconds; a dump reports milliseconds. */
+const MS_PER_SECOND = 1000;
+/**
+ * Ceiling on the pid-collision search. A directory holding this many dumps for
+ * one pid is a runaway, not a collision, and giving up on a reported line is a
+ * better outcome than spinning.
+ *
+ * Exhausting it does NOT fall back to overwriting the last slot. That was the
+ * old behaviour, and it destroyed a dump for the same reason the check-then-
+ * write gap did — silently, and precisely when the directory was busiest.
+ */
+export const MAX_DUMP_COLLISIONS = 1000;
+/**
+ * The `writeFileSync` flag that makes claiming a name atomic.
+ *
+ * `wx` is create-exclusive: the OS fails the call with `EEXIST` when the path
+ * already exists, so exactly one caller wins each name no matter how many are
+ * racing for it. Asking `existsSync` first and writing second is two operations
+ * with a gap in between, and threads sharing a pid land in that gap routinely —
+ * a measured 8-worker parse pool lost 6 of 9 dumps to it, reporting 44 of 172
+ * documents as if that were the whole run.
+ */
+const EXCLUSIVE_CREATE = 'wx';
+/** How the failure line names the ceiling case, so it reads unlike an OS error. */
+const CEILING_DETAIL = `every name up to the ${String(MAX_DUMP_COLLISIONS)}-collision ceiling was already claimed`;
+/**
+ * Reduce a raw env value to a directory or `null`.
+ *
+ * An empty-string value counts as absent: `VAT_PARSE_TIMING=` in a shell profile
+ * is a variable somebody meant to unset, not a request to dump into the process's
+ * working directory.
+ *
+ * @param raw - The env var's value, if set
+ * @returns The dump directory, or `null` when the seam is off
+ */
+export function normalizeTimingDirectory(raw) {
+    return raw === undefined || raw === '' ? null : raw;
+}
+/**
+ * Report a dump problem on stderr.
+ *
+ * Never throws and never touches stdout: vat's stdout carries a YAML report, and
+ * an exit handler that threw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, so a reader knows which instrument failed
+ * @param target - Path the failure concerns
+ * @param error - Whatever was caught
+ */
+export function reportTimingDumpFailure(noun, target, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`vat: ${noun} dump failed for ${target}: ${detail}\n`);
+}
+/**
+ * Create the dump directory, swallowing failure.
+ *
+ * Done once when the seam turns on rather than at exit, so a bad path is
+ * reported while there is still a run to abandon — and so the exit handler does
+ * the minimum possible work.
+ *
+ * @param noun - What the seam is called, for the failure line
+ * @param directory - Directory dumps will be written to
+ */
+export function ensureTimingDirectory(noun, directory) {
+    try {
+        mkdirSyncReal(directory, { recursive: true });
+    }
+    catch (error) {
+        reportTimingDumpFailure(noun, directory, error);
+    }
+}
+/**
+ * Read this process's lifetime wall and CPU time.
+ *
+ * Called ONCE per dump — two syscalls for a whole run, which is why the process
+ * level can afford a CPU reading that a per-bracket level cannot. Deliberately
+ * not an accumulator and deliberately not reset: it describes the process, not
+ * the measurement window.
+ *
+ * @returns Wall clock and CPU since process start, in milliseconds
+ */
+export function readTimingProcess() {
+    const cpu = process.cpuUsage();
+    return {
+        wallMs: process.uptime() * MS_PER_SECOND,
+        cpuUserMs: cpu.user / MICROSECONDS_PER_MS,
+        cpuSystemMs: cpu.system / MICROSECONDS_PER_MS,
+    };
+}
+/**
+ * The nth candidate name in one pid's dump sequence.
+ *
+ * @param directory - Directory dumps are written to
+ * @param stem - Basename and pid, already joined
+ * @param collision - 0 for the unsuffixed name, then the collision counter
+ * @returns The candidate path
+ */
+function timingDumpCandidate(directory, stem, collision) {
+    const suffix = collision === 0 ? '' : `-${String(collision)}`;
+    return safePath.join(directory, `${stem}${suffix}.json`);
+}
+/**
+ * Whether a caught write failure means somebody else already holds the name.
+ *
+ * @param error - Whatever `writeFileSync` threw
+ * @returns `true` only for `EEXIST`, which is a lost race and not a fault
+ */
+function isNameAlreadyTaken(error) {
+    return error instanceof Error && 'code' in error && error.code === 'EEXIST';
+}
+/**
+ * Claim a name by creating it, and fill it in the same operation.
+ *
+ * Choosing the name and writing it CANNOT be two steps: whatever separates them
+ * is a window in which another writer takes the name that was just declared
+ * free, and the loser's dump disappears with no error raised anywhere. So each
+ * candidate is written create-exclusively ({@link EXCLUSIVE_CREATE}) and an
+ * `EEXIST` — the OS saying somebody else got there — advances to the next
+ * counter rather than overwriting.
+ *
+ * @param directory - Directory dumps are written to
+ * @param basename - Basename stem; the pid and any collision counter follow
+ * @param contents - The already-serialized dump body
+ * @returns Which name was claimed, or why none could be
+ */
+function claimTimingDump(directory, basename, contents) {
+    const stem = `${basename}-${String(process.pid)}`;
+    for (let collision = 0; collision <= MAX_DUMP_COLLISIONS; collision += 1) {
+        const candidate = timingDumpCandidate(directory, stem, collision);
+        try {
+            writeFileSync(candidate, contents, { encoding: 'utf-8', flag: EXCLUSIVE_CREATE });
+            return { outcome: 'written', path: candidate };
+        }
+        catch (error) {
+            if (!isNameAlreadyTaken(error))
+                return { outcome: 'failed', path: candidate, error };
+        }
+    }
+    return {
+        outcome: 'exhausted',
+        path: timingDumpCandidate(directory, stem, MAX_DUMP_COLLISIONS),
+    };
+}
+/**
+ * Write one seam's dump, if the seam is on.
+ *
+ * The body is built lazily, inside this call, so a disabled seam never pays to
+ * snapshot accumulators nobody will read — and a `build` that throws is reported
+ * like any other failure, because this runs from an `exit` listener where a
+ * throw would change the process's exit behaviour.
+ *
+ * @param noun - What the seam is called, for any failure line
+ * @param directory - Where to write, or `null` when the seam is off
+ * @param basename - Basename stem for the file
+ * @param build - Produces the dump body
+ * @returns The path written, or `null` when the seam is off or nothing was written
+ */
+export function writeTimingDump(noun, directory, basename, build) {
+    if (directory === null)
+        return null;
+    let claim;
+    try {
+        claim = claimTimingDump(directory, basename, `${JSON.stringify(build(), null, 2)}\n`);
+    }
+    catch (error) {
+        // Only `build()` and its serialization can reach here; every filesystem
+        // failure is already an outcome rather than a throw.
+        reportTimingDumpFailure(noun, directory, error);
+        return null;
+    }
+    if (claim.outcome === 'written')
+        return claim.path;
+    reportTimingDumpFailure(noun, claim.path, claim.outcome === 'exhausted' ? CEILING_DETAIL : claim.error);
+    return null;
+}
+//# sourceMappingURL=timing-dump.js.map

package/dist/timing-dump.js.map

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

package/dist/windows-shell.d.ts

@@ -68,7 +68,6 @@ export declare function isPathLike(command: string): boolean;
  *
  * - Node.js deprecation: https://nodejs.org/api/deprecations.html#DEP0190
  * - Security tests: `packages/utils/test/safe-exec.test.ts`
- * - Windows fix: PR #94 (fix/windows-shell-independence-v2)
  *
  * @param commandPath - Resolved absolute path to command
  * @returns true if shell should be used, false otherwise

package/dist/windows-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"windows-shell.d.ts","sourceRoot":"","sources":["../src/windows-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAiB3D;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2BrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtF;AAsCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAWlF"}
+{"version":3,"file":"windows-shell.d.ts","sourceRoot":"","sources":["../src/windows-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAiB3D;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2BrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtF;AAsCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAWlF"}

package/dist/windows-shell.js

@@ -71,7 +71,6 @@ export function isPathLike(command) {
  *
  * - Node.js deprecation: https://nodejs.org/api/deprecations.html#DEP0190
  * - Security tests: `packages/utils/test/safe-exec.test.ts`
- * - Windows fix: PR #94 (fix/windows-shell-independence-v2)
  *
  * @param commandPath - Resolved absolute path to command
  * @returns true if shell should be used, false otherwise