@pify/cli 0.3.1 → 0.4.0

package/README.md

@@ -27,7 +27,10 @@ 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 (v0.4)
 pify update                # update pi + every installed @pify package
+pify profile save          # write the installed suite + versions to a file (v0.4)
+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
@@ -101,6 +104,36 @@ npm run typecheck
 
 Requires Node >= 22.19.0 (same floor as the pi coding agent). Tested with pi 0.84.4.
 
+## Profiles (v0.4)
+
+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. (Profiles, and the rule that applying passes through a review, are from [`pi-extmgr`](https://github.com/ayagmar/pi-extmgr); what this drops is the interactive screen — a CLI's review is a diff and an explicit flag.)
+
+## Conflict detection (v0.4)
+
+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. (pi-extmgr detects this at runtime through `pi.getCommands()`, which a CLI outside pi cannot call; this is the static equivalent.)
+
 ## License
 
 MIT © [Pify maintainers](https://github.com/pifydev)

package/catalog.json

@@ -1,5 +1,5 @@
 {
-  "version": 17,
+  "version": 18,
   "org": "pifydev",
   "scope": "@pify",
   "remote": "https://raw.githubusercontent.com/pifydev/cli/main/catalog.json",
@@ -30,21 +30,32 @@
       "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"
+      "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"
+      "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",
-      "status": "published"
+      "status": "published",
+      "conflicts": [
+        "pi-pretty",
+        "pi-pretty-tui",
+        "pi-tool-display"
+      ]
     },
     {
       "name": "subagent",

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.0",
   "description": "Front door for the Pify suite: install and update the pi coding agent, manage @pify packages, and scaffold Pi Packages",
   "keywords": [
     "pify",