@sven1103/opencode-worktree-workflow 0.2.0 → 0.4.0

package/README.md

@@ -4,7 +4,17 @@
 
 ## Install in an OpenCode project
 
-Add the plugin package to your project config:
+Add the package as a project dependency, following the official docs style:
+
+```json
+{
+  "dependencies": {
+    "@sven1103/opencode-worktree-workflow": "^0.2.0"
+  }
+}
+```
+
+Then reference the installed package from your OpenCode config:
 
 ```json
 {
@@ -13,13 +23,20 @@ Add the plugin package to your project config:
 }
 ```
 
-OpenCode installs npm plugins with Bun when it starts.
+Keeping the npm dependency in `package.json` makes the installation more durable even if shared `opencode.json` bundles overwrite plugin entries.
+
+If you do not already install dependencies in your project, you can add the package directly with npm:
+
+```sh
+npm install @sven1103/opencode-worktree-workflow
+```
 
 ## Install slash commands
 
 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):
 
@@ -61,7 +78,7 @@ 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_cleanup`: preview all connected worktrees, 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.
 
@@ -74,7 +91,7 @@ You can override the defaults in `opencode.json`, `opencode.jsonc`, or `.opencod
   "worktreeWorkflow": {
     "branchPrefix": "wt/",
     "remote": "origin",
-    "worktreeRoot": "../.worktrees/$REPO",
+    "worktreeRoot": ".worktrees/$REPO",
     "cleanupMode": "preview",
     "protectedBranches": ["release"]
   }
@@ -93,6 +110,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.
@@ -101,7 +120,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.2.0",
+  "version": "0.4.0",
   "description": "OpenCode plugin for creating and cleaning up git worktrees.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -7,7 +7,7 @@ import { tool } from "@opencode-ai/plugin";
 const DEFAULTS = {
   branchPrefix: "wt/",
   remote: "origin",
-  worktreeRoot: "../.worktrees/$REPO",
+  worktreeRoot: ".worktrees/$REPO",
   cleanupMode: "preview",
   protectedBranches: [],
 };
@@ -111,34 +111,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 +186,81 @@ 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 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 default branch by git ancestry",
+      selectable: true,
+    };
+  }
+
+  return {
+    ...item,
+    status: "review",
+    reason: "not merged into default branch by git ancestry",
+    selectable: true,
+  };
+}
+
 export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
   async function git(args, options = {}) {
     const cwd = options.cwd ?? directory;
@@ -330,12 +438,16 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
         },
       }),
       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"),
+          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})` });
@@ -348,47 +460,84 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
           const worktreeList = await git(["worktree", "list", "--porcelain"], { cwd: repoRoot });
           const entries = parseWorktreeList(worktreeList.stdout);
           const protectedBranches = new Set([defaultBranch, ...config.protectedBranches]);
-          const candidates = [];
+          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);
+          }
+
+          const requestedMode = args.mode || config.cleanupMode;
+          if (requestedMode !== "apply") {
+            return formatPreview(grouped, defaultBranch);
+          }
+
+          const requestedSelectors = [...new Set(args.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);
+          }
 
-            if (merged.exitCode === 0) {
-              candidates.push({
-                branch: branchName,
-                path: entryPath,
-                head: entry.head,
+          const targets = [...grouped.safe];
+
+          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 +551,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 +575,7 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             allowFailure: true,
           });
 
-          return formatCleanupSummary(defaultBranch, removed, failed);
+          return formatCleanupSummary(defaultBranch, removed, failed, requestedSelectors);
         },
       }),
     },