@sven1103/opencode-worktree-workflow 0.6.1 → 0.6.2

package/README.md

@@ -42,6 +42,11 @@ In practice:
 - if the native tools are unavailable, use the local CLI fallback from the same installed package
 - if the package is not installed, no CLI fallback is available
 
+Important distinction:
+
+- `worktree_prepare` and `worktree_cleanup` are native OpenCode tools, not shell commands
+- from a terminal, use `npx opencode-worktree-workflow ...` or `./node_modules/.bin/opencode-worktree-workflow ...`
+
 ## Install in an OpenCode project
 
 Add the package as a project dependency, following the official docs style:
@@ -145,9 +150,11 @@ If your setup uses installed skill files, copy the released `SKILL.md` into a `w
 
 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.
+
 ## Structured contract
 
-The native tool results and CLI `--json` output now use a versioned structured contract with a `schema_version` field.
+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.
 
 - current `schema_version`: `1.0.0`
 - contract overview: `docs/contract.md`
@@ -163,21 +170,33 @@ Human-readable output remains available through the result `message`, but caller
 
 The npm package also exposes a local CLI so agents can fall back to the same installed package when the native plugin tools are unavailable.
 
+Use the CLI from a terminal when you want to run the workflow manually. Run it inside a real git repository. By default, the workflow expects a normal remote and base-branch setup such as `origin` plus the repository default branch, unless you override that in `.opencode/worktree-workflow.json`.
+
 Examples:
 
 ```sh
+npx opencode-worktree-workflow --help
+npx opencode-worktree-workflow wt-clean --help
 npx opencode-worktree-workflow wt-new "Improve checkout retry logic"
 npx opencode-worktree-workflow wt-new "Improve checkout retry logic" --json
 npx opencode-worktree-workflow wt-clean preview
 npx opencode-worktree-workflow wt-clean apply feature/foo --json
 ```
 
+Direct local bin examples:
+
+```sh
+./node_modules/.bin/opencode-worktree-workflow --help
+./node_modules/.bin/opencode-worktree-workflow wt-clean preview
+```
+
 Defaults:
 
 - human-readable output by default
 - structured output with `--json`
 - the CLI shares the same underlying implementation and result contract as the native tools
 - the CLI fallback depends on the package already being installed in the project
+- if you run it outside a git repo or without the expected remote context, the CLI returns an actionable error
 
 ## Compatibility model
 

package/package.json

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

package/src/cli.js

@@ -121,6 +121,15 @@ export async function run(argv = process.argv.slice(2)) {
   });
 
   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();
@@ -129,26 +138,20 @@ 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 },
-      { metadata() {}, worktree: process.cwd() },
-    );
+    result = await plugin.tool.worktree_prepare.execute({ title }, toolContext);
   } else if (command === "wt-clean") {
     const raw = rest.join(" ").trim();
-    result = await plugin.tool.worktree_cleanup.execute(
-      { raw, selectors: [] },
-      { metadata() {}, worktree: process.cwd() },
-    );
+    result = await plugin.tool.worktree_cleanup.execute({ raw, selectors: [] }, toolContext);
   } else {
     throw new Error(`Unknown command: ${command}`);
   }
 
   if (outputJson) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify(structuredResult ?? { ok: true, message: result }, null, 2)}\n`);
     return;
   }
 
-  process.stdout.write(`${result.message || JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`${result}\n`);
 }
 
 export function isInvokedAsScript(argvPath = process.argv[1]) {

package/src/index.js

@@ -261,6 +261,16 @@ function buildPrepareResult({ title, branch, worktreePath, defaultBranch, baseBr
   };
 }
 
+function publishStructuredResult(context, result) {
+  context.metadata({
+    metadata: {
+      result,
+    },
+  });
+
+  return result.message || JSON.stringify(result, null, 2);
+}
+
 function buildCleanupPreviewResult({ defaultBranch, baseBranch, baseRef, grouped }) {
   const structuredGroups = {
     safe: grouped.safe.map(toStructuredCleanupItem),
@@ -662,15 +672,18 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             );
           }
 
-          return buildPrepareResult({
-            title: args.title,
-            branch: branchName,
-            worktreePath,
-            defaultBranch,
-            baseBranch,
-            baseRef,
-            baseCommit,
-          });
+          return publishStructuredResult(
+            context,
+            buildPrepareResult({
+              title: args.title,
+              branch: branchName,
+              worktreePath,
+              defaultBranch,
+              baseBranch,
+              baseRef,
+              baseCommit,
+            }),
+          );
         },
       }),
       worktree_cleanup: tool({
@@ -726,12 +739,15 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
           }
 
           if (normalizedArgs.mode !== "apply") {
-            return buildCleanupPreviewResult({
-              defaultBranch,
-              baseBranch,
-              baseRef,
-              grouped,
-            });
+            return publishStructuredResult(
+              context,
+              buildCleanupPreviewResult({
+                defaultBranch,
+                baseBranch,
+                baseRef,
+                grouped,
+              }),
+            );
           }
 
           const requestedSelectors = [...new Set(normalizedArgs.selectors || [])];
@@ -818,14 +834,17 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
             allowFailure: true,
           });
 
-          return buildCleanupApplyResult({
-            defaultBranch,
-            baseBranch,
-            baseRef,
-            removed,
-            failed,
-            requestedSelectors,
-          });
+          return publishStructuredResult(
+            context,
+            buildCleanupApplyResult({
+              defaultBranch,
+              baseBranch,
+              baseRef,
+              removed,
+              failed,
+              requestedSelectors,
+            }),
+          );
         },
       }),
     },