greview-cli 0.12.4 → 0.13.0

package/README.md

@@ -8,12 +8,18 @@ Read and reply to review comments attached to local Git diffs.
 npm install --global greview-cli
 ```
 
-The npm package is named `greview-cli`; it installs the `greview` command.
+The npm package is named `greview-cli`; it installs the `greview` command. Run
+the guided setup to install the VS Code extension, agent skill, or both:
 
-Install the companion agent skill:
+```sh
+greview setup
+```
+
+Install one component directly:
 
 ```sh
-greview install-skill
+greview setup skill
+greview setup extension
 ```
 
 ## Quick start

package/dist/cli.js

@@ -4,6 +4,7 @@
 import { parseArgs } from "node:util";
 import { readFileSync as readFileSync2 } from "node:fs";
 import { spawn, spawnSync as spawnSync2 } from "node:child_process";
+import { createInterface } from "node:readline/promises";
 
 // src/anchor.ts
 function splitLines(text) {
@@ -510,6 +511,393 @@ var Store = class {
   }
 };
 
+// src/help.ts
+var SKILL_URL = "https://github.com/YouXam/greview/tree/main/skills/greview";
+function globalHelp(version) {
+  return `greview ${version} - review local Git diffs with humans and coding agents
+
+Usage:
+  greview <command> [options]
+  greview help <command>
+
+Review threads:
+  list                     List open threads
+  show <id>                Show a thread, its comments, and current location
+  add                      Start a thread on a line range
+  reply <id>               Reply to a thread
+  edit <comment-id>        Edit a comment
+  resolve <id>             Resolve a thread
+  unresolve <id>           Reopen a thread
+  rm <id>                  Delete a thread
+
+Repository:
+  sync                     Re-anchor all threads
+  stats                    Show thread counts
+  repo                     Show repository details
+
+Setup and integrations:
+  setup [skill|extension]  Install greview components
+  onsubmit <command>       Manage review submission hooks
+
+Help:
+  help [command]           Show global or command-specific help
+  version                  Print the greview version
+
+Global options:
+  --cwd <dir>              Run as if started in this directory
+  --json                   Emit {"ok":true,"data":...} responses
+  -h, --help               Show help for the selected command
+  -v, --version            Print the greview version
+
+Agent skill:
+  Guide:   ${SKILL_URL}
+  Install: greview setup skill
+  Direct:  npx --yes skills add YouXam/greview --skill greview
+
+Run \`greview help <command>\` for command options and examples.
+`;
+}
+var HELP = {
+  list: `Usage:
+  greview list [options]
+
+List review threads, freshly re-anchored against the current repository state.
+Open threads are shown by default, with changed or orphaned threads first.
+
+Options:
+  --all                    Include open and resolved threads
+  --resolved               Show only resolved threads
+  --file <path>            Restrict results to one file
+  --target <target>        Restrict to worktree, index, or head
+  --events                 Include event history in JSON output
+  --no-sync                Use the last recorded locations
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Examples:
+  greview list
+  greview list --file src/api.ts --json
+  greview list --resolved --no-sync
+`,
+  show: `Usage:
+  greview show <thread-id> [options]
+
+Show one thread with its comments, original anchor, current region, drift notes,
+and event history. The thread is re-anchored before display by default.
+
+Options:
+  --no-sync                Use the last recorded location
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Examples:
+  greview show 3
+  greview show 3 --json
+`,
+  add: `Usage:
+  greview add --file <path> --line <n|n-m> -m <text> [options]
+
+Start a review thread on lines in a local Git diff.
+
+Required:
+  --file <path>            Repository-relative or local file path
+  --line <n|n-m>           One line or an inclusive line range
+  -m, --message <text>     Comment text; use - to read stdin
+
+Options:
+  --side <side>            new or old (default: new)
+  --target <target>        worktree, index, or head (default: worktree)
+  --author <name>          Comment author
+  --agent                  Mark the author as a coding agent
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Examples:
+  greview add --file src/api.ts --line 41-48 -m "Handle malformed input"
+  greview add --file src/api.ts --line 12 --target index --side old -m -
+`,
+  reply: `Usage:
+  greview reply <thread-id> -m <text> [options]
+
+Add a comment to an existing review thread. Replying does not resolve it.
+
+Options:
+  -m, --message <text>     Comment text; use - to read stdin
+  --author <name>          Comment author
+  --agent                  Mark the author as a coding agent
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Examples:
+  greview reply 3 --agent --author codex -m "Added input validation."
+  printf 'Detailed reply
+' | greview reply 3 -m -
+`,
+  edit: `Usage:
+  greview edit <comment-id> -m <text> [options]
+
+Replace the body of an existing comment. Comment IDs are shown by
+\`greview show <thread-id> --json\`.
+
+Options:
+  -m, --message <text>     Replacement text; use - to read stdin
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview edit 7 -m "Corrected reply text."
+`,
+  resolve: `Usage:
+  greview resolve <thread-id> [options]
+
+Mark a review thread as resolved. Resolution is a human review decision; coding
+agents should reply to threads and leave resolution to the reviewer.
+
+Options:
+  --author <name>          Person recording the decision
+  --by <name>              Explicit resolution attribution
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview resolve 3
+`,
+  unresolve: `Usage:
+  greview unresolve <thread-id> [options]
+
+Reopen a resolved review thread.
+
+Options:
+  --author <name>          Person recording the decision
+  --by <name>              Explicit attribution
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview unresolve 3
+`,
+  rm: `Usage:
+  greview rm <thread-id> [options]
+
+Permanently delete a thread and all of its comments. Coding agents should never
+delete review threads on behalf of the reviewer.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview rm 3
+`,
+  sync: `Usage:
+  greview sync [options]
+
+Re-anchor every thread against the current worktree, index, and HEAD, then record
+any drift or location changes.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview sync --json
+`,
+  stats: `Usage:
+  greview stats [options]
+
+Show counts for open, resolved, changed, and orphaned threads. Locations are
+refreshed before counting.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview stats --json
+`,
+  repo: `Usage:
+  greview repo [options]
+
+Show the repository root, Git directory, current branch, HEAD commit, and greview
+data path.
+
+Options:
+  --cwd <dir>              Start discovery from another directory
+  --json                   Emit machine-readable output
+
+Example:
+  greview repo --cwd ../another-checkout
+`,
+  setup: `Usage:
+  greview setup
+  greview setup skill
+  greview setup extension
+
+Install greview components. With no component, choose the agent skill, VS Code
+extension, or both interactively. Setup does not require a Git repository.
+
+Components:
+  skill                    Run the interactive skills CLI installer
+  extension                Install youxam.greview from the VS Code Marketplace
+
+Requirements:
+  skill                    Node.js with npm/npx
+  extension                The VS Code \`code\` command on PATH
+
+Examples:
+  greview setup
+  greview setup skill
+  greview setup extension
+`,
+  "setup:skill": `Usage:
+  greview setup skill
+
+Install the greview agent skill from GitHub. This starts the skills CLI and keeps
+its interactive choice of project/global scope and target agents.
+
+Requirements:
+  Node.js with npm/npx
+
+Equivalent command:
+  npx --yes skills add YouXam/greview --skill greview
+`,
+  "setup:extension": `Usage:
+  greview setup extension
+
+Install the greview extension from the VS Code Marketplace by running:
+  code --install-extension youxam.greview
+
+Requirement:
+  The VS Code \`code\` command must be available on PATH.
+
+Marketplace:
+  https://marketplace.visualstudio.com/items?itemName=youxam.greview
+`,
+  onsubmit: `Usage:
+  greview onsubmit <command> [arguments] [options]
+
+Manage commands that run when a review is submitted. Hooks belong to the current
+worktree, run concurrently through the shell, and receive no arguments.
+
+Commands:
+  list                     List hooks
+  add <name> <command>     Add or replace a hook
+  delete <name>            Delete one hook
+  clear                    Delete all hooks
+  run                      Run all hooks now
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Examples:
+  greview onsubmit list
+  greview help onsubmit add
+`,
+  "onsubmit:list": `Usage:
+  greview onsubmit list [options]
+
+List review submission hooks configured for the current worktree.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview onsubmit list --json
+`,
+  "onsubmit:add": `Usage:
+  greview onsubmit add <name> <command> [options]
+
+Add a review submission hook, or replace the hook with the same name. The command
+runs through the shell at the repository root and receives no arguments.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview onsubmit add notify "./scripts/notify-review.sh"
+`,
+  "onsubmit:delete": `Usage:
+  greview onsubmit delete <name> [options]
+
+Delete one review submission hook from the current worktree.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview onsubmit delete notify
+`,
+  "onsubmit:clear": `Usage:
+  greview onsubmit clear [options]
+
+Delete every review submission hook from the current worktree.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable output
+
+Example:
+  greview onsubmit clear
+`,
+  "onsubmit:run": `Usage:
+  greview onsubmit run [options]
+
+Run all review submission hooks concurrently. Each hook has a one-minute timeout;
+the command exits non-zero if any hook fails.
+
+Options:
+  --cwd <dir>              Run against another checkout
+  --json                   Emit machine-readable hook results
+
+Example:
+  greview onsubmit run --json
+`,
+  help: `Usage:
+  greview help [command]
+  greview <command> --help
+
+Show global help or detailed help for a command. Nested onsubmit commands also
+have their own pages.
+
+Examples:
+  greview help add
+  greview list --help
+  greview help onsubmit add
+`,
+  version: `Usage:
+  greview version
+  greview --version
+
+Print the installed greview CLI version.
+`
+};
+var ALIASES = {
+  ls: "list",
+  delete: "rm",
+  reopen: "unresolve"
+};
+var ONSUBMIT_ALIASES = {
+  rm: "delete"
+};
+function commandHelp(parts) {
+  const rawCommand = parts[0];
+  if (rawCommand === void 0) return null;
+  const command = ALIASES[rawCommand] ?? rawCommand;
+  if (command === "setup") {
+    const component = parts[1];
+    return component === void 0 ? HELP.setup ?? null : HELP[`setup:${component}`] ?? null;
+  }
+  if (command !== "onsubmit") return HELP[command] ?? null;
+  const rawSubcommand = parts[1];
+  if (rawSubcommand === void 0) return HELP.onsubmit ?? null;
+  const subcommand = ONSUBMIT_ALIASES[rawSubcommand] ?? rawSubcommand;
+  return HELP[`onsubmit:${subcommand}`] ?? null;
+}
+
 // src/sync.ts
 var VERSIONS = ["worktree", "index", "head"];
 function intact(d) {
@@ -820,66 +1208,6 @@ function packageVersion() {
   return pkg.version;
 }
 var VERSION = packageVersion();
-var USAGE = `greview ${VERSION} \u2014 review threads anchored to git diffs
-
-Usage: greview <command> [options]
-
-Commands
-  list                     List threads (open ones by default)
-  show <id>                One thread in full, with before/after and history
-  add                      Start a thread on a line range
-  reply <id> -m <text>     Add a comment to a thread
-  edit <comment-id> -m <t> Rewrite one comment (ids shown by "show")
-  resolve <id>             Mark resolved            unresolve <id>   reopen
-  rm <id>                  Delete a thread and its comments
-  sync                     Re-anchor every thread and record what moved
-  stats                    Counts, for status lines and hooks
-  repo                     Repo root, git dir and database path
-  install-skill            Install the greview skill for coding agents
-  onsubmit <sub>           Commands to run when the reviewer presses Submit:
-                             list                    show this worktree's hooks
-                             add <name> <command>     add or replace one
-                             delete <name>            remove one
-                             clear                    remove all
-                             run                      run them all, concurrently
-
-Options
-  --cwd <dir>              Run as if in this directory (default: cwd)
-  --json                   Machine-readable output; every response is
-                           {"ok":true,"data":...} or {"ok":false,"error":"..."}
-
-  list/show
-  --all                    Include resolved threads
-  --resolved               Only resolved threads
-  --file <path>            Restrict to one file
-  --target <t>             Restrict to worktree | index | head
-  --events                 Include the event history in --json output
-  --no-sync                Skip re-anchoring; report the last known positions
-
-  add
-  --file <path>            File to comment on (required)
-  --line <n|n-m>           Line range in the current version (required)
-  --side new|old           Diff side (default: new)
-  --target worktree|index|head
-                           Which diff the comment belongs to (default: worktree)
-  -m, --message <text>     Comment body; use "-" to read stdin
-
-  add/reply/edit/resolve
-  --author <name>          Default: $GREVIEW_AUTHOR, then git config user.name for
-                           a person, or the agent's own name for an agent
-  --agent                  Record the author as an agent rather than a human.
-                           Implied when $AI_AGENT or $CLAUDECODE is set; override
-                           with GREVIEW_AUTHOR_KIND=human. An agent is never
-                           recorded under git config user.name.
-
-Submit hooks are per-worktree and run through the shell with no arguments. They
-are how something outside greview hears that a review is ready; greview does not
-care what they do.
-
-Anchoring: a thread stores the exact text of the lines it was written against.
-Later, "drift" says what became of them \u2014 current, moved, changed or orphaned.
-Nothing is ever auto-resolved; resolving is a human decision.
-`;
 var UsageError = class extends Error {
 };
 var SKILL_INSTALL_ARGS = [
@@ -890,24 +1218,85 @@ var SKILL_INSTALL_ARGS = [
   "--skill",
   "greview"
 ];
+var EXTENSION_ID = "youxam.greview";
+var MARKETPLACE_URL = `https://marketplace.visualstudio.com/items?itemName=${EXTENSION_ID}`;
 function fail(message) {
   throw new UsageError(message);
 }
-function cmdInstallSkill() {
-  const executable = process.platform === "win32" ? "npx.cmd" : "npx";
-  const result = spawnSync2(executable, SKILL_INSTALL_ARGS, { stdio: "inherit" });
+function runInstaller(executable, args, missingHelp) {
+  const result = spawnSync2(executable, args, { stdio: "inherit" });
   if (result.error) {
-    process.stderr.write(`greview: could not start npx: ${result.error.message}
+    process.stderr.write(`greview: could not start ${executable}: ${result.error.message}
+${missingHelp}
 `);
     return 1;
   }
   if (result.signal) {
-    process.stderr.write(`greview: skill installer stopped by ${result.signal}
+    process.stderr.write(`greview: ${executable} stopped by ${result.signal}
 `);
     return 1;
   }
   return result.status ?? 1;
 }
+function installSkill() {
+  const executable = process.platform === "win32" ? "npx.cmd" : "npx";
+  return runInstaller(
+    executable,
+    SKILL_INSTALL_ARGS,
+    "Install Node.js with npm, then run `greview setup skill` again."
+  );
+}
+function installExtension() {
+  const executable = process.platform === "win32" ? "code.cmd" : "code";
+  return runInstaller(
+    executable,
+    ["--install-extension", EXTENSION_ID],
+    `Install from ${MARKETPLACE_URL}, or add the VS Code \`code\` command to PATH.`
+  );
+}
+function installComponents(components) {
+  let status = 0;
+  for (const component of components) {
+    const result = component === "skill" ? installSkill() : installExtension();
+    if (result !== 0) status = result;
+  }
+  return status;
+}
+async function interactiveSetup() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  let components = null;
+  try {
+    process.stdout.write(
+      "greview setup\n\n  1) Agent skill\n  2) VS Code extension\n  3) Both\n\n"
+    );
+    const answer = (await rl.question("Select components [1-3, q to cancel]: ")).trim().toLowerCase();
+    if (answer === "1" || answer === "skill") components = ["skill"];
+    else if (answer === "2" || answer === "extension") components = ["extension"];
+    else if (answer === "3" || answer === "both") components = ["skill", "extension"];
+    else if (answer === "q" || answer === "quit" || answer === "") return 0;
+    else {
+      process.stderr.write(`greview: unknown setup selection "${answer}"
+`);
+      return 2;
+    }
+  } finally {
+    rl.close();
+  }
+  if (components === null) return 0;
+  return installComponents(components);
+}
+function cmdSetup(positionals) {
+  if (positionals.length > 2) {
+    process.stderr.write("greview: usage: greview setup [skill|extension]\n");
+    return 2;
+  }
+  const component = positionals[1];
+  if (component === void 0) return interactiveSetup();
+  if (component === "skill" || component === "extension") return installComponents([component]);
+  process.stderr.write(`greview: unknown setup component "${component}" (skill or extension)
+`);
+  return 2;
+}
 function parse(argv) {
   return parseArgs({
     args: argv,
@@ -1315,6 +1704,21 @@ function cmdStats(ctx) {
     )
   );
 }
+function printHelp(parts) {
+  if (parts.length === 0) {
+    process.stdout.write(globalHelp(VERSION));
+    return 0;
+  }
+  const text = commandHelp(parts);
+  if (text === null) {
+    process.stderr.write(`greview: no help topic for "${parts.join(" ")}"
+Try: greview help
+`);
+    return 2;
+  }
+  process.stdout.write(text);
+  return 0;
+}
 function main(argv) {
   let values;
   let positionals;
@@ -1326,16 +1730,14 @@ function main(argv) {
     return 2;
   }
   const command = positionals[0] ?? (values.version ? "version" : "help");
-  if (values.help || command === "help") {
-    process.stdout.write(USAGE);
-    return 0;
-  }
+  if (command === "help") return printHelp(positionals.slice(1));
+  if (values.help) return printHelp(positionals);
   if (command === "version") {
     process.stdout.write(`${VERSION}
 `);
     return 0;
   }
-  if (command === "install-skill") return cmdInstallSkill();
+  if (command === "setup") return cmdSetup(positionals);
   let ctx = null;
   try {
     const repo = findRepo(cwdOf(values));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greview-cli",
-  "version": "0.12.4",
+  "version": "0.13.0",
   "description": "Review local Git diffs with humans and coding agents",
   "license": "MIT",
   "type": "module",