gitd-client 0.0.0-stage → 0.8.0

package/dist/types.d.ts

@@ -0,0 +1,232 @@
+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. */
+export interface Workspace {
+    path: string;
+    commit: string;
+    /** The branch it follows; empty when detached at a commit. */
+    branch: string;
+    strategy: StrategyName;
+    /** 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[];
+    /** Files the repository keeps in git LFS: pointers here, as gitd does not download them. */
+    lfsPatterns: string[];
+}
+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;
+    url: string;
+    reason: string;
+}
+/** What a workspace is on disk. */
+export interface Description {
+    url: string;
+    commit: string;
+    branch: string;
+    /** Whether there are uncommitted changes. */
+    modified: boolean;
+    strategy: StrategyName;
+    submodules: Submodule[];
+    /** Files kept in git LFS, which are pointers here. */
+    lfsPatterns: string[];
+}
+export interface Submodule {
+    path: string;
+    url: string;
+    commit: string;
+    checkedOut: boolean;
+}
+/** 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;
+    /** The submodule's path; empty for the workspace's own repository. */
+    path: string;
+    commit: string;
+    /** 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;
+    gitVersion: string;
+    pools: number;
+    poolsBytes: number;
+    templates: number;
+    templatesBytes: number;
+    strategy: StrategyName;
+    strategyReason: string;
+}
+/** Whether a repository can be read, and its branches. */
+export interface Probe {
+    access: "public" | "reachable" | "denied";
+    defaultBranch: string;
+    /** Each branch and the commit it points at. */
+    branches: Record<string, string>;
+    /** Why it cannot be read, when denied. */
+    denied?: string;
+}
+/** 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. */
+    workspace: string;
+    /** The workspace's repository; empty when the workspace could not be opened. */
+    url: string;
+    branch: string;
+    /** What was pushed, the workspace's repository first; empty when refused. */
+    repositories: PublishedRepository[];
+    /** Why it was refused, when it was. */
+    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. */
+    since?: Date;
+    /** Only the publishes of this repository, by its URL. */
+    url?: string;
+    /** At most this many: 100 by default, never more than 1000. */
+    limit?: number;
+}
+/** Options of a call that streams progress. */
+export interface Progressing {
+    /** Told what git is doing while the call runs. */
+    onProgress?: (progress: Progress) => void;
+    signal?: AbortSignal;
+}
+export interface PrepareOptions extends Progressing {
+    url: string;
+    path: string;
+    branch?: string;
+    commit?: string;
+    submodules?: boolean;
+    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. */
+    branch?: string;
+    submodules?: boolean;
+}
+export interface CheckoutOptions extends Progressing {
+    submodules?: boolean;
+}

package/dist/types.js

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

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,52 @@
 {
   "name": "gitd-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.0",
+  "description": "Client for gitd: instant, secretless git checkouts for agent sandboxes",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dooservice/gitd.git",
+    "directory": "sdk/typescript"
+  },
+  "homepage": "https://github.com/dooservice/gitd",
+  "keywords": [
+    "git",
+    "ai-agents",
+    "sandbox",
+    "workspace",
+    "connectrpc"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "generate": "buf generate --template buf.gen.yaml ../../proto",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "example": "tsx examples/agent.ts"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.16.0",
+    "@connectrpc/connect": "^2.2.0",
+    "@connectrpc/connect-node": "^2.2.0"
+  },
+  "devDependencies": {
+    "@bufbuild/buf": "^1.74.0",
+    "@bufbuild/protoc-gen-es": "^2.16.0",
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
+}