@cloudflare/workspace 0.0.0-alpha.0

package/README.md

@@ -0,0 +1,98 @@
+# `@cloudflare/workspace`
+
+> [!IMPORTANT]
+> **PREVIEW ONLY** This package is provided as a preview for feedback only.
+> APIs are unstable and the design is subject to change.
+>
+> Suitable for experiments, exploration and prototypes. It is NOT suitable
+> for production use at this time.
+>
+> The specification under [`docs/`](docs/) is forward-looking — read it for
+> intent, not as description of the code today.
+
+Durable Object-side facade for a Cloudflare Workspace. Pairs a local
+SQLite-backed VFS (via `@cloudflare/dofs`) with a sync connection to
+a `wsd` instance through a pluggable backend.
+
+The public surface lives on three classes:
+
+- `Workspace` — the host-side facade. Owns the local store, the
+  backend handle, and the push/pull bracket.
+- `WorkspaceStub` — what `workspace.stub()` returns, designed to
+  cross the Workers-RPC boundary into another Worker or DO.
+- `WorkspaceShell` / `ExecHandle` — the command-execution half of
+  the API.
+
+Typical DO-side usage:
+
+```ts
+import { Workspace, CloudflareContainerBackend } from "@cloudflare/workspace";
+import { DurableObject } from "cloudflare:workers";
+
+export class WsdContainer extends DurableObject<Env> {
+  #workspace = new Workspace({
+    storage: this.ctx.storage,
+    backends: [
+      new CloudflareContainerBackend({
+        container: () => this.ctx.container!,
+        egress: this.ctx.exports.WsdEgress({ props: { id: this.ctx.id.toString() } }),
+      }),
+    ],
+  });
+
+  async getWorkspace(): Promise<WorkspaceStub> {
+    await this.#workspace.ready();
+    return this.#workspace.stub();
+  }
+}
+```
+
+Worker-side consumption:
+
+```ts
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const id = env.WSD.idFromName("user-123");
+    using ws = await env.WSD.get(id).getWorkspace();
+
+    await ws.fs.writeFile("/notes.md", "hello");
+    using handle = await ws.shell.exec("ls /workspace");
+    const { exitCode, stdout } = await handle.result();
+
+    return new Response(stdout, { status: exitCode === 0 ? 200 : 500 });
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+## Stub disposal
+
+capnweb does not garbage-collect remote stubs. On the long-lived
+sessions this package depends on (Worker ↔ DO over Workers RPC,
+DO ↔ wsd over capnweb), undisposed stubs accumulate on the peer
+side until the session ends.
+
+The minimum a caller needs to know:
+
+- `using` the value returned from `env.WSD.get(id).getWorkspace()`.
+- `using` the handle returned from `ws.shell.exec(...)`.
+- Don't worry about `ws.fs` / `ws.shell` — those are property
+  accessors that ride with the parent.
+- Pure-value returns (`readFile` as a string, `stat`, `readdir`,
+  etc.) carry no stubs; nothing to dispose.
+
+Short-lived single-shot Workers (one `getWorkspace()`, a few calls,
+return a response) tear the session down with the request, so the
+discipline matters most on long-lived isolates that keep grabbing
+fresh `WorkspaceStub`s or on busy `exec` workloads inside a single
+request.
+
+The full contract — including the boundary between the driver code
+and direct streaming callers, and how it interacts with hibernation
+and reconnect — is in [`docs/11_lifecycle.md`](../../docs/11_lifecycle.md#stub-disposal-contract).
+
+Leak discovery: set `CAPNWEB_TRACK_STUBS=1` and read the snapshot
+via `stubSnapshot()` from `@cloudflare/workspace-rpc/debug`, or
+hit `GET /__wsd/stubs` on a wsd instance. The soak scripts at
+[`script/wsd-stub-soak.mjs`](../../script/wsd-stub-soak.mjs) and
+[`tests/stub-soak.test.ts`](./tests/stub-soak.test.ts) exercise both
+boundaries.

package/dist/git.d.ts

@@ -0,0 +1,119 @@
+import { i as SQLiteWorkspaceProvider } from "./shared-RIdME5uo.js";
+
+//#region src/git/adapter.d.ts
+/**
+ * The shape isomorphic-git wants as its `fs` argument: an object
+ * whose `.promises` is an own, enumerable property and implements
+ * the `node:fs/promises` subset listed in `PromiseFsClient`.
+ *
+ * `promises` is typed as `object` rather than enumerating every
+ * method @platformatic/vfs forwards. The full surface is wider
+ * than this package consumes and pinning it here would either
+ * leak @platformatic/vfs into our public types or force tedious
+ * structural shadowing. Callers that want a typed file API can
+ * cast `client.promises` to `import('@platformatic/vfs').VirtualFileSystem['promises']`.
+ */
+interface IsomorphicGitFSClient {
+  promises: object;
+}
+//#endregion
+//#region src/git/clone.d.ts
+type ProgressCallback = (e: {
+  phase: string;
+  loaded: number;
+  total?: number;
+}) => void;
+type MessageCallback = (msg: string) => void;
+interface GitCloneOptions {
+  /** Repository URL. HTTPS only — isomorphic-git has no SSH transport. */
+  url: string;
+  /** Working-tree directory inside the VFS. Defaults to `/`. */
+  dir?: string;
+  /** Branch, tag, or commit. Defaults to the remote's default branch. */
+  ref?: string;
+  /**
+   * If set, only these paths are written into the working tree.
+   * `.git/` is fully populated regardless (subject to `depth`).
+   * Globs are not supported; pass directory or file paths.
+   */
+  paths?: string[];
+  /**
+   * Shallow-clone depth. Defaults to 1. Pass `0` or `Infinity` for
+   * full history. Even with depth=1, every blob reachable from the
+   * tip tree is fetched — see the package README for why.
+   */
+  depth?: number;
+  /** Fetch only the requested ref's branch. Default: true. */
+  singleBranch?: boolean;
+  /** Skip tags. Default: true. */
+  noTags?: boolean;
+  /** Extra HTTP headers, e.g. `Authorization` for a private repo. */
+  headers?: Record<string, string>;
+  /** CORS proxy URL. Usually unneeded inside a Worker. */
+  corsProxy?: string;
+  /** Progress callback. Forwarded to isomorphic-git. */
+  onProgress?: ProgressCallback;
+  /** Sideband message callback. Forwarded to isomorphic-git. */
+  onMessage?: MessageCallback;
+}
+//#endregion
+//#region src/git/diff.d.ts
+/**
+ * Status-matrix row as emitted by isomorphic-git's `statusMatrix`:
+ * `[filepath, headStatus, workdirStatus, stageStatus]`.
+ *   - 0 = absent
+ *   - 1 = same as HEAD
+ *   - 2 = differs from HEAD
+ *   - 3 = differs from HEAD and stage (rarely meaningful here)
+ */
+type StatusRow = [string, number, number, number];
+interface GitDiffOptions {
+  /** Working-tree directory inside the VFS. Defaults to `/`. */
+  dir?: string;
+  /** Ref to diff against. Defaults to `HEAD`. */
+  ref?: string;
+}
+//#endregion
+//#region src/git/index.d.ts
+/** Duck-typed workspace handle. Only `.provider()` is required. */
+interface WorkspaceLike {
+  provider(): SQLiteWorkspaceProvider;
+}
+/** Methods returned by `createGitClient`. */
+interface GitClient {
+  /** Shallow-clone a remote into the bound workspace. */
+  clone(options: GitCloneOptions): Promise<void>;
+  /** Unified diff between a ref (default HEAD) and the working tree. */
+  diff(options?: GitDiffOptions): Promise<string>;
+}
+interface CreateGitClientOptions {
+  /** Workspace whose provider backs the git operations. */
+  ws: WorkspaceLike;
+  /**
+   * Test seam for substituting the @platformatic/vfs adapter.
+   * Production callers do not pass this.
+   */
+  adapter?: (provider: SQLiteWorkspaceProvider) => Promise<IsomorphicGitFSClient>;
+}
+/**
+ * Build a git client bound to a workspace.
+ *
+ * The FsClient is constructed lazily on first use and reused
+ * across subsequent calls — `@platformatic/vfs.create()` is cheap
+ * but not free, and the workspace provider is stable for the
+ * lifetime of the client.
+ *
+ * An isomorphic-git pack/index cache is also created per client
+ * and threaded into every isogit call. Without this, each
+ * `readBlob` / `statusMatrix` / `walk` re-parses the packfile
+ * from the SQLite-backed VFS — fine for tiny repos, catastrophic
+ * for anything with a real history (the difference between a
+ * sub-second `diff` and one that hangs for minutes).
+ */
+declare function createGitClient({
+  ws,
+  adapter
+}: CreateGitClientOptions): GitClient;
+//#endregion
+export { CreateGitClientOptions, GitClient, type GitCloneOptions, type GitDiffOptions, type MessageCallback, type ProgressCallback, type StatusRow, WorkspaceLike, createGitClient };
+//# sourceMappingURL=git.d.ts.map

package/dist/git.js

@@ -0,0 +1,271 @@
+//#region src/git/adapter.ts
+/**
+* Methods on `SQLiteWorkspaceProvider` forwarded through the
+* wrapping `VirtualProvider`. Listed explicitly (rather than walked
+* off the prototype) so the surface is stable across dofs releases:
+* a new method on the provider does not silently widen the wrapper.
+*/
+const FORWARDED_METHODS = [
+	"open",
+	"openSync",
+	"stat",
+	"statSync",
+	"lstat",
+	"lstatSync",
+	"readdir",
+	"readdirSync",
+	"mkdir",
+	"mkdirSync",
+	"rmdir",
+	"rmdirSync",
+	"unlink",
+	"unlinkSync",
+	"rename",
+	"renameSync",
+	"readFile",
+	"readFileSync",
+	"writeFile",
+	"writeFileSync",
+	"appendFile",
+	"appendFileSync",
+	"exists",
+	"existsSync",
+	"copyFile",
+	"copyFileSync",
+	"internalModuleStat",
+	"realpath",
+	"realpathSync",
+	"access",
+	"accessSync",
+	"readlink",
+	"readlinkSync",
+	"symlink",
+	"symlinkSync",
+	"watch",
+	"watchAsync",
+	"watchFile",
+	"unwatchFile",
+	"closeSync",
+	"readSync",
+	"writeSync",
+	"fstatSync",
+	"truncateSync",
+	"ftruncateSync"
+];
+/**
+* Build an isomorphic-git-compatible FsClient from a
+* SQLiteWorkspaceProvider.
+*
+* Lazily imports `@platformatic/vfs`. If the peer dep is missing,
+* the thrown error names the package so the failure mode stays
+* one stack frame away from obvious.
+*/
+async function workspaceIsomorphicGitClient(provider) {
+	let create;
+	let VirtualProvider;
+	try {
+		({create, VirtualProvider} = await import("@platformatic/vfs"));
+	} catch (cause) {
+		throw new Error("@cloudflare/workspace/git requires @platformatic/vfs as an optional peer dependency. Install it, or pass `fs` to clone() explicitly.", { cause });
+	}
+	class SQLiteVirtualProvider extends VirtualProvider {
+		#inner;
+		constructor(inner) {
+			super();
+			this.#inner = inner;
+		}
+		get readonly() {
+			return this.#inner.readonly;
+		}
+		get supportsSymlinks() {
+			return this.#inner.supportsSymlinks;
+		}
+		get supportsWatch() {
+			return this.#inner.supportsWatch;
+		}
+		/** Used by the forwarding loop below. */
+		get inner() {
+			return this.#inner;
+		}
+	}
+	for (const name of FORWARDED_METHODS) Object.defineProperty(SQLiteVirtualProvider.prototype, name, {
+		value(...args) {
+			const inner = this.inner;
+			const fn = inner[name];
+			if (typeof fn !== "function") throw new Error(`SQLiteWorkspaceProvider.${String(name)} is not a function`);
+			return fn.apply(inner, args);
+		},
+		writable: true,
+		configurable: true
+	});
+	return { promises: create(new SQLiteVirtualProvider(provider), { moduleHooks: false }).promises };
+}
+//#endregion
+//#region src/git/clone.ts
+async function cloneWith(opts) {
+	const dir = opts.dir ?? "/";
+	const ref = opts.ref;
+	const depthRaw = opts.depth ?? 1;
+	const depth = depthRaw > 0 && Number.isFinite(depthRaw) ? depthRaw : void 0;
+	await opts.git.clone({
+		fs: opts.fs,
+		http: opts.http,
+		dir,
+		url: opts.url,
+		ref,
+		corsProxy: opts.corsProxy,
+		headers: opts.headers,
+		depth,
+		singleBranch: opts.singleBranch ?? true,
+		noTags: opts.noTags ?? true,
+		noCheckout: true,
+		cache: opts.cache,
+		onProgress: opts.onProgress,
+		onMessage: opts.onMessage
+	});
+	await opts.git.checkout({
+		fs: opts.fs,
+		dir,
+		ref: ref ?? "HEAD",
+		filepaths: opts.paths,
+		force: true,
+		cache: opts.cache
+	});
+}
+//#endregion
+//#region src/git/diff.ts
+async function diffWith(opts) {
+	const dir = opts.dir ?? "/";
+	const ref = opts.ref ?? "HEAD";
+	let head;
+	try {
+		head = await opts.git.resolveRef({
+			fs: opts.fs,
+			dir,
+			ref
+		});
+	} catch {
+		return "";
+	}
+	const status = await opts.git.statusMatrix({
+		fs: opts.fs,
+		dir,
+		ref,
+		cache: opts.cache
+	});
+	const chunks = [];
+	for (const [filepath, headStatus, workdirStatus] of status) {
+		if (workdirStatus === 1) continue;
+		const headText = headStatus === 1 ? await readBlobAsText(opts.git, opts.fs, dir, head, filepath, opts.cache) : "";
+		const workdirText = workdirStatus === 2 ? await readWorkdirAsText(opts.readFile, dir, filepath) : "";
+		const patch = opts.createPatch(filepath, headText, workdirText, "", "");
+		if (patch.trim().length > 0) chunks.push(patch);
+	}
+	return chunks.join("\n");
+}
+async function readBlobAsText(git, fs, dir, oid, filepath, cache) {
+	try {
+		const { blob } = await git.readBlob({
+			fs,
+			dir,
+			oid,
+			filepath,
+			cache
+		});
+		return new TextDecoder("utf-8", {
+			fatal: false,
+			ignoreBOM: false
+		}).decode(blob);
+	} catch {
+		return "";
+	}
+}
+async function readWorkdirAsText(readFile, dir, filepath) {
+	try {
+		const data = await readFile(`${dir}/${filepath}`);
+		if (typeof data === "string") return data;
+		return new TextDecoder("utf-8", {
+			fatal: false,
+			ignoreBOM: false
+		}).decode(data);
+	} catch {
+		return "";
+	}
+}
+//#endregion
+//#region src/git/index.ts
+/**
+* Build a git client bound to a workspace.
+*
+* The FsClient is constructed lazily on first use and reused
+* across subsequent calls — `@platformatic/vfs.create()` is cheap
+* but not free, and the workspace provider is stable for the
+* lifetime of the client.
+*
+* An isomorphic-git pack/index cache is also created per client
+* and threaded into every isogit call. Without this, each
+* `readBlob` / `statusMatrix` / `walk` re-parses the packfile
+* from the SQLite-backed VFS — fine for tiny repos, catastrophic
+* for anything with a real history (the difference between a
+* sub-second `diff` and one that hangs for minutes).
+*/
+function createGitClient({ ws, adapter = workspaceIsomorphicGitClient }) {
+	let fsPromise;
+	const fs = () => {
+		if (!fsPromise) fsPromise = adapter(ws.provider());
+		return fsPromise;
+	};
+	const cache = {};
+	return {
+		async clone(options) {
+			await cloneWith({
+				...options,
+				fs: await fs(),
+				git: await loadIsomorphicGit(),
+				http: await loadDefaultHTTP(),
+				cache
+			});
+		},
+		async diff(options = {}) {
+			const f = await fs();
+			return diffWith({
+				...options,
+				fs: f,
+				git: await loadIsomorphicGit(),
+				createPatch: await loadCreatePatch(),
+				readFile: readFileFrom(f),
+				cache
+			});
+		}
+	};
+}
+async function loadIsomorphicGit() {
+	try {
+		const mod = await import("isomorphic-git");
+		return mod.default ?? mod;
+	} catch (cause) {
+		throw new Error("@cloudflare/workspace/git requires isomorphic-git as an optional peer dependency. Install isomorphic-git.", { cause });
+	}
+}
+async function loadDefaultHTTP() {
+	try {
+		return (await import("isomorphic-git/http/web")).default;
+	} catch (cause) {
+		throw new Error("Failed to load isomorphic-git/http/web. Install isomorphic-git.", { cause });
+	}
+}
+async function loadCreatePatch() {
+	try {
+		return (await import("./shared-Dj4r_9xb.js")).createPatch;
+	} catch (cause) {
+		throw new Error("@cloudflare/workspace/git requires `diff` as an optional peer dependency. Install `diff`.", { cause });
+	}
+}
+function readFileFrom(fs) {
+	const promises = fs.promises;
+	return (path) => promises.readFile(path);
+}
+//#endregion
+export { createGitClient };
+
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","names":["#inner"],"sources":["../src/git/adapter.ts","../src/git/clone.ts","../src/git/diff.ts","../src/git/index.ts"],"sourcesContent":["// Bridge from `@cloudflare/dofs`'s SQLiteWorkspaceProvider to an\n// FsClient that isomorphic-git can consume directly.\n//\n// Mirrors the recipe in `examples/think/src/tools/git/vfs.ts`\n// (which mirrors the trick wsd uses for its FUSE mount):\n//\n//   1. SQLiteWorkspaceProvider already implements the full node:fs\n//      surface @platformatic/vfs's VirtualFileSystem needs,\n//      including symlink / readlink.\n//   2. It does not extend @platformatic/vfs.VirtualProvider, and\n//      `create()` checks `provider instanceof VirtualProvider` —\n//      failing silently into an in-memory store on a miss. The\n//      dofs provider therefore has to be wrapped in a\n//      VirtualProvider subclass with an explicit forwarding list.\n//   3. `vfs.promises` is declared as a class getter. isomorphic-git\n//      probes `Object.getOwnPropertyDescriptor(fs, 'promises')`,\n//      does not see an enumerable own property, and falls through\n//      to its callback-style branch — which then crashes.\n//      Re-exposing `promises` as an own property on a plain object\n//      fixes the detection.\n//\n// `@platformatic/vfs` is imported lazily so the base\n// `@cloudflare/workspace` bundle has no static reference to it.\n\nimport type { SQLiteWorkspaceProvider } from \"@cloudflare/dofs\";\n\n/**\n * The shape isomorphic-git wants as its `fs` argument: an object\n * whose `.promises` is an own, enumerable property and implements\n * the `node:fs/promises` subset listed in `PromiseFsClient`.\n *\n * `promises` is typed as `object` rather than enumerating every\n * method @platformatic/vfs forwards. The full surface is wider\n * than this package consumes and pinning it here would either\n * leak @platformatic/vfs into our public types or force tedious\n * structural shadowing. Callers that want a typed file API can\n * cast `client.promises` to `import('@platformatic/vfs').VirtualFileSystem['promises']`.\n */\nexport interface IsomorphicGitFSClient {\n  promises: object;\n}\n\n/**\n * Methods on `SQLiteWorkspaceProvider` forwarded through the\n * wrapping `VirtualProvider`. Listed explicitly (rather than walked\n * off the prototype) so the surface is stable across dofs releases:\n * a new method on the provider does not silently widen the wrapper.\n */\nconst FORWARDED_METHODS = [\n  \"open\",\n  \"openSync\",\n  \"stat\",\n  \"statSync\",\n  \"lstat\",\n  \"lstatSync\",\n  \"readdir\",\n  \"readdirSync\",\n  \"mkdir\",\n  \"mkdirSync\",\n  \"rmdir\",\n  \"rmdirSync\",\n  \"unlink\",\n  \"unlinkSync\",\n  \"rename\",\n  \"renameSync\",\n  \"readFile\",\n  \"readFileSync\",\n  \"writeFile\",\n  \"writeFileSync\",\n  \"appendFile\",\n  \"appendFileSync\",\n  \"exists\",\n  \"existsSync\",\n  \"copyFile\",\n  \"copyFileSync\",\n  \"internalModuleStat\",\n  \"realpath\",\n  \"realpathSync\",\n  \"access\",\n  \"accessSync\",\n  \"readlink\",\n  \"readlinkSync\",\n  \"symlink\",\n  \"symlinkSync\",\n  \"watch\",\n  \"watchAsync\",\n  \"watchFile\",\n  \"unwatchFile\",\n  // fd-style extensions @platformatic/vfs's router uses on\n  // read/write paths going through `open`.\n  \"closeSync\",\n  \"readSync\",\n  \"writeSync\",\n  \"fstatSync\",\n  \"truncateSync\",\n  \"ftruncateSync\",\n] as const;\n\n/**\n * Build an isomorphic-git-compatible FsClient from a\n * SQLiteWorkspaceProvider.\n *\n * Lazily imports `@platformatic/vfs`. If the peer dep is missing,\n * the thrown error names the package so the failure mode stays\n * one stack frame away from obvious.\n */\nexport async function workspaceIsomorphicGitClient(\n  provider: SQLiteWorkspaceProvider,\n): Promise<IsomorphicGitFSClient> {\n  let create: typeof import(\"@platformatic/vfs\").create;\n  let VirtualProvider: typeof import(\"@platformatic/vfs\").VirtualProvider;\n  try {\n    ({ create, VirtualProvider } = await import(\"@platformatic/vfs\"));\n  } catch (cause) {\n    throw new Error(\n      \"@cloudflare/workspace/git requires @platformatic/vfs as an optional peer dependency. \" +\n        \"Install it, or pass `fs` to clone() explicitly.\",\n      { cause },\n    );\n  }\n\n  class SQLiteVirtualProvider extends VirtualProvider {\n    readonly #inner: SQLiteWorkspaceProvider;\n    constructor(inner: SQLiteWorkspaceProvider) {\n      super();\n      this.#inner = inner;\n    }\n    // VirtualProvider's defaults are false. The dofs provider\n    // declares the real values as instance properties; the\n    // forwarding loop below skips accessors, so re-expose them.\n    override get readonly(): boolean {\n      return this.#inner.readonly;\n    }\n    override get supportsSymlinks(): boolean {\n      return this.#inner.supportsSymlinks;\n    }\n    override get supportsWatch(): boolean {\n      return this.#inner.supportsWatch;\n    }\n    /** Used by the forwarding loop below. */\n    get inner(): SQLiteWorkspaceProvider {\n      return this.#inner;\n    }\n  }\n\n  for (const name of FORWARDED_METHODS) {\n    Object.defineProperty(SQLiteVirtualProvider.prototype, name, {\n      value(this: SQLiteVirtualProvider, ...args: unknown[]): unknown {\n        // biome-ignore lint/suspicious/noExplicitAny: dispatch table\n        const inner = this.inner as any;\n        const fn = inner[name];\n        if (typeof fn !== \"function\") {\n          throw new Error(`SQLiteWorkspaceProvider.${String(name)} is not a function`);\n        }\n        return fn.apply(inner, args);\n      },\n      writable: true,\n      configurable: true,\n    });\n  }\n\n  // `moduleHooks: false` keeps @platformatic/vfs from installing\n  // Node module-resolution hooks, which depend on `node:module` and\n  // are pointless inside workerd.\n  const vfs = create(new SQLiteVirtualProvider(provider), { moduleHooks: false });\n  // Re-expose `.promises` as an enumerable own property so\n  // isomorphic-git's FileSystem detection picks the promise branch.\n  return { promises: vfs.promises };\n}\n","// Clone a remote repository into a workspace-backed filesystem.\n//\n// Subset-of-files support comes from isomorphic-git's two-step\n// model: clone with `noCheckout: true` to populate `.git/`, then\n// `checkout({ filepaths })` to materialize a chosen subset of the\n// working tree. The wire protocol still ships every blob reachable\n// from the tip tree — isomorphic-git does not speak the v2\n// `filter` capability — but disk writes are limited to `paths`.\n//\n// `cloneWith` is the testable core: it takes a pre-built\n// IsomorphicGitClient and HTTP transport. The public `clone()` in\n// ./index.ts resolves those from dynamic imports of `isomorphic-git`\n// so the peer dep stays optional and the base bundle pays no cost.\n\n/**\n * The subset of `isomorphic-git`'s API consumed here. Declared\n * structurally to avoid pulling the package's `.d.ts` into this\n * package's public types, and to let tests pass plain spies.\n */\nexport interface IsomorphicGitClient {\n  clone(args: {\n    fs: object;\n    http: object;\n    dir: string;\n    url: string;\n    ref?: string;\n    corsProxy?: string;\n    headers?: Record<string, string>;\n    depth?: number;\n    singleBranch?: boolean;\n    noTags?: boolean;\n    noCheckout?: boolean;\n    cache?: object;\n    onProgress?: ProgressCallback;\n    onMessage?: MessageCallback;\n  }): Promise<void>;\n\n  checkout(args: {\n    fs: object;\n    dir: string;\n    ref: string;\n    filepaths?: string[];\n    force?: boolean;\n    cache?: object;\n  }): Promise<void>;\n}\n\nexport type ProgressCallback = (e: { phase: string; loaded: number; total?: number }) => void;\nexport type MessageCallback = (msg: string) => void;\n\nexport interface GitCloneOptions {\n  /** Repository URL. HTTPS only — isomorphic-git has no SSH transport. */\n  url: string;\n  /** Working-tree directory inside the VFS. Defaults to `/`. */\n  dir?: string;\n  /** Branch, tag, or commit. Defaults to the remote's default branch. */\n  ref?: string;\n  /**\n   * If set, only these paths are written into the working tree.\n   * `.git/` is fully populated regardless (subject to `depth`).\n   * Globs are not supported; pass directory or file paths.\n   */\n  paths?: string[];\n  /**\n   * Shallow-clone depth. Defaults to 1. Pass `0` or `Infinity` for\n   * full history. Even with depth=1, every blob reachable from the\n   * tip tree is fetched — see the package README for why.\n   */\n  depth?: number;\n  /** Fetch only the requested ref's branch. Default: true. */\n  singleBranch?: boolean;\n  /** Skip tags. Default: true. */\n  noTags?: boolean;\n  /** Extra HTTP headers, e.g. `Authorization` for a private repo. */\n  headers?: Record<string, string>;\n  /** CORS proxy URL. Usually unneeded inside a Worker. */\n  corsProxy?: string;\n  /** Progress callback. Forwarded to isomorphic-git. */\n  onProgress?: ProgressCallback;\n  /** Sideband message callback. Forwarded to isomorphic-git. */\n  onMessage?: MessageCallback;\n}\n\n/**\n * Dependency-injected form. Used directly by tests and by the\n * public `clone()` wrapper. Splitting this out keeps the import\n * graph clean: this file has no runtime dependency on\n * `isomorphic-git` or `@platformatic/vfs`.\n */\nexport interface CloneWithDeps extends GitCloneOptions {\n  git: IsomorphicGitClient;\n  http: object;\n  fs: object;\n  /**\n   * isomorphic-git's pack/index cache. Pass the same object to\n   * every isogit call against this repo so the packfile is parsed\n   * once. Without this, each `readBlob` / `walk` / `statusMatrix`\n   * re-parses the pack from the SQLite-backed VFS (~tens of MB),\n   * which is the difference between sub-second diffs and minutes.\n   */\n  cache?: object;\n}\n\nexport async function cloneWith(opts: CloneWithDeps): Promise<void> {\n  const dir = opts.dir ?? \"/\";\n  const ref = opts.ref;\n  const depthRaw = opts.depth ?? 1;\n  // depth=0 and depth=Infinity both mean \"no shallow limit\" on this\n  // surface. isomorphic-git interprets `undefined` that way.\n  const depth = depthRaw > 0 && Number.isFinite(depthRaw) ? depthRaw : undefined;\n\n  await opts.git.clone({\n    fs: opts.fs,\n    http: opts.http,\n    dir,\n    url: opts.url,\n    ref,\n    corsProxy: opts.corsProxy,\n    headers: opts.headers,\n    depth,\n    singleBranch: opts.singleBranch ?? true,\n    noTags: opts.noTags ?? true,\n    noCheckout: true,\n    cache: opts.cache,\n    onProgress: opts.onProgress,\n    onMessage: opts.onMessage,\n  });\n\n  // The working tree is empty after a noCheckout clone, so `force`\n  // is safe — nothing real can conflict — and matches caller intent\n  // (\"populate this workspace from the remote\").\n  await opts.git.checkout({\n    fs: opts.fs,\n    dir,\n    ref: ref ?? \"HEAD\",\n    filepaths: opts.paths,\n    force: true,\n    cache: opts.cache,\n  });\n}\n","// Unified-diff between a git ref (default HEAD) and the working\n// tree, the way `git diff HEAD` would, but in pure JS via\n// isomorphic-git + the `diff` package.\n//\n// `diffWith` is the testable core: takes a pre-built\n// IsomorphicGitDiffClient, an FsClient, a `createPatch` function,\n// and a `readFile` function. The public `diff()` in ./index.ts\n// resolves those from dynamic imports of `isomorphic-git` and\n// `diff` so both stay optional peer deps.\n\nimport type { IsomorphicGitFSClient } from \"./adapter.js\";\n\n/**\n * Status-matrix row as emitted by isomorphic-git's `statusMatrix`:\n * `[filepath, headStatus, workdirStatus, stageStatus]`.\n *   - 0 = absent\n *   - 1 = same as HEAD\n *   - 2 = differs from HEAD\n *   - 3 = differs from HEAD and stage (rarely meaningful here)\n */\nexport type StatusRow = [string, number, number, number];\n\n/** Subset of isomorphic-git's API used to compute a working-tree diff. */\nexport interface IsomorphicGitDiffClient {\n  resolveRef(args: { fs: object; dir: string; ref: string }): Promise<string>;\n  statusMatrix(args: {\n    fs: object;\n    dir: string;\n    ref?: string;\n    cache?: object;\n  }): Promise<StatusRow[]>;\n  readBlob(args: {\n    fs: object;\n    dir: string;\n    oid: string;\n    filepath: string;\n    cache?: object;\n  }): Promise<{ blob: Uint8Array; oid: string }>;\n}\n\n/** Signature compatible with the `diff` package's `createPatch`. */\nexport type CreatePatchFn = (\n  fileName: string,\n  oldStr: string,\n  newStr: string,\n  oldHeader?: string,\n  newHeader?: string,\n) => string;\n\n/** Signature compatible with `fs.promises.readFile` (binary mode). */\nexport type ReadFileFn = (path: string) => Promise<Uint8Array | string>;\n\nexport interface GitDiffOptions {\n  /** Working-tree directory inside the VFS. Defaults to `/`. */\n  dir?: string;\n  /** Ref to diff against. Defaults to `HEAD`. */\n  ref?: string;\n}\n\n/**\n * Dependency-injected form. Used directly by tests and by the\n * public `diff()` wrapper.\n */\nexport interface DiffWithDeps extends GitDiffOptions {\n  git: IsomorphicGitDiffClient;\n  fs: IsomorphicGitFSClient | object;\n  createPatch: CreatePatchFn;\n  readFile: ReadFileFn;\n  /**\n   * isomorphic-git's pack/index cache. Shared with the surrounding\n   * GitClient so the packfile is parsed once across clone, diff,\n   * and any other isogit call. See clone.ts's CloneWithDeps.cache.\n   */\n  cache?: object;\n}\n\nexport async function diffWith(opts: DiffWithDeps): Promise<string> {\n  const dir = opts.dir ?? \"/\";\n  const ref = opts.ref ?? \"HEAD\";\n\n  let head: string;\n  try {\n    head = await opts.git.resolveRef({ fs: opts.fs, dir, ref });\n  } catch {\n    // Ref unresolvable (e.g. workspace never cloned). Empty\n    // string is a more useful signal than an exception for the\n    // common \"diff after maybe-no-op\" call site.\n    return \"\";\n  }\n\n  // Pass `ref` through so the matrix is computed against the\n  // requested commit rather than always HEAD. Without this the\n  // `ref` argument would only affect blob reads, leaving the\n  // status walk silently skewed.\n  const status = await opts.git.statusMatrix({ fs: opts.fs, dir, ref, cache: opts.cache });\n  const chunks: string[] = [];\n  for (const [filepath, headStatus, workdirStatus] of status) {\n    // workdirStatus: 0 absent, 1 == HEAD, 2 differs. Skip\n    // unchanged rows up front to avoid the blob/file reads.\n    if (workdirStatus === 1) continue;\n\n    const headText =\n      headStatus === 1\n        ? await readBlobAsText(opts.git, opts.fs, dir, head, filepath, opts.cache)\n        : \"\";\n    const workdirText =\n      workdirStatus === 2 ? await readWorkdirAsText(opts.readFile, dir, filepath) : \"\";\n    const patch = opts.createPatch(filepath, headText, workdirText, \"\", \"\");\n    if (patch.trim().length > 0) chunks.push(patch);\n  }\n  return chunks.join(\"\\n\");\n}\n\nasync function readBlobAsText(\n  git: IsomorphicGitDiffClient,\n  fs: object,\n  dir: string,\n  oid: string,\n  filepath: string,\n  cache: object | undefined,\n): Promise<string> {\n  try {\n    const { blob } = await git.readBlob({ fs, dir, oid, filepath, cache });\n    // Best-effort UTF-8 decode. A real diff tool would skip\n    // binaries entirely; for the general case here a noisy diff\n    // beats a thrown error.\n    return new TextDecoder(\"utf-8\", { fatal: false, ignoreBOM: false }).decode(blob);\n  } catch {\n    return \"\";\n  }\n}\n\nasync function readWorkdirAsText(\n  readFile: ReadFileFn,\n  dir: string,\n  filepath: string,\n): Promise<string> {\n  try {\n    const data = await readFile(`${dir}/${filepath}`);\n    if (typeof data === \"string\") return data;\n    return new TextDecoder(\"utf-8\", { fatal: false, ignoreBOM: false }).decode(data);\n  } catch {\n    return \"\";\n  }\n}\n","// Public surface of @cloudflare/workspace/git.\n//\n// `createGitClient({ ws })` is the one entry point. It binds a\n// workspace handle once and returns `{ clone, diff }` methods that\n// don't repeat the workspace argument. Internally each method\n// lazy-loads its optional peer deps (`isomorphic-git`, the http\n// transport, and for `diff` the `diff` package) and delegates to\n// `cloneWith` / `diffWith`.\n//\n// `cloneWith` and `diffWith` are still exported for callers that\n// bring their own FsClient — tests, custom adapters, running\n// against node:fs directly — but the workspace-bound path is the\n// only one most consumers need.\n\nimport type { SQLiteWorkspaceProvider } from \"@cloudflare/dofs\";\n\nimport { type IsomorphicGitFSClient, workspaceIsomorphicGitClient } from \"./adapter.js\";\nimport { cloneWith, type GitCloneOptions, type IsomorphicGitClient } from \"./clone.js\";\nimport {\n  type CreatePatchFn,\n  diffWith,\n  type GitDiffOptions,\n  type IsomorphicGitDiffClient,\n  type ReadFileFn,\n} from \"./diff.js\";\n\nexport type { GitCloneOptions, MessageCallback, ProgressCallback } from \"./clone.js\";\nexport type { GitDiffOptions, StatusRow } from \"./diff.js\";\n\n/** Duck-typed workspace handle. Only `.provider()` is required. */\nexport interface WorkspaceLike {\n  provider(): SQLiteWorkspaceProvider;\n}\n\n/** Methods returned by `createGitClient`. */\nexport interface GitClient {\n  /** Shallow-clone a remote into the bound workspace. */\n  clone(options: GitCloneOptions): Promise<void>;\n  /** Unified diff between a ref (default HEAD) and the working tree. */\n  diff(options?: GitDiffOptions): Promise<string>;\n}\n\nexport interface CreateGitClientOptions {\n  /** Workspace whose provider backs the git operations. */\n  ws: WorkspaceLike;\n  /**\n   * Test seam for substituting the @platformatic/vfs adapter.\n   * Production callers do not pass this.\n   */\n  adapter?: (provider: SQLiteWorkspaceProvider) => Promise<IsomorphicGitFSClient>;\n}\n\n/**\n * Build a git client bound to a workspace.\n *\n * The FsClient is constructed lazily on first use and reused\n * across subsequent calls — `@platformatic/vfs.create()` is cheap\n * but not free, and the workspace provider is stable for the\n * lifetime of the client.\n *\n * An isomorphic-git pack/index cache is also created per client\n * and threaded into every isogit call. Without this, each\n * `readBlob` / `statusMatrix` / `walk` re-parses the packfile\n * from the SQLite-backed VFS — fine for tiny repos, catastrophic\n * for anything with a real history (the difference between a\n * sub-second `diff` and one that hangs for minutes).\n */\nexport function createGitClient({\n  ws,\n  adapter = workspaceIsomorphicGitClient,\n}: CreateGitClientOptions): GitClient {\n  let fsPromise: Promise<IsomorphicGitFSClient> | undefined;\n  const fs = () => {\n    if (!fsPromise) fsPromise = adapter(ws.provider());\n    return fsPromise;\n  };\n  const cache: Record<string, unknown> = {};\n\n  return {\n    async clone(options) {\n      await cloneWith({\n        ...options,\n        fs: await fs(),\n        git: await loadIsomorphicGit<IsomorphicGitClient>(),\n        http: await loadDefaultHTTP(),\n        cache,\n      });\n    },\n    async diff(options = {}) {\n      const f = await fs();\n      return diffWith({\n        ...options,\n        fs: f,\n        git: await loadIsomorphicGit<IsomorphicGitDiffClient>(),\n        createPatch: await loadCreatePatch(),\n        readFile: readFileFrom(f),\n        cache,\n      });\n    },\n  };\n}\n\n// isomorphic-git ships both named exports and a default export\n// (CJS interop). Callers pull the subset they need via the generic.\nasync function loadIsomorphicGit<T>(): Promise<T> {\n  try {\n    const mod = await import(\"isomorphic-git\");\n    return (mod.default ?? mod) as unknown as T;\n  } catch (cause) {\n    throw new Error(\n      \"@cloudflare/workspace/git requires isomorphic-git as an optional peer dependency. \" +\n        \"Install isomorphic-git.\",\n      { cause },\n    );\n  }\n}\n\nasync function loadDefaultHTTP(): Promise<object> {\n  try {\n    const mod = await import(\"isomorphic-git/http/web\");\n    return mod.default;\n  } catch (cause) {\n    throw new Error(\"Failed to load isomorphic-git/http/web. Install isomorphic-git.\", { cause });\n  }\n}\n\nasync function loadCreatePatch(): Promise<CreatePatchFn> {\n  try {\n    const mod = await import(\"diff\");\n    return mod.createPatch;\n  } catch (cause) {\n    throw new Error(\n      \"@cloudflare/workspace/git requires `diff` as an optional peer dependency. \" +\n        \"Install `diff`.\",\n      { cause },\n    );\n  }\n}\n\nfunction readFileFrom(fs: IsomorphicGitFSClient): ReadFileFn {\n  // `fs.promises` is typed as `object` on the public surface; the\n  // underlying @platformatic/vfs handle exposes `readFile`. Narrow\n  // locally rather than widening the exported type.\n  const promises = fs.promises as { readFile: ReadFileFn };\n  return (path) => promises.readFile(path);\n}\n"],"mappings":";;;;;;;AAgDA,MAAM,oBAAoB;CACxB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAGA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;;;AAUA,eAAsB,6BACpB,UACgC;CAChC,IAAI;CACJ,IAAI;CACJ,IAAI;EACF,CAAC,CAAE,QAAQ,mBAAoB,MAAM,OAAO;CAC9C,SAAS,OAAO;EACd,MAAM,IAAI,MACR,wIAEA,EAAE,MAAM,CACV;CACF;CAEA,MAAM,8BAA8B,gBAAgB;EAClD;EACA,YAAY,OAAgC;GAC1C,MAAM;GACN,KAAKA,SAAS;EAChB;EAIA,IAAa,WAAoB;GAC/B,OAAO,KAAKA,OAAO;EACrB;EACA,IAAa,mBAA4B;GACvC,OAAO,KAAKA,OAAO;EACrB;EACA,IAAa,gBAAyB;GACpC,OAAO,KAAKA,OAAO;EACrB;;EAEA,IAAI,QAAiC;GACnC,OAAO,KAAKA;EACd;CACF;CAEA,KAAK,MAAM,QAAQ,mBACjB,OAAO,eAAe,sBAAsB,WAAW,MAAM;EAC3D,MAAmC,GAAG,MAA0B;GAE9D,MAAM,QAAQ,KAAK;GACnB,MAAM,KAAK,MAAM;GACjB,IAAI,OAAO,OAAO,YAChB,MAAM,IAAI,MAAM,2BAA2B,OAAO,IAAI,EAAE,mBAAmB;GAE7E,OAAO,GAAG,MAAM,OAAO,IAAI;EAC7B;EACA,UAAU;EACV,cAAc;CAChB,CAAC;CASH,OAAO,EAAE,UAHG,OAAO,IAAI,sBAAsB,QAAQ,GAAG,EAAE,aAAa,MAAM,CAGxD,EAAE,SAAS;AAClC;;;ACjEA,eAAsB,UAAU,MAAoC;CAClE,MAAM,MAAM,KAAK,OAAO;CACxB,MAAM,MAAM,KAAK;CACjB,MAAM,WAAW,KAAK,SAAS;CAG/B,MAAM,QAAQ,WAAW,KAAK,OAAO,SAAS,QAAQ,IAAI,WAAW,KAAA;CAErE,MAAM,KAAK,IAAI,MAAM;EACnB,IAAI,KAAK;EACT,MAAM,KAAK;EACX;EACA,KAAK,KAAK;EACV;EACA,WAAW,KAAK;EAChB,SAAS,KAAK;EACd;EACA,cAAc,KAAK,gBAAgB;EACnC,QAAQ,KAAK,UAAU;EACvB,YAAY;EACZ,OAAO,KAAK;EACZ,YAAY,KAAK;EACjB,WAAW,KAAK;CAClB,CAAC;CAKD,MAAM,KAAK,IAAI,SAAS;EACtB,IAAI,KAAK;EACT;EACA,KAAK,OAAO;EACZ,WAAW,KAAK;EAChB,OAAO;EACP,OAAO,KAAK;CACd,CAAC;AACH;;;AC/DA,eAAsB,SAAS,MAAqC;CAClE,MAAM,MAAM,KAAK,OAAO;CACxB,MAAM,MAAM,KAAK,OAAO;CAExB,IAAI;CACJ,IAAI;EACF,OAAO,MAAM,KAAK,IAAI,WAAW;GAAE,IAAI,KAAK;GAAI;GAAK;EAAI,CAAC;CAC5D,QAAQ;EAIN,OAAO;CACT;CAMA,MAAM,SAAS,MAAM,KAAK,IAAI,aAAa;EAAE,IAAI,KAAK;EAAI;EAAK;EAAK,OAAO,KAAK;CAAM,CAAC;CACvF,MAAM,SAAmB,CAAC;CAC1B,KAAK,MAAM,CAAC,UAAU,YAAY,kBAAkB,QAAQ;EAG1D,IAAI,kBAAkB,GAAG;EAEzB,MAAM,WACJ,eAAe,IACX,MAAM,eAAe,KAAK,KAAK,KAAK,IAAI,KAAK,MAAM,UAAU,KAAK,KAAK,IACvE;EACN,MAAM,cACJ,kBAAkB,IAAI,MAAM,kBAAkB,KAAK,UAAU,KAAK,QAAQ,IAAI;EAChF,MAAM,QAAQ,KAAK,YAAY,UAAU,UAAU,aAAa,IAAI,EAAE;EACtE,IAAI,MAAM,KAAK,EAAE,SAAS,GAAG,OAAO,KAAK,KAAK;CAChD;CACA,OAAO,OAAO,KAAK,IAAI;AACzB;AAEA,eAAe,eACb,KACA,IACA,KACA,KACA,UACA,OACiB;CACjB,IAAI;EACF,MAAM,EAAE,SAAS,MAAM,IAAI,SAAS;GAAE;GAAI;GAAK;GAAK;GAAU;EAAM,CAAC;EAIrE,OAAO,IAAI,YAAY,SAAS;GAAE,OAAO;GAAO,WAAW;EAAM,CAAC,EAAE,OAAO,IAAI;CACjF,QAAQ;EACN,OAAO;CACT;AACF;AAEA,eAAe,kBACb,UACA,KACA,UACiB;CACjB,IAAI;EACF,MAAM,OAAO,MAAM,SAAS,GAAG,IAAI,GAAG,UAAU;EAChD,IAAI,OAAO,SAAS,UAAU,OAAO;EACrC,OAAO,IAAI,YAAY,SAAS;GAAE,OAAO;GAAO,WAAW;EAAM,CAAC,EAAE,OAAO,IAAI;CACjF,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;AC7EA,SAAgB,gBAAgB,EAC9B,IACA,UAAU,gCAC0B;CACpC,IAAI;CACJ,MAAM,WAAW;EACf,IAAI,CAAC,WAAW,YAAY,QAAQ,GAAG,SAAS,CAAC;EACjD,OAAO;CACT;CACA,MAAM,QAAiC,CAAC;CAExC,OAAO;EACL,MAAM,MAAM,SAAS;GACnB,MAAM,UAAU;IACd,GAAG;IACH,IAAI,MAAM,GAAG;IACb,KAAK,MAAM,kBAAuC;IAClD,MAAM,MAAM,gBAAgB;IAC5B;GACF,CAAC;EACH;EACA,MAAM,KAAK,UAAU,CAAC,GAAG;GACvB,MAAM,IAAI,MAAM,GAAG;GACnB,OAAO,SAAS;IACd,GAAG;IACH,IAAI;IACJ,KAAK,MAAM,kBAA2C;IACtD,aAAa,MAAM,gBAAgB;IACnC,UAAU,aAAa,CAAC;IACxB;GACF,CAAC;EACH;CACF;AACF;AAIA,eAAe,oBAAmC;CAChD,IAAI;EACF,MAAM,MAAM,MAAM,OAAO;EACzB,OAAQ,IAAI,WAAW;CACzB,SAAS,OAAO;EACd,MAAM,IAAI,MACR,6GAEA,EAAE,MAAM,CACV;CACF;AACF;AAEA,eAAe,kBAAmC;CAChD,IAAI;EAEF,QAAO,MADW,OAAO,4BACd;CACb,SAAS,OAAO;EACd,MAAM,IAAI,MAAM,mEAAmE,EAAE,MAAM,CAAC;CAC9F;AACF;AAEA,eAAe,kBAA0C;CACvD,IAAI;EAEF,QAAO,MADW,OAAO,yBACd;CACb,SAAS,OAAO;EACd,MAAM,IAAI,MACR,6FAEA,EAAE,MAAM,CACV;CACF;AACF;AAEA,SAAS,aAAa,IAAuC;CAI3D,MAAM,WAAW,GAAG;CACpB,QAAQ,SAAS,SAAS,SAAS,IAAI;AACzC"}