gitd-client 0.7.0 → 0.9.0

package/dist/gitd.d.ts

@@ -1,16 +1,36 @@
 import { type Transport } from "@connectrpc/connect";
-import type { AuditEntry, AuditOptions, CheckoutOptions, Description, Info, PrepareOptions, Probe, Published, UpdateOptions, Workspace } from "./types.js";
+import { Credentials } from "./credentials.js";
+import { Endpoint } from "./endpoint.js";
+import { Publishing } from "./publishing.js";
+import type { PublishOptions } from "./publishing-types.js";
+import type { AuditEntry, AuditOptions, Changes, CheckoutOptions, CompareOptions, Comparison, Conflict, Description, Diff, DiffOptions, Info, PrepareOptions, Probe, Published, Side, WorkspaceEvent, UpdateOptions, WarmLayer, Workspace } from "./types.js";
 export interface GitdOptions {
     /** gitd's Unix socket; default $GITD_SOCKET, then /run/gitd/gitd.sock. */
     socket?: string;
+    /**
+     * A gitd on the network instead, e.g. `https://gitd.internal:9420` (or http:// on a private
+     * network); default $GITD_URL.
+     */
+    url?: string;
+    /** The key naming your tenant; default the file $GITD_KEY_FILE names, then $GITD_KEY. */
+    key?: string;
+    /** The PEM of a certificate authority the system does not trust; default $GITD_CA_FILE's. */
+    ca?: string;
     /** A transport of your own instead, e.g. for tests. */
     transport?: Transport;
 }
 /**
- * A gitd on its Unix socket. No call takes a credential: gitd reads and publishes with the
- * ones it keeps.
+ * A gitd on its Unix socket. No call on workspaces takes a credential: gitd reads and
+ * publishes with the ones it keeps, which a platform manages through `credentials`, and
+ * publishing follows the rules it sets through `publishing`.
  */
 export declare class Gitd {
+    /** The credentials gitd keeps, and connecting GitHub. */
+    readonly credentials: Credentials;
+    /** The rules publishing follows, per repository prefix. */
+    readonly publishing: Publishing;
+    /** Tokens of gitd's endpoint, for sandboxes elsewhere. */
+    readonly endpoint: Endpoint;
     private readonly workspaces;
     private readonly repositories;
     private readonly server;
@@ -27,10 +47,31 @@ export declare class Gitd {
     checkout(path: string, commit: string, options?: CheckoutOptions): Promise<Workspace>;
     /** What a workspace is on disk, without the network. */
     describe(path: string): Promise<Description>;
-    /** Pushes what was committed in a workspace to a new branch, with the token gitd keeps. */
-    publish(path: string, branch: string): Promise<Published>;
+    /**
+     * Pushes what was committed in a workspace to a new branch, with the credential gitd
+     * keeps, and opens its pull request when the publishing settings or the options say so.
+     */
+    publish(path: string, branch: string, options?: PublishOptions): Promise<Published>;
     /** The audit log: every publish, done or refused, newest first. */
     audit(options?: AuditOptions): Promise<AuditEntry[]>;
+    /** What was changed in a workspace since gitd put it on its commit, committed or not. */
+    changes(path: string, includeIgnored?: boolean): Promise<Changes>;
+    /** The unified diff of a workspace's changes, of some files or all, cut short at a size. */
+    diff(path: string, options?: DiffOptions): Promise<Diff>;
+    /** How two works of one repository differ, from first to second. */
+    compare(first: Side, second: Side, options?: CompareOptions): Promise<Comparison>;
+    /** Which pairs of works do not merge cleanly; a workspace stands for what it committed. */
+    conflicts(sides: Side[], url?: string): Promise<Conflict[]>;
+    /** What happens to the workspaces at paths, or to every one, as it happens. */
+    watch(paths?: string[], signal?: AbortSignal): AsyncGenerator<WorkspaceEvent>;
+    /**
+     * Seals what was installed in an overlay workspace as the warm layer `name` of its
+     * repository, for workspaces made later at the same commit to stand on. The layer is
+     * moved, not copied: the workspace is removed.
+     */
+    seal(path: string, name: string): Promise<WarmLayer>;
+    /** The warm layers of a repository. */
+    warmLayers(url: string): Promise<WarmLayer[]>;
     /** Deletes a workspace; its pool stays. */
     remove(path: string): Promise<void>;
 }

package/dist/gitd.js

@@ -1,23 +1,41 @@
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
 import { createClient } from "@connectrpc/connect";
+import { readFileSync } from "node:fs";
 import { createConnectTransport } from "@connectrpc/connect-node";
-import { RepositoryService, ServerService, WorkspaceService } from "./gen/gitd/v1/gitd_pb.js";
+import { ConnectionService, EndpointService, PublishingService, RepositoryService, ServerService, WorkspaceService, } from "./gen/gitd/v1/gitd_pb.js";
 import { call, drain } from "./calls.js";
-import { accessName, pushedOf, revisionOf, strategyName, strategyProto, toAuditEntry, toWorkspace, } from "./convert.js";
+import { sideProto, toEvent, toSide } from "./compare-convert.js";
+import { toWarmLayer } from "./warm-convert.js";
+import { refusal } from "./errors.js";
+import { Credentials } from "./credentials.js";
+import { Endpoint } from "./endpoint.js";
+import { pullRequestOptionsProto } from "./publishing-convert.js";
+import { Publishing } from "./publishing.js";
+import { accessName, publishedOf, revisionOf, strategyName, strategyProto, toAuditEntry, toChangedFiles, toChanges, toWorkspace, } from "./convert.js";
 const defaultSocket = "/run/gitd/gitd.sock";
 /**
- * A gitd on its Unix socket. No call takes a credential: gitd reads and publishes with the
- * ones it keeps.
+ * A gitd on its Unix socket. No call on workspaces takes a credential: gitd reads and
+ * publishes with the ones it keeps, which a platform manages through `credentials`, and
+ * publishing follows the rules it sets through `publishing`.
  */
 export class Gitd {
+    /** The credentials gitd keeps, and connecting GitHub. */
+    credentials;
+    /** The rules publishing follows, per repository prefix. */
+    publishing;
+    /** Tokens of gitd's endpoint, for sandboxes elsewhere. */
+    endpoint;
     workspaces;
     repositories;
     server;
     constructor(options = {}) {
-        const transport = options.transport ?? socketTransport(options.socket);
+        const transport = options.transport ?? transportFor(options);
         this.workspaces = createClient(WorkspaceService, transport);
         this.repositories = createClient(RepositoryService, transport);
         this.server = createClient(ServerService, transport);
+        this.credentials = new Credentials(createClient(ConnectionService, transport));
+        this.publishing = new Publishing(createClient(PublishingService, transport));
+        this.endpoint = new Endpoint(createClient(EndpointService, transport));
     }
     /** Which gitd answers, and how it makes workspaces here and why. */
     async info() {
@@ -52,6 +70,7 @@ export class Gitd {
             withSubmodules: options.submodules ?? false,
             fullHistory: options.fullHistory ?? false,
             strategy: strategyProto(options.strategy),
+            warm: options.warm ?? "",
         };
         const stream = this.workspaces.prepare(request, { signal: options.signal });
         return toWorkspace(options.path, await drain(stream, options.onProgress));
@@ -86,10 +105,25 @@ export class Gitd {
             lfsPatterns: answer.lfsPatterns,
         };
     }
-    /** Pushes what was committed in a workspace to a new branch, with the token gitd keeps. */
-    async publish(path, branch) {
-        const answer = await call(() => this.workspaces.publish({ path, branch }));
-        return { branch: answer.branch, repositories: pushedOf(answer.repository, answer.submodules) };
+    /**
+     * Pushes what was committed in a workspace to a new branch, with the credential gitd
+     * keeps, and opens its pull request when the publishing settings or the options say so.
+     */
+    async publish(path, branch, options = {}) {
+        const answer = await call(() => this.workspaces.publish({
+            path,
+            branch,
+            requestedBy: options.requestedBy ?? "",
+            sandbox: options.sandbox ?? "",
+            pullRequest: pullRequestOptionsProto(options.pullRequest),
+            provenance: options.provenance && {
+                agent: options.provenance.agent ?? "",
+                model: options.provenance.model ?? "",
+                session: options.provenance.session ?? "",
+                taskUrl: options.provenance.taskUrl ?? "",
+            },
+        }));
+        return publishedOf(answer);
     }
     /** The audit log: every publish, done or refused, newest first. */
     async audit(options = {}) {
@@ -101,15 +135,107 @@ export class Gitd {
         const answer = await call(() => this.server.audit(request));
         return answer.entries.map(toAuditEntry);
     }
+    /** What was changed in a workspace since gitd put it on its commit, committed or not. */
+    async changes(path, includeIgnored = false) {
+        return toChanges(await call(() => this.workspaces.changes({ path, includeIgnored })));
+    }
+    /** The unified diff of a workspace's changes, of some files or all, cut short at a size. */
+    async diff(path, options = {}) {
+        const answer = await call(() => this.workspaces.diff({
+            path,
+            files: options.files ?? [],
+            maxBytes: BigInt(options.maxBytes ?? 0),
+            includeIgnored: options.includeIgnored ?? false,
+        }));
+        return { base: answer.base, diff: answer.diff, truncated: answer.truncated };
+    }
+    /** How two works of one repository differ, from first to second. */
+    async compare(first, second, options = {}) {
+        const answer = await call(() => this.workspaces.compare({
+            first: sideProto(first),
+            second: sideProto(second),
+            url: options.url ?? "",
+            withDiff: options.withDiff ?? false,
+            maxBytes: BigInt(options.maxBytes ?? 0),
+            includeIgnored: options.includeIgnored ?? false,
+        }));
+        return { files: toChangedFiles(answer.files), diff: answer.diff, truncated: answer.truncated };
+    }
+    /** Which pairs of works do not merge cleanly; a workspace stands for what it committed. */
+    async conflicts(sides, url = "") {
+        const answer = await call(() => this.workspaces.conflicts({ sides: sides.map(sideProto), url }));
+        return answer.conflicts.map((conflict) => ({
+            first: toSide(conflict.first),
+            second: toSide(conflict.second),
+            paths: conflict.paths,
+        }));
+    }
+    /** What happens to the workspaces at paths, or to every one, as it happens. */
+    async *watch(paths = [], signal) {
+        try {
+            for await (const event of this.workspaces.watch({ paths }, { signal })) {
+                yield toEvent(event);
+            }
+        }
+        catch (error) {
+            if (signal?.aborted) {
+                return;
+            }
+            throw refusal(error);
+        }
+    }
+    /**
+     * Seals what was installed in an overlay workspace as the warm layer `name` of its
+     * repository, for workspaces made later at the same commit to stand on. The layer is
+     * moved, not copied: the workspace is removed.
+     */
+    async seal(path, name) {
+        const answer = await call(() => this.workspaces.seal({ path, name }));
+        return toWarmLayer(answer.warm);
+    }
+    /** The warm layers of a repository. */
+    async warmLayers(url) {
+        const answer = await call(() => this.workspaces.listWarm({ url }));
+        return answer.warm.map(toWarmLayer);
+    }
     /** Deletes a workspace; its pool stays. */
     async remove(path) {
         await call(() => this.workspaces.remove({ path }));
     }
 }
-function socketTransport(socket) {
+/** The way to the gitd options name: its network address, else its socket, with the key. */
+function transportFor(options) {
+    const key = options.key ?? keyFromEnvironment();
+    const interceptors = key
+        ? [
+            (next) => async (request) => {
+                request.header.set("Authorization", `Bearer ${key}`);
+                return next(request);
+            },
+        ]
+        : [];
+    const url = options.url ?? process.env.GITD_URL;
+    if (url) {
+        const caFile = process.env.GITD_CA_FILE;
+        const ca = options.ca ?? (caFile ? readFileSync(caFile, "utf8") : undefined);
+        return createConnectTransport({
+            baseUrl: url.replace(/\/$/, ""),
+            httpVersion: "1.1",
+            interceptors,
+            nodeOptions: ca ? { ca } : {},
+        });
+    }
     return createConnectTransport({
         baseUrl: "http://gitd",
         httpVersion: "1.1",
-        nodeOptions: { socketPath: socket ?? process.env.GITD_SOCKET ?? defaultSocket },
+        interceptors,
+        nodeOptions: { socketPath: options.socket ?? process.env.GITD_SOCKET ?? defaultSocket },
     });
 }
+function keyFromEnvironment() {
+    const file = process.env.GITD_KEY_FILE;
+    if (file) {
+        return readFileSync(file, "utf8").trim();
+    }
+    return process.env.GITD_KEY?.trim() || undefined;
+}

package/dist/index.d.ts

@@ -1,4 +1,10 @@
 export { Gitd, type GitdOptions } from "./gitd.js";
 export { GitdError } from "./errors.js";
+export { Credentials } from "./credentials.js";
+export { Publishing } from "./publishing.js";
+export { Endpoint } from "./endpoint.js";
+export type * from "./endpoint-types.js";
 export type * from "./types.js";
+export type * from "./credential-types.js";
+export type * from "./publishing-types.js";
 export * as proto from "./gen/gitd/v1/gitd_pb.js";

package/dist/index.js

@@ -1,3 +1,6 @@
 export { Gitd } from "./gitd.js";
 export { GitdError } from "./errors.js";
+export { Credentials } from "./credentials.js";
+export { Publishing } from "./publishing.js";
+export { Endpoint } from "./endpoint.js";
 export * as proto from "./gen/gitd/v1/gitd_pb.js";

package/dist/publishing-convert.d.ts

@@ -0,0 +1,8 @@
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import { type Preset as PresetMessage, type PresetSchema, type PublishSettings as PublishSettingsMessage, type PublishSettingsSchema, type PullRequestOptionsSchema } from "./gen/gitd/v1/gitd_pb.js";
+import type { Preset, PublishSettings, PullRequestOptions } from "./publishing-types.js";
+export declare function toPublishSettings(settings: PublishSettingsMessage | undefined): PublishSettings;
+export declare function publishSettingsProto(settings: PublishSettings): MessageInitShape<typeof PublishSettingsSchema>;
+export declare function pullRequestOptionsProto(options: PullRequestOptions | undefined): MessageInitShape<typeof PullRequestOptionsSchema> | undefined;
+export declare function toPreset(preset: PresetMessage | undefined): Preset;
+export declare function presetProto(preset: Preset): MessageInitShape<typeof PresetSchema>;

package/dist/publishing-convert.js

@@ -0,0 +1,74 @@
+import { Preset_Origin, PullRequestSettings_Open, } from "./gen/gitd/v1/gitd_pb.js";
+export function toPublishSettings(settings) {
+    const pullRequests = settings?.pullRequests;
+    return {
+        urlPrefix: settings?.urlPrefix ?? "",
+        preset: settings?.preset || undefined,
+        protectedPaths: settings?.protectedPaths ?? [],
+        keptPaths: settings?.keptPaths ?? [],
+        allowedPaths: settings?.allowedPaths ?? [],
+        maxChangedFiles: settings?.maxChangedFiles,
+        branchPrefix: settings?.branchPrefix ?? "",
+        pullRequests: pullRequests && {
+            opening: pullRequests.open === PullRequestSettings_Open.ALWAYS ? "always" : "when_asked",
+            draft: pullRequests.draft,
+            labels: pullRequests.labels,
+            requestReviewFromRequester: pullRequests.requestReviewFromRequester,
+        },
+        fromFile: settings?.fromFile ?? false,
+    };
+}
+export function publishSettingsProto(settings) {
+    const pullRequests = settings.pullRequests;
+    return {
+        urlPrefix: settings.urlPrefix,
+        preset: settings.preset ?? "",
+        protectedPaths: settings.protectedPaths ?? [],
+        keptPaths: settings.keptPaths ?? [],
+        allowedPaths: settings.allowedPaths ?? [],
+        maxChangedFiles: settings.maxChangedFiles,
+        branchPrefix: settings.branchPrefix ?? "",
+        pullRequests: pullRequests && {
+            open: pullRequests.opening === "always" ? PullRequestSettings_Open.ALWAYS : PullRequestSettings_Open.WHEN_ASKED,
+            draft: pullRequests.draft ?? false,
+            labels: pullRequests.labels ?? [],
+            requestReviewFromRequester: pullRequests.requestReviewFromRequester ?? false,
+        },
+    };
+}
+export function pullRequestOptionsProto(options) {
+    return (options && {
+        open: options.open ?? false,
+        title: options.title ?? "",
+        body: options.body ?? "",
+        base: options.base ?? "",
+        draft: options.draft,
+    });
+}
+export function toPreset(preset) {
+    return {
+        name: preset?.name ?? "",
+        protectedPaths: preset?.protectedPaths ?? [],
+        keptPaths: preset?.keptPaths ?? [],
+        maxChangedFiles: preset?.maxChangedFiles,
+        origin: originName(preset?.origin ?? Preset_Origin.UNSPECIFIED),
+    };
+}
+export function presetProto(preset) {
+    return {
+        name: preset.name,
+        protectedPaths: preset.protectedPaths ?? [],
+        keptPaths: preset.keptPaths ?? [],
+        maxChangedFiles: preset.maxChangedFiles,
+    };
+}
+function originName(origin) {
+    switch (origin) {
+        case Preset_Origin.BUILT_IN:
+            return "built_in";
+        case Preset_Origin.FILE:
+            return "file";
+        default:
+            return "api";
+    }
+}

package/dist/publishing-types.d.ts

@@ -0,0 +1,72 @@
+/** When publishes open pull requests: only when a publish asks, or always. */
+export type Opening = "when_asked" | "always";
+/** How publishes open pull requests. */
+export interface PullRequestSettings {
+    opening: Opening;
+    draft?: boolean;
+    labels?: string[];
+    /** Ask the person a publish names as requester to review it. */
+    requestReviewFromRequester?: boolean;
+}
+/** The rules of the repositories whose address starts with urlPrefix ("" for every one). */
+export interface PublishSettings {
+    urlPrefix: string;
+    /** The name of a preset whose rules these take; `recommended` is gitd's own. */
+    preset?: string;
+    /** Paths a publish may not change, as git's glob pathspecs, e.g. `.github/workflows/**`. */
+    protectedPaths?: string[];
+    /** Paths a publish may change but not delete or rename away. */
+    keptPaths?: string[];
+    /** Paths these settings' own rules leave free, e.g. `.gitmodules` under `recommended`. */
+    allowedPaths?: string[];
+    maxChangedFiles?: number;
+    /** What every published branch must start with, e.g. `agents/`. */
+    branchPrefix?: string;
+    pullRequests?: PullRequestSettings;
+    /** Declared in gitd.toml: shown, never changed through the API. */
+    fromFile?: boolean;
+}
+/** Where a preset comes from: gitd's own, gitd.toml, or the API. */
+export type PresetOrigin = "built_in" | "file" | "api";
+/** A named set of rules settings take; one named `recommended` replaces gitd's own. */
+export interface Preset {
+    name: string;
+    protectedPaths?: string[];
+    keptPaths?: string[];
+    maxChangedFiles?: number;
+    /** Read from gitd, never sent. */
+    origin?: PresetOrigin;
+}
+/** A publish's own say on its pull request. */
+export interface PullRequestOptions {
+    /** Open one even when the settings open them only when asked. */
+    open?: boolean;
+    /** Default: the newest commit's subject. */
+    title?: string;
+    /** Text that comes before what gitd checked. */
+    body?: string;
+    /** The branch it merges into; default: the repository's default branch. */
+    base?: string;
+    draft?: boolean;
+}
+/** Where a publish's work came from, as the platform says; gitd records it as told. */
+export interface Provenance {
+    agent?: string;
+    model?: string;
+    session?: string;
+    /** An https address: an issue, a ticket. */
+    taskUrl?: string;
+}
+export interface PublishOptions {
+    /** Who asked for the work, as their account on the host. */
+    requestedBy?: string;
+    pullRequest?: PullRequestOptions;
+    provenance?: Provenance;
+    /** Publish what a sandbox pushed through the endpoint instead of a workspace; path is then "". */
+    sandbox?: string;
+}
+/** A pull request gitd opened. */
+export interface OpenedPullRequest {
+    url: string;
+    number: number;
+}

package/dist/publishing-types.js

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

package/dist/publishing.d.ts

@@ -0,0 +1,23 @@
+import type { Client } from "@connectrpc/connect";
+import type { PublishingService } from "./gen/gitd/v1/gitd_pb.js";
+import type { Preset, PublishSettings } from "./publishing-types.js";
+/**
+ * The rules publishing follows, per repository prefix, as `gitd.publishing`: for a
+ * platform's own pages, never for an agent.
+ */
+export declare class Publishing {
+    private readonly publishing;
+    constructor(publishing: Client<typeof PublishingService>);
+    /** Every setting, gitd.toml's included. */
+    settings(): Promise<PublishSettings[]>;
+    /** Keeps the settings of a prefix, replacing those it had, as gitd checked them. */
+    set(settings: PublishSettings): Promise<PublishSettings>;
+    /** Forgets the settings of a prefix set through the API. */
+    remove(urlPrefix: string): Promise<void>;
+    /** Every preset as it applies: gitd's own, gitd.toml's and those set through the API. */
+    presets(): Promise<Preset[]>;
+    /** Keeps a preset, replacing one of the same name; `recommended` replaces gitd's own. */
+    setPreset(preset: Preset): Promise<Preset>;
+    /** Forgets a preset set through the API; refused while settings take it. */
+    removePreset(name: string): Promise<void>;
+}

package/dist/publishing.js

@@ -0,0 +1,40 @@
+import { call } from "./calls.js";
+import { presetProto, publishSettingsProto, toPreset, toPublishSettings } from "./publishing-convert.js";
+/**
+ * The rules publishing follows, per repository prefix, as `gitd.publishing`: for a
+ * platform's own pages, never for an agent.
+ */
+export class Publishing {
+    publishing;
+    constructor(publishing) {
+        this.publishing = publishing;
+    }
+    /** Every setting, gitd.toml's included. */
+    async settings() {
+        const answer = await call(() => this.publishing.getSettings({}));
+        return answer.settings.map(toPublishSettings);
+    }
+    /** Keeps the settings of a prefix, replacing those it had, as gitd checked them. */
+    async set(settings) {
+        const answer = await call(() => this.publishing.setSettings({ settings: publishSettingsProto(settings) }));
+        return toPublishSettings(answer.settings);
+    }
+    /** Forgets the settings of a prefix set through the API. */
+    async remove(urlPrefix) {
+        await call(() => this.publishing.removeSettings({ urlPrefix }));
+    }
+    /** Every preset as it applies: gitd's own, gitd.toml's and those set through the API. */
+    async presets() {
+        const answer = await call(() => this.publishing.listPresets({}));
+        return answer.presets.map(toPreset);
+    }
+    /** Keeps a preset, replacing one of the same name; `recommended` replaces gitd's own. */
+    async setPreset(preset) {
+        const answer = await call(() => this.publishing.setPreset({ preset: presetProto(preset) }));
+        return toPreset(answer.preset);
+    }
+    /** Forgets a preset set through the API; refused while settings take it. */
+    async removePreset(name) {
+        await call(() => this.publishing.removePreset({ name }));
+    }
+}