@pify/cli 0.4.8 → 0.5.1

package/README.md

@@ -22,7 +22,7 @@ npx @pify/cli setup
 
 ```
 pify setup                 # install the pi coding agent (safe to re-run)
-pify setup --pi-version 0.85.1   # pin the version your team has tested
+pify setup --pi-version 0.87.0   # 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

package/catalog.json

@@ -1,5 +1,5 @@
 {
-  "version": 31,
+  "version": 32,
   "org": "pifydev",
   "scope": "@pify",
   "remote": "https://raw.githubusercontent.com/pifydev/cli/main/catalog.json",
@@ -112,14 +112,14 @@
       "name": "subagent",
       "npm": "@pify/subagent",
       "repo": "https://github.com/pifydev/subagent",
-      "description": "Spawn scoped subagents: agent_run/agent_result, @agent mentions, custom agent types, ask_supervisor, shell gates with bounded repair, task outcome separate from session status, results delivered not polled",
+      "description": "Spawn scoped subagents: agent_run/agent_result, @agent mentions, custom agent types, ask_supervisor, shell gates run async (wait on agent_result) with bounded repair, task outcome separate from session status, results delivered not polled",
       "status": "published"
     },
     {
       "name": "swarm",
       "npm": "@pify/swarm",
       "repo": "https://github.com/pifydev/swarm",
-      "description": "Run many pi agents in parallel: fan-out with per-item routing, needs-DAG with skip-on-upstream-failure, per-item shell gates, concurrency queue, shared mailbox, first hard failure interrupts early, results delivered not polled",
+      "description": "Run many pi agents in parallel: fan-out with per-item routing, needs-DAG with skip-on-upstream-failure, per-item shell gates, concurrency queue, shared mailbox, /swarm stop, first hard failure interrupts early, wait for results (delivered not polled)",
       "status": "published"
     },
     {
@@ -147,7 +147,7 @@
       "name": "workflow",
       "npm": "@pify/workflow",
       "repo": "https://github.com/pifydev/workflow",
-      "description": "Deterministic agent orchestration through JavaScript scripts: agent()/parallel()/pipeline(), gates, resume",
+      "description": "Deterministic agent orchestration through JavaScript scripts: agent()/parallel()/pipeline(), gates, resume, /workflows stop, failure ledger, wait for results",
       "status": "published"
     },
     {

package/dist/cli.js

@@ -199,7 +199,7 @@ var VERSION = require2("../package.json").version;
 // src/pi.ts
 var PI_PACKAGE = "@earendil-works/pi-coding-agent";
 var NODE_FLOOR = "22.19.0";
-var TESTED_PI_VERSION = "0.84.4";
+var TESTED_PI_VERSION = "0.87.0";
 var LATEST_VERSION_URL = "https://pi.dev/api/latest-version";
 function piStatus() {
   const binPath = which("pi");
@@ -515,16 +515,23 @@ var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 function loadBundledCatalog() {
   return JSON.parse(readFileSync2(bundledCatalogPath(), "utf8"));
 }
+var CLEAN_TEXT = /^[^\x00-\x1f\x7f]{1,500}$/;
+var CATALOG_REPO = /^https:\/\/github\.com\/pifydev\/[A-Za-z0-9._-]+$/;
+var CATALOG_IDENT = /^[@a-z0-9-]+$/;
 function validateCatalog(data) {
   if (typeof data !== "object" || data === null) return false;
   const c = data;
   if (!Number.isInteger(c.version)) return false;
+  if (typeof c.org !== "string" || !CATALOG_IDENT.test(c.org)) return false;
+  if (typeof c.scope !== "string" || !CATALOG_IDENT.test(c.scope)) return false;
   if (!Array.isArray(c.packages)) return false;
   for (const entry of c.packages) {
     if (typeof entry !== "object" || entry === null) return false;
     const p = entry;
     if (typeof p.name !== "string" || !/^[a-z0-9-]+$/.test(p.name)) return false;
     if (typeof p.npm !== "string" || !p.npm.startsWith("@pify/")) return false;
+    if (typeof p.description !== "string" || !CLEAN_TEXT.test(p.description)) return false;
+    if (typeof p.repo !== "string" || !CATALOG_REPO.test(p.repo)) return false;
     if (p.status !== "published" && p.status !== "planned") return false;
     if (p.conflicts !== void 0) {
       if (!Array.isArray(p.conflicts)) return false;
@@ -540,7 +547,7 @@ function validateCatalog(data) {
       if (typeof entry !== "object" || entry === null) return false;
       const b = entry;
       if (typeof b.name !== "string" || !/^[a-z0-9-]+$/.test(b.name)) return false;
-      if (typeof b.description !== "string") return false;
+      if (typeof b.description !== "string" || !CLEAN_TEXT.test(b.description)) return false;
       if (!Array.isArray(b.packages) || b.packages.length === 0) return false;
       for (const member of b.packages) {
         if (typeof member !== "string" || !known.has(member)) return false;
@@ -965,27 +972,50 @@ async function profile(args, opts) {
 }
 
 // src/commands/update.ts
-async function checkUpdates() {
-  const installed = installedPifyPackages();
+function piRow(installed, latest) {
+  const base = { name: "pi", installed, latest, pin: null };
+  if (installed === null) return { ...base, state: "missing" };
+  if (latest === null) return { ...base, state: "unknown" };
+  return { ...base, state: compareSemver(installed, latest) < 0 ? "outdated" : "current" };
+}
+async function checkUpdates(deps = {}) {
+  const installed = deps.installed ?? installedPifyPackages();
+  const versionOnDisk = deps.versionOnDisk ?? installedVersionOnDisk;
+  const latestPackage = deps.latestPackage ?? fetchLatestPackageVersion;
+  const piVersion = deps.piVersion !== void 0 ? deps.piVersion : piStatus().version;
+  const latestPi = deps.latestPi ?? fetchLatestPiVersion;
   const names = [...installed.keys()].sort();
-  const statuses = await Promise.all(
-    names.map(async (name) => {
+  const [piLatest, ...packages] = await Promise.all([
+    latestPi(),
+    ...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" };
+      const onDisk = versionOnDisk(name, entry.scope);
+      const latest = await latestPackage(name);
+      const pin = entry.pin;
+      if (!onDisk.present) return { name, installed: null, latest, pin, state: "missing" };
       if (!onDisk.version || !latest) {
-        return { name, installed: onDisk.version, latest, state: "unknown" };
+        return { name, installed: onDisk.version, latest, pin, state: "unknown" };
       }
-      return {
-        name,
-        installed: onDisk.version,
-        latest,
-        state: compareSemver(onDisk.version, latest) < 0 ? "outdated" : "current"
-      };
+      const behind = compareSemver(onDisk.version, latest) < 0;
+      const state = behind ? pin !== null ? "pinned" : "outdated" : "current";
+      return { name, installed: onDisk.version, latest, pin, state };
     })
-  );
-  return statuses;
+  ]);
+  return { pi: piRow(piVersion, piLatest), packages };
+}
+function checkDetail(status) {
+  switch (status.state) {
+    case "outdated":
+      return `${status.installed} \u2192 ${status.latest}`;
+    case "pinned":
+      return `${status.installed} pinned, ${status.latest} available - pify install ${status.name}@${status.latest}`;
+    case "missing":
+      return status.name === "pi" ? "not installed" : "configured but not on disk";
+    case "unknown":
+      return `${status.installed ?? "?"} (registry unreachable)`;
+    default:
+      return `${status.installed}`;
+  }
 }
 async function update(targets, opts) {
   if (isOffline()) {
@@ -1006,23 +1036,30 @@ async function update(targets, opts) {
   }
   if (opts.check) {
     if (targets.length > 0) throw usageError("--check reports on everything; drop the package names.");
-    const statuses = await checkUpdates();
+    const report = await checkUpdates();
     if (opts.json) {
-      out(JSON.stringify({ packages: statuses }, null, 2));
+      out(JSON.stringify({ pi: report.pi, packages: report.packages }, 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 rows = [report.pi, ...report.packages];
+    const width = rows.reduce((m, s) => Math.max(m, s.name.length), 0);
+    for (const status of rows) {
+      out(`  ${status.state.padEnd(9)}${status.name.padEnd(width + 2)}${checkDetail(status)}`);
     }
-    const outdated = statuses.filter((s) => s.state === "outdated").length;
+    if (report.packages.length === 0) hint("No @pify packages installed.");
+    const outdatedPackages = report.packages.filter((s) => s.state === "outdated").length;
+    const pinnedCount = report.packages.filter((s) => s.state === "pinned").length;
+    const piOutdated = report.pi.state === "outdated";
     out();
-    out(outdated > 0 ? `${outdated} package(s) can be updated: pify update` : "Everything is current.");
+    if (outdatedPackages > 0) {
+      out(`${outdatedPackages} package(s) can be updated: pify update`);
+    } else if (piOutdated) {
+      out("pi can be updated: pify update pi");
+    } else if (pinnedCount > 0) {
+      out(`Everything current except ${pinnedCount} pinned package(s) \u2014 re-pin to advance.`);
+    } else {
+      out("Everything is current.");
+    }
     return 0;
   }
   const updateEverything = targets.length === 0;
@@ -1698,7 +1735,9 @@ function powershellScript() {
   const commands = COMMAND_SPECS.flatMap(allNames);
   const caseBlocks = COMMAND_SPECS.map((spec) => {
     const words = [...positionalWords(spec), ...flagTokens(spec)].map((w) => `'${w}'`).join(", ");
-    return `      ${allNames(spec).map((n) => `'${n}'`).join(" ")} { @(${words}) }`;
+    const names = allNames(spec);
+    const condition = names.length > 1 ? `{ $_ -in ${names.map((n) => `'${n}'`).join(", ")} }` : `'${names[0]}'`;
+    return `      ${condition} { @(${words}) }`;
   }).join("\n");
   return `# PowerShell completion for pify \u2014 generated by \`pify completions powershell\`
 # Install: pify completions powershell | Out-String | Invoke-Expression  (add to $PROFILE)

package/dist/index.d.ts

@@ -39,6 +39,128 @@ declare function planApply(profile: Profile, installedNow: Map<string, {
     scope: "user" | "project";
 }>): PlanRow[];
 
+/** The npm package that provides the `pi` binary. */
+declare const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+/** Minimum Node version required by the pi coding agent. */
+declare const NODE_FLOOR = "22.19.0";
+/** The pi version this CLI release was developed and tested against. */
+declare const TESTED_PI_VERSION = "0.87.0";
+interface PiStatus {
+    installed: boolean;
+    /** Absolute path to the `pi` launcher, when installed. */
+    binPath: string | null;
+    /** Version reported by `pi --version`, when installed. */
+    version: string | null;
+}
+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;
+/**
+ * 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>;
+/**
+ * Update pi. Delegates to bare `pi update` (its default target is self):
+ * pi's updater owns install-method detection, the pi.dev rename protocol,
+ * managed-install staging, and the Windows native-module quarantine.
+ * Reimplementing any of it would rot. When pi is absent, fall through to a
+ * fresh install so `npx @pify/cli update` works on a bare machine.
+ */
+declare function updatePi(): Promise<void>;
+interface PiSettings {
+    packages?: Array<string | {
+        source: string;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
+/** pi's agent directory: tilde-expanded PI_CODING_AGENT_DIR or ~/.pi/agent. */
+declare function agentDir(): string;
+/**
+ * Read-only view of pi settings. All writes go through the pi CLI — pi owns
+ * that state (dedup rules, npm workspace, trust model), and two writers would
+ * eventually disagree. Parse failures are treated as absent (doctor warns).
+ */
+declare function readSettings(scope: "user" | "project"): PiSettings | null;
+interface InstalledPifyPackage {
+    name: string;
+    scope: "user" | "project";
+    source: string;
+    pin: string | null;
+}
+declare function installedPifyPackages(): Map<string, InstalledPifyPackage>;
+interface OnDiskState {
+    present: boolean;
+    version: string | null;
+}
+/** Version of an installed @pify package as materialized in pi's npm root. */
+declare function installedVersionOnDisk(name: string, scope: "user" | "project"): OnDiskState;
+
+interface UpdateStatus {
+    name: string;
+    installed: string | null;
+    latest: string | null;
+    /** The exact pin holding this package back, if any (packages only). */
+    pin: string | null;
+    /**
+     * "pinned" means behind the registry but held at an exact version, so
+     * `pify update` will not (and should not) advance it — the user must re-pin.
+     */
+    state: "current" | "outdated" | "missing" | "unknown" | "pinned";
+}
+/** pi plus every installed @pify package, in one snapshot. */
+interface UpdateReport {
+    pi: UpdateStatus;
+    packages: UpdateStatus[];
+}
+/**
+ * Seams for the check, so a test can drive checkUpdates without a real pi
+ * install or a network round-trip. Every field defaults to the live primitive.
+ */
+interface CheckUpdatesDeps {
+    installed?: Map<string, InstalledPifyPackage>;
+    versionOnDisk?: (name: string, scope: "user" | "project") => OnDiskState;
+    latestPackage?: (name: string) => Promise<string | null>;
+    /** pi's own installed version; `undefined` means ask piStatus(). */
+    piVersion?: string | null;
+    latestPi?: () => Promise<string | null>;
+}
+/**
+ * Compare what is installed against what is published, without installing
+ * anything. Separating the question from the action is the point: "is there
+ * anything to do" is asked far more often than "do it", and it should not
+ * cost a package install to find out.
+ *
+ * pi is checked alongside the packages because `pify update` updates pi first;
+ * a check that skipped it would say "current" and then `pify update` would
+ * upgrade the agent the user was told nothing about. Its latest-version fetch
+ * rides in the SAME Promise.all as the packages', so adding it costs no serial
+ * latency.
+ */
+declare function checkUpdates(deps?: CheckUpdatesDeps): Promise<UpdateReport>;
+
 interface CatalogPackage {
     /** Short name used on the pify command line, e.g. "goal". */
     name: string;
@@ -72,14 +194,6 @@ interface Catalog {
     bundles?: CatalogBundle[];
 }
 declare function loadBundledCatalog(): Catalog;
-/**
- * SECURITY-CRITICAL. A fetched catalog is either fully valid or fully
- * discarded: every npm name must stay inside the @pify scope so a tampered
- * catalog cannot redirect installs outside the org (npm publish rights are a
- * separate credential from GitHub). Combined with the install rule that only
- * `npm:@pify/...` specs are ever delegated to pi, this bounds the blast
- * radius of a compromised remote to "packages the org itself published".
- */
 declare function validateCatalog(data: unknown): data is Catalog;
 /** The bundle by that name, or null. Package names always win over bundles. */
 declare function findBundle(catalog: Catalog, name: string): CatalogBundle | null;
@@ -134,85 +248,6 @@ declare function resolveInstallTarget(catalog: Catalog, input: string): InstallT
  */
 declare function resolvePifyName(input: string): string;
 
-/** The npm package that provides the `pi` binary. */
-declare const PI_PACKAGE = "@earendil-works/pi-coding-agent";
-/** Minimum Node version required by the pi coding agent. */
-declare const NODE_FLOOR = "22.19.0";
-/** The pi version this CLI release was developed and tested against. */
-declare const TESTED_PI_VERSION = "0.84.4";
-interface PiStatus {
-    installed: boolean;
-    /** Absolute path to the `pi` launcher, when installed. */
-    binPath: string | null;
-    /** Version reported by `pi --version`, when installed. */
-    version: string | null;
-}
-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;
-/**
- * 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>;
-/**
- * Update pi. Delegates to bare `pi update` (its default target is self):
- * pi's updater owns install-method detection, the pi.dev rename protocol,
- * managed-install staging, and the Windows native-module quarantine.
- * Reimplementing any of it would rot. When pi is absent, fall through to a
- * fresh install so `npx @pify/cli update` works on a bare machine.
- */
-declare function updatePi(): Promise<void>;
-interface PiSettings {
-    packages?: Array<string | {
-        source: string;
-        [k: string]: unknown;
-    }>;
-    [k: string]: unknown;
-}
-/** pi's agent directory: tilde-expanded PI_CODING_AGENT_DIR or ~/.pi/agent. */
-declare function agentDir(): string;
-/**
- * Read-only view of pi settings. All writes go through the pi CLI — pi owns
- * that state (dedup rules, npm workspace, trust model), and two writers would
- * eventually disagree. Parse failures are treated as absent (doctor warns).
- */
-declare function readSettings(scope: "user" | "project"): PiSettings | null;
-interface InstalledPifyPackage {
-    name: string;
-    scope: "user" | "project";
-    source: string;
-    pin: string | null;
-}
-declare function installedPifyPackages(): Map<string, InstalledPifyPackage>;
-interface OnDiskState {
-    present: boolean;
-    version: string | null;
-}
-/** Version of an installed @pify package as materialized in pi's npm root. */
-declare function installedVersionOnDisk(name: string, scope: "user" | "project"): OnDiskState;
-
 /** True when the user asked for offline behavior (pi's env var is honored too). */
 declare function isOffline(): boolean;
 declare function assertSafeArg(arg: string, what?: string): void;
@@ -299,4 +334,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, 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 };
+export { COMMAND_SPECS, COMPLETION_SHELLS, type Catalog, type CatalogBundle, type CatalogPackage, type CheckUpdatesDeps, 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, type UpdateReport, type UpdateStatus, VERSION, agentDir, assertSafeArg, buildProfile, checkUpdates, 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

@@ -142,16 +142,23 @@ var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 function loadBundledCatalog() {
   return JSON.parse(readFileSync(bundledCatalogPath(), "utf8"));
 }
+var CLEAN_TEXT = /^[^\x00-\x1f\x7f]{1,500}$/;
+var CATALOG_REPO = /^https:\/\/github\.com\/pifydev\/[A-Za-z0-9._-]+$/;
+var CATALOG_IDENT = /^[@a-z0-9-]+$/;
 function validateCatalog(data) {
   if (typeof data !== "object" || data === null) return false;
   const c = data;
   if (!Number.isInteger(c.version)) return false;
+  if (typeof c.org !== "string" || !CATALOG_IDENT.test(c.org)) return false;
+  if (typeof c.scope !== "string" || !CATALOG_IDENT.test(c.scope)) return false;
   if (!Array.isArray(c.packages)) return false;
   for (const entry of c.packages) {
     if (typeof entry !== "object" || entry === null) return false;
     const p = entry;
     if (typeof p.name !== "string" || !/^[a-z0-9-]+$/.test(p.name)) return false;
     if (typeof p.npm !== "string" || !p.npm.startsWith("@pify/")) return false;
+    if (typeof p.description !== "string" || !CLEAN_TEXT.test(p.description)) return false;
+    if (typeof p.repo !== "string" || !CATALOG_REPO.test(p.repo)) return false;
     if (p.status !== "published" && p.status !== "planned") return false;
     if (p.conflicts !== void 0) {
       if (!Array.isArray(p.conflicts)) return false;
@@ -167,7 +174,7 @@ function validateCatalog(data) {
       if (typeof entry !== "object" || entry === null) return false;
       const b = entry;
       if (typeof b.name !== "string" || !/^[a-z0-9-]+$/.test(b.name)) return false;
-      if (typeof b.description !== "string") return false;
+      if (typeof b.description !== "string" || !CLEAN_TEXT.test(b.description)) return false;
       if (!Array.isArray(b.packages) || b.packages.length === 0) return false;
       for (const member of b.packages) {
         if (typeof member !== "string" || !known.has(member)) return false;
@@ -389,7 +396,7 @@ function hint(msg) {
 // src/pi.ts
 var PI_PACKAGE = "@earendil-works/pi-coding-agent";
 var NODE_FLOOR = "22.19.0";
-var TESTED_PI_VERSION = "0.84.4";
+var TESTED_PI_VERSION = "0.87.0";
 var LATEST_VERSION_URL = "https://pi.dev/api/latest-version";
 function piStatus() {
   const binPath = which("pi");
@@ -581,6 +588,25 @@ function installedPifyPackages() {
   }
   return result;
 }
+async function fetchLatestPackageVersion(name) {
+  if (isOffline()) return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 5e3);
+  try {
+    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"
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 function installedVersionOnDisk(name, scope) {
   const root = scope === "user" ? join3(agentDir(), "npm") : join3(process.cwd(), ".pi", "npm");
   try {
@@ -662,6 +688,39 @@ function planApply(profile, installedNow) {
   return rows.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// src/commands/update.ts
+function piRow(installed, latest) {
+  const base = { name: "pi", installed, latest, pin: null };
+  if (installed === null) return { ...base, state: "missing" };
+  if (latest === null) return { ...base, state: "unknown" };
+  return { ...base, state: compareSemver(installed, latest) < 0 ? "outdated" : "current" };
+}
+async function checkUpdates(deps = {}) {
+  const installed = deps.installed ?? installedPifyPackages();
+  const versionOnDisk = deps.versionOnDisk ?? installedVersionOnDisk;
+  const latestPackage = deps.latestPackage ?? fetchLatestPackageVersion;
+  const piVersion = deps.piVersion !== void 0 ? deps.piVersion : piStatus().version;
+  const latestPi = deps.latestPi ?? fetchLatestPiVersion;
+  const names = [...installed.keys()].sort();
+  const [piLatest, ...packages] = await Promise.all([
+    latestPi(),
+    ...names.map(async (name) => {
+      const entry = installed.get(name);
+      const onDisk = versionOnDisk(name, entry.scope);
+      const latest = await latestPackage(name);
+      const pin = entry.pin;
+      if (!onDisk.present) return { name, installed: null, latest, pin, state: "missing" };
+      if (!onDisk.version || !latest) {
+        return { name, installed: onDisk.version, latest, pin, state: "unknown" };
+      }
+      const behind = compareSemver(onDisk.version, latest) < 0;
+      const state = behind ? pin !== null ? "pinned" : "outdated" : "current";
+      return { name, installed: onDisk.version, latest, pin, state };
+    })
+  ]);
+  return { pi: piRow(piVersion, piLatest), packages };
+}
+
 // src/registry.ts
 var GLOBAL_FLAGS = [
   { name: "help", short: "h", description: "Show help" },
@@ -879,7 +938,9 @@ function powershellScript() {
   const commands = COMMAND_SPECS.flatMap(allNames);
   const caseBlocks = COMMAND_SPECS.map((spec) => {
     const words = [...positionalWords(spec), ...flagTokens(spec)].map((w) => `'${w}'`).join(", ");
-    return `      ${allNames(spec).map((n) => `'${n}'`).join(" ")} { @(${words}) }`;
+    const names = allNames(spec);
+    const condition = names.length > 1 ? `{ $_ -in ${names.map((n) => `'${n}'`).join(", ")} }` : `'${names[0]}'`;
+    return `      ${condition} { @(${words}) }`;
   }).join("\n");
   return `# PowerShell completion for pify \u2014 generated by \`pify completions powershell\`
 # Install: pify completions powershell | Out-String | Invoke-Expression  (add to $PROFILE)
@@ -1050,6 +1111,7 @@ export {
   agentDir,
   assertSafeArg,
   buildProfile,
+  checkUpdates,
   compareSemver,
   expandBundles,
   fetchLatestPiVersion,

package/package.json

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