gitd-client 0.7.0 → 0.8.0

package/dist/gitd.d.ts

@@ -1,5 +1,8 @@
 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 { 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;
@@ -7,10 +10,15 @@ export interface GitdOptions {
     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;
     private readonly workspaces;
     private readonly repositories;
     private readonly server;
@@ -27,10 +35,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,15 +1,26 @@
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
 import { createClient } from "@connectrpc/connect";
 import { createConnectTransport } from "@connectrpc/connect-node";
-import { RepositoryService, ServerService, WorkspaceService } from "./gen/gitd/v1/gitd_pb.js";
+import { ConnectionService, 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 { 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;
     workspaces;
     repositories;
     server;
@@ -18,6 +29,8 @@ export class Gitd {
         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));
     }
     /** Which gitd answers, and how it makes workspaces here and why. */
     async info() {
@@ -52,6 +65,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 +100,24 @@ 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 ?? "",
+            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,6 +129,69 @@ 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 }));

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { Gitd, type GitdOptions } from "./gitd.js";
 export { GitdError } from "./errors.js";
+export { Credentials } from "./credentials.js";
+export { Publishing } from "./publishing.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,5 @@
 export { Gitd } from "./gitd.js";
 export { GitdError } from "./errors.js";
+export { Credentials } from "./credentials.js";
+export { Publishing } from "./publishing.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,70 @@
+/** 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;
+}
+/** 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 }));
+    }
+}

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { Progress } from "./gen/gitd/v1/gitd_pb.js";
+import type { OpenedPullRequest, Provenance } from "./publishing-types.js";
 /** How a workspace was made: a layer on a shared template, a block clone, or every file written. */
 export type StrategyName = "overlay" | "reflink" | "copy";
 /** Where a workspace ended up. */
@@ -8,7 +9,7 @@ export interface Workspace {
     /** The branch it follows; empty when detached at a commit. */
     branch: string;
     strategy: StrategyName;
-    /** An overlay workspace's template (lower) and its own layer (upper, work). */
+    /** An overlay workspace's template (lower), its own layer (upper, work), and its warm layer. */
     layers?: Layers;
     /** Submodules that could not be checked out, and why. */
     pendingSubmodules: PendingSubmodule[];
@@ -19,6 +20,21 @@ export interface Layers {
     lower: string;
     upper: string;
     work: string;
+    /** The warm layer between the template and its own, when it stands on one; else empty. */
+    warm: string;
+}
+/** A layer sealed from a workspace — what installing its dependencies wrote — for later ones to stand on. */
+export interface WarmLayer {
+    url: string;
+    name: string;
+    /** Workspaces stand on it at this commit only. */
+    commit: string;
+    sealedAt: Date;
+    sealedFrom: string;
+    /** Files it changes that git does not ignore, e.g. a lock file rewritten. */
+    changedFiles: number;
+    /** Workspaces standing on it now. */
+    users: number;
 }
 export interface PendingSubmodule {
     path: string;
@@ -43,10 +59,20 @@ export interface Submodule {
     commit: string;
     checkedOut: boolean;
 }
-/** What a publish pushed: the workspace's repository first, then each submodule. */
+/** Why gitd refused something: its reason (POLICY_REFUSED, AUTH_REQUIRED, …) and what was said. */
+export interface Refusal {
+    reason: string;
+    said: string;
+}
+/**
+ * What a publish pushed: the workspace's repository first, then each submodule; the pull
+ * request it opened, or why it could not, the branch being published either way.
+ */
 export interface Published {
     branch: string;
     repositories: PublishedRepository[];
+    pullRequest?: OpenedPullRequest;
+    pullRequestRefused?: Refusal;
 }
 export interface PublishedRepository {
     url: string;
@@ -56,6 +82,70 @@ export interface PublishedRepository {
     /** The subjects of the new commits, newest first. */
     subjects: string[];
 }
+/** How a file changed. */
+export type ChangeKind = "added" | "modified" | "deleted";
+/** A file changed, relative to the workspace, with its lines; a binary one counts none. */
+export interface ChangedFile {
+    path: string;
+    kind: ChangeKind;
+    addedLines: number;
+    removedLines: number;
+    binary: boolean;
+}
+/** What was changed in a workspace since gitd put it on `base`, committed or not. */
+export interface Changes {
+    base: string;
+    /** Read from the agent's own layer, with no git run in the workspace. */
+    fromLayer: boolean;
+    files: ChangedFile[];
+}
+/** The unified diff of a workspace's changes. */
+export interface Diff {
+    base: string;
+    diff: string;
+    /** Cut short at maxBytes. */
+    truncated: boolean;
+}
+export interface DiffOptions {
+    /** Only these files, relative to the workspace. */
+    files?: string[];
+    /** At most this many bytes: 512 KiB by default, never more than 8 MiB. */
+    maxBytes?: number;
+    includeIgnored?: boolean;
+}
+/** One work: a workspace by its path, or a branch gitd published or its pool holds. */
+export type Side = {
+    workspace: string;
+} | {
+    branch: string;
+};
+export interface CompareOptions {
+    /** The repository, when both sides are branches. */
+    url?: string;
+    withDiff?: boolean;
+    maxBytes?: number;
+    includeIgnored?: boolean;
+}
+/** How two works differ, from the first to the second. */
+export interface Comparison {
+    files: ChangedFile[];
+    diff: string;
+    truncated: boolean;
+}
+/** Two works that do not merge cleanly, and the files they conflict on. */
+export interface Conflict {
+    first: Side;
+    second: Side;
+    paths: string[];
+}
+/** What happened to a workspace. */
+export interface WorkspaceEvent {
+    kind: "made" | "changed" | "published" | "refused" | "removed";
+    path: string;
+    time: Date;
+    branch: string;
+    detail: string;
+}
 /** Which gitd answers, and how it makes workspaces on its machine. */
 export interface Info {
     version: string;
@@ -76,7 +166,15 @@ export interface Probe {
     /** Why it cannot be read, when denied. */
     denied?: string;
 }
-/** One publish, done or refused, as the audit log keeps it. */
+/** A change to the credentials or publishing settings, as the audit log keeps it. */
+export interface ConfigurationChange {
+    /** connection_added, connection_removed, settings_set or settings_removed. */
+    action: string;
+    /** The credential's id, or the settings' prefix. */
+    subject: string;
+    urlPrefix: string;
+}
+/** One publish, done or refused, or one change to credentials or settings, as the audit log keeps it. */
 export interface AuditEntry {
     time: Date;
     /** The workspace's path, as the caller gave it. */
@@ -87,10 +185,13 @@ export interface AuditEntry {
     /** What was pushed, the workspace's repository first; empty when refused. */
     repositories: PublishedRepository[];
     /** Why it was refused, when it was. */
-    refused?: {
-        reason: string;
-        said: string;
-    };
+    refused?: Refusal;
+    /** Who asked for the work, as the publish said. */
+    requestedBy: string;
+    pullRequest?: OpenedPullRequest;
+    pullRequestRefused?: Refusal;
+    change?: ConfigurationChange;
+    provenance?: Provenance;
 }
 export interface AuditOptions {
     /** Only the publishes from this time on. */
@@ -115,6 +216,11 @@ export interface PrepareOptions extends Progressing {
     fullHistory?: boolean;
     /** A preference; gitd falls back to copy when it cannot run here. */
     strategy?: StrategyName;
+    /**
+     * A warm layer to stand on, its dependencies installed already: the workspace is then made
+     * by overlay, at the commit the layer was sealed at, or not at all.
+     */
+    warm?: string;
 }
 export interface UpdateOptions extends Progressing {
     /** The branch to follow; default: the one it follows. */

package/dist/warm-convert.d.ts

@@ -0,0 +1,4 @@
+import type { WarmLayer as WarmLayerMessage } from "./gen/gitd/v1/gitd_pb.js";
+import type { WarmLayer } from "./types.js";
+/** A warm layer as gitd answers it, read as this client's. */
+export declare function toWarmLayer(warm: WarmLayerMessage | undefined): WarmLayer;

package/dist/warm-convert.js

@@ -0,0 +1,12 @@
+/** A warm layer as gitd answers it, read as this client's. */
+export function toWarmLayer(warm) {
+    return {
+        url: warm?.url ?? "",
+        name: warm?.name ?? "",
+        commit: warm?.commit ?? "",
+        sealedAt: new Date(Number(warm?.sealedAt ?? 0n) * 1000),
+        sealedFrom: warm?.sealedFrom ?? "",
+        changedFiles: warm?.changedFiles ?? 0,
+        users: warm?.users ?? 0,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitd-client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Client for gitd: instant, secretless git checkouts for agent sandboxes",
   "license": "Apache-2.0",
   "repository": {