@sven1103/opencode-worktree-workflow 0.6.0 → 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.0",
+  "version": "0.6.2",
   "description": "OpenCode plugin for creating and cleaning up git worktrees.",
   "type": "module",
   "main": "./src/index.js",

package/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { execFile } from "node:child_process";
+import fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
@@ -68,6 +69,31 @@ function printUsage() {
   );
 }
 
+function printSubcommandUsage(command) {
+  if (command === "wt-new") {
+    process.stdout.write(
+      [
+        "Usage:",
+        "  opencode-worktree-workflow wt-new <title> [--json]",
+        "",
+        "Create a synced worktree and branch from the configured base branch.",
+      ].join("\n") + "\n",
+    );
+    return;
+  }
+
+  if (command === "wt-clean") {
+    process.stdout.write(
+      [
+        "Usage:",
+        "  opencode-worktree-workflow wt-clean [preview|apply] [selectors...] [--json]",
+        "",
+        "Preview connected worktrees or remove safe and explicitly selected review worktrees.",
+      ].join("\n") + "\n",
+    );
+  }
+}
+
 export function parseCliArgs(argv) {
   const outputJson = argv.includes("--json");
   const args = argv.filter((arg) => arg !== "--json");
@@ -84,12 +110,26 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
+  if ((command === "wt-new" || command === "wt-clean") && rest.some((arg) => arg === "--help" || arg === "-h" || arg === "help")) {
+    printSubcommandUsage(command);
+    return;
+  }
+
   const plugin = await WorktreeWorkflowPlugin({
     $: createShell(process.cwd()),
     directory: process.cwd(),
   });
 
   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();
@@ -98,29 +138,35 @@ 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]) {
+  if (!argvPath) {
+    return false;
+  }
+
+  try {
+    return fs.realpathSync(argvPath) === fileURLToPath(import.meta.url);
+  } catch {
+    return fileURLToPath(import.meta.url) === argvPath;
+  }
 }
 
-const invokedAsScript = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+const invokedAsScript = isInvokedAsScript();
 
 if (invokedAsScript) {
   run().catch((error) => {

package/src/index.js

@@ -24,6 +24,14 @@ async function pathExists(targetPath) {
   }
 }
 
+function isMissingGitRepositoryError(message) {
+  return /not a git repository/i.test(message);
+}
+
+function isMissingRemoteError(message, remote) {
+  return new RegExp(`No such remote:?\s+${remote}|does not appear to be a git repository|Could not read from remote repository`, "i").test(message);
+}
+
 async function readJsonFile(filePath) {
   if (!(await pathExists(filePath))) {
     return null;
@@ -253,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),
@@ -376,6 +394,8 @@ export const __internal = {
   buildCleanupPreviewResult,
   buildPrepareResult,
   classifyEntry,
+  isMissingGitRepositoryError,
+  isMissingRemoteError,
   parseCleanupRawArguments,
   normalizeCleanupArgs,
   toStructuredCleanupFailure,
@@ -470,8 +490,18 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
   }
 
   async function getRepoRoot() {
-    const result = await git(["rev-parse", "--show-toplevel"]);
-    return result.stdout;
+    try {
+      const result = await git(["rev-parse", "--show-toplevel"]);
+      return result.stdout;
+    } catch (error) {
+      if (isMissingGitRepositoryError(error.message || "")) {
+        throw new Error(
+          "This command must run inside a git repository. Initialize a repository first or run it from an existing repo root.",
+        );
+      }
+
+      throw error;
+    }
   }
 
   async function loadWorkflowConfig(repoRoot) {
@@ -557,7 +587,17 @@ export const WorktreeWorkflowPlugin = async ({ $, directory }) => {
   }
 
   async function getBaseRef(repoRoot, remote, baseBranch) {
-    await git(["fetch", "--prune", remote, baseBranch], { cwd: repoRoot });
+    try {
+      await git(["fetch", "--prune", remote, baseBranch], { cwd: repoRoot });
+    } catch (error) {
+      if (isMissingRemoteError(error.message || "", remote)) {
+        throw new Error(
+          `Could not fetch base branch information from remote \"${remote}\". Configure the expected remote in .opencode/worktree-workflow.json or add that remote to this repository.`,
+        );
+      }
+
+      throw error;
+    }
 
     const remoteRef = `refs/remotes/${remote}/${baseBranch}`;
     const remoteExists = await git(["show-ref", "--verify", "--quiet", remoteRef], {
@@ -632,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({
@@ -696,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 || [])];
@@ -788,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,
+            }),
+          );
         },
       }),
     },