@pify/cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,1419 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// src/pi.ts
+import { readFileSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+
+// src/exec.ts
+import { spawn, spawnSync } from "child_process";
+import { accessSync, constants, statSync } from "fs";
+import { delimiter, join } from "path";
+
+// src/errors.ts
+var ExitCode = {
+  OK: 0,
+  /** Generic / unexpected failure. */
+  FAILURE: 1,
+  /** Bad arguments, unknown command, malformed package name. */
+  USAGE: 2,
+  /** A required external program (pi, npm, node) is missing or too old. */
+  ENVIRONMENT: 3,
+  /** The requested package is not in the catalog or not yet published. */
+  NOT_FOUND: 4,
+  /** A delegated `pi` or `npm` subprocess exited non-zero. */
+  SUBPROCESS: 5
+};
+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, hint2) {
+    super(message);
+    this.name = "PifyError";
+    this.code = code;
+    this.hint = hint2;
+  }
+};
+function usageError(message, hint2) {
+  return new PifyError(message, ExitCode.USAGE, hint2);
+}
+function environmentError(message, hint2) {
+  return new PifyError(message, ExitCode.ENVIRONMENT, hint2);
+}
+function notFoundError(message, hint2) {
+  return new PifyError(message, ExitCode.NOT_FOUND, hint2);
+}
+
+// src/exec.ts
+var isWindows = process.platform === "win32";
+function isOffline() {
+  for (const name of ["PIFY_OFFLINE", "PI_OFFLINE"]) {
+    const v = process.env[name];
+    if (v && /^(1|true|yes)$/i.test(v)) return true;
+  }
+  return false;
+}
+var SAFE_ARG = /^[A-Za-z0-9@._:/\\+=-]+$/;
+function assertSafeArg(arg, what = "argument") {
+  if (!SAFE_ARG.test(arg)) {
+    throw new PifyError(
+      `Refusing to pass unsafe ${what} to a subprocess: ${JSON.stringify(arg)}`,
+      ExitCode.USAGE,
+      "Package names may contain letters, digits and @ . _ : / \\ + = - only."
+    );
+  }
+}
+function spawnPlan(command, args) {
+  assertSafeArg(command, "command");
+  args.forEach((a) => assertSafeArg(a));
+  return isWindows ? [`${command} ${args.join(" ")}`.trim(), [], { shell: true }] : [command, args, { shell: false }];
+}
+function runCapture(command, args) {
+  const [cmd, argv, opts] = spawnPlan(command, args);
+  const res = spawnSync(cmd, argv, {
+    ...opts,
+    encoding: "utf8",
+    windowsHide: true
+  });
+  return {
+    status: res.status ?? (res.error ? 127 : 1),
+    stdout: res.stdout ?? "",
+    stderr: res.stderr ?? ""
+  };
+}
+function runInherit(command, args) {
+  const [cmd, argv, opts] = spawnPlan(command, args);
+  return new Promise((resolve2, reject) => {
+    const child = spawn(cmd, argv, {
+      ...opts,
+      stdio: "inherit",
+      windowsHide: true
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve2(code ?? 1));
+  });
+}
+function which(command) {
+  const dirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+  if (isWindows) {
+    const exts = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    for (const dir of dirs) {
+      const candidates = command.includes(".") ? [join(dir, command)] : exts.map((ext) => join(dir, command + ext));
+      for (const candidate of candidates) {
+        try {
+          if (statSync(candidate).isFile()) return candidate;
+        } catch {
+        }
+      }
+    }
+    return null;
+  }
+  for (const dir of dirs) {
+    const candidate = join(dir, command);
+    try {
+      if (!statSync(candidate).isFile()) continue;
+      accessSync(candidate, constants.X_OK);
+      return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+
+// src/ui.ts
+function detectColor(stream) {
+  const { NO_COLOR, FORCE_COLOR, TERM } = process.env;
+  if (FORCE_COLOR !== void 0 && FORCE_COLOR !== "0") return true;
+  if (NO_COLOR !== void 0 && NO_COLOR !== "") return false;
+  if (TERM === "dumb") return false;
+  return Boolean(stream.isTTY);
+}
+var stdoutColor = detectColor(process.stdout);
+var stderrColor = detectColor(process.stderr);
+function setColor(enabled) {
+  stdoutColor = enabled;
+  stderrColor = enabled;
+}
+function palette(enabled) {
+  const wrap = (open, close) => (s) => enabled() ? `[${open}m${s}[${close}m` : s;
+  return {
+    bold: wrap("1", "22"),
+    dim: wrap("2", "22"),
+    red: wrap("31", "39"),
+    green: wrap("32", "39"),
+    yellow: wrap("33", "39"),
+    cyan: wrap("36", "39")
+  };
+}
+var style = palette(() => stdoutColor);
+var estyle = palette(() => stderrColor);
+function out(msg = "") {
+  process.stdout.write(`${msg}
+`);
+}
+function step(command) {
+  process.stdout.write(`${style.dim(`$ ${command}`)}
+`);
+}
+function success(msg) {
+  process.stdout.write(`${style.green(msg)}
+`);
+}
+function hint(msg) {
+  process.stdout.write(`${style.dim(msg)}
+`);
+}
+function warn(msg) {
+  process.stderr.write(`${estyle.yellow(`Warning: ${msg}`)}
+`);
+}
+function error(msg) {
+  process.stderr.write(`${estyle.red(`Error: ${msg}`)}
+`);
+}
+function errorHint(msg) {
+  process.stderr.write(`${estyle.dim(msg)}
+`);
+}
+
+// src/version.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var VERSION = require2("../package.json").version;
+
+// src/pi.ts
+var PI_PACKAGE = "@earendil-works/pi-coding-agent";
+var NODE_FLOOR = "22.19.0";
+var TESTED_PI_VERSION = "0.84.4";
+var LATEST_VERSION_URL = "https://pi.dev/api/latest-version";
+function piStatus() {
+  const binPath = which("pi");
+  if (!binPath) return { installed: false, binPath: null, version: null };
+  const res = runCapture("pi", ["--version"]);
+  const version = res.status === 0 ? res.stdout.trim() || null : null;
+  return { installed: true, binPath, version };
+}
+async function fetchLatestPiVersion() {
+  if (isOffline()) return null;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5e3);
+    const res = await fetch(LATEST_VERSION_URL, {
+      signal: controller.signal,
+      headers: { "user-agent": `pify/${VERSION}` }
+    });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  }
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map((n) => Number.parseInt(n, 10));
+  const pb = b.split(".").map((n) => Number.parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function assertNodeVersion() {
+  const current = process.versions.node;
+  if (compareSemver(current, NODE_FLOOR) < 0) {
+    throw environmentError(
+      `The pi coding agent requires Node >= ${NODE_FLOOR}; you are running ${current}.`,
+      "Upgrade Node (e.g. via nvm / nvm-windows) and try again."
+    );
+  }
+}
+function npmPrefixEvidence(binPath) {
+  const res = runCapture("npm", ["prefix", "-g"]);
+  const prefix = res.status === 0 ? res.stdout.trim() : "";
+  if (!prefix) return { managed: false, prefix: null };
+  const resolve2 = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  const normalize = (p) => isWindows ? p.toLowerCase() : p;
+  const managed = normalize(resolve2(binPath)).startsWith(normalize(resolve2(prefix)));
+  return { managed, prefix };
+}
+function guardNpmManaged(binPath) {
+  if (process.env.PI_MANAGED_INSTALL_ROOT) {
+    throw environmentError("pi is a managed install; pify will not overwrite it.");
+  }
+  if (!npmPrefixEvidence(binPath).managed) {
+    throw environmentError(
+      `pi at ${binPath} is not managed by npm; refusing to install over it.`,
+      "Update it with the package manager that installed it (pnpm/yarn/bun), or remove it first."
+    );
+  }
+}
+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)."
+    );
+  }
+  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]);
+  if (code !== 0) {
+    throw new PifyError(
+      `npm install -g ${spec} 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."
+    );
+  }
+  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."
+    );
+  }
+  success(`pi ${st.version ?? ""} installed.`.replace("  ", " "));
+}
+function requirePi() {
+  if (!piStatus().installed) {
+    throw environmentError(
+      "The pi coding agent is not installed.",
+      "Run pify setup to install it."
+    );
+  }
+}
+function delegate(args) {
+  return runInherit("pi", args);
+}
+function agentDir() {
+  const override = process.env.PI_CODING_AGENT_DIR;
+  if (override) {
+    return override.startsWith("~") ? join2(homedir(), override.slice(1).replace(/^[/\\]/, "")) : override;
+  }
+  return join2(homedir(), ".pi", "agent");
+}
+function settingsPath(scope) {
+  return scope === "user" ? join2(agentDir(), "settings.json") : join2(process.cwd(), ".pi", "settings.json");
+}
+function readSettings(scope) {
+  try {
+    return JSON.parse(readFileSync(settingsPath(scope), "utf8"));
+  } catch {
+    return null;
+  }
+}
+var PIFY_SOURCE = /^npm:@pify\/([A-Za-z0-9._-]+?)(?:@(.+))?$/;
+function installedPifyPackages() {
+  const result = /* @__PURE__ */ new Map();
+  for (const scope of ["user", "project"]) {
+    const settings = readSettings(scope);
+    for (const entry of settings?.packages ?? []) {
+      const source = typeof entry === "string" ? entry : entry.source;
+      if (typeof source !== "string") continue;
+      const match = PIFY_SOURCE.exec(source);
+      const name = match?.[1];
+      if (!name) continue;
+      result.set(name, { name, scope, source, pin: match?.[2] ?? null });
+    }
+  }
+  return result;
+}
+function installedVersionOnDisk(name, scope) {
+  const root = scope === "user" ? join2(agentDir(), "npm") : join2(process.cwd(), ".pi", "npm");
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join2(root, "node_modules", "@pify", name, "package.json"), "utf8")
+    );
+    return { present: true, version: typeof pkg.version === "string" ? pkg.version : null };
+  } catch {
+    return { present: false, version: null };
+  }
+}
+
+// src/commands/setup.ts
+async function setup(opts) {
+  assertNodeVersion();
+  if (!which("npm")) {
+    throw environmentError(
+      "npm was not found on PATH.",
+      "Install Node.js (which bundles npm) from https://nodejs.org and retry."
+    );
+  }
+  const st = piStatus();
+  if (st.installed && !opts.force && !opts.piVersion) {
+    success(`pi ${st.version ?? "(unknown version)"} is already installed at ${st.binPath}`);
+    const latest = await fetchLatestPiVersion();
+    if (latest && st.version && compareSemver(st.version, latest) < 0) {
+      out(style.yellow(`Update available: ${st.version} -> ${latest} - run pify update pi`));
+    }
+    hint("Next: pify list to see available packages.");
+    return 0;
+  }
+  if (st.installed && opts.piVersion && st.version === opts.piVersion) {
+    success(`pi ${opts.piVersion} is already installed.`);
+    return 0;
+  }
+  if (st.installed && st.binPath) {
+    guardNpmManaged(st.binPath);
+  }
+  await installPi(opts.piVersion);
+  hint("Next: pify list to see available packages.");
+  return 0;
+}
+
+// src/catalog.ts
+import { readFileSync as readFileSync2, writeFileSync, mkdirSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname, join as join3 } from "path";
+import { fileURLToPath } from "url";
+function bundledCatalogPath() {
+  return join3(dirname(fileURLToPath(import.meta.url)), "..", "catalog.json");
+}
+function cachePath() {
+  return join3(homedir2(), ".pify", "catalog.json");
+}
+var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+function loadBundledCatalog() {
+  return JSON.parse(readFileSync2(bundledCatalogPath(), "utf8"));
+}
+function validateCatalog(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const c = data;
+  if (!Number.isInteger(c.version)) return false;
+  if (!Array.isArray(c.packages)) return false;
+  for (const entry of c.packages) {
+    if (typeof entry !== "object" || entry === null) return false;
+    const p = entry;
+    if (typeof p.name !== "string" || !/^[a-z0-9-]+$/.test(p.name)) return false;
+    if (typeof p.npm !== "string" || !p.npm.startsWith("@pify/")) return false;
+    if (p.status !== "published" && p.status !== "planned") return false;
+  }
+  return true;
+}
+async function loadCatalog(opts = {}) {
+  const bundled = loadBundledCatalog();
+  const cached = readCache();
+  let remote = cached?.catalog ?? null;
+  const stale = !cached || Date.now() - cached.fetchedAt > CACHE_TTL_MS;
+  if (opts.refresh || stale) {
+    const fetched = await fetchRemoteCatalog(bundled.remote, opts.refresh ? 1e4 : 3e3);
+    if (fetched) {
+      remote = fetched;
+      writeCache(fetched);
+    }
+  }
+  if (!remote || !validateCatalog(remote)) return bundled;
+  return remote.version >= bundled.version ? remote : bundled;
+}
+async function refreshCatalog() {
+  const bundled = loadBundledCatalog();
+  const fetched = await fetchRemoteCatalog(bundled.remote, 1e4);
+  if (fetched) {
+    writeCache(fetched);
+    return { ok: true, catalog: fetched };
+  }
+  const cached = readCache();
+  const fallback = cached && validateCatalog(cached.catalog) && cached.catalog.version >= bundled.version ? cached.catalog : bundled;
+  return { ok: false, catalog: fallback };
+}
+async function fetchRemoteCatalog(defaultUrl, timeoutMs) {
+  if (isOffline()) return null;
+  const url = process.env.PIFY_CATALOG_URL || defaultUrl;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return validateCatalog(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+function readCache() {
+  try {
+    const parsed = JSON.parse(readFileSync2(cachePath(), "utf8"));
+    if (typeof parsed.fetchedAt !== "number" || !validateCatalog(parsed.catalog)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function writeCache(catalog) {
+  try {
+    mkdirSync(dirname(cachePath()), { recursive: true });
+    writeFileSync(cachePath(), JSON.stringify({ fetchedAt: Date.now(), catalog }, null, 2));
+  } catch {
+  }
+}
+var EXACT_VERSION = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+var DIST_TAG = /^[a-z][a-z0-9._-]*$/i;
+function parseInstallSpec(input) {
+  const raw = input.startsWith("npm:") ? input.slice(4) : input;
+  const at = raw.indexOf("@", raw.startsWith("@") ? 1 : 0);
+  const base = at > 0 ? raw.slice(0, at) : raw;
+  const pin = at > 0 ? raw.slice(at + 1) : null;
+  if (pin !== null && !EXACT_VERSION.test(pin) && !(DIST_TAG.test(pin) && !/^\d/.test(pin))) {
+    throw usageError(
+      "Version pins must be exact versions or dist-tags.",
+      `Got ${JSON.stringify(pin)} - ranges (^, ~, >, <, *, x) are not supported.`
+    );
+  }
+  return { base, pin };
+}
+function resolveInstallTarget(catalog, input) {
+  const { base, pin } = parseInstallSpec(input);
+  if (base.startsWith("@")) {
+    if (!base.startsWith("@pify/")) {
+      throw usageError(
+        "pify installs @pify packages only.",
+        `For other sources use: pi install ${input}`
+      );
+    }
+    const shortName = base.slice("@pify/".length).toLowerCase();
+    if (!/^[a-z0-9._-]+$/.test(shortName)) {
+      throw usageError(`Invalid package name: ${JSON.stringify(base)}`);
+    }
+    const entry2 = catalog.packages.find((p) => p.name === shortName) ?? null;
+    return {
+      shortName,
+      npm: `@pify/${shortName}`,
+      pin,
+      explicit: true,
+      inCatalog: entry2 !== null,
+      status: entry2?.status ?? null,
+      repo: entry2?.repo ?? null
+    };
+  }
+  if (/[:/\\]/.test(base)) {
+    throw usageError(
+      "pify installs @pify packages only.",
+      `For other sources use: pi install ${input}`
+    );
+  }
+  const needle = base.toLowerCase();
+  const entry = catalog.packages.find((p) => p.name === needle || `pify-${p.name}` === needle) ?? null;
+  if (!entry) {
+    const names = catalog.packages.map((p) => p.name).join(", ");
+    throw notFoundError(
+      `Unknown pify package: ${JSON.stringify(input)}`,
+      `Available: ${names}`
+    );
+  }
+  if (entry.status !== "published") {
+    throw notFoundError(
+      `@pify/${entry.name} is not published yet.`,
+      `Track it at ${entry.repo}. Run "pify update --catalog" to refresh availability.`
+    );
+  }
+  return {
+    shortName: entry.name,
+    npm: entry.npm,
+    pin,
+    explicit: false,
+    inCatalog: true,
+    status: entry.status,
+    repo: entry.repo
+  };
+}
+function resolvePifyName(input) {
+  const { base } = parseInstallSpec(input);
+  if (base.startsWith("@")) {
+    if (!base.startsWith("@pify/")) {
+      throw usageError(
+        "pify manages @pify packages only.",
+        `For other sources use the pi CLI directly.`
+      );
+    }
+    const shortName = base.slice("@pify/".length).toLowerCase();
+    if (!/^[a-z0-9._-]+$/.test(shortName)) {
+      throw usageError(`Invalid package name: ${JSON.stringify(base)}`);
+    }
+    return shortName;
+  }
+  if (/[:/\\]/.test(base)) {
+    throw usageError(
+      "pify manages @pify packages only.",
+      `For other sources use the pi CLI directly.`
+    );
+  }
+  const name = base.toLowerCase();
+  return name.startsWith("pify-") ? name.slice("pify-".length) : name;
+}
+
+// src/commands/install.ts
+function piArgs(target, opts) {
+  const spec = target.pin ? `npm:${target.npm}@${target.pin}` : `npm:${target.npm}`;
+  const args = ["install", spec];
+  if (opts.local) args.push("-l");
+  if (opts.approve) args.push("-a");
+  return args;
+}
+async function install(names, opts) {
+  if (names.length === 0) {
+    throw usageError("Missing package name.", "Usage: pify install <name...> [-l] [-a]");
+  }
+  const catalog = await loadCatalog();
+  const targets = names.map((name) => resolveInstallTarget(catalog, name));
+  for (const target of targets) {
+    if (target.explicit && (!target.inCatalog || target.status !== "published")) {
+      warn(`${target.npm} is not in the catalog (or not marked published); installing anyway.`);
+    }
+  }
+  requirePi();
+  if (opts.dryRun) {
+    for (const target of targets) out(`pi ${piArgs(target, opts).join(" ")}`);
+    return 0;
+  }
+  const failed = [];
+  for (const target of targets) {
+    const args = piArgs(target, opts);
+    step(`pi ${args.join(" ")}`);
+    const code = await delegate(args);
+    if (code !== 0) failed.push(target.shortName);
+  }
+  if (failed.length > 0) {
+    throw new PifyError(
+      `Installed ${targets.length - failed.length} of ${targets.length}; failed: ${failed.join(", ")}`,
+      ExitCode.SUBPROCESS
+    );
+  }
+  return 0;
+}
+
+// src/commands/remove.ts
+var PIFY_SOURCE2 = /^npm:@pify\/([A-Za-z0-9._-]+?)(?:@.+)?$/;
+function configuredNames(scope) {
+  const names = /* @__PURE__ */ new Set();
+  for (const entry of readSettings(scope)?.packages ?? []) {
+    const source = typeof entry === "string" ? entry : entry.source;
+    if (typeof source !== "string") continue;
+    const name = PIFY_SOURCE2.exec(source)?.[1];
+    if (name) names.add(name);
+  }
+  return names;
+}
+async function remove(names, opts) {
+  if (names.length === 0) {
+    throw usageError("Missing package name.", "Usage: pify remove <name...> [-l] [-a]");
+  }
+  const targets = names.map(resolvePifyName);
+  const scope = opts.local ? "project" : "user";
+  const installed = configuredNames(scope);
+  for (const name of targets) {
+    if (!installed.has(name)) {
+      const scopeNote = opts.local ? " in project scope" : "";
+      throw notFoundError(
+        `${name} is not installed${scopeNote}.`,
+        installed.size > 0 ? `Installed @pify packages: ${[...installed].sort().join(", ")}` : "Nothing from @pify is installed."
+      );
+    }
+  }
+  requirePi();
+  const argsFor = (name) => {
+    const args = ["remove", `npm:@pify/${name}`];
+    if (opts.local) args.push("-l");
+    if (opts.approve) args.push("-a");
+    return args;
+  };
+  if (opts.dryRun) {
+    for (const name of targets) out(`pi ${argsFor(name).join(" ")}`);
+    return 0;
+  }
+  const failed = [];
+  for (const name of targets) {
+    const args = argsFor(name);
+    step(`pi ${args.join(" ")}`);
+    const code = await delegate(args);
+    if (code !== 0) failed.push(name);
+  }
+  if (failed.length > 0) {
+    throw new PifyError(
+      `Removed ${targets.length - failed.length} of ${targets.length}; failed: ${failed.join(", ")}`,
+      ExitCode.SUBPROCESS
+    );
+  }
+  return 0;
+}
+
+// src/commands/update.ts
+async function update(targets, opts) {
+  if (isOffline()) {
+    warn("PIFY_OFFLINE/PI_OFFLINE is set - updates skipped.");
+    return 0;
+  }
+  if (opts.catalogOnly) {
+    if (targets.length > 0) {
+      throw usageError("--catalog cannot be combined with update targets.");
+    }
+    const { ok, catalog } = await refreshCatalog();
+    if (ok) {
+      out(`Catalog refreshed (version ${catalog.version}, ${catalog.packages.length} packages).`);
+    } else {
+      warn("Could not refresh the catalog; using the existing copy.");
+    }
+    return 0;
+  }
+  const updateEverything = targets.length === 0;
+  const piOnly = targets.length === 1 && (targets[0] === "pi" || targets[0] === "self");
+  const installed = installedPifyPackages();
+  let packageNames = [];
+  if (updateEverything) {
+    packageNames = [...installed.keys()].sort();
+  } else if (!piOnly) {
+    packageNames = targets.map(resolvePifyName);
+    for (const name of packageNames) {
+      if (!installed.has(name)) {
+        throw notFoundError(`${name} is not installed.`, `pify install ${name}`);
+      }
+    }
+  }
+  if (opts.dryRun) {
+    if (updateEverything || piOnly) out("pi update");
+    for (const name of packageNames) out(`pi update npm:@pify/${name}`);
+    if (updateEverything) out("refresh catalog");
+    return 0;
+  }
+  const failed = [];
+  if (updateEverything || piOnly) {
+    if (!piStatus().installed) {
+      await installPi();
+    } else {
+      step("pi update");
+      const code = await delegate(["update"]);
+      if (code !== 0) failed.push("pi");
+    }
+  }
+  if (packageNames.length > 0 && !piStatus().installed) {
+    throw new PifyError(
+      "pi is required to update packages.",
+      ExitCode.ENVIRONMENT,
+      "Run pify setup first."
+    );
+  }
+  for (const name of packageNames) {
+    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) {
+    hint("No @pify packages installed; nothing more to update.");
+  }
+  if (updateEverything) {
+    await loadCatalog({ refresh: true });
+  }
+  if (failed.length > 0) {
+    throw new PifyError(`Update failed for: ${failed.join(", ")}`, ExitCode.SUBPROCESS);
+  }
+  success("Everything is up to date.");
+  return 0;
+}
+
+// src/commands/list.ts
+async function list(opts) {
+  const catalog = await loadCatalog();
+  const installed = installedPifyPackages();
+  const rows = catalog.packages.map((pkg) => {
+    const entry = installed.get(pkg.name);
+    if (!entry) {
+      return { name: pkg.name, npm: pkg.npm, description: pkg.description, repo: pkg.repo, status: pkg.status, installed: null };
+    }
+    const disk = installedVersionOnDisk(pkg.name, entry.scope);
+    return {
+      name: pkg.name,
+      npm: pkg.npm,
+      description: pkg.description,
+      repo: pkg.repo,
+      status: pkg.status,
+      installed: {
+        scope: entry.scope,
+        version: disk.version,
+        pinned: entry.pin !== null,
+        missingOnDisk: !disk.present
+      }
+    };
+  });
+  for (const [name, entry] of installed) {
+    if (rows.some((r) => r.name === name)) continue;
+    const disk = installedVersionOnDisk(name, entry.scope);
+    rows.push({
+      name,
+      npm: `@pify/${name}`,
+      description: "(not in catalog)",
+      repo: null,
+      status: null,
+      installed: {
+        scope: entry.scope,
+        version: disk.version,
+        pinned: entry.pin !== null,
+        missingOnDisk: !disk.present
+      }
+    });
+  }
+  if (opts.json) {
+    out(JSON.stringify(rows, null, 2));
+    return 0;
+  }
+  out(style.bold(`@pify packages (${catalog.org})`));
+  out();
+  const nameWidth = rows.reduce((m, r) => Math.max(m, r.name.length), 0) + 2;
+  const stateOf = (r) => {
+    if (r.installed) {
+      if (r.installed.missingOnDisk) {
+        return { text: `missing on disk (${r.installed.scope})`, paint: style.red };
+      }
+      const ver = r.installed.version ?? "?";
+      const pin = r.installed.pinned ? " pinned" : "";
+      return { text: `installed ${ver} (${r.installed.scope})${pin}`, paint: style.green };
+    }
+    if (r.status === "published") return { text: "available", paint: (s) => s };
+    return { text: "planned", paint: style.dim };
+  };
+  const stateWidth = rows.reduce((m, r) => Math.max(m, stateOf(r).text.length), 0) + 2;
+  for (const r of rows) {
+    const { text, paint } = stateOf(r);
+    out(`  ${r.name.padEnd(nameWidth)}${paint(text.padEnd(stateWidth))}${style.dim(r.description)}`);
+  }
+  out();
+  hint("Install with: pify install <name>");
+  return 0;
+}
+
+// src/commands/doctor.ts
+import { existsSync } from "fs";
+async function doctor(opts) {
+  const checks = [];
+  const push = (id, status, detail) => checks.push({ id, status, detail });
+  const nodeOk = compareSemver(process.versions.node, NODE_FLOOR) >= 0;
+  push(
+    "node",
+    nodeOk ? "ok" : "fail",
+    nodeOk ? `v${process.versions.node} (>= ${NODE_FLOOR} required)` : `v${process.versions.node} - pi requires >= ${NODE_FLOOR}; upgrade Node`
+  );
+  const npmPath = which("npm");
+  if (npmPath) {
+    const ver = runCapture("npm", ["--version"]);
+    push("npm", "ok", `${ver.status === 0 ? `v${ver.stdout.trim()} at ` : ""}${npmPath}`);
+  } else {
+    push("npm", "fail", "not found on PATH - install Node.js from https://nodejs.org");
+  }
+  const gitPath = which("git");
+  push(
+    "git",
+    gitPath ? "ok" : "warn",
+    gitPath ?? "git not found - pi's git: package sources will not work"
+  );
+  const pi = piStatus();
+  if (!pi.installed) {
+    push("pi", "fail", "not installed - run: pify setup");
+  } else if (!pi.version) {
+    push("pi", "fail", `pi found at ${pi.binPath} but "pi --version" failed (broken install)`);
+  } else {
+    push("pi", "ok", `pi ${pi.version} at ${pi.binPath}`);
+  }
+  if (isOffline()) {
+    push("pi-latest", "info", "skipped (offline)");
+  } else {
+    const latest = await fetchLatestPiVersion();
+    if (!latest) {
+      push("pi-latest", "warn", "could not reach pi.dev to check the latest version");
+    } else if (pi.version && compareSemver(pi.version, latest) < 0) {
+      push("pi-latest", "warn", `pi ${pi.version} installed, ${latest} available - run pify update pi`);
+    } else {
+      push("pi-latest", "ok", `pi ${latest} is current`);
+    }
+  }
+  if (process.env.PI_MANAGED_INSTALL_ROOT) {
+    push("pi-install-method", "info", "managed install (PI_MANAGED_INSTALL_ROOT)");
+  } else if (pi.binPath) {
+    const { managed, prefix } = npmPrefixEvidence(pi.binPath);
+    push(
+      "pi-install-method",
+      "info",
+      managed ? `npm global (${prefix})` : "unrecognized (self-update is delegated to pi either way)"
+    );
+  } else {
+    push("pi-install-method", "info", "n/a (pi not installed)");
+  }
+  for (const scope of ["user", "project"]) {
+    const id = scope === "user" ? "settings-user" : "settings-project";
+    const path = settingsPath(scope);
+    if (!existsSync(path)) {
+      push(id, "info", scope === "user" ? "not found (run pi once to create it)" : "none");
+      continue;
+    }
+    const settings = readSettings(scope);
+    if (settings === null) {
+      push(id, "warn", `${path} is unparseable JSON`);
+    } else {
+      push(id, "ok", `${path} (${settings.packages?.length ?? 0} packages configured)`);
+    }
+  }
+  const installed = installedPifyPackages();
+  if (installed.size === 0) {
+    push("pify-packages", "info", "no @pify packages configured yet");
+  } else {
+    const missing = [...installed.values()].filter(
+      (p) => !installedVersionOnDisk(p.name, p.scope).present
+    );
+    if (missing.length > 0) {
+      push(
+        "pify-packages",
+        "fail",
+        `missing on disk: ${missing.map((p) => p.name).join(", ")} - run pify install <name> to repair`
+      );
+    } else {
+      push("pify-packages", "ok", `${installed.size} configured, all present on disk`);
+    }
+  }
+  const envVars = ["PI_OFFLINE", "PIFY_OFFLINE", "PI_CODING_AGENT_DIR", "NO_COLOR", "PIFY_CATALOG_URL"].filter((name) => process.env[name] !== void 0).map((name) => `${name}=${process.env[name]}`);
+  push("env", "info", envVars.length > 0 ? envVars.join(", ") : "none set");
+  const problems = checks.filter((c) => c.status === "fail").length;
+  if (opts.json) {
+    out(JSON.stringify({ pify: VERSION, agentDir: agentDir(), checks, problems }, null, 2));
+    return problems > 0 ? 1 : 0;
+  }
+  out(style.bold("pify doctor"));
+  out();
+  const paint = {
+    ok: style.green,
+    warn: style.yellow,
+    fail: style.red,
+    info: style.dim
+  };
+  const idWidth = checks.reduce((m, c) => Math.max(m, c.id.length), 0) + 2;
+  for (const c of checks) {
+    out(`  ${paint[c.status](c.status.padEnd(6))}${c.id.padEnd(idWidth)}${style.dim(c.detail)}`);
+  }
+  out();
+  if (problems > 0) {
+    out(style.red(`${problems} problem${problems > 1 ? "s" : ""} found.`));
+    return 1;
+  }
+  out(style.green("Everything looks good."));
+  return 0;
+}
+
+// src/commands/init.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, writeFileSync as writeFileSync2 } from "fs";
+import { basename, join as join4, resolve } from "path";
+
+// src/templates.ts
+function interpolate(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = vars[key];
+    if (value === void 0) throw new Error(`Unknown template variable: ${key}`);
+    return value;
+  });
+}
+function packageJsonTemplate(scoped) {
+  const publishConfig = scoped ? `
+  "publishConfig": { "access": "public" },` : "";
+  return `{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "description": "{{description}}",
+  "type": "module",
+  "keywords": ["pi-package", "pi-extension", "pi", "pify"],
+  "license": "MIT",${publishConfig}
+  "files": ["index.ts", "src"],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "engines": { "node": ">=22.19.0" },
+  "scripts": { "typecheck": "tsc --noEmit" },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": { "optional": true },
+    "@earendil-works/pi-agent-core": { "optional": true },
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typescript": "^5.7.2",
+    "@types/node": "^22.10.2"
+  }
+}
+`;
+}
+var INDEX_TS = `import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Rules this template already follows:
+// - Signal tool errors by THROWING from execute(); returned values never set isError.
+// - Truncate large output with truncateHead/truncateTail from
+//   @earendil-works/pi-coding-agent (built-in limits: 50 KB / 2000 lines).
+// - Use StringEnum from @earendil-works/pi-ai for enum parameters;
+//   Type.Union/Type.Literal breaks on Google's API.
+// - Use the CONFIG_DIR_NAME export instead of hardcoding ".pi" for
+//   project-local config paths.
+const exampleTool = defineTool({
+  name: "{{snakeName}}_hello",
+  label: "{{shortName}} hello",
+  description: "Example tool for {{name}}. Replace with your own.",
+  parameters: Type.Object({
+    name: Type.String({ description: "Name to greet" }),
+  }),
+  async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+    return {
+      content: [{ type: "text", text: \`Hello, \${params.name}!\` }],
+      details: { greeted: params.name },
+    };
+  },
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool(exampleTool);
+
+  pi.registerCommand("{{shortName}}-hello", {
+    description: "Example command for {{name}}. Replace with your own.",
+    handler: async (args, _ctx) => {
+      // \`args\` is the single raw string typed after the command name.
+      // There is no argv parsing - split it yourself if you need arguments.
+    },
+  });
+
+  // Never start watchers, sockets, timers, or child processes here in the
+  // factory: it can run in invocations that never start a session.
+  pi.on("session_start", async (_event, _ctx) => {
+    // Start background resources here.
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    // Tear them down here. This must be idempotent: it fires on quit,
+    // /reload, /new, /resume, and /fork.
+  });
+}
+`;
+var TSCONFIG_JSON = `{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "types": ["node"]
+  },
+  "include": ["index.ts", "src/**/*.ts"]
+}
+`;
+var GITIGNORE = `node_modules/
+`;
+var README_MD = `# {{name}}
+
+{{description}}
+
+A Pi Package for the pi coding agent (https://pi.dev).
+
+## Develop
+
+    npm install              # dev dependencies for typechecking
+    pi install ./{{dir}}     # register locally; hot-reloads with /reload
+    pi -e ./index.ts         # or load ad hoc for a single run
+    npm run typecheck
+
+## Publish
+
+    npm publish --access public
+
+Then install anywhere with: pi install npm:{{name}}
+
+Tested with pi {{piVersion}}.
+`;
+
+// src/commands/init.ts
+var NPM_NAME = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+async function init(dirArg, opts) {
+  const dir = dirArg ?? ".";
+  const target = resolve(dir);
+  if (existsSync2(target) && readdirSync(target).length > 0) {
+    throw new PifyError(
+      `Target directory ${JSON.stringify(dir)} is not empty.`,
+      ExitCode.FAILURE,
+      "Choose a new directory: pify init my-extension"
+    );
+  }
+  const name = (opts.name ?? basename(target)).toLowerCase();
+  if (!NPM_NAME.test(name)) {
+    throw usageError(
+      `Invalid npm package name: ${JSON.stringify(name)}`,
+      "Pass a valid name explicitly: pify init <dir> --name my-pi-package"
+    );
+  }
+  const shortName = name.includes("/") ? name.split("/")[1] : name;
+  const vars = {
+    name,
+    description: opts.description ?? "A Pi Package for the pi coding agent.",
+    shortName,
+    snakeName: shortName.replace(/-/g, "_").replace(/[^a-z0-9_]/g, "_"),
+    piVersion: TESTED_PI_VERSION,
+    dir: basename(target)
+  };
+  mkdirSync2(target, { recursive: true });
+  const files = [
+    ["package.json", interpolate(packageJsonTemplate(name.startsWith("@")), vars)],
+    ["index.ts", interpolate(INDEX_TS, vars)],
+    ["tsconfig.json", TSCONFIG_JSON],
+    [".gitignore", GITIGNORE],
+    ["README.md", interpolate(README_MD, vars)]
+  ];
+  for (const [file, content] of files) {
+    writeFileSync2(join4(target, file), content);
+  }
+  success(`Created ${files.length} files in ${basename(target)}/`);
+  for (const [file] of files) out(`  ${file}`);
+  out();
+  hint("Next steps:");
+  hint(`  cd ${basename(target)} && npm install`);
+  hint(`  pi install ./${basename(target)}   # register locally; hot-reloads with /reload`);
+  hint(`  pi -e ./${basename(target)}/index.ts   # or load ad hoc for a single run`);
+  return 0;
+}
+
+// src/help.ts
+function render(text) {
+  return text.split("\n").map((line) => {
+    if (/^(Usage|Commands|Short forms|Options|Examples|Environment Variables):$/.test(line)) {
+      return style.bold(line);
+    }
+    if (/^\s+#/.test(line)) return style.dim(line);
+    return line;
+  }).join("\n");
+}
+function mainHelp() {
+  return render(`${style.bold("pify")} - front door for the Pify suite for the pi coding agent
+
+Usage:
+  pify <command> [options]
+
+Commands:
+  setup                  Install the pi coding agent (safe to re-run)
+  install <name...>      Install @pify packages by short name
+  remove <name...>       Remove installed @pify packages
+  update [pi|<name...>]  Update pi and installed @pify packages
+  list                   Show the @pify catalog with install state
+  doctor                 Diagnose the local pi/pify environment
+  init [dir]             Scaffold a new Pi Package
+
+Short forms:
+  i = install, rm = remove, up = update, ls = list
+
+Options:
+  -h, --help             Show help (pify <command> --help for details)
+  -v, --version          Print the pify version
+      --no-color         Disable colored output
+
+Examples:
+  # Bootstrap a bare machine (installs pi via npm)
+  npx @pify/cli setup
+
+  # Install packages by short name
+  pify install goal task
+
+  # Keep pi and every installed @pify package current
+  pify update
+
+  # Scaffold a new extension package
+  pify init my-extension
+
+Environment Variables:
+  PI_CODING_AGENT_DIR    Override pi's agent directory (default: ~/.pi/agent)
+  PIFY_CATALOG_URL       Override the remote catalog URL
+  PIFY_OFFLINE, PI_OFFLINE
+                         Set to 1/true/yes to skip catalog and version lookups
+  NO_COLOR               Disable colored output
+
+Package operations are delegated to the pi CLI; pify never edits pi's
+settings. Anything beyond these commands is pi's job: run pi --help.
+`);
+}
+var COMMAND_HELP = {
+  setup: `Usage:
+  pify setup [--force] [--pi-version <version>]
+
+Install the pi coding agent globally via npm. Safe to re-run; reports status
+when pi is already installed. Updates of an existing pi are pi's own job:
+run pify update pi.
+
+Options:
+      --force                Reinstall pi even if it is already installed
+      --pi-version <version> Install an exact pi version (may downgrade)
+
+Examples:
+  # Bootstrap a bare machine
+  npx @pify/cli setup
+
+  # Pin the version your team has tested
+  pify setup --pi-version 0.84.4
+`,
+  install: `Usage:
+  pify install <name...> [-l] [-a] [--dry-run]
+
+Install @pify packages by short name. Names resolve against the Pify catalog
+(goal -> npm:@pify/goal); the install itself is delegated to pi install.
+Exact version pins are accepted (goal@0.3.0); range specifiers are refused.
+
+Options:
+  -l, --local            Project scope (.pi/settings.json, .pi/npm)
+  -a, --approve          Forward --approve to pi (scripted -l installs)
+      --dry-run          Print the pi commands without running them
+
+Examples:
+  # Install two packages by short name
+  pify install goal task
+
+  # Project-scoped install in CI (pre-approves project trust)
+  pify install goal -l -a
+`,
+  remove: `Usage:
+  pify remove <name...> [-l] [-a] [--dry-run]
+
+Remove installed @pify packages by short name. Delegates to pi remove.
+
+Options:
+  -l, --local            Project scope
+  -a, --approve          Forward --approve to pi
+      --dry-run          Print the pi commands without running them
+
+Examples:
+  pify remove goal
+`,
+  update: `Usage:
+  pify update [pi | <name...>] [--catalog] [--dry-run]
+
+With no target: update pi itself, then every installed @pify package, then
+refresh the catalog cache. "pify update pi" updates only the agent; named
+targets update only those packages. Exact version pins are never advanced;
+re-pin with pify install <name>@<version>.
+
+Options:
+      --catalog          Refresh the remote catalog cache only
+      --dry-run          Print the update plan without executing it
+
+Examples:
+  # Everything current in one pass
+  pify update
+
+  # Agent only
+  pify update pi
+`,
+  list: `Usage:
+  pify list [--json]
+
+Show the @pify catalog with local install state. pi list shows what is
+installed; pify list also shows what exists and what is coming.
+
+Options:
+      --json             Machine-readable output
+
+Examples:
+  pify list
+`,
+  doctor: `Usage:
+  pify doctor [--json]
+
+Diagnose the local pi/pify environment: Node and npm, the pi install,
+settings files, and installed @pify packages. Exit 0 means healthy; 1 means
+problems were found.
+
+Options:
+      --json             Machine-readable output
+
+Examples:
+  pify doctor
+`,
+  init: `Usage:
+  pify init [dir] [--name <package-name>] [--description <text>]
+
+Scaffold a new Pi Package: a raw-TypeScript extension entry (no build step),
+correct peerDependencies layout, pi manifest, and files allowlist. The
+target directory must be empty or not exist.
+
+Options:
+      --name <name>          npm package name (default: the directory name)
+      --description <text>   Package description
+
+Examples:
+  # New extension package in ./my-extension
+  pify init my-extension
+
+  # Scoped name
+  pify init tools --name @myorg/pi-tools
+`
+};
+function commandHelp(command) {
+  const text = COMMAND_HELP[command];
+  return text ? render(text) : mainHelp();
+}
+
+// src/cli.ts
+var COMMANDS = [
+  {
+    name: "setup",
+    aliases: [],
+    options: {
+      force: { type: "boolean", default: false },
+      "pi-version": { type: "string" }
+    },
+    allowPositionals: false,
+    run: (_p, v) => setup({ force: Boolean(v.force), piVersion: v["pi-version"] })
+  },
+  {
+    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
+    })
+  }
+];
+async function main(argv) {
+  const args = argv.filter((a) => a !== "--no-color");
+  if (args.length !== argv.length) setColor(false);
+  if (args.length === 0) {
+    out(mainHelp());
+    return ExitCode.USAGE;
+  }
+  const first = args[0];
+  if (first === "-h" || first === "--help") {
+    out(mainHelp());
+    return 0;
+  }
+  if (first === "-v" || first === "--version") {
+    out(VERSION);
+    return 0;
+  }
+  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) {
+    throw usageError(
+      `Unknown command: ${JSON.stringify(first)}`,
+      'Run "pify --help" to see available commands.'
+    );
+  }
+  const rest = args.slice(1);
+  if (rest.includes("-h") || rest.includes("--help")) {
+    out(commandHelp(command.name));
+    return 0;
+  }
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: rest,
+      options: command.options,
+      allowPositionals: command.allowPositionals,
+      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".`
+    );
+  }
+  return command.run(parsed.positionals, parsed.values);
+}
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((err) => {
+  if (err instanceof PifyError) {
+    error(err.message);
+    if (err.hint) errorHint(err.hint);
+    process.exitCode = err.code;
+  } else {
+    error(err instanceof Error ? err.stack ?? err.message : String(err));
+    process.exitCode = ExitCode.FAILURE;
+  }
+});