gitd-client 0.0.0-stage → 0.8.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/compare-convert.d.ts

@@ -0,0 +1,6 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { type Side as SideMessage, type SideSchema, type WatchResponse } from "./gen/gitd/v1/gitd_pb.js";
+import type { Side, WorkspaceEvent } from "./types.js";
+export declare function sideProto(side: Side): MessageInitShape<typeof SideSchema>;
+export declare function toSide(side: SideMessage | undefined): Side;
+export declare function toEvent(event: WatchResponse): WorkspaceEvent;

package/dist/compare-convert.js

@@ -0,0 +1,33 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { WatchResponse_Kind, } from "./gen/gitd/v1/gitd_pb.js";
+export function sideProto(side) {
+    return "workspace" in side
+        ? { of: { case: "workspace", value: side.workspace } }
+        : { of: { case: "branch", value: side.branch } };
+}
+export function toSide(side) {
+    return side?.of.case === "workspace" ? { workspace: side.of.value } : { branch: side?.of.value ?? "" };
+}
+export function toEvent(event) {
+    return {
+        kind: eventKind(event.kind),
+        path: event.path,
+        time: event.time ? timestampDate(event.time) : new Date(0),
+        branch: event.branch,
+        detail: event.detail,
+    };
+}
+function eventKind(kind) {
+    switch (kind) {
+        case WatchResponse_Kind.MADE:
+            return "made";
+        case WatchResponse_Kind.PUBLISHED:
+            return "published";
+        case WatchResponse_Kind.REFUSED:
+            return "refused";
+        case WatchResponse_Kind.REMOVED:
+            return "removed";
+        default:
+            return "changed";
+    }
+}

package/dist/convert.d.ts

@@ -0,0 +1,16 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { ProbeResponse_Access, Strategy, type AuditEntry as AuditEntryMessage, type ChangedFile as ChangedFileMessage, type ChangesResponse, type PublishResponse, type PublishedRepository as PublishedRepositoryMessage, type RevisionSchema, type WorkspaceResult } from "./gen/gitd/v1/gitd_pb.js";
+import type { AuditEntry, ChangedFile, Changes, Probe, Published, 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[];
+/** What a publish pushed, and the pull request it opened or why it could not. */
+export declare function publishedOf(answer: PublishResponse): Published;
+export declare function toAuditEntry(entry: AuditEntryMessage): AuditEntry;
+export declare function toChanges(answer: ChangesResponse): Changes;
+export declare function toChangedFiles(files: ChangedFileMessage[]): ChangedFile[];

package/dist/convert.js

@@ -0,0 +1,128 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { ChangedFile_Kind, ConfigurationChange_Action, 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, warm: layers.warm },
+        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 }));
+}
+/** What a publish pushed, and the pull request it opened or why it could not. */
+export function publishedOf(answer) {
+    return {
+        branch: answer.branch,
+        repositories: pushedOf(answer.repository, answer.submodules),
+        pullRequest: openedOf(answer.pullRequest),
+        pullRequestRefused: refusalOf(answer.pullRequestFailure),
+    };
+}
+export function toAuditEntry(entry) {
+    const change = entry.change;
+    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: refusalOf(entry.refusal),
+        requestedBy: entry.requestedBy,
+        pullRequest: openedOf(entry.pullRequest),
+        pullRequestRefused: refusalOf(entry.pullRequestFailure),
+        provenance: entry.provenance && {
+            agent: entry.provenance.agent,
+            model: entry.provenance.model,
+            session: entry.provenance.session,
+            taskUrl: entry.provenance.taskUrl,
+        },
+        change: change && {
+            action: (ConfigurationChange_Action[change.action] ?? "").replace("ACTION_", "").toLowerCase(),
+            subject: change.subject,
+            urlPrefix: change.urlPrefix,
+        },
+    };
+}
+function openedOf(opened) {
+    return opened && { url: opened.url, number: Number(opened.number) };
+}
+function refusalOf(failure) {
+    return failure && { reason: (GitFailure_Reason[failure.reason] ?? "").replace("REASON_", ""), said: failure.gitSaid };
+}
+export function toChanges(answer) {
+    return { base: answer.base, fromLayer: answer.fromLayer, files: toChangedFiles(answer.files) };
+}
+export function toChangedFiles(files) {
+    return files.map((file) => ({
+        path: file.path,
+        kind: kindName(file.kind),
+        addedLines: file.addedLines,
+        removedLines: file.removedLines,
+        binary: file.binary,
+    }));
+}
+function kindName(kind) {
+    switch (kind) {
+        case ChangedFile_Kind.ADDED:
+            return "added";
+        case ChangedFile_Kind.DELETED:
+            return "deleted";
+        default:
+            return "modified";
+    }
+}

package/dist/credential-convert.d.ts

@@ -0,0 +1,3 @@
+import { type Connection } from "./gen/gitd/v1/gitd_pb.js";
+import type { KeptCredential } from "./credential-types.js";
+export declare function toKeptCredential(connection: Connection | undefined): KeptCredential;

package/dist/credential-convert.js

@@ -0,0 +1,27 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { Connection_Kind } from "./gen/gitd/v1/gitd_pb.js";
+export function toKeptCredential(connection) {
+    return {
+        id: connection?.id ?? "",
+        kind: kindName(connection?.kind ?? Connection_Kind.UNSPECIFIED),
+        urlPrefix: connection?.urlPrefix ?? "",
+        actsAs: connection?.actsAs ?? "",
+        appId: Number(connection?.appId ?? 0),
+        manageUrl: connection?.manageUrl ?? "",
+        expires: connection?.expires && timestampDate(connection.expires),
+        fromFile: connection?.fromFile ?? false,
+        created: connection?.created && timestampDate(connection.created),
+    };
+}
+function kindName(kind) {
+    switch (kind) {
+        case Connection_Kind.SSH_KEY:
+            return "ssh_key";
+        case Connection_Kind.GITHUB_APP:
+            return "github_app";
+        case Connection_Kind.GITHUB_LOGIN:
+            return "github_login";
+        default:
+            return "token";
+    }
+}

package/dist/credential-types.d.ts

@@ -0,0 +1,57 @@
+/** What a credential gitd keeps is: a token, an SSH key, a GitHub App, or a person signed in. */
+export type CredentialKind = "token" | "ssh_key" | "github_app" | "github_login";
+/** One credential gitd keeps, never its secret. */
+export interface KeptCredential {
+    /** What to remove it by. */
+    id: string;
+    kind: CredentialKind;
+    /** The repositories it opens: those whose address starts with this. */
+    urlPrefix: string;
+    /** Whom it acts as: an App's bot (`acme-agents[bot]`) or a person. */
+    actsAs: string;
+    appId: number;
+    /** Where an App's installations are managed. */
+    manageUrl: string;
+    /** When a sign-in stops renewing. */
+    expires?: Date;
+    /** Declared in gitd.toml: shown, never changed through the API. */
+    fromFile: boolean;
+    created?: Date;
+}
+/** A GitHub App or sign-in gitd now keeps, and where it is installed on repositories. */
+export interface Connected {
+    credential: KeptCredential;
+    installUrl: string;
+}
+/** What a browser posts to GitHub to create an App: `manifest`, as a form field, to `formAction`. */
+export interface AppToCreate {
+    formAction: string;
+    manifest: string;
+    /** Sent back by GitHub with the code, for completeGitHubApp. */
+    state: string;
+}
+/** A sign-in waiting for a person to enter `userCode` at `verificationUrl`. */
+export interface SignIn {
+    userCode: string;
+    verificationUrl: string;
+    loginId: string;
+    expiresInSeconds: number;
+}
+export interface BeginGitHubAppOptions {
+    /** The App's name on GitHub; its bot is `<name>[bot]`. */
+    name: string;
+    /** Where GitHub sends the person back with a code and the state. */
+    redirectUrl: string;
+    /** The organisation that owns it; default: the person creating it. */
+    organization?: string;
+    /** A GitHub Enterprise Server's host; default github.com. */
+    host?: string;
+}
+export interface AddGitHubAppOptions {
+    appId: number;
+    /** The App's private key, in PEM. */
+    privateKey: string;
+    host?: string;
+    /** The repositories it opens; default every one on the host. */
+    urlPrefix?: string;
+}

package/dist/credential-types.js

@@ -0,0 +1 @@
+export {};

package/dist/credentials.d.ts

@@ -0,0 +1,27 @@
+import type { Client } from "@connectrpc/connect";
+import type { ConnectionService } from "./gen/gitd/v1/gitd_pb.js";
+import type { AddGitHubAppOptions, AppToCreate, BeginGitHubAppOptions, Connected, KeptCredential, SignIn } from "./credential-types.js";
+/**
+ * The credentials gitd keeps, as `gitd.credentials`: for a platform's own pages, never for
+ * an agent.
+ */
+export declare class Credentials {
+    private readonly connections;
+    constructor(connections: Client<typeof ConnectionService>);
+    /** Every credential gitd keeps, gitd.toml's included, never a secret. */
+    list(): Promise<KeptCredential[]>;
+    /** Forgets a credential kept through the API. */
+    remove(id: string): Promise<void>;
+    /** Keeps a token for the repositories under urlPrefix, which names the host. */
+    addToken(urlPrefix: string, token: string, user?: string): Promise<KeptCredential>;
+    /** Keeps a GitHub App a platform already has, once GitHub takes the key as its own. */
+    addGitHubApp(options: AddGitHubAppOptions): Promise<KeptCredential>;
+    /** Starts creating the organisation's own GitHub App from a manifest. */
+    beginGitHubApp(options: BeginGitHubAppOptions): Promise<AppToCreate>;
+    /** Finishes creating the App with the code and state GitHub sent back. */
+    completeGitHubApp(code: string, state: string): Promise<Connected>;
+    /** Asks GitHub for the code a person enters to sign in through gitd's public App. */
+    startGitHubLogin(host?: string): Promise<SignIn>;
+    /** Waits until the person has entered the code, and keeps the sign-in. */
+    finishGitHubLogin(loginId: string): Promise<Connected>;
+}

package/dist/credentials.js

@@ -0,0 +1,66 @@
+import { call } from "./calls.js";
+import { toKeptCredential } from "./credential-convert.js";
+/**
+ * The credentials gitd keeps, as `gitd.credentials`: for a platform's own pages, never for
+ * an agent.
+ */
+export class Credentials {
+    connections;
+    constructor(connections) {
+        this.connections = connections;
+    }
+    /** Every credential gitd keeps, gitd.toml's included, never a secret. */
+    async list() {
+        const answer = await call(() => this.connections.listConnections({}));
+        return answer.connections.map(toKeptCredential);
+    }
+    /** Forgets a credential kept through the API. */
+    async remove(id) {
+        await call(() => this.connections.removeConnection({ id }));
+    }
+    /** Keeps a token for the repositories under urlPrefix, which names the host. */
+    async addToken(urlPrefix, token, user = "") {
+        const answer = await call(() => this.connections.addToken({ urlPrefix, token, user }));
+        return toKeptCredential(answer.connection);
+    }
+    /** Keeps a GitHub App a platform already has, once GitHub takes the key as its own. */
+    async addGitHubApp(options) {
+        const answer = await call(() => this.connections.addGitHubApp({
+            appId: BigInt(options.appId),
+            privateKey: options.privateKey,
+            host: options.host ?? "",
+            urlPrefix: options.urlPrefix ?? "",
+        }));
+        return toKeptCredential(answer.connection);
+    }
+    /** Starts creating the organisation's own GitHub App from a manifest. */
+    async beginGitHubApp(options) {
+        const answer = await call(() => this.connections.beginGitHubApp({
+            name: options.name,
+            redirectUrl: options.redirectUrl,
+            organization: options.organization ?? "",
+            host: options.host ?? "",
+        }));
+        return { formAction: answer.formAction, manifest: answer.manifest, state: answer.state };
+    }
+    /** Finishes creating the App with the code and state GitHub sent back. */
+    async completeGitHubApp(code, state) {
+        const answer = await call(() => this.connections.completeGitHubApp({ code, state }));
+        return { credential: toKeptCredential(answer.connection), installUrl: answer.installUrl };
+    }
+    /** Asks GitHub for the code a person enters to sign in through gitd's public App. */
+    async startGitHubLogin(host = "") {
+        const answer = await call(() => this.connections.startGitHubLogin({ host }));
+        return {
+            userCode: answer.userCode,
+            verificationUrl: answer.verificationUrl,
+            loginId: answer.loginId,
+            expiresInSeconds: answer.expiresInSeconds,
+        };
+    }
+    /** Waits until the person has entered the code, and keeps the sign-in. */
+    async finishGitHubLogin(loginId) {
+        const answer = await call(() => this.connections.finishGitHubLogin({ loginId }));
+        return { credential: toKeptCredential(answer.connection), installUrl: answer.installUrl };
+    }
+}

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);
+}