@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/git/read-observation.js

@@ -0,0 +1,361 @@
+import { spawn } from "node:child_process";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { gitObjectId } from "./identity.js";
+import { parseTreeObject, validPath } from "./tree.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, GitPlumbingError, readRef, } from "./repository.js";
+const gitReadObservationBrand = Symbol("GitReadObservation");
+const gitDecodeChannelBrand = Symbol("GitDecodeChannel");
+function streamCursor(stream) {
+    const iterator = stream[Symbol.asyncIterator]();
+    let buffer = Buffer.alloc(0);
+    const pull = async (expected) => {
+        const next = await iterator.next();
+        if (next.done)
+            throw new Error(`git cat-file --batch ended while reading ${expected}`);
+        const chunk = Buffer.from(next.value);
+        buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]);
+    };
+    const line = async () => {
+        for (;;) {
+            const newline = buffer.indexOf(0x0a);
+            if (newline >= 0) {
+                const value = buffer.subarray(0, newline);
+                buffer = buffer.subarray(newline + 1);
+                return value;
+            }
+            await pull("line");
+        }
+    };
+    const exact = async (length) => {
+        while (buffer.length < length)
+            await pull(`${length} bytes`);
+        const value = buffer.subarray(0, length);
+        buffer = buffer.subarray(length);
+        return value;
+    };
+    return { line, exact };
+}
+function batchObjectReader(repository) {
+    const child = spawn("git", ["cat-file", "--batch"], {
+        cwd: repository.effectiveCwd,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    const cursor = streamCursor(child.stdout);
+    const cache = new Map();
+    const stderr = [];
+    const closed = new Promise((resolve) => {
+        child.once("close", (code, signal) => resolve({ code, signal }));
+    });
+    let tail = Promise.resolve();
+    let spawnError = null;
+    let failure = null;
+    child.stderr.on("data", (chunk) => stderr.push(Buffer.from(chunk)));
+    child.on("error", (error) => { spawnError = error; });
+    child.stdin.on("error", (error) => { spawnError ??= error; });
+    const plumbingError = (message, status) => new GitPlumbingError({
+        stderr: Buffer.concat(stderr),
+        status,
+        message: `git cat-file --batch: ${message}`,
+        pid: child.pid ?? null,
+    });
+    const write = async (value) => {
+        if (spawnError !== null)
+            throw spawnError;
+        await new Promise((resolve, reject) => {
+            child.stdin.write(value, (error) => error === null || error === undefined ? resolve() : reject(error));
+        });
+    };
+    const read = async (oid) => {
+        if (failure !== null)
+            throw failure;
+        try {
+            await write(`${oid}\n`);
+            const header = (await cursor.line()).toString("ascii").split(" ");
+            if (header.length === 2 && header[0] === oid && header[1] === "missing")
+                return { kind: "missing" };
+            if (header.length !== 3 || header[0] !== oid || header[1] === undefined || header[2] === undefined) {
+                throw new Error(`unexpected header for ${oid}`);
+            }
+            if (!/^(0|[1-9][0-9]*)$/.test(header[2]))
+                throw new Error(`invalid size for ${oid}`);
+            const size = Number(header[2]);
+            if (!Number.isSafeInteger(size))
+                throw new Error(`unsafe size for ${oid}`);
+            const bytes = await cursor.exact(size);
+            const delimiter = await cursor.exact(1);
+            if (delimiter[0] !== 0x0a)
+                throw new Error(`missing content delimiter for ${oid}`);
+            return { kind: "present", type: header[1], bytes };
+        }
+        catch (error) {
+            if (failure !== null)
+                throw failure;
+            child.kill();
+            await closed;
+            failure = plumbingError(error instanceof Error ? error.message : String(error), child.exitCode);
+            throw failure;
+        }
+    };
+    const object = (oid) => {
+        const cached = cache.get(oid);
+        if (cached !== undefined)
+            return cached;
+        const requested = tail.then(() => read(oid));
+        tail = requested.then(() => undefined, () => undefined);
+        cache.set(oid, requested);
+        return requested;
+    };
+    const objects = async (oids) => {
+        const unique = [...new Set(oids)];
+        for (const oid of unique)
+            gitObjectId(oid, "Git object");
+        const entries = await Promise.all(unique.map(async (oid) => [oid, await object(oid)]));
+        return new Map(entries);
+    };
+    const close = async () => {
+        await tail.catch(() => undefined);
+        if (failure !== null)
+            return;
+        if (!child.stdin.destroyed)
+            child.stdin.end();
+        const outcome = await closed;
+        if (spawnError !== null || outcome.code !== 0) {
+            throw plumbingError("git cat-file --batch did not close cleanly", outcome.code);
+        }
+    };
+    return { objects, close };
+}
+function commitTree(result, commit) {
+    if (result.kind === "missing")
+        throw new AuthorityCorruptionError(`Git state commit is missing: ${commit}`);
+    if (result.type !== "commit")
+        throw new AuthorityCorruptionError(`Git state ref does not name a commit: ${commit}`);
+    const newline = result.bytes.indexOf(0x0a);
+    if (newline < 0)
+        throw new AuthorityCorruptionError(`Git state commit has no headers: ${commit}`);
+    const firstLine = result.bytes.subarray(0, newline).toString("ascii");
+    if (!firstLine.startsWith("tree "))
+        throw new AuthorityCorruptionError(`Git state commit has no root tree: ${commit}`);
+    return gitObjectId(firstLine.slice("tree ".length), "Git state tree");
+}
+async function completeTree(channel, root) {
+    const paths = new Map();
+    const directories = new Map();
+    let level = [{ path: "", oid: root }];
+    while (level.length > 0) {
+        const objects = await channel.readObjects(level.map(({ oid }) => oid));
+        const next = [];
+        for (const tree of level) {
+            const object = objects.get(tree.oid);
+            if (object?.kind !== "present")
+                throw new AuthorityCorruptionError(`Git tree is missing: ${tree.oid}`);
+            if (object.type !== "tree")
+                throw new AuthorityCorruptionError(`Git object is not a tree: ${tree.oid}`);
+            const entries = parseTreeObject(object.bytes, tree.oid.length / 2);
+            directories.set(tree.path, entries);
+            for (const [name, entry] of entries) {
+                const path = tree.path.length === 0 ? name : `${tree.path}/${name}`;
+                if (entry.type === "tree")
+                    next.push({ path, oid: entry.oid });
+                else
+                    paths.set(path, entry);
+            }
+        }
+        level = next;
+    }
+    return { paths, directories };
+}
+function selectionTree(selection) {
+    const root = { exact: false, subtree: false, children: new Map() };
+    const add = (path, kind) => {
+        validPath(path);
+        let node = root;
+        for (const segment of path.split("/")) {
+            let child = node.children.get(segment);
+            if (child === undefined) {
+                child = { exact: false, subtree: false, children: new Map() };
+                node.children.set(segment, child);
+            }
+            node = child;
+        }
+        node[kind] = true;
+    };
+    add(GIT_FORMAT_PATH, "exact");
+    for (const path of selection.paths ?? [])
+        add(path, "exact");
+    for (const path of selection.subtrees ?? [])
+        add(path, "subtree");
+    return root;
+}
+export async function readGitTreeSelection(channel, root, selection) {
+    const paths = new Map();
+    const directories = new Map();
+    const readDirectory = async (path, oid) => {
+        const object = (await channel.readObjects([oid])).get(oid);
+        if (object?.kind !== "present")
+            throw new AuthorityCorruptionError(`Git tree is missing: ${oid}`);
+        if (object.type !== "tree")
+            throw new AuthorityCorruptionError(`Git object is not a tree: ${oid}`);
+        const entries = parseTreeObject(object.bytes, oid.length / 2);
+        directories.set(path, entries);
+        return entries;
+    };
+    const enumerate = async (path, oid) => {
+        const entries = await readDirectory(path, oid);
+        await Promise.all([...entries].map(async ([name, entry]) => {
+            const childPath = path.length === 0 ? name : `${path}/${name}`;
+            if (entry.type === "tree")
+                await enumerate(childPath, entry.oid);
+            else
+                paths.set(childPath, entry);
+        }));
+    };
+    const visit = async (path, oid, node) => {
+        const entries = await readDirectory(path, oid);
+        await Promise.all([...node.children].map(async ([name, child]) => {
+            const entry = entries.get(name);
+            if (entry === undefined)
+                return;
+            const childPath = path.length === 0 ? name : `${path}/${name}`;
+            if (entry.type !== "tree") {
+                paths.set(childPath, entry);
+                return;
+            }
+            if (child.exact || child.subtree)
+                paths.set(childPath, entry);
+            if (child.exact && child.children.size === 0 && !child.subtree) {
+                paths.set(childPath, entry);
+                return;
+            }
+            if (child.subtree)
+                await enumerate(childPath, entry.oid);
+            else if (child.children.size > 0)
+                await visit(childPath, entry.oid, child);
+        }));
+    };
+    await visit("", root, selectionTree(selection));
+    return { paths, directories };
+}
+async function readFormat(observation) {
+    const entry = observation.snapshot.paths.get(GIT_FORMAT_PATH);
+    if (entry === undefined)
+        throw new AuthorityCorruptionError(`Git is missing ${GIT_FORMAT_PATH}`);
+    if (entry.type !== "blob")
+        throw new AuthorityCorruptionError(`Git format is not a blob: ${GIT_FORMAT_PATH}`);
+    const result = (await observation.readBlobs([entry.oid])).get(entry.oid);
+    if (result?.kind !== "present" || result.bytes.toString("utf8") !== GIT_FORMAT_BYTES) {
+        throw new AuthorityCorruptionError(`Git format is not current: ${GIT_FORMAT_PATH}`);
+    }
+}
+export async function withGitDecodeChannel(repository, consume) {
+    const transport = { reader: null };
+    let active = true;
+    const objectReader = () => transport.reader ??= batchObjectReader(repository);
+    const channel = {
+        [gitDecodeChannelBrand]: true,
+        readObjects: (oids) => {
+            if (!active)
+                throw new Error("Git decode channel is closed");
+            return oids.length === 0 ? Promise.resolve(new Map()) : objectReader().objects(oids);
+        },
+    };
+    let result;
+    let failure;
+    try {
+        result = await consume(channel);
+    }
+    catch (error) {
+        failure = error;
+    }
+    active = false;
+    try {
+        if (transport.reader !== null)
+            await transport.reader.close();
+    }
+    catch (error) {
+        failure ??= error;
+    }
+    if (failure !== undefined)
+        throw failure;
+    return result;
+}
+async function observeEpoch(repository, channel, selection, consume) {
+    const commit = readRef(repository, GIT_REF);
+    let active = true;
+    const refs = new Map();
+    const assertActive = () => {
+        if (!active)
+            throw new Error("Git read observation is closed");
+    };
+    const resolveRef = async (ref) => {
+        assertActive();
+        let resolved = refs.get(ref);
+        if (resolved === undefined) {
+            resolved = Promise.resolve().then(() => readRef(repository, ref));
+            refs.set(ref, resolved);
+        }
+        return resolved;
+    };
+    const readBlobResults = async (oids) => {
+        assertActive();
+        if (oids.length === 0)
+            return new Map();
+        const objects = await channel.readObjects(oids);
+        const blobs = new Map();
+        for (const [oid, object] of objects) {
+            if (object.kind === "missing")
+                blobs.set(oid, object);
+            else {
+                if (object.type !== "blob")
+                    throw new AuthorityCorruptionError(`Git object is not a blob: ${oid}`);
+                blobs.set(oid, { kind: "present", bytes: object.bytes });
+            }
+        }
+        return blobs;
+    };
+    let result;
+    let failure;
+    try {
+        let snapshot;
+        let treeDirectories;
+        if (commit === null) {
+            snapshot = { commit: null, tree: null, paths: new Map() };
+            treeDirectories = new Map();
+        }
+        else {
+            const commitObject = (await channel.readObjects([commit])).get(commit);
+            if (commitObject === undefined)
+                throw new Error(`missing state commit result: ${commit}`);
+            const tree = commitTree(commitObject, commit);
+            const observed = selection === null
+                ? await completeTree(channel, tree)
+                : await readGitTreeSelection(channel, tree, selection);
+            snapshot = { commit, tree, paths: observed.paths };
+            treeDirectories = observed.directories;
+        }
+        const observation = {
+            [gitReadObservationBrand]: true,
+            repository,
+            snapshot,
+            treeDirectories,
+            readBlobs: readBlobResults,
+            resolveRef,
+        };
+        if (commit !== null)
+            await readFormat(observation);
+        result = await consume(observation);
+    }
+    catch (error) {
+        failure = error;
+    }
+    active = false;
+    if (failure !== undefined)
+        throw failure;
+    return result;
+}
+export function withGitReadObservation(repository, channel, consume) {
+    return observeEpoch(repository, channel, null, consume);
+}
+export function withGitTargetedReadObservation(repository, channel, selection, consume) {
+    return observeEpoch(repository, channel, selection, consume);
+}

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

@@ -0,0 +1,59 @@
+import { type GitOid, type GitRepository } from "./repository.js";
+import type { ContractId, ContractState } from "../core/facts/types.js";
+import type { GitDecodeChannel } from "./read-observation.js";
+import { type TargetCheckoutEffect, type TargetCheckoutLag } from "./target-placement.js";
+import { type WorktreeHookLag, type WorktreeHooks } from "./hooks.js";
+import { type UnsealedBytes } from "./terminal-seal.js";
+export type Effect = Readonly<{
+    kind: "worktree";
+    path: string;
+    action: "created" | "removed" | "unchanged";
+}> | TargetCheckoutEffect | Readonly<{
+    kind: "ref";
+    name: string;
+    before: GitOid | null;
+    after: GitOid | null;
+    action: "created" | "updated" | "removed" | "unchanged";
+}>;
+type ReconcileInput = Readonly<{
+    repository: GitRepository;
+    channel: GitDecodeChannel;
+    contractId: ContractId;
+    hooks: WorktreeHooks;
+    retryHooks: boolean;
+    retainTerminalWorktree?: boolean;
+}>;
+type WorktreeRetained = Readonly<{
+    kind: "worktree-retained";
+    path: string;
+}>;
+export type ReconcileFailure = Readonly<{
+    kind: "reconcile-failed";
+    stage: "observation" | "effect";
+    diagnostic: string;
+}>;
+export type ReconcileLag = WorktreeRetained | UnsealedBytes | TargetCheckoutLag | WorktreeHookLag | ReconcileFailure;
+export type ReconcileResult = Readonly<{
+    effects: readonly Effect[];
+    lag: readonly ReconcileLag[];
+}>;
+type ReconcileBatchItem = Readonly<{
+    contract: ContractId;
+    state: ContractState | null;
+    result: ReconcileResult;
+}>;
+export type GitReconcileObservation = Readonly<{
+    state: ContractState | null;
+    result: ReconcileResult;
+}>;
+export declare function reconcile(input: ReconcileInput): Promise<GitReconcileObservation>;
+export declare function reconcileObservationFailure(error: unknown): ReconcileResult;
+export declare function reconcileEffectFailure(error: unknown, prior?: ReconcileResult): ReconcileResult;
+type ReconcileBatchOptions = Readonly<{
+    hooks: WorktreeHooks;
+    retryHooks: boolean;
+    retainTerminalWorktree: boolean;
+}>;
+/** Reconcile each discovered Contract through its own serialized, fresh observation. */
+export declare function reconcileBatch(repository: GitRepository, channel: GitDecodeChannel, contracts: Iterable<ContractId>, options: ReconcileBatchOptions): Promise<readonly ReconcileBatchItem[]>;
+export {};