@pi-stef/catalog 0.4.0 → 0.5.0

package/README.md

@@ -4,14 +4,6 @@ Declarative package manager for the [pi](https://pi.dev) coding agent. Manage yo
 
 ## Installation
 
-From the monorepo root (while developing):
-
-```bash
-pi install packages/catalog
-```
-
-Once published to npm:
-
 ```bash
 pi install npm:@pi-stef/catalog
 ```
@@ -40,37 +32,48 @@ All commands are invoked as `/ct <subcommand>` inside pi, or via the shorthand `
 |---|---|---|---|
 | `sync` | — | Full sync cycle: pull → reconcile → execute → push | `--dry-run`, `--force`, `--no-push`, `--profile=<name>` |
 | `init` | — | Initialize catalog from installed packages or a gist | `--from-gist=<id>` |
-| `add` | `a` | Add a package to the catalog and install it | `--rating=<r>`, `-r <r>`, `--type=<t>`, `-s <t>` |
-| `remove` | `rm` | Remove a package from the catalog | — |
-| `toggle` | — | Cycle a package's rating: core → useful → debatable → disabled → core | — |
-| `enable` | — | Re-enable a disabled package (restores previous rating) | — |
-| `disable` | — | Disable a package (preserves rating for later restore) | — |
+| `add` | `a` | Add a package to the catalog and install it | `--type=<t>`, `-s <t>`, `--scope=@pi-stef` |
+| `remove` | `rm` | Remove a package from the catalog | `--yes`, `--scope=@pi-stef` |
+| `toggle` | — | Toggle a package's enabled state (enabled ↔ disabled) | — |
+| `enable` | — | Enable a disabled package | — |
+| `disable` | — | Disable a package and uninstall it | — |
+| `update` | `up` | Update packages to latest versions | `--all` |
 | `push` | — | Push local catalog + lock to GitHub Gist | `--dry-run`, `--profile=<name>` |
 | `pull` | — | Pull remote catalog from gist and reconcile | `--dry-run`, `--profile=<name>` |
 | `login` | — | Authenticate with GitHub via `gh` CLI | — |
-| `status` | — | Show catalog status, package counts, gist URL, last sync | — |
+| `status` | — | Show catalog status with package listing | — |
 | `diff` | — | Show diff between local and remote catalog | — |
-| `verify` | — | Verify catalog integrity (sources, ratings, duplicates) | — |
+| `verify` | — | Verify catalog integrity | — |
 | `profiles` | — | List all profiles with active indicator | — |
 | `profile` | — | Show or switch active profile | — |
+| `reset` | — | Uninstall all @pi-stef packages and delete config | `--yes` |
 
 ### Adding Packages
 
 ```bash
-# Add from a git source (prompts for type if not specified)
-/ct add my-skill git:github.com/user/repo#packages/my-skill
-
-# Add with explicit rating and type
-/ct add my-skill git:github.com/user/repo#packages/my-skill --rating=useful --type=skill
+# Add from a git source (name auto-derived)
+/ct add git:github.com/user/repo#packages/my-skill
 
 # Add an npm package
-/ct add lodash npm:lodash
+/ct add npm:lodash
+
+# Add all @pi-stef packages at once
+/ct add --scope=@pi-stef
 ```
 
 ### Removing Packages
 
 ```bash
 /ct remove my-skill
+/ct remove --scope=@pi-stef
+```
+
+### Enabling and Disabling
+
+```bash
+/ct enable my-skill      # Enable a disabled package
+/ct disable my-skill     # Disable a package (uninstalls it)
+/ct toggle my-skill      # Toggle enabled ↔ disabled
 ```
 
 ## `cat.yaml` Format
@@ -85,18 +88,14 @@ meta:
 packages:
   superpowers-adapter:
     source: "git:github.com/sfiorini/pi-stef#packages/superpowers-adapter"
-    rating: core
     type: skill
   team:
     source: "git:github.com/sfiorini/pi-stef#packages/team"
-    rating: core
     type: skill
   atlassian:
     source: "git:github.com/sfiorini/pi-stef#packages/atlassian"
-    rating: useful
     type: skill
     enabled: false
-    previousRating: useful
 ```
 
 ### Package Fields
@@ -104,11 +103,9 @@ packages:
 | Field | Required | Description |
 |---|---|---|
 | `source` | ✓ | Package source URL (`npm:…` or `git:…`) |
-| `rating` | ✓ | One of: `core`, `useful`, `debatable`, `disabled` |
 | `type` | — | `skill` or `pi-native` |
 | `profile` | — | Profile name this package belongs to |
 | `enabled` | — | `true` (default) or `false` |
-| `previousRating` | — | Rating before disable; restored by `ct enable` |
 
 ### Examples
 
@@ -117,7 +114,6 @@ packages:
 packages:
   lodash:
     source: "npm:lodash"
-    rating: useful
 ```
 
 **Git source:**
@@ -125,17 +121,19 @@ packages:
 packages:
   my-extension:
     source: "git:github.com/user/repo#packages/my-extension"
-    rating: core
     type: pi-native
 ```
 
-**Git source with subpath:**
-```yaml
-packages:
-  my-skill:
-    source: "git:github.com/user/repo#skills/my-skill"
-    rating: core
-    type: skill
+## Setup Detection
+
+Packages can include a `.pi-setup.json` file declaring requirements (environment variables, config files, CLI tools). After install or update, the catalog checks these requirements and warns if anything is missing.
+
+```json
+{
+  "env": ["API_TOKEN"],
+  "files": ["config.json"],
+  "cli": ["docker"]
+}
 ```
 
 ## Profiles
@@ -150,19 +148,16 @@ meta:
 packages:
   superpowers-adapter:
     source: "git:github.com/sfiorini/pi-stef#packages/superpowers-adapter"
-    rating: core
 
 profiles:
   work:
     packages:
       atlassian:
         source: "git:github.com/sfiorini/pi-stef#packages/atlassian"
-        rating: core
   personal:
     packages:
       figma:
         source: "git:github.com/sfiorini/pi-stef#packages/figma"
-        rating: useful
 ```
 
 **Profile commands:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-stef/catalog",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi extension for managing skill/package catalogs.",
   "type": "module",
   "license": "MIT",

package/src/catalog/crud.ts

@@ -1,6 +1,5 @@
 import type { CatalogYaml, CatalogPackage } from "../config/schema.js";
-import type { RatingValue } from "./ratings.js";
-import { isValidSource, isDisabled, nextRating } from "./ratings.js";
+import { isValidSource } from "./ratings.js";
 
 // ---------------------------------------------------------------------------
 // Immutable helpers
@@ -28,7 +27,6 @@ export function addPackage(
   catalog: CatalogYaml,
   name: string,
   source: string,
-  rating: RatingValue,
   type?: "skill" | "pi-native",
 ): CatalogYaml {
   if (catalog.packages[name]) {
@@ -41,7 +39,7 @@ export function addPackage(
     );
   }
 
-  const entry: CatalogPackage = { source, rating };
+  const entry: CatalogPackage = { source };
   if (type !== undefined) {
     entry.type = type;
   }
@@ -70,8 +68,7 @@ export function removePackage(
 }
 
 /**
- * Toggle a package's rating through the cycle:
- * core → useful → debatable → disabled → core
+ * Toggle a package's enabled state: enabled ↔ disabled.
  *
  * @throws if the package is not found
  */
@@ -87,13 +84,13 @@ export function togglePackage(
   const next = cloneCatalog(catalog);
   next.packages[name] = {
     ...entry,
-    rating: nextRating(entry.rating),
+    enabled: entry.enabled === false ? true : false,
   };
   return next;
 }
 
 /**
- * Enable a disabled package, restoring its previous rating (or "core").
+ * Enable a disabled package.
  * No-op when the package is already enabled.
  *
  * @throws if the package is not found
@@ -108,19 +105,17 @@ export function enablePackage(
   }
 
   // No-op if already enabled
-  if (!isDisabled(entry.rating)) {
+  if (entry.enabled !== false) {
     return catalog;
   }
 
-  const restored = entry.previousRating ?? "core";
   const next = cloneCatalog(catalog);
-  const { previousRating: _, ...clean } = entry;
-  next.packages[name] = { ...clean, rating: restored };
+  next.packages[name] = { ...entry, enabled: true };
   return next;
 }
 
 /**
- * Disable a package, saving its current rating for later restoration.
+ * Disable a package.
  *
  * @throws if the package is not found
  */
@@ -134,10 +129,6 @@ export function disablePackage(
   }
 
   const next = cloneCatalog(catalog);
-  next.packages[name] = {
-    ...entry,
-    previousRating: entry.rating,
-    rating: "disabled",
-  };
+  next.packages[name] = { ...entry, enabled: false };
   return next;
 }

package/src/catalog/install.ts

@@ -31,6 +31,8 @@ export interface InstalledPackage {
   name: string;
   /** Installed version if discoverable, otherwise undefined. */
   version: string | undefined;
+  /** Absolute path to the installed package directory, if discoverable. */
+  installDir?: string;
 }
 
 export type InstalledMap = Record<string, InstalledPackage>;
@@ -135,10 +137,14 @@ function readPackagesFromSettings(
     const parsed = parseSource(rawSource);
 
     let version: string | undefined;
+    let installDir: string | undefined;
     if (parsed.type === "npm") {
       version = readNpmVersion(home, parsed.npmName!);
+      installDir = path.join(npmNodeModulesDir(home), parsed.npmName!);
     } else if (parsed.type === "local") {
       version = readLocalVersion(home, rawSource);
+      const settingsDir = path.join(home, ".pi", "agent");
+      installDir = path.resolve(settingsDir, rawSource);
     }
 
     const key = parsed.type === "local" ? rawSource : parsed.name;
@@ -147,6 +153,7 @@ function readPackagesFromSettings(
       source: rawSource,
       name: parsed.name,
       version,
+      installDir,
     };
   }
 

package/src/catalog/migrate.ts

@@ -0,0 +1,59 @@
+/**
+ * Migration: rating → enabled boolean.
+ *
+ * Operates on raw YAML output (before Zod validation) so that the `rating`
+ * field — which Zod would strip — is still available for conversion.
+ *
+ * Rules:
+ *   - rating "disabled" → enabled: false
+ *   - any other rating → enabled: true (or omit, since Zod defaults to true)
+ *   - Remove `rating` and `previousRating` fields
+ */
+
+interface RawPackage {
+  source: string;
+  rating?: string;
+  previousRating?: string;
+  enabled?: boolean;
+  type?: string;
+  profile?: string;
+  [key: string]: unknown;
+}
+
+interface RawCatalog {
+  meta: Record<string, unknown>;
+  packages: Record<string, RawPackage>;
+  profiles?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Migrate a raw YAML catalog object from rating-based to enabled-based.
+ *
+ * Returns the mutated object (in-place) for chaining. If the catalog has
+ * no `packages` key or is not an object, returns it unchanged.
+ */
+export function migrateRatingToEnabledRaw(raw: unknown): unknown {
+  if (!raw || typeof raw !== "object") return raw;
+  const catalog = raw as RawCatalog;
+  if (!catalog.packages || typeof catalog.packages !== "object") return raw;
+
+  for (const [_name, pkg] of Object.entries(catalog.packages)) {
+    if (!pkg || typeof pkg !== "object") continue;
+
+    if ("rating" in pkg) {
+      const rating = pkg.rating;
+      if (rating === "disabled") {
+        pkg.enabled = false;
+      }
+      // For non-disabled ratings, don't set enabled — Zod defaults to true
+      delete pkg.rating;
+    }
+
+    if ("previousRating" in pkg) {
+      delete pkg.previousRating;
+    }
+  }
+
+  return raw;
+}

package/src/catalog/ratings.ts

@@ -1,19 +1,3 @@
-/** The ordered rating cycle: core → useful → debatable → disabled → core */
-export const RATING_CYCLE = ["core", "useful", "debatable", "disabled"] as const;
-
-export type RatingValue = (typeof RATING_CYCLE)[number];
-
-/** Returns the next rating in the cycle. */
-export function nextRating(rating: RatingValue): RatingValue {
-  const idx = RATING_CYCLE.indexOf(rating);
-  return RATING_CYCLE[(idx + 1) % RATING_CYCLE.length];
-}
-
-/** Returns true when the rating is "disabled". */
-export function isDisabled(rating: RatingValue): boolean {
-  return rating === "disabled";
-}
-
 /**
  * Validates a source string.
  * Accepted formats:

package/src/catalog/setup.ts

@@ -0,0 +1,169 @@
+/**
+ * Setup detection for packages that need additional configuration.
+ *
+ * Packages can include a `.pi-setup.json` file in their install directory
+ * declaring requirements:
+ *   - `env`: required environment variables
+ *   - `files`: required config files (relative to config dir ~/.pi/sf/<pkg>/)
+ *   - `cli`: required CLI tools (checked via `which`)
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { z } from "zod";
+import { parseSource } from "./source.js";
+import { npmNodeModulesDir } from "../config/paths.js";
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+export const SetupCheckSchema = z.object({
+  /** Required environment variables. */
+  env: z.array(z.string()).optional(),
+  /** Required config files (relative to config dir). */
+  files: z.array(z.string()).optional(),
+  /** Required CLI tools (checked via `which`). */
+  cli: z.array(z.string()).optional(),
+});
+
+export type SetupCheck = z.infer<typeof SetupCheckSchema>;
+
+export interface SetupStatus {
+  /** Whether all requirements are met. */
+  ok: boolean;
+  /** Missing environment variables. */
+  missingEnv: string[];
+  /** Missing config files. */
+  missingFiles: string[];
+  /** Missing CLI tools. */
+  missingCli: string[];
+}
+
+// ---------------------------------------------------------------------------
+// checkSetup
+// ---------------------------------------------------------------------------
+
+/**
+ * Check setup requirements for a package.
+ *
+ * @param installDir - The package's installed directory (where .pi-setup.json lives)
+ * @param configDir - The package's config directory (~/.pi/sf/<pkg>/)
+ * @returns Setup status with missing requirements, or undefined if no .pi-setup.json
+ */
+export function checkSetup(
+  installDir: string,
+  configDir: string,
+): SetupStatus | undefined {
+  const setupPath = path.join(installDir, ".pi-setup.json");
+
+  if (!fs.existsSync(setupPath)) {
+    return undefined;
+  }
+
+  let raw: unknown;
+  try {
+    const content = fs.readFileSync(setupPath, "utf-8");
+    raw = JSON.parse(content);
+  } catch {
+    console.warn(`Warning: malformed .pi-setup.json in ${installDir}`);
+    return undefined;
+  }
+
+  const parsed = SetupCheckSchema.safeParse(raw);
+  if (!parsed.success) {
+    console.warn(`Warning: invalid .pi-setup.json in ${installDir}: ${parsed.error.message}`);
+    return undefined;
+  }
+
+  const check = parsed.data;
+  const missingEnv: string[] = [];
+  const missingFiles: string[] = [];
+  const missingCli: string[] = [];
+
+  // Check environment variables
+  if (check.env) {
+    for (const varName of check.env) {
+      if (!process.env[varName]) {
+        missingEnv.push(varName);
+      }
+    }
+  }
+
+  // Check config files
+  if (check.files) {
+    for (const filePath of check.files) {
+      const fullPath = path.join(configDir, filePath);
+      if (!fs.existsSync(fullPath)) {
+        missingFiles.push(filePath);
+      }
+    }
+  }
+
+  // Check CLI tools
+  if (check.cli) {
+    for (const tool of check.cli) {
+      const result = spawnSync("which", [tool], {
+        stdio: "pipe",
+        timeout: 5000,
+      });
+      if (result.status !== 0) {
+        missingCli.push(tool);
+      }
+    }
+  }
+
+  const ok =
+    missingEnv.length === 0 &&
+    missingFiles.length === 0 &&
+    missingCli.length === 0;
+
+  return { ok, missingEnv, missingFiles, missingCli };
+}
+
+/**
+ * Format a setup status as a human-readable message.
+ */
+export function formatSetupStatus(status: SetupStatus): string {
+  const parts: string[] = [];
+  if (status.missingEnv.length > 0) {
+    parts.push(`Missing env: ${status.missingEnv.join(", ")}`);
+  }
+  if (status.missingFiles.length > 0) {
+    parts.push(`Missing files: ${status.missingFiles.join(", ")}`);
+  }
+  if (status.missingCli.length > 0) {
+    parts.push(`Missing CLI: ${status.missingCli.join(", ")}`);
+  }
+  return parts.join("; ");
+}
+
+/**
+ * Check setup requirements for a package by source string.
+ *
+ * Derives install dir from source type and config dir from home.
+ * Returns undefined if no .pi-setup.json exists.
+ */
+export function checkSetupForSource(
+  source: string,
+  home?: string,
+): SetupStatus | undefined {
+  const parsed = parseSource(source);
+  const resolvedHome = home ?? os.homedir();
+
+  let installDir: string | undefined;
+  if (parsed.type === "npm") {
+    installDir = path.join(npmNodeModulesDir(resolvedHome), parsed.npmName!);
+  } else if (parsed.type === "local") {
+    const settingsDir = path.join(resolvedHome, ".pi", "agent");
+    installDir = path.resolve(settingsDir, source);
+  } else {
+    // git sources — no known install dir
+    return undefined;
+  }
+
+  const configDir = path.join(resolvedHome, ".pi", "sf", parsed.name);
+  return checkSetup(installDir, configDir);
+}

package/src/commands/add.ts

@@ -2,7 +2,7 @@
  * `ct add` subcommand implementation.
  *
  * Adds a new package to the catalog. Supports:
- *   - Full args: `ct add <name> <source> [--rating <r>] [--type <t>]`
+ *   - Full args: `ct add <source> [--type <t>]`
  *   - Git source without `--type`: prompts for type via `ctx.ui.select()`
  *   - After adding, runs `pi install` to install the package
  *
@@ -10,10 +10,10 @@
  * and `writeCatalog` / `readCatalog` for persistence.
  */
 
-import type { RatingValue } from "../catalog/ratings.js";
 import type { CommandArgs, CommandCtx } from "./types.js";
 import { addPackage } from "../catalog/crud.js";
 import { sourceToKey } from "../catalog/source.js";
+import { checkSetupForSource, formatSetupStatus } from "../catalog/setup.js";
 import { PI_STEF_PACKAGES } from "../catalog/packages.js";
 import { readCatalog, writeCatalog } from "../config/io.js";
 import { piInstall } from "../util/exec.js";
@@ -36,25 +36,6 @@ export interface AddCtx extends CommandCtx {
 // Helpers
 // ---------------------------------------------------------------------------
 
-const VALID_RATINGS: RatingValue[] = ["core", "useful", "debatable"];
-
-function isValidRating(value: string): value is RatingValue {
-  return VALID_RATINGS.includes(value as RatingValue);
-}
-
-function resolveRating(flags: Record<string, true | string>): RatingValue {
-  const raw =
-    "r" in flags
-      ? flags["r"]
-      : "rating" in flags
-        ? flags["rating"]
-        : undefined;
-
-  if (raw === true || raw === undefined) return "core";
-  if (typeof raw === "string" && isValidRating(raw)) return raw;
-  return "core";
-}
-
 function resolveType(
   flags: Record<string, true | string>,
 ): "skill" | "pi-native" | undefined {
@@ -77,10 +58,10 @@ function resolveType(
 /**
  * Execute the `ct add` subcommand.
  *
- * New syntax (preferred): `ct add <source> [--rating ...] [--type ...]`
+ * New syntax (preferred): `ct add <source> [--type ...]`
  *   — name is auto-derived from source via `sourceToKey()`.
  *
- * Legacy syntax (deprecated): `ct add <name> <source> [--rating ...] [--type ...]`
+ * Legacy syntax (deprecated): `ct add <name> <source> [--type ...]`
  *   — still accepted but emits a deprecation warning.
  *
  * Reads the catalog, validates inputs, prompts for type if needed,
@@ -98,7 +79,6 @@ export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void>
     }
 
     const catalog = readCatalog(ctx.home);
-    const rating = resolveRating(flags);
     let added = 0;
     let skipped = 0;
     let currentCatalog = catalog;
@@ -113,7 +93,7 @@ export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void>
       }
 
       try {
-        currentCatalog = addPackage(currentCatalog, pkg, npmSource, rating);
+        currentCatalog = addPackage(currentCatalog, pkg, npmSource);
         added++;
       } catch (err: unknown) {
         // Unexpected validation error — warn but continue
@@ -130,21 +110,37 @@ export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void>
     }
 
     // Install all added packages
+    const setupWarnings: string[] = [];
     if (added > 0) {
       for (const pkg of PI_STEF_PACKAGES) {
         if (currentCatalog.packages[pkg]?.source === `npm:${pkg}`) {
+          ctx.ui.setWorkingMessage?.(`Installing ${pkg}...`);
           try {
             await piInstall(`npm:${pkg}`);
+
+            // Check setup after successful install
+            const setup = checkSetupForSource(`npm:${pkg}`, ctx.home);
+            if (setup && !setup.ok) {
+              setupWarnings.push(`${pkg}: ${formatSetupStatus(setup)}`);
+            }
           } catch {
             ctx.ui.notify(`Warning: install of "${pkg}" failed`, "warning");
           }
         }
       }
+      ctx.ui.setWorkingMessage?.();
     }
 
-    ctx.ui.notify(
+    const parts: string[] = [
       `Scope @pi-stef: added ${added}, skipped ${skipped} (already in catalog)`,
-      "info",
+    ];
+    if (setupWarnings.length > 0) {
+      parts.push(`Setup incomplete:\n  ${setupWarnings.join("\n  ")}`);
+    }
+
+    ctx.ui.notify(
+      parts.join("\n"),
+      setupWarnings.length > 0 ? "warning" : "info",
     );
     return;
   }
@@ -165,13 +161,12 @@ export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void>
     name = sourceToKey(source);
   } else {
     ctx.ui.notify(
-      "Usage: ct add <source> [--rating <core|useful|debatable>] [--type <skill|pi-native>]",
+      "Usage: ct add <source> [--type <skill|pi-native>]",
       "error",
     );
     return;
   }
 
-  const rating = resolveRating(flags);
   let type = resolveType(flags);
 
   // --- Read catalog ---------------------------------------------------------
@@ -192,7 +187,7 @@ export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void>
 
   // --- Add package ----------------------------------------------------------
   try {
-    const updated = addPackage(catalog, name, source, rating, type);
+    const updated = addPackage(catalog, name, source, type);
     writeCatalog(updated, ctx.home);
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
@@ -203,6 +198,7 @@ export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void>
   ctx.ui.notify(`Added "${name}" to catalog`, "info");
 
   // --- Run pi install -------------------------------------------------------
+  ctx.ui.setWorkingMessage?.(`Installing ${name}...`);
   try {
     await piInstall(source);
   } catch {
@@ -211,4 +207,14 @@ export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void>
       "warning",
     );
   }
+  ctx.ui.setWorkingMessage?.();
+
+  // --- Check setup requirements ---------------------------------------------
+  const setup = checkSetupForSource(source, ctx.home);
+  if (setup && !setup.ok) {
+    ctx.ui.notify(
+      `Setup incomplete for "${name}": ${formatSetupStatus(setup)}`,
+      "warning",
+    );
+  }
 }

package/src/commands/definitions.ts

@@ -30,7 +30,7 @@ export const SUBCOMMAND_DEFS: readonly SubcommandDef[] = [
   { name: "init", description: "Initialize a new catalog" },
   { name: "add", aliases: ["a"], description: "Add a package to the catalog" },
   { name: "remove", aliases: ["rm"], description: "Remove a package from the catalog" },
-  { name: "toggle", description: "Toggle a package's rating" },
+  { name: "toggle", description: "Toggle a package's enabled state" },
   { name: "update", aliases: ["up"], description: "Update packages to latest versions" },
   { name: "disable", description: "Disable a package" },
   { name: "enable", description: "Enable a package" },

package/src/commands/init.ts

@@ -8,6 +8,7 @@
 import yaml from "js-yaml";
 
 import { scanInstalled } from "../catalog/install.js";
+import { migrateRatingToEnabledRaw } from "../catalog/migrate.js";
 import { CatalogYamlSchema } from "../config/schema.js";
 import type { CatalogYaml } from "../config/schema.js";
 import type { CommandArgs, CommandCtx } from "./types.js";
@@ -29,7 +30,7 @@ export type InitContext = CommandCtx;
  * Initialize a new catalog.
  *
  * - Without flags: scans installed packages and generates a catalog with
- *   `rating: 'core'` for every discovered package.
+ *   every discovered package enabled.
  * - With `--from-gist=<id>`: fetches the gist, reads its `cat.yaml` file,
  *   validates it, and writes it as the local catalog.
  */
@@ -70,7 +71,6 @@ function initFromScan(ctx: InitContext): void {
   for (const [name, pkg] of Object.entries(installed)) {
     packages[name] = {
       source: pkg.source,
-      rating: "core",
     };
   }
 
@@ -115,6 +115,7 @@ async function initFromGist(gistId: string, ctx: InitContext): Promise<void> {
 
   // Validate and write
   const parsed = yaml.load(gistContent);
+  migrateRatingToEnabledRaw(parsed);
   const catalog = CatalogYamlSchema.parse(parsed);
 
   writeCatalog(catalog, ctx.home);

package/src/commands/remove.ts

@@ -97,6 +97,7 @@ export async function removeCommand(
     let uninstalled = 0;
     let failed = 0;
     for (const name of piStefNames) {
+      ctx.ui.setWorkingMessage?.(`Uninstalling ${name} (${uninstalled + 1}/${piStefNames.length})...`);
       try {
         await piUninstall(sources[name]);
         uninstalled++;
@@ -105,6 +106,7 @@ export async function removeCommand(
         failed++;
       }
     }
+    ctx.ui.setWorkingMessage?.();
 
     ctx.ui.notify(
       `Scope @pi-stef: removed ${piStefNames.length}, uninstalled ${uninstalled}${failed > 0 ? ` (${failed} uninstall failed)` : ""}`,
@@ -163,6 +165,7 @@ export async function removeCommand(
   ctx.ui.notify(`Removed "${name}" from catalog`, "info");
 
   // --- Run pi uninstall -----------------------------------------------------
+  ctx.ui.setWorkingMessage?.(`Uninstalling ${name}...`);
   try {
     await piUninstall(source);
   } catch {
@@ -171,4 +174,5 @@ export async function removeCommand(
       "warning",
     );
   }
+  ctx.ui.setWorkingMessage?.();
 }

package/src/commands/reset.ts

@@ -91,6 +91,7 @@ export async function resetCommand(
   let failed = 0;
 
   for (const name of piStefNames) {
+    ctx.ui.setWorkingMessage?.(`Uninstalling ${name} (${uninstalled + 1}/${piStefNames.length})...`);
     try {
       await piUninstall(packages[name].source);
       uninstalled++;
@@ -99,6 +100,7 @@ export async function resetCommand(
       failed++;
     }
   }
+  ctx.ui.setWorkingMessage?.();
 
   // --- Delete config files --------------------------------------------------
   const dir = catalogDir(ctx.home);

package/src/commands/status.ts

@@ -1,14 +1,16 @@
 /**
  * `ct status` subcommand implementation.
  *
- * Shows catalog status: profile, package counts by rating,
- * installed/missing/orphan counts, gist URL, and last sync time.
+ * Shows catalog status: profile, package counts (enabled/disabled),
+ * installed/missing/orphan counts, gist URL, last sync time,
+ * and individual package listing with setup status.
  */
 
 import type { CommandArgs, CommandCtx } from "./types.js";
 import { readCatalog, readLock } from "../config/io.js";
 import { scanInstalled } from "../catalog/install.js";
 import { readCachedGistId } from "../sync/cache.js";
+import { checkSetupForSource } from "../catalog/setup.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -17,30 +19,6 @@ import { readCachedGistId } from "../sync/cache.js";
 /** Context for `statusCommand`. Uses the base `CommandCtx`. */
 export type StatusCtx = CommandCtx;
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-interface RatingCounts {
-  core: number;
-  useful: number;
-  debatable: number;
-  disabled: number;
-}
-
-function countByRating(
-  packages: Record<string, { rating: string; enabled?: boolean }>,
-): RatingCounts {
-  const counts: RatingCounts = { core: 0, useful: 0, debatable: 0, disabled: 0 };
-  for (const pkg of Object.values(packages)) {
-    const r = pkg.rating as keyof RatingCounts;
-    if (r in counts) {
-      counts[r]++;
-    }
-  }
-  return counts;
-}
-
 // ---------------------------------------------------------------------------
 // statusCommand
 // ---------------------------------------------------------------------------
@@ -49,7 +27,7 @@ function countByRating(
  * Execute the `ct status` subcommand.
  *
  * Reads catalog, lock, gist cache, and installed packages to build
- * a comprehensive status summary.
+ * a comprehensive status summary with individual package listing.
  */
 export async function statusCommand(
   args: CommandArgs,
@@ -67,24 +45,33 @@ export async function statusCommand(
   const packages = catalog.packages;
   const totalPackages = Object.keys(packages).length;
 
-  // --- Package counts by rating ---
-  const ratingCounts = countByRating(packages);
+  // --- Enabled / disabled counts ---
+  let enabledCount = 0;
+  let disabledCount = 0;
+  for (const pkg of Object.values(packages)) {
+    if (pkg.enabled === false) {
+      disabledCount++;
+    } else {
+      enabledCount++;
+    }
+  }
 
   // --- Installed / missing / orphan ---
+  // Build a lookup map for installed packages by source
+  const installedBySource = new Map<string, { name: string; version?: string }>();
+  for (const inst of Object.values(installed)) {
+    installedBySource.set(inst.source, { name: inst.name, version: inst.version });
+  }
+
   const catalogSources = new Set<string>();
   for (const pkg of Object.values(packages)) {
     catalogSources.add(pkg.source);
   }
 
-  const installedSources = new Set<string>();
-  for (const inst of Object.values(installed)) {
-    installedSources.add(inst.source);
-  }
-
   // Count how many catalog packages are actually installed
   let installedCount = 0;
   for (const pkg of Object.values(packages)) {
-    if (installedSources.has(pkg.source)) {
+    if (installedBySource.has(pkg.source)) {
       installedCount++;
     }
   }
@@ -116,7 +103,7 @@ export async function statusCommand(
 
   // Package counts
   lines.push(
-    `Packages: ${totalPackages} total (core: ${ratingCounts.core}, useful: ${ratingCounts.useful}, debatable: ${ratingCounts.debatable}, disabled: ${ratingCounts.disabled})`,
+    `Packages: ${totalPackages} total (${enabledCount} enabled, ${disabledCount} disabled)`,
   );
 
   // Installed/missing/orphan
@@ -138,5 +125,53 @@ export async function statusCommand(
     lines.push("Last sync: never synced");
   }
 
+  // --- Individual package listing ---
+  if (totalPackages > 0) {
+    lines.push("");
+    lines.push("Packages:");
+
+    for (const [name, pkg] of Object.entries(packages)) {
+      const isDisabled = pkg.enabled === false;
+      const isInstalled = installedBySource.has(pkg.source);
+      const inst = installedBySource.get(pkg.source);
+
+      // Status indicator
+      let status: string;
+      if (isDisabled) {
+        status = "disabled";
+      } else if (isInstalled) {
+        status = "installed";
+      } else {
+        status = "missing";
+      }
+
+      // Version info
+      const versionStr = inst?.version ? ` v${inst.version}` : "";
+
+      // Setup status
+      let setupStr = "";
+      if (isInstalled && !isDisabled) {
+        const setup = checkSetupForSource(pkg.source, ctx.home);
+        if (setup && !setup.ok) {
+          setupStr = " ⚠ setup incomplete";
+        }
+      }
+
+      lines.push(`  ${name} [${status}]${versionStr}${setupStr}`);
+    }
+  }
+
+  // --- Orphans ---
+  if (orphanCount > 0) {
+    lines.push("");
+    lines.push("Orphans:");
+    for (const inst of Object.values(installed)) {
+      if (!catalogSources.has(inst.source)) {
+        const versionStr = inst.version ? ` v${inst.version}` : "";
+        lines.push(`  ${inst.name} [orphan]${versionStr}`);
+      }
+    }
+  }
+
   ctx.ui.notify(lines.join("\n"), "info");
 }

package/src/commands/sync.ts

@@ -120,6 +120,7 @@ export async function syncCommand(
   // --- 2. Pull remote catalog (into memory only) ---------------------------
   let remoteCatalog = false;
   let pulledData: { catalog: CatalogYaml; lock: LockFile } | undefined;
+  ctx.ui.setWorkingMessage?.("Pulling remote catalog...");
   try {
     pulledData = await pullCatalog(profile, ctx.home);
     remoteCatalog = true;
@@ -129,6 +130,7 @@ export async function syncCommand(
     ctx.ui.notify(`Pull failed: ${message}`, "warning");
     summary.errors.push(message);
   }
+  ctx.ui.setWorkingMessage?.();
 
   // --- 3. Reconcile --------------------------------------------------------
   // Use pulled catalog if available, otherwise read from disk
@@ -172,6 +174,12 @@ export async function syncCommand(
     }
   }
 
+  // Track whether the rebuilt lock (from buildSyncedLock) differs from the
+  // remote lock. This catches the case where `pi update` bumped an installed
+  // version but the catalog source string hasn't changed, so the pre-pull
+  // lock comparison wouldn't detect it.
+  let rebuiltLockDiffers = false;
+
   const installed = scanInstalled(ctx.home);
 
   // Build catalog entries for reconcile
@@ -220,7 +228,9 @@ export async function syncCommand(
       writeLock(pulledData.lock, ctx.home);
     }
 
+    ctx.ui.setWorkingMessage?.("Executing actions...");
     const result = await executeActions(plan, { home: ctx.home });
+    ctx.ui.setWorkingMessage?.();
 
     for (const { error } of result.errors) {
       ctx.ui.notify(`Action error: ${error.message}`, "warning");
@@ -234,6 +244,28 @@ export async function syncCommand(
     // Always write a populated lock so "last sync" is accurate
     const syncedLock = buildSyncedLock(catalog, installed);
     writeLock(syncedLock, ctx.home);
+
+    // Compare rebuilt lock versions against remote to detect version drift
+    // from external `pi update` calls that bumped installed versions without
+    // changing the catalog source string.
+    if (pulledData) {
+      const remoteLock = pulledData.lock;
+      for (const [key, rebuiltEntry] of Object.entries(syncedLock.packages)) {
+        const remoteEntry = remoteLock.packages[key];
+        if (!remoteEntry || remoteEntry.version !== rebuiltEntry.version) {
+          rebuiltLockDiffers = true;
+          break;
+        }
+      }
+      if (!rebuiltLockDiffers) {
+        for (const key of Object.keys(remoteLock.packages)) {
+          if (!(key in syncedLock.packages)) {
+            rebuiltLockDiffers = true;
+            break;
+          }
+        }
+      }
+    }
   }
 
   // --- 5. Push if changed --------------------------------------------------
@@ -251,7 +283,8 @@ export async function syncCommand(
   const hasGist = readCachedGistId(ctx.home) !== undefined;
   const localHasPackages = Object.keys(catalog.packages).length > 0;
 
-  if (force || summary.actionCount > 0 || hasLocalOnlyPackages || hasLocalLockChanges || (!hasGist && localHasPackages)) {
+  if (force || summary.actionCount > 0 || hasLocalOnlyPackages || hasLocalLockChanges || rebuiltLockDiffers || (!hasGist && localHasPackages)) {
+    ctx.ui.setWorkingMessage?.("Pushing to gist...");
     try {
       const updatedCatalog = readCatalog(ctx.home);
       const updatedLock = readLock(ctx.home);
@@ -268,6 +301,7 @@ export async function syncCommand(
       ctx.ui.notify(`Push failed: ${message}`, "error");
       summary.errors.push(message);
     }
+    ctx.ui.setWorkingMessage?.();
   }
 
   // --- 6. Report summary ---------------------------------------------------
@@ -282,7 +316,7 @@ export async function syncCommand(
     }
   }
 
-  if (summary.actionCount === 0 && summary.errors.length === 0 && !force && !hasLocalOnlyPackages && !hasLocalLockChanges) {
+  if (summary.actionCount === 0 && summary.errors.length === 0 && !force && !hasLocalOnlyPackages && !hasLocalLockChanges && !rebuiltLockDiffers) {
     ctx.ui.notify("Catalog already up to date.", "info");
     return;
   }
@@ -298,6 +332,9 @@ export async function syncCommand(
   if (hasLocalLockChanges) {
     parts.push("Pushed local version updates.");
   }
+  if (rebuiltLockDiffers) {
+    parts.push("Rebuilt lock (version drift detected).");
+  }
   if (plan.installs.length > 0) {
     parts.push(`${plan.installs.length} install(s): ${plan.installs.map((a) => a.key).join(", ")}`);
   }

package/src/commands/toggle.ts

@@ -1,12 +1,9 @@
 /**
  * `ct toggle`, `ct enable`, and `ct disable` subcommand implementations.
  *
- * - `ct toggle <name>` cycles a package's rating through the cycle:
- *   core → useful → debatable → disabled → core
- * - `ct enable <name>` sets a disabled package back to its previous rating
- *   (or "core" if no previous rating stored). No-op when already enabled.
- * - `ct disable <name>` sets rating to disabled, saves the previous rating,
- *   and runs `pi uninstall` to remove the package.
+ * - `ct toggle <name>` toggles a package's enabled state (enabled ↔ disabled)
+ * - `ct enable <name>` enables a disabled package. No-op when already enabled.
+ * - `ct disable <name>` disables a package and runs `pi uninstall`.
  *
  * All commands read/write `cat.yaml` via `readCatalog` / `writeCatalog`
  * and provide user feedback through `ctx.ui.notify`.
@@ -31,7 +28,7 @@ export type ToggleCtx = CommandCtx;
 /**
  * Execute the `ct toggle` subcommand.
  *
- * Cycles the package's rating through: core → useful → debatable → disabled → core.
+ * Toggles the package's enabled state: enabled ↔ disabled.
  */
 export async function toggleCommand(
   args: CommandArgs,
@@ -49,8 +46,9 @@ export async function toggleCommand(
   try {
     const updated = togglePackage(catalog, name);
     writeCatalog(updated, ctx.home);
+    const isEnabled = updated.packages[name].enabled !== false;
     ctx.ui.notify(
-      `Toggled "${name}" to ${updated.packages[name].rating}`,
+      `Toggled "${name}" — now ${isEnabled ? "enabled" : "disabled"}`,
       "info",
     );
   } catch (err: unknown) {
@@ -66,8 +64,7 @@ export async function toggleCommand(
 /**
  * Execute the `ct enable` subcommand.
  *
- * Restores a disabled package to its previous rating (or "core").
- * No-op when the package is already enabled.
+ * Enables a disabled package. No-op when the package is already enabled.
  */
 export async function enableCommand(
   args: CommandArgs,
@@ -92,10 +89,7 @@ export async function enableCommand(
     }
 
     writeCatalog(updated, ctx.home);
-    ctx.ui.notify(
-      `Enabled "${name}" (rating: ${updated.packages[name].rating})`,
-      "info",
-    );
+    ctx.ui.notify(`Enabled "${name}"`, "info");
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
     ctx.ui.notify(message, "error");
@@ -109,8 +103,7 @@ export async function enableCommand(
 /**
  * Execute the `ct disable` subcommand.
  *
- * Sets the package rating to "disabled", saves the previous rating for later
- * restoration, and runs `pi uninstall` to remove the package.
+ * Disables a package and runs `pi uninstall` to remove it.
  */
 export async function disableCommand(
   args: CommandArgs,
@@ -136,6 +129,7 @@ export async function disableCommand(
   }
 
   // Run pi uninstall after disabling
+  ctx.ui.setWorkingMessage?.(`Uninstalling ${name}...`);
   try {
     await piUninstall(name);
   } catch {
@@ -144,4 +138,5 @@ export async function disableCommand(
       "warning",
     );
   }
+  ctx.ui.setWorkingMessage?.();
 }

package/src/commands/types.ts

@@ -32,6 +32,8 @@ export interface CommandArgs {
 export interface CommandCtx {
   ui: {
     notify: (msg: string, type?: "error" | "info" | "warning") => void;
+    /** Show a temporary working message (e.g. "Adding..."). Pass undefined or no arg to clear. */
+    setWorkingMessage?: (msg?: string) => void;
   };
   /** Home directory override (for testing). */
   home?: string;

package/src/commands/update.ts

@@ -13,6 +13,7 @@
 import type { CommandArgs, CommandCtx } from "./types.js";
 import { readCatalog } from "../config/io.js";
 import { piUpdate } from "../util/exec.js";
+import { checkSetupForSource, formatSetupStatus } from "../catalog/setup.js";
 
 // ---------------------------------------------------------------------------
 // updateCommand
@@ -48,12 +49,23 @@ export async function updateCommand(
       return;
     }
 
+    ctx.ui.setWorkingMessage?.(`Updating ${name}...`);
     try {
       await piUpdate(entry.source);
       ctx.ui.notify(`Updated "${name}"`, "info");
     } catch {
       ctx.ui.notify(`Warning: update of "${name}" failed`, "warning");
     }
+    ctx.ui.setWorkingMessage?.();
+
+    // Check setup requirements after update
+    const setup = checkSetupForSource(entry.source, ctx.home);
+    if (setup && !setup.ok) {
+      ctx.ui.notify(
+        `Setup incomplete for "${name}": ${formatSetupStatus(setup)}`,
+        "warning",
+      );
+    }
     return;
   }
 
@@ -66,20 +78,36 @@ export async function updateCommand(
 
   let updated = 0;
   let failed = 0;
+  const setupWarnings: string[] = [];
 
   for (const pkgName of names) {
     const entry = packages[pkgName];
+    ctx.ui.setWorkingMessage?.(`Updating ${pkgName} (${updated + 1}/${names.length})...`);
     try {
       await piUpdate(entry.source);
       updated++;
+
+      // Check setup after successful update
+      const setup = checkSetupForSource(entry.source, ctx.home);
+      if (setup && !setup.ok) {
+        setupWarnings.push(`${pkgName}: ${formatSetupStatus(setup)}`);
+      }
     } catch {
       ctx.ui.notify(`Warning: update of "${pkgName}" failed`, "warning");
       failed++;
     }
   }
+  ctx.ui.setWorkingMessage?.();
 
-  ctx.ui.notify(
+  const parts: string[] = [
     `Updated ${updated}/${names.length} packages${failed > 0 ? ` (${failed} failed)` : ""}`,
-    failed > 0 ? "warning" : "info",
+  ];
+  if (setupWarnings.length > 0) {
+    parts.push(`Setup incomplete:\n  ${setupWarnings.join("\n  ")}`);
+  }
+
+  ctx.ui.notify(
+    parts.join("\n"),
+    failed > 0 || setupWarnings.length > 0 ? "warning" : "info",
   );
 }

package/src/config/io.ts

@@ -4,6 +4,7 @@ import yaml from "js-yaml";
 import { catalogFile, lockFile, ensureCatalogDir } from "./paths.js";
 import { CatalogYamlSchema, LockFileSchema } from "./schema.js";
 import type { CatalogYaml, LockFile } from "./schema.js";
+import { migrateRatingToEnabledRaw } from "../catalog/migrate.js";
 
 // ---------------------------------------------------------------------------
 // Empty defaults
@@ -37,6 +38,8 @@ export function readCatalog(home?: string): CatalogYaml {
   }
 
   const parsed = yaml.load(raw);
+  // Migrate rating → enabled before Zod validation strips the unknown field
+  migrateRatingToEnabledRaw(parsed);
   return CatalogYamlSchema.parse(parsed);
 }
 

package/src/config/schema.ts

@@ -7,23 +7,16 @@ import { z } from "zod";
 /** Type discriminator for a catalog package entry. */
 export const PackageType = z.enum(["skill", "pi-native"]);
 
-/** Rating values for catalog packages. */
-export const Rating = z.enum(["core", "useful", "debatable", "disabled"]);
-
 /** A single package entry inside cat.yaml. */
 export const CatalogPackageSchema = z.object({
   /** Where to fetch the package from (URL, path, etc.). */
   source: z.string().min(1),
-  /** User-assigned rating. */
-  rating: Rating,
   /** Optional type discriminator. */
   type: PackageType.optional(),
   /** Optional profile name this package belongs to. */
   profile: z.string().optional(),
   /** Whether the package is active. Defaults to true when absent. */
   enabled: z.boolean().optional(),
-  /** Previous rating before disable; used by enablePackage to restore. */
-  previousRating: Rating.optional(),
 });
 
 /** The meta section at the top of cat.yaml. */
@@ -84,4 +77,3 @@ export type CatalogPackage = z.infer<typeof CatalogPackageSchema>;
 export type Profile = z.infer<typeof ProfileSchema>;
 export type LockFile = z.infer<typeof LockFileSchema>;
 export type LockPackage = z.infer<typeof LockPackageSchema>;
-export type RatingValue = z.infer<typeof Rating>;

package/src/register.ts

@@ -224,13 +224,11 @@ export function registerCatalog(pi: ExtensionAPI): void {
     ],
     parameters: Type.Object({
       source: Type.String({ description: "Package source (npm:… or git:…)" }),
-      rating: Type.Optional(Type.String({ description: "Initial rating (core, useful, debatable)" })),
       scope: Type.Optional(Type.String({ description: "Batch scope: '@pi-stef' to add all @pi-stef packages" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
         const flags: Record<string, true | string> = {};
-        if (params.rating) flags.rating = params.rating;
         if (params.scope) flags.scope = params.scope;
         const args: CommandArgs = {
           positional: params.scope ? [] : [params.source],
@@ -277,10 +275,10 @@ export function registerCatalog(pi: ExtensionAPI): void {
     name: "ct_toggle",
     label: "Catalog Toggle",
     description:
-      "Toggle a package's rating through the cycle: core → useful → debatable → disabled → core.",
-    promptSnippet: "Toggle a package's catalog rating",
+      "Toggle a package's enabled state (enabled ↔ disabled).",
+    promptSnippet: "Toggle a package's enabled state",
     promptGuidelines: [
-      "Use ct_toggle when the user wants to cycle a package's rating.",
+      "Use ct_toggle when the user wants to enable or disable a package.",
     ],
     parameters: Type.Object({
       name: Type.String({ description: "Package name to toggle" }),

package/src/sync/pull.ts

@@ -2,6 +2,7 @@ import yaml from "js-yaml";
 
 import { CatalogYamlSchema, LockFileSchema } from "../config/schema.js";
 import type { CatalogYaml, LockFile } from "../config/schema.js";
+import { migrateRatingToEnabledRaw } from "../catalog/migrate.js";
 import { readGist, findGistByDescription } from "./gist.js";
 import { readCachedGistId, writeCachedGistId } from "./cache.js";
 
@@ -62,6 +63,7 @@ export async function pullCatalog(
   const lockJsonContent = gist.files["catalog.lock.json"]?.content ?? "";
 
   const parsedYaml = yaml.load(catYamlContent);
+  migrateRatingToEnabledRaw(parsedYaml);
   const catalog: CatalogYaml = CatalogYamlSchema.parse(parsedYaml);
 
   const parsedLock = JSON.parse(lockJsonContent);