@sven1103/opencode-worktree-workflow 0.3.0 → 0.5.0

package/README.md

@@ -36,6 +36,7 @@ npm install @sven1103/opencode-worktree-workflow
 OpenCode loads custom commands from either `.opencode/commands/` (project) or `~/.config/opencode/commands/` (global).
 
 This repo publishes `wt-new.md` and `wt-clean.md` as GitHub Release assets so you can install them without browsing the repository.
+For a plain-language explanation of what each release contains, how it is produced, and how to verify it before installing, see `docs/releases.md`.
 
 Project install (latest release):
 
@@ -76,24 +77,34 @@ curl -fsSL "https://github.com/sven1103-agent/opencode-worktree-plugin/releases/
 
 ## 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
+- `worktree_prepare`: create a worktree and matching branch from the latest configured base-branch commit, or the default branch when no base branch is configured
+- `worktree_cleanup`: preview all connected worktrees against the configured base branch, auto-clean safe ones, and optionally remove selected review items
 
 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`:
+OpenCode's native `opencode.json` and `opencode.jsonc` files are schema-validated, so they can load this plugin through the standard `plugin` key but they cannot store a custom `worktreeWorkflow` block.
+
+To override this plugin's defaults, put a sidecar config file at `.opencode/worktree-workflow.json`:
 
 ```json
 {
-  "worktreeWorkflow": {
-    "branchPrefix": "wt/",
-    "remote": "origin",
-    "worktreeRoot": ".worktrees/$REPO",
-    "cleanupMode": "preview",
-    "protectedBranches": ["release"]
-  }
+  "branchPrefix": "wt/",
+  "remote": "origin",
+  "baseBranch": "release/v0.4.0",
+  "worktreeRoot": ".worktrees/$REPO",
+  "cleanupMode": "preview",
+  "protectedBranches": ["release"]
+}
+```
+
+Use `opencode.json` only to load the npm plugin itself:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@sven1103/opencode-worktree-workflow"]
 }
 ```
 
@@ -101,6 +112,7 @@ Supported settings:
 
 - `branchPrefix`: prefix for generated worktree branches
 - `remote`: remote used to detect the default branch and fetch updates
+- `baseBranch`: optional branch name used as the creation and cleanup base; defaults to the remote's default branch
 - `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
@@ -109,6 +121,8 @@ Supported settings:
 
 This repo is prepared for npm publishing from GitHub Actions using npm trusted publishing.
 
+If you consume releases instead of contributing to the repo, `docs/releases.md` is the end-user guide for understanding what the published npm package and GitHub Release assets include.
+
 Typical release flow:
 
 1. Publish the package once manually to create it on npm.
@@ -117,7 +131,7 @@ Typical release flow:
 
 The release workflow creates a `release/v<version>` branch from `main`, updates `package.json` and `package-lock.json`, commits the version bump there, creates a matching `v<version>` tag, and pushes the branch and tag.
 
-The release workflow then explicitly starts the publish workflow for that tag, which verifies the tag matches `package.json` before running `npm publish` using OIDC, without storing an `NPM_TOKEN` secret. Merge the release branch back to `main` afterward if you want the version bump recorded on the default branch.
+The release workflow then explicitly starts the publish workflow for that tag, which verifies the tag matches `package.json`, runs `npm publish` using OIDC without storing an `NPM_TOKEN` secret, and creates or updates the GitHub Release with generated release notes plus the command assets. Merge the release branch back to `main` afterward if you want the version bump recorded on the default branch.
 
 ## Local development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sven1103/opencode-worktree-workflow",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "OpenCode plugin for creating and cleaning up git worktrees.",
   "type": "module",
   "main": "./src/index.js",
@@ -32,6 +32,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "dependencies": {
     "@opencode-ai/plugin": "1.3.0",
     "jsonc-parser": "^3.3.1"

package/src/index.js

@@ -7,6 +7,7 @@ import { tool } from "@opencode-ai/plugin";
 const DEFAULTS = {
   branchPrefix: "wt/",
   remote: "origin",
+  baseBranch: null,
   worktreeRoot: ".worktrees/$REPO",
   cleanupMode: "preview",
   protectedBranches: [],
@@ -111,34 +112,74 @@ function parseWorktreeList(output) {
   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");
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function formatWorktreeSummary(item) {
+  return `${item.branch || "(detached)"} -> ${item.path}${item.head ? ` (${item.head.slice(0, 12)})` : ""}`;
+}
+
+function formatCopyPasteCommands(item) {
+  const selector = item.branch || item.path;
+  const branchFlag = item.status === "safe" ? "-d" : "-D";
+
+  return [
+    `  copy: /wt-clean apply ${selector}`,
+    `  git:  git worktree remove ${shellQuote(item.path)} && git branch ${branchFlag} ${shellQuote(item.branch)}`,
+  ];
+}
+
+function formatPreviewSection(title, items, { includeCommands = false } = {}) {
+  if (items.length === 0) {
+    return [title, "- none"];
   }
 
+  const lines = [title];
+
+  for (const item of items) {
+    lines.push(`- ${formatWorktreeSummary(item)}: ${item.reason}`);
+
+    if (includeCommands && item.branch) {
+      lines.push(...formatCopyPasteCommands(item));
+    }
+  }
+
+  return lines;
+}
+
+function formatPreview(grouped, defaultBranch) {
   return [
-    `Merged worktrees ready for cleanup against ${defaultBranch}:`,
-    ...candidates.map(
-      (candidate) =>
-        `- ${candidate.branch} -> ${candidate.path}${candidate.head ? ` (${candidate.head.slice(0, 12)})` : ""}`,
-    ),
+    `Worktrees connected to this repository against ${defaultBranch}:`,
+    "",
+    ...formatPreviewSection("Safe to clean automatically:", grouped.safe, { includeCommands: true }),
     "",
-    "Run `/wt-clean apply` to remove these worktrees and delete their local branches.",
+    ...formatPreviewSection("Needs review before cleanup:", grouped.review, { includeCommands: true }),
+    "",
+    ...formatPreviewSection("Not cleanable here:", grouped.blocked),
+    "",
+    "Run `/wt-clean apply` to remove only the safe group.",
+    "Run `/wt-clean apply <branch-or-path>` to also remove selected review items.",
   ].join("\n");
 }
 
-function formatCleanupSummary(defaultBranch, removed, failed) {
-  const lines = [`Cleaned worktrees merged into ${defaultBranch}:`];
+function formatCleanupSummary(defaultBranch, removed, failed, requestedSelectors) {
+  const lines = [`Cleaned worktrees relative to ${defaultBranch}:`];
 
   if (removed.length === 0) {
     lines.push("- none removed");
   } else {
     for (const item of removed) {
-      lines.push(`- removed ${item.branch} -> ${item.path}`);
+      const modeLabel = item.selected ? "selected" : "auto";
+      lines.push(`- removed (${modeLabel}) ${item.branch} -> ${item.path}`);
+    }
+  }
+
+  if (requestedSelectors.length > 0) {
+    lines.push("");
+    lines.push("Requested selectors:");
+    for (const selector of requestedSelectors) {
+      lines.push(`- ${selector}`);
     }
   }
 
@@ -146,13 +187,166 @@ function formatCleanupSummary(defaultBranch, removed, failed) {
     lines.push("");
     lines.push("Cleanup skipped for:");
     for (const item of failed) {
-      lines.push(`- ${item.branch} -> ${item.path}: ${item.reason}`);
+      lines.push(`- ${item.branch || item.selector} -> ${item.path || "(no path)"}: ${item.reason}`);
     }
   }
 
   return lines.join("\n");
 }
 
+function splitCleanupToken(value) {
+  if (typeof value !== "string") {
+    return [];
+  }
+
+  return value
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function parseCleanupRawArguments(raw) {
+  const tokens = splitCleanupToken(raw);
+
+  if (tokens[0] === "apply") {
+    return {
+      mode: "apply",
+      selectors: tokens.slice(1),
+    };
+  }
+
+  if (tokens[0] === "preview") {
+    return {
+      mode: "preview",
+      selectors: tokens.slice(1),
+    };
+  }
+
+  return {
+    mode: null,
+    selectors: tokens,
+  };
+}
+
+function normalizeCleanupArgs(args, config) {
+  const selectors = Array.isArray(args.selectors) ? [...args.selectors] : [];
+  const normalizedSelectors = [];
+  const rawArgs = parseCleanupRawArguments(args.raw);
+  let explicitMode = rawArgs.mode;
+
+  if (rawArgs.selectors.length > 0) {
+    selectors.unshift(...rawArgs.selectors);
+  }
+
+  if (typeof args.mode === "string" && args.mode.trim()) {
+    const modeValue = args.mode.trim();
+    if (modeValue === "apply" || modeValue === "preview") {
+      explicitMode = modeValue;
+    } else {
+      selectors.unshift(...splitCleanupToken(modeValue));
+    }
+  }
+
+  for (const selector of selectors) {
+    if (typeof selector !== "string") {
+      continue;
+    }
+
+    if (selector.includes(" ")) {
+      normalizedSelectors.push(...splitCleanupToken(selector));
+      continue;
+    }
+
+    normalizedSelectors.push(selector);
+  }
+
+  const inlineApply = normalizedSelectors[0] === "apply";
+
+  if (inlineApply) {
+    normalizedSelectors.shift();
+  }
+
+  const mode = explicitMode === "apply" || inlineApply ? "apply" : explicitMode || config.cleanupMode;
+
+  return {
+    mode,
+    selectors: normalizedSelectors,
+  };
+}
+
+export const __internal = {
+  parseCleanupRawArguments,
+  normalizeCleanupArgs,
+};
+
+function selectorMatches(item, selector) {
+  const normalized = path.resolve(selector);
+  return item.branch === selector || item.path === normalized;
+}
+
+function classifyEntry(entry, repoRoot, activeWorktree, protectedBranches, mergedIntoBase) {
+  const entryPath = path.resolve(entry.path);
+  const branchName = entry.branch;
+  const item = {
+    branch: branchName,
+    path: entryPath,
+    head: entry.head,
+    detached: Boolean(entry.detached),
+  };
+
+  if (!branchName || entry.detached) {
+    return {
+      ...item,
+      status: "blocked",
+      reason: !branchName ? "no branch" : "detached HEAD",
+      selectable: false,
+    };
+  }
+
+  if (entryPath === path.resolve(repoRoot)) {
+    return {
+      ...item,
+      status: "blocked",
+      reason: entryPath === activeWorktree ? "repository root, current worktree, protected branch" : "repository root",
+      selectable: false,
+    };
+  }
+
+  if (entryPath === activeWorktree) {
+    return {
+      ...item,
+      status: "blocked",
+      reason: "current worktree",
+      selectable: false,
+    };
+  }
+
+  if (protectedBranches.has(branchName)) {
+    return {
+      ...item,
+      status: "blocked",
+      reason: "protected branch",
+      selectable: false,
+    };
+  }
+
+  if (mergedIntoBase) {
+    return {
+      ...item,
+      status: "safe",
+      reason: "merged into base branch by git ancestry",
+      selectable: true,
+    };
+  }
+
+  return {
+    ...item,
+    status: "review",
+    reason: "not merged into base branch by git ancestry",
+    selectable: true,
+  };
+}
+
 export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
   async function git(args, options = {}) {
     const cwd = options.cwd ?? directory;
@@ -194,6 +388,7 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
     return {
       branchPrefix: normalizeBranchPrefix(merged.branchPrefix ?? DEFAULTS.branchPrefix),
       remote: merged.remote || DEFAULTS.remote,
+      baseBranch: typeof merged.baseBranch === "string" && merged.baseBranch.trim() ? merged.baseBranch.trim() : null,
       cleanupMode: merged.cleanupMode === "apply" ? "apply" : DEFAULTS.cleanupMode,
       protectedBranches: Array.isArray(merged.protectedBranches)
         ? merged.protectedBranches.filter((value) => typeof value === "string")
@@ -254,16 +449,20 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
     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 });
+  async function resolveBaseBranch(repoRoot, remote, configuredBaseBranch) {
+    return configuredBaseBranch || getDefaultBranch(repoRoot, remote);
+  }
+
+  async function getBaseRef(repoRoot, remote, baseBranch) {
+    await git(["fetch", "--prune", remote, baseBranch], { cwd: repoRoot });
 
-    const remoteRef = `refs/remotes/${remote}/${defaultBranch}`;
+    const remoteRef = `refs/remotes/${remote}/${baseBranch}`;
     const remoteExists = await git(["show-ref", "--verify", "--quiet", remoteRef], {
       cwd: repoRoot,
       allowFailure: true,
     });
 
-    return remoteExists.exitCode === 0 ? `${remote}/${defaultBranch}` : defaultBranch;
+    return remoteExists.exitCode === 0 ? `${remote}/${baseBranch}` : baseBranch;
   }
 
   async function ensureBranchDoesNotExist(repoRoot, branchName) {
@@ -290,7 +489,8 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
           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 baseBranch = await resolveBaseBranch(repoRoot, config.remote, config.baseBranch);
+          const baseRef = await getBaseRef(repoRoot, config.remote, baseBranch);
           const baseCommit = (await git(["rev-parse", baseRef], { cwd: repoRoot })).stdout;
           const slug = slugifyTitle(args.title);
 
@@ -315,7 +515,7 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
           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.`,
+              `New branch ${branchName} does not match ${baseBranch} at ${baseCommit}. Found ${branchCommit} instead.`,
             );
           }
 
@@ -324,71 +524,113 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             `- branch: ${branchName}`,
             `- worktree: ${worktreePath}`,
             `- default branch: ${defaultBranch}`,
+            `- base branch: ${baseBranch}`,
             `- base ref: ${baseRef}`,
             `- base commit: ${baseCommit}`,
           ].join("\n");
         },
       }),
       worktree_cleanup: tool({
-        description: "Preview or clean merged git worktrees",
+        description: "Preview or clean git worktrees",
         args: {
-          mode: tool.schema
-            .enum(["preview", "apply"])
-            .default("preview")
-            .describe("Preview cleanup candidates or remove them"),
+          mode: tool.schema.string().optional().describe("Preview cleanup candidates or remove them"),
+          raw: tool.schema.string().optional().describe("Raw cleanup arguments from slash commands"),
+          selectors: tool.schema
+            .array(tool.schema.string())
+            .default([])
+            .describe("Optional branch names or worktree paths to remove explicitly"),
         },
         async execute(args, context) {
-          context.metadata({ title: `Clean worktrees (${args.mode})` });
-
           const repoRoot = await getRepoRoot();
           const config = await loadWorkflowConfig(repoRoot);
+          const normalizedArgs = normalizeCleanupArgs(args, config);
+
+          context.metadata({ title: `Clean worktrees (${normalizedArgs.mode})` });
+
           const defaultBranch = await getDefaultBranch(repoRoot, config.remote);
-          const baseRef = await getBaseRef(repoRoot, config.remote, defaultBranch);
+          const baseBranch = await resolveBaseBranch(repoRoot, config.remote, config.baseBranch);
+          const baseRef = await getBaseRef(repoRoot, config.remote, baseBranch);
           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 = [];
+          const protectedBranches = new Set([defaultBranch, baseBranch, ...config.protectedBranches]);
+          const grouped = {
+            safe: [],
+            review: [],
+            blocked: [],
+          };
 
           for (const entry of entries) {
-            const entryPath = path.resolve(entry.path);
             const branchName = entry.branch;
+            let mergedIntoBase = false;
 
-            if (!branchName || entry.detached) {
-              continue;
+            if (branchName && !entry.detached) {
+              const merged = await git(["merge-base", "--is-ancestor", branchName, baseRef], {
+                cwd: repoRoot,
+                allowFailure: true,
+              });
+
+              mergedIntoBase = merged.exitCode === 0;
             }
 
-            if (entryPath === path.resolve(repoRoot) || entryPath === activeWorktree) {
+            const classified = classifyEntry(
+              entry,
+              repoRoot,
+              activeWorktree,
+              protectedBranches,
+              mergedIntoBase,
+            );
+
+            grouped[classified.status].push(classified);
+          }
+
+          if (normalizedArgs.mode !== "apply") {
+            return formatPreview(grouped, baseBranch);
+          }
+
+          const requestedSelectors = [...new Set(normalizedArgs.selectors || [])];
+          const selected = [];
+          const failed = [];
+
+          for (const selector of requestedSelectors) {
+            const match = [...grouped.safe, ...grouped.review, ...grouped.blocked].find((item) =>
+              selectorMatches(item, selector),
+            );
+
+            if (!match) {
+              failed.push({
+                selector,
+                reason: "selector did not match any connected worktree",
+              });
               continue;
             }
 
-            if (protectedBranches.has(branchName)) {
+            if (!match.selectable) {
+              failed.push({
+                ...match,
+                selector,
+                reason: `cannot remove via selector: ${match.reason}`,
+              });
               continue;
             }
 
-            const merged = await git(["merge-base", "--is-ancestor", branchName, baseRef], {
-              cwd: repoRoot,
-              allowFailure: true,
-            });
+            selected.push(match);
+          }
+
+          const targets = [...grouped.safe];
 
-            if (merged.exitCode === 0) {
-              candidates.push({
-                branch: branchName,
-                path: entryPath,
-                head: entry.head,
+          for (const item of selected) {
+            if (!targets.some((target) => target.path === item.path)) {
+              targets.push({
+                ...item,
+                selected: true,
               });
             }
           }
 
-          const requestedMode = args.mode || config.cleanupMode;
-          if (requestedMode !== "apply") {
-            return formatPreview(candidates, defaultBranch);
-          }
-
           const removed = [];
-          const failed = [];
 
-          for (const candidate of candidates) {
+          for (const candidate of targets) {
             const removeWorktree = await git(["worktree", "remove", candidate.path], {
               cwd: repoRoot,
               allowFailure: true,
@@ -402,10 +644,13 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
               continue;
             }
 
-            const deleteBranch = await git(["branch", "-d", candidate.branch], {
-              cwd: repoRoot,
-              allowFailure: true,
-            });
+            const deleteBranch = await git(
+              ["branch", candidate.status === "safe" ? "-d" : "-D", candidate.branch],
+              {
+                cwd: repoRoot,
+                allowFailure: true,
+              },
+            );
 
             if (deleteBranch.exitCode !== 0) {
               failed.push({
@@ -423,7 +668,7 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             allowFailure: true,
           });
 
-          return formatCleanupSummary(defaultBranch, removed, failed);
+          return formatCleanupSummary(baseBranch, removed, failed, requestedSelectors);
         },
       }),
     },