@mikode13/harness 4.0.1 → 5.1.0

package/dist/tools/infrastructure/commandCheckpoint.d.ts

@@ -0,0 +1,55 @@
+import type { FileState, RunJournal } from '#src/recovery/domain/recoveryStore';
+/**
+ * Every file a command's checkpoint covers now, by its real path, absolute: what `.gitignore`
+ * does not exclude in the `write` roots, less what the access policy closes to writing by name.
+ */
+export type CoveredFiles = (signal: AbortSignal) => Promise<string[]>;
+/** A file a command changed, as the checkpoint found it. */
+export interface ObservedChange {
+    path: string;
+    before: FileState;
+    after: FileState;
+}
+/**
+ * The files a command may change, captured right before it runs and compared right after, so
+ * what it changed is in the run's history like any tool's change, and can be undone.
+ *
+ * `begin` stores the content of every covered file and a manifest of them, then records the
+ * observation in the journal; if any of that fails, the command must not run. `end` lists the
+ * covered files again, and records each one that differs from the manifest as a change made by
+ * the command. This first version reads and hashes everything both times, trusting neither size
+ * nor modification time, and keeps what that cost with the observation.
+ */
+export declare class CommandCheckpoint {
+    private readonly journal;
+    private readonly covered;
+    private readonly by;
+    private readonly manifest;
+    /** Covered files it could not copy before, which it leaves out after too. */
+    private readonly uncopyable;
+    private readonly sequence;
+    private readonly measure;
+    private constructor();
+    /** Captures every covered file. Cancelling it, or any failure, leaves the command unstarted. */
+    static begin({ journal, covered, by, signal, }: {
+        journal: RunJournal;
+        covered: CoveredFiles;
+        /** The command, as the history will name it. */
+        by: string;
+        signal: AbortSignal;
+    }): Promise<CommandCheckpoint>;
+    /**
+     * Compares the covered files with the capture and records every change found. It is never
+     * cancelled: once the command has run, what it changed must reach the history. Unless
+     * `complete`, the observation stays open, because the command may still be changing files.
+     *
+     * @returns the changes, and the paths it could not record because they are now something the
+     * history cannot copy, such as a file the command replaced with a folder, or made too large.
+     */
+    end({ complete }: {
+        complete: boolean;
+    }): Promise<{
+        changes: ObservedChange[];
+        unrecorded: string[];
+    }>;
+}

package/dist/tools/infrastructure/commandCheckpoint.js

@@ -0,0 +1,178 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile } from 'node:fs/promises';
+import { sameState } from '#src/recovery/domain/fileChanges';
+// The same bound the history uses for a file it records: a larger one is not copied.
+const maxCoveredBytes = 64 * 1024 * 1024;
+const captureConcurrency = 16;
+function code(error) {
+    return error.code;
+}
+/**
+ * The files a command may change, captured right before it runs and compared right after, so
+ * what it changed is in the run's history like any tool's change, and can be undone.
+ *
+ * `begin` stores the content of every covered file and a manifest of them, then records the
+ * observation in the journal; if any of that fails, the command must not run. `end` lists the
+ * covered files again, and records each one that differs from the manifest as a change made by
+ * the command. This first version reads and hashes everything both times, trusting neither size
+ * nor modification time, and keeps what that cost with the observation.
+ */
+export class CommandCheckpoint {
+    journal;
+    covered;
+    by;
+    manifest;
+    /** Covered files it could not copy before, which it leaves out after too. */
+    uncopyable;
+    sequence;
+    measure;
+    constructor(fields) {
+        this.journal = fields.journal;
+        this.covered = fields.covered;
+        this.by = fields.by;
+        this.manifest = fields.manifest;
+        this.uncopyable = fields.uncopyable;
+        this.sequence = fields.sequence;
+        this.measure = fields.measure;
+    }
+    /** Captures every covered file. Cancelling it, or any failure, leaves the command unstarted. */
+    static async begin({ journal, covered, by, signal, }) {
+        const started = performance.now();
+        const storedBefore = journal.storedBytes;
+        const paths = await covered(signal);
+        const states = [];
+        const uncopyable = new Set();
+        let bytesRead = 0;
+        // Several at once: each stored content waits for its own sync, which dominates the time.
+        await eachAtOnce(paths, captureConcurrency, async (path, index) => {
+            signal.throwIfAborted();
+            const read = await readState(path);
+            // A folder, a link or a file too large: no entry records it, so it is not covered.
+            if (!read) {
+                uncopyable.add(path);
+                return;
+            }
+            if (read.content) {
+                bytesRead += read.content.length;
+                const hash = await journal.saveContent(read.content);
+                states[index] = { exists: true, hash, mode: read.mode };
+            }
+        });
+        const files = {};
+        paths.forEach((path, index) => {
+            const state = states[index];
+            if (state)
+                files[path] = state;
+        });
+        const manifest = { files };
+        const hash = await journal.saveContent(Buffer.from(JSON.stringify(manifest)));
+        signal.throwIfAborted();
+        const sequence = await journal.observe(hash, by);
+        return new CommandCheckpoint({
+            journal,
+            covered,
+            by,
+            manifest,
+            uncopyable,
+            sequence,
+            measure: { bytesRead, durationMs: performance.now() - started, storedBefore },
+        });
+    }
+    /**
+     * Compares the covered files with the capture and records every change found. It is never
+     * cancelled: once the command has run, what it changed must reach the history. Unless
+     * `complete`, the observation stays open, because the command may still be changing files.
+     *
+     * @returns the changes, and the paths it could not record because they are now something the
+     * history cannot copy, such as a file the command replaced with a folder, or made too large.
+     */
+    async end({ complete }) {
+        const started = performance.now();
+        const signal = new AbortController().signal;
+        const paths = new Set([...Object.keys(this.manifest.files), ...(await this.covered(signal))]);
+        const changes = [];
+        const unrecorded = [];
+        let bytesRead = this.measure.bytesRead;
+        for (const path of paths) {
+            const before = this.manifest.files[path] ?? { exists: false };
+            const read = await readState(path);
+            if (!read) {
+                // One it could not copy before either, such as a file over the size limit, is not
+                // covered at all; one it could is now something no entry records.
+                if (!this.uncopyable.has(path))
+                    unrecorded.push(path);
+                continue;
+            }
+            let after = { exists: false };
+            if (read.content) {
+                bytesRead += read.content.length;
+                const hash = createHash('sha256').update(read.content).digest('hex');
+                after = { exists: true, hash, mode: read.mode };
+            }
+            if (sameState(before, after))
+                continue;
+            // Stored only now that it changed, so an unchanged file costs no write.
+            if (read.content)
+                await this.journal.saveContent(read.content);
+            const sequence = await this.journal.prepare({ path, before, after, observedBy: this.by });
+            await this.journal.applied(sequence);
+            changes.push({ path, before, after });
+        }
+        // Left open when something the command started may still be running: the record then says
+        // that what it changed may not all be here.
+        if (!complete)
+            return { changes, unrecorded };
+        await this.journal.observed(this.sequence, {
+            files: paths.size,
+            bytesRead,
+            bytesStored: this.journal.storedBytes - this.measure.storedBefore,
+            durationMs: Math.round(this.measure.durationMs + performance.now() - started),
+        });
+        return { changes, unrecorded };
+    }
+}
+/**
+ * What `path` holds: nothing, or a regular file's content and mode. `undefined` for anything an
+ * entry cannot record: a folder, a link, or a file too large to copy.
+ */
+async function readState(path) {
+    let stats;
+    try {
+        stats = await lstat(path);
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT')
+            return { mode: 0 };
+        throw error;
+    }
+    if (!stats.isFile() || stats.size > maxCoveredBytes)
+        return undefined;
+    try {
+        return { content: await readFile(path), mode: stats.mode & 0o7777 };
+    }
+    catch (error) {
+        // Deleted between the two calls.
+        if (code(error) === 'ENOENT')
+            return { mode: 0 };
+        throw error;
+    }
+}
+/** Runs `task` on every item, at most `limit` at a time, and fails with the first failure. */
+async function eachAtOnce(items, limit, task) {
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < items.length) {
+            const index = next++;
+            try {
+                await task(items[index], index);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+//# sourceMappingURL=commandCheckpoint.js.map

package/dist/tools/infrastructure/commandCheckpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandCheckpoint.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/commandCheckpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAG7D,qFAAqF;AACrF,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACzC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAe9B,SAAS,IAAI,CAAC,KAAc;IAC3B,OAAQ,KAA+B,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,iBAAiB;IACZ,OAAO,CAAa;IACpB,OAAO,CAAe;IACtB,EAAE,CAAS;IACX,QAAQ,CAAW;IACpC,6EAA6E;IAC5D,UAAU,CAAsB;IAChC,QAAQ,CAAS;IACjB,OAAO,CAAkE;IAE1F,YAAoB,MAQnB;QACA,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,CAAC;IAED,gGAAgG;IAChG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAClB,OAAO,EACP,OAAO,EACP,EAAE,EACF,MAAM,GAON;QACA,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;QACzC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAA8B,EAAE,CAAC;QAC7C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,yFAAyF;QACzF,MAAM,UAAU,CAAC,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YACjE,MAAM,CAAC,cAAc,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;YACnC,mFAAmF;YACnF,IAAI,CAAC,IAAI,EAAE,CAAC;gBACX,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACrB,OAAO;YACR,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClB,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;gBACjC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACrD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;YACzD,CAAC;QACF,CAAC,CAAC,CAAC;QACH,MAAM,KAAK,GAAsB,EAAE,CAAC;QACpC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5B,IAAI,KAAK;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAChC,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAa,EAAE,KAAK,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACjD,OAAO,IAAI,iBAAiB,CAAC;YAC5B,OAAO;YACP,OAAO;YACP,EAAE;YACF,QAAQ;YACR,UAAU;YACV,QAAQ;YACR,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE;SAC7E,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAyB;QAI5C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC,MAAM,CAAC;QAC5C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9F,MAAM,OAAO,GAAqB,EAAE,CAAC;QACrC,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;QAEvC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,MAAM,GAAc,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACzE,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACX,kFAAkF;gBAClF,kEAAkE;gBAClE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtD,SAAS;YACV,CAAC;YACD,IAAI,KAAK,GAAc,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClB,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;gBACjC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACrE,KAAK,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;YACjD,CAAC;YACD,IAAI,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;gBAAE,SAAS;YACvC,wEAAwE;YACxE,IAAI,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1F,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACvC,CAAC;QAED,0FAA0F;QAC1F,4CAA4C;QAC5C,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;QAC9C,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC1C,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,SAAS;YACT,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY;YACjE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;SAC7E,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IAChC,CAAC;CACD;AAED;;;GAGG;AACH,KAAK,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,KAAK,CAAC;IACV,IAAI,CAAC;QACJ,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,CAAC;IACb,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,GAAG,eAAe;QAAE,OAAO,SAAS,CAAC;IACtE,IAAI,CAAC;QACJ,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,GAAG,MAAM,EAAE,CAAC;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,iCAAiC;QACjC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACjD,MAAM,KAAK,CAAC;IACb,CAAC;AACF,CAAC;AAED,8FAA8F;AAC9F,KAAK,UAAU,UAAU,CACxB,KAAsB,EACtB,KAAa,EACb,IAAkD;IAElD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,MAAM,GAAG,KAAK,IAAI,EAAE;QACzB,OAAO,CAAC,MAAM,IAAI,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC;YACrB,IAAI,CAAC;gBACJ,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAS,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,GAAG,IAAI,CAAC;gBACd,MAAM,KAAK,CAAC;YACb,CAAC;QACF,CAAC;IACF,CAAC,CAAC;IACF,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;AAClF,CAAC","sourcesContent":["import { createHash } from 'node:crypto';\nimport { lstat, readFile } from 'node:fs/promises';\nimport { sameState } from '#src/recovery/domain/fileChanges';\nimport type { FileState, Manifest, RunJournal } from '#src/recovery/domain/recoveryStore';\n\n// The same bound the history uses for a file it records: a larger one is not copied.\nconst maxCoveredBytes = 64 * 1024 * 1024;\nconst captureConcurrency = 16;\n\n/**\n * Every file a command's checkpoint covers now, by its real path, absolute: what `.gitignore`\n * does not exclude in the `write` roots, less what the access policy closes to writing by name.\n */\nexport type CoveredFiles = (signal: AbortSignal) => Promise<string[]>;\n\n/** A file a command changed, as the checkpoint found it. */\nexport interface ObservedChange {\n\tpath: string;\n\tbefore: FileState;\n\tafter: FileState;\n}\n\nfunction code(error: unknown): string | undefined {\n\treturn (error as NodeJS.ErrnoException).code;\n}\n\n/**\n * The files a command may change, captured right before it runs and compared right after, so\n * what it changed is in the run's history like any tool's change, and can be undone.\n *\n * `begin` stores the content of every covered file and a manifest of them, then records the\n * observation in the journal; if any of that fails, the command must not run. `end` lists the\n * covered files again, and records each one that differs from the manifest as a change made by\n * the command. This first version reads and hashes everything both times, trusting neither size\n * nor modification time, and keeps what that cost with the observation.\n */\nexport class CommandCheckpoint {\n\tprivate readonly journal: RunJournal;\n\tprivate readonly covered: CoveredFiles;\n\tprivate readonly by: string;\n\tprivate readonly manifest: Manifest;\n\t/** Covered files it could not copy before, which it leaves out after too. */\n\tprivate readonly uncopyable: ReadonlySet<string>;\n\tprivate readonly sequence: number;\n\tprivate readonly measure: { bytesRead: number; durationMs: number; storedBefore: number };\n\n\tprivate constructor(fields: {\n\t\tjournal: RunJournal;\n\t\tcovered: CoveredFiles;\n\t\tby: string;\n\t\tmanifest: Manifest;\n\t\tuncopyable: ReadonlySet<string>;\n\t\tsequence: number;\n\t\tmeasure: { bytesRead: number; durationMs: number; storedBefore: number };\n\t}) {\n\t\tthis.journal = fields.journal;\n\t\tthis.covered = fields.covered;\n\t\tthis.by = fields.by;\n\t\tthis.manifest = fields.manifest;\n\t\tthis.uncopyable = fields.uncopyable;\n\t\tthis.sequence = fields.sequence;\n\t\tthis.measure = fields.measure;\n\t}\n\n\t/** Captures every covered file. Cancelling it, or any failure, leaves the command unstarted. */\n\tstatic async begin({\n\t\tjournal,\n\t\tcovered,\n\t\tby,\n\t\tsignal,\n\t}: {\n\t\tjournal: RunJournal;\n\t\tcovered: CoveredFiles;\n\t\t/** The command, as the history will name it. */\n\t\tby: string;\n\t\tsignal: AbortSignal;\n\t}): Promise<CommandCheckpoint> {\n\t\tconst started = performance.now();\n\t\tconst storedBefore = journal.storedBytes;\n\t\tconst paths = await covered(signal);\n\t\tconst states: (FileState | undefined)[] = [];\n\t\tconst uncopyable = new Set<string>();\n\t\tlet bytesRead = 0;\n\t\t// Several at once: each stored content waits for its own sync, which dominates the time.\n\t\tawait eachAtOnce(paths, captureConcurrency, async (path, index) => {\n\t\t\tsignal.throwIfAborted();\n\t\t\tconst read = await readState(path);\n\t\t\t// A folder, a link or a file too large: no entry records it, so it is not covered.\n\t\t\tif (!read) {\n\t\t\t\tuncopyable.add(path);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (read.content) {\n\t\t\t\tbytesRead += read.content.length;\n\t\t\t\tconst hash = await journal.saveContent(read.content);\n\t\t\t\tstates[index] = { exists: true, hash, mode: read.mode };\n\t\t\t}\n\t\t});\n\t\tconst files: Manifest['files'] = {};\n\t\tpaths.forEach((path, index) => {\n\t\t\tconst state = states[index];\n\t\t\tif (state) files[path] = state;\n\t\t});\n\t\tconst manifest: Manifest = { files };\n\t\tconst hash = await journal.saveContent(Buffer.from(JSON.stringify(manifest)));\n\t\tsignal.throwIfAborted();\n\t\tconst sequence = await journal.observe(hash, by);\n\t\treturn new CommandCheckpoint({\n\t\t\tjournal,\n\t\t\tcovered,\n\t\t\tby,\n\t\t\tmanifest,\n\t\t\tuncopyable,\n\t\t\tsequence,\n\t\t\tmeasure: { bytesRead, durationMs: performance.now() - started, storedBefore },\n\t\t});\n\t}\n\n\t/**\n\t * Compares the covered files with the capture and records every change found. It is never\n\t * cancelled: once the command has run, what it changed must reach the history. Unless\n\t * `complete`, the observation stays open, because the command may still be changing files.\n\t *\n\t * @returns the changes, and the paths it could not record because they are now something the\n\t * history cannot copy, such as a file the command replaced with a folder, or made too large.\n\t */\n\tasync end({ complete }: { complete: boolean }): Promise<{\n\t\tchanges: ObservedChange[];\n\t\tunrecorded: string[];\n\t}> {\n\t\tconst started = performance.now();\n\t\tconst signal = new AbortController().signal;\n\t\tconst paths = new Set([...Object.keys(this.manifest.files), ...(await this.covered(signal))]);\n\t\tconst changes: ObservedChange[] = [];\n\t\tconst unrecorded: string[] = [];\n\t\tlet bytesRead = this.measure.bytesRead;\n\n\t\tfor (const path of paths) {\n\t\t\tconst before: FileState = this.manifest.files[path] ?? { exists: false };\n\t\t\tconst read = await readState(path);\n\t\t\tif (!read) {\n\t\t\t\t// One it could not copy before either, such as a file over the size limit, is not\n\t\t\t\t// covered at all; one it could is now something no entry records.\n\t\t\t\tif (!this.uncopyable.has(path)) unrecorded.push(path);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tlet after: FileState = { exists: false };\n\t\t\tif (read.content) {\n\t\t\t\tbytesRead += read.content.length;\n\t\t\t\tconst hash = createHash('sha256').update(read.content).digest('hex');\n\t\t\t\tafter = { exists: true, hash, mode: read.mode };\n\t\t\t}\n\t\t\tif (sameState(before, after)) continue;\n\t\t\t// Stored only now that it changed, so an unchanged file costs no write.\n\t\t\tif (read.content) await this.journal.saveContent(read.content);\n\t\t\tconst sequence = await this.journal.prepare({ path, before, after, observedBy: this.by });\n\t\t\tawait this.journal.applied(sequence);\n\t\t\tchanges.push({ path, before, after });\n\t\t}\n\n\t\t// Left open when something the command started may still be running: the record then says\n\t\t// that what it changed may not all be here.\n\t\tif (!complete) return { changes, unrecorded };\n\t\tawait this.journal.observed(this.sequence, {\n\t\t\tfiles: paths.size,\n\t\t\tbytesRead,\n\t\t\tbytesStored: this.journal.storedBytes - this.measure.storedBefore,\n\t\t\tdurationMs: Math.round(this.measure.durationMs + performance.now() - started),\n\t\t});\n\t\treturn { changes, unrecorded };\n\t}\n}\n\n/**\n * What `path` holds: nothing, or a regular file's content and mode. `undefined` for anything an\n * entry cannot record: a folder, a link, or a file too large to copy.\n */\nasync function readState(path: string): Promise<{ content?: Buffer; mode: number } | undefined> {\n\tlet stats;\n\ttry {\n\t\tstats = await lstat(path);\n\t} catch (error) {\n\t\tif (code(error) === 'ENOENT') return { mode: 0 };\n\t\tthrow error;\n\t}\n\tif (!stats.isFile() || stats.size > maxCoveredBytes) return undefined;\n\ttry {\n\t\treturn { content: await readFile(path), mode: stats.mode & 0o7777 };\n\t} catch (error) {\n\t\t// Deleted between the two calls.\n\t\tif (code(error) === 'ENOENT') return { mode: 0 };\n\t\tthrow error;\n\t}\n}\n\n/** Runs `task` on every item, at most `limit` at a time, and fails with the first failure. */\nasync function eachAtOnce<Item>(\n\titems: readonly Item[],\n\tlimit: number,\n\ttask: (item: Item, index: number) => Promise<void>,\n): Promise<void> {\n\tlet next = 0;\n\tlet failed = false;\n\tconst worker = async () => {\n\t\twhile (!failed && next < items.length) {\n\t\t\tconst index = next++;\n\t\t\ttry {\n\t\t\t\tawait task(items[index] as Item, index);\n\t\t\t} catch (error) {\n\t\t\t\tfailed = true;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t};\n\tawait Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));\n}\n"]}

package/dist/tools/infrastructure/commandProcess.d.ts

@@ -0,0 +1,47 @@
+/**
+ * How a command ended:
+ * - `exited`: it ended by itself, with `exitCode`, or killed by `signal` from outside.
+ * - `timedOut`: it ran past its time and was stopped.
+ * - `cancelled`: the run was cancelled while it ran, and it was stopped.
+ */
+export interface CommandProcessResult {
+    outcome: 'exited' | 'timedOut' | 'cancelled';
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    /** The end of what it printed, standard output and error together, as they arrived. */
+    output: string;
+    /** Everything it printed, of which `output` is the end. */
+    printedBytes: number;
+    durationMs: number;
+    /**
+     * Every process of its group is gone. When false, something it started may still be
+     * changing files, so nothing observed after it can be taken as its final effect.
+     */
+    stopped: boolean;
+}
+/**
+ * Runs a configured command in a process group of its own, never through a shell, and returns
+ * once that group is gone. A timeout or a cancellation stops the whole group: first asked with
+ * `SIGTERM`, then killed. A command that ends by itself has whatever it left running in its
+ * group stopped too, so nothing it started outlives it. A process that leaves the group, as a
+ * daemon does, is out of reach; the docs say so.
+ *
+ * Only for POSIX: Windows has no process groups to stop.
+ *
+ * @throws {Error} when the program cannot be started, such as when it is not found; nothing ran.
+ */
+export declare function runCommandProcess(executable: string, args: string[], { cwd, env, timeoutMs, outputBytes, signal, gracePeriodMs, killWaitMs, recheckMs, }: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    outputBytes: number;
+    signal: AbortSignal;
+    /** How long the group gets to stop on `SIGTERM` before it is killed. Defaults to 5 s. */
+    gracePeriodMs?: number;
+    /** How long a killed group gets to disappear before it counts as unconfirmed. 5 s. */
+    killWaitMs?: number;
+    /** How often an unconfirmed group is asked about again. Defaults to 1 s. */
+    recheckMs?: number;
+}): Promise<CommandProcessResult>;
+/** The groups of the commands still running, for tests. */
+export declare function liveGroupIds(): number[];

package/dist/tools/infrastructure/commandProcess.js

@@ -0,0 +1,217 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+// How long a group asked to stop gets before it is killed, and how long a kill gets to take.
+const defaultGracePeriodMs = 5_000;
+const defaultKillWaitMs = 5_000;
+const pollMs = 25;
+// Output still in the pipes once every process is gone arrives at once; a process that left
+// the group and holds a pipe open must not hold up the result.
+const drainMs = 1_000;
+/**
+ * Runs a configured command in a process group of its own, never through a shell, and returns
+ * once that group is gone. A timeout or a cancellation stops the whole group: first asked with
+ * `SIGTERM`, then killed. A command that ends by itself has whatever it left running in its
+ * group stopped too, so nothing it started outlives it. A process that leaves the group, as a
+ * daemon does, is out of reach; the docs say so.
+ *
+ * Only for POSIX: Windows has no process groups to stop.
+ *
+ * @throws {Error} when the program cannot be started, such as when it is not found; nothing ran.
+ */
+export function runCommandProcess(executable, args, { cwd, env, timeoutMs, outputBytes, signal, gracePeriodMs = defaultGracePeriodMs, killWaitMs = defaultKillWaitMs, recheckMs = defaultRecheckMs, }) {
+    // A rejection, not a throw: a caller awaiting the result must see it as one.
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    const started = performance.now();
+    return new Promise((resolve, reject) => {
+        // `detached` makes it the leader of a new process group, whose id is its pid.
+        const child = spawn(executable, args, {
+            cwd,
+            env,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (child.pid !== undefined)
+            watchForExit(child.pid);
+        const tail = new OutputTail(outputBytes);
+        let outcome = 'exited';
+        let stopping;
+        let exit;
+        const streamsClosed = Promise.all([child.stdout, child.stderr].map(stream => new Promise(done => stream.once('close', () => {
+            done();
+        }))));
+        child.stdout.on('data', (chunk) => {
+            tail.push(chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            tail.push(chunk);
+        });
+        const stop = (why) => {
+            // The first reason stands: a timeout during a cancellation's grace period is still a
+            // cancellation, and must end the run as one.
+            if (exit || stopping || child.pid === undefined)
+                return;
+            outcome = why;
+            detach();
+            stopping = stopGroup(child.pid, { gracePeriodMs, killWaitMs });
+            // A leader that outlives even the kill never exits, so the result cannot wait for it.
+            void stopping.then(gone => {
+                if (!gone)
+                    void finish(false);
+            });
+        };
+        const timer = setTimeout(() => {
+            stop('timedOut');
+        }, timeoutMs);
+        const onAbort = () => {
+            stop('cancelled');
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        const detach = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+        };
+        let finished = false;
+        const finish = async (stopped) => {
+            if (finished)
+                return;
+            finished = true;
+            detach();
+            if (child.pid !== undefined) {
+                if (stopped)
+                    liveGroups.delete(child.pid);
+                else
+                    forgetWhenGone(child.pid, recheckMs);
+            }
+            await Promise.race([streamsClosed, delay(drainMs)]);
+            child.stdout.destroy();
+            child.stderr.destroy();
+            resolve({
+                outcome,
+                exitCode: exit?.code ?? null,
+                signal: exit?.signal ?? null,
+                output: tail.text(),
+                printedBytes: tail.total,
+                durationMs: Math.round(performance.now() - started),
+                stopped,
+            });
+        };
+        child.once('error', error => {
+            // Only a program that never started: nothing here signals the child through Node.
+            if (child.pid !== undefined)
+                return;
+            detach();
+            reject(error);
+        });
+        child.once('exit', (code, exitSignal) => {
+            exit = { code, signal: exitSignal };
+            detach();
+            const pid = child.pid;
+            // What it left in its group is stopped as well; an empty group is gone at once.
+            void (stopping ??
+                (pid === undefined ? Promise.resolve(true) : stopGroup(pid, { gracePeriodMs, killWaitMs }))).then(finish);
+        });
+    });
+}
+/**
+ * The groups of the commands still running. If this process exits while one runs, as on an
+ * uncaught exception, each is killed on the way out: nothing would be left to stop it or
+ * record what it changed. A process killed by a signal gets no such chance, and its commands
+ * then run on until they end.
+ */
+const liveGroups = new Set();
+let exitHookInstalled = false;
+const defaultRecheckMs = 1_000;
+/** The groups of the commands still running, for tests. */
+export function liveGroupIds() {
+    return [...liveGroups];
+}
+/**
+ * Keeps an unconfirmed group in `liveGroups` until the system says it is gone, then forgets
+ * it: once the group is empty its id can be given to another, which the exit hook must never
+ * kill. It asks every second, so a reuse in between is the only gap; nothing short of a pidfd
+ * closes it.
+ */
+function forgetWhenGone(pgid, intervalMs) {
+    const timer = setInterval(() => {
+        if (signalGroup(pgid, 0))
+            return;
+        liveGroups.delete(pgid);
+        clearInterval(timer);
+    }, intervalMs);
+    // It must not keep this process alive on its own.
+    timer.unref();
+}
+function watchForExit(pgid) {
+    liveGroups.add(pgid);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.once('exit', () => {
+        for (const group of liveGroups)
+            signalGroup(group, 'SIGKILL');
+    });
+}
+/**
+ * Stops every process in the group `pgid` and waits until none is left. Whether it is gone is
+ * asked of the system, never assumed from a signal being sent.
+ *
+ * @returns whether the group is confirmed gone.
+ */
+async function stopGroup(pgid, { gracePeriodMs, killWaitMs }) {
+    if (!signalGroup(pgid, 'SIGTERM'))
+        return true;
+    if (await goneWithin(pgid, gracePeriodMs))
+        return true;
+    if (!signalGroup(pgid, 'SIGKILL'))
+        return true;
+    return goneWithin(pgid, killWaitMs);
+}
+/** Sends `signal` to the group; false when the group no longer exists. */
+function signalGroup(pgid, signal) {
+    try {
+        process.kill(-pgid, signal);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        // EPERM: a process of the group exists, but this one may not signal it.
+        return true;
+    }
+}
+async function goneWithin(pgid, ms) {
+    const deadline = performance.now() + ms;
+    while (performance.now() < deadline) {
+        if (!signalGroup(pgid, 0))
+            return true;
+        await delay(pollMs);
+    }
+    return !signalGroup(pgid, 0);
+}
+/** Keeps only the last `limit` bytes of what is pushed, and counts all of it. */
+class OutputTail {
+    limit;
+    chunks = [];
+    kept = 0;
+    total = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    push(chunk) {
+        this.total += chunk.length;
+        this.chunks.push(chunk);
+        this.kept += chunk.length;
+        while (this.chunks.length > 1 && this.kept - (this.chunks[0]?.length ?? 0) >= this.limit) {
+            this.kept -= this.chunks.shift()?.length ?? 0;
+        }
+    }
+    text() {
+        const all = Buffer.concat(this.chunks);
+        const cut = all.length > this.limit;
+        const text = (cut ? all.subarray(all.length - this.limit) : all).toString('utf8');
+        // A cut can land inside a character, which decodes as replacement characters.
+        return cut ? text.replace(/^�+/u, '') : text;
+    }
+}
+//# sourceMappingURL=commandProcess.js.map

package/dist/tools/infrastructure/commandProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandProcess.js","sourceRoot":"","sources":["../../../src/tools/infrastructure/commandProcess.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'node:child_process';\nimport { setTimeout as delay } from 'node:timers/promises';\n\n// How long a group asked to stop gets before it is killed, and how long a kill gets to take.\nconst defaultGracePeriodMs = 5_000;\nconst defaultKillWaitMs = 5_000;\nconst pollMs = 25;\n// Output still in the pipes once every process is gone arrives at once; a process that left\n// the group and holds a pipe open must not hold up the result.\nconst drainMs = 1_000;\n\n/**\n * How a command ended:\n * - `exited`: it ended by itself, with `exitCode`, or killed by `signal` from outside.\n * - `timedOut`: it ran past its time and was stopped.\n * - `cancelled`: the run was cancelled while it ran, and it was stopped.\n */\nexport interface CommandProcessResult {\n\toutcome: 'exited' | 'timedOut' | 'cancelled';\n\texitCode: number | null;\n\tsignal: NodeJS.Signals | null;\n\t/** The end of what it printed, standard output and error together, as they arrived. */\n\toutput: string;\n\t/** Everything it printed, of which `output` is the end. */\n\tprintedBytes: number;\n\tdurationMs: number;\n\t/**\n\t * Every process of its group is gone. When false, something it started may still be\n\t * changing files, so nothing observed after it can be taken as its final effect.\n\t */\n\tstopped: boolean;\n}\n\n/**\n * Runs a configured command in a process group of its own, never through a shell, and returns\n * once that group is gone. A timeout or a cancellation stops the whole group: first asked with\n * `SIGTERM`, then killed. A command that ends by itself has whatever it left running in its\n * group stopped too, so nothing it started outlives it. A process that leaves the group, as a\n * daemon does, is out of reach; the docs say so.\n *\n * Only for POSIX: Windows has no process groups to stop.\n *\n * @throws {Error} when the program cannot be started, such as when it is not found; nothing ran.\n */\nexport function runCommandProcess(\n\texecutable: string,\n\targs: string[],\n\t{\n\t\tcwd,\n\t\tenv,\n\t\ttimeoutMs,\n\t\toutputBytes,\n\t\tsignal,\n\t\tgracePeriodMs = defaultGracePeriodMs,\n\t\tkillWaitMs = defaultKillWaitMs,\n\t\trecheckMs = defaultRecheckMs,\n\t}: {\n\t\tcwd: string;\n\t\tenv: NodeJS.ProcessEnv;\n\t\ttimeoutMs: number;\n\t\toutputBytes: number;\n\t\tsignal: AbortSignal;\n\t\t/** How long the group gets to stop on `SIGTERM` before it is killed. Defaults to 5 s. */\n\t\tgracePeriodMs?: number;\n\t\t/** How long a killed group gets to disappear before it counts as unconfirmed. 5 s. */\n\t\tkillWaitMs?: number;\n\t\t/** How often an unconfirmed group is asked about again. Defaults to 1 s. */\n\t\trecheckMs?: number;\n\t},\n): Promise<CommandProcessResult> {\n\t// A rejection, not a throw: a caller awaiting the result must see it as one.\n\tif (signal.aborted) return Promise.reject(signal.reason as Error);\n\tconst started = performance.now();\n\n\treturn new Promise((resolve, reject) => {\n\t\t// `detached` makes it the leader of a new process group, whose id is its pid.\n\t\tconst child = spawn(executable, args, {\n\t\t\tcwd,\n\t\t\tenv,\n\t\t\tdetached: true,\n\t\t\tstdio: ['ignore', 'pipe', 'pipe'],\n\t\t});\n\t\tif (child.pid !== undefined) watchForExit(child.pid);\n\t\tconst tail = new OutputTail(outputBytes);\n\t\tlet outcome: CommandProcessResult['outcome'] = 'exited';\n\t\tlet stopping: Promise<boolean> | undefined;\n\t\tlet exit: { code: number | null; signal: NodeJS.Signals | null } | undefined;\n\n\t\tconst streamsClosed = Promise.all(\n\t\t\t[child.stdout, child.stderr].map(\n\t\t\t\tstream =>\n\t\t\t\t\tnew Promise<void>(done =>\n\t\t\t\t\t\tstream.once('close', () => {\n\t\t\t\t\t\t\tdone();\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\tchild.stdout.on('data', (chunk: Buffer) => {\n\t\t\ttail.push(chunk);\n\t\t});\n\t\tchild.stderr.on('data', (chunk: Buffer) => {\n\t\t\ttail.push(chunk);\n\t\t});\n\n\t\tconst stop = (why: 'timedOut' | 'cancelled'): void => {\n\t\t\t// The first reason stands: a timeout during a cancellation's grace period is still a\n\t\t\t// cancellation, and must end the run as one.\n\t\t\tif (exit || stopping || child.pid === undefined) return;\n\t\t\toutcome = why;\n\t\t\tdetach();\n\t\t\tstopping = stopGroup(child.pid, { gracePeriodMs, killWaitMs });\n\t\t\t// A leader that outlives even the kill never exits, so the result cannot wait for it.\n\t\t\tvoid stopping.then(gone => {\n\t\t\t\tif (!gone) void finish(false);\n\t\t\t});\n\t\t};\n\t\tconst timer = setTimeout(() => {\n\t\t\tstop('timedOut');\n\t\t}, timeoutMs);\n\t\tconst onAbort = () => {\n\t\t\tstop('cancelled');\n\t\t};\n\t\tsignal.addEventListener('abort', onAbort, { once: true });\n\t\tconst detach = () => {\n\t\t\tclearTimeout(timer);\n\t\t\tsignal.removeEventListener('abort', onAbort);\n\t\t};\n\n\t\tlet finished = false;\n\t\tconst finish = async (stopped: boolean) => {\n\t\t\tif (finished) return;\n\t\t\tfinished = true;\n\t\t\tdetach();\n\t\t\tif (child.pid !== undefined) {\n\t\t\t\tif (stopped) liveGroups.delete(child.pid);\n\t\t\t\telse forgetWhenGone(child.pid, recheckMs);\n\t\t\t}\n\t\t\tawait Promise.race([streamsClosed, delay(drainMs)]);\n\t\t\tchild.stdout.destroy();\n\t\t\tchild.stderr.destroy();\n\t\t\tresolve({\n\t\t\t\toutcome,\n\t\t\t\texitCode: exit?.code ?? null,\n\t\t\t\tsignal: exit?.signal ?? null,\n\t\t\t\toutput: tail.text(),\n\t\t\t\tprintedBytes: tail.total,\n\t\t\t\tdurationMs: Math.round(performance.now() - started),\n\t\t\t\tstopped,\n\t\t\t});\n\t\t};\n\n\t\tchild.once('error', error => {\n\t\t\t// Only a program that never started: nothing here signals the child through Node.\n\t\t\tif (child.pid !== undefined) return;\n\t\t\tdetach();\n\t\t\treject(error);\n\t\t});\n\t\tchild.once('exit', (code, exitSignal) => {\n\t\t\texit = { code, signal: exitSignal };\n\t\t\tdetach();\n\t\t\tconst pid = child.pid;\n\t\t\t// What it left in its group is stopped as well; an empty group is gone at once.\n\t\t\tvoid (\n\t\t\t\tstopping ??\n\t\t\t\t(pid === undefined ? Promise.resolve(true) : stopGroup(pid, { gracePeriodMs, killWaitMs }))\n\t\t\t).then(finish);\n\t\t});\n\t});\n}\n\n/**\n * The groups of the commands still running. If this process exits while one runs, as on an\n * uncaught exception, each is killed on the way out: nothing would be left to stop it or\n * record what it changed. A process killed by a signal gets no such chance, and its commands\n * then run on until they end.\n */\nconst liveGroups = new Set<number>();\nlet exitHookInstalled = false;\n\nconst defaultRecheckMs = 1_000;\n\n/** The groups of the commands still running, for tests. */\nexport function liveGroupIds(): number[] {\n\treturn [...liveGroups];\n}\n\n/**\n * Keeps an unconfirmed group in `liveGroups` until the system says it is gone, then forgets\n * it: once the group is empty its id can be given to another, which the exit hook must never\n * kill. It asks every second, so a reuse in between is the only gap; nothing short of a pidfd\n * closes it.\n */\nfunction forgetWhenGone(pgid: number, intervalMs: number): void {\n\tconst timer = setInterval(() => {\n\t\tif (signalGroup(pgid, 0)) return;\n\t\tliveGroups.delete(pgid);\n\t\tclearInterval(timer);\n\t}, intervalMs);\n\t// It must not keep this process alive on its own.\n\ttimer.unref();\n}\n\nfunction watchForExit(pgid: number): void {\n\tliveGroups.add(pgid);\n\tif (exitHookInstalled) return;\n\texitHookInstalled = true;\n\tprocess.once('exit', () => {\n\t\tfor (const group of liveGroups) signalGroup(group, 'SIGKILL');\n\t});\n}\n\n/**\n * Stops every process in the group `pgid` and waits until none is left. Whether it is gone is\n * asked of the system, never assumed from a signal being sent.\n *\n * @returns whether the group is confirmed gone.\n */\nasync function stopGroup(\n\tpgid: number,\n\t{ gracePeriodMs, killWaitMs }: { gracePeriodMs: number; killWaitMs: number },\n): Promise<boolean> {\n\tif (!signalGroup(pgid, 'SIGTERM')) return true;\n\tif (await goneWithin(pgid, gracePeriodMs)) return true;\n\tif (!signalGroup(pgid, 'SIGKILL')) return true;\n\treturn goneWithin(pgid, killWaitMs);\n}\n\n/** Sends `signal` to the group; false when the group no longer exists. */\nfunction signalGroup(pgid: number, signal: NodeJS.Signals | 0): boolean {\n\ttry {\n\t\tprocess.kill(-pgid, signal);\n\t\treturn true;\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === 'ESRCH') return false;\n\t\t// EPERM: a process of the group exists, but this one may not signal it.\n\t\treturn true;\n\t}\n}\n\nasync function goneWithin(pgid: number, ms: number): Promise<boolean> {\n\tconst deadline = performance.now() + ms;\n\twhile (performance.now() < deadline) {\n\t\tif (!signalGroup(pgid, 0)) return true;\n\t\tawait delay(pollMs);\n\t}\n\treturn !signalGroup(pgid, 0);\n}\n\n/** Keeps only the last `limit` bytes of what is pushed, and counts all of it. */\nclass OutputTail {\n\tprivate readonly limit: number;\n\tprivate chunks: Buffer[] = [];\n\tprivate kept = 0;\n\ttotal = 0;\n\n\tconstructor(limit: number) {\n\t\tthis.limit = limit;\n\t}\n\n\tpush(chunk: Buffer): void {\n\t\tthis.total += chunk.length;\n\t\tthis.chunks.push(chunk);\n\t\tthis.kept += chunk.length;\n\t\twhile (this.chunks.length > 1 && this.kept - (this.chunks[0]?.length ?? 0) >= this.limit) {\n\t\t\tthis.kept -= this.chunks.shift()?.length ?? 0;\n\t\t}\n\t}\n\n\ttext(): string {\n\t\tconst all = Buffer.concat(this.chunks);\n\t\tconst cut = all.length > this.limit;\n\t\tconst text = (cut ? all.subarray(all.length - this.limit) : all).toString('utf8');\n\t\t// A cut can land inside a character, which decodes as replacement characters.\n\t\treturn cut ? text.replace(/^�+/u, '') : text;\n\t}\n}\n"]}

package/dist/tools/infrastructure/commandTool.d.ts

@@ -0,0 +1,36 @@
+import type { AccessPolicy } from '../domain/accessPolicy.ts';
+import { type CommandDefinition, type Commands } from '../domain/commands.ts';
+import { type PreparingTool } from '../domain/preparedCall.ts';
+import { type CoveredFiles } from './commandCheckpoint.ts';
+import { runCommandProcess } from './commandProcess.ts';
+import type { WorkspaceWrites } from './workspaceWrites.ts';
+/**
+ * `runCommand`, which runs one of the commands the consumer configured, by name, with the
+ * parameters each one declares. Every call asks the approver, showing the program exactly as
+ * it will run; `autoApprove` skips that.
+ *
+ * Around each command, the covered files are captured before and compared after, so what it
+ * changed is in the run's history and can be undone: see `CommandCheckpoint`. If the capture
+ * fails, the command does not run. A timeout or a cancellation stops its whole process group,
+ * and is never reported as a completed command. If the group cannot be confirmed stopped, what
+ * changed so far is recorded, the observation stays open, and writing stops for the run.
+ *
+ * This is not a sandbox: a command runs the repository's code, with everything this user can
+ * reach. See "Configured commands are trusted, not sandboxed" in decisions.md.
+ *
+ * @throws {InvalidAgentConfigError} for an invalid configuration, a working directory outside
+ * every `write` root, or on Windows, where a process group cannot be stopped.
+ */
+export declare function createCommandTool({ commands, policy, writes, covered, base, platform, runProcess, }: {
+    commands: Commands;
+    policy: AccessPolicy;
+    writes: WorkspaceWrites;
+    covered: CoveredFiles;
+    /** The real path of the first root, where a relative `cwd` starts. */
+    base: string;
+    platform?: NodeJS.Platform;
+    /** Runs the program. Replaced in tests, to reach what a real process rarely does. */
+    runProcess?: typeof runCommandProcess;
+}): Promise<PreparingTool>;
+/** A small environment of its own: the inherited few, then what the consumer set. */
+export declare function environmentFor(definition: CommandDefinition, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;