@astrosheep/keiyaku 4.0.1 → 4.0.2

package/build/src/runtime/proc/run.js

@@ -1,5 +1,7 @@
-import { spawn, spawnSync } from "node:child_process";
-import { closeSync, openSync } from "node:fs";
+import { execFile, spawn } from "node:child_process";
+import { open } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
 const TERMINATION_GRACE_MS = 250;
 const STREAM_TAIL_BYTES = 16 * 1024;
 function tailCapture(limit) {
@@ -31,25 +33,21 @@ function tailCapture(limit) {
         },
     };
 }
-function wait(milliseconds) {
-    return new Promise((resolve) => setTimeout(resolve, milliseconds));
-}
 function ignoreMissingProcess(error) {
     if (error.code !== "ESRCH")
         throw error;
 }
-function terminateWindowsTree(pid) {
-    return new Promise((resolve) => {
-        const taskkill = spawn("taskkill", ["/PID", String(pid), "/T", "/F"], {
-            stdio: "ignore",
-            windowsHide: true,
-        });
-        taskkill.once("error", resolve);
-        taskkill.once("close", resolve);
+const WINDOWS_TERMINATION_TIMEOUT_MS = 1_000;
+const execFileAsync = promisify(execFile);
+async function terminateWindowsTree(pid) {
+    await execFileAsync("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        timeout: WINDOWS_TERMINATION_TIMEOUT_MS,
+        windowsHide: true,
     });
 }
-export async function terminateProcessTree(pid, force = false) {
-    if (pid === undefined)
+export async function terminateOwnedProcess(child, force = false) {
+    const pid = child.pid;
+    if (pid === undefined || child.exitCode !== null || child.signalCode !== null)
         return;
     if (process.platform === "win32") {
         await terminateWindowsTree(pid);
@@ -64,6 +62,11 @@ export async function terminateProcessTree(pid, force = false) {
         }
         return;
     }
+    let exited = false;
+    const exit = new Promise((resolve) => {
+        child.once("exit", () => { exited = true; resolve(); });
+        child.once("close", () => { exited = true; resolve(); });
+    });
     try {
         process.kill(-pid, "SIGTERM");
     }
@@ -71,7 +74,9 @@ export async function terminateProcessTree(pid, force = false) {
         ignoreMissingProcess(error);
         return;
     }
-    await wait(TERMINATION_GRACE_MS);
+    await Promise.race([exit, delay(TERMINATION_GRACE_MS)]);
+    if (exited || child.exitCode !== null || child.signalCode !== null)
+        return;
     try {
         process.kill(-pid, "SIGKILL");
     }
@@ -79,49 +84,14 @@ export async function terminateProcessTree(pid, force = false) {
         ignoreMissingProcess(error);
     }
 }
-function processStartToken(pid) {
-    const command = process.platform === "win32"
-        ? ["powershell.exe", "-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter \"ProcessId=${pid}\").CreationDate`]
-        : ["ps", "-o", "lstart=", "-p", String(pid)];
-    const result = spawnSync(command[0], command.slice(1), { encoding: "utf8", windowsHide: true });
-    const token = result.status === 0 ? result.stdout.trim() : "";
-    return token.length === 0 ? null : token;
-}
-export function currentProcessCollar() {
-    const identity = currentProcessIdentity();
-    return { ...identity, processGroup: identity.pid };
-}
-export function currentProcessIdentity() {
-    const spawnedAt = processStartToken(process.pid);
-    if (spawnedAt === null)
-        throw new Error(`cannot read process start identity for ${process.pid}`);
-    return { pid: process.pid, spawnedAt };
-}
-export function probeProcessIdentity(identity) {
-    try {
-        process.kill(identity.pid, 0);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === "ESRCH")
-            return { kind: "gone" };
-        return { kind: "unverifiable", diagnostic: error instanceof Error ? error.message : String(error) };
-    }
-    const current = processStartToken(identity.pid);
-    if (current === null)
-        return { kind: "unverifiable", diagnostic: `cannot read process start identity for ${identity.pid}` };
-    if (current === identity.spawnedAt)
-        return { kind: "alive" };
-    return { kind: "replaced" };
-}
 export async function spawnDetachedProcess(input) {
-    const log = openSync(input.log, "a");
+    const log = await open(input.log, "a");
     try {
         const child = spawn(input.argv[0], input.argv.slice(1), {
             cwd: input.cwd,
             env: input.env,
             detached: true,
-            stdio: ["ignore", log, log],
+            stdio: ["ignore", log.fd, log.fd],
             windowsHide: true,
         });
         await new Promise((resolve, reject) => {
@@ -130,48 +100,47 @@ export async function spawnDetachedProcess(input) {
         });
         if (child.pid === undefined)
             throw new Error("detached process spawned without a pid");
-        const spawnedAt = processStartToken(child.pid);
-        if (spawnedAt === null)
-            throw new Error(`cannot read process start identity for ${child.pid}`);
-        child.unref();
-        return { pid: child.pid, processGroup: child.pid, spawnedAt };
+        const pid = child.pid;
+        let state = "active";
+        let termination;
+        const invalidate = () => { state = "inert"; };
+        child.once("exit", invalidate);
+        child.once("close", invalidate);
+        return {
+            pid,
+            terminate(force = false) {
+                if (state === "inert")
+                    return Promise.resolve();
+                if (termination !== undefined)
+                    return termination;
+                state = "terminating";
+                termination = terminateOwnedProcess(child, force).finally(invalidate);
+                return termination;
+            },
+            release: () => {
+                if (state === "inert")
+                    return;
+                state = "inert";
+                child.unref();
+            },
+        };
     }
     finally {
-        closeSync(log);
-    }
-}
-export function probeProcessTree(collar) {
-    try {
-        process.kill(process.platform === "win32" ? collar.pid : -collar.processGroup, 0);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === "ESRCH")
-            return { kind: "gone" };
-        return { kind: "unverifiable", diagnostic: error instanceof Error ? error.message : String(error) };
+        await log.close();
     }
-    const current = processStartToken(collar.pid);
-    if (current === null && process.platform !== "win32")
-        return { kind: "alive" };
-    if (current === collar.spawnedAt)
-        return { kind: "alive" };
-    return { kind: "unverifiable", diagnostic: `process ${collar.pid} no longer matches its recorded start identity` };
 }
-export async function putDownProcessTree(collar) {
-    const before = probeProcessTree(collar);
-    if (before.kind === "gone")
-        return "already-dead";
-    if (before.kind === "unverifiable")
-        return "unavailable";
-    await terminateProcessTree(collar.pid);
-    const after = probeProcessTree(collar);
-    if (after.kind === "gone")
-        return "killed";
-    return after.kind === "alive" ? "alive-after-sigkill" : "unavailable";
+function terminalOutcome(code, stdout, stderr, consuming) {
+    return {
+        kind: "terminal",
+        code,
+        stdout: consuming ? "" : stdout.text,
+        stderr: stderr.text,
+        truncated: (consuming ? false : stdout.truncated) || stderr.truncated,
+    };
 }
-async function executeProcess(input, timeoutMs) {
+async function executeProcess(input, timeoutMs, consumeStdout) {
     if (input.signal?.aborted === true)
-        return { kind: "cancelled" };
+        return { outcome: { kind: "cancelled" }, pid: null };
     const child = spawn(input.argv[0], input.argv.slice(1), {
         cwd: input.cwd,
         env: input.env,
@@ -181,16 +150,38 @@ async function executeProcess(input, timeoutMs) {
     });
     const stdout = tailCapture(STREAM_TAIL_BYTES);
     const stderr = tailCapture(STREAM_TAIL_BYTES);
-    child.stdout.on("data", (chunk) => stdout.append(chunk));
-    child.stderr.on("data", (chunk) => stderr.append(chunk));
     let stop;
+    let streamError;
     let termination;
     const requestStop = (reason) => {
         if (stop !== undefined)
             return;
         stop = reason;
-        termination = terminateProcessTree(child.pid);
+        termination = terminateOwnedProcess(child);
+    };
+    const failStream = (error) => {
+        if (streamError !== undefined)
+            return;
+        streamError = error;
+        requestStop("cancelled");
     };
+    child.stdout.on("data", (chunk) => {
+        if (consumeStdout === undefined) {
+            stdout.append(chunk);
+            return;
+        }
+        try {
+            consumeStdout(chunk);
+        }
+        catch (error) {
+            failStream(error);
+        }
+    });
+    child.stderr.on("data", (chunk) => stderr.append(chunk));
+    if (consumeStdout !== undefined) {
+        child.stdout.once("error", failStream);
+        child.stderr.once("error", failStream);
+    }
     const cancel = () => requestStop("cancelled");
     input.signal?.addEventListener("abort", cancel, { once: true });
     const timeout = timeoutMs === undefined ? undefined : setTimeout(() => requestStop("timeout"), timeoutMs);
@@ -202,25 +193,42 @@ async function executeProcess(input, timeoutMs) {
         clearTimeout(timeout);
     input.signal?.removeEventListener("abort", cancel);
     await termination;
-    if (terminal.kind === "spawn-error")
-        return { kind: "spawn-error", diagnostic: terminal.error.message };
+    const pid = child.pid ?? null;
+    if (terminal.kind === "spawn-error") {
+        return { outcome: { kind: "spawn-error", diagnostic: terminal.error.message }, pid };
+    }
+    if (streamError !== undefined) {
+        return {
+            outcome: {
+                kind: "stream-error",
+                diagnostic: streamError instanceof Error ? streamError.message : String(streamError),
+            },
+            pid,
+        };
+    }
     if (stop !== undefined)
-        return { kind: stop };
+        return { outcome: { kind: stop }, pid };
     if (terminal.code === null)
-        return { kind: "unknown-exit" };
+        return { outcome: { kind: "unknown-exit" }, pid };
     const capturedStdout = stdout.result();
     const capturedStderr = stderr.result();
     return {
-        kind: "terminal",
-        code: terminal.code,
-        stdout: capturedStdout.text,
-        stderr: capturedStderr.text,
-        truncated: capturedStdout.truncated || capturedStderr.truncated,
+        outcome: terminalOutcome(terminal.code, capturedStdout, capturedStderr, consumeStdout !== undefined),
+        pid,
     };
 }
-export function runProcess(input) {
-    return executeProcess(input, input.timeoutMs);
+export async function runProcess(input) {
+    const result = await executeProcess(input, input.timeoutMs);
+    if (result.outcome.kind === "stream-error")
+        throw new Error("buffered process produced a stream consumer error");
+    return result.outcome;
+}
+export async function runProcessToExit(input) {
+    const result = await executeProcess(input, undefined);
+    if (result.outcome.kind === "stream-error")
+        throw new Error("buffered process produced a stream consumer error");
+    return result.outcome;
 }
-export function runProcessToExit(input) {
-    return executeProcess(input, undefined);
+export function consumeProcessStdout(input, consume) {
+    return executeProcess(input, input.timeoutMs, consume);
 }

package/build/src/runtime/proc/stdio.d.ts

@@ -0,0 +1,18 @@
+import type { Readable, Writable } from "node:stream";
+export type StdioProcessExit = Readonly<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stderr: string;
+}>;
+export type StdioProcess = Readonly<{
+    input: Writable;
+    output: Readable;
+    exited: Promise<StdioProcessExit>;
+    endInputAndDrain(timeoutMs?: number): Promise<void>;
+    close(force?: boolean): Promise<void>;
+}>;
+export declare function spawnStdioProcess(input: Readonly<{
+    argv: readonly [string, ...string[]];
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}>): StdioProcess;

package/build/src/runtime/proc/stdio.js

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { terminateOwnedProcess } from "./run.js";
+const DEFAULT_DRAIN_TIMEOUT_MS = 1_000;
+export function spawnStdioProcess(input) {
+    const child = spawn(input.argv[0], input.argv.slice(1), {
+        cwd: input.cwd,
+        env: input.env ?? process.env,
+        detached: true,
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let stderr = "";
+    let inputEnded = false;
+    let forced;
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => { stderr = `${stderr}${chunk}`.slice(-4_000); });
+    const exited = new Promise((resolve) => {
+        child.once("close", (code, signal) => resolve({ code, signal, stderr: stderr.trim() }));
+        child.once("error", (error) => resolve({ code: null, signal: null, stderr: error.message }));
+    });
+    const endInput = () => {
+        if (inputEnded)
+            return;
+        inputEnded = true;
+        child.stdin.end();
+    };
+    const forceClose = async () => {
+        forced ??= (async () => {
+            await terminateOwnedProcess(child, true);
+            await exited;
+        })();
+        await forced;
+    };
+    const endInputAndDrain = async (timeoutMs = DEFAULT_DRAIN_TIMEOUT_MS) => {
+        endInput();
+        if (forced !== undefined) {
+            await forced;
+            return;
+        }
+        const timedOut = await Promise.race([
+            exited.then(() => false),
+            delay(timeoutMs, true, { ref: false }),
+        ]);
+        if (timedOut)
+            await forceClose();
+    };
+    const close = async (force = false) => {
+        endInput();
+        if (force) {
+            await forceClose();
+            return;
+        }
+        await terminateOwnedProcess(child, false);
+        await exited;
+    };
+    return { input: child.stdin, output: child.stdout, exited, endInputAndDrain, close };
+}

package/build/src/settings.d.ts

@@ -46,6 +46,6 @@ export declare class SettingsError extends Error {
     readonly kind = "settings";
     constructor(message: string);
 }
-export declare function settings(input?: SettingsInput): Settings;
+export declare function settings(input?: SettingsInput): Promise<Settings>;
 /** Read only the project scope owned by a materialized candidate snapshot. */
-export declare function projectSettings(root: string): Settings;
+export declare function projectSettings(root: string): Promise<Settings>;

package/build/src/settings.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 export class SettingsError extends Error {
@@ -27,10 +27,10 @@ function freezeJson(value) {
 function bounded(error) {
     return (error instanceof Error ? error.message : String(error)).slice(0, 500);
 }
-function readScope(path) {
+async function readScope(path) {
     let bytes;
     try {
-        bytes = readFileSync(path, "utf8");
+        bytes = await readFile(path, "utf8");
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -91,7 +91,7 @@ function settingsFromScopes(project, user) {
         },
     });
 }
-export function settings(input = {}) {
+export async function settings(input = {}) {
     if (!object(input))
         throw new TypeError("settings input must be an object");
     if (input.root !== undefined && (typeof input.root !== "string" || input.root.trim().length === 0)) {
@@ -102,13 +102,13 @@ export function settings(input = {}) {
     }
     const project = input.root === undefined
         ? { state: { kind: "absent" } }
-        : readScope(join(resolve(input.root), ".keiyaku", "settings.json"));
-    const user = readScope(join(resolve(input.home ?? join(homedir(), ".keiyaku")), "settings.json"));
+        : await readScope(join(resolve(input.root), ".keiyaku", "settings.json"));
+    const user = await readScope(join(resolve(input.home ?? join(homedir(), ".keiyaku")), "settings.json"));
     return settingsFromScopes(project, user);
 }
 /** Read only the project scope owned by a materialized candidate snapshot. */
-export function projectSettings(root) {
+export async function projectSettings(root) {
     if (typeof root !== "string" || root.trim().length === 0)
         throw new TypeError("settings root must be a nonblank string");
-    return settingsFromScopes(readScope(join(resolve(root), ".keiyaku", "settings.json")), { state: { kind: "absent" } });
+    return settingsFromScopes(await readScope(join(resolve(root), ".keiyaku", "settings.json")), { state: { kind: "absent" } });
 }

package/build/src/settlement/fence.d.ts

@@ -3,7 +3,3 @@ import { type GitRepository } from "../git/repository.js";
 import type { TaskId } from "../task/identity.js";
 export declare function settlementFencePath(repository: GitRepository, taskId: TaskId): string;
 export declare function acquireTaskSettlementFence(repository: GitRepository, taskId: TaskId): Promise<HeldSqliteTransactionLock>;
-export declare function withTaskSettlementFence<T>(input: Readonly<{
-    repository: GitRepository;
-    taskId: TaskId;
-}>, action: () => T | Promise<T>): Promise<T>;

package/build/src/settlement/fence.js

@@ -12,12 +12,3 @@ export function acquireTaskSettlementFence(repository, taskId) {
         mode: "immediate",
     });
 }
-export async function withTaskSettlementFence(input, action) {
-    const held = await acquireTaskSettlementFence(input.repository, input.taskId);
-    try {
-        return await action();
-    }
-    finally {
-        held.close();
-    }
-}

package/build/src/settlement/holder.d.ts

@@ -1,7 +1,7 @@
 import type { TreeUpdate } from "../core/facts/offer.js";
 import { type ContractId } from "../core/facts/types.js";
 import type { GitDecisionObservation } from "../git/observe.js";
-import type { GitRepository } from "../git/repository.js";
+import { type GitRepository } from "../git/repository.js";
 import { type GitDecodeChannel, type GitReadObservation, type GitTreeSelection } from "../git/read-observation.js";
 import { type TaskId } from "../task/identity.js";
 export declare function taskHolderObservationSelection(): GitTreeSelection;
@@ -28,6 +28,16 @@ export type TaskHolderAdmission<T extends AdmissionOutcome> = Readonly<{
 export declare function finishTaskHolderAdmission<T extends AdmissionOutcome>(taskId: TaskId, result: T, close: () => void): TaskHolderAdmission<T>;
 export declare function claimTaskHolderWithFence<T extends AdmissionOutcome>(repository: GitRepository, taskId: TaskId, action: () => T | Promise<T>): Promise<TaskHolderAdmission<T>>;
 export declare function releaseTaskHolder(channel: GitDecodeChannel, observation: GitDecisionObservation, owner: ContractId): Promise<TreeUpdate | null>;
+export type TaskHolderReleasePublication = Readonly<{
+    kind: "released";
+}> | Readonly<{
+    kind: "not-held";
+}> | Readonly<{
+    kind: "non-published";
+    diagnostic: string;
+}>;
+/** Publish the released holder against the same frozen observation that decided the release. */
+export declare function publishTaskHolderRelease(repository: GitRepository, channel: GitDecodeChannel, observation: GitDecisionObservation, owner: ContractId): Promise<TaskHolderReleasePublication>;
 export declare function readTaskHolderProjectionFromDecision(channel: GitDecodeChannel, observation: GitDecisionObservation): Promise<TaskHolderProjection>;
 export declare function observeTaskHolderProjection(repository: GitRepository, channel: GitDecodeChannel): Promise<TaskHolderProjection>;
 export declare function releaseTaskHolderWithFence<T extends AdmissionOutcome>(repository: GitRepository, channel: GitDecodeChannel, owner: ContractId, action: () => T | Promise<T>): Promise<TaskHolderAdmission<T>>;

package/build/src/settlement/holder.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { contractId } from "../core/facts/types.js";
+import { GIT_REF, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "../git/repository.js";
 import { withGitTargetedReadObservation, } from "../git/read-observation.js";
 import { parseTaskId } from "../task/identity.js";
 import { acquireTaskSettlementFence } from "./fence.js";
@@ -120,6 +121,30 @@ export async function releaseTaskHolder(channel, observation, owner) {
         ? null
         : update({ ...current, disposition: "released" });
 }
+/** Publish the released holder against the same frozen observation that decided the release. */
+export async function publishTaskHolderRelease(repository, channel, observation, owner) {
+    const release = await releaseTaskHolder(channel, observation, owner);
+    if (release === null)
+        return { kind: "not-held" };
+    const tree = await updateGitTree(repository, observation.admission.snapshot.tree, new Map([[release.path, { oid: await writeBlob(repository, release.bytes) }]]));
+    const commit = await writeCommit({
+        repository,
+        tree,
+        parent: observation.admission.snapshot.commit,
+        message: `release held Task completion: ${owner}`,
+    });
+    const publication = await updateRefsAtomically(repository, [{
+            ref: GIT_REF,
+            newOid: commit,
+            expectedOid: observation.admission.snapshot.commit,
+        }]);
+    if (publication.kind === "published")
+        return { kind: "released" };
+    return {
+        kind: "non-published",
+        diagnostic: publication.kind === "non-published" ? detail(publication.error) : "Task holder release publication state is unknown",
+    };
+}
 export async function readTaskHolderProjectionFromDecision(channel, observation) {
     const read = {
         snapshot: observation.admission.snapshot,

package/build/src/settlement/settle.d.ts

@@ -6,7 +6,7 @@ import type { TaskId } from "../task/identity.js";
 export type SettlementAction = Readonly<{
     kind: "task";
     taskId: TaskId;
-    action: "done" | "reopened";
+    action: "done";
 }> | Readonly<{
     kind: "namespace-context";
     path: string;