gitd-client 0.7.0 → 0.9.0

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

@@ -1,6 +1,6 @@
 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";
+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;
@@ -9,4 +9,8 @@ export declare function accessName(access: ProbeResponse_Access): Probe["access"
 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

@@ -1,5 +1,5 @@
 import { timestampDate } from "@bufbuild/protobuf/wkt";
-import { GitFailure_Reason, ProbeResponse_Access, Strategy, } from "./gen/gitd/v1/gitd_pb.js";
+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 {
@@ -7,7 +7,7 @@ export function toWorkspace(path, result) {
         commit: result.commit,
         branch: result.branch,
         strategy: strategyName(result.strategy),
-        layers: layers && { lower: layers.lower, upper: layers.upper, work: layers.work },
+        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,
@@ -64,17 +64,65 @@ export function pushedOf(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 refusal = entry.refusal;
+    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: refusal && {
-            reason: GitFailure_Reason[refusal.reason].replace("REASON_", ""),
-            said: refusal.gitSaid,
+        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/endpoint-types.d.ts

@@ -0,0 +1,28 @@
+/** A token of gitd's endpoint as gitd shows it, never its secret. */
+export interface TokenInfo {
+    id: string;
+    /** The repository it reads. */
+    url: string;
+    /** The sandbox repository it pushes to, when writable. */
+    sandbox: string;
+    writable: boolean;
+    issuedAt: Date;
+    expiresAt: Date;
+}
+/** A token just issued: its secret, shown this once, and where the sandbox clones from. */
+export interface IssuedToken {
+    secret: string;
+    cloneUrl: string;
+    /** The clone URL with the secret in it, for the sandbox's git: `git clone <this>`. */
+    authenticatedUrl: string;
+    info: TokenInfo;
+}
+export interface IssueTokenOptions {
+    /** The branch the sandbox starts from; default the repository's default branch. */
+    branch?: string;
+    /** How long the token lives, in seconds: an hour by default, a day at most. */
+    lifetimeSeconds?: number;
+    readOnly?: boolean;
+    /** A sandbox repository from an earlier token, to keep pushing to. */
+    sandbox?: string;
+}

package/dist/endpoint-types.js

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

package/dist/endpoint.d.ts

@@ -0,0 +1,18 @@
+import type { Client } from "@connectrpc/connect";
+import type { EndpointService } from "./gen/gitd/v1/gitd_pb.js";
+import type { IssuedToken, IssueTokenOptions, TokenInfo } from "./endpoint-types.js";
+/**
+ * gitd's endpoint, as `gitd.endpoint`: tokens for sandboxes that clone over HTTP instead of
+ * mounting a workspace. What a sandbox pushes is published with `gitd.publish("", branch,
+ * { sandbox })`.
+ */
+export declare class Endpoint {
+    private readonly endpoint;
+    constructor(endpoint: Client<typeof EndpointService>);
+    /** A token for a sandbox: it reads url and pushes to its own sandbox repository. */
+    issue(url: string, options?: IssueTokenOptions): Promise<IssuedToken>;
+    /** Ends a token now, and removes its sandbox repository when asked. */
+    revoke(id: string, removeSandbox?: boolean): Promise<void>;
+    /** The tokens alive, never their secrets. */
+    tokens(): Promise<TokenInfo[]>;
+}

package/dist/endpoint.js

@@ -0,0 +1,49 @@
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { call } from "./calls.js";
+/**
+ * gitd's endpoint, as `gitd.endpoint`: tokens for sandboxes that clone over HTTP instead of
+ * mounting a workspace. What a sandbox pushes is published with `gitd.publish("", branch,
+ * { sandbox })`.
+ */
+export class Endpoint {
+    endpoint;
+    constructor(endpoint) {
+        this.endpoint = endpoint;
+    }
+    /** A token for a sandbox: it reads url and pushes to its own sandbox repository. */
+    async issue(url, options = {}) {
+        const answer = await call(() => this.endpoint.issueToken({
+            url,
+            branch: options.branch ?? "",
+            lifetimeSeconds: BigInt(options.lifetimeSeconds ?? 0),
+            readOnly: options.readOnly ?? false,
+            sandbox: options.sandbox ?? "",
+        }));
+        const [scheme, rest] = answer.cloneUrl.split("://", 2);
+        return {
+            secret: answer.token,
+            cloneUrl: answer.cloneUrl,
+            authenticatedUrl: rest ? `${scheme}://x:${answer.token}@${rest}` : answer.cloneUrl,
+            info: toTokenInfo(answer.info),
+        };
+    }
+    /** Ends a token now, and removes its sandbox repository when asked. */
+    async revoke(id, removeSandbox = false) {
+        await call(() => this.endpoint.revokeToken({ id, removeSandbox }));
+    }
+    /** The tokens alive, never their secrets. */
+    async tokens() {
+        const answer = await call(() => this.endpoint.listTokens({}));
+        return answer.tokens.map(toTokenInfo);
+    }
+}
+function toTokenInfo(info) {
+    return {
+        id: info?.id ?? "",
+        url: info?.url ?? "",
+        sandbox: info?.sandbox ?? "",
+        writable: info?.writable ?? false,
+        issuedAt: info?.issuedAt ? timestampDate(info.issuedAt) : new Date(0),
+        expiresAt: info?.expiresAt ? timestampDate(info.expiresAt) : new Date(0),
+    };
+}