@pify/cli 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -92,10 +92,29 @@ declare function piStatus(): PiStatus;
 /** Latest pi version from pi's own release endpoint. Null offline/on error. */
 declare function fetchLatestPiVersion(): Promise<string | null>;
 declare function compareSemver(a: string, b: string): number;
+/** The official installer one-liner for this OS, for hints and --installer. */
+declare function officialInstallerCommand(): string;
 /**
- * Install pi globally via npm. This is the one operation pi cannot do for
- * itself — `pi update --self` requires a working pi. `--ignore-scripts`
- * matches pi's own self-update invocation (supply-chain-safe default).
+ * The npm install argv pi's official installers use:
+ * `--ignore-scripts` (supply-chain-safe; matches pi's self-update),
+ * `--min-release-age=0` (pi ships npm-shrinkwrap.json, so bypassing npm's
+ * release-age gate does not reopen transitive ranges; npm >= 11 only),
+ * `--no-fund --no-audit` (noise). Exported for tests.
+ */
+declare function npmInstallPiArgs(spec: string, npmMajor: number, prefix?: string): string[];
+/**
+ * Install pi with the same decisions as pi's official installers, minus the
+ * interactive parts. This is the one operation pi cannot do for itself —
+ * `pi update` requires a working pi.
+ *
+ * Per-OS behavior (ported from install.sh / install.ps1):
+ * - POSIX, npm prefix unwritable, no global pi there: fall back to
+ *   `--prefix ~/.local` — never sudo.
+ * - POSIX, npm prefix unwritable but an old global pi lives there: stop
+ *   (a ~/.local copy would be shadowed by the stale global one).
+ * - No npm but bun on PATH: `bun add -g --ignore-scripts` (documented
+ *   alternative channel).
+ * - Neither: point at the official installer, which can bootstrap Node too.
  */
 declare function installPi(version?: string): Promise<void>;
 /**
@@ -148,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
@@ -192,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, 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

@@ -34,21 +34,21 @@ var PifyError = class extends Error {
   code;
   /** Optional follow-up shown after the message, e.g. a command to run. */
   hint;
-  constructor(message, code = ExitCode.FAILURE, hint) {
+  constructor(message, code = ExitCode.FAILURE, hint2) {
     super(message);
     this.name = "PifyError";
     this.code = code;
-    this.hint = hint;
+    this.hint = hint2;
   }
 };
-function usageError(message, hint) {
-  return new PifyError(message, ExitCode.USAGE, hint);
+function usageError(message, hint2) {
+  return new PifyError(message, ExitCode.USAGE, hint2);
 }
-function environmentError(message, hint) {
-  return new PifyError(message, ExitCode.ENVIRONMENT, hint);
+function environmentError(message, hint2) {
+  return new PifyError(message, ExitCode.ENVIRONMENT, hint2);
 }
-function notFoundError(message, hint) {
-  return new PifyError(message, ExitCode.NOT_FOUND, hint);
+function notFoundError(message, hint2) {
+  return new PifyError(message, ExitCode.NOT_FOUND, hint2);
 }
 
 // src/exec.ts
@@ -305,9 +305,9 @@ function resolvePifyName(input) {
 }
 
 // src/pi.ts
-import { readFileSync as readFileSync2, realpathSync } from "fs";
+import { accessSync as accessSync2, constants as constants2, readFileSync as readFileSync2, realpathSync, statSync as statSync2 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join3 } from "path";
+import { dirname as dirname2, join as join3 } from "path";
 
 // src/ui.ts
 function detectColor(stream) {
@@ -340,6 +340,10 @@ function success(msg) {
   process.stdout.write(`${style.green(msg)}
 `);
 }
+function hint(msg) {
+  process.stdout.write(`${style.dim(msg)}
+`);
+}
 
 // src/pi.ts
 var PI_PACKAGE = "@earendil-works/pi-coding-agent";
@@ -388,38 +392,107 @@ function assertNodeVersion() {
     );
   }
 }
+function officialInstallerCommand() {
+  return isWindows ? 'powershell -c "irm https://pi.dev/install.ps1 | iex"' : "curl -fsSL https://pi.dev/install.sh | sh";
+}
+function writableOrCreatable(path) {
+  let current = path;
+  for (; ; ) {
+    try {
+      statSync2(current);
+      break;
+    } catch {
+      const parent = dirname2(current);
+      if (parent === current) return false;
+      current = parent;
+    }
+  }
+  try {
+    if (!statSync2(current).isDirectory()) return false;
+    accessSync2(current, constants2.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function npmInstallPiArgs(spec, npmMajor, prefix) {
+  const args = ["install", "-g", "--ignore-scripts"];
+  if (npmMajor >= 11) args.push("--min-release-age=0");
+  args.push("--no-fund", "--no-audit");
+  if (prefix) args.push("--prefix", prefix);
+  args.push(spec);
+  return args;
+}
+function npmMajorVersion() {
+  const res = runCapture("npm", ["--version"]);
+  const major = Number.parseInt(res.stdout.trim().split(".")[0] ?? "", 10);
+  return Number.isNaN(major) ? 0 : major;
+}
 async function installPi(version) {
   assertNodeVersion();
-  if (!which("npm")) {
-    throw environmentError(
-      "npm was not found on PATH.",
-      "Install Node.js (which bundles npm) from https://nodejs.org and retry."
-    );
-  }
   if (process.env.PI_MANAGED_INSTALL_ROOT && !piStatus().installed) {
     throw environmentError(
       "PI_MANAGED_INSTALL_ROOT is set but pi is not installed.",
-      "Use the managed installer: curl -fsSL https://pi.dev/install.sh | sh (Linux/macOS)."
+      `Use the official installer: ${officialInstallerCommand()}`
     );
   }
   const spec = version ? `${PI_PACKAGE}@${version}` : PI_PACKAGE;
-  step(`npm install -g --ignore-scripts ${spec}`);
-  const code = await runInherit("npm", ["install", "-g", "--ignore-scripts", spec]);
+  const npmPath = which("npm");
+  const bunPath = which("bun");
+  if (!npmPath && !bunPath) {
+    throw environmentError(
+      "Neither npm nor bun was found on PATH.",
+      `Run the official installer (it can install Node too): ${officialInstallerCommand()}`
+    );
+  }
+  let command;
+  let args;
+  let localPrefix = null;
+  if (npmPath) {
+    command = "npm";
+    if (!isWindows) {
+      const prefixRes = runCapture("npm", ["prefix", "-g"]);
+      const prefix = prefixRes.status === 0 ? prefixRes.stdout.trim() : "";
+      const prefixWritable = prefix !== "" && writableOrCreatable(join3(prefix, "lib", "node_modules")) && writableOrCreatable(join3(prefix, "bin"));
+      if (prefix && !prefixWritable) {
+        let staleGlobalPi = false;
+        try {
+          statSync2(join3(prefix, "bin", "pi"));
+          staleGlobalPi = true;
+        } catch {
+        }
+        if (staleGlobalPi) {
+          throw environmentError(
+            `npm's global directory is not writable (${prefix}) and pi is already installed there.`,
+            `Update or remove it first: sudo npm install -g --ignore-scripts ${PI_PACKAGE}`
+          );
+        }
+        localPrefix = join3(homedir2(), ".local");
+      }
+    }
+    args = npmInstallPiArgs(spec, npmMajorVersion(), localPrefix ?? void 0);
+  } else {
+    command = "bun";
+    args = ["add", "-g", "--ignore-scripts", spec];
+  }
+  step(`${command} ${args.join(" ")}`);
+  const code = await runInherit(command, args);
   if (code !== 0) {
     throw new PifyError(
-      `npm install -g ${spec} exited with code ${code}.`,
+      `${command} ${args[0]} exited with code ${code}.`,
       ExitCode.SUBPROCESS,
-      isWindows ? "If this is a permissions or file-lock error, close running pi sessions and retry from an elevated terminal." : "If this is an EACCES error, configure a user-writable npm prefix (https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) or use a Node version manager."
+      isWindows ? "If this is a permissions or file-lock error, close running pi sessions and retry from an elevated terminal." : `If the problem persists, try the official installer: ${officialInstallerCommand()}`
     );
   }
   const st = piStatus();
   if (!st.installed) {
-    throw environmentError(
-      "pi was installed but is not resolvable on PATH.",
-      "Add npm's global prefix to PATH (npm prefix -g) and open a new terminal."
-    );
+    const pathHint = localPrefix ? `Add ${join3(localPrefix, "bin")} to PATH and open a new terminal.` : "Add the global bin directory to PATH (npm prefix -g) and open a new terminal.";
+    throw environmentError("pi was installed but is not resolvable on PATH.", pathHint);
   }
   success(`pi ${st.version ?? ""} installed.`.replace("  ", " "));
+  if (localPrefix) {
+    hint(`Installed under ${localPrefix} because npm's global prefix is not writable.`);
+  }
 }
 async function updatePi() {
   const st = piStatus();
@@ -478,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) => {
@@ -596,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,
@@ -608,6 +922,7 @@ export {
   assertSafeArg,
   compareSemver,
   fetchLatestPiVersion,
+  generateCompletion,
   installPi,
   installedPifyPackages,
   installedVersionOnDisk,
@@ -615,7 +930,10 @@ export {
   isOffline,
   loadBundledCatalog,
   loadCatalog,
+  npmInstallPiArgs,
+  officialInstallerCommand,
   packageJsonTemplate,
+  parseArgsOptionsFor,
   parseInstallSpec,
   piStatus,
   readSettings,

package/package.json

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