@pi-stef/catalog 0.3.5 → 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.3.5",
+  "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/packages.ts

@@ -0,0 +1,56 @@
+/**
+ * Hardcoded list of @pi-stef packages for scope-based batch operations.
+ *
+ * Used by `ct add --scope @pi-stef` and `ct remove --scope @pi-stef`
+ * to identify which packages belong to the @pi-stef ecosystem.
+ *
+ * NOTE: `@pi-stef/catalog` is intentionally excluded — it manages the
+ * other packages and should not be batch-operated on itself.
+ */
+
+import { extractNpmName } from "./source.js";
+
+/** The catalog package itself (excluded from batch operations). */
+export const CATALOG_PACKAGE_NAME = "@pi-stef/catalog";
+
+/**
+ * All @pi-stef packages except the catalog itself.
+ *
+ * This list is used for `--scope @pi-stef` batch operations.
+ */
+export const PI_STEF_PACKAGES: readonly string[] = [
+  "@pi-stef/agent-workflows",
+  "@pi-stef/atlassian",
+  "@pi-stef/figma",
+  "@pi-stef/paths",
+  "@pi-stef/team",
+  "@pi-stef/web",
+] as const;
+
+/**
+ * Returns true if the given package name is a @pi-stef package
+ * (excluding the catalog itself).
+ */
+export function isPiStefPackage(name: string): boolean {
+  return PI_STEF_PACKAGES.includes(name);
+}
+
+/**
+ * Returns true if the source string refers to a @pi-stef package.
+ *
+ * Handles both `npm:@scope/pkg@version` and bare package name formats.
+ * Explicitly excludes `@pi-stef/catalog` — it manages the others
+ * and should not be included in batch scope operations.
+ */
+export function isPiStefSource(source: string): boolean {
+  // npm: prefixed source — extract the package name
+  if (source.startsWith("npm:")) {
+    const pkgName = extractNpmName(source.slice(4));
+    // Never include the catalog package itself in batch operations
+    if (pkgName === CATALOG_PACKAGE_NAME) return false;
+    return PI_STEF_PACKAGES.includes(pkgName);
+  }
+
+  // Non-npm source — check if it's a bare package name
+  return PI_STEF_PACKAGES.includes(source);
+}

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);
+}