@pify/cli 0.1.1 → 0.1.3

package/README.md

@@ -1,11 +1,8 @@
 # @pify/cli
 
-Front door for the [Pify](https://github.com/pifydev) suite: install and update the
-[pi coding agent](https://github.com/earendil-works/pi), manage the `@pify/*`
-extension packages with short names, and scaffold new Pi Packages.
+Front door for the [Pify](https://github.com/pifydev) suite: install and update the [pi coding agent](https://github.com/earendil-works/pi), manage the `@pify/*` extension packages with short names, and scaffold new Pi Packages.
 
-> Not to be confused with the unscoped npm package `pify` (sindresorhus's
-> promisify library) — unrelated.
+> Not to be confused with the unscoped npm package `pify` (sindresorhus's promisify library) — unrelated.
 
 ## Install
 
@@ -24,6 +21,7 @@ npx @pify/cli setup
 ```
 pify setup                 # install the pi coding agent (safe to re-run)
 pify setup --pi-version 0.84.4   # pin the version your team has tested
+pify setup --installer     # run pi's official interactive installer (ps1/sh)
 pify list                  # show the @pify catalog with install state
 pify install goal task     # short names resolve to @pify/goal, @pify/task
 pify install goal -l -a    # project scope, pre-approved (CI-friendly)
@@ -34,29 +32,17 @@ pify doctor                # diagnose node / npm / pi / settings
 pify init my-extension     # scaffold a new Pi Package
 ```
 
-Every command supports `--help`; `install`/`remove`/`update` support `--dry-run`;
-`list`/`doctor` support `--json`.
+Every command supports `--help`; `install`/`remove`/`update` support `--dry-run`; `list`/`doctor` support `--json`.
 
 ## 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:
-
-- **Bootstrap** — `pi update` can't run when pi isn't installed yet; `pify setup`
-  closes that gap (`npm install -g --ignore-scripts @earendil-works/pi-coding-agent`,
-  matching pi's own self-update invocation).
-- **Catalog** — `@pify/*` short names, discovery (including packages that are
-  planned but not yet published), and install state at a glance.
-- **One-pass update** — `pify update` chains pi's self-update with per-package
-  updates of everything from this org, without touching non-Pify packages you
-  manage separately.
+`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:
+
+- **Bootstrap** — `pi update` can't run when pi isn't installed yet; `pify setup` closes that gap with the same invocation as pi's official installers (`npm install -g --ignore-scripts --min-release-age=0 --no-fund --no-audit`), falling back to `bun add -g --ignore-scripts` when npm is absent and to `--prefix ~/.local` on POSIX when npm's global prefix is not writable (never sudo). `pify setup --installer` hands off to the official interactive installer (`install.ps1` on Windows, `install.sh` on Unix), which can bootstrap Node and Git Bash too.
+- **Catalog** — `@pify/*` short names, discovery (including packages that are planned but not yet published), and install state at a glance.
+- **One-pass update** — `pify update` chains pi's self-update with per-package updates of everything from this org, without touching non-Pify packages you manage separately.
 - **Doctor** — environment sanity checks for support requests.
-- **Scaffolding** — `pify init` emits a correctly-shaped Pi Package: raw
-  TypeScript entry (no build step; pi loads `.ts` via jiti), host packages as
-  optional `peerDependencies`, `files` allowlist that actually ships the
-  sources, and a lifecycle-correct extension factory.
+- **Scaffolding** — `pify init` emits a correctly-shaped Pi Package: raw TypeScript entry (no build step; pi loads `.ts` via jiti), host packages as optional `peerDependencies`, `files` allowlist that actually ships the sources, and a lifecycle-correct extension factory.
 
 ## Packages
 
@@ -74,16 +60,9 @@ pi's settings. What `pify` adds:
 | `@pify/workflow` | Deterministic multi-step agent workflows |
 | `@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).
+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).
 
-Explicit `@pify/<name>` arguments bypass the catalog's published/planned gate
-(with a warning), so a freshly published package is installable before the
-catalog propagates.
+Explicit `@pify/<name>` arguments bypass the catalog's published/planned gate (with a warning), so a freshly published package is installable before the catalog propagates.
 
 ## Exit codes
 
@@ -96,9 +75,7 @@ catalog propagates.
 | 4 | Not found (unknown catalog name; not yet published; not installed) |
 | 5 | A delegated `pi`/`npm` subprocess exited non-zero |
 
-Colored output respects `NO_COLOR`, `FORCE_COLOR`, `--no-color`, and non-TTY
-pipes. Results go to stdout; warnings and errors go to stderr. No interactive
-prompts anywhere — behavior is identical in TTY and CI except color.
+Colored output respects `NO_COLOR`, `FORCE_COLOR`, `--no-color`, and non-TTY pipes. Results go to stdout; warnings and errors go to stderr. No interactive prompts anywhere — behavior is identical in TTY and CI except color.
 
 ## Development
 
@@ -109,8 +86,7 @@ npm test           # builds first, then node --test
 npm run typecheck
 ```
 
-Requires Node >= 22.19.0 (same floor as the pi coding agent).
-Tested with pi 0.84.4.
+Requires Node >= 22.19.0 (same floor as the pi coding agent). Tested with pi 0.84.4.
 
 ## License
 

package/dist/cli.js

@@ -4,9 +4,9 @@
 import { parseArgs } from "util";
 
 // src/pi.ts
-import { readFileSync, realpathSync } from "fs";
+import { accessSync as accessSync2, constants as constants2, readFileSync, realpathSync, statSync as statSync2 } from "fs";
 import { homedir } from "os";
-import { join as join2 } from "path";
+import { dirname, join as join2 } from "path";
 
 // src/exec.ts
 import { spawn, spawnSync } from "child_process";
@@ -97,6 +97,17 @@ function runInherit(command, args) {
     child.on("close", (code) => resolve2(code ?? 1));
   });
 }
+function runOfficialInstaller(kind) {
+  const [cmd, argv] = kind === "windows" ? [
+    "powershell",
+    ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", "irm https://pi.dev/install.ps1 | iex"]
+  ] : ["sh", ["-c", "curl -fsSL https://pi.dev/install.sh | sh"]];
+  return new Promise((resolve2, reject) => {
+    const child = spawn(cmd, argv, { stdio: "inherit", windowsHide: false });
+    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) {
@@ -258,38 +269,107 @@ function guardNpmManaged(binPath) {
     );
   }
 }
+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 = dirname(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(join2(prefix, "lib", "node_modules")) && writableOrCreatable(join2(prefix, "bin"));
+      if (prefix && !prefixWritable) {
+        let staleGlobalPi = false;
+        try {
+          statSync2(join2(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 = join2(homedir(), ".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 ${join2(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.`);
+  }
 }
 function requirePi() {
   if (!piStatus().installed) {
@@ -349,12 +429,19 @@ function installedVersionOnDisk(name, scope) {
 
 // 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."
-    );
+  if (opts.installer) {
+    if (!process.stdin.isTTY || process.env.CI) {
+      throw environmentError(
+        "The official installer is interactive and needs a terminal.",
+        "In CI, use plain `pify setup` (non-interactive npm path) instead."
+      );
+    }
+    step(officialInstallerCommand());
+    const code = await runOfficialInstaller(isWindows ? "windows" : "posix");
+    if (code !== 0) {
+      throw new PifyError(`The official installer exited with code ${code}.`, ExitCode.SUBPROCESS);
+    }
+    return 0;
   }
   const st = piStatus();
   if (st.installed && !opts.force && !opts.piVersion) {
@@ -381,10 +468,10 @@ async function setup(opts) {
 // 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 { dirname as dirname2, join as join3 } from "path";
 import { fileURLToPath } from "url";
 function bundledCatalogPath() {
-  return join3(dirname(fileURLToPath(import.meta.url)), "..", "catalog.json");
+  return join3(dirname2(fileURLToPath(import.meta.url)), "..", "catalog.json");
 }
 function cachePath() {
   return join3(homedir2(), ".pify", "catalog.json");
@@ -459,7 +546,7 @@ function readCache() {
 }
 function writeCache(catalog) {
   try {
-    mkdirSync(dirname(cachePath()), { recursive: true });
+    mkdirSync(dirname2(cachePath()), { recursive: true });
     writeFileSync(cachePath(), JSON.stringify({ fetchedAt: Date.now(), catalog }, null, 2));
   } catch {
   }
@@ -822,6 +909,14 @@ async function doctor(opts) {
     gitPath ? "ok" : "warn",
     gitPath ?? "git not found - pi's git: package sources will not work"
   );
+  if (isWindows) {
+    const bashPath = which("bash");
+    push(
+      "bash",
+      bashPath ? "ok" : "warn",
+      bashPath ?? "bash not found - pi needs Git Bash on Windows; run pify setup --installer"
+    );
+  }
   const pi = piStatus();
   if (!pi.installed) {
     push("pi", "fail", "not installed - run: pify setup");
@@ -1159,15 +1254,21 @@ settings. Anything beyond these commands is pi's job: run pi --help.
 }
 var COMMAND_HELP = {
   setup: `Usage:
-  pify setup [--force] [--pi-version <version>]
+  pify setup [--force] [--pi-version <version>] [--installer]
 
-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.
+Install the pi coding agent. Safe to re-run; reports status when pi is
+already installed. Uses the same npm invocation as pi's official installers
+(--ignore-scripts --min-release-age=0), falls back to bun when npm is
+absent, and to --prefix ~/.local on POSIX when npm's global prefix is not
+writable (never sudo). 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)
+      --installer            Run pi's official interactive installer for
+                             this OS (can bootstrap Node and Git Bash;
+                             needs a terminal, refuses in CI)
 
 Examples:
   # Bootstrap a bare machine
@@ -1175,6 +1276,9 @@ Examples:
 
   # Pin the version your team has tested
   pify setup --pi-version 0.84.4
+
+  # Full native experience (Windows: install.ps1, Unix: install.sh)
+  pify setup --installer
 `,
   install: `Usage:
   pify install <name...> [-l] [-a] [--dry-run]
@@ -1283,10 +1387,15 @@ var COMMANDS = [
     aliases: [],
     options: {
       force: { type: "boolean", default: false },
-      "pi-version": { type: "string" }
+      "pi-version": { type: "string" },
+      installer: { type: "boolean", default: false }
     },
     allowPositionals: false,
-    run: (_p, v) => setup({ force: Boolean(v.force), piVersion: v["pi-version"] })
+    run: (_p, v) => setup({
+      force: Boolean(v.force),
+      piVersion: v["pi-version"],
+      installer: Boolean(v.installer)
+    })
   },
   {
     name: "install",

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>;
 /**
@@ -192,4 +211,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 { 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 };

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();
@@ -615,6 +688,8 @@ export {
   isOffline,
   loadBundledCatalog,
   loadCatalog,
+  npmInstallPiArgs,
+  officialInstallerCommand,
   packageJsonTemplate,
   parseInstallSpec,
   piStatus,

package/package.json

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