@sven1103/opencode-worktree-workflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sven Fillinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# OpenCode Worktree Workflow
+
+`@sven1103/opencode-worktree-workflow` is an OpenCode plugin that adds git worktree helpers for creating synced feature worktrees and cleaning up merged ones.
+
+## Install in an OpenCode project
+
+Add the plugin package to your project config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@sven1103/opencode-worktree-workflow"]
+}
+```
+
+OpenCode installs npm plugins with Bun when it starts.
+
+## What the plugin provides
+
+- `worktree_prepare`: create a worktree and matching branch from the latest default-branch commit
+- `worktree_cleanup`: preview or remove merged worktrees
+
+This package currently focuses on plugin distribution. Slash command packaging can be layered on later.
+
+## Optional project configuration
+
+You can override the defaults in `opencode.json`, `opencode.jsonc`, or `.opencode/worktree-workflow.json`:
+
+```json
+{
+  "worktreeWorkflow": {
+    "branchPrefix": "wt/",
+    "remote": "origin",
+    "worktreeRoot": "../.worktrees/$REPO",
+    "cleanupMode": "preview",
+    "protectedBranches": ["release"]
+  }
+}
+```
+
+Supported settings:
+
+- `branchPrefix`: prefix for generated worktree branches
+- `remote`: remote used to detect the default branch and fetch updates
+- `worktreeRoot`: destination root for new worktrees; supports `$REPO`, `$ROOT`, and `$ROOT_PARENT`
+- `cleanupMode`: default cleanup behavior, either `preview` or `apply`
+- `protectedBranches`: branches that should never be auto-cleaned
+
+## Publish workflow
+
+This repo is prepared for npm publishing from GitHub Actions using npm trusted publishing.
+
+Typical release flow:
+
+1. Publish the package once manually to create it on npm.
+2. Configure the package's trusted publisher on npm for `.github/workflows/publish.yml`.
+3. Tag a release like `v0.1.0` and push the tag.
+
+The GitHub Actions workflow then runs `npm publish` using OIDC, without storing an `NPM_TOKEN` secret.
+
+## Local development
+
+The repo still contains a project-local `.opencode/` setup for development and testing:
+
+- `.opencode/plugins/worktree.js` re-exports the plugin from `src/index.js`
+- `.opencode/commands/` contains local slash command wrappers for manual testing
+- `.opencode/worktree-workflow.md` documents the local workflow
+
+The publishable npm artifact is limited to `src/` via the root `package.json` `files` field. Install dependencies at the repo root with `npm install` for local development.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sven1103/opencode-worktree-workflow",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for creating and cleaning up git worktrees.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "git",
+    "worktree"
+  ],
+  "license": "MIT",
+  "author": "Sven Fillinger",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sven1103-agent/opencode-worktree-plugin.git"
+  },
+  "homepage": "https://github.com/sven1103-agent/opencode-worktree-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/sven1103-agent/opencode-worktree-plugin/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.3.0",
+    "jsonc-parser": "^3.3.1"
+  }
+}

package/src/index.js

@@ -0,0 +1,433 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "jsonc-parser";
+import { tool } from "@opencode-ai/plugin";
+
+const DEFAULTS = {
+  branchPrefix: "wt/",
+  remote: "origin",
+  worktreeRoot: "../.worktrees/$REPO",
+  cleanupMode: "preview",
+  protectedBranches: [],
+};
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonFile(filePath) {
+  if (!(await pathExists(filePath))) {
+    return null;
+  }
+
+  const source = await fs.readFile(filePath, "utf8");
+  const data = parse(source);
+  return data && typeof data === "object" ? data : null;
+}
+
+function normalizeBranchPrefix(prefix) {
+  if (!prefix) {
+    return "";
+  }
+
+  return prefix.endsWith("/") ? prefix : `${prefix}/`;
+}
+
+function slugifyTitle(title) {
+  return title
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+}
+
+function formatRootTemplate(template, repoRoot) {
+  const repoName = path.basename(repoRoot);
+  return template
+    .replaceAll("$REPO", repoName)
+    .replaceAll("$ROOT", repoRoot)
+    .replaceAll("$ROOT_PARENT", path.dirname(repoRoot));
+}
+
+function parseShortBranch(branchRef) {
+  const prefix = "refs/heads/";
+  return branchRef.startsWith(prefix) ? branchRef.slice(prefix.length) : branchRef;
+}
+
+function parseWorktreeList(output) {
+  const entries = [];
+  let current = null;
+
+  for (const rawLine of output.split("\n")) {
+    const line = rawLine.trim();
+    if (!line) {
+      if (current) {
+        entries.push(current);
+        current = null;
+      }
+      continue;
+    }
+
+    if (line.startsWith("worktree ")) {
+      if (current) {
+        entries.push(current);
+      }
+      current = { path: line.slice("worktree ".length) };
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    if (line.startsWith("HEAD ")) {
+      current.head = line.slice("HEAD ".length);
+      continue;
+    }
+
+    if (line.startsWith("branch ")) {
+      current.branchRef = line.slice("branch ".length);
+      current.branch = parseShortBranch(current.branchRef);
+      continue;
+    }
+
+    if (line === "detached") {
+      current.detached = true;
+    }
+  }
+
+  if (current) {
+    entries.push(current);
+  }
+
+  return entries;
+}
+
+function formatPreview(candidates, defaultBranch) {
+  if (candidates.length === 0) {
+    return [
+      `No merged worktrees are ready for cleanup against ${defaultBranch}.`,
+      "",
+      "Use `/wt-clean apply` after merged branches appear here.",
+    ].join("\n");
+  }
+
+  return [
+    `Merged worktrees ready for cleanup against ${defaultBranch}:`,
+    ...candidates.map(
+      (candidate) =>
+        `- ${candidate.branch} -> ${candidate.path}${candidate.head ? ` (${candidate.head.slice(0, 12)})` : ""}`,
+    ),
+    "",
+    "Run `/wt-clean apply` to remove these worktrees and delete their local branches.",
+  ].join("\n");
+}
+
+function formatCleanupSummary(defaultBranch, removed, failed) {
+  const lines = [`Cleaned worktrees merged into ${defaultBranch}:`];
+
+  if (removed.length === 0) {
+    lines.push("- none removed");
+  } else {
+    for (const item of removed) {
+      lines.push(`- removed ${item.branch} -> ${item.path}`);
+    }
+  }
+
+  if (failed.length > 0) {
+    lines.push("");
+    lines.push("Cleanup skipped for:");
+    for (const item of failed) {
+      lines.push(`- ${item.branch} -> ${item.path}: ${item.reason}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
+  async function git(args, options = {}) {
+    const cwd = options.cwd ?? directory;
+    const command = `git ${args.map((arg) => $.escape(String(arg))).join(" ")}`;
+    const result = await $`${{ raw: command }}`.cwd(cwd).quiet().nothrow();
+    const stdout = result.text().trim();
+    const stderr = result.stderr.toString("utf8").trim();
+
+    if (!options.allowFailure && result.exitCode !== 0) {
+      throw new Error(stderr || stdout || `Git command failed: ${command}`);
+    }
+
+    return {
+      stdout,
+      stderr,
+      exitCode: result.exitCode,
+    };
+  }
+
+  async function getRepoRoot() {
+    const result = await git(["rev-parse", "--show-toplevel"]);
+    return result.stdout;
+  }
+
+  async function loadWorkflowConfig(repoRoot) {
+    const [projectConfig, projectConfigC, sidecarConfig] = await Promise.all([
+      readJsonFile(path.join(repoRoot, "opencode.json")),
+      readJsonFile(path.join(repoRoot, "opencode.jsonc")),
+      readJsonFile(path.join(repoRoot, ".opencode", "worktree-workflow.json")),
+    ]);
+
+    const merged = {
+      ...DEFAULTS,
+      ...(projectConfig?.worktreeWorkflow ?? {}),
+      ...(projectConfigC?.worktreeWorkflow ?? {}),
+      ...(sidecarConfig ?? {}),
+    };
+
+    return {
+      branchPrefix: normalizeBranchPrefix(merged.branchPrefix ?? DEFAULTS.branchPrefix),
+      remote: merged.remote || DEFAULTS.remote,
+      cleanupMode: merged.cleanupMode === "apply" ? "apply" : DEFAULTS.cleanupMode,
+      protectedBranches: Array.isArray(merged.protectedBranches)
+        ? merged.protectedBranches.filter((value) => typeof value === "string")
+        : [],
+      worktreeRoot: path.resolve(repoRoot, formatRootTemplate(merged.worktreeRoot || DEFAULTS.worktreeRoot, repoRoot)),
+    };
+  }
+
+  async function getDefaultBranch(repoRoot, remote) {
+    const remoteHead = await git(
+      ["symbolic-ref", "--quiet", "--short", `refs/remotes/${remote}/HEAD`],
+      { cwd: repoRoot, allowFailure: true },
+    );
+
+    if (remoteHead.exitCode === 0 && remoteHead.stdout.startsWith(`${remote}/`)) {
+      return remoteHead.stdout.slice(remote.length + 1);
+    }
+
+    const remoteShow = await git(["remote", "show", remote], {
+      cwd: repoRoot,
+      allowFailure: true,
+    });
+
+    if (remoteShow.exitCode === 0) {
+      const match = remoteShow.stdout.match(/HEAD branch: (.+)/);
+      if (match?.[1]) {
+        return match[1].trim();
+      }
+    }
+
+    for (const candidate of ["main", "master", "trunk", "develop"]) {
+      const hasLocal = await git(["show-ref", "--verify", "--quiet", `refs/heads/${candidate}`], {
+        cwd: repoRoot,
+        allowFailure: true,
+      });
+      if (hasLocal.exitCode === 0) {
+        return candidate;
+      }
+
+      const hasRemote = await git(["show-ref", "--verify", "--quiet", `refs/remotes/${remote}/${candidate}`], {
+        cwd: repoRoot,
+        allowFailure: true,
+      });
+      if (hasRemote.exitCode === 0) {
+        return candidate;
+      }
+    }
+
+    const currentBranch = await git(["branch", "--show-current"], {
+      cwd: repoRoot,
+      allowFailure: true,
+    });
+
+    if (currentBranch.stdout) {
+      return currentBranch.stdout;
+    }
+
+    throw new Error("Could not determine the default branch for this repository.");
+  }
+
+  async function getBaseRef(repoRoot, remote, defaultBranch) {
+    await git(["fetch", "--prune", remote, defaultBranch], { cwd: repoRoot });
+
+    const remoteRef = `refs/remotes/${remote}/${defaultBranch}`;
+    const remoteExists = await git(["show-ref", "--verify", "--quiet", remoteRef], {
+      cwd: repoRoot,
+      allowFailure: true,
+    });
+
+    return remoteExists.exitCode === 0 ? `${remote}/${defaultBranch}` : defaultBranch;
+  }
+
+  async function ensureBranchDoesNotExist(repoRoot, branchName) {
+    const exists = await git(["show-ref", "--verify", "--quiet", `refs/heads/${branchName}`], {
+      cwd: repoRoot,
+      allowFailure: true,
+    });
+
+    if (exists.exitCode === 0) {
+      throw new Error(`Local branch already exists: ${branchName}`);
+    }
+  }
+
+  return {
+    tool: {
+      worktree_prepare: tool({
+        description: "Create a synced git worktree from a descriptive title",
+        args: {
+          title: tool.schema.string().min(3).describe("Descriptive working title for the new worktree"),
+        },
+        async execute(args, context) {
+          context.metadata({ title: `Create worktree: ${args.title}` });
+
+          const repoRoot = await getRepoRoot();
+          const config = await loadWorkflowConfig(repoRoot);
+          const defaultBranch = await getDefaultBranch(repoRoot, config.remote);
+          const baseRef = await getBaseRef(repoRoot, config.remote, defaultBranch);
+          const baseCommit = (await git(["rev-parse", baseRef], { cwd: repoRoot })).stdout;
+          const slug = slugifyTitle(args.title);
+
+          if (!slug) {
+            throw new Error("Could not derive a branch name from the provided title.");
+          }
+
+          const branchName = `${config.branchPrefix}${slug}`;
+          const worktreePath = path.join(config.worktreeRoot, slug);
+
+          await ensureBranchDoesNotExist(repoRoot, branchName);
+
+          if (await pathExists(worktreePath)) {
+            throw new Error(`Worktree path already exists: ${worktreePath}`);
+          }
+
+          await fs.mkdir(config.worktreeRoot, { recursive: true });
+          await git(["worktree", "add", "-b", branchName, worktreePath, baseRef], {
+            cwd: repoRoot,
+          });
+
+          const branchCommit = (await git(["rev-parse", branchName], { cwd: repoRoot })).stdout;
+          if (branchCommit !== baseCommit) {
+            throw new Error(
+              `New branch ${branchName} does not match ${defaultBranch} at ${baseCommit}. Found ${branchCommit} instead.`,
+            );
+          }
+
+          return [
+            `Created worktree for \"${args.title}\".`,
+            `- branch: ${branchName}`,
+            `- worktree: ${worktreePath}`,
+            `- default branch: ${defaultBranch}`,
+            `- base ref: ${baseRef}`,
+            `- base commit: ${baseCommit}`,
+          ].join("\n");
+        },
+      }),
+      worktree_cleanup: tool({
+        description: "Preview or clean merged git worktrees",
+        args: {
+          mode: tool.schema
+            .enum(["preview", "apply"])
+            .default("preview")
+            .describe("Preview cleanup candidates or remove them"),
+        },
+        async execute(args, context) {
+          context.metadata({ title: `Clean worktrees (${args.mode})` });
+
+          const repoRoot = await getRepoRoot();
+          const config = await loadWorkflowConfig(repoRoot);
+          const defaultBranch = await getDefaultBranch(repoRoot, config.remote);
+          const baseRef = await getBaseRef(repoRoot, config.remote, defaultBranch);
+          const activeWorktree = path.resolve(context.worktree || repoRoot);
+          const worktreeList = await git(["worktree", "list", "--porcelain"], { cwd: repoRoot });
+          const entries = parseWorktreeList(worktreeList.stdout);
+          const protectedBranches = new Set([defaultBranch, ...config.protectedBranches]);
+          const candidates = [];
+
+          for (const entry of entries) {
+            const entryPath = path.resolve(entry.path);
+            const branchName = entry.branch;
+
+            if (!branchName || entry.detached) {
+              continue;
+            }
+
+            if (entryPath === path.resolve(repoRoot) || entryPath === activeWorktree) {
+              continue;
+            }
+
+            if (protectedBranches.has(branchName)) {
+              continue;
+            }
+
+            const merged = await git(["merge-base", "--is-ancestor", branchName, baseRef], {
+              cwd: repoRoot,
+              allowFailure: true,
+            });
+
+            if (merged.exitCode === 0) {
+              candidates.push({
+                branch: branchName,
+                path: entryPath,
+                head: entry.head,
+              });
+            }
+          }
+
+          const requestedMode = args.mode || config.cleanupMode;
+          if (requestedMode !== "apply") {
+            return formatPreview(candidates, defaultBranch);
+          }
+
+          const removed = [];
+          const failed = [];
+
+          for (const candidate of candidates) {
+            const removeWorktree = await git(["worktree", "remove", candidate.path], {
+              cwd: repoRoot,
+              allowFailure: true,
+            });
+
+            if (removeWorktree.exitCode !== 0) {
+              failed.push({
+                ...candidate,
+                reason: removeWorktree.stderr || removeWorktree.stdout || "worktree remove failed",
+              });
+              continue;
+            }
+
+            const deleteBranch = await git(["branch", "-d", candidate.branch], {
+              cwd: repoRoot,
+              allowFailure: true,
+            });
+
+            if (deleteBranch.exitCode !== 0) {
+              failed.push({
+                ...candidate,
+                reason: deleteBranch.stderr || deleteBranch.stdout || "branch delete failed",
+              });
+              continue;
+            }
+
+            removed.push(candidate);
+          }
+
+          await git(["worktree", "prune"], {
+            cwd: repoRoot,
+            allowFailure: true,
+          });
+
+          return formatCleanupSummary(defaultBranch, removed, failed);
+        },
+      }),
+    },
+  };
+};
+
+export default WorktreeWorkflowPlugin;