@bendyline/docblocks 1.1.2 → 2.0.0

package/src/filesystem/v2.ts

@@ -0,0 +1,231 @@
+import type { FsError } from './fs-error.js';
+import type { WorkspacePath } from './workspace-path.js';
+
+/**
+ * Opaque provider-issued token representing one observed entry/tree state.
+ * Tokens support equality only within the issuing provider; callers must not
+ * parse them or assume a move or byte-identical rewrite changes the token.
+ * A token need not be a content hash, but it must change whenever the issuing
+ * provider observes a potentially different kind, payload, or descendant
+ * state. Detection of non-cooperating external changes is bounded by the
+ * backend's declared capabilities and metadata precision.
+ */
+declare const fileSystemVersionBrand: unique symbol;
+export type FileSystemVersion = string & {
+  readonly [fileSystemVersionBrand]: 'FileSystemVersion';
+};
+
+/** Validate/rebrand a version received from a provider transport. */
+export function parseFileSystemVersion(value: unknown): FileSystemVersion {
+  if (typeof value !== 'string' || !value || value.length > 1024 || value.includes('\0')) {
+    throw new TypeError('Filesystem version tokens must be non-empty bounded strings.');
+  }
+  return value as FileSystemVersion;
+}
+
+export function tryParseFileSystemVersion(value: unknown): FileSystemVersion | null {
+  try {
+    return parseFileSystemVersion(value);
+  } catch {
+    return null;
+  }
+}
+
+/** `process` excludes this provider's local peers; `cross-context` also excludes cooperating tabs/processes. */
+export type FileSystemAtomicity = 'none' | 'process' | 'cross-context';
+export type FileSystemCaseSensitivity = 'sensitive' | 'insensitive' | 'platform';
+export type FileSystemDurability = 'volatile' | 'best-effort' | 'durable';
+export type FileSystemConditionalWriteStrength =
+  | 'none'
+  | 'process'
+  | 'cross-context'
+  | 'storage-atomic';
+export type FileSystemSymlinkPolicy = 'unsupported' | 'reject' | 'follow-contained' | 'preserve';
+
+/** Serializable feature declaration; consumers never need provider instanceof checks. */
+export interface FileSystemProviderCapabilities {
+  /** Isolation of one successful file replacement from cooperating writers. */
+  readonly writeAtomicity: FileSystemAtomicity;
+  /** Isolation of one successful source-to-destination move. */
+  readonly moveAtomicity: FileSystemAtomicity;
+  /** Writers excluded while one complete snapshot is captured. */
+  readonly snapshotAtomicity: FileSystemAtomicity;
+  /** Strongest boundary at which expectedVersion is checked with mutation. */
+  readonly conditionalWrite: FileSystemConditionalWriteStrength;
+  readonly recursiveRemove: boolean;
+  /** True only when watch has a real ready barrier and sequenced events. */
+  readonly watch: boolean;
+  readonly caseSensitivity: FileSystemCaseSensitivity;
+  readonly symlinkPolicy: FileSystemSymlinkPolicy;
+  readonly durability: FileSystemDurability;
+}
+
+interface FileSystemEntrySnapshotBase {
+  readonly path: WorkspacePath;
+  readonly name: string;
+  readonly version: FileSystemVersion;
+  /** ISO-8601 timestamp supplied by the backend; versions remain authoritative. */
+  readonly lastModified: string;
+}
+
+export interface FileSystemFileSnapshot extends FileSystemEntrySnapshotBase {
+  readonly kind: 'file';
+  readonly size: number;
+}
+
+export interface FileSystemDirectorySnapshot extends FileSystemEntrySnapshotBase {
+  readonly kind: 'directory';
+  readonly size: null;
+}
+
+export type FileSystemEntrySnapshot = FileSystemFileSnapshot | FileSystemDirectorySnapshot;
+
+/** A read always couples owned bytes to the exact metadata version they represent. */
+export interface FileSystemFileRead {
+  readonly entry: FileSystemFileSnapshot;
+  readonly data: ArrayBuffer;
+}
+
+export interface FileSystemSnapshotFile extends FileSystemFileSnapshot {
+  readonly data: ArrayBuffer;
+}
+
+export type FileSystemSnapshotEntry = FileSystemSnapshotFile | FileSystemDirectorySnapshot;
+
+/**
+ * Complete best-available tree traversal. `snapshotAtomicity` declares
+ * whether concurrent local/cross-context mutations are excluded while it is
+ * captured. Implementations must never expose aliased buffers.
+ */
+export interface FileSystemSnapshot {
+  readonly version: FileSystemVersion;
+  readonly entries: readonly FileSystemSnapshotEntry[];
+}
+
+export type FileSystemWriteMode = 'upsert' | 'create' | 'replace';
+
+export interface FileSystemWriteOptions {
+  /** Defaults to upsert. */
+  readonly mode?: FileSystemWriteMode;
+  /** Defaults to false so structure creation is never implicit. */
+  readonly createParents?: boolean;
+  /** null means the entry must not exist; a token requires an exact match. */
+  readonly expectedVersion?: FileSystemVersion | null;
+}
+
+export type FileSystemCreateDirectoryMode = 'ensure' | 'create';
+
+export interface FileSystemCreateDirectoryOptions {
+  /** Defaults to ensure (idempotently return an existing directory). */
+  readonly mode?: FileSystemCreateDirectoryMode;
+  /** Defaults to false. */
+  readonly createParents?: boolean;
+}
+
+export interface FileSystemRemoveOptions {
+  /** Defaults to false; non-empty directories otherwise fail with not-empty. */
+  readonly recursive?: boolean;
+  /** Defaults to error. */
+  readonly missing?: 'ignore' | 'error';
+  readonly expectedVersion?: FileSystemVersion;
+}
+
+export interface FileSystemRemoveResult {
+  readonly removed: boolean;
+  /** Version of the complete tree after the removal attempt. */
+  readonly version: FileSystemVersion;
+}
+
+export interface FileSystemMoveOptions {
+  /** Defaults to false. Destinations are never overwritten. */
+  readonly createParents?: boolean;
+  readonly expectedVersion?: FileSystemVersion;
+}
+
+export type FileSystemWatchEventType = 'created' | 'modified' | 'removed' | 'moved' | 'overflow';
+export type FileSystemWatchEventOrigin = 'local' | 'external' | 'unknown';
+
+interface FileSystemWatchEventBase {
+  readonly sequence: number;
+  readonly origin: FileSystemWatchEventOrigin;
+  readonly path: WorkspacePath;
+}
+
+export interface FileSystemEntryWatchEvent extends FileSystemWatchEventBase {
+  readonly type: Exclude<FileSystemWatchEventType, 'overflow'>;
+  readonly kind: 'file' | 'directory';
+  readonly destinationPath: WorkspacePath | null;
+  readonly version: FileSystemVersion | null;
+  readonly previousVersion: FileSystemVersion | null;
+}
+
+export interface FileSystemOverflowWatchEvent extends FileSystemWatchEventBase {
+  readonly type: 'overflow';
+  readonly kind: null;
+  readonly destinationPath: null;
+  readonly version: null;
+  readonly previousVersion: null;
+}
+
+export type FileSystemWatchEvent = FileSystemEntryWatchEvent | FileSystemOverflowWatchEvent;
+
+export type FileSystemWatchListener = (event: FileSystemWatchEvent) => void;
+export type FileSystemWatchErrorListener = (error: FsError) => void;
+
+export interface FileSystemWatchOptions {
+  readonly onError?: FileSystemWatchErrorListener;
+}
+
+export interface FileSystemWatchSubscription {
+  readonly closed: boolean;
+  /** Resolves after the backend watch is installed and no initial event can be missed. */
+  readonly ready: Promise<void>;
+  /** Idempotent and awaitable so resource release can join provider shutdown. */
+  dispose(): Promise<void>;
+}
+
+/**
+ * Correctness-first filesystem contract. Every logical path has exactly one
+ * kind and one byte payload; conditional writes and lifecycle disposal are
+ * mandatory rather than optional provider extensions.
+ */
+export interface FileSystemProviderV2 {
+  readonly id: string;
+  readonly label: string;
+  readonly capabilities: FileSystemProviderCapabilities;
+
+  /** Absence is represented only by null; permission/I/O/wrong-kind errors throw FsError. */
+  stat(path: WorkspacePath): Promise<FileSystemEntrySnapshot | null>;
+  /** Absence is represented only by null; a directory at path is type-mismatch. */
+  readFile(path: WorkspacePath): Promise<FileSystemFileRead | null>;
+  /** Missing paths and file paths throw; results are canonical and deterministic. */
+  readDirectory(path: WorkspacePath): Promise<readonly FileSystemEntrySnapshot[]>;
+
+  writeFile(
+    path: WorkspacePath,
+    data: ArrayBuffer | Uint8Array,
+    options?: FileSystemWriteOptions,
+  ): Promise<FileSystemFileSnapshot>;
+  createDirectory(
+    path: WorkspacePath,
+    options?: FileSystemCreateDirectoryOptions,
+  ): Promise<FileSystemDirectorySnapshot>;
+  remove(path: WorkspacePath, options?: FileSystemRemoveOptions): Promise<FileSystemRemoveResult>;
+  move(
+    oldPath: WorkspacePath,
+    newPath: WorkspacePath,
+    options?: FileSystemMoveOptions,
+  ): Promise<FileSystemEntrySnapshot>;
+
+  snapshot(): Promise<FileSystemSnapshot>;
+  /**
+   * Always returns a disposable subscription. When `capabilities.watch` is
+   * false, `ready` rejects with `FsError('not-supported')` and `onError`
+   * observes the same failure; callers can therefore use one cleanup path.
+   */
+  watch(
+    listener: FileSystemWatchListener,
+    options?: FileSystemWatchOptions,
+  ): FileSystemWatchSubscription;
+  dispose(): Promise<void>;
+}

package/src/filesystem/workspace-path.ts

@@ -0,0 +1,92 @@
+import { FsError } from './fs-error.js';
+
+declare const workspacePathBrand: unique symbol;
+
+/** Canonical, root-relative, forward-slash path within one workspace. */
+export type WorkspacePath = string & { readonly [workspacePathBrand]: 'WorkspacePath' };
+
+export const WORKSPACE_ROOT = '' as WorkspacePath;
+
+/**
+ * Parse a legacy/user path into its one canonical workspace representation.
+ * Leading/trailing and repeated separators are normalized; traversal and NUL
+ * segments are rejected rather than resolved.
+ */
+export function parseWorkspacePath(input: string): WorkspacePath {
+  if (
+    [...input].some((character) => {
+      const codePoint = character.codePointAt(0) ?? 0;
+      return codePoint <= 0x1f || codePoint === 0x7f;
+    })
+  ) {
+    throw invalidPath(input, 'Workspace paths must not contain NUL or other control characters.');
+  }
+  if (/^[a-zA-Z]:/u.test(input)) {
+    throw new FsError('path-escape', 'Workspace paths must not be OS drive-qualified paths.', {
+      operation: 'parse-path',
+      path: input,
+    });
+  }
+
+  const normalized = input
+    .replace(/\\/g, '/')
+    .replace(/\/+/g, '/')
+    .replace(/^\/|\/$/g, '');
+  if (!normalized) return WORKSPACE_ROOT;
+
+  const segments = normalized.split('/');
+  if (segments.some((segment) => segment === '.' || segment === '..')) {
+    throw new FsError('path-escape', 'Workspace paths must not contain "." or ".." segments.', {
+      operation: 'parse-path',
+      path: input,
+    });
+  }
+  return normalized as WorkspacePath;
+}
+
+export function tryParseWorkspacePath(input: unknown): WorkspacePath | null {
+  if (typeof input !== 'string') return null;
+  try {
+    return parseWorkspacePath(input);
+  } catch {
+    return null;
+  }
+}
+
+/** Convert a canonical path to the slash-prefixed form accepted by v1 providers. */
+export function workspacePathToLegacy(path: WorkspacePath): string {
+  return path ? `/${path}` : '/';
+}
+
+export function workspacePathJoin(parent: WorkspacePath, child: string): WorkspacePath {
+  const childPath = parseWorkspacePath(child);
+  if (!parent) return childPath;
+  if (!childPath) return parent;
+  return parseWorkspacePath(`${parent}/${childPath}`);
+}
+
+export function workspacePathDirname(path: WorkspacePath): WorkspacePath {
+  if (!path) return WORKSPACE_ROOT;
+  const slash = path.lastIndexOf('/');
+  return slash < 0 ? WORKSPACE_ROOT : (path.slice(0, slash) as WorkspacePath);
+}
+
+export function workspacePathBasename(path: WorkspacePath): string {
+  if (!path) return '';
+  const slash = path.lastIndexOf('/');
+  return slash < 0 ? path : path.slice(slash + 1);
+}
+
+export function workspacePathContains(
+  parent: WorkspacePath,
+  candidate: WorkspacePath,
+  inclusive = true,
+): boolean {
+  if (parent === candidate) return inclusive;
+  if (!parent) return candidate !== WORKSPACE_ROOT;
+  return candidate.startsWith(`${parent}/`);
+}
+
+function invalidPath(path: string, message: string): FsError {
+  return new FsError('invalid-path', message, { operation: 'parse-path', path });
+}

package/src/host/filesystem-v2.ts

@@ -0,0 +1,104 @@
+import type {
+  FileSystemCreateDirectoryOptions,
+  FileSystemDirectorySnapshot,
+  FileSystemEntrySnapshot,
+  FileSystemFileRead,
+  FileSystemFileSnapshot,
+  FileSystemMoveOptions,
+  FileSystemProviderCapabilities,
+  FileSystemRemoveOptions,
+  FileSystemRemoveResult,
+  FileSystemSnapshot,
+  FileSystemWatchEvent,
+  FileSystemWriteOptions,
+  SerializedFsError,
+  WorkspacePath,
+} from '../filesystem/index.js';
+
+/** Stable capabilities shared by the Electron v2 client and native backend. */
+export const ELECTRON_FILE_SYSTEM_V2_CAPABILITIES: FileSystemProviderCapabilities = Object.freeze({
+  writeAtomicity: 'process',
+  moveAtomicity: 'process',
+  snapshotAtomicity: 'process',
+  conditionalWrite: 'process',
+  recursiveRemove: true,
+  watch: true,
+  caseSensitivity: 'platform',
+  symlinkPolicy: 'follow-contained',
+  durability: 'best-effort',
+});
+
+/** Explicit result envelope; Electron does not preserve custom Error fields. */
+export type HostFileSystemV2Result<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: SerializedFsError };
+
+export interface HostFileSystemV2OpenRequest {
+  readonly instanceId: string;
+  /** Main-owned persisted workspace authority, never an absolute path. */
+  readonly providerId: string;
+  readonly label: string;
+}
+
+export type HostFileSystemV2WatchMessage =
+  | {
+      readonly instanceId: string;
+      readonly subscriptionId: string;
+      readonly kind: 'event';
+      readonly event: FileSystemWatchEvent;
+    }
+  | {
+      readonly instanceId: string;
+      readonly subscriptionId: string;
+      readonly kind: 'error';
+      readonly error: SerializedFsError;
+    };
+
+/** Wire-level filesystem v2 API exposed by preload. */
+export interface DocBlocksHostFsV2API {
+  open(
+    request: HostFileSystemV2OpenRequest,
+  ): Promise<HostFileSystemV2Result<FileSystemProviderCapabilities>>;
+  stat(
+    instanceId: string,
+    path: WorkspacePath,
+  ): Promise<HostFileSystemV2Result<FileSystemEntrySnapshot | null>>;
+  readFile(
+    instanceId: string,
+    path: WorkspacePath,
+  ): Promise<HostFileSystemV2Result<FileSystemFileRead | null>>;
+  readDirectory(
+    instanceId: string,
+    path: WorkspacePath,
+  ): Promise<HostFileSystemV2Result<readonly FileSystemEntrySnapshot[]>>;
+  writeFile(
+    instanceId: string,
+    path: WorkspacePath,
+    data: ArrayBuffer | Uint8Array,
+    options?: FileSystemWriteOptions,
+  ): Promise<HostFileSystemV2Result<FileSystemFileSnapshot>>;
+  createDirectory(
+    instanceId: string,
+    path: WorkspacePath,
+    options?: FileSystemCreateDirectoryOptions,
+  ): Promise<HostFileSystemV2Result<FileSystemDirectorySnapshot>>;
+  remove(
+    instanceId: string,
+    path: WorkspacePath,
+    options?: FileSystemRemoveOptions,
+  ): Promise<HostFileSystemV2Result<FileSystemRemoveResult>>;
+  move(
+    instanceId: string,
+    oldPath: WorkspacePath,
+    newPath: WorkspacePath,
+    options?: FileSystemMoveOptions,
+  ): Promise<HostFileSystemV2Result<FileSystemEntrySnapshot>>;
+  snapshot(instanceId: string): Promise<HostFileSystemV2Result<FileSystemSnapshot>>;
+  watchSubscribe(instanceId: string, subscriptionId: string): Promise<HostFileSystemV2Result<null>>;
+  watchUnsubscribe(
+    instanceId: string,
+    subscriptionId: string,
+  ): Promise<HostFileSystemV2Result<null>>;
+  dispose(instanceId: string): Promise<HostFileSystemV2Result<null>>;
+  onWatchMessage(listener: (message: HostFileSystemV2WatchMessage) => void): () => void;
+}

package/src/host/git.ts

@@ -0,0 +1,246 @@
+/**
+ * Git host API — wire types for the desktop shell's git integration.
+ *
+ * The desktop app spawns the user's system git from the main process, so
+ * credentials (helpers, SSH agent, signing config and raw remote URLs) remain
+ * in the main process. Everything here is generic git; the only host-specific
+ * conveniences are remote-URL parsing (`GitRemoteInfo.web`) and PR creation
+ * via the GitHub CLI when installed.
+ *
+ * Expected git failures cross IPC as data (`GitResult`), never as thrown
+ * errors — `ipcMain.handle` rejections lose structure. Throwing is reserved
+ * for contract violations (unregistered root, path escape).
+ */
+
+import type { ElectronWorkspaceInfo } from './types.js';
+
+/** Every git operation resolves this — expected failures are data, not throws. */
+export type GitResult<T> = { ok: true; value: T } | { ok: false; error: GitError };
+
+export interface GitError {
+  code: GitErrorCode;
+  /** One-line human summary (classified stderr or synthesized). */
+  message: string;
+  /** Truncated raw stderr for a details disclosure in the UI. */
+  stderr?: string;
+  exitCode?: number;
+}
+
+export type GitErrorCode =
+  | 'git-not-available'
+  | 'not-a-repository'
+  | 'auth-failed'
+  | 'remote-not-found'
+  | 'no-upstream'
+  | 'network'
+  | 'non-fast-forward'
+  | 'merge-conflict'
+  | 'uncommitted-changes'
+  | 'detached-head'
+  | 'unborn-branch'
+  | 'identity-not-configured'
+  | 'branch-exists'
+  | 'invalid-ref-name'
+  | 'nothing-to-commit'
+  | 'invalid-url'
+  | 'destination-exists'
+  | 'pr-exists'
+  | 'gh-not-available'
+  | 'timeout'
+  | 'cancelled'
+  | 'permission-denied'
+  | 'unknown';
+
+export interface GitCapabilities {
+  /** False in store-sandboxed builds, when git is absent, or git < 2.23. */
+  gitAvailable: boolean;
+  gitVersion: string | null;
+  ghAvailable: boolean;
+  ghVersion: string | null;
+}
+
+export interface GitRepoDetection {
+  isRepo: boolean;
+  /** False when the workspace root is a subdirectory of a larger repo. */
+  rootIsToplevel?: boolean;
+  /** Main-owned repository authority; absent when expanded access was declined. */
+  repositoryId?: string;
+  /** True when Git metadata or the work tree extends beyond the workspace grant. */
+  requiresExpandedGrant?: boolean;
+}
+
+export type GitFileStatusCode =
+  | 'added'
+  | 'modified'
+  | 'deleted'
+  | 'renamed'
+  | 'copied'
+  | 'type-changed'
+  | 'untracked'
+  | 'ignored'
+  | 'unmerged';
+
+export interface GitFileChange {
+  /** Slash-prefixed path relative to the WORKSPACE root (fs API convention). */
+  path: string;
+  /** Previous path for renames/copies (workspace-relative, slash-prefixed). */
+  origPath?: string;
+  /** Index-vs-HEAD state (staged), if any. */
+  index?: GitFileStatusCode;
+  /** Worktree-vs-index state (unstaged), if any. */
+  worktree?: GitFileStatusCode;
+  conflicted: boolean;
+}
+
+export interface GitStatus {
+  /** Branch name; null when detached or unborn with no branch. */
+  branch: string | null;
+  detached: boolean;
+  /** HEAD points at a branch with no commits yet. */
+  unborn: boolean;
+  /** Full HEAD SHA; null when unborn. */
+  head: string | null;
+  /** Upstream ref short name, e.g. "origin/main". */
+  upstream: string | null;
+  ahead: number;
+  behind: number;
+  changes: GitFileChange[];
+  /** True when `changes` was capped. */
+  truncated: boolean;
+  operation: 'merge' | 'rebase' | 'cherry-pick' | 'revert' | 'bisect' | null;
+}
+
+export interface GitBranchInfo {
+  /** "main" for local branches, "origin/main" for remote entries. */
+  name: string;
+  kind: 'local' | 'remote';
+  current: boolean;
+  upstream: string | null;
+  ahead: number;
+  behind: number;
+  upstreamGone: boolean;
+  headSha: string;
+  headSubject: string;
+  /** ISO 8601. */
+  headDate: string;
+}
+
+export interface GitLogOptions {
+  /** Workspace-relative file path — per-file history (follows renames). */
+  path?: string;
+  /** Default 100; the host caps at 1000. */
+  maxCount?: number;
+  skip?: number;
+}
+
+export interface GitLogEntry {
+  sha: string;
+  parents: string[];
+  authorName: string;
+  authorEmail: string;
+  /** ISO 8601. */
+  authorDate: string;
+  subject: string;
+  /** Ref decorations ("HEAD -> main", "origin/main", "tag: v1"). */
+  refs: string[];
+}
+
+/** Typed revision selector — the renderer never passes raw rev strings. */
+export type GitRevision =
+  | { kind: 'head' }
+  | { kind: 'index' }
+  | { kind: 'commit'; sha: string }
+  | { kind: 'parent-of'; sha: string };
+
+export interface GitFileAtRevision {
+  /** Null when the file is absent at that revision, or binary/too large. */
+  content: string | null;
+  binary: boolean;
+}
+
+export interface GitRemoteInfo {
+  name: string;
+  /** Sanitized web location. Raw fetch/push URLs never cross IPC. */
+  web: { host: string; owner: string; repo: string; webUrl: string } | null;
+}
+
+export interface GitCloneProgress {
+  /** e.g. "Receiving objects", "Resolving deltas", "Checking out files". */
+  phase: string;
+  percent: number | null;
+  /** Raw progress line for display. */
+  detail?: string;
+}
+
+export interface GitCloneHandle {
+  /**
+   * Resolves `ok(null)` if the user cancels the destination picker; on
+   * success resolves the registered workspace ready to open.
+   */
+  result: Promise<GitResult<ElectronWorkspaceInfo | null>>;
+  /** Kill git and remove the partial clone directory. */
+  cancel: () => void;
+}
+
+export interface DocBlocksHostGitAPI {
+  capabilities(): Promise<GitCapabilities>;
+  /** Detect a persisted workspace by opaque workspace id and mint repository authority. */
+  detectRepo(workspaceId: string): Promise<GitResult<GitRepoDetection>>;
+  init(workspaceId: string): Promise<GitResult<void>>;
+
+  status(repositoryId: string): Promise<GitResult<GitStatus>>;
+  stage(repositoryId: string, paths: string[]): Promise<GitResult<void>>;
+  unstage(repositoryId: string, paths: string[]): Promise<GitResult<void>>;
+  /** Revert tracked files to HEAD; delete untracked ones. Destructive — the renderer confirms. */
+  discard(repositoryId: string, paths: string[]): Promise<GitResult<void>>;
+  /**
+   * With `paths`: stages exactly those files (`add -A -- <paths>`) and commits
+   * them, leaving other staged entries staged. Without: commits the index as-is.
+   */
+  commit(
+    repositoryId: string,
+    message: string,
+    paths?: string[],
+  ): Promise<GitResult<{ sha: string }>>;
+
+  push(repositoryId: string, opts?: { setUpstream?: boolean }): Promise<GitResult<void>>;
+  pull(repositoryId: string): Promise<GitResult<void>>;
+  fetch(repositoryId: string): Promise<GitResult<void>>;
+
+  listBranches(repositoryId: string): Promise<GitResult<GitBranchInfo[]>>;
+  createBranch(
+    repositoryId: string,
+    name: string,
+    opts?: { checkout?: boolean },
+  ): Promise<GitResult<void>>;
+  checkoutBranch(repositoryId: string, name: string): Promise<GitResult<void>>;
+
+  log(repositoryId: string, opts?: GitLogOptions): Promise<GitResult<GitLogEntry[]>>;
+  /** Files changed in one commit plus the full message body. */
+  commitFiles(
+    repositoryId: string,
+    sha: string,
+  ): Promise<GitResult<{ body: string; files: GitFileChange[] }>>;
+  readFileAtRevision(
+    repositoryId: string,
+    path: string,
+    revision: GitRevision,
+  ): Promise<GitResult<GitFileAtRevision>>;
+
+  listRemotes(repositoryId: string): Promise<GitResult<GitRemoteInfo[]>>;
+
+  /**
+   * Clone a remote repository. The main process shows a native picker for the
+   * destination parent directory, then registers the clone as a workspace.
+   */
+  clone(url: string, onProgress?: (p: GitCloneProgress) => void): GitCloneHandle;
+
+  /** `gh pr create --web` (falls back to `gh pr view --web` if one exists). */
+  createPullRequest(repositoryId: string): Promise<GitResult<void>>;
+
+  /**
+   * Throttled status stream for a workspace root. Emits once immediately on
+   * subscribe. Returns an unsubscribe function.
+   */
+  onStatusChanged(repositoryId: string, listener: (status: GitStatus) => void): () => void;
+}