gitd-client 0.0.0-stage → 0.7.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# gitd-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript client for [gitd](https://github.com/dooservice/gitd): instant, secretless git
+checkouts for agent sandboxes.
+
+```sh
+npm install gitd-client
+```
+
+```ts
+import { Gitd, GitdError } from "gitd-client";
+
+const gitd = new Gitd(); // $GITD_SOCKET, then /run/gitd/gitd.sock
+
+const workspace = await gitd.prepare({
+  url: "https://github.com/your-org/your-repo",
+  path: "/var/lib/gitd/workspaces/agent-1",
+});
+console.log(workspace.commit, workspace.strategy); // "overlay": made in milliseconds
+
+// … the agent works in workspace.path with plain git, and commits …
+
+await gitd.publish(workspace.path, "agents/fix-login"); // pushed with the token gitd keeps
+await gitd.remove(workspace.path);
+```
+
+No call takes a credential: gitd reads and publishes with the ones it keeps.
+
+| Method | What it does |
+|---|---|
+| `prepare({ url, path, branch, commit, submodules, fullHistory, strategy, onProgress })` | A workspace of a repository at a path under gitd's roots |
+| `update(path, { branch, submodules, onProgress })` | To the tip of its branch, or of the branch given |
+| `checkout(path, commit, { submodules, onProgress })` | To a commit, as a rollback does |
+| `describe(path)` | Its repository, commit, branch, uncommitted changes and submodules |
+| `publish(path, branch)` | Its commits pushed to a new branch |
+| `remove(path)` | Deleted; its pool stays |
+| `probe(url)` | Whether it can be read, its default branch and branches |
+| `info()` | Which gitd answers, and how it makes workspaces here and why |
+| `audit({ since, url, limit })` | Every publish, done or refused, newest first |
+
+A refusal is a `GitdError` with its `reason` (`AUTH_REQUIRED`, `NOT_FOUND`, `PATH_REFUSED`,
+`BRANCH_REFUSED`, `BUSY`, …) and what git said. The whole contract is under `proto`.
+
+[`examples/agent.ts`](examples/agent.ts) is an agent's round trip: prepare, commit, publish.
+
+Node 22 or later. Generated from gitd's contract with `npm run generate`; built with
+`npm run build`.

package/dist/calls.d.ts

@@ -0,0 +1,19 @@
+import type { Progress, WorkspaceResult } from "./gen/gitd/v1/gitd_pb.js";
+/** A message of a workspace stream: progress, or the result that ends it. */
+type Event = {
+    event: {
+        case: "progress";
+        value: Progress;
+    } | {
+        case: "result";
+        value: WorkspaceResult;
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/** Reads a stream to its result, handing the progress on. */
+export declare function drain(stream: AsyncIterable<Event>, onProgress?: (progress: Progress) => void): Promise<WorkspaceResult>;
+/** Makes a unary call, reading a refusal into a GitdError. */
+export declare function call<T>(request: () => Promise<T>): Promise<T>;
+export {};

package/dist/calls.js

@@ -0,0 +1,32 @@
+import { Code } from "@connectrpc/connect";
+import { GitdError, refusal } from "./errors.js";
+/** Reads a stream to its result, handing the progress on. */
+export async function drain(stream, onProgress) {
+    try {
+        let result;
+        for await (const message of stream) {
+            if (message.event.case === "progress") {
+                onProgress?.(message.event.value);
+            }
+            else if (message.event.case === "result") {
+                result = message.event.value;
+            }
+        }
+        if (!result) {
+            throw new GitdError("", "gitd ended the call without a result", Code.Internal);
+        }
+        return result;
+    }
+    catch (error) {
+        throw refusal(error);
+    }
+}
+/** Makes a unary call, reading a refusal into a GitdError. */
+export async function call(request) {
+    try {
+        return await request();
+    }
+    catch (error) {
+        throw refusal(error);
+    }
+}

package/dist/convert.d.ts

@@ -0,0 +1,12 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { ProbeResponse_Access, Strategy, type AuditEntry as AuditEntryMessage, type PublishedRepository as PublishedRepositoryMessage, type RevisionSchema, type WorkspaceResult } from "./gen/gitd/v1/gitd_pb.js";
+import type { AuditEntry, Probe, PublishedRepository, StrategyName, Workspace } from "./types.js";
+export declare function toWorkspace(path: string, result: WorkspaceResult): Workspace;
+export declare function strategyName(strategy: Strategy): StrategyName;
+export declare function strategyProto(name?: StrategyName): Strategy;
+export declare function accessName(access: ProbeResponse_Access): Probe["access"];
+/** The revision a prepare asks for: a commit, a branch, or the default branch. */
+export declare function revisionOf(branch?: string, commit?: string): MessageInitShape<typeof RevisionSchema> | undefined;
+/** What a publish pushed: the workspace's repository first, then each submodule. */
+export declare function pushedOf(repository: PublishedRepositoryMessage | undefined, submodules: PublishedRepositoryMessage[]): PublishedRepository[];
+export declare function toAuditEntry(entry: AuditEntryMessage): AuditEntry;

package/dist/convert.js

@@ -0,0 +1,80 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { GitFailure_Reason, ProbeResponse_Access, Strategy, } from "./gen/gitd/v1/gitd_pb.js";
+export function toWorkspace(path, result) {
+    const layers = result.layers;
+    return {
+        path,
+        commit: result.commit,
+        branch: result.branch,
+        strategy: strategyName(result.strategy),
+        layers: layers && { lower: layers.lower, upper: layers.upper, work: layers.work },
+        pendingSubmodules: result.pendingSubmodules.map((submodule) => ({
+            path: submodule.path,
+            url: submodule.url,
+            reason: submodule.failure?.gitSaid ?? "",
+        })),
+        lfsPatterns: result.lfsPatterns,
+    };
+}
+export function strategyName(strategy) {
+    switch (strategy) {
+        case Strategy.OVERLAY:
+            return "overlay";
+        case Strategy.REFLINK:
+            return "reflink";
+        default:
+            return "copy";
+    }
+}
+export function strategyProto(name) {
+    switch (name) {
+        case "overlay":
+            return Strategy.OVERLAY;
+        case "reflink":
+            return Strategy.REFLINK;
+        case "copy":
+            return Strategy.COPY;
+        default:
+            return Strategy.UNSPECIFIED;
+    }
+}
+export function accessName(access) {
+    switch (access) {
+        case ProbeResponse_Access.PUBLIC:
+            return "public";
+        case ProbeResponse_Access.REACHABLE:
+            return "reachable";
+        default:
+            return "denied";
+    }
+}
+/** The revision a prepare asks for: a commit, a branch, or the default branch. */
+export function revisionOf(branch, commit) {
+    if (commit) {
+        return { target: { case: "commit", value: commit } };
+    }
+    if (branch) {
+        return { target: { case: "branch", value: branch } };
+    }
+    return undefined;
+}
+/** What a publish pushed: the workspace's repository first, then each submodule. */
+export function pushedOf(repository, submodules) {
+    return [repository, ...submodules]
+        .filter((pushed) => pushed !== undefined)
+        .map((pushed) => ({ url: pushed.url, path: pushed.path, commit: pushed.commit, subjects: pushed.subjects }));
+}
+export function toAuditEntry(entry) {
+    const refusal = entry.refusal;
+    return {
+        time: entry.time ? timestampDate(entry.time) : new Date(0),
+        workspace: entry.workspace,
+        url: entry.url,
+        branch: entry.branch,
+        repositories: pushedOf(entry.repository, entry.submodules),
+        refused: refusal && {
+            reason: GitFailure_Reason[refusal.reason].replace("REASON_", ""),
+            said: refusal.gitSaid,
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+import { Code } from "@connectrpc/connect";
+/**
+ * A refusal from gitd: its reason (AUTH_REQUIRED, NOT_FOUND, PATH_REFUSED, BUSY, …) and
+ * what git said. Tell users what happened from the reason, never by parsing the message.
+ */
+export declare class GitdError extends Error {
+    readonly reason: string;
+    readonly said: string;
+    readonly code: Code;
+    constructor(reason: string, said: string, code: Code);
+}
+/** Reads a Connect error into a GitdError; anything else is passed on as it is. */
+export declare function refusal(error: unknown): unknown;

package/dist/errors.js

@@ -0,0 +1,30 @@
+import { ConnectError } from "@connectrpc/connect";
+import { GitFailureSchema, GitFailure_Reason } from "./gen/gitd/v1/gitd_pb.js";
+/**
+ * A refusal from gitd: its reason (AUTH_REQUIRED, NOT_FOUND, PATH_REFUSED, BUSY, …) and
+ * what git said. Tell users what happened from the reason, never by parsing the message.
+ */
+export class GitdError extends Error {
+    reason;
+    said;
+    code;
+    constructor(reason, said, code) {
+        super(reason ? `${reason}: ${said}` : said);
+        this.reason = reason;
+        this.said = said;
+        this.code = code;
+        this.name = "GitdError";
+    }
+}
+/** Reads a Connect error into a GitdError; anything else is passed on as it is. */
+export function refusal(error) {
+    if (error instanceof GitdError || !(error instanceof ConnectError)) {
+        return error;
+    }
+    const [failure] = error.findDetails(GitFailureSchema);
+    if (!failure) {
+        return new GitdError("", error.rawMessage, error.code);
+    }
+    const reason = GitFailure_Reason[failure.reason].replace("REASON_", "");
+    return new GitdError(reason, failure.gitSaid, error.code);
+}