argsbarg 3.1.0 → 3.3.0

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");
+});

package/src/install/update.ts

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import type { CliProgram } from "../types.ts";
+import { runInstallMutation } from "./index.ts";
+import { installErr } from "./status.ts";
+
+/** Downloads the latest release and reinstalls installed artifacts (`myapp update`). */
+export async function cliUpdate(root: CliProgram): Promise<never> {
+  const hook = root.install?.updateGetLatest;
+  if (!hook) {
+    installErr("update is not configured. Set install.updateGetLatest on the program root.");
+    process.exit(1);
+  }
+
+  let artifact: Awaited<ReturnType<typeof hook>>;
+  try {
+    artifact = await hook({ version: root.version });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    installErr(message);
+    process.exit(1);
+  }
+
+  if (!artifact.path || !existsSync(artifact.path)) {
+    installErr(`updateGetLatest returned missing binary: ${JSON.stringify(artifact.path)}`);
+    process.exit(1);
+  }
+
+  if (artifact.version !== undefined && artifact.version === root.version) {
+    process.stdout.write(`Already at v${root.version}\n`);
+    await artifact.cleanup?.();
+    process.exit(0);
+  }
+
+  const currentVersion = root.version;
+  try {
+    await runInstallMutation(root, {
+      reinstall: "1",
+      yes: "1",
+      quiet: "1",
+      from: artifact.path,
+    });
+  } catch (err) {
+    await artifact.cleanup?.();
+    installErr(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+
+  await artifact.cleanup?.();
+
+  if (artifact.version !== undefined && artifact.version !== currentVersion) {
+    process.stdout.write(`Updated ${root.key} ${currentVersion} → ${artifact.version}\n`);
+  }
+
+  process.exit(0);
+}

package/src/invoke.ts

@@ -12,7 +12,7 @@ import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.t
 import { format } from "node:util";
 
 /** Outcome of a non-exiting CLI invocation. */
-export type CliInvokeKind = "ok" | "help" | "schema" | "error";
+export type CliInvokeKind = "ok" | "help" | "error";
 
 /** Result of cliInvoke: captured output and exit metadata without process.exit. */
 export interface CliInvokeResult {
@@ -74,16 +74,6 @@ export async function cliInvoke(root: CliProgram, argv: string[]): Promise<CliIn
     };
   }
 
-  if (pr.kind === ParseKind.Schema) {
-    return {
-      kind: "schema",
-      exitCode: 1,
-      stdout: "",
-      stderr: "",
-      errorMsg: "Schema export is not available via MCP tool calls.",
-    };
-  }
-
   if (pr.kind === ParseKind.Error) {
     return {
       kind: "error",

package/src/mcp/tools.ts

@@ -134,7 +134,7 @@ export function allMcpResources(root: CliProgram): McpResourceEntry[] {
   const builtIn: McpResourceEntry = {
     uri: schemaUri,
     name: "cli-schema",
-    description: "Full CLI command tree (same as --schema).",
+    description: "Full CLI command tree (same as docs schema).",
     mimeType: "application/json",
     load: () => cliSchemaJson(root),
   };

package/src/parse.ts

@@ -29,8 +29,6 @@ export enum ParseKind {
   Ok = "ok",
   /** User requested help (explicit or implicit). */
   Help = "help",
-  /** User requested machine-readable schema export (`--schema`). */
-  Schema = "schema",
   /** User error (unknown command, bad option, etc.). */
   Error = "error",
 }
@@ -59,18 +57,12 @@ export interface ParseResult {
 
 const helpShort = "-h";
 const helpLong = "--help";
-const schemaLong = "--schema";
 
 /** Returns true if the argv token is `-h` or `--help`. */
 function isHelpTok(tok: string): boolean {
   return tok === helpShort || tok === helpLong;
 }
 
-/** Returns true if the argv token is `--schema`. */
-function isSchemaTok(tok: string): boolean {
-  return tok === schemaLong;
-}
-
 /** Looks up a subcommand or routing node by `key`. */
 function findChild(cmds: CliNode[], name: string): CliNode | undefined {
   return cmds.find((c) => c.key === name);
@@ -195,7 +187,6 @@ function consumeOptions(
     const tok = argv[idx];
 
     if (isHelpTok(tok)) break;
-    if (isSchemaTok(tok)) break;
     if (!tok.startsWith("-")) break;
 
     if (tok === "--") {
@@ -371,20 +362,6 @@ function helpResult(p: string[], explicit: boolean): ParseResult {
   };
 }
 
-/** Builds a schema-export result for the program root. */
-function schemaResult(): ParseResult {
-  return {
-    kind: ParseKind.Schema,
-    path: [],
-    opts: {},
-    args: [],
-    helpExplicit: false,
-    helpPath: [],
-    errorMsg: "",
-    errorHelpPath: [],
-  };
-}
-
 /**
  * Parses `argv` against the program root, routing into subcommands and filling `opts` / `args`.
  */
@@ -420,10 +397,6 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     return helpResult([], true);
   }
 
-  if (i < argv.length && !forcePositionals && isSchemaTok(argv[i])) {
-    return schemaResult();
-  }
-
   // Determine which subcommand to route to
   let cmdName: string;
   let node: CliNode | undefined;

package/src/runtime.ts

@@ -10,7 +10,6 @@ import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.t
 import { CliContext } from "./context.ts";
 import { cliHelpRender } from "./help.ts";
 import { parse, postParseValidate, ParseKind } from "./parse.ts";
-import { cliSchemaJson } from "./schema.ts";
 import { cliValidateProgram } from "./validate.ts";
 
 function cliRootMergedWithBuiltins(program: CliProgram): CliRouter {
@@ -41,6 +40,13 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(1);
   }
 
+  if (argv.length >= 1 && argv[0] === "update" && !caps.update) {
+    process.stderr.write(
+      "update is not enabled. Set install.updateGetLatest on the program root.\n",
+    );
+    process.exit(1);
+  }
+
   if (argv.length >= 1 && argv[0] === "docs" && !caps.docs) {
     process.stderr.write("docs is not enabled. Set docs: { enabled: true } on the program root.\n");
     process.exit(1);
@@ -73,11 +79,6 @@ export async function cliRun(program: CliProgram, argv: string[] = process.argv.
     process.exit(pr.helpExplicit ? 0 : 1);
   }
 
-  if (pr.kind === ParseKind.Schema) {
-    process.stdout.write(cliSchemaJson(program));
-    process.exit(0);
-  }
-
   if (pr.kind === "error") {
     const color = process.stderr.isTTY;
     const msg = color ? `\u001B[31m${pr.errorMsg}\u001B[0m` : pr.errorMsg;

package/src/schema.ts

@@ -5,7 +5,7 @@ This module serializes the CLI schema tree to JSON for machine-readable introspe
 import { type CliNode, type CliProgram, isCliLeaf, isCliRouter } from "./types.ts";
 import { exportPresentationBuiltins, type CliSchemaExport } from "./builtins/export.ts";
 
-const RESERVED = new Set(["completion", "install", "docs", "mcp", "version"]);
+const RESERVED = new Set(["completion", "install", "docs", "mcp", "version", "update"]);
 
 function exportCommand(cmd: CliNode): CliSchemaExport {
   const out: CliSchemaExport = {
@@ -44,8 +44,13 @@ function exportCommand(cmd: CliNode): CliSchemaExport {
   return out;
 }
 
+/** Returns the JSON-safe command tree (handlers omitted). */
+export function cliSchemaExport(root: CliProgram): CliSchemaExport {
+  return exportCommand(root);
+}
+
 export function cliSchemaJson(root: CliProgram): string {
-  return JSON.stringify(exportCommand(root), null, 2) + "\n";
+  return JSON.stringify(cliSchemaExport(root), null, 2) + "\n";
 }
 
 export type { CliSchemaExport };

package/src/skill/generate.ts

@@ -96,7 +96,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     "## Reference",
     "",
-    "See `reference.md` in this skill directory for the full `--schema` JSON export.",
+    "See `reference.md` in this skill directory for the full `docs schema` JSON export.",
     "",
   );
 
@@ -130,7 +130,7 @@ function buildReferenceMd(root: CliProgram): string {
   return [
     `# ${root.key} — CLI reference`,
     "",
-    "Generated from the program `--schema` export. Handlers and runtime-only nodes are omitted.",
+    "Generated from the program `docs schema` export. Handlers and runtime-only nodes are omitted.",
     "",
     "```json",
     cliSchemaJson(root).trimEnd(),

package/src/types.ts

@@ -153,11 +153,28 @@ export interface CliMcpToolConfig {
 /**
  * Opt-out and defaults for the `install` built-in (program root only).
  */
+export interface CliUpdateArtifact {
+  /** Path to an executable binary to copy into the install location. */
+  path: string;
+  /** Release version of `path` (used for already-current checks and success messages). */
+  version?: string;
+  /** Called after reinstall completes (e.g. remove a temp download directory). */
+  cleanup?: () => void | Promise<void>;
+}
+
+/** Fetches the latest release binary for the `update` built-in. */
+export type CliUpdateGetLatest = (ctx: { version: string }) => Promise<CliUpdateArtifact>;
+
 export interface CliInstallConfig {
   /** When `false`, hide/disable `install` (default: enabled). */
   enabled?: boolean;
   /** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
   prefix?: string;
+  /**
+   * When set, enables the `update` built-in (`myapp update`).
+   * Should download or locate the latest release binary and return its path.
+   */
+  updateGetLatest?: CliUpdateGetLatest;
 }
 
 /**

package/src/validate.ts

@@ -63,6 +63,17 @@ export function cliValidateProgram(program: CliProgram): void {
     validateDocsConfig(program.docs);
   }
 
+  if (program.install?.updateGetLatest !== undefined) {
+    if (program.install.enabled === false) {
+      throw new CliSchemaValidationError(
+        "install.updateGetLatest requires install to be enabled (omit install.enabled: false)",
+      );
+    }
+    if (typeof program.install.updateGetLatest !== "function") {
+      throw new CliSchemaValidationError("install.updateGetLatest must be a function");
+    }
+  }
+
   const caps = resolveCapabilities(program);
   const reserved = reservedCommandNames(caps);
 
@@ -166,12 +177,6 @@ function validateOptions(scopeKey: string, options: import("./types.ts").CliOpti
       );
     }
 
-    if (opt.name === "schema") {
-      throw new CliSchemaValidationError(
-        `Option name "schema" is reserved for --schema: ${scopeKey}/${opt.name}`,
-      );
-    }
-
     if (opt.shortName !== undefined) {
       if (opt.shortName === "h") {
         throw new CliSchemaValidationError(