@smithers-orchestrator/engine 0.16.0

package/src/effect/diff-bundle.js

@@ -0,0 +1,352 @@
+import { applyPatch as applyUnifiedPatch } from "diff";
+import { spawn } from "node:child_process";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/** @typedef {import("./DiffBundle.ts").DiffBundle} DiffBundle */
+/** @typedef {import("./FilePatch.ts").FilePatch} FilePatch */
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {{ input?: string; allowExitCodes?: ReadonlySet<number>; }} [options]
+ * @returns {Promise<GitCommandResult>}
+ */
+async function runGit(cwd, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", args, {
+            cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.once("error", reject);
+        child.once("close", (code) => {
+            const allowExitCodes = options?.allowExitCodes;
+            if (code === 0 || (typeof code === "number" && allowExitCodes?.has(code))) {
+                resolve({ stdout, stderr });
+                return;
+            }
+            reject(new SmithersError("INVALID_INPUT", `git ${args.join(" ")} failed`, { cwd, args, code, stderr: stderr.trim(), stdout: stdout.trim() }));
+        });
+        if (options?.input) {
+            child.stdin.write(options.input);
+        }
+        child.stdin.end();
+    });
+}
+/**
+ * @param {string} diff
+ * @returns {string[]}
+ */
+function splitGitDiff(diff) {
+    const normalized = diff.trim();
+    if (normalized.length === 0) {
+        return [];
+    }
+    return normalized
+        .split(/^diff --git /m)
+        .filter((chunk) => chunk.length > 0)
+        .map((chunk) => `diff --git ${chunk}`.trimEnd() + "\n");
+}
+/**
+ * @param {string} chunk
+ * @returns {string}
+ */
+function extractPatchPath(chunk) {
+    const renameTo = chunk.match(/^rename to (.+)$/m)?.[1];
+    if (renameTo) {
+        return renameTo.trim();
+    }
+    const plusPath = chunk.match(/^\+\+\+ b\/(.+)$/m)?.[1];
+    if (plusPath) {
+        return plusPath.trim();
+    }
+    const minusPath = chunk.match(/^--- a\/(.+)$/m)?.[1];
+    if (minusPath) {
+        return minusPath.trim();
+    }
+    const diffHeader = chunk.match(/^diff --git a\/(.+?) b\/(.+)$/m);
+    if (diffHeader) {
+        return diffHeader[2].trim();
+    }
+    throw new SmithersError("INVALID_INPUT", "Unable to determine file path from diff chunk", { chunk: chunk.slice(0, 200) });
+}
+/**
+ * @param {string} chunk
+ * @returns {FilePatch["operation"]}
+ */
+function extractOperation(chunk) {
+    if (/^new file mode /m.test(chunk)) {
+        return "add";
+    }
+    if (/^deleted file mode /m.test(chunk)) {
+        return "delete";
+    }
+    return "modify";
+}
+/**
+ * @param {string} chunk
+ * @returns {boolean}
+ */
+function isBinaryPatch(chunk) {
+    return /(^GIT binary patch$)|(^Binary files )/m.test(chunk);
+}
+/**
+ * @param {string} path
+ * @returns {Promise<boolean>}
+ */
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * @param {string} baseRef
+ * @param {string} currentDir
+ * @returns {Promise<Set<string>>}
+ */
+async function listBinaryPaths(baseRef, currentDir) {
+    const { stdout } = await runGit(currentDir, [
+        "diff",
+        "--numstat",
+        "--find-renames=100%",
+        baseRef,
+        "--",
+        ".",
+    ]);
+    const binaryPaths = new Set();
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const [added, removed, ...rest] = trimmed.split("\t");
+        if (added === "-" && removed === "-" && rest.length > 0) {
+            binaryPaths.add(rest.join("\t"));
+        }
+    }
+    return binaryPaths;
+}
+/**
+ * @param {string} currentDir
+ * @returns {Promise<string[]>}
+ */
+async function listUntrackedFiles(currentDir) {
+    const { stdout } = await runGit(currentDir, [
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "--",
+        ".",
+    ]);
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+/**
+ * @param {string} currentDir
+ * @returns {Promise<string[]>}
+ */
+async function computeUntrackedDiffs(currentDir) {
+    const untracked = await listUntrackedFiles(currentDir);
+    const diffs = [];
+    for (const relativePath of untracked) {
+        const { stdout } = await runGit(currentDir, ["diff", "--no-index", "--binary", "--", "/dev/null", relativePath], { allowExitCodes: new Set([1]) });
+        if (stdout.trim().length > 0) {
+            diffs.push(stdout.trimEnd() + "\n");
+        }
+    }
+    return diffs;
+}
+/**
+ * Compute a diff bundle strictly between two immutable refs.
+ *
+ * Unlike {@link computeDiffBundle}, this variant does NOT read the working
+ * tree or untracked files. It is the preferred entry point for historical
+ * diffs (e.g. the `getNodeDiff` RPC) because it is read-only and cannot be
+ * contaminated by concurrent runs mutating the checkout.
+ *
+ * @param {string} baseRef
+ * @param {string} targetRef
+ * @param {string} currentDir
+ * @param {number} [seq]
+ * @returns {Promise<DiffBundle>}
+ */
+export async function computeDiffBundleBetweenRefs(baseRef, targetRef, currentDir, seq = 1) {
+    const [{ stdout: trackedDiff }, { stdout: numstat }] = await Promise.all([
+        runGit(currentDir, [
+            "diff",
+            "--binary",
+            "--find-renames=100%",
+            "--no-ext-diff",
+            baseRef,
+            targetRef,
+            "--",
+            ".",
+        ]),
+        runGit(currentDir, [
+            "diff",
+            "--numstat",
+            "--find-renames=100%",
+            baseRef,
+            targetRef,
+            "--",
+            ".",
+        ]),
+    ]);
+    const binaryPaths = new Set();
+    for (const line of numstat.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const [added, removed, ...rest] = trimmed.split("\t");
+        if (added === "-" && removed === "-" && rest.length > 0) {
+            binaryPaths.add(rest.join("\t"));
+        }
+    }
+    const patches = [];
+    const chunks = splitGitDiff(trackedDiff);
+    for (const chunk of chunks) {
+        const path = extractPatchPath(chunk);
+        const operation = extractOperation(chunk);
+        const binary = isBinaryPatch(chunk) || binaryPaths.has(path);
+        let binaryContent;
+        if (binary && operation !== "delete") {
+            try {
+                const { stdout } = await runGit(currentDir, [
+                    "show",
+                    `${targetRef}:${path}`,
+                ]);
+                binaryContent = Buffer.from(stdout, "binary").toString("base64");
+            }
+            catch {
+                // File may not be readable as a blob at targetRef; fall through
+                // without binaryContent. Caller receives operation + diff only.
+                binaryContent = undefined;
+            }
+        }
+        patches.push({
+            path,
+            operation,
+            diff: chunk,
+            binaryContent,
+        });
+    }
+    return {
+        seq,
+        baseRef,
+        patches,
+    };
+}
+/**
+ * @param {string} baseRef
+ * @param {string} currentDir
+ * @returns {Promise<DiffBundle>}
+ */
+export async function computeDiffBundle(baseRef, currentDir, seq = 1) {
+    const [{ stdout: trackedDiff }, binaryPaths, untrackedDiffs] = await Promise.all([
+        runGit(currentDir, [
+            "diff",
+            "--binary",
+            "--find-renames=100%",
+            "--no-ext-diff",
+            baseRef,
+            "--",
+            ".",
+        ]),
+        listBinaryPaths(baseRef, currentDir),
+        computeUntrackedDiffs(currentDir),
+    ]);
+    const patches = [];
+    const chunks = [
+        ...splitGitDiff(trackedDiff),
+        ...untrackedDiffs.flatMap(splitGitDiff),
+    ];
+    for (const chunk of chunks) {
+        const path = extractPatchPath(chunk);
+        const operation = extractOperation(chunk);
+        const binary = isBinaryPatch(chunk) || binaryPaths.has(path);
+        const fullPath = join(currentDir, path);
+        patches.push({
+            path,
+            operation,
+            diff: chunk,
+            binaryContent: binary && operation !== "delete" && await fileExists(fullPath)
+                ? (await readFile(fullPath)).toString("base64")
+                : undefined,
+        });
+    }
+    return {
+        seq,
+        baseRef,
+        patches,
+    };
+}
+/**
+ * @param {FilePatch} patch
+ * @param {string} targetDir
+ * @returns {Promise<void>}
+ */
+async function applyPatchFallback(patch, targetDir) {
+    const targetPath = join(targetDir, patch.path);
+    const targetExists = await fileExists(targetPath);
+    if (patch.binaryContent) {
+        if (patch.operation === "delete") {
+            await rm(targetPath, { force: true });
+            return;
+        }
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, Buffer.from(patch.binaryContent, "base64"));
+        return;
+    }
+    if (patch.operation === "delete" && !targetExists) {
+        return;
+    }
+    const current = patch.operation === "add" || !targetExists
+        ? ""
+        : await readFile(targetPath, "utf8");
+    const updated = applyUnifiedPatch(current, patch.diff);
+    if (updated === false) {
+        throw new SmithersError("TOOL_PATCH_FAILED", `Failed to apply patch for ${patch.path}`, { path: patch.path, operation: patch.operation });
+    }
+    if (patch.operation === "delete") {
+        await rm(targetPath, { force: true });
+        return;
+    }
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, updated, "utf8");
+}
+/**
+ * @param {DiffBundle} bundle
+ * @param {string} targetDir
+ * @returns {Promise<void>}
+ */
+export async function applyDiffBundle(bundle, targetDir) {
+    if (bundle.patches.length === 0) {
+        return;
+    }
+    await mkdir(targetDir, { recursive: true });
+    const fullPatch = bundle.patches.map((patch) => patch.diff).join("");
+    try {
+        await runGit(targetDir, ["apply", "--binary", "--whitespace=nowarn", "--unsafe-paths", "-"], { input: fullPatch });
+        return;
+    }
+    catch (error) {
+        for (const patch of bundle.patches) {
+            await applyPatchFallback(patch, targetDir);
+        }
+    }
+}

package/src/effect/durable-deferred-bridge.js

@@ -0,0 +1,282 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./ApprovalDurableDeferredResolution.ts").ApprovalDurableDeferredResolution} ApprovalDurableDeferredResolution */
+/** @typedef {import("./WaitForEventDurableDeferredResolution.ts").WaitForEventDurableDeferredResolution} WaitForEventDurableDeferredResolution */
+// @smithers-type-exports-end
+
+import * as DurableDeferred from "@effect/workflow/DurableDeferred";
+import * as Workflow from "@effect/workflow/Workflow";
+import { resolve as resolvePath } from "node:path";
+import { Effect, Exit, Schema } from "effect";
+import { updateAsyncExternalWaitPending } from "@smithers-orchestrator/observability/metrics";
+/**
+ * @typedef {{ _tag: "Complete"; exit: Exit.Exit<any, any>; } | { _tag: "Pending"; }} BridgeDeferredResult
+ */
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} _SmithersDb */
+/**
+ * @typedef {{ signalName: string; correlationId: string | null; payloadJson: string; seq: number; receivedAtMs: number; }} WaitForEventSignalInput
+ */
+
+export const DurableDeferredBridgeWorkflow = Workflow.make({
+    name: "SmithersDurableDeferredBridge",
+    payload: { executionId: Schema.String },
+    success: Schema.Unknown,
+    idempotencyKey: ({ executionId }) => executionId,
+});
+const adapterNamespaces = new WeakMap();
+let nextAdapterNamespace = 0;
+/**
+ * @param {_SmithersDb} adapter
+ * @returns {string}
+ */
+const getAdapterNamespace = (adapter) => {
+    const filename = adapter?.db?.$client?.filename;
+    if (typeof filename === "string" && filename.length > 0 && filename !== ":memory:") {
+        return `sqlite:${resolvePath(filename)}`;
+    }
+    const existing = adapterNamespaces.get(adapter);
+    if (existing) {
+        return existing;
+    }
+    const created = `adapter-${++nextAdapterNamespace}`;
+    adapterNamespaces.set(adapter, created);
+    return created;
+};
+export const approvalDurableDeferredSuccessSchema = Schema.Struct({
+    approved: Schema.Boolean,
+    note: Schema.NullOr(Schema.String),
+    decidedBy: Schema.NullOr(Schema.String),
+    decisionJson: Schema.NullOr(Schema.String),
+    autoApproved: Schema.Boolean,
+});
+export const waitForEventDurableDeferredSuccessSchema = Schema.Struct({
+    signalName: Schema.String,
+    correlationId: Schema.NullOr(Schema.String),
+    payloadJson: Schema.String,
+    seq: Schema.Number,
+    receivedAtMs: Schema.Number,
+});
+/**
+ * @param {string | null | undefined} value
+ * @returns {string | null}
+ */
+function normalizeCorrelationId(value) {
+    const normalized = typeof value === "string" ? value.trim() : "";
+    return normalized.length > 0 ? normalized : null;
+}
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function parseOptionalFiniteNumber(value) {
+    if (value == null || value === "") {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * @param {string | null} [metaJson]
+ * @returns {WaitForEventAttemptSnapshot | null}
+ */
+function parseWaitForEventAttemptSnapshot(metaJson) {
+    if (!metaJson)
+        return null;
+    try {
+        const parsed = JSON.parse(metaJson);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        const waitForEvent = parsed?.waitForEvent;
+        if (!waitForEvent || typeof waitForEvent !== "object" || Array.isArray(waitForEvent)) {
+            return null;
+        }
+        const signalName = typeof waitForEvent.signalName === "string"
+            ? waitForEvent.signalName.trim()
+            : "";
+        if (!signalName) {
+            return null;
+        }
+        return {
+            meta: parsed,
+            signalName,
+            correlationId: normalizeCorrelationId(waitForEvent.correlationId),
+            waitAsync: waitForEvent.waitAsync === true,
+            resolvedSignalSeq: parseOptionalFiniteNumber(waitForEvent.resolvedSignalSeq),
+            receivedAtMs: parseOptionalFiniteNumber(waitForEvent.receivedAtMs),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @param {WaitForEventAttemptSnapshot} snapshot
+ * @param {WaitForEventSignalInput} signal
+ * @returns {string}
+ */
+function buildResolvedWaitForEventMetaJson(snapshot, signal) {
+    const waitForEvent = snapshot.meta.waitForEvent &&
+        typeof snapshot.meta.waitForEvent === "object" &&
+        !Array.isArray(snapshot.meta.waitForEvent)
+        ? snapshot.meta.waitForEvent
+        : {};
+    return JSON.stringify({
+        ...snapshot.meta,
+        kind: typeof snapshot.meta.kind === "string"
+            ? snapshot.meta.kind
+            : "wait-for-event",
+        waitForEvent: {
+            ...waitForEvent,
+            signalName: snapshot.signalName,
+            correlationId: snapshot.correlationId,
+            waitAsync: snapshot.waitAsync,
+            resolvedSignalSeq: signal.seq,
+            receivedAtMs: signal.receivedAtMs,
+        },
+    });
+}
+/**
+ * @param {_SmithersDb} adapter
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @param {WaitForEventSignalInput} signal
+ */
+async function markWaitForEventResolved(adapter, runId, nodeId, iteration, signal) {
+    const attempts = await Effect.runPromise(adapter.listAttempts(runId, nodeId, iteration));
+    const waitingAttempt = attempts.find((attempt) => attempt.state === "waiting-event") ??
+        attempts[0];
+    const snapshot = parseWaitForEventAttemptSnapshot(waitingAttempt?.metaJson);
+    if (!waitingAttempt || !snapshot || snapshot.resolvedSignalSeq !== undefined) {
+        return;
+    }
+    await Effect.runPromise(adapter.updateAttempt(runId, nodeId, iteration, waitingAttempt.attempt, {
+        metaJson: buildResolvedWaitForEventMetaJson(snapshot, signal),
+    }));
+    if (snapshot.waitAsync) {
+        try {
+            await Effect.runPromise(updateAsyncExternalWaitPending("event", -1));
+        }
+        catch { }
+    }
+}
+const deferredResolutions = new Map();
+/**
+ * @template Success, Error
+ * @param {string} executionId
+ * @param {DurableDeferred.DurableDeferred<Success, Error>} _deferred
+ * @returns {Promise<BridgeDeferredResult>}
+ */
+const awaitBridgeDeferred = async (executionId, _deferred) => {
+    const exit = deferredResolutions.get(executionId);
+    return exit ? { _tag: "Complete", exit } : { _tag: "Pending" };
+};
+/**
+ * @template Success, Error
+ * @param {string} executionId
+ * @param {DurableDeferred.DurableDeferred<Success, Error>} _deferred
+ * @param {Exit.Exit<Success["Type"], Error["Type"]>} exit
+ */
+const resolveBridgeDeferred = async (executionId, _deferred, exit) => {
+    deferredResolutions.set(executionId, exit);
+};
+/**
+ * @param {_SmithersDb} adapter
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @returns {string}
+ */
+export const makeDurableDeferredBridgeExecutionId = (adapter, runId, nodeId, iteration) => [
+    "smithers-durable-deferred-bridge",
+    getAdapterNamespace(adapter),
+    runId,
+    nodeId,
+    String(iteration),
+].join(":");
+/**
+ * @param {string} nodeId
+ */
+export const makeApprovalDurableDeferred = (nodeId) => DurableDeferred.make(`approval:${nodeId}`, {
+    success: approvalDurableDeferredSuccessSchema,
+});
+/**
+ * @param {string} nodeId
+ */
+export const makeWaitForEventDurableDeferred = (nodeId) => DurableDeferred.make(`wait-for-event:${nodeId}`, {
+    success: waitForEventDurableDeferredSuccessSchema,
+});
+/**
+ * @param {_SmithersDb} adapter
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ */
+export const awaitApprovalDurableDeferred = (adapter, runId, nodeId, iteration) => awaitBridgeDeferred(makeDurableDeferredBridgeExecutionId(adapter, runId, nodeId, iteration), makeApprovalDurableDeferred(nodeId));
+/**
+ * @param {_SmithersDb} adapter
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ */
+export const awaitWaitForEventDurableDeferred = (adapter, runId, nodeId, iteration) => awaitBridgeDeferred(makeDurableDeferredBridgeExecutionId(adapter, runId, nodeId, iteration), makeWaitForEventDurableDeferred(nodeId));
+/**
+ * @param {_SmithersDb} adapter
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @param {{ approved: boolean; note?: string | null; decidedBy?: string | null; decisionJson?: string | null; autoApproved?: boolean; }} resolution
+ */
+export const bridgeApprovalResolve = async (adapter, runId, nodeId, iteration, resolution) => {
+    await resolveBridgeDeferred(makeDurableDeferredBridgeExecutionId(adapter, runId, nodeId, iteration), makeApprovalDurableDeferred(nodeId), Exit.succeed({
+        approved: resolution.approved,
+        note: resolution.note ?? null,
+        decidedBy: resolution.decidedBy ?? null,
+        decisionJson: resolution.decisionJson ?? null,
+        autoApproved: resolution.autoApproved ?? false,
+    }));
+};
+/**
+ * @param {_SmithersDb} adapter
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @param {WaitForEventSignalInput} signal
+ */
+export const bridgeWaitForEventResolve = async (adapter, runId, nodeId, iteration, signal) => {
+    await markWaitForEventResolved(adapter, runId, nodeId, iteration, signal);
+    await resolveBridgeDeferred(makeDurableDeferredBridgeExecutionId(adapter, runId, nodeId, iteration), makeWaitForEventDurableDeferred(nodeId), Exit.succeed({
+        signalName: signal.signalName,
+        correlationId: normalizeCorrelationId(signal.correlationId),
+        payloadJson: signal.payloadJson,
+        seq: signal.seq,
+        receivedAtMs: signal.receivedAtMs,
+    }));
+};
+/**
+ * @param {_SmithersDb} adapter
+ * @param {string} runId
+ * @param {WaitForEventSignalInput} signal
+ */
+export const bridgeSignalResolve = async (adapter, runId, signal) => {
+    const nodes = await Effect.runPromise(adapter.listNodes(runId));
+    const normalizedCorrelationId = normalizeCorrelationId(signal.correlationId);
+    for (const node of nodes) {
+        if (node.state !== "waiting-event")
+            continue;
+        const iteration = node.iteration ?? 0;
+        const attempts = await Effect.runPromise(adapter.listAttempts(runId, node.nodeId, iteration));
+        const waitingAttempt = attempts.find((attempt) => attempt.state === "waiting-event") ??
+            attempts[0];
+        if (!waitingAttempt)
+            continue;
+        const snapshot = parseWaitForEventAttemptSnapshot(waitingAttempt.metaJson);
+        if (!snapshot)
+            continue;
+        if (snapshot.signalName !== signal.signalName)
+            continue;
+        if (snapshot.correlationId !== normalizedCorrelationId)
+            continue;
+        await bridgeWaitForEventResolve(adapter, runId, node.nodeId, iteration, signal);
+    }
+};