@astrosheep/keiyaku 2.9.12 → 4.0.0

package/build/src/git/reconcile.js

@@ -0,0 +1,223 @@
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, readRef, registeredWorktreePaths, runGit, worktreeGitDirectory, } from "./repository.js";
+import { contractId } from "../core/facts/types.js";
+import { contractLocator, gitObjectIdForSnapshot } from "./identity.js";
+import { observeContract } from "./observe.js";
+import { runCreateHooks, runDestroyHooks, } from "./hooks.js";
+const WORKTREE_DIRECTORY = [".keiyaku-v4", "worktrees"];
+function materializedName(contract) { return contractId(contract).replace("/", "-"); }
+function deliveryRefFor(contract) { return `${DELIVERY_REF_NAMESPACE}/${materializedName(contract)}`; }
+function candidatePinRefFor(contract) { return `${CANDIDATE_PIN_REF_NAMESPACE}/${materializedName(contract)}`; }
+export function deliveryWorktreePath(repository, contract) { return resolve(realpathSync(repository.primaryWorktree), ...WORKTREE_DIRECTORY, materializedName(contract)); }
+function updateRef(repository, ref, desired) {
+    const before = readRef(repository, ref);
+    if (before === desired)
+        return { kind: "ref", name: ref, action: "unchanged", before, after: desired };
+    runGit(repository, ["update-ref", "--no-deref", ref, gitObjectIdForSnapshot(desired), before ?? "0".repeat(desired.length)]);
+    return { kind: "ref", name: ref, action: before === null ? "created" : "updated", before, after: desired };
+}
+function removeRef(repository, ref) {
+    const before = readRef(repository, ref);
+    if (before === null)
+        return { kind: "ref", name: ref, action: "unchanged", before: null, after: null };
+    runGit(repository, ["update-ref", "--no-deref", "-d", ref, before]);
+    return { kind: "ref", name: ref, action: "removed", before, after: null };
+}
+function acquireWorktreeTopology(repository) {
+    return { paths: new Set(registeredWorktreePaths(repository)) };
+}
+function fromPrimaryWorktree(repository) {
+    return { ...repository, effectiveCwd: repository.primaryWorktree };
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function complete(effects = [], lag = []) {
+    return { effects, lag };
+}
+function failed(stage, error, effects = [], lag = []) {
+    if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+        throw error;
+    return { effects, lag: [...lag, { kind: "reconcile-failed", stage, diagnostic: diagnostic(error) }] };
+}
+function reconcileLockPath(repository, contract) {
+    const locator = contractLocator(contract);
+    return join(commonGitDirectory(repository), "keiyaku", "locks", "reconcile", locator.slice(0, 2), `${locator.slice(2)}.sqlite`);
+}
+function worktree(repository, topology, path, desired) {
+    const registered = topology.paths.has(path);
+    if (registered && existsSync(path))
+        return { kind: "worktree", path, action: "unchanged" };
+    if (registered) {
+        runGit(repository, ["worktree", "remove", path]);
+        topology.paths.delete(path);
+    }
+    if (existsSync(path))
+        throw new Error(`delivery worktree path is occupied: ${path}`);
+    mkdirSync(dirname(path), { recursive: true });
+    runGit(repository, ["worktree", "add", "--detach", path, gitObjectIdForSnapshot(desired)]);
+    topology.paths.add(path);
+    return { kind: "worktree", path, action: "created" };
+}
+function canRemoveWorktree(repository, path, expected) {
+    if (runGit(repository, ["-C", path, "status", "--porcelain", "--untracked-files=all"]).length !== 0)
+        return false;
+    const [head, headTree] = runGit(repository, ["-C", path, "rev-parse", "HEAD", "HEAD^{tree}"])
+        .toString("utf8").trim().split("\n");
+    const matched = expected.find((snapshot) => head === gitObjectIdForSnapshot(snapshot));
+    if (matched === undefined)
+        return false;
+    const expectedTree = runGit(repository, ["-C", path, "rev-parse", `${gitObjectIdForSnapshot(matched)}^{tree}`])
+        .toString("utf8").trim();
+    return headTree === expectedTree;
+}
+function removeWorktree(repository, topology, path) {
+    const registered = topology.paths.has(path);
+    if (!registered)
+        return { effect: { kind: "worktree", path, action: "unchanged" }, retained: false };
+    if (!existsSync(path)) {
+        runGit(repository, ["worktree", "remove", path]);
+        topology.paths.delete(path);
+        return { effect: { kind: "worktree", path, action: "removed" }, retained: false };
+    }
+    try {
+        runGit(repository, ["worktree", "remove", path]);
+    }
+    catch {
+        return { effect: { kind: "worktree", path, action: "unchanged" }, retained: true };
+    }
+    topology.paths.delete(path);
+    return { effect: { kind: "worktree", path, action: "removed" }, retained: false };
+}
+async function reconcileWithTopology({ repository, hooks, retryHooks }, state, topology) {
+    const effects = [];
+    const lag = [];
+    try {
+        if (!state)
+            return complete(effects, lag);
+        const ref = deliveryRefFor(state.id), pin = candidatePinRefFor(state.id), path = deliveryWorktreePath(repository, state.id);
+        if (state.coordinates.workspace === "here") {
+            if (state.terminal)
+                effects.push(removeRef(repository, pin));
+            else if (state.bound)
+                effects.push(state.delivery === null
+                    ? removeRef(repository, pin)
+                    : updateRef(repository, pin, state.delivery.data.candidate));
+            return complete(effects, lag);
+        }
+        if (state.terminal) {
+            const expected = state.delivery === null
+                ? [state.coordinates.start]
+                : [state.delivery.data.candidate, state.coordinates.start];
+            const primary = fromPrimaryWorktree(repository);
+            const retain = (retainedLag) => {
+                effects.push(updateRef(primary, ref, state.delivery?.data.candidate ?? state.coordinates.start));
+                effects.push(state.delivery === null ? removeRef(primary, pin) : updateRef(primary, pin, state.delivery.data.candidate));
+                effects.push({ kind: "worktree", path, action: "unchanged" });
+                lag.push(retainedLag);
+                return complete(effects, lag);
+            };
+            const registered = topology.paths.has(path);
+            if (registered && existsSync(path)) {
+                if (!canRemoveWorktree(primary, path, expected))
+                    return retain({ kind: "worktree-retained", path });
+                const hookLag = await runDestroyHooks(path, worktreeGitDirectory(primary, path), hooks, retryHooks);
+                if (hookLag !== null)
+                    return retain(hookLag);
+            }
+            const removal = removeWorktree(primary, topology, path);
+            if (removal.retained)
+                return retain({ kind: "worktree-retained", path });
+            effects.push(removal.effect);
+            effects.push(removeRef(primary, ref));
+            effects.push(removeRef(primary, pin));
+            return complete(effects, lag);
+        }
+        if (!state.bound)
+            return complete(effects, lag);
+        const desired = state.delivery?.data.candidate ?? state.coordinates.start;
+        effects.push(updateRef(repository, ref, desired));
+        effects.push(worktree(repository, topology, path, desired));
+        const hookLag = await runCreateHooks(path, worktreeGitDirectory(repository, path), hooks, retryHooks);
+        if (hookLag !== null)
+            lag.push(hookLag);
+        effects.push(state.delivery ? updateRef(repository, pin, state.delivery.data.candidate) : removeRef(repository, pin));
+        return complete(effects, lag);
+    }
+    catch (error) {
+        return failed("effect", error, effects, lag);
+    }
+}
+function needsWorktreeTopology(state) {
+    return state !== null && state.coordinates.workspace === "worktree" && (state.terminal !== null || state.bound !== null);
+}
+function releaseFailure(held, observation) {
+    try {
+        held.close();
+        return observation;
+    }
+    catch (error) {
+        const prior = observation?.result;
+        return {
+            state: observation?.state ?? null,
+            result: failed("effect", error, prior?.effects, prior?.lag),
+        };
+    }
+}
+export async function reconcile(input) {
+    let held;
+    try {
+        held = await acquireSqliteTransactionLock({
+            path: reconcileLockPath(input.repository, input.contractId),
+            mode: "immediate",
+        });
+    }
+    catch (error) {
+        return { state: null, result: failed("observation", error) };
+    }
+    let observation;
+    let exceptional;
+    try {
+        const state = observeContract(input.repository, input.contractId).state;
+        const topology = needsWorktreeTopology(state)
+            ? acquireWorktreeTopology(input.repository)
+            : { paths: new Set() };
+        observation = {
+            state,
+            result: await reconcileWithTopology(input, state, topology),
+        };
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+            exceptional = error;
+        else
+            observation = { state: null, result: failed("observation", error) };
+    }
+    observation = releaseFailure(held, observation);
+    if (exceptional !== undefined)
+        throw exceptional;
+    if (observation === undefined)
+        throw new Error("reconcile produced no observation");
+    return observation;
+}
+export function reconcileObservationFailure(error) {
+    return failed("observation", error);
+}
+async function reconcileBatchItem(repository, contract, hooks, retryHooks) {
+    const observation = await reconcile({ repository, contractId: contract, hooks, retryHooks });
+    return {
+        contract,
+        state: observation.state,
+        result: observation.result,
+    };
+}
+/** Reconcile each discovered Contract through its own serialized, fresh observation. */
+export async function reconcileBatch(repository, contracts, hooks, retryHooks) {
+    const items = [];
+    for (const contract of contracts)
+        items.push(await reconcileBatchItem(repository, contract, hooks, retryHooks));
+    return items;
+}

package/build/src/git/repository.d.ts

@@ -0,0 +1,80 @@
+import { type TreeChange, type TreeEntry } from "./tree.js";
+export type { TreeChange } from "./tree.js";
+export declare const GIT_REF = "refs/heads/keiyaku-state";
+export declare const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
+export declare const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
+export declare const GIT_FORMAT_PATH = "meta/format.json";
+export declare const GIT_FORMAT_BYTES = "{\"version\":3}\n";
+export declare function isKeiyakuOwnedRef(ref: string): boolean;
+export type GitOid = string;
+export type RefPublication = Readonly<{
+    readonly kind: "published";
+}> | Readonly<{
+    readonly kind: "non-published";
+    readonly error: unknown;
+}> | Readonly<{
+    readonly kind: "unknown";
+}>;
+export type GitRepository = Readonly<{
+    /** The invocation's effective working directory, including a caller -C worktree. */
+    readonly effectiveCwd: string;
+    /** The canonical primary worktree root for this repository. */
+    readonly primaryWorktree: string;
+}>;
+export type GitSnapshot = Readonly<{
+    readonly commit: GitOid | null;
+    readonly tree: GitOid | null;
+    readonly paths: ReadonlyMap<string, TreeEntry>;
+}>;
+export declare class NoGitWorldError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare class GitPlumbingError extends Error {
+    readonly stderr: Buffer;
+    readonly status: number | null;
+    readonly pid: number | null;
+    constructor(input: Readonly<{
+        stderr: string | Uint8Array;
+        status: number | null;
+        message: string;
+        pid?: number | null;
+    }>);
+}
+export declare function registeredWorktreePaths(repository: GitRepository): readonly string[];
+export declare function repositoryAt(cwd: string): GitRepository;
+export declare function commonGitDirectory(repository: GitRepository): string;
+export declare function worktreeGitDirectory(repository: GitRepository, worktree: string): string;
+export declare function runGit(repository: GitRepository, args: readonly string[], input?: string | Uint8Array): Buffer;
+export declare function runGitWithEnvironment(repository: GitRepository, args: readonly string[], input: string | Uint8Array | undefined, environment: NodeJS.ProcessEnv): Buffer;
+export declare function readRef(repository: GitRepository, ref: string): GitOid | null;
+export declare function readGit(repository: GitRepository): GitSnapshot;
+/** Read only the requested private Git paths from one immutable Git tree. */
+export declare function readGitPaths(repository: GitRepository, requestedPaths: readonly string[]): GitSnapshot;
+/** Add paths from the same immutable Git tree without rereading its ref. */
+export declare function extendGitPaths(repository: GitRepository, snapshot: GitSnapshot, requestedPaths: readonly string[]): GitSnapshot;
+/** Expand a targeted immutable snapshot to its complete already-pinned tree. */
+export declare function expandGitSnapshot(repository: GitRepository, snapshot: GitSnapshot): GitSnapshot;
+export declare function writeBlob(repository: GitRepository, bytes: string | Uint8Array): GitOid;
+export declare function readBlob(repository: GitRepository, oid: GitOid): Buffer;
+/** Read immutable Git objects through one structured, length-delimited batch. */
+export declare function readBlobs(repository: GitRepository, oids: readonly GitOid[]): ReadonlyMap<GitOid, Buffer>;
+/** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
+export declare function updateGitTree(repository: GitRepository, baseTree: GitOid | null, changes: ReadonlyMap<string, TreeChange>): GitOid;
+export declare function writeCommit(input: Readonly<{
+    repository: GitRepository;
+    tree: GitOid;
+    parent: GitOid | null;
+    message?: string;
+    actor?: string;
+    at?: string;
+}>): GitOid;
+export declare function updateRefsAtomically(repository: GitRepository, updates: readonly ({
+    readonly ref: typeof GIT_REF;
+    readonly newOid: GitOid;
+    readonly expectedOid: GitOid | null;
+} | {
+    readonly ref: string;
+    readonly newOid: GitOid;
+    readonly expectedOid: GitOid;
+})[]): RefPublication;