@sven1103/opencode-worktree-workflow 0.6.3 → 1.0.0-alpha.1

package/README.md

@@ -12,6 +12,22 @@ To get the workflow running in a project:
 4. If you want policy guidance for when to isolate work, install the skill from [Co-shipped skill](#co-shipped-skill).
 5. If you need to understand how the local fallback works, see [CLI fallback](#cli-fallback).
 
+## Verify installation
+
+After setup, verify the surface you installed:
+
+- Plugin: confirm OpenCode exposes `worktree_prepare` and `worktree_cleanup`.
+- CLI: run `npx opencode-worktree-workflow --help`.
+- Slash commands: confirm `/wt-new <title>` and `/wt-clean` are available.
+
+Quick smoke check:
+
+```sh
+npx opencode-worktree-workflow wt-new "docs smoke check" --json
+```
+
+That should return a structured result with a `worktree_path`. For release verification before installing, see `docs/releases.md`.
+
 ## Recommended setup
 
 Install the package once:
@@ -146,12 +162,55 @@ If your setup uses installed skill files, copy the released `SKILL.md` into a `w
 ## What the plugin provides
 
 - `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
+- `worktree_cleanup`: preview connected worktrees against the configured base branch and, when explicitly applied, remove safe or selected review items
 
 This package now ships the plugin capability, a CLI fallback surface, thin slash commands, and a co-shipped policy skill.
 
 These native tools are exposed inside OpenCode after the plugin is loaded. They are not terminal commands.
 
+## Lifecycle hooks (determinism)
+
+If you use this plugin in autonomous agent tasks, the key feature is that it uses OpenCode lifecycle hooks to make workspace selection deterministic.
+
+Hooks implemented by the plugin:
+
+- `tool.execute.before`
+  - Enforces isolation for repo-mutating tools by ensuring a session-scoped active worktree exists (requires `sessionID`).
+  - Rewrites tool inputs so they operate inside the active worktree by default:
+    - `bash`: injects `workdir`/`cwd` when missing
+    - `glob`/`grep`: injects `path` when missing
+    - known path arguments are rewritten from repo-root paths into the bound `worktree_path`
+  - Blocks unsafe calls that cannot be rewritten safely (for example repo-root absolute paths in opaque arguments).
+  - For delegated `task` calls: requires the prompt to reference a safe handoff artifact path under `.opencode/sessions/<session>/handoffs/*.json`, then enriches that handoff with the active workspace context (`task_id`, `worktree_path`, `workspace_role`).
+
+- `tool.execute.after`
+  - Records tool usage for the session (used to keep runtime state and cleanup advice consistent across steps).
+  - After a delegated `task`, correlates the handoff with result artifacts to infer lifecycle transitions (complete/block) and persists them.
+  - When completion is detected, emits an advisory cleanup preview (non-fatal if it cannot be generated).
+
+- `experimental.chat.system.transform`
+  - Injects an "Active workspace context" block into the system prompt when an active worktree is bound, so agents and tools see the same worktree context every step.
+
+- `command.execute.before`
+  - Implements `/wt-new` and `/wt-clean` as thin prompt shims (it rewrites the command output parts so the agent calls `worktree_prepare` / `worktree_cleanup`).
+
+Net effect: once a `sessionID` is in play, the plugin keeps a stable session-to-worktree binding and consistently routes repository actions into that worktree. This removes prompt-only ambiguity ("did the agent remember to cd?") and is what makes the workflow reproducible.
+
+## Typical usage
+
+Most users only need one of these flows:
+
+1. Plugin only: use `worktree_prepare` and `worktree_cleanup` directly in OpenCode.
+2. Plugin plus slash commands: use `/wt-new <title>` to start isolated work and `/wt-clean` to preview cleanup.
+3. CLI fallback: use `npx opencode-worktree-workflow wt-new "<title>"` when native tools are unavailable.
+
+Typical manual flow:
+
+1. Create a worktree with `worktree_prepare`, `/wt-new <title>`, or `npx opencode-worktree-workflow wt-new "<title>"`.
+2. Do the task inside the returned `worktree_path`.
+3. Preview cleanup with `worktree_cleanup`, `/wt-clean`, or `npx opencode-worktree-workflow wt-clean preview`.
+4. Apply cleanup only when deletion is intentional.
+
 ## Structured contract
 
 The package now exposes a versioned structured contract with a `schema_version` field. Native tools return human-readable text and publish the structured result in tool metadata, while CLI `--json` prints the same structured object directly.
@@ -240,6 +299,20 @@ Supported settings:
 - `cleanupMode`: default cleanup behavior, either `preview` or `apply`
 - `protectedBranches`: branches that should never be auto-cleaned
 
+## Uninstall
+
+Remove only the surfaces you installed:
+
+- npm package: `npm remove @sven1103/opencode-worktree-workflow`
+- OpenCode plugin entry: remove `@sven1103/opencode-worktree-workflow` from `opencode.json`
+- Slash commands: delete `wt-new.md` and `wt-clean.md` from `.opencode/commands/` or `~/.config/opencode/commands/`
+- Skill: delete `SKILL.md` from your `worktree-workflow/` skill folder
+
+Optional cleanup:
+
+- remove `.opencode/worktree-workflow.json` if you created it only for this plugin
+- remove persisted runtime state from `OPENCODE_WORKTREE_STATE_DIR` or the platform default state directory if you no longer want stored task bindings
+
 ## Publish workflow
 
 This repo is prepared for npm publishing from GitHub Actions using npm trusted publishing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sven1103/opencode-worktree-workflow",
-  "version": "0.6.3",
+  "version": "1.0.0-alpha.1",
   "description": "OpenCode plugin for creating and cleaning up git worktrees.",
   "type": "module",
   "main": "./src/index.js",

package/src/cli.js

@@ -5,7 +5,8 @@ import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
-import { WorktreeWorkflowPlugin } from "./index.js";
+import { createWorktreeWorkflowService } from "./core/worktree-service.js";
+import { createRuntimeStateStore } from "./runtime/state-store.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -115,21 +116,26 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const plugin = await WorktreeWorkflowPlugin({
-    $: createShell(process.cwd()),
+  const shell = createShell(process.cwd());
+  const git = async (args, options = {}) => {
+    const cwd = options.cwd ?? process.cwd();
+    const command = `git ${args.map((arg) => shell.escape(String(arg))).join(" ")}`;
+    const result = await shell`${{ 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 };
+  };
+  const service = createWorktreeWorkflowService({
     directory: process.cwd(),
+    git,
+    stateStore: createRuntimeStateStore(),
   });
 
   let result;
   let structuredResult = null;
-  const toolContext = {
-    metadata(input) {
-      if (input?.metadata?.result) {
-        structuredResult = input.metadata.result;
-      }
-    },
-    worktree: process.cwd(),
-  };
 
   if (command === "wt-new") {
     const title = rest.join(" ").trim();
@@ -138,10 +144,12 @@ export async function run(argv = process.argv.slice(2)) {
       throw new Error("wt-new requires a descriptive title.");
     }
 
-    result = await plugin.tool.worktree_prepare.execute({ title }, toolContext);
+    structuredResult = await service.prepare({ title, sessionID: "cli" });
+    result = structuredResult.message;
   } else if (command === "wt-clean") {
     const raw = rest.join(" ").trim();
-    result = await plugin.tool.worktree_cleanup.execute({ raw, selectors: [] }, toolContext);
+    structuredResult = await service.cleanup({ raw, selectors: [], worktree: process.cwd(), sessionID: "cli" });
+    result = structuredResult.message;
   } else {
     throw new Error(`Unknown command: ${command}`);
   }

package/src/core/task-binding.js

@@ -0,0 +1,154 @@
+import path from "node:path";
+
+export function decideContinuity({ hasActiveTask = false, continuationSignal = false, distinctObjectiveSignal = false, alternativeRequested = false, ambiguous = false } = {}) {
+  if (!hasActiveTask) {
+    return { decision: "create-new", reason: "no-active-task" };
+  }
+
+  if (distinctObjectiveSignal || alternativeRequested) {
+    return { decision: "create-new", reason: alternativeRequested ? "alternative-requested" : "distinct-objective" };
+  }
+
+  if (ambiguous) {
+    return { decision: "ask-user", reason: "ambiguous-continuity" };
+  }
+
+  if (continuationSignal) {
+    return { decision: "reuse-active", reason: "clear-continuation" };
+  }
+
+  return { decision: "ask-user", reason: "insufficient-signal" };
+}
+
+export function inferTaskLifecycleTransition({ currentStatus = "inactive", explicitSignal = "none" } = {}) {
+  if (explicitSignal === "activate") return "active";
+  if (explicitSignal === "deactivate") return "inactive";
+  if (explicitSignal === "complete") return "completed";
+  if (explicitSignal === "block") return "blocked";
+  return currentStatus;
+}
+
+const READ_ONLY_TOOLS = new Set(["read", "glob", "grep", "webfetch"]);
+const WORKTREE_CONTROL_TOOLS = new Set(["worktree_prepare", "worktree_cleanup"]);
+const MUTATING_TOOLS = new Set(["write", "edit", "apply_patch"]);
+const WORKSPACE_ROLES = new Set(["planner", "implementer", "reviewer", "linear-flow"]);
+const READ_ONLY_GIT_COMMAND = /^\s*git\s+(status|diff|log|show|rev-parse|symbolic-ref|branch\s+--show-current|remote\s+show)\b/i;
+
+export function classifyToolExecution({ toolName, args = {} } = {}) {
+  const name = typeof toolName === "string" ? toolName : "";
+  if (WORKTREE_CONTROL_TOOLS.has(name)) return { requiresIsolation: false, bypass: true, kind: "worktree-control" };
+  if (READ_ONLY_TOOLS.has(name)) return { requiresIsolation: false, bypass: false, kind: "read-only" };
+  if (name === "task") return { requiresIsolation: true, bypass: false, kind: "delegation" };
+  if (MUTATING_TOOLS.has(name)) return { requiresIsolation: true, bypass: false, kind: "mutating" };
+  if (name === "bash") {
+    const command = typeof args.command === "string" ? args.command : "";
+    if (READ_ONLY_GIT_COMMAND.test(command)) return { requiresIsolation: false, bypass: false, kind: "read-only" };
+    return { requiresIsolation: true, bypass: false, kind: "mutating" };
+  }
+  return { requiresIsolation: true, bypass: false, kind: "unknown" };
+}
+
+export function deriveTaskTitle({ explicitTitle, toolName, args = {}, sessionID } = {}) {
+  if (typeof explicitTitle === "string" && explicitTitle.trim()) return explicitTitle.trim();
+  if (typeof args.title === "string" && args.title.trim()) return args.title.trim();
+  if (typeof args.prompt === "string" && args.prompt.trim()) return args.prompt.trim().slice(0, 80);
+  if (typeof args.description === "string" && args.description.trim()) return args.description.trim().slice(0, 80);
+  const shortID = typeof sessionID === "string" && sessionID ? sessionID.slice(0, 8) : "auto";
+  if (typeof toolName === "string" && toolName) return `${toolName}-${shortID}`;
+  return `task-${shortID}`;
+}
+
+export function deriveWorkspaceRole({ subagentType } = {}) {
+  if (typeof subagentType !== "string") return "linear-flow";
+  const normalized = subagentType.trim().toLowerCase();
+  return WORKSPACE_ROLES.has(normalized) ? normalized : "linear-flow";
+}
+
+export function extractHandoffArtifactPath(prompt) {
+  if (typeof prompt !== "string" || !prompt.trim()) return null;
+  const match = prompt.match(/(?:^|\s)(\/?[^\s]*\.opencode\/sessions\/[A-Za-z0-9_-]+\/handoffs\/[A-Za-z0-9._-]+\.json)(?:\s|$)/);
+  return match?.[1] ?? null;
+}
+
+export function buildWorkspaceContext({ task, workspaceRole } = {}) {
+  return {
+    task_id: task?.task_id ?? null,
+    task_title: task?.title ?? null,
+    worktree_path: task?.worktree_path ?? null,
+    workspace_role: workspaceRole || "linear-flow",
+    lifecycle_state: task?.status ?? "active",
+  };
+}
+
+const REWRITE_POLICIES = {
+  read: { pathArgKeys: ["filePath"], opaqueArgKeys: [] },
+  write: { pathArgKeys: ["filePath"], opaqueArgKeys: [] },
+  edit: { pathArgKeys: ["filePath"], opaqueArgKeys: [] },
+  glob: { pathArgKeys: ["path"], opaqueArgKeys: [] },
+  grep: { pathArgKeys: ["path"], opaqueArgKeys: [] },
+  bash: { pathArgKeys: ["workdir", "cwd"], opaqueArgKeys: ["command"] },
+  apply_patch: { pathArgKeys: [], opaqueArgKeys: ["patchText"] },
+};
+
+export function getToolRewritePolicy({ toolName } = {}) {
+  return REWRITE_POLICIES[toolName] || { pathArgKeys: [], opaqueArgKeys: [] };
+}
+
+function isInsideRepoRoot(candidatePath, repoRoot) {
+  const relative = path.relative(repoRoot, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isInsideWorktree(candidatePath, worktreePath) {
+  const relative = path.relative(worktreePath, candidatePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function rewriteRepoScopedPathIntoWorktree({ value, repoRoot, worktreePath } = {}) {
+  if (typeof value !== "string" || !value.trim()) return value;
+  const normalizedRepoRoot = path.resolve(repoRoot);
+  const normalizedWorktreePath = path.resolve(worktreePath);
+  if (!path.isAbsolute(value)) return path.join(normalizedWorktreePath, value);
+  const resolvedValue = path.resolve(value);
+  if (isInsideWorktree(resolvedValue, normalizedWorktreePath)) return resolvedValue;
+  if (!isInsideRepoRoot(resolvedValue, normalizedRepoRoot)) return value;
+  const relative = path.relative(normalizedRepoRoot, resolvedValue);
+  return relative ? path.join(normalizedWorktreePath, relative) : normalizedWorktreePath;
+}
+
+function isBoundaryChar(char) {
+  if (!char) return true;
+  return /[\s"'`()[\]{}<>,:;=]/.test(char) || char === "/" || char === "\\";
+}
+
+export function hasOpaqueRepoRootAbsoluteReference({ value, repoRoot } = {}) {
+  if (typeof value !== "string" || !value) return false;
+  const normalizedRepoRoot = path.resolve(repoRoot).replaceAll("\\", "/");
+  const normalizedValue = value.replaceAll("\\", "/");
+  let index = normalizedValue.indexOf(normalizedRepoRoot);
+  while (index !== -1) {
+    const before = index > 0 ? normalizedValue[index - 1] : "";
+    const after = normalizedValue[index + normalizedRepoRoot.length] || "";
+    if (isBoundaryChar(before) && isBoundaryChar(after)) return true;
+    index = normalizedValue.indexOf(normalizedRepoRoot, index + 1);
+  }
+  return false;
+}
+
+export function buildWtNewCommandPromptParts(argumentsText = "") {
+  const title = typeof argumentsText === "string" ? argumentsText.trim() : "";
+  if (!title) {
+    return [{ type: "text", text: "Usage: /wt-new <title>\nExample: /wt-new improve checkout retry logic" }];
+  }
+  return [
+    {
+      type: "text",
+      text: `Call worktree_prepare with ${JSON.stringify({ title })}. Return the tool result and treat its worktree_path as the active workspace for follow-up work.`,
+    },
+  ];
+}
+
+export function buildWtCleanCommandPromptParts(argumentsText = "") {
+  const raw = typeof argumentsText === "string" ? argumentsText : "";
+  return [{ type: "text", text: `Call worktree_cleanup with ${JSON.stringify({ raw })}. Return the tool result.` }];
+}