@pify/cli 0.1.3 → 0.2.1

package/README.md

@@ -34,6 +34,15 @@ pify init my-extension     # scaffold a new Pi Package
 
 Every command supports `--help`; `install`/`remove`/`update` support `--dry-run`; `list`/`doctor` support `--json`.
 
+**Tab completion** — generated from the live command registry (commands, aliases, flags, and package names all complete):
+
+```bash
+eval "$(pify completions bash)"        # bash — add to ~/.bashrc
+eval "$(pify completions zsh)"         # zsh — add to ~/.zshrc
+pify completions fish > ~/.config/fish/completions/pify.fish
+pify completions powershell | Out-String | Invoke-Expression   # add to $PROFILE
+```
+
 ## How it relates to `pi`
 
 `pify` deliberately does **not** replace pi's package manager. Every package operation delegates to `pi install` / `pi remove` / `pi update`, which own `~/.pi/agent/settings.json` and the extension npm workspace — pify never edits pi's settings. What `pify` adds:
@@ -48,16 +57,19 @@ Every command supports `--help`; `install`/`remove`/`update` support `--dry-run`
 
 | Package | Description |
 |---|---|
-| `@pify/btw` | By-the-way notes: capture asides without derailing the agent |
+| `@pify/ask-question` | Structured questions on built-in dialogs: 1-4 questions, multi-select, Other free-text |
+| `@pify/btw` | By-the-way side conversations: a read-only, codebase-aware side agent |
 | `@pify/goal` | Pin a session goal and keep the agent anchored to it |
 | `@pify/memory` | Persistent memory across pi sessions |
 | `@pify/plan-mode` | Read-only planning mode with approve-then-execute gate |
 | `@pify/pretty` | Prettier TUI rendering for tool calls, diffs, markdown |
 | `@pify/subagent` | Spawn scoped subagents from within a pi session |
 | `@pify/swarm` | Coordinate multiple pi agents working in parallel |
-| `@pify/task` | Track tasks and progress inside pi sessions |
-| `@pify/usage` | Token and cost usage reporting |
-| `@pify/workflow` | Deterministic multi-step agent workflows |
+| `@pify/task` | Task tracking: dependency graph, evidence-gated completion, reminders |
+| `@pify/todo` | Agent working-memory checklist: TodoWrite-style, next-item surfacing |
+| `@pify/usage` | Token and cost reporting: live footer, local-history dashboard |
+| `@pify/workflow` | Deterministic agent orchestration: CC-style workflow scripts |
+| `@pify/worktree` | Safe git-worktree management with safety rails and merge-back |
 | `@pify/yolo` | Auto-approve everything, with an undo trail |
 
 The catalog ships inside the CLI and refreshes (at most daily) from [`catalog.json` on `main`](https://github.com/pifydev/cli/blob/main/catalog.json), so newly published packages appear without a CLI update. A fetched catalog is validated before use — every entry must stay inside the `@pify` scope — and any invalid document is discarded entirely. Overrides: `PIFY_CATALOG_URL` (remote URL), `PIFY_OFFLINE=1` or `PI_OFFLINE=1` (skip all network lookups).

package/catalog.json

@@ -1,85 +1,106 @@
 {
-  "version": 1,
+  "version": 15,
   "org": "pifydev",
   "scope": "@pify",
   "remote": "https://raw.githubusercontent.com/pifydev/cli/main/catalog.json",
   "packages": [
+    {
+      "name": "ask-question",
+      "npm": "@pify/ask-question",
+      "repo": "https://github.com/pifydev/ask-question",
+      "description": "CC AskUserQuestion-shaped tool on built-in dialogs: 1-4 questions, multi-select, Other free-text",
+      "status": "published"
+    },
     {
       "name": "btw",
       "npm": "@pify/btw",
       "repo": "https://github.com/pifydev/btw",
-      "description": "By-the-way notes: capture asides during a session without derailing the agent",
-      "status": "planned"
+      "description": "By-the-way side conversations: a read-only, codebase-aware side agent in a widget",
+      "status": "published"
     },
     {
       "name": "goal",
       "npm": "@pify/goal",
       "repo": "https://github.com/pifydev/goal",
-      "description": "Pin a session goal and keep the agent anchored to it",
-      "status": "planned"
+      "description": "Pin a session goal and keep the agent anchored to it: settled-idle continuation with safety limits",
+      "status": "published"
     },
     {
       "name": "memory",
       "npm": "@pify/memory",
       "repo": "https://github.com/pifydev/memory",
-      "description": "Persistent memory across pi sessions",
-      "status": "planned"
+      "description": "Persistent memory: two-tier markdown storage, FTS5 search, secret-scanned writes",
+      "status": "published"
     },
     {
       "name": "plan-mode",
       "npm": "@pify/plan-mode",
       "repo": "https://github.com/pifydev/plan-mode",
-      "description": "Read-only planning mode with an explicit approve-then-execute gate",
-      "status": "planned"
+      "description": "Read-only planning mode with an enforced approve-then-execute gate: tool policy, plan files, fresh-session handoff",
+      "status": "published"
     },
     {
       "name": "pretty",
       "npm": "@pify/pretty",
       "repo": "https://github.com/pifydev/pretty",
-      "description": "Prettier TUI rendering for tool calls, diffs, and markdown",
-      "status": "planned"
+      "description": "Compact theme-aware rendering for built-in tools: summaries, highlighted reads, colorized diffs",
+      "status": "published"
     },
     {
       "name": "subagent",
       "npm": "@pify/subagent",
       "repo": "https://github.com/pifydev/subagent",
-      "description": "Spawn scoped subagents from within a pi session",
-      "status": "planned"
+      "description": "Spawn scoped subagents: agent_run/agent_result, custom agent types, turn caps and tool allowlists",
+      "status": "published"
     },
     {
       "name": "swarm",
       "npm": "@pify/swarm",
       "repo": "https://github.com/pifydev/swarm",
-      "description": "Coordinate multiple pi agents working in parallel",
-      "status": "planned"
+      "description": "Coordinate multiple pi agents in parallel: fan-out with auto-routing, concurrency queue, aggregated reports",
+      "status": "published"
     },
     {
       "name": "task",
       "npm": "@pify/task",
       "repo": "https://github.com/pifydev/task",
-      "description": "Track tasks and progress inside pi sessions",
-      "status": "planned"
+      "description": "Task tracking with dependency graph, evidence-gated completion, live widget, CC-style reminders",
+      "status": "published"
+    },
+    {
+      "name": "todo",
+      "npm": "@pify/todo",
+      "repo": "https://github.com/pifydev/todo",
+      "description": "Agent working-memory checklist: CC TodoWrite-style complete-replacement, next-item surfacing, live widget",
+      "status": "published"
     },
     {
       "name": "usage",
       "npm": "@pify/usage",
       "repo": "https://github.com/pifydev/usage",
-      "description": "Token and cost usage reporting for pi sessions",
-      "status": "planned"
+      "description": "Token and cost reporting: live footer, /usage dashboard over local session history, zero network",
+      "status": "published"
     },
     {
       "name": "workflow",
       "npm": "@pify/workflow",
       "repo": "https://github.com/pifydev/workflow",
-      "description": "Deterministic multi-step agent workflows for pi",
-      "status": "planned"
+      "description": "Deterministic agent orchestration: CC-style workflow scripts with agent()/parallel()/pipeline()",
+      "status": "published"
+    },
+    {
+      "name": "worktree",
+      "npm": "@pify/worktree",
+      "repo": "https://github.com/pifydev/worktree",
+      "description": "Safe git-worktree management: create/list/merge/remove with safety rails, no shell interpolation",
+      "status": "published"
     },
     {
       "name": "yolo",
       "npm": "@pify/yolo",
       "repo": "https://github.com/pifydev/yolo",
-      "description": "One toggle to auto-approve everything, with an undo trail",
-      "status": "planned"
+      "description": "One toggle to auto-approve everything, with an undo trail: three-tier bash guard, file pre-images",
+      "status": "published"
     }
   ]
 }

package/dist/cli.js

@@ -762,12 +762,12 @@ async function update(targets, opts) {
   const updateEverything = targets.length === 0;
   const piOnly = targets.length === 1 && (targets[0] === "pi" || targets[0] === "self");
   const installed = installedPifyPackages();
-  let packageNames = [];
+  let packageNames2 = [];
   if (updateEverything) {
-    packageNames = [...installed.keys()].sort();
+    packageNames2 = [...installed.keys()].sort();
   } else if (!piOnly) {
-    packageNames = targets.map(resolvePifyName);
-    for (const name of packageNames) {
+    packageNames2 = targets.map(resolvePifyName);
+    for (const name of packageNames2) {
       if (!installed.has(name)) {
         throw notFoundError(`${name} is not installed.`, `pify install ${name}`);
       }
@@ -775,7 +775,7 @@ async function update(targets, opts) {
   }
   if (opts.dryRun) {
     if (updateEverything || piOnly) out("pi update");
-    for (const name of packageNames) out(`pi update npm:@pify/${name}`);
+    for (const name of packageNames2) out(`pi update npm:@pify/${name}`);
     if (updateEverything) out("refresh catalog");
     return 0;
   }
@@ -789,20 +789,20 @@ async function update(targets, opts) {
       if (code !== 0) failed.push("pi");
     }
   }
-  if (packageNames.length > 0 && !piStatus().installed) {
+  if (packageNames2.length > 0 && !piStatus().installed) {
     throw new PifyError(
       "pi is required to update packages.",
       ExitCode.ENVIRONMENT,
       "Run pify setup first."
     );
   }
-  for (const name of packageNames) {
+  for (const name of packageNames2) {
     const args = ["update", `npm:@pify/${name}`];
     step(`pi ${args.join(" ")}`);
     const code = await delegate(args);
     if (code !== 0) failed.push(name);
   }
-  if (updateEverything && packageNames.length === 0) {
+  if (updateEverything && packageNames2.length === 0) {
     hint("No @pify packages installed; nothing more to update.");
   }
   if (updateEverything) {
@@ -1195,6 +1195,244 @@ async function init(dirArg, opts) {
   return 0;
 }
 
+// src/registry.ts
+var GLOBAL_FLAGS = [
+  { name: "help", short: "h", description: "Show help" },
+  { name: "version", short: "v", description: "Print the pify version" },
+  { name: "no-color", description: "Disable colored output" }
+];
+var COMMAND_SPECS = [
+  {
+    name: "setup",
+    aliases: [],
+    description: "Install the pi coding agent (safe to re-run)",
+    positional: "none",
+    flags: [
+      { name: "force", description: "Reinstall pi even if present" },
+      { name: "pi-version", takesValue: true, description: "Install an exact pi version" },
+      { name: "installer", description: "Run pi's official interactive installer" }
+    ]
+  },
+  {
+    name: "install",
+    aliases: ["i", "add"],
+    description: "Install @pify packages by short name",
+    positional: "packages",
+    flags: [
+      { name: "local", short: "l", description: "Project scope" },
+      { name: "approve", short: "a", description: "Forward --approve to pi" },
+      { name: "dry-run", description: "Print the pi commands without running them" }
+    ]
+  },
+  {
+    name: "remove",
+    aliases: ["rm", "uninstall"],
+    description: "Remove installed @pify packages",
+    positional: "packages",
+    flags: [
+      { name: "local", short: "l", description: "Project scope" },
+      { name: "approve", short: "a", description: "Forward --approve to pi" },
+      { name: "dry-run", description: "Print the pi commands without running them" }
+    ]
+  },
+  {
+    name: "update",
+    aliases: ["up"],
+    description: "Update pi and installed @pify packages",
+    positional: "updateTargets",
+    flags: [
+      { name: "catalog", description: "Refresh the catalog cache only" },
+      { name: "dry-run", description: "Print the update plan without executing" }
+    ]
+  },
+  {
+    name: "list",
+    aliases: ["ls"],
+    description: "Show the @pify catalog with install state",
+    positional: "none",
+    flags: [{ name: "json", description: "Machine-readable output" }]
+  },
+  {
+    name: "doctor",
+    aliases: [],
+    description: "Diagnose the local pi/pify environment",
+    positional: "none",
+    flags: [{ name: "json", description: "Machine-readable output" }]
+  },
+  {
+    name: "init",
+    aliases: [],
+    description: "Scaffold a new Pi Package",
+    positional: "directory",
+    flags: [
+      { name: "name", takesValue: true, description: "npm package name" },
+      { name: "description", takesValue: true, description: "Package description" }
+    ]
+  },
+  {
+    name: "completions",
+    aliases: [],
+    description: "Print a shell completion script",
+    positional: "shell",
+    flags: []
+  }
+];
+var COMPLETION_SHELLS = ["bash", "zsh", "fish", "powershell"];
+function parseArgsOptionsFor(spec) {
+  const options = {};
+  for (const flag of spec.flags) {
+    options[flag.name] = flag.takesValue ? { type: "string", ...flag.short ? { short: flag.short } : {} } : { type: "boolean", default: false, ...flag.short ? { short: flag.short } : {} };
+  }
+  return options;
+}
+
+// src/completions.ts
+function packageNames() {
+  return loadBundledCatalog().packages.map((p) => p.name);
+}
+function allNames(spec) {
+  return [spec.name, ...spec.aliases];
+}
+function flagTokens(spec) {
+  return spec.flags.flatMap((f) => [`--${f.name}`, ...f.short ? [`-${f.short}`] : []]);
+}
+function positionalWords(spec) {
+  switch (spec.positional) {
+    case "packages":
+      return packageNames();
+    case "updateTargets":
+      return ["pi", ...packageNames()];
+    case "shell":
+      return [...COMPLETION_SHELLS];
+    default:
+      return [];
+  }
+}
+function bashScript() {
+  const commands = COMMAND_SPECS.flatMap(allNames).join(" ");
+  const cases = COMMAND_SPECS.map((spec) => {
+    const words = [...positionalWords(spec), ...flagTokens(spec)].join(" ");
+    return `    ${allNames(spec).join("|")}) words="${words}" ;;`;
+  }).join("\n");
+  return `# bash completion for pify \u2014 generated by \`pify completions bash\`
+# Install: eval "$(pify completions bash)"  (or save to a bash-completion dir)
+_pify_completions() {
+  local cur words
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=($(compgen -W "${commands} ${GLOBAL_FLAGS.map((f) => `--${f.name}`).join(" ")}" -- "$cur"))
+    return
+  fi
+  case "\${COMP_WORDS[1]}" in
+${cases}
+    *) words="" ;;
+  esac
+  COMPREPLY=($(compgen -W "$words" -- "$cur"))
+}
+complete -F _pify_completions pify
+`;
+}
+function zshScript() {
+  const commandDescs = COMMAND_SPECS.flatMap(
+    (spec) => allNames(spec).map((n) => `    '${n}:${spec.description.replace(/'/g, "")}'`)
+  ).join("\n");
+  const cases = COMMAND_SPECS.map((spec) => {
+    const words = [...positionalWords(spec), ...flagTokens(spec)].map((w) => `'${w}'`).join(" ");
+    return `    ${allNames(spec).join("|")}) _values 'value' ${words || "''"} ;;`;
+  }).join("\n");
+  return `#compdef pify
+# zsh completion for pify \u2014 generated by \`pify completions zsh\`
+# Install: eval "$(pify completions zsh)"  (or save into a directory on $fpath)
+_pify() {
+  local -a commands
+  commands=(
+${commandDescs}
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case "$words[2]" in
+${cases}
+  esac
+}
+_pify "$@"
+`;
+}
+function fishScript() {
+  const lines = [
+    `# fish completion for pify \u2014 generated by \`pify completions fish\``,
+    `# Install: pify completions fish > ~/.config/fish/completions/pify.fish`,
+    `complete -c pify -f`
+  ];
+  for (const spec of COMMAND_SPECS) {
+    for (const name of allNames(spec)) {
+      lines.push(
+        `complete -c pify -n __fish_use_subcommand -a ${name} -d '${spec.description.replace(/'/g, "")}'`
+      );
+    }
+    const condition = `__fish_seen_subcommand_from ${allNames(spec).join(" ")}`;
+    const words = positionalWords(spec);
+    if (words.length > 0) {
+      lines.push(`complete -c pify -n '${condition}' -a '${words.join(" ")}'`);
+    }
+    for (const flag of spec.flags) {
+      const short = flag.short ? ` -s ${flag.short}` : "";
+      lines.push(
+        `complete -c pify -n '${condition}' -l ${flag.name}${short} -d '${flag.description.replace(/'/g, "")}'`
+      );
+    }
+  }
+  for (const flag of GLOBAL_FLAGS) {
+    const short = flag.short ? ` -s ${flag.short}` : "";
+    lines.push(`complete -c pify -l ${flag.name}${short} -d '${flag.description.replace(/'/g, "")}'`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function powershellScript() {
+  const commands = COMMAND_SPECS.flatMap(allNames);
+  const caseBlocks = COMMAND_SPECS.map((spec) => {
+    const words = [...positionalWords(spec), ...flagTokens(spec)].map((w) => `'${w}'`).join(", ");
+    return `      ${allNames(spec).map((n) => `'${n}'`).join(" ")} { @(${words}) }`;
+  }).join("\n");
+  return `# PowerShell completion for pify \u2014 generated by \`pify completions powershell\`
+# Install: pify completions powershell | Out-String | Invoke-Expression  (add to $PROFILE)
+Register-ArgumentCompleter -Native -CommandName pify -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $tokens = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
+  $candidates = if ($tokens.Count -le 1 -or ($tokens.Count -eq 2 -and $wordToComplete)) {
+    @(${commands.map((c) => `'${c}'`).join(", ")})
+  } else {
+    switch ($tokens[1]) {
+${caseBlocks}
+      default { @() }
+    }
+  }
+  $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}
+`;
+}
+function generateCompletion(shell) {
+  switch (shell) {
+    case "bash":
+      return bashScript();
+    case "zsh":
+      return zshScript();
+    case "fish":
+      return fishScript();
+    case "powershell":
+      return powershellScript();
+    default:
+      throw usageError(
+        `Unknown shell ${JSON.stringify(shell)}.`,
+        `Usage: pify completions <${COMPLETION_SHELLS.join("|")}>`
+      );
+  }
+}
+
 // src/help.ts
 function render(text) {
   return text.split("\n").map((line) => {
@@ -1219,6 +1457,7 @@ Commands:
   list                   Show the @pify catalog with install state
   doctor                 Diagnose the local pi/pify environment
   init [dir]             Scaffold a new Pi Package
+  completions <shell>    Print a completion script (bash|zsh|fish|powershell)
 
 Short forms:
   i = install, rm = remove, up = update, ls = list
@@ -1355,6 +1594,23 @@ Options:
 
 Examples:
   pify doctor
+`,
+  completions: `Usage:
+  pify completions <bash|zsh|fish|powershell>
+
+Print a shell completion script generated from the live command registry \u2014
+command names, aliases, flags, and package names all tab-complete.
+
+Examples:
+  # bash / zsh \u2014 evaluate at shell startup (add to your rc file)
+  eval "$(pify completions bash)"
+  eval "$(pify completions zsh)"
+
+  # fish
+  pify completions fish > ~/.config/fish/completions/pify.fish
+
+  # PowerShell \u2014 add to $PROFILE
+  pify completions powershell | Out-String | Invoke-Expression
 `,
   init: `Usage:
   pify init [dir] [--name <package-name>] [--description <text>]
@@ -1381,90 +1637,40 @@ function commandHelp(command) {
 }
 
 // src/cli.ts
-var COMMANDS = [
-  {
-    name: "setup",
-    aliases: [],
-    options: {
-      force: { type: "boolean", default: false },
-      "pi-version": { type: "string" },
-      installer: { type: "boolean", default: false }
-    },
-    allowPositionals: false,
-    run: (_p, v) => setup({
-      force: Boolean(v.force),
-      piVersion: v["pi-version"],
-      installer: Boolean(v.installer)
-    })
-  },
-  {
-    name: "install",
-    aliases: ["i", "add"],
-    options: {
-      local: { type: "boolean", short: "l", default: false },
-      approve: { type: "boolean", short: "a", default: false },
-      "dry-run": { type: "boolean", default: false }
-    },
-    allowPositionals: true,
-    run: (p, v) => install(p, {
-      local: Boolean(v.local),
-      approve: Boolean(v.approve),
-      dryRun: Boolean(v["dry-run"])
-    })
-  },
-  {
-    name: "remove",
-    aliases: ["rm", "uninstall"],
-    options: {
-      local: { type: "boolean", short: "l", default: false },
-      approve: { type: "boolean", short: "a", default: false },
-      "dry-run": { type: "boolean", default: false }
-    },
-    allowPositionals: true,
-    run: (p, v) => remove(p, {
-      local: Boolean(v.local),
-      approve: Boolean(v.approve),
-      dryRun: Boolean(v["dry-run"])
-    })
-  },
-  {
-    name: "update",
-    aliases: ["up"],
-    options: {
-      catalog: { type: "boolean", default: false },
-      "dry-run": { type: "boolean", default: false }
-    },
-    allowPositionals: true,
-    run: (p, v) => update(p, { catalogOnly: Boolean(v.catalog), dryRun: Boolean(v["dry-run"]) })
-  },
-  {
-    name: "list",
-    aliases: ["ls"],
-    options: { json: { type: "boolean", default: false } },
-    allowPositionals: false,
-    run: (_p, v) => list({ json: Boolean(v.json) })
-  },
-  {
-    name: "doctor",
-    aliases: [],
-    options: { json: { type: "boolean", default: false } },
-    allowPositionals: false,
-    run: (_p, v) => doctor({ json: Boolean(v.json) })
-  },
-  {
-    name: "init",
-    aliases: [],
-    options: {
-      name: { type: "string" },
-      description: { type: "string" }
-    },
-    allowPositionals: true,
-    run: (p, v) => init(p[0], {
-      name: v.name,
-      description: v.description
-    })
+var RUNNERS = {
+  setup: (_p, v) => setup({
+    force: Boolean(v.force),
+    piVersion: v["pi-version"],
+    installer: Boolean(v.installer)
+  }),
+  install: (p, v) => install(p, {
+    local: Boolean(v.local),
+    approve: Boolean(v.approve),
+    dryRun: Boolean(v["dry-run"])
+  }),
+  remove: (p, v) => remove(p, {
+    local: Boolean(v.local),
+    approve: Boolean(v.approve),
+    dryRun: Boolean(v["dry-run"])
+  }),
+  update: (p, v) => update(p, { catalogOnly: Boolean(v.catalog), dryRun: Boolean(v["dry-run"]) }),
+  list: (_p, v) => list({ json: Boolean(v.json) }),
+  doctor: (_p, v) => doctor({ json: Boolean(v.json) }),
+  init: (p, v) => init(p[0], {
+    name: v.name,
+    description: v.description
+  }),
+  completions: async (p) => {
+    if (!p[0]) {
+      throw usageError("Missing shell.", "Usage: pify completions <bash|zsh|fish|powershell>");
+    }
+    out(generateCompletion(p[0]));
+    return 0;
   }
-];
+};
+function findSpec(name) {
+  return COMMAND_SPECS.find((c) => c.name === name || c.aliases.includes(name));
+}
 async function main(argv) {
   const args = argv.filter((a) => a !== "--no-color");
   if (args.length !== argv.length) setColor(false);
@@ -1484,8 +1690,8 @@ async function main(argv) {
   if (first.startsWith("-")) {
     throw usageError(`Unknown option ${first}.`, 'Use "pify --help".');
   }
-  const command = COMMANDS.find((c) => c.name === first || c.aliases.includes(first));
-  if (!command) {
+  const spec = findSpec(first);
+  if (!spec) {
     throw usageError(
       `Unknown command: ${JSON.stringify(first)}`,
       'Run "pify --help" to see available commands.'
@@ -1493,26 +1699,26 @@ async function main(argv) {
   }
   const rest = args.slice(1);
   if (rest.includes("-h") || rest.includes("--help")) {
-    out(commandHelp(command.name));
+    out(commandHelp(spec.name));
     return 0;
   }
   let parsed;
   try {
     parsed = parseArgs({
       args: rest,
-      options: command.options,
-      allowPositionals: command.allowPositionals,
+      options: parseArgsOptionsFor(spec),
+      allowPositionals: spec.positional !== "none",
       strict: true
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const unknown = /Unknown option '(--?[^']+)'/.exec(message)?.[1];
     throw usageError(
-      unknown ? `Unknown option ${unknown} for "${command.name}".` : message,
-      `Use "pify --help" or "pify ${command.name} --help".`
+      unknown ? `Unknown option ${unknown} for "${spec.name}".` : message,
+      `Use "pify --help" or "pify ${spec.name} --help".`
     );
   }
-  return command.run(parsed.positionals, parsed.values);
+  return RUNNERS[spec.name](parsed.positionals, parsed.values);
 }
 main(process.argv.slice(2)).then((code) => {
   process.exitCode = code;

package/dist/index.d.ts

@@ -167,6 +167,39 @@ declare function assertSafeArg(arg: string, what?: string): void;
  */
 declare function which(command: string): string | null;
 
+declare function generateCompletion(shell: string): string;
+
+/**
+ * Declarative command surface — the single source of truth consumed by BOTH
+ * the argument parser (cli.ts) and the completion generator (completions.ts),
+ * so completions can never drift from the real CLI (oh-my-pi's principle).
+ */
+interface FlagSpec {
+    name: string;
+    short?: string;
+    /** Flag takes a value (e.g. --pi-version <version>). */
+    takesValue?: boolean;
+    description: string;
+}
+type PositionalKind = "none" | "packages" | "updateTargets" | "directory" | "shell";
+interface CommandSpec {
+    name: string;
+    aliases: string[];
+    description: string;
+    positional: PositionalKind;
+    flags: FlagSpec[];
+}
+declare const GLOBAL_FLAGS: FlagSpec[];
+declare const COMMAND_SPECS: CommandSpec[];
+declare const COMPLETION_SHELLS: readonly ["bash", "zsh", "fish", "powershell"];
+type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+/** Build the strict parseArgs options table for one command. */
+declare function parseArgsOptionsFor(spec: CommandSpec): Record<string, {
+    type: "boolean" | "string";
+    short?: string;
+    default?: boolean;
+}>;
+
 /**
  * The five `pify init` file templates, embedded as string literals so the
  * tarball ships nothing extra. Every line of the package.json template
@@ -211,4 +244,4 @@ declare class PifyError extends Error {
     constructor(message: string, code?: ExitCodeValue, hint?: string);
 }
 
-export { type Catalog, type CatalogPackage, ExitCode, INDEX_TS, type InstallSpec, type InstallTarget, type InstalledPifyPackage, NODE_FLOOR, PI_PACKAGE, type PiSettings, type PiStatus, PifyError, README_MD, TESTED_PI_VERSION, type TemplateVars, VERSION, agentDir, assertSafeArg, compareSemver, fetchLatestPiVersion, installPi, installedPifyPackages, installedVersionOnDisk, interpolate, isOffline, loadBundledCatalog, loadCatalog, npmInstallPiArgs, officialInstallerCommand, packageJsonTemplate, parseInstallSpec, piStatus, readSettings, refreshCatalog, resolveInstallTarget, resolvePifyName, updatePi, validateCatalog, which };
+export { COMMAND_SPECS, COMPLETION_SHELLS, type Catalog, type CatalogPackage, type CommandSpec, type CompletionShell, ExitCode, type FlagSpec, GLOBAL_FLAGS, INDEX_TS, type InstallSpec, type InstallTarget, type InstalledPifyPackage, NODE_FLOOR, PI_PACKAGE, type PiSettings, type PiStatus, PifyError, README_MD, TESTED_PI_VERSION, type TemplateVars, VERSION, agentDir, assertSafeArg, compareSemver, fetchLatestPiVersion, generateCompletion, installPi, installedPifyPackages, installedVersionOnDisk, interpolate, isOffline, loadBundledCatalog, loadCatalog, npmInstallPiArgs, officialInstallerCommand, packageJsonTemplate, parseArgsOptionsFor, parseInstallSpec, piStatus, readSettings, refreshCatalog, resolveInstallTarget, resolvePifyName, updatePi, validateCatalog, which };

package/dist/index.js

@@ -551,6 +551,244 @@ function installedVersionOnDisk(name, scope) {
   }
 }
 
+// src/registry.ts
+var GLOBAL_FLAGS = [
+  { name: "help", short: "h", description: "Show help" },
+  { name: "version", short: "v", description: "Print the pify version" },
+  { name: "no-color", description: "Disable colored output" }
+];
+var COMMAND_SPECS = [
+  {
+    name: "setup",
+    aliases: [],
+    description: "Install the pi coding agent (safe to re-run)",
+    positional: "none",
+    flags: [
+      { name: "force", description: "Reinstall pi even if present" },
+      { name: "pi-version", takesValue: true, description: "Install an exact pi version" },
+      { name: "installer", description: "Run pi's official interactive installer" }
+    ]
+  },
+  {
+    name: "install",
+    aliases: ["i", "add"],
+    description: "Install @pify packages by short name",
+    positional: "packages",
+    flags: [
+      { name: "local", short: "l", description: "Project scope" },
+      { name: "approve", short: "a", description: "Forward --approve to pi" },
+      { name: "dry-run", description: "Print the pi commands without running them" }
+    ]
+  },
+  {
+    name: "remove",
+    aliases: ["rm", "uninstall"],
+    description: "Remove installed @pify packages",
+    positional: "packages",
+    flags: [
+      { name: "local", short: "l", description: "Project scope" },
+      { name: "approve", short: "a", description: "Forward --approve to pi" },
+      { name: "dry-run", description: "Print the pi commands without running them" }
+    ]
+  },
+  {
+    name: "update",
+    aliases: ["up"],
+    description: "Update pi and installed @pify packages",
+    positional: "updateTargets",
+    flags: [
+      { name: "catalog", description: "Refresh the catalog cache only" },
+      { name: "dry-run", description: "Print the update plan without executing" }
+    ]
+  },
+  {
+    name: "list",
+    aliases: ["ls"],
+    description: "Show the @pify catalog with install state",
+    positional: "none",
+    flags: [{ name: "json", description: "Machine-readable output" }]
+  },
+  {
+    name: "doctor",
+    aliases: [],
+    description: "Diagnose the local pi/pify environment",
+    positional: "none",
+    flags: [{ name: "json", description: "Machine-readable output" }]
+  },
+  {
+    name: "init",
+    aliases: [],
+    description: "Scaffold a new Pi Package",
+    positional: "directory",
+    flags: [
+      { name: "name", takesValue: true, description: "npm package name" },
+      { name: "description", takesValue: true, description: "Package description" }
+    ]
+  },
+  {
+    name: "completions",
+    aliases: [],
+    description: "Print a shell completion script",
+    positional: "shell",
+    flags: []
+  }
+];
+var COMPLETION_SHELLS = ["bash", "zsh", "fish", "powershell"];
+function parseArgsOptionsFor(spec) {
+  const options = {};
+  for (const flag of spec.flags) {
+    options[flag.name] = flag.takesValue ? { type: "string", ...flag.short ? { short: flag.short } : {} } : { type: "boolean", default: false, ...flag.short ? { short: flag.short } : {} };
+  }
+  return options;
+}
+
+// src/completions.ts
+function packageNames() {
+  return loadBundledCatalog().packages.map((p) => p.name);
+}
+function allNames(spec) {
+  return [spec.name, ...spec.aliases];
+}
+function flagTokens(spec) {
+  return spec.flags.flatMap((f) => [`--${f.name}`, ...f.short ? [`-${f.short}`] : []]);
+}
+function positionalWords(spec) {
+  switch (spec.positional) {
+    case "packages":
+      return packageNames();
+    case "updateTargets":
+      return ["pi", ...packageNames()];
+    case "shell":
+      return [...COMPLETION_SHELLS];
+    default:
+      return [];
+  }
+}
+function bashScript() {
+  const commands = COMMAND_SPECS.flatMap(allNames).join(" ");
+  const cases = COMMAND_SPECS.map((spec) => {
+    const words = [...positionalWords(spec), ...flagTokens(spec)].join(" ");
+    return `    ${allNames(spec).join("|")}) words="${words}" ;;`;
+  }).join("\n");
+  return `# bash completion for pify \u2014 generated by \`pify completions bash\`
+# Install: eval "$(pify completions bash)"  (or save to a bash-completion dir)
+_pify_completions() {
+  local cur words
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=($(compgen -W "${commands} ${GLOBAL_FLAGS.map((f) => `--${f.name}`).join(" ")}" -- "$cur"))
+    return
+  fi
+  case "\${COMP_WORDS[1]}" in
+${cases}
+    *) words="" ;;
+  esac
+  COMPREPLY=($(compgen -W "$words" -- "$cur"))
+}
+complete -F _pify_completions pify
+`;
+}
+function zshScript() {
+  const commandDescs = COMMAND_SPECS.flatMap(
+    (spec) => allNames(spec).map((n) => `    '${n}:${spec.description.replace(/'/g, "")}'`)
+  ).join("\n");
+  const cases = COMMAND_SPECS.map((spec) => {
+    const words = [...positionalWords(spec), ...flagTokens(spec)].map((w) => `'${w}'`).join(" ");
+    return `    ${allNames(spec).join("|")}) _values 'value' ${words || "''"} ;;`;
+  }).join("\n");
+  return `#compdef pify
+# zsh completion for pify \u2014 generated by \`pify completions zsh\`
+# Install: eval "$(pify completions zsh)"  (or save into a directory on $fpath)
+_pify() {
+  local -a commands
+  commands=(
+${commandDescs}
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case "$words[2]" in
+${cases}
+  esac
+}
+_pify "$@"
+`;
+}
+function fishScript() {
+  const lines = [
+    `# fish completion for pify \u2014 generated by \`pify completions fish\``,
+    `# Install: pify completions fish > ~/.config/fish/completions/pify.fish`,
+    `complete -c pify -f`
+  ];
+  for (const spec of COMMAND_SPECS) {
+    for (const name of allNames(spec)) {
+      lines.push(
+        `complete -c pify -n __fish_use_subcommand -a ${name} -d '${spec.description.replace(/'/g, "")}'`
+      );
+    }
+    const condition = `__fish_seen_subcommand_from ${allNames(spec).join(" ")}`;
+    const words = positionalWords(spec);
+    if (words.length > 0) {
+      lines.push(`complete -c pify -n '${condition}' -a '${words.join(" ")}'`);
+    }
+    for (const flag of spec.flags) {
+      const short = flag.short ? ` -s ${flag.short}` : "";
+      lines.push(
+        `complete -c pify -n '${condition}' -l ${flag.name}${short} -d '${flag.description.replace(/'/g, "")}'`
+      );
+    }
+  }
+  for (const flag of GLOBAL_FLAGS) {
+    const short = flag.short ? ` -s ${flag.short}` : "";
+    lines.push(`complete -c pify -l ${flag.name}${short} -d '${flag.description.replace(/'/g, "")}'`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function powershellScript() {
+  const commands = COMMAND_SPECS.flatMap(allNames);
+  const caseBlocks = COMMAND_SPECS.map((spec) => {
+    const words = [...positionalWords(spec), ...flagTokens(spec)].map((w) => `'${w}'`).join(", ");
+    return `      ${allNames(spec).map((n) => `'${n}'`).join(" ")} { @(${words}) }`;
+  }).join("\n");
+  return `# PowerShell completion for pify \u2014 generated by \`pify completions powershell\`
+# Install: pify completions powershell | Out-String | Invoke-Expression  (add to $PROFILE)
+Register-ArgumentCompleter -Native -CommandName pify -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $tokens = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
+  $candidates = if ($tokens.Count -le 1 -or ($tokens.Count -eq 2 -and $wordToComplete)) {
+    @(${commands.map((c) => `'${c}'`).join(", ")})
+  } else {
+    switch ($tokens[1]) {
+${caseBlocks}
+      default { @() }
+    }
+  }
+  $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}
+`;
+}
+function generateCompletion(shell) {
+  switch (shell) {
+    case "bash":
+      return bashScript();
+    case "zsh":
+      return zshScript();
+    case "fish":
+      return fishScript();
+    case "powershell":
+      return powershellScript();
+    default:
+      throw usageError(
+        `Unknown shell ${JSON.stringify(shell)}.`,
+        `Usage: pify completions <${COMPLETION_SHELLS.join("|")}>`
+      );
+  }
+}
+
 // src/templates.ts
 function interpolate(template, vars) {
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
@@ -669,7 +907,10 @@ Then install anywhere with: pi install npm:{{name}}
 Tested with pi {{piVersion}}.
 `;
 export {
+  COMMAND_SPECS,
+  COMPLETION_SHELLS,
   ExitCode,
+  GLOBAL_FLAGS,
   INDEX_TS,
   NODE_FLOOR,
   PI_PACKAGE,
@@ -681,6 +922,7 @@ export {
   assertSafeArg,
   compareSemver,
   fetchLatestPiVersion,
+  generateCompletion,
   installPi,
   installedPifyPackages,
   installedVersionOnDisk,
@@ -691,6 +933,7 @@ export {
   npmInstallPiArgs,
   officialInstallerCommand,
   packageJsonTemplate,
+  parseArgsOptionsFor,
   parseInstallSpec,
   piStatus,
   readSettings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/cli",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Front door for the Pify suite: install and update the pi coding agent, manage @pify packages, and scaffold Pi Packages",
   "keywords": [
     "pify",