argsbarg 3.0.0 → 3.2.0

package/src/docs/resolve.ts

@@ -0,0 +1,119 @@
+import type { CliDocsConfig, CliProgram } from "../types.ts";
+import { cliSchemaJson } from "../schema.ts";
+import { generateSkillBundle } from "../skill/generate.ts";
+import { generateApiGuide } from "./api-guide.ts";
+import { generateMcpGuide } from "./mcp-guide.ts";
+
+/** Built-in docs subcommand keys not allowed in `docs.topics`. */
+export const DOCS_BUILTIN_TOPIC_KEYS = ["mcp", "all", "schema", "api", "skill"] as const;
+
+export type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
+
+/** Default router description for the `docs` built-in. */
+export const DOCS_ROUTER_DESCRIPTION = "Print bundled CLI documentation.";
+
+/** Returns whether bundled docs are enabled on the program root. */
+export function docsEnabled(program: CliProgram): boolean {
+  return program.docs?.enabled === true;
+}
+
+/** User topic keys in declaration order. */
+export function docsUserTopicKeys(docs: CliDocsConfig): string[] {
+  return Object.keys(docs.topics);
+}
+
+/** Subcommand used when argv is bare `myapp docs`. */
+export function docsEffectiveDefaultTopic(docs: CliDocsConfig): string {
+  if (docs.defaultTopic !== undefined) {
+    return docs.defaultTopic;
+  }
+  const keys = docsUserTopicKeys(docs);
+  if (keys.length === 0) {
+    throw new Error("docs.topics must be non-empty");
+  }
+  return keys[0]!;
+}
+
+/** Whether MCP auto-guide topic is included. */
+export function docsIncludesMcpTopic(program: CliProgram): boolean {
+  return docsEnabled(program) && program.mcpServer?.enabled === true;
+}
+
+/** Leaf help description for a user topic. */
+export function docsTopicDescription(key: string, custom?: string): string {
+  if (custom) {
+    return custom;
+  }
+  if (key === "readme") {
+    return "Print README (user guide).";
+  }
+  const label = key.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `Print ${label} documentation.`;
+}
+
+/** Ordered keys for `docs all` (user topics, then auto `mcp` when enabled). */
+export function docsPrintOrder(program: CliProgram): string[] {
+  const docs = program.docs!;
+  const order = docsUserTopicKeys(docs);
+  if (docsIncludesMcpTopic(program)) {
+    order.push("mcp");
+  }
+  return order;
+}
+
+/** Markdown body for one docs topic key. */
+export function docsTopicText(program: CliProgram, topic: string): string {
+  const docs = program.docs!;
+  if (topic === "mcp") {
+    if (!docsIncludesMcpTopic(program)) {
+      throw new Error("Unknown docs topic 'mcp'.");
+    }
+    return generateMcpGuide(program);
+  }
+  const entry = docs.topics[topic];
+  if (!entry) {
+    throw new Error(`Unknown docs topic '${topic}'.`);
+  }
+  return entry.text;
+}
+
+/** All bundled docs concatenated with horizontal rules. */
+export function combineAllDocs(program: CliProgram): string {
+  return docsPrintOrder(program)
+    .map((key) => docsTopicText(program, key).trim())
+    .join("\n\n---\n\n");
+}
+
+/** Writes CLI schema JSON to stdout (`docs schema`). */
+export function printDocsSchema(program: CliProgram): void {
+  process.stdout.write(cliSchemaJson(program));
+}
+
+/** Writes markdown API reference to stdout (`docs api`). */
+export function printDocsApi(program: CliProgram): void {
+  process.stdout.write(generateApiGuide(program));
+}
+
+/** Writes generated Cursor SKILL.md to stdout (`docs skill`). */
+export function printDocsSkill(program: CliProgram): void {
+  const bundle = generateSkillBundle(program, "cursor");
+  process.stdout.write(`${bundle.skillMd}\n`);
+}
+
+/** Writes one docs topic (or `all`) to stdout. */
+export function printDocsTopic(program: CliProgram, topic: string): void {
+  if (topic === "schema") {
+    printDocsSchema(program);
+    return;
+  }
+  if (topic === "api") {
+    printDocsApi(program);
+    return;
+  }
+  if (topic === "skill") {
+    printDocsSkill(program);
+    return;
+  }
+  const content = topic === "all" ? combineAllDocs(program) : docsTopicText(program, topic);
+  process.stdout.write(`${content}\n`);
+}

package/src/help.ts

@@ -346,16 +346,12 @@ function usageLines(
 }
 
 /** Table rows for named options, including synthetic built-in rows. */
-function rowsForOptions(defs: CliOption[], color: boolean, isRoot: boolean): HelpRow[] {
+function rowsForOptions(defs: CliOption[], color: boolean): HelpRow[] {
   const rows: HelpRow[] = [];
   const helpLabel = color
     ? style.aquaBold("--help, ") + style.greenBright("-h")
     : "--help, -h";
   rows.push({ label: helpLabel, description: "Show help for this command." });
-  if (isRoot) {
-    const schemaLabel = color ? style.aquaBold("--schema") : "--schema";
-    rows.push({ label: schemaLabel, description: "Print the full command tree as JSON." });
-  }
   for (const o of defs) {
     const desc = o.required ? "(required) " + o.description : o.description;
     rows.push({ label: cliOptionLabel(o, color), description: desc });
@@ -401,7 +397,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
       ).join("\n"),
     );
 
-    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color, true), hw, color);
+    const optBox = renderTableBox("Options", rowsForOptions(schema.options ?? [], color), hw, color);
     if (optBox.length > 0) {
       lines.push("");
       lines.push(optBox.join("\n"));
@@ -450,7 +446,7 @@ export function cliHelpRender(schema: CliRouter, helpPath: string[], useStderr:
     ).join("\n"),
   );
 
-  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color, false), hw, color);
+  const optBox = renderTableBox("Options", rowsForOptions(node.options ?? [], color), hw, color);
   if (optBox.length > 0) {
     lines.push("");
     lines.push(optBox.join("\n"));

package/src/index.test.ts

@@ -500,8 +500,8 @@ test("leaf completion help prints correctly", async () => {
   expect(stderr.toString()).toBe("");
 });
 
-test("--schema exports JSON for nested CLIs", async () => {
-  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts --schema`.nothrow().quiet();
+test("docs schema exports JSON for nested CLIs", async () => {
+  const { stdout, stderr, exitCode } = await $`bun run examples/nested.ts docs schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
   expect(stderr.toString()).toBe("");
 
@@ -516,15 +516,20 @@ test("--schema exports JSON for nested CLIs", async () => {
   expect(lookup.positionals[0].name).toBe("path");
 });
 
-test("--schema exports JSON for leaf roots", async () => {
-  const { stdout, exitCode } = await $`bun run examples/minimal.ts --schema`.nothrow().quiet();
+test("docs schema exports JSON for leaf roots", async () => {
+  const { stdout, exitCode } = await $`bun run examples/minimal.ts docs schema`.nothrow().quiet();
   expect(exitCode).toBe(0);
 
   const schema = JSON.parse(stdout.toString());
   expect(schema.key).toBe("minimal.ts");
   expect(schema.positionals[0].name).toBe("name");
   expect(schema.options[0].name).toBe("verbose");
-  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual(["completion", "version", "install"]);
+  expect(schema.commands.map((c: { key: string }) => c.key)).toEqual([
+    "completion",
+    "version",
+    "install",
+    "docs",
+  ]);
 });
 
 test("version builtin prints program version", async () => {
@@ -540,10 +545,15 @@ test("leaf root help lists completion built-in", async () => {
   expect(stdout.toString()).toContain("Generate the autocompletion script for shells.");
 });
 
-test("parse recognizes --schema at the program root", () => {
-  const root= testProgram({
+test("root --schema is no longer a flag", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
     commands: [
       {
         key: "x",
@@ -553,8 +563,8 @@ test("parse recognizes --schema at the program root", () => {
     ],
   });
   cliValidateProgram(root);
-  const pr = parse(root, ["--schema"]);
-  expect(pr.kind).toBe(ParseKind.Schema);
+  const pr = parse(cliPresentationRoot(root), ["--schema"]);
+  expect(pr.kind).not.toBe(ParseKind.Ok);
 });
 
 test("cliSchemaJson omits handlers and completion built-ins", () => {
@@ -587,32 +597,15 @@ test("cliSchemaJson omits handlers and completion built-ins", () => {
   expect(schema).not.toHaveProperty("handler");
 });
 
-test("reserved option name schema is rejected", () => {
-  const root= testProgram({
-    key: "app",
-    description: "",
-    commands: [
-      {
-        key: "x",
-        description: "cmd",
-        options: [
-          {
-            name: "schema",
-            description: "",
-            kind: CliOptionKind.String,
-          },
-        ],
-        handler: () => {},
-      },
-    ],
-  });
-  expect(() => cliValidateProgram(root)).toThrow(/reserved for --schema/);
-});
-
-test("root help lists --schema built-in", () => {
-  const root= testProgram({
+test("docs help lists schema, api, and skill subcommands", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
+    docs: {
+      enabled: true,
+      topics: { readme: { text: "# readme\n" } },
+    },
     commands: [
       {
         key: "x",
@@ -621,14 +614,19 @@ test("root help lists --schema built-in", () => {
       },
     ],
   });
-  const help = cliHelpRender(cliPresentationRoot(root), [], false);
-  expect(help).toContain("--schema");
+  const help = cliHelpRender(cliPresentationRoot(root), ["docs"], false);
+  expect(help).toContain("schema");
   expect(help).toContain("Print the full command tree as JSON.");
+  expect(help).toContain("api");
+  expect(help).toContain("markdown");
+  expect(help).toContain("skill");
+  expect(help).toContain("SKILL.md");
 });
 
-test("nested help omits --schema built-in", () => {
-  const root= testProgram({
+test("root help omits legacy --schema flag", () => {
+  const root = testProgram({
     key: "app",
+    version: "1.0.0",
     description: "demo",
     commands: [
       {
@@ -638,37 +636,10 @@ test("nested help omits --schema built-in", () => {
       },
     ],
   });
-  const help = cliHelpRender(cliPresentationRoot(root), ["x"], false);
+  const help = cliHelpRender(cliPresentationRoot(root), [], false);
   expect(help).not.toContain("--schema");
 });
 
-test("completion scripts offer --schema at the program root only", () => {
-  const root= testProgram({
-    key: "myapp",
-    description: "",
-    commands: [
-      {
-        key: "stat",
-        description: "stats",
-        commands: [
-          {
-            key: "show",
-            description: "show",
-            handler: () => {},
-          },
-        ],
-      },
-    ],
-  });
-
-  const bash = completionBashScript(cliPresentationRoot(root));
-  expect(bash).toContain("A_myapp_0_opts+=('--schema')");
-  expect(bash).not.toContain("A_myapp_1_opts+=('--schema')");
-
-  const zsh = completionZshScript(cliPresentationRoot(root));
-  expect(zsh).toContain("'--schema:Print the full command tree as JSON.'");
-});
-
 const nestedMcpFixture = testProgram({
   key: "nested.ts",
   description: "Nested groups demo.",
@@ -1760,7 +1731,10 @@ test("generateSkillBundle includes frontmatter and command catalog", () => {
   expect(bundle.dirName).toBe("nested_ts");
   expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
   expect(bundle.skillMd).toContain("stat owner lookup");
-  expect(bundle.skillMd).toContain("nested.ts mcp");
+  expect(bundle.skillMd).toContain("Invoke via shell:");
+  expect(bundle.skillMd).not.toContain("mcp.json");
+  expect(bundle.skillMd).not.toContain("Prefer MCP");
+  expect(bundle.skillMd).not.toContain("tools/call");
   expect(bundle.referenceMd).toContain("```json");
   expect(() => JSON.parse(bundle.referenceMd.match(/```json\n([\s\S]*?)\n```/)![1]!)).not.toThrow();
 });

package/src/index.ts

@@ -20,6 +20,10 @@ export type {
   CliMcpServerConfig,
   CliMcpToolConfig,
   CliInstallConfig,
+  CliUpdateArtifact,
+  CliUpdateGetLatest,
+  CliDocsConfig,
+  CliDocsTopic,
   CliOption,
   CliPositional,
 } from "./types.ts";

package/src/install/binary.ts

@@ -16,8 +16,13 @@ export interface BinaryInstallResult {
   patchedZshRc: boolean;
 }
 
-/** Copies the running binary to the install path and patches rc files when shells are detected. */
-export function installBinary(root: CliProgram, paths: InstallPaths, dry: boolean): BinaryInstallResult {
+/** Copies a binary to the install path and patches rc files when shells are detected. */
+export function installBinary(
+  root: CliProgram,
+  paths: InstallPaths,
+  dry: boolean,
+  sourcePath: string = process.execPath,
+): BinaryInstallResult {
   const changed: string[] = [];
   const shells = detectShells();
   let patchedBashRc = false;
@@ -25,7 +30,7 @@ export function installBinary(root: CliProgram, paths: InstallPaths, dry: boolea
 
   if (!dry) {
     mkdirSync(paths.bindir, { recursive: true });
-    copyFileSync(process.execPath, paths.binaryPath);
+    copyFileSync(sourcePath, paths.binaryPath);
   }
   changed.push(paths.binaryPath);
 

package/src/install/index.ts

@@ -15,13 +15,15 @@ import { buildUninstallPlan, uninstallSkillDir, type UninstallAction } from "./u
 
 function parseInstallOpts(raw: Record<string, string>): InstallOpts {
   const flag = (name: string) => raw[name] === "1";
+  const reinstall = flag("reinstall") || flag("update");
   return {
     all: flag("all"),
     bin: flag("bin"),
     completions: flag("completions"),
     skill: flag("skill"),
     mcp: flag("mcp"),
-    update: flag("update"),
+    reinstall,
+    from: raw.from,
     status: flag("status"),
     uninstall: flag("uninstall"),
     yes: flag("yes"),
@@ -36,28 +38,32 @@ function validateOpts(opts: InstallOpts): string | null {
   if (opts.quiet && opts.dry) {
     return "--quiet cannot be combined with --dry.";
   }
-  if (opts.quiet && !opts.yes && !opts.json && !opts.update) {
-    return "--quiet requires --yes (or --json / --update).";
+  if (opts.quiet && !opts.yes && !opts.json && !opts.reinstall) {
+    return "--quiet requires --yes (or --json / --reinstall).";
   }
   if (opts.json) {
     opts.yes = true;
   }
-  if (opts.update) {
+  if (opts.reinstall) {
     opts.bin = true;
     opts.yes = true;
   }
 
-  const mutationFlags = opts.all || opts.bin || opts.completions || opts.skill || opts.mcp || opts.update || opts.uninstall;
+  const mutationFlags =
+    opts.all || opts.bin || opts.completions || opts.skill || opts.mcp || opts.reinstall || opts.uninstall;
   if (opts.status && mutationFlags) {
-    return "--status is mutually exclusive with install/update/uninstall targets.";
+    return "--status is mutually exclusive with install/reinstall/uninstall targets.";
   }
-  if (opts.update && (opts.all || opts.bin || opts.completions || opts.skill || opts.mcp || opts.uninstall || opts.status)) {
-    return "--update cannot be combined with other target flags.";
+  if (
+    opts.reinstall &&
+    (opts.all || opts.completions || opts.skill || opts.mcp || opts.uninstall || opts.status)
+  ) {
+    return "--reinstall cannot be combined with other target flags.";
   }
-  if (opts.uninstall && (opts.all || opts.update || opts.status)) {
-    return "--uninstall cannot be combined with --all, --update, or --status.";
+  if (opts.uninstall && (opts.all || opts.reinstall || opts.status)) {
+    return "--uninstall cannot be combined with --all, --reinstall, or --status.";
   }
-  if (!opts.status && !opts.update && !opts.uninstall) {
+  if (!opts.status && !opts.reinstall && !opts.uninstall) {
     const hasTarget = opts.all || opts.bin || opts.completions || opts.skill || opts.mcp;
     if (!hasTarget) {
       return "Specify at least one target: --all, --bin, --completions, --skill, or --mcp.";
@@ -114,31 +120,31 @@ function executePlan(
   return changed;
 }
 
-/** Main install command orchestrator. */
-export async function cliInstall(root: CliProgram, rawOpts: Record<string, string>): Promise<never> {
+/** Runs install/reinstall/uninstall mutations without exiting the process. */
+export async function runInstallMutation(
+  root: CliProgram,
+  rawOpts: Record<string, string>,
+): Promise<{ changed: string[]; opts: InstallOpts; paths: ReturnType<typeof resolveInstallPaths> }> {
   const opts = parseInstallOpts(rawOpts);
   const err = validateOpts(opts);
   if (err) {
-    installErr(err);
-    process.exit(1);
+    throw new Error(err);
   }
 
   const paths = resolveInstallPaths(root, opts);
 
   if (opts.status) {
     printInstallStatus(root, opts);
-    process.exit(0);
+    return { changed: [], opts, paths };
   }
 
-  // MCP conflict checks before planning
   if (!opts.uninstall && resolveCapabilities(root).mcp && (opts.all || opts.mcp)) {
     const entry = expectedMcpEntry(root);
     const yes = !!opts.yes;
     for (const p of [paths.cursorMcpPath, paths.claudeMcpPath]) {
       const conflict = checkMcpConflict(p, paths.mcpName, entry, yes);
       if (conflict) {
-        installErr(conflict);
-        process.exit(1);
+        throw new Error(conflict);
       }
     }
   }
@@ -146,37 +152,52 @@ export async function cliInstall(root: CliProgram, rawOpts: Record<string, strin
   let actions: Array<InstallAction | UninstallAction>;
   if (opts.uninstall) {
     actions = buildUninstallPlan(root, paths, opts);
-  } else if (opts.update) {
+  } else if (opts.reinstall) {
     actions = buildUpdatePlan(root, paths, opts);
   } else {
     actions = buildInstallPlan(root, paths, opts);
   }
 
   if (actions.length === 0) {
-    installErr("Nothing to do.");
-    process.exit(1);
+    throw new Error("Nothing to do.");
   }
 
   if (!opts.quiet && !opts.json) {
-    installOut("About to " + (opts.uninstall ? "remove" : opts.update ? "update" : "install") + ":", opts);
+    installOut("About to " + (opts.uninstall ? "remove" : opts.reinstall ? "reinstall" : "install") + ":", opts);
     for (const a of actions) {
       installOut("  - " + a.summary, opts);
     }
   }
 
-  const autoYes = opts.yes || opts.json || opts.update;
+  const autoYes = opts.yes || opts.json || opts.reinstall;
   if (!autoYes) {
     if (!process.stdin.isTTY) {
-      installErr("Refusing to proceed without --yes (stdin is not a TTY).");
-      process.exit(1);
+      throw new Error("Refusing to proceed without --yes (stdin is not a TTY).");
     }
     if (!promptConfirm()) {
-      installErr("Aborted.");
-      process.exit(1);
+      throw new Error("Aborted.");
     }
   }
 
   const changed = executePlan(root, actions, opts);
+  return { changed, opts, paths };
+}
+
+/** Main install command orchestrator. */
+export async function cliInstall(root: CliProgram, rawOpts: Record<string, string>): Promise<never> {
+  let result: Awaited<ReturnType<typeof runInstallMutation>>;
+  try {
+    result = await runInstallMutation(root, rawOpts);
+  } catch (err) {
+    installErr(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+
+  const { changed, opts, paths } = result;
+
+  if (opts.status) {
+    process.exit(0);
+  }
 
   if (opts.json) {
     process.stdout.write(JSON.stringify(changed, null, 2) + "\n");
@@ -184,9 +205,13 @@ export async function cliInstall(root: CliProgram, rawOpts: Record<string, strin
   }
 
   if (!opts.quiet && changed.length > 0) {
-    const verb = opts.uninstall ? "Removed" : opts.update ? "Updated" : "Installed";
+    const verb = opts.uninstall ? "Removed" : opts.reinstall ? "Reinstalled" : "Installed";
     installOut(`${verb} ${changed.length} file(s).`, opts);
-    if (!opts.uninstall && (opts.all || opts.bin) && changed.some((p) => p === paths.bashRc || p === paths.zshRc || p === paths.binaryPath)) {
+    if (
+      !opts.uninstall &&
+      (opts.all || opts.bin) &&
+      changed.some((p) => p === paths.bashRc || p === paths.zshRc || p === paths.binaryPath)
+    ) {
       installOut("Open a new shell, or run: hash -r (bash) / rehash (zsh)", opts);
     }
   }

package/src/install/plan.ts

@@ -15,7 +15,8 @@ export interface InstallOpts {
   completions?: boolean;
   skill?: boolean;
   mcp?: boolean;
-  update?: boolean;
+  reinstall?: boolean;
+  from?: string;
   status?: boolean;
   uninstall?: boolean;
   yes?: boolean;
@@ -35,7 +36,7 @@ export interface InstallAction {
 }
 
 function wantsBin(opts: InstallOpts): boolean {
-  return !!(opts.all || opts.bin || opts.update);
+  return !!(opts.all || opts.bin || opts.reinstall);
 }
 
 function wantsCompletions(opts: InstallOpts): boolean {
@@ -56,11 +57,12 @@ export function buildInstallPlan(root: CliProgram, paths: InstallPaths, opts: In
   const dry = !!opts.dry;
 
   if (wantsBin(opts)) {
+    const sourcePath = opts.from ?? process.execPath;
     actions.push({
       kind: "binary",
       summary: `binary: ${paths.binaryPath}`,
       message: `Installing binary to ${paths.binaryPath}`,
-      run: () => installBinary(root, paths, dry).changedFiles,
+      run: () => installBinary(root, paths, dry, sourcePath).changedFiles,
     });
   }
 

package/src/install/update.test.ts

@@ -0,0 +1,106 @@
+import { expect, test, beforeEach, afterEach } from "bun:test";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { cliPresentationRoot } from "../builtins/presentation.ts";
+import { cliInvoke } from "../index.ts";
+import type { CliProgram, CliUpdateArtifact } from "../types.ts";
+import { cliValidateProgram } from "../validate.ts";
+import { parseInstallOpts, runInstallMutation } from "./index.ts";
+
+let home: string;
+let prevHome: string | undefined;
+let prevExecPath: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "argsbarg-update-"));
+  prevHome = process.env.HOME;
+  process.env.HOME = home;
+  prevExecPath = process.execPath;
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.HOME;
+  else process.env.HOME = prevHome;
+  process.execPath = prevExecPath;
+  rmSync(home, { recursive: true, force: true });
+});
+
+function fixtureWithUpdate(hook: () => Promise<CliUpdateArtifact>): CliProgram {
+  return {
+    key: "testapp",
+    version: "1.0.0",
+    description: "Test",
+    install: { updateGetLatest: hook },
+    commands: [{ key: "run", description: "Run", handler: () => {} }],
+  };
+}
+
+test("update reserved when updateGetLatest is set", () => {
+  const root: CliProgram = {
+    ...fixtureWithUpdate(async () => ({ path: process.execPath })),
+    commands: [{ key: "update", description: "conflict", handler: () => {} }],
+  };
+  expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: update/);
+});
+
+test("presentation includes update builtin when hook is set", () => {
+  const root = fixtureWithUpdate(async () => ({ path: process.execPath }));
+  const presentation = cliPresentationRoot(root);
+  expect(presentation.commands.some((c) => c.key === "update")).toBe(true);
+});
+
+test("parseInstallOpts maps deprecated --update to reinstall", () => {
+  const opts = parseInstallOpts({ update: "1" });
+  expect(opts.reinstall).toBe(true);
+});
+
+test("runInstallMutation honors --from for binary copy", async () => {
+  const root: CliProgram = {
+    key: "testapp",
+    version: "1.0.0",
+    description: "Test",
+    handler: () => {},
+  };
+  const source = join(home, "new-binary");
+  writeFileSync(source, "#!/bin/sh\necho hi\n", "utf8");
+  chmodSync(source, 0o755);
+
+  const { changed } = await runInstallMutation(root, {
+    reinstall: "1",
+    yes: "1",
+    quiet: "1",
+    from: source,
+  });
+
+  const dest = join(home, ".local", "bin", "testapp");
+  expect(changed).toContain(dest);
+  expect(readFileSync(dest, "utf8")).toContain("echo hi");
+});
+
+test("cliInvoke update uses hook and reinstalls", async () => {
+  const source = join(home, "new-binary");
+  writeFileSync(source, "#!/bin/sh\necho hi\n", "utf8");
+  chmodSync(source, 0o755);
+
+  const root = fixtureWithUpdate(async () => ({
+    path: source,
+    version: "2.0.0",
+  }));
+
+  const result = await cliInvoke(root, ["update"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Updated testapp 1.0.0 → 2.0.0");
+  expect(existsSync(join(home, ".local", "bin", "testapp"))).toBe(true);
+});
+
+test("cliInvoke update reports already current", async () => {
+  const root = fixtureWithUpdate(async () => ({
+    path: process.execPath,
+    version: "1.0.0",
+  }));
+
+  const result = await cliInvoke(root, ["update"]);
+  expect(result.exitCode).toBe(0);
+  expect(result.stdout).toContain("Already at v1.0.0");
+});