@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/git-commit.js

@@ -0,0 +1,251 @@
+/**
+ * Write to an installation's repository through its GIT binding: commit files
+ * to a branch, point a ref at an existing commit, or merge one repository's
+ * branch into another's. All run isomorphic-git over the binding's byte-RPC smart-HTTP exchange in memory, so an App never
+ * holds a remote or a credential. Every write is compare-and-swap on the ref:
+ * the caller names the head it built on, and a ref that moved is reported
+ * stale instead of overwritten.
+ */
+import { Buffer } from "buffer";
+import * as git from "isomorphic-git";
+import { advertisedRefs } from "./git-wire.js";
+import { memoryFs } from "./internal/memory-fs.js";
+import { begin, runStep, memoryGitStepMaterial, } from "./git-steps.js";
+const DIR = "/repository";
+const ORIGIN = "https://git.binding.invalid/";
+const ADVERTISE = /^https:\/\/git\.binding\.invalid\/[^/]+\.git\/info\/refs\?service=git-(upload|receive)-pack$/u;
+const EXCHANGE = /^https:\/\/git\.binding\.invalid\/[^/]+\.git\/git-(upload|receive)-pack$/u;
+// isomorphic-git expects a global Buffer; App backends run without Node's.
+if (!("Buffer" in globalThis))
+    Reflect.set(globalThis, "Buffer", Buffer);
+class StaleRef extends Error {
+    head;
+    constructor(head) {
+        super("Ref moved");
+        this.head = head;
+    }
+}
+async function collect(body) {
+    if (body === undefined)
+        return null;
+    const parts = [];
+    for await (const part of body)
+        parts.push(part);
+    return Buffer.concat(parts);
+}
+async function* once(chunk) {
+    await Promise.resolve();
+    yield chunk;
+}
+/**
+ * isomorphic-git's HTTP client over the binding. A guard checks the expected
+ * head in the fetch advertisement and again in the push advertisement; the
+ * server's ref update is compare-and-swap on that advertised head.
+ */
+function exchangeClient(store, repository, guard) {
+    return {
+        async request(input) {
+            const advertise = ADVERTISE.exec(input.url);
+            const exchange = advertise === null ? EXCHANGE.exec(input.url) : null;
+            const match = advertise ?? exchange;
+            if (match === null)
+                throw new Error("Unexpected Git URL");
+            const service = match[1] === "receive" ? "receive-pack" : "upload-pack";
+            const request = {
+                service,
+                phase: advertise === null ? "exchange" : "advertise",
+                headers: input.headers ?? {},
+                body: await collect(input.body),
+            };
+            const response = await store.exchange(repository, request);
+            if (guard !== null && request.phase === "advertise") {
+                const head = advertisedRefs(response.body).get(guard.ref) ?? null;
+                if (head !== guard.expected)
+                    throw new StaleRef(head);
+            }
+            return {
+                url: input.url,
+                method: input.method ?? "GET",
+                statusCode: response.status,
+                statusMessage: "",
+                headers: { ...response.headers },
+                body: once(response.body),
+            };
+        },
+    };
+}
+async function heads(store, repository) {
+    const response = await store.exchange(repository, {
+        service: "upload-pack",
+        phase: "advertise",
+        headers: {},
+        body: null,
+    });
+    if (response.status !== 200)
+        throw new Error("Repository advertisement unavailable");
+    return advertisedRefs(response.body);
+}
+/**
+ * The server refused the ref update (another push landed between our
+ * advertisement and our pack: non-fast-forward, "fetch first", a lost ref
+ * lock). Nothing was written; report the branch's fresh head.
+ */
+function rejectedPush(cause) {
+    return (cause instanceof git.Errors.PushRejectedError ||
+        cause instanceof git.Errors.GitPushError);
+}
+async function staleAfterRejection(store, repository, ref) {
+    return {
+        kind: "stale",
+        head: (await heads(store, repository)).get(ref) ?? null,
+    };
+}
+async function open(store, repository) {
+    const fs = memoryFs();
+    await fs.promises.mkdir(DIR);
+    await git.init({ fs, dir: DIR });
+    await git.addRemote({
+        fs,
+        dir: DIR,
+        remote: "origin",
+        url: `${ORIGIN}${repository}.git`,
+    });
+    /** Fetch one branch's head (depth 1) and return its commit. */
+    const fetchHead = async (branch, guard = null) => {
+        await git.fetch({
+            fs,
+            http: exchangeClient(store, repository, guard),
+            dir: DIR,
+            remote: "origin",
+            ref: branch,
+            singleBranch: true,
+            depth: 1,
+            tags: false,
+        });
+        return git.resolveRef({
+            fs,
+            dir: DIR,
+            ref: `refs/remotes/origin/${branch}`,
+        });
+    };
+    return { fs, fetchHead };
+}
+/** Foreground driver over the same resumable engine used by background owners. */
+async function driveSteps(store, operation, beforeWrite) {
+    // This key is local to a new volatile store per call, not a minted identity.
+    const material = memoryGitStepMaterial();
+    let checkpoint = await begin(operation, material);
+    const ports = { git: store, material };
+    const signal = new AbortController().signal;
+    const [started, checked] = await Promise.allSettled([
+        runStep(checkpoint, ports, signal),
+        Promise.resolve().then(() => beforeWrite?.()),
+    ]);
+    // Preserve validation precedence and settle the fetch before the first push.
+    if (checked.status === "rejected")
+        throw checked.reason;
+    if (started.status === "rejected")
+        throw started.reason;
+    let reply = started.value;
+    for (;;) {
+        if ("done" in reply) {
+            if (reply.done.kind === "too_large")
+                throw new RangeError("Git material exceeds resumable write bound");
+            return reply.done;
+        }
+        if ("yield" in reply)
+            throw new Error("Foreground Git write yielded");
+        checkpoint = reply.next;
+        reply = await runStep(checkpoint, ports, signal);
+    }
+}
+/** Commit files using independently resumable, CAS-guarded Git steps. */
+export async function commitFiles(store, request, beforeWrite) {
+    const result = await driveSteps(store, { kind: "commit", requestKey: "foreground", request }, beforeWrite);
+    if (result.kind === "committed" ||
+        result.kind === "unchanged" ||
+        result.kind === "updated" ||
+        result.kind === "stale")
+        return result;
+    throw new Error("Invalid commit step outcome");
+}
+/** Point a ref at the head commit of `source`, compare-and-swap on the ref. */
+export async function moveRef(store, request) {
+    const result = await moveRefs(store, {
+        repository: request.repository,
+        source: request.source,
+        commit: request.commit,
+        updates: [{ ref: request.ref, expected: request.expected }],
+    });
+    return result.kind === "stale"
+        ? { kind: "stale", head: result.head }
+        : result;
+}
+/** Fetch a source once, then move refs in order with separate guarded pushes. */
+export async function moveRefs(store, request) {
+    const first = request.updates.at(0);
+    if (first === undefined)
+        return { kind: "updated" };
+    const { fs, fetchHead } = await open(store, request.repository);
+    try {
+        if ((await fetchHead(request.source, first)) !== request.commit)
+            throw new RangeError("Commit is not the head of its source branch");
+    }
+    catch (cause) {
+        if (cause instanceof StaleRef)
+            return { kind: "stale", ref: first.ref, head: cause.head };
+        throw cause;
+    }
+    for (const update of request.updates) {
+        await git.writeRef({
+            fs,
+            dir: DIR,
+            ref: update.ref,
+            value: request.commit,
+            force: true,
+        });
+        try {
+            const pushed = await git.push({
+                fs,
+                http: exchangeClient(store, request.repository, update),
+                dir: DIR,
+                remote: "origin",
+                ref: update.ref,
+                remoteRef: update.ref,
+                // Each push's advertisement checks that ref's expected head.
+                force: true,
+            });
+            if (!pushed.ok)
+                return {
+                    ...(await staleAfterRejection(store, request.repository, update.ref)),
+                    ref: update.ref,
+                };
+        }
+        catch (cause) {
+            if (cause instanceof StaleRef)
+                return { kind: "stale", ref: update.ref, head: cause.head };
+            if (rejectedPush(cause))
+                return {
+                    ...(await staleAfterRejection(store, request.repository, update.ref)),
+                    ref: update.ref,
+                };
+            throw cause;
+        }
+    }
+    return { kind: "updated" };
+}
+/** Merge branches through the same one-exchange step engine as background owners. */
+export async function mergeBranch(store, request) {
+    const result = await driveSteps(store, {
+        kind: "merge",
+        requestKey: "foreground",
+        request,
+    });
+    if (result.kind === "merged" ||
+        result.kind === "up-to-date" ||
+        result.kind === "conflict" ||
+        result.kind === "stale" ||
+        result.kind === "source-moved")
+        return result;
+    throw new Error("Invalid merge step outcome");
+}

package/dist/git-rpc.d.ts

@@ -0,0 +1,310 @@
+import * as z from "zod";
+import { type GitBinding } from "./git.js";
+/** The native tuple and result grammar shared by the handle and frame entrypoint. */
+export declare const nativeGitCodecs: {
+    create: {
+        args: z.ZodTuple<[z.ZodString, z.ZodOptional<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+            defaultBranch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>], null>;
+        result: z.ZodObject<{
+            name: z.ZodString;
+            defaultBranch: z.ZodString;
+            lastPushAt: z.ZodNullable<z.ZodString>;
+            source: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    };
+    fork: {
+        args: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodOptional<z.ZodObject<{
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>], null>;
+        result: z.ZodObject<{
+            name: z.ZodString;
+            defaultBranch: z.ZodString;
+            lastPushAt: z.ZodNullable<z.ZodString>;
+            source: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    };
+    cloneUrl: {
+        args: z.ZodTuple<[z.ZodString], null>;
+        result: z.ZodURL;
+    };
+    info: {
+        args: z.ZodTuple<[z.ZodString], null>;
+        result: z.ZodNullable<z.ZodObject<{
+            name: z.ZodString;
+            defaultBranch: z.ZodString;
+            lastPushAt: z.ZodNullable<z.ZodString>;
+            source: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    };
+    delete: {
+        args: z.ZodTuple<[z.ZodString], null>;
+        result: z.ZodBoolean;
+    };
+    log: {
+        args: z.ZodTuple<[z.ZodString, z.ZodObject<{
+            ref: z.ZodString;
+            limit: z.ZodOptional<z.ZodNumber>;
+            offset: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], null>;
+        result: z.ZodArray<z.ZodObject<{
+            hash: z.ZodString;
+            treeHash: z.ZodString;
+            message: z.ZodString;
+            author: z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodString;
+            }, z.core.$strict>;
+            committer: z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodString;
+            }, z.core.$strict>;
+            parents: z.ZodArray<z.ZodString>;
+            authoredAt: z.ZodNumber;
+            committedAt: z.ZodNumber;
+        }, z.core.$strict>>;
+    };
+    readCommit: {
+        args: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        result: z.ZodNullable<z.ZodObject<{
+            hash: z.ZodString;
+            treeHash: z.ZodString;
+            message: z.ZodString;
+            author: z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodString;
+            }, z.core.$strict>;
+            committer: z.ZodObject<{
+                name: z.ZodString;
+                email: z.ZodString;
+            }, z.core.$strict>;
+            parents: z.ZodArray<z.ZodString>;
+            authoredAt: z.ZodNumber;
+            committedAt: z.ZodNumber;
+        }, z.core.$strict>>;
+    };
+    readTree: {
+        args: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        result: z.ZodNullable<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            mode: z.ZodString;
+            hash: z.ZodString;
+            type: z.ZodEnum<{
+                blob: "blob";
+                tree: "tree";
+                commit: "commit";
+            }>;
+        }, z.core.$strict>>>;
+    };
+    readBlob: {
+        args: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        result: z.ZodNullable<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+    };
+    refs: {
+        args: z.ZodTuple<[z.ZodString], null>;
+        result: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            hash: z.ZodString;
+        }, z.core.$strict>>;
+    };
+    exchange: {
+        args: z.ZodTuple<[z.ZodString, z.ZodObject<{
+            service: z.ZodEnum<{
+                "upload-pack": "upload-pack";
+                "receive-pack": "receive-pack";
+            }>;
+            phase: z.ZodEnum<{
+                advertise: "advertise";
+                exchange: "exchange";
+            }>;
+            body: z.ZodNullable<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+            headers: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>], null>;
+        result: z.ZodObject<{
+            status: z.ZodNumber;
+            headers: z.ZodRecord<z.ZodString, z.ZodString>;
+            body: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+        }, z.core.$strict>;
+    };
+};
+/** Host operation required before a native Git effect. */
+export type NativeGitOperation = "create" | "fork" | "read" | "write" | "exchange";
+/** Native Git preserves tuples and binary values through the shared frame factory. */
+export declare const nativeGitFrameMethods: {
+    create: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string, ({
+            description?: string | undefined;
+            defaultBranch?: string | undefined;
+        } | undefined)?];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            name: string;
+            defaultBranch: string;
+            lastPushAt: string | null;
+            source: string | null;
+        };
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    fork: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string, string, ({
+            description?: string | undefined;
+        } | undefined)?];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            name: string;
+            defaultBranch: string;
+            lastPushAt: string | null;
+            source: string | null;
+        };
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    cloneUrl: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => string;
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    info: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            name: string;
+            defaultBranch: string;
+            lastPushAt: string | null;
+            source: string | null;
+        } | null;
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    delete: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => boolean;
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    log: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string, {
+            ref: string;
+            limit?: number | undefined;
+            offset?: number | undefined;
+        }];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            hash: string;
+            treeHash: string;
+            message: string;
+            author: {
+                name: string;
+                email: string;
+            };
+            committer: {
+                name: string;
+                email: string;
+            };
+            parents: string[];
+            authoredAt: number;
+            committedAt: number;
+        }[];
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    readCommit: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string, string];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            hash: string;
+            treeHash: string;
+            message: string;
+            author: {
+                name: string;
+                email: string;
+            };
+            committer: {
+                name: string;
+                email: string;
+            };
+            parents: string[];
+            authoredAt: number;
+            committedAt: number;
+        } | null;
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    readTree: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string, string];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            name: string;
+            mode: string;
+            hash: string;
+            type: "blob" | "tree" | "commit";
+        }[] | null;
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    readBlob: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string, string];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => Uint8Array<ArrayBuffer> | null;
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    refs: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            name: string;
+            hash: string;
+        }[];
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+    exchange: {
+        /** Decode the native positional arguments with the method's tuple codec. */
+        decodeArgs: (raw: readonly unknown[]) => [string, {
+            service: "upload-pack" | "receive-pack";
+            phase: "advertise" | "exchange";
+            body: Uint8Array<ArrayBuffer> | null;
+            headers: Record<string, string>;
+        }];
+        /** Validate the native result, preserving binary values. */
+        decodeResult: (raw: unknown) => {
+            status: number;
+            headers: Record<string, string>;
+            body: Uint8Array<ArrayBuffer>;
+        };
+        /** Operations the host must grant for these decoded arguments. */
+        requiredOperations: (args: readonly unknown[]) => readonly string[];
+    };
+};
+/** Native method identity is a source-owned refinement, not a transport parser. */
+export declare const nativeGitMethodNameSchema: z.ZodEnum<{
+    info: "info";
+    create: "create";
+    delete: "delete";
+    exchange: "exchange";
+    fork: "fork";
+    cloneUrl: "cloneUrl";
+    log: "log";
+    readCommit: "readCommit";
+    readTree: "readTree";
+    readBlob: "readBlob";
+    refs: "refs";
+}>;
+/** Dispatch owned tuples through the retained native handle without a JSON conversion. */
+export declare function invokeNativeGit(git: GitBinding, method: string, raw: readonly unknown[]): Promise<Awaited<ReturnType<GitBinding[keyof GitBinding]>>>;