opencode-gitwt 0.2.1 → 0.3.0

package/README.md

@@ -3,19 +3,22 @@
 OpenCode adapter for `gitwt`. It exposes the shared worktree core as agent tools:
 https://github.com/voischev/gitwt
 
-Requires Node.js 22.14+ and Git. Supports OpenCode 1.19.3–<2.
+Requires Node.js 22.14+ and Git. Supports OpenCode V1 (1.19.3+) and V2 (2.2.5+).
 
 ## Use in OpenCode
 
-Add the plugin to your project's `opencode.json`, then restart OpenCode:
+For **OpenCode V2**, add to your project's `opencode.json`:
 
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-gitwt@latest"]
+  "plugins": ["opencode-gitwt@latest"]
 }
 ```
 
+For **V1**, use `"plugin": ["opencode-gitwt@latest"]` instead. Restart OpenCode
+after installation. Both versions expose the same four gitwt tools.
+
 Ask the agent in chat, for example:
 
 > Create a worktree on branch feature/login from main, fix the login issue there,
@@ -43,3 +46,23 @@ and `~/.config/gitwt/config.json` globally. Options include `remote`, `base`,
 
 For the standalone `gitwt` command, run `npm install -g @voischev/gitwt`.
 Move existing settings to these paths and remove comments and trailing commas.
+
+## Why use it with OpenCode V2?
+
+V2 already has native worktree tools, setup commands, and session moves.
+Use gitwt when you want:
+
+- **One workflow across agents:** the same standalone CLI, Node API, and JSON
+  contract in OpenCode, Codex, Claude Code, and scripts.
+- **Named branches from a fresh remote base:** gitwt fetches the selected base
+  and verifies path, branch, and commit before setup. V2's built-in Git strategy
+  creates a detached checkout from a local ref or HEAD, without fetching.
+- **Per-worktree lifecycle hooks:** saved `postCreate` and `preRemove` commands;
+  teardown failure blocks removal through gitwt, even with `--force`.
+
+Prefer native V2 features for integrated UI navigation and actual session moves.
+Native removal does not run gitwt's teardown hooks: remove gitwt-managed copies
+through `gitwt_remove` or the CLI when those hooks matter.
+
+Comparison verified against OpenCode V2.2.5's built-in Git strategy:
+https://github.com/anomalyco/opencode/blob/v2.2.5/packages/core/src/worktree.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-gitwt",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Git worktree tools for OpenCode, powered by gitwt",
   "type": "module",
   "main": "./src/index.js",
@@ -15,7 +15,7 @@
   ],
   "engines": {
     "node": ">=22.14.0",
-    "opencode": ">=1.19.3 <2"
+    "opencode": ">=1.19.3 <2 || >=2.2.5 <3"
   },
   "scripts": {
     "check": "biome check .",
@@ -23,8 +23,7 @@
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@voischev/gitwt": "^0.1.4",
-    "zod": "4.1.8"
+    "@voischev/gitwt": "^0.1.4"
   },
   "devDependencies": {
     "@biomejs/biome": "2.6.3"

package/src/index.js

@@ -1,69 +1,130 @@
-import { createWorktree, listWorktrees, removeWorktree, resolveWorktree } from "@voischev/gitwt";
-import { z } from "zod";
+import {
+  createWorktree,
+  GitwtError,
+  listWorktrees,
+  removeWorktree,
+  resolveWorktree,
+} from "@voischev/gitwt";
 
 export async function GitwtPlugin({ directory }, config = {}) {
-  return {
-    tool: {
-      gitwt_create: {
-        description:
-          "Create and verify a new worktree. Use worktreePath for commands and files in the current session. Keep the worktree when pausing or handing off a task.",
-        args: {
-          branch: z.string().describe("New branch name"),
-          base: z.string().optional().describe("Remote base branch"),
-          from: z
-            .string()
-            .optional()
-            .describe("Local ref or verified commit instead of a remote base"),
-          path: z.string().optional().describe("Destination path"),
-          noHooks: z.boolean().optional().describe("Disable hooks for this worktree"),
+  const tool = {
+    gitwt_create: {
+      description:
+        "Create and verify a new worktree. Use worktreePath for commands and files in the current session. Keep the worktree when pausing or handing off a task.",
+      args: {
+        branch: { type: "string", description: "New branch name" },
+        base: { type: "string", description: "Remote base branch" },
+        from: {
+          type: "string",
+          description: "Local ref or verified commit instead of a remote base",
         },
-        execute: async (args, ctx) =>
-          JSON.stringify(
-            await createWorktree(ctx.directory ?? directory, {
-              ...args,
-              signal: ctx.abort,
-              config: { ...config, base: args.base ?? config.base },
-            }),
-          ),
-      },
-      gitwt_list: {
-        description:
-          "List Git worktrees. With status, check dirty and available ahead/behind counts; null means unknown.",
-        args: { status: z.boolean().optional().describe("Check live worktree status") },
-        execute: async (args, ctx) =>
-          JSON.stringify(await listWorktrees(ctx.directory ?? directory, args)),
-      },
-      gitwt_cd: {
-        description:
-          "Resolve a branch or full path to a worktree with HEAD and status. Use worktreePath explicitly; this does not change the session directory.",
-        args: { target: z.string().describe("Exact branch name or full worktree path") },
-        execute: async ({ target }, ctx) =>
-          JSON.stringify(
-            await resolveWorktree(ctx.directory ?? directory, target, { status: true }),
-          ),
+        path: { type: "string", description: "Destination path" },
+        noHooks: { type: "boolean", description: "Disable hooks for this worktree" },
       },
-      gitwt_remove: {
-        description:
-          "Remove a worktree only when explicitly requested and no longer in use. Force discards local changes but does not bypass a failing preRemove hook.",
-        args: {
-          target: z.string().describe("Exact branch name or full worktree path"),
-          force: z.boolean().optional().describe("Allow discarding local changes"),
-          keepBranch: z
-            .boolean()
-            .optional()
-            .describe("Keep the branch after removing the worktree"),
-        },
-        execute: async ({ target, force, keepBranch }, ctx) =>
-          JSON.stringify(
-            await removeWorktree(ctx.directory ?? directory, target, {
-              force,
-              deleteBranch: !keepBranch,
-              signal: ctx.abort,
-            }),
-          ),
+      execute: async (args, ctx) =>
+        JSON.stringify(
+          await createWorktree(ctx.directory ?? directory, {
+            ...args,
+            signal: ctx.abort,
+            config: { ...config, base: args.base ?? config.base },
+          }),
+        ),
+    },
+    gitwt_list: {
+      description:
+        "List Git worktrees. With status, check dirty and available ahead/behind counts; null means unknown.",
+      args: { status: { type: "boolean", description: "Check live worktree status" } },
+      execute: async (args, ctx) =>
+        JSON.stringify(await listWorktrees(ctx.directory ?? directory, args)),
+    },
+    gitwt_cd: {
+      description:
+        "Resolve a branch or full path to a worktree with HEAD and status. Use worktreePath explicitly; this does not change the session directory.",
+      args: { target: { type: "string", description: "Exact branch name or full worktree path" } },
+      execute: async ({ target }, ctx) =>
+        JSON.stringify(await resolveWorktree(ctx.directory ?? directory, target, { status: true })),
+    },
+    gitwt_remove: {
+      description:
+        "Remove a worktree only when explicitly requested and no longer in use. Force discards local changes but does not bypass a failing preRemove hook.",
+      args: {
+        target: { type: "string", description: "Exact branch name or full worktree path" },
+        force: { type: "boolean", description: "Allow discarding local changes" },
+        keepBranch: { type: "boolean", description: "Keep the branch after removing the worktree" },
       },
+      execute: async ({ target, force, keepBranch }, ctx) =>
+        JSON.stringify(
+          await removeWorktree(ctx.directory ?? directory, target, {
+            force,
+            deleteBranch: !keepBranch,
+            signal: ctx.abort,
+          }),
+        ),
+    },
+  };
+  const required = {
+    gitwt_create: ["branch"],
+    gitwt_list: [],
+    gitwt_cd: ["target"],
+    gitwt_remove: ["target"],
+  };
+  for (const [id, definition] of Object.entries(tool)) {
+    const execute = definition.execute;
+    definition.execute = async (args, ctx) => {
+      if (!args || typeof args !== "object" || Array.isArray(args)) {
+        throw new GitwtError("invalid_arguments", `${id}: expected an argument object`);
+      }
+      for (const key of Object.keys(args)) {
+        if (!Object.hasOwn(definition.args, key)) {
+          throw new GitwtError("invalid_arguments", `${id}: unknown argument ${key}`);
+        }
+      }
+      for (const [key, schema] of Object.entries(definition.args)) {
+        if (args[key] === undefined && !required[id].includes(key)) continue;
+        if (typeof args[key] !== schema.type) {
+          throw new GitwtError("invalid_arguments", `${id}: ${key} must be ${schema.type}`);
+        }
+      }
+      return execute(args, ctx);
+    };
+  }
+  return {
+    tool,
+    "tool.definition": async ({ toolID }, output) => {
+      if (!Object.hasOwn(tool, toolID)) return;
+      output.jsonSchema = {
+        type: "object",
+        properties: tool[toolID].args,
+        required: required[toolID],
+        additionalProperties: false,
+      };
     },
   };
 }
 
-export default { id: "opencode-gitwt", server: GitwtPlugin };
+export default {
+  id: "opencode-gitwt",
+  server: GitwtPlugin,
+  async setup(ctx) {
+    const directory = ctx.location.directory;
+    const hooks = await GitwtPlugin({ directory }, ctx.options);
+    const definitions = [];
+    for (const [name, definition] of Object.entries(hooks.tool)) {
+      const output = {};
+      await hooks["tool.definition"]({ toolID: name }, output);
+      definitions.push({
+        name,
+        description: definition.description,
+        input: output.jsonSchema,
+        options: { codemode: false },
+        async execute(args, call) {
+          call.signal.throwIfAborted();
+          return { content: await definition.execute(args, { directory, abort: call.signal }) };
+        },
+      });
+    }
+    await ctx.tool.transform((editor) => {
+      for (const definition of definitions) editor.add(definition);
+    });
+  },
+};