@pify/cli 0.3.1 → 0.4.1

package/README.md

@@ -1,5 +1,7 @@
 # @pify/cli
 
+[![npm version](https://img.shields.io/npm/v/@pify/cli)](https://www.npmjs.com/package/@pify/cli) [![npm downloads](https://img.shields.io/npm/dm/@pify/cli)](https://www.npmjs.com/package/@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.
 
 > Not to be confused with the unscoped npm package `pify` (sindresorhus's promisify library) — unrelated.
@@ -20,14 +22,17 @@ 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 --pi-version 0.85.1   # 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 suite         # the whole suite in one go (also: core, agents)
 pify install goal -l -a    # project scope, pre-approved (CI-friendly)
 pify remove goal
+pify update --check        # what is out of date, changing nothing
 pify update                # update pi + every installed @pify package
+pify profile save          # write the installed suite + versions to a file
+pify profile apply f.json  # diff it against this machine; --yes to apply
 pify update pi             # agent only
 pify doctor                # diagnose node / npm / pi / settings
 pify init my-extension     # scaffold a new Pi Package
@@ -63,20 +68,33 @@ pify completions powershell | Out-String | Invoke-Expression   # add to $PROFILE
 | `@pify/goal` | Pin a session goal and keep the agent anchored to it |
 | `@pify/memory` | Persistent memory across pi sessions |
 | `@pify/plan-mode` | Read-only planning mode with approve-then-execute gate |
-| `@pify/pretty` | Prettier TUI rendering for tool calls, diffs, markdown |
+| `@pify/pretty` | Compact, theme-aware rendering for pi's built-in tools |
+| `@pify/search` | Fuzzy file finding and indexed content search: `fffind` and `ffgrep` |
+| `@pify/skills` | See what skills are loaded, what they cost per request, and which ones ever fire |
 | `@pify/subagent` | Spawn scoped subagents, including by `@agent` mention |
 | `@pify/swarm` | Coordinate multiple pi agents working in parallel |
 | `@pify/task` | Task tracking: dependency graph, evidence-gated completion, reminders |
-| `@pify/todo` | Agent working-memory checklist: TodoWrite-style, next-item surfacing |
+| `@pify/todo` | Agent working-memory checklist with next-item surfacing |
 | `@pify/usage` | Token and cost reporting, plus what is filling the context window |
-| `@pify/workflow` | Deterministic agent orchestration: CC-style workflow scripts |
-| `@pify/worktree` | Safe git-worktree management with safety rails and merge-back |
+| `@pify/workflow` | Deterministic agent orchestration through JavaScript workflow scripts |
+| `@pify/worktree` | Safe git-worktree management, with `/worktree enter` to take the session along |
 | `@pify/yolo` | A safety gradient from auto-approve to ask-about-anything, 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).
 
 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.
 
+## Environment
+
+| Variable | Effect |
+|---|---|
+| `PIFY_CATALOG_URL` | Fetch the catalog from somewhere other than the org's `main` |
+| `PIFY_OFFLINE=1` / `PI_OFFLINE=1` | Skip every network lookup |
+| `PIFY_TRUST_PROJECT=1` | Approve project-supplied config for the suite's extensions in a headless run |
+| `NO_COLOR` / `FORCE_COLOR` | Colour, as usual |
+
+`PIFY_TRUST_PROJECT` is read by the extensions rather than by this CLI, and it matters in CI. Several packages load files a repository ships — `@pify/memory`'s `.pi/memory/MEMORY.md`, `@pify/subagent`'s `.pi/agents/*.md`, `@pify/yolo`'s `.pi/yolo.json` — and each asks once before doing so, because pi's own trust prompt does not cover files pi itself does not load. With no UI to ask through, the answer is no. Set this to `1` where you have decided the checkout is trustworthy. It is an environment variable rather than a config file precisely because the repository being read cannot set one for itself.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -90,6 +108,36 @@ Explicit `@pify/<name>` arguments bypass the catalog's published/planned gate (w
 
 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.
 
+## Profiles
+
+The suite you actually run, written down — which packages, at which versions, in which scope — so a second machine can reproduce it:
+
+```bash
+pify profile save                  # → pify-profile.json
+pify profile apply pify-profile.json          # prints the plan, changes nothing
+pify profile apply pify-profile.json --yes    # applies it
+```
+
+Applying always shows the difference first:
+
+```
+  change  goal          0.5.0 → 0.4.0
+  extra   todo          installed here, not in the profile (left alone)
+  install swarm         (latest)
+```
+
+A package installed here but absent from the profile is reported as `extra` and **never removed**: a profile says what must be present, not what must be deleted. Every name still goes through the same catalog resolution as a typed install, so a profile file cannot reach outside the `@pify` scope. A CLI's review is a diff and an explicit flag rather than an interactive screen, so the same command works the same way in a script.
+
+## Conflict detection
+
+Some extensions cannot run beside each other: they register the same command, tool, or flag, so pi loads both and one silently wins — and which one is not something you chose. `pify doctor` now reads pi's whole package list and says so:
+
+```
+  warn  conflicts   @pify/memory + pi-memory; @pify/pretty + pi-pretty-tui register the same commands or tools - remove one
+```
+
+The pairs come from the catalog, where each is taken from the package's own README. Detecting this properly would mean asking a running pi which commands are registered, which a CLI outside pi cannot do — so this is the static equivalent, and it is only as complete as the catalog.
+
 ## Development
 
 ```bash
@@ -99,7 +147,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 — the same floor as the pi coding agent.
 
 ## License
 

package/catalog.json

@@ -1,5 +1,5 @@
 {
-  "version": 17,
+  "version": 24,
   "org": "pifydev",
   "scope": "@pify",
   "remote": "https://raw.githubusercontent.com/pifydev/cli/main/catalog.json",
@@ -8,98 +8,123 @@
       "name": "ask-question",
       "npm": "@pify/ask-question",
       "repo": "https://github.com/pifydev/ask-question",
-      "description": "CC AskUserQuestion-shaped tool on built-in dialogs: 1-4 questions, multi-select, Other free-text, /ask history",
+      "description": "Structured questions on built-in dialogs: 1-4 questions, options with trade-offs, multi-select, Other free-text",
       "status": "published"
     },
     {
       "name": "btw",
       "npm": "@pify/btw",
       "repo": "https://github.com/pifydev/btw",
-      "description": "By-the-way side conversations: a read-only, codebase-aware side agent in a widget",
+      "description": "By-the-way side conversations: a read-only, codebase-aware side agent in a widget, out of the main context",
       "status": "published"
     },
     {
       "name": "goal",
       "npm": "@pify/goal",
       "repo": "https://github.com/pifydev/goal",
-      "description": "Pin a session goal and keep the agent anchored: ordered steps, safety limits, evidence-gated completion with an optional independent audit",
+      "description": "Pin a session goal and keep the agent anchored: ordered steps, evidence-gated completion, cost-weighted budget",
       "status": "published"
     },
     {
       "name": "memory",
       "npm": "@pify/memory",
       "repo": "https://github.com/pifydev/memory",
-      "description": "Persistent memory across sessions: two-tier markdown, FTS5 search, secret-scanned writes, opt-in LLM consolidation",
-      "status": "published"
+      "description": "Persistent memory across sessions: two-tier markdown, FTS5 search, secret-scanned writes, consent-gated project tier",
+      "status": "published",
+      "conflicts": [
+        "pi-memory"
+      ]
     },
     {
       "name": "plan-mode",
       "npm": "@pify/plan-mode",
       "repo": "https://github.com/pifydev/plan-mode",
-      "description": "Read-only planning with an approve-then-execute gate: enforced tool policy, tracked plan steps, saved-plan library, HTML export",
-      "status": "published"
+      "description": "Read-only planning with an approve-then-execute gate: enforced tool policy, tracked steps, plans as files",
+      "status": "published",
+      "conflicts": [
+        "@narumitw/pi-plan-mode"
+      ]
     },
     {
       "name": "pretty",
       "npm": "@pify/pretty",
       "repo": "https://github.com/pifydev/pretty",
-      "description": "Compact theme-aware rendering for built-in tools: summaries, highlighted reads, colorized diffs, configurable caps",
+      "description": "Compact theme-aware rendering for built-in tools: summaries, highlighted reads, word-level diff emphasis",
+      "status": "published",
+      "conflicts": [
+        "pi-pretty",
+        "pi-pretty-tui",
+        "pi-tool-display"
+      ]
+    },
+    {
+      "name": "search",
+      "npm": "@pify/search",
+      "repo": "https://github.com/pifydev/search",
+      "description": "Fuzzy file finding and indexed content search: fffind and ffgrep, with a pure-TypeScript fallback",
+      "status": "published"
+    },
+    {
+      "name": "skills",
+      "npm": "@pify/skills",
+      "repo": "https://github.com/pifydev/skills",
+      "description": "See the skills pi has loaded, what they cost in every request, and which ones ever fire",
       "status": "published"
     },
     {
       "name": "subagent",
       "npm": "@pify/subagent",
       "repo": "https://github.com/pifydev/subagent",
-      "description": "Spawn scoped subagents: agent_run/agent_result, @agent mentions, custom agent types, turn caps and tool allowlists",
+      "description": "Spawn scoped subagents: agent_run/agent_result, @agent mentions, custom agent types, ask_supervisor, results delivered not polled",
       "status": "published"
     },
     {
       "name": "swarm",
       "npm": "@pify/swarm",
       "repo": "https://github.com/pifydev/swarm",
-      "description": "Coordinate multiple pi agents in parallel: fan-out with auto-routing, concurrency queue, aggregated reports",
+      "description": "Run many pi agents in parallel: fan-out with per-item routing, concurrency queue, shared mailbox, results delivered not polled",
       "status": "published"
     },
     {
       "name": "task",
       "npm": "@pify/task",
       "repo": "https://github.com/pifydev/task",
-      "description": "Task tracking with dependency graph, evidence-gated completion, live widget, CC-style reminders",
+      "description": "Task tracking with a dependency graph, evidence-gated completion, live widget, and a sweep when the list finishes",
       "status": "published"
     },
     {
       "name": "todo",
       "npm": "@pify/todo",
       "repo": "https://github.com/pifydev/todo",
-      "description": "Agent working-memory checklist: CC TodoWrite-style complete-replacement, next-item surfacing, live widget",
+      "description": "Agent working-memory checklist: complete-replacement writes, next-item surfacing, live widget",
       "status": "published"
     },
     {
       "name": "usage",
       "npm": "@pify/usage",
       "repo": "https://github.com/pifydev/usage",
-      "description": "Token and cost reporting: live footer, local-history dashboard with per-project costs, and /usage context showing what fills the window",
+      "description": "Token and cost reporting: live footer, local-history dashboard with per-project totals, context breakdown",
       "status": "published"
     },
     {
       "name": "workflow",
       "npm": "@pify/workflow",
       "repo": "https://github.com/pifydev/workflow",
-      "description": "Deterministic agent orchestration: CC-style scripts with agent()/parallel()/pipeline(), schema-validated results, gates, and resume",
+      "description": "Deterministic agent orchestration through JavaScript scripts: agent()/parallel()/pipeline(), gates, resume",
       "status": "published"
     },
     {
       "name": "worktree",
       "npm": "@pify/worktree",
       "repo": "https://github.com/pifydev/worktree",
-      "description": "Safe git-worktree management: create/list/merge/remove with safety rails, no shell interpolation",
+      "description": "Safe git-worktree management: create/list/merge/remove with safety rails, plus /worktree enter to take the session along",
       "status": "published"
     },
     {
       "name": "yolo",
       "npm": "@pify/yolo",
       "repo": "https://github.com/pifydev/yolo",
-      "description": "A safety gradient from auto-approve-everything to ask-about-anything: four modes, secret-file gate, undo trail with git checkpoints",
+      "description": "A safety gradient from auto-approve-everything to ask-about-anything: four modes, read-before-write, undo trail, rewind to before a prompt",
       "status": "published"
     }
   ],
@@ -114,6 +139,8 @@
         "memory",
         "plan-mode",
         "pretty",
+        "search",
+        "skills",
         "subagent",
         "swarm",
         "task",

package/dist/cli.js

@@ -87,14 +87,14 @@ function runCapture(command, args) {
 }
 function runInherit(command, args) {
   const [cmd, argv, opts] = spawnPlan(command, args);
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const child = spawn(cmd, argv, {
       ...opts,
       stdio: "inherit",
       windowsHide: true
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve2(code ?? 1));
+    child.on("close", (code) => resolve3(code ?? 1));
   });
 }
 function runOfficialInstaller(kind) {
@@ -102,10 +102,10 @@ function runOfficialInstaller(kind) {
     "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) => {
+  return new Promise((resolve3, reject) => {
     const child = spawn(cmd, argv, { stdio: "inherit", windowsHide: false });
     child.on("error", reject);
-    child.on("close", (code) => resolve2(code ?? 1));
+    child.on("close", (code) => resolve3(code ?? 1));
   });
 }
 function which(command) {
@@ -247,7 +247,7 @@ 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) => {
+  const resolve3 = (p) => {
     try {
       return realpathSync(p);
     } catch {
@@ -255,7 +255,7 @@ function npmPrefixEvidence(binPath) {
     }
   };
   const normalize = (p) => isWindows ? p.toLowerCase() : p;
-  const managed = normalize(resolve2(binPath)).startsWith(normalize(resolve2(prefix)));
+  const managed = normalize(resolve3(binPath)).startsWith(normalize(resolve3(prefix)));
   return { managed, prefix };
 }
 function guardNpmManaged(binPath) {
@@ -400,6 +400,21 @@ function readSettings(scope) {
   }
 }
 var PIFY_SOURCE = /^npm:@pify\/([A-Za-z0-9._-]+?)(?:@(.+))?$/;
+function configuredNpmPackages() {
+  const found = [];
+  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" || !source.startsWith("npm:")) continue;
+      const spec = source.slice("npm:".length);
+      const at = spec.indexOf("@", spec.startsWith("@") ? 1 : 0);
+      const name = at > 0 ? spec.slice(0, at) : spec;
+      if (name && !found.some((f) => f.name === name && f.scope === scope)) found.push({ name, scope });
+    }
+  }
+  return found;
+}
 function installedPifyPackages() {
   const result = /* @__PURE__ */ new Map();
   for (const scope of ["user", "project"]) {
@@ -415,6 +430,24 @@ function installedPifyPackages() {
   }
   return result;
 }
+async function fetchLatestPackageVersion(name) {
+  if (isOffline()) return null;
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5e3);
+    const res = await fetch(`https://registry.npmjs.org/@pify/${encodeURIComponent(name)}/latest`, {
+      signal: controller.signal,
+      headers: { "user-agent": `pify/${VERSION}`, accept: "application/json" },
+      redirect: "error"
+    });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  }
+}
 function installedVersionOnDisk(name, scope) {
   const root = scope === "user" ? join2(agentDir(), "npm") : join2(process.cwd(), ".pi", "npm");
   try {
@@ -491,6 +524,12 @@ function validateCatalog(data) {
     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;
+    if (p.conflicts !== void 0) {
+      if (!Array.isArray(p.conflicts)) return false;
+      if (!p.conflicts.every((c2) => typeof c2 === "string" && /^(@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(c2))) {
+        return false;
+      }
+    }
   }
   if (c.bundles !== void 0) {
     if (!Array.isArray(c.bundles)) return false;
@@ -776,7 +815,171 @@ async function remove(names, opts) {
   return 0;
 }
 
+// src/commands/profile.ts
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, resolve } from "path";
+var PROFILE_VERSION = 1;
+function buildProfile(now = /* @__PURE__ */ new Date()) {
+  const installed = installedPifyPackages();
+  const packages = [...installed.values()].map((entry) => ({
+    name: entry.name,
+    version: installedVersionOnDisk(entry.name, entry.scope).version,
+    scope: entry.scope
+  })).sort((a, b) => a.name.localeCompare(b.name));
+  return { version: PROFILE_VERSION, createdAt: now.toISOString(), packages };
+}
+function parseProfile(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw usageError("That profile is not valid JSON.");
+  }
+  if (typeof parsed !== "object" || parsed === null) throw usageError("That profile is not an object.");
+  const candidate = parsed;
+  if (candidate.version !== PROFILE_VERSION) {
+    throw usageError(
+      `Unsupported profile version ${String(candidate.version)}.`,
+      `This pify writes and reads version ${PROFILE_VERSION}.`
+    );
+  }
+  if (!Array.isArray(candidate.packages)) throw usageError("That profile has no packages array.");
+  const packages = [];
+  for (const entry of candidate.packages) {
+    if (typeof entry !== "object" || entry === null) throw usageError("A profile entry is not an object.");
+    const e = entry;
+    if (typeof e.name !== "string" || !/^[a-z0-9._-]+$/.test(e.name)) {
+      throw usageError(`Invalid package name in profile: ${JSON.stringify(e.name)}`);
+    }
+    if (e.version !== null && typeof e.version !== "string") {
+      throw usageError(`Invalid version for ${e.name} in profile.`);
+    }
+    if (e.scope !== "user" && e.scope !== "project") {
+      throw usageError(`Invalid scope for ${e.name} in profile.`);
+    }
+    packages.push({ name: e.name, version: e.version, scope: e.scope });
+  }
+  return { version: PROFILE_VERSION, createdAt: String(candidate.createdAt ?? ""), packages };
+}
+function planApply(profile2, installedNow) {
+  const rows = [];
+  for (const entry of profile2.packages) {
+    const current = installedNow.get(entry.name);
+    if (!current) {
+      rows.push({ name: entry.name, action: "install", from: null, to: entry.version });
+      continue;
+    }
+    const onDisk = installedVersionOnDisk(entry.name, current.scope).version;
+    if (entry.version && onDisk && entry.version !== onDisk) {
+      rows.push({ name: entry.name, action: "change", from: onDisk, to: entry.version });
+    } else {
+      rows.push({ name: entry.name, action: "keep", from: onDisk, to: entry.version });
+    }
+  }
+  for (const [name] of installedNow) {
+    if (!profile2.packages.some((p) => p.name === name)) {
+      rows.push({ name, action: "extra", from: installedVersionOnDisk(name, "user").version, to: null });
+    }
+  }
+  return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+function describe(row) {
+  switch (row.action) {
+    case "install":
+      return `install ${row.to ? `@ ${row.to}` : "(latest)"}`;
+    case "change":
+      return `${row.from} \u2192 ${row.to}`;
+    case "keep":
+      return `already ${row.from ?? "installed"}`;
+    case "extra":
+      return `installed here, not in the profile (left alone)`;
+  }
+}
+async function profile(args, opts) {
+  const [sub, file] = args;
+  if (sub === "save") {
+    const target = resolve(file ?? "pify-profile.json");
+    const built = buildProfile();
+    if (built.packages.length === 0) {
+      warn("No @pify packages are installed; saving an empty profile.");
+    }
+    mkdirSync2(dirname3(target), { recursive: true });
+    writeFileSync2(target, `${JSON.stringify(built, null, 2)}
+`);
+    success(`Saved ${built.packages.length} package(s) to ${target}`);
+    return 0;
+  }
+  if (sub === "apply") {
+    if (!file) throw usageError("Which profile?", "Usage: pify profile apply <file> [--yes]");
+    const target = resolve(file);
+    if (!existsSync(target)) throw notFoundError(`No profile at ${target}.`);
+    const parsed = parseProfile(readFileSync3(target, "utf8"));
+    const catalog = await loadCatalog();
+    for (const entry of parsed.packages) resolveInstallTarget(catalog, entry.name);
+    const rows = planApply(parsed, installedPifyPackages());
+    if (opts.json) {
+      out(JSON.stringify({ profile: target, plan: rows }, null, 2));
+      return 0;
+    }
+    const width = rows.reduce((m, r) => Math.max(m, r.name.length), 0);
+    out(style.bold(`Applying ${target}`));
+    out();
+    for (const row of rows) {
+      out(`  ${row.action.padEnd(8)}${row.name.padEnd(width + 2)}${style.dim(describe(row))}`);
+    }
+    out();
+    const work = rows.filter((r) => r.action === "install" || r.action === "change");
+    if (work.length === 0) {
+      success("Nothing to do \u2014 this machine already matches the profile.");
+      return 0;
+    }
+    if (!opts.yes) {
+      hint(`${work.length} package(s) would change. Re-run with --yes to apply.`);
+      return 0;
+    }
+    requirePi();
+    const failed = [];
+    for (const row of work) {
+      const spec = row.to ? `npm:@pify/${row.name}@${row.to}` : `npm:@pify/${row.name}`;
+      const argv = ["install", spec];
+      step(`pi ${argv.join(" ")}`);
+      if (await delegate(argv) !== 0) failed.push(row.name);
+    }
+    if (failed.length > 0) {
+      throw new PifyError(`Failed for: ${failed.join(", ")}`, ExitCode.SUBPROCESS);
+    }
+    success(`Applied ${work.length} package(s).`);
+    return 0;
+  }
+  throw usageError(
+    `Unknown profile subcommand ${JSON.stringify(sub ?? "")}.`,
+    "Usage: pify profile save [file] | pify profile apply <file> [--yes]"
+  );
+}
+
 // src/commands/update.ts
+async function checkUpdates() {
+  const installed = installedPifyPackages();
+  const names = [...installed.keys()].sort();
+  const statuses = await Promise.all(
+    names.map(async (name) => {
+      const entry = installed.get(name);
+      const onDisk = installedVersionOnDisk(name, entry.scope);
+      const latest = await fetchLatestPackageVersion(name);
+      if (!onDisk.present) return { name, installed: null, latest, state: "missing" };
+      if (!onDisk.version || !latest) {
+        return { name, installed: onDisk.version, latest, state: "unknown" };
+      }
+      return {
+        name,
+        installed: onDisk.version,
+        latest,
+        state: compareSemver(onDisk.version, latest) < 0 ? "outdated" : "current"
+      };
+    })
+  );
+  return statuses;
+}
 async function update(targets, opts) {
   if (isOffline()) {
     warn("PIFY_OFFLINE/PI_OFFLINE is set - updates skipped.");
@@ -794,6 +997,27 @@ async function update(targets, opts) {
     }
     return 0;
   }
+  if (opts.check) {
+    if (targets.length > 0) throw usageError("--check reports on everything; drop the package names.");
+    const statuses = await checkUpdates();
+    if (opts.json) {
+      out(JSON.stringify({ packages: statuses }, null, 2));
+      return 0;
+    }
+    if (statuses.length === 0) {
+      hint("No @pify packages installed.");
+      return 0;
+    }
+    const width = statuses.reduce((m, s) => Math.max(m, s.name.length), 0);
+    for (const status of statuses) {
+      const detail = status.state === "outdated" ? `${status.installed} \u2192 ${status.latest}` : status.state === "missing" ? "configured but not on disk" : status.state === "unknown" ? `${status.installed ?? "?"} (registry unreachable)` : `${status.installed}`;
+      out(`  ${status.state.padEnd(9)}${status.name.padEnd(width + 2)}${detail}`);
+    }
+    const outdated = statuses.filter((s) => s.state === "outdated").length;
+    out();
+    out(outdated > 0 ? `${outdated} package(s) can be updated: pify update` : "Everything is current.");
+    return 0;
+  }
   const updateEverything = targets.length === 0;
   const piOnly = targets.length === 1 && (targets[0] === "pi" || targets[0] === "self");
   const installed = installedPifyPackages();
@@ -921,7 +1145,7 @@ async function list(opts) {
 }
 
 // src/commands/doctor.ts
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 async function doctor(opts) {
   const checks = [];
   const push = (id, status, detail) => checks.push({ id, status, detail });
@@ -987,7 +1211,7 @@ async function doctor(opts) {
   for (const scope of ["user", "project"]) {
     const id = scope === "user" ? "settings-user" : "settings-project";
     const path = settingsPath(scope);
-    if (!existsSync(path)) {
+    if (!existsSync2(path)) {
       push(id, "info", scope === "user" ? "not found (run pi once to create it)" : "none");
       continue;
     }
@@ -1015,6 +1239,26 @@ async function doctor(opts) {
       push("pify-packages", "ok", `${installed.size} configured, all present on disk`);
     }
   }
+  const catalog = await loadCatalog();
+  const configured = configuredNpmPackages();
+  const configuredNames2 = new Set(configured.map((p) => p.name));
+  const clashes = [];
+  for (const entry of catalog.packages) {
+    if (!entry.conflicts?.length) continue;
+    if (!configuredNames2.has(entry.npm)) continue;
+    for (const other of entry.conflicts) {
+      if (configuredNames2.has(other)) clashes.push(`${entry.npm} + ${other}`);
+    }
+  }
+  if (clashes.length === 0) {
+    push("conflicts", "ok", `no conflicting packages among ${configured.length} configured`);
+  } else {
+    push(
+      "conflicts",
+      "warn",
+      `${clashes.join("; ")} register the same commands or tools - remove one (pi remove npm:<name>)`
+    );
+  }
   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;
@@ -1044,8 +1288,8 @@ async function doctor(opts) {
 }
 
 // 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";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync, writeFileSync as writeFileSync3 } from "fs";
+import { basename, join as join4, resolve as resolve2 } from "path";
 
 // src/templates.ts
 function interpolate(template, vars) {
@@ -1185,8 +1429,8 @@ Tested with pi {{piVersion}}.
 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) {
+  const target = resolve2(dir);
+  if (existsSync3(target) && readdirSync(target).length > 0) {
     throw new PifyError(
       `Target directory ${JSON.stringify(dir)} is not empty.`,
       ExitCode.FAILURE,
@@ -1209,7 +1453,7 @@ async function init(dirArg, opts) {
     piVersion: TESTED_PI_VERSION,
     dir: basename(target)
   };
-  mkdirSync2(target, { recursive: true });
+  mkdirSync3(target, { recursive: true });
   const files = [
     ["package.json", interpolate(packageJsonTemplate(name.startsWith("@")), vars)],
     ["index.ts", interpolate(INDEX_TS, vars)],
@@ -1218,7 +1462,7 @@ async function init(dirArg, opts) {
     ["README.md", interpolate(README_MD, vars)]
   ];
   for (const [file, content] of files) {
-    writeFileSync2(join4(target, file), content);
+    writeFileSync3(join4(target, file), content);
   }
   success(`Created ${files.length} files in ${basename(target)}/`);
   for (const [file] of files) out(`  ${file}`);
@@ -1277,6 +1521,8 @@ var COMMAND_SPECS = [
     positional: "updateTargets",
     flags: [
       { name: "catalog", description: "Refresh the catalog cache only" },
+      { name: "check", description: "Report what is out of date and change nothing" },
+      { name: "json", description: "Machine-readable output (with --check)" },
       { name: "dry-run", description: "Print the update plan without executing" }
     ]
   },
@@ -1294,6 +1540,16 @@ var COMMAND_SPECS = [
     positional: "none",
     flags: [{ name: "json", description: "Machine-readable output" }]
   },
+  {
+    name: "profile",
+    aliases: [],
+    description: "Save the installed suite to a file, or apply one",
+    positional: "profile",
+    flags: [
+      { name: "yes", short: "y", description: "Apply the plan instead of only showing it" },
+      { name: "json", description: "Machine-readable plan" }
+    ]
+  },
   {
     name: "init",
     aliases: [],
@@ -1343,6 +1599,8 @@ function positionalWords(spec) {
       return ["pi", ...packageNames()];
     case "shell":
       return [...COMPLETION_SHELLS];
+    case "profile":
+      return ["save", "apply"];
     default:
       return [];
   }
@@ -1495,6 +1753,7 @@ Commands:
   update [pi|<name...>]  Update pi and installed @pify packages
   list                   Show the @pify catalog with install state
   doctor                 Diagnose the local pi/pify environment
+  profile save|apply     Save the installed suite to a file, or apply one
   init [dir]             Scaffold a new Pi Package
   completions <shell>    Print a completion script (bash|zsh|fish|powershell)
 
@@ -1557,6 +1816,21 @@ Examples:
 
   # Full native experience (Windows: install.ps1, Unix: install.sh)
   pify setup --installer
+`,
+  profile: `Usage:
+  pify profile save [file]          # default: pify-profile.json
+  pify profile apply <file> [--yes]
+
+Write down the suite you actually run \u2014 which packages, at which versions \u2014
+so a second machine can reproduce it. Applying always prints the plan first
+and changes nothing without --yes.
+
+A package installed here but absent from the profile is reported and left
+alone: a profile says what must be present, not what must be removed.
+
+Options:
+  -y, --yes              Apply the plan instead of only showing it
+      --json             Machine-readable plan
 `,
   install: `Usage:
   pify install <name...> [-l] [-a] [--dry-run]
@@ -1682,6 +1956,7 @@ function commandHelp(command) {
 
 // src/cli.ts
 var RUNNERS = {
+  profile: (p, v) => profile(p, { yes: Boolean(v.yes), json: Boolean(v.json) }),
   setup: (_p, v) => setup({
     force: Boolean(v.force),
     piVersion: v["pi-version"],
@@ -1697,7 +1972,12 @@ var RUNNERS = {
     approve: Boolean(v.approve),
     dryRun: Boolean(v["dry-run"])
   }),
-  update: (p, v) => update(p, { catalogOnly: Boolean(v.catalog), dryRun: Boolean(v["dry-run"]) }),
+  update: (p, v) => update(p, {
+    catalogOnly: Boolean(v.catalog),
+    dryRun: Boolean(v["dry-run"]),
+    check: Boolean(v.check),
+    json: Boolean(v.json)
+  }),
   list: (_p, v) => list({ json: Boolean(v.json) }),
   doctor: (_p, v) => doctor({ json: Boolean(v.json) }),
   init: (p, v) => init(p[0], {

package/dist/index.d.ts

@@ -1,6 +1,37 @@
 /** CLI version, read from the packaged package.json (always in the tarball). */
 declare const VERSION: string;
 
+interface ProfileEntry {
+    name: string;
+    /** Exact version recorded at save time, or null when it was unknown. */
+    version: string | null;
+    scope: "user" | "project";
+}
+interface Profile {
+    version: number;
+    createdAt: string;
+    packages: ProfileEntry[];
+}
+declare function buildProfile(now?: Date): Profile;
+/** Read a profile file, refusing anything this version cannot honour. */
+declare function parseProfile(raw: string): Profile;
+type PlanAction = "install" | "change" | "keep" | "extra";
+interface PlanRow {
+    name: string;
+    action: PlanAction;
+    from: string | null;
+    to: string | null;
+}
+/**
+ * What applying this profile would do. Packages installed here but absent from
+ * the profile are reported as `extra` and never removed: a profile says what
+ * must be present, and deleting whatever else someone installed is not a
+ * decision this command gets to make silently.
+ */
+declare function planApply(profile: Profile, installedNow: Map<string, {
+    scope: "user" | "project";
+}>): PlanRow[];
+
 interface CatalogPackage {
     /** Short name used on the pify command line, e.g. "goal". */
     name: string;
@@ -10,6 +41,12 @@ interface CatalogPackage {
     description: string;
     /** "published" once it exists on the npm registry; "planned" before that. */
     status: "published" | "planned";
+    /**
+     * npm packages that cannot run alongside this one — they register the same
+     * command, tool, or flag, so pi loads both and one silently wins. Each entry
+     * is documented in that package's own README (v0.4).
+     */
+    conflicts?: string[];
 }
 /** A named set of packages installable in one go, e.g. `pify install suite`. */
 interface CatalogBundle {
@@ -161,10 +198,6 @@ interface InstalledPifyPackage {
     source: string;
     pin: string | null;
 }
-/**
- * @pify packages configured in pi's settings, both scopes, deduped by name
- * (project wins, matching pi's own scope precedence).
- */
 declare function installedPifyPackages(): Map<string, InstalledPifyPackage>;
 interface OnDiskState {
     present: boolean;
@@ -196,7 +229,7 @@ interface FlagSpec {
     takesValue?: boolean;
     description: string;
 }
-type PositionalKind = "none" | "packages" | "updateTargets" | "directory" | "shell";
+type PositionalKind = "none" | "packages" | "updateTargets" | "directory" | "shell" | "profile";
 interface CommandSpec {
     name: string;
     aliases: string[];
@@ -259,4 +292,4 @@ declare class PifyError extends Error {
     constructor(message: string, code?: ExitCodeValue, hint?: string);
 }
 
-export { COMMAND_SPECS, COMPLETION_SHELLS, type Catalog, type CatalogBundle, 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, expandBundles, fetchLatestPiVersion, findBundle, generateCompletion, installPi, installedPifyPackages, installedVersionOnDisk, interpolate, isOffline, loadBundledCatalog, loadCatalog, npmInstallPiArgs, officialInstallerCommand, packageJsonTemplate, parseArgsOptionsFor, parseInstallSpec, piStatus, readSettings, refreshCatalog, resolveInstallTarget, resolvePifyName, updatePi, validateCatalog, which };
+export { COMMAND_SPECS, COMPLETION_SHELLS, type Catalog, type CatalogBundle, 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, type PlanRow, type Profile, type ProfileEntry, README_MD, TESTED_PI_VERSION, type TemplateVars, VERSION, agentDir, assertSafeArg, buildProfile, compareSemver, expandBundles, fetchLatestPiVersion, findBundle, generateCompletion, installPi, installedPifyPackages, installedVersionOnDisk, interpolate, isOffline, loadBundledCatalog, loadCatalog, npmInstallPiArgs, officialInstallerCommand, packageJsonTemplate, parseArgsOptionsFor, parseInstallSpec, parseProfile, piStatus, planApply, readSettings, refreshCatalog, resolveInstallTarget, resolvePifyName, updatePi, validateCatalog, which };

package/dist/index.js

@@ -5,6 +5,10 @@ import { createRequire } from "module";
 var require2 = createRequire(import.meta.url);
 var VERSION = require2("../package.json").version;
 
+// src/commands/profile.ts
+import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname3, resolve } from "path";
+
 // src/catalog.ts
 import { readFileSync, writeFileSync, mkdirSync } from "fs";
 import { homedir } from "os";
@@ -90,14 +94,14 @@ function runCapture(command, args) {
 }
 function runInherit(command, args) {
   const [cmd, argv, opts] = spawnPlan(command, args);
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const child = spawn(cmd, argv, {
       ...opts,
       stdio: "inherit",
       windowsHide: true
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve(code ?? 1));
+    child.on("close", (code) => resolve2(code ?? 1));
   });
 }
 function which(command) {
@@ -149,6 +153,12 @@ function validateCatalog(data) {
     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;
+    if (p.conflicts !== void 0) {
+      if (!Array.isArray(p.conflicts)) return false;
+      if (!p.conflicts.every((c2) => typeof c2 === "string" && /^(@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(c2))) {
+        return false;
+      }
+    }
   }
   if (c.bundles !== void 0) {
     if (!Array.isArray(c.bundles)) return false;
@@ -581,6 +591,73 @@ function installedVersionOnDisk(name, scope) {
   }
 }
 
+// src/commands/profile.ts
+var PROFILE_VERSION = 1;
+function buildProfile(now = /* @__PURE__ */ new Date()) {
+  const installed = installedPifyPackages();
+  const packages = [...installed.values()].map((entry) => ({
+    name: entry.name,
+    version: installedVersionOnDisk(entry.name, entry.scope).version,
+    scope: entry.scope
+  })).sort((a, b) => a.name.localeCompare(b.name));
+  return { version: PROFILE_VERSION, createdAt: now.toISOString(), packages };
+}
+function parseProfile(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw usageError("That profile is not valid JSON.");
+  }
+  if (typeof parsed !== "object" || parsed === null) throw usageError("That profile is not an object.");
+  const candidate = parsed;
+  if (candidate.version !== PROFILE_VERSION) {
+    throw usageError(
+      `Unsupported profile version ${String(candidate.version)}.`,
+      `This pify writes and reads version ${PROFILE_VERSION}.`
+    );
+  }
+  if (!Array.isArray(candidate.packages)) throw usageError("That profile has no packages array.");
+  const packages = [];
+  for (const entry of candidate.packages) {
+    if (typeof entry !== "object" || entry === null) throw usageError("A profile entry is not an object.");
+    const e = entry;
+    if (typeof e.name !== "string" || !/^[a-z0-9._-]+$/.test(e.name)) {
+      throw usageError(`Invalid package name in profile: ${JSON.stringify(e.name)}`);
+    }
+    if (e.version !== null && typeof e.version !== "string") {
+      throw usageError(`Invalid version for ${e.name} in profile.`);
+    }
+    if (e.scope !== "user" && e.scope !== "project") {
+      throw usageError(`Invalid scope for ${e.name} in profile.`);
+    }
+    packages.push({ name: e.name, version: e.version, scope: e.scope });
+  }
+  return { version: PROFILE_VERSION, createdAt: String(candidate.createdAt ?? ""), packages };
+}
+function planApply(profile, installedNow) {
+  const rows = [];
+  for (const entry of profile.packages) {
+    const current = installedNow.get(entry.name);
+    if (!current) {
+      rows.push({ name: entry.name, action: "install", from: null, to: entry.version });
+      continue;
+    }
+    const onDisk = installedVersionOnDisk(entry.name, current.scope).version;
+    if (entry.version && onDisk && entry.version !== onDisk) {
+      rows.push({ name: entry.name, action: "change", from: onDisk, to: entry.version });
+    } else {
+      rows.push({ name: entry.name, action: "keep", from: onDisk, to: entry.version });
+    }
+  }
+  for (const [name] of installedNow) {
+    if (!profile.packages.some((p) => p.name === name)) {
+      rows.push({ name, action: "extra", from: installedVersionOnDisk(name, "user").version, to: null });
+    }
+  }
+  return rows.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 // src/registry.ts
 var GLOBAL_FLAGS = [
   { name: "help", short: "h", description: "Show help" },
@@ -628,6 +705,8 @@ var COMMAND_SPECS = [
     positional: "updateTargets",
     flags: [
       { name: "catalog", description: "Refresh the catalog cache only" },
+      { name: "check", description: "Report what is out of date and change nothing" },
+      { name: "json", description: "Machine-readable output (with --check)" },
       { name: "dry-run", description: "Print the update plan without executing" }
     ]
   },
@@ -645,6 +724,16 @@ var COMMAND_SPECS = [
     positional: "none",
     flags: [{ name: "json", description: "Machine-readable output" }]
   },
+  {
+    name: "profile",
+    aliases: [],
+    description: "Save the installed suite to a file, or apply one",
+    positional: "profile",
+    flags: [
+      { name: "yes", short: "y", description: "Apply the plan instead of only showing it" },
+      { name: "json", description: "Machine-readable plan" }
+    ]
+  },
   {
     name: "init",
     aliases: [],
@@ -694,6 +783,8 @@ function positionalWords(spec) {
       return ["pi", ...packageNames()];
     case "shell":
       return [...COMPLETION_SHELLS];
+    case "profile":
+      return ["save", "apply"];
     default:
       return [];
   }
@@ -954,6 +1045,7 @@ export {
   VERSION,
   agentDir,
   assertSafeArg,
+  buildProfile,
   compareSemver,
   expandBundles,
   fetchLatestPiVersion,
@@ -971,7 +1063,9 @@ export {
   packageJsonTemplate,
   parseArgsOptionsFor,
   parseInstallSpec,
+  parseProfile,
   piStatus,
+  planApply,
   readSettings,
   refreshCatalog,
   resolveInstallTarget,

package/package.json

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