opencode2-cow-worktree 0.1.0

package/src/platform.ts

@@ -0,0 +1,71 @@
+/**
+ * The platform seam: which syscall fulfils a CoW clone.
+ *
+ * On Linux the primitive is a reflink (`COPYFILE_FICLONE_FORCE`). On macOS it
+ * is `copyfile(3)` with `COPYFILE_CLONE_FORCE`, because libuv never reached
+ * `clonefile(2)` on Darwin even on APFS — under Node the reflink call fails
+ * with `ENOSYS` unconditionally. `cloneFile` and `isDarwin` are the only
+ * platform-specific things the rest of the code touches.
+ */
+
+/**
+ * The CoW clone operation for one regular file: shares the target's extents
+ * with `source`, or throws. Never falls back to a byte copy.
+ */
+export type CloneFile = (source: string, target: string) => Promise<void>;
+
+/**
+ * True on Darwin. Injectable into `cloneFile` so the platform dispatch is
+ * exercised from a Linux test.
+ */
+export type PlatformCheck = () => boolean;
+
+/** True when the current process is running on macOS. */
+export function isDarwin(): boolean {
+  return process.platform === "darwin";
+}
+
+const defaultIsDarwin: PlatformCheck = isDarwin;
+
+/**
+ * Clones one regular file using this platform's syscall, or throws.
+ *
+ * Dispatch is by `platform` so the Darwin branch is reachable from tests on
+ * Linux. On Linux this is exactly the previous behavior:
+ * `COPYFILE_FICLONE_FORCE` on the same paths.
+ */
+export async function cloneFile(
+  source: string,
+  target: string,
+  platform: PlatformCheck = defaultIsDarwin,
+): Promise<void> {
+  if (platform()) return cloneOnDarwin(source, target);
+  return cloneOnLinux(source, target);
+}
+
+/**
+ * The Linux primitive: a forced, create-only reflink, which fails rather than
+ * byte-copying and refuses an existing destination instead of overwriting it.
+ * `COPYFILE_EXCL` is Darwin parity — `COPYFILE_CLONE_FORCE` implies it there
+ * (see `platform-darwin.ts`) — and correct on its own: the clone walker only
+ * ever writes fresh names, so an occupied destination is a bug to surface,
+ * not bytes to replace.
+ */
+export async function cloneOnLinux(source: string, target: string): Promise<void> {
+  const { constants } = await import("node:fs");
+  const { copyFile } = await import("node:fs/promises");
+  await copyFile(
+    source,
+    target,
+    constants.COPYFILE_FICLONE_FORCE | constants.COPYFILE_EXCL,
+  );
+}
+
+/**
+ * The Darwin backend, loaded only when selected. The dynamic import keeps the
+ * macOS module — and its `bun:ffi` `dlopen` — out of the Linux process.
+ */
+async function cloneOnDarwin(source: string, target: string): Promise<void> {
+  const { cloneFileOnDarwin } = await import("./platform-darwin");
+  await cloneFileOnDarwin(source, target);
+}

package/src/plugin.ts

@@ -0,0 +1,249 @@
+import type { Context } from "@opencode-ai/plugin";
+import { stat } from "node:fs/promises";
+import { probeCowCapability } from "./capability";
+import { fallbackPolicy, postCreateHooks, targetRoot } from "./config";
+import { deviceOf, isDirectory } from "./device";
+import { listCowWorktrees, spawnWorkspace } from "./tool";
+import type {
+  FallbackPolicy,
+  SpawnWorkspaceDeps,
+  SpawnWorkspaceInput,
+} from "./tool";
+import { createCowStrategy } from "./strategy";
+
+/**
+ * The tool's input schema, as the v2 plugin API expects a JSON Schema. Kept a
+ * plain object because the installed plugin package is a v1 build; the running
+ * v2 binary decodes it.
+ */
+const spawnWorkspaceInput = {
+  type: "object",
+  properties: {
+    sourceDirectory: {
+      type: "string",
+      description: "The project directory to clone or branch from.",
+    },
+    name: {
+      type: "string",
+      description: "Optional name for the worktree and its session.",
+    },
+  },
+  required: ["sourceDirectory"],
+  additionalProperties: false,
+} as const;
+
+/**
+ * The tool's declared output, as a JSON Schema. A tool that returns an `output`
+ * field must declare its schema: opencode2 treats an undeclared output as a
+ * defect ("Tool result declared output without an output schema"), not as a
+ * recoverable error. The reported mechanism is part of the contract, so the
+ * structured result is declared rather than flattened into text.
+ */
+const spawnWorkspaceOutput = {
+  type: "object",
+  properties: {
+    sessionID: {
+      type: "string",
+      description: "The session started in the created directory.",
+    },
+    directory: {
+      type: "string",
+      description: "The working directory that was produced.",
+    },
+    mechanism: {
+      type: "string",
+      enum: ["cow", "git"],
+      description: "The mechanism that produced the directory.",
+    },
+    attached: {
+      type: "boolean",
+      description:
+        "True when the session was attached to an existing worktree instead of a new clone.",
+    },
+  },
+  required: ["sessionID", "directory", "mechanism"],
+  additionalProperties: false,
+} as const;
+
+/**
+ * `list_worktrees` takes no input. The empty object keeps the shape the tool
+ * seam expects (a JSON Schema object) while declaring that no properties
+ * exist.
+ */
+const listWorktreesInput = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+} as const;
+
+/**
+ * `list_worktrees`' declared output, with the same rule as
+ * `spawn_workspace`'s: a tool that returns an `output` field must declare its
+ * schema. The four entry fields are exactly what `listCowWorktrees` derives.
+ */
+const listWorktreesOutput = {
+  type: "object",
+  properties: {
+    worktrees: {
+      type: "array",
+      description: "The location's cow worktrees, in inventory order.",
+      items: {
+        type: "object",
+        properties: {
+          name: {
+            type: "string",
+            description: "The worktree directory's basename.",
+          },
+          directory: {
+            type: "string",
+            description: "The worktree directory, as the worktree inventory records it.",
+          },
+          strategy: {
+            type: "string",
+            enum: ["cow"],
+            description: "Only cow worktrees are listed.",
+          },
+          createdAt: {
+            type: "string",
+            description:
+              "ISO 8601 timestamp of the directory's birthtime, falling back to its " +
+              "mtime when the filesystem reports no birthtime.",
+          },
+        },
+        required: ["name", "directory", "strategy", "createdAt"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["worktrees"],
+  additionalProperties: false,
+} as const;
+
+/**
+ * Binds `spawnWorkspace`'s seams to the live opencode2 context. The tool is
+ * the layer that owns the strategy choice, so the capability probe and the
+ * worktree/session APIs meet here and nowhere else.
+ *
+ * The fallback policy and the Worktree target root arrive already validated —
+ * `setup` read them from the plugin's options once and passes the values in.
+ * The fallback defaults to `"none"`: a request for `cow` is a statement about
+ * what the caller gets, so the tool never produces a Shallow worktree unless
+ * the opt-in was set. The target root defaults to unset, which makes the tool
+ * place the Worktree beside the source — the same-filesystem parent a CoW
+ * clone requires.
+ */
+function liveDeps(
+  ctx: Context,
+  fallback: FallbackPolicy,
+  worktreeRoot: string | undefined,
+): SpawnWorkspaceDeps {
+  return {
+    probe: probeCowCapability,
+    probeDevice: deviceOf,
+    listWorktrees: () => ctx.worktree.list(),
+    isDirectory,
+    createWorktree: (input) =>
+      ctx.worktree.create({
+        strategy: input.strategy,
+        name: input.name,
+        location: { directory: input.sourceDirectory },
+        directory: input.parentDirectory,
+      }),
+    createSession: async (directory, name) => {
+      const session = await ctx.session.create({ title: name, location: { directory } });
+      return session.id;
+    },
+    removeWorktree: (directory) =>
+      ctx.worktree.remove({ directory, force: true }),
+    fallback,
+    targetRoot: worktreeRoot,
+  };
+}
+
+/**
+ * The opencode2 plugin module.
+ *
+ * `setup` registers the `cow` Strategy through the worktree seam, and the
+ * `spawn_workspace` and `list_worktrees` tools through the tool seam.
+ * Registering the Strategy also selects it as the Location default; opencode2's
+ * registry still lets a caller name the built-in `git` strategy explicitly, so
+ * this module does not touch that behavior.
+ */
+export default {
+  id: "opencode2-cow-worktree",
+  async setup(ctx: Context): Promise<void> {
+    // Every plugin option is validated exactly once, here, before anything is
+    // registered: a misconfiguration must fail the plugin load, not surface
+    // inside the first tool call or halfway through a create. The validated
+    // values close over into the strategy and the tool bindings below, so
+    // the tool path never re-reads — or re-throws on — `ctx.options`.
+    const hooks = postCreateHooks(ctx.options);
+    const fallback = fallbackPolicy(ctx.options);
+    const worktreeRoot = targetRoot(ctx.options);
+    await ctx.worktree.transform((editor) => {
+      editor.add(createCowStrategy({ postCreate: hooks }));
+    });
+    // `?.`: the installed plugin package is a v1 build whose Context has no
+    // tool domain; the v2 binary always provides it. Optional chaining keeps
+    // setup usable with a context that predates the tool seam.
+    await ctx.tool?.transform((editor) => {
+      editor.add({
+        name: "spawn_workspace",
+        description:
+          "Create a worktree and start a session in it, reporting the mechanism that produced the directory. " +
+          "When a worktree with the requested name already exists and was produced by the cow strategy, the " +
+          "session is attached to it instead of creating a new directory; anything else at that name is refused.",
+        input: spawnWorkspaceInput,
+        output: spawnWorkspaceOutput,
+        // A tool defaults into CodeMode, which advertises it to the model only
+        // through `execute`. This tool must be callable by name, so it is kept
+        // on the provider's native tool list.
+        options: { codemode: false },
+        execute: async (input: SpawnWorkspaceInput) => {
+          const result = await spawnWorkspace(input, liveDeps(ctx, fallback, worktreeRoot));
+          // The text is what tells attach from create: on attach `mechanism`
+          // reports the found directory's mechanism, and the caller must never
+          // read that as a fresh clone having happened.
+          const content = result.attached
+            ? `Attached to existing cow worktree at ${result.directory} (session ${result.sessionID}); no new worktree was created.`
+            : `Created ${result.mechanism} worktree at ${result.directory} (session ${result.sessionID}).`;
+          return {
+            output: result,
+            content,
+          };
+        },
+      });
+      editor.add({
+        name: "list_worktrees",
+        description:
+          "List this location's cow worktrees: each entry carries the directory's basename as " +
+          "name, the directory, the strategy, and createdAt from a stat of the directory " +
+          "(birthtime, falling back to mtime when the filesystem reports none). Derived from " +
+          "opencode2's worktree inventory alone — there is no sessions field, because server " +
+          "plugins cannot enumerate sessions (ADR 0003). The list fails rather than skipping " +
+          "when an inventory row's directory cannot be read: the inventory is truth.",
+        input: listWorktreesInput,
+        output: listWorktreesOutput,
+        // Same reason as spawn_workspace above: callable by name, not routed
+        // through CodeMode.
+        options: { codemode: false },
+        execute: async () => {
+          const worktrees = await listCowWorktrees({
+            // Own minimal deps, not liveDeps: this read-only call touches only
+            // the inventory and one stat per row, none of spawn_workspace's
+            // other seams. (Option validation happens once in setup, so there
+            // is no validation side effect to dodge either way.)
+            listWorktrees: () => ctx.worktree.list(),
+            statEntry: stat,
+          });
+          const summary =
+            worktrees.length === 0 ? "0 cow worktree(s)" : `${worktrees.length} cow worktree(s):`;
+          return {
+            output: { worktrees },
+            content: `${summary}\n${JSON.stringify(worktrees, null, 2)}`,
+          };
+        },
+      });
+    });
+  },
+};

package/src/removal.ts

@@ -0,0 +1,306 @@
+import { randomBytes } from "node:crypto";
+import { readdir, rename, rm, stat } from "node:fs/promises";
+import type { Dirent, Stats } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/**
+ * The mechanics half of `cow`'s `remove`: identity-captured, quarantine-renamed
+ * deletion.
+ *
+ * `rm` deletes whatever occupies a path now, not the directory that was audited.
+ * Between the dirty guard's probe and the delete, the path can be swapped or
+ * recycled — a rename racing the removal, a create taking the freed name — and
+ * an in-place `rm` would destroy the newcomer in the audited worktree's name.
+ * So the directory is first stat'd (dev + inode), renamed to a sibling
+ * quarantine name, and the quarantine path is re-stat'd: only when the identity
+ * still matches the capture is the copy deleted. A mismatch aborts loudly and
+ * moves the directory back. The original path is never deleted in place; at
+ * every point before the identity is re-confirmed, a failure leaves it intact.
+ *
+ * The rename is also what keeps an agent holding a cwd inside the worktree from
+ * blocking the removal: the path is vacated immediately even though its former
+ * contents cannot be fully unlinked until that process lets go.
+ *
+ * The slow tail — dependency directories like `node_modules` — is deleted
+ * asynchronously in-process (the server is long-lived) after the removal
+ * returns, with failures logged, never thrown: a deletion the caller is no
+ * longer waiting on must not turn a reported success into a late error.
+ *
+ * A leftover `.cow-removing-…` directory means a deletion failed midway (the
+ * thrown or logged error names it): it holds the remains of a removed worktree
+ * and nothing else, and is safe to delete by hand once no process is using it.
+ */
+
+/** The filesystem identity a directory is pinned by: device + inode. */
+interface DirectoryIdentity {
+  readonly dev: number;
+  readonly ino: number;
+}
+
+/**
+ * The dependency-directory class removed by the background tail, recognised by
+ * name at the quarantine's top level. Everything nested inside a deferred one
+ * goes with it — the tail deletes with the same recursive mechanics as the
+ * in-band pass.
+ */
+const HEAVY_DIRECTORY = "node_modules";
+
+/** How much randomness separates a quarantine name from any other sibling. */
+const QUARANTINE_RANDOM_BYTES = 12;
+
+/**
+ * Removes a directory whose identity has been captured and re-confirmed, per
+ * the module doc. Resolves once the original path is vacated and the in-band
+ * deletion finished; any remaining dependency directories are the background
+ * tail's business.
+ *
+ * A missing directory is a completed removal, not an error: opencode2's
+ * `remove` is idempotent the same way `rm`'s `force` was.
+ */
+export async function removeQuarantined(directory: string): Promise<void> {
+  const captured = await captureIdentity(directory);
+  if (captured === undefined) return;
+  const quarantine = quarantineTarget(directory);
+  try {
+    await renamePath(directory, quarantine);
+  } catch (cause) {
+    throw new Error(
+      `cow cannot remove ${directory}: moving it aside to ${quarantine} failed, ` +
+        "so the original directory was left untouched.",
+      { cause },
+    );
+  }
+  await verifyQuarantined(captured, directory, quarantine);
+  await deleteInBand(quarantine);
+}
+
+/**
+ * The dev + inode of the directory a path names, or `undefined` when the path
+ * does not exist. Any other stat failure is real corruption (a file where a
+ * directory component belongs, a permission problem) and propagates: deleting
+ * on an unreadable path is how the wrong thing gets destroyed.
+ */
+async function captureIdentity(
+  directory: string,
+): Promise<DirectoryIdentity | undefined> {
+  try {
+    const stats = await statDirectory(directory);
+    return { dev: stats.dev, ino: stats.ino };
+  } catch (cause) {
+    if (isMissing(cause)) return undefined;
+    throw cause;
+  }
+}
+
+/**
+ * Re-validates the quarantine path against the capture before anything is
+ * deleted. A mismatch — or a quarantine path that cannot be read at all — means
+ * what sits there is not the audited directory, so it is moved back to the
+ * original path and the operation aborts loudly. When even the move-back fails,
+ * both failures are chained: the files are stranded at the quarantine path and
+ * the error must say so.
+ */
+async function verifyQuarantined(
+  captured: DirectoryIdentity,
+  directory: string,
+  quarantine: string,
+): Promise<void> {
+  if (await identityMatches(quarantine, captured)) return;
+  try {
+    await renamePath(quarantine, directory);
+  } catch (cause) {
+    throw new Error(
+      `cow cannot remove ${directory}: the quarantine path ${quarantine} does ` +
+        "not hold the directory whose identity was captured, and moving the " +
+        `worktree back to ${directory} failed. Nothing was deleted; the files ` +
+        `remain at ${quarantine}.`,
+      { cause },
+    );
+  }
+  throw new Error(
+    `cow cannot remove ${directory}: the quarantine path ${quarantine} does ` +
+      "not hold the directory whose identity was captured, so deleting it " +
+      "could destroy files that were never audited. The worktree was moved " +
+      `back to ${directory}; nothing was deleted.`,
+  );
+}
+
+/**
+ * Whether the path still holds the captured directory. An unreadable path is a
+ * mismatch, never a pass: only a positive identity match allows deletion.
+ */
+async function identityMatches(
+  path: string,
+  captured: DirectoryIdentity,
+): Promise<boolean> {
+  try {
+    const stats = await statDirectory(path);
+    return stats.dev === captured.dev && stats.ino === captured.ino;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The in-band deletion: everything in the quarantine copy except dependency
+ * directories, which are handed to the background tail. With no tail work the
+ * quarantine directory is removed here too, so an ordinary removal leaves no
+ * trace behind. A child — or the listing, or the quarantine copy itself —
+ * that cannot be deleted fails the removal with the quarantine path in the
+ * message: the original path is already vacated, so the remains and their
+ * meaning are the one thing the caller must learn.
+ */
+async function deleteInBand(quarantine: string): Promise<void> {
+  const heavy: string[] = [];
+  let entries: Dirent[];
+  try {
+    entries = await readDirectory(quarantine);
+  } catch (cause) {
+    throw new Error(
+      `cow could not finish removing the worktree: reading the quarantine ` +
+        `copy ${quarantine} failed, so remains are left at ${quarantine}. ` +
+        "The original worktree path is gone; the remains hold nothing else " +
+        "and are safe to delete by hand.",
+      { cause },
+    );
+  }
+  for (const entry of entries) {
+    const child = join(quarantine, entry.name);
+    if (entry.name === HEAVY_DIRECTORY && entry.isDirectory()) {
+      heavy.push(child);
+      continue;
+    }
+    await removeChild(child, quarantine);
+  }
+  if (heavy.length > 0) {
+    void deleteHeavyTail(quarantine, heavy);
+    return;
+  }
+  try {
+    await removeTree(quarantine);
+  } catch (cause) {
+    throw new Error(
+      `cow could not finish removing the worktree: deleting the quarantine ` +
+        `copy ${quarantine} failed, so remains are left at ${quarantine}. ` +
+        "The original worktree path is gone; the remains hold nothing else " +
+        "and are safe to delete by hand.",
+      { cause },
+    );
+  }
+}
+
+/**
+ * Deletes one in-band child, converting a failure into the removal's error.
+ * Logged as well as thrown: the thrown error may reach the caller compressed,
+ * while the log carries the record for whoever inspects the server.
+ */
+async function removeChild(child: string, quarantine: string): Promise<void> {
+  try {
+    await removeTree(child);
+  } catch (cause) {
+    const error = new Error(
+      `cow could not finish removing the worktree: deleting ${child} inside ` +
+        `the quarantine copy failed, so remains are left at ${quarantine}. ` +
+        "The original worktree path is gone; the remains hold nothing else " +
+        "and are safe to delete by hand.",
+      { cause },
+    );
+    logFailure(error.message);
+    throw error;
+  }
+}
+
+/**
+ * The background tail: deletes the deferred dependency directories and then the
+ * quarantine shell, logging every failure and never throwing — the caller that
+ * triggered this has already been told the removal succeeded.
+ */
+export async function deleteHeavyTail(
+  quarantine: string,
+  heavy: readonly string[],
+): Promise<void> {
+  for (const directory of heavy) {
+    try {
+      await removeTree(directory);
+    } catch (cause) {
+      logFailure(
+        `cow could not delete the dependency directory ${directory} while ` +
+          `finishing a removal: ${describeCause(cause)}. Its files remain ` +
+          "there and are safe to delete by hand.",
+      );
+    }
+  }
+  try {
+    await removeTree(quarantine);
+  } catch (cause) {
+    logFailure(
+      `cow could not delete the quarantine directory ${quarantine} while ` +
+        `finishing a removal: ${describeCause(cause)}. Whatever remains ` +
+        "there is safe to delete by hand.",
+    );
+  }
+}
+
+/** Where a failed tail is recorded: the server's own log. */
+function logFailure(message: string): void {
+  console.error(message);
+}
+
+/** The human-readable half of a logged cause. */
+function describeCause(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+/**
+ * The sibling quarantine path: same parent (so the rename never crosses a
+ * device), hidden dot-name with the `.cow-removing-` prefix and a random
+ * suffix. The prefix keeps the name out of the worktree namespace callers
+ * choose, and the randomness keeps concurrent removals from colliding with
+ * each other or with a directory a caller could predict.
+ */
+function quarantineTarget(directory: string): string {
+  const name = basename(directory);
+  const random = randomBytes(QUARANTINE_RANDOM_BYTES).toString("hex");
+  return join(dirname(directory), `.cow-removing-${name}-${random}`);
+}
+
+/**
+ * Whether an error is a plain ENOENT — "the path is not there", which for a
+ * removal means the work is already done. Node's filesystem errors carry the
+ * code; anything else is not an absence answer.
+ */
+function isMissing(cause: unknown): boolean {
+  return (
+    typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT"
+  );
+}
+
+// The filesystem seams below are module-level exports so `bun:test`'s `spyOn`
+// can replace what this module calls — the same pattern as `probeUncommitted`
+// and `deviceOf`. The calls are deliberately unqualified.
+
+/** `stat`, following symlinks: a symlinked worktree still owns its contents. */
+export async function statDirectory(path: string): Promise<Stats> {
+  return stat(path);
+}
+
+/** `readdir`, listing the quarantine copy for the in-band deletion pass. */
+export async function readDirectory(path: string): Promise<Dirent[]> {
+  return readdir(path, { withFileTypes: true });
+}
+
+/** `rename`, the quarantine step and, on a mismatch, the way back. */
+export async function renamePath(from: string, to: string): Promise<void> {
+  await rename(from, to);
+}
+
+/**
+ * The deletion mechanics: `rm` with a literal `force: true`, because a path
+ * this function is authorized to delete may legitimately be gone already.
+ */
+export async function removeTree(path: string): Promise<void> {
+  await rm(path, { recursive: true, force: true });
+}