@pi-stef/catalog 0.2.2

package/README.md

@@ -0,0 +1,205 @@
+# @pi-stef/catalog
+
+Declarative package manager for the [pi](https://pi.dev) coding agent. Manage your skills and extensions from a single `cat.yaml` file, sync across machines via GitHub Gist.
+
+## Installation
+
+From the monorepo root (while developing):
+
+```bash
+pi install packages/catalog
+```
+
+Once published to npm:
+
+```bash
+pi install npm:@pi-stef/catalog
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate with GitHub (requires gh CLI)
+/ct login
+
+# 2. Initialize catalog from installed packages (or import from a gist)
+/ct init
+#   or: /ct init --from-gist=<gist-id>
+
+# 3. Sync — install missing, remove orphaned, push changes to gist
+/ct sync
+```
+
+After `ct login`, your GitHub token is cached for future sync operations.
+
+## Command Reference
+
+All commands are invoked as `/ct <subcommand>` inside pi, or via the shorthand `/ct-<subcommand>`.
+
+| Subcommand | Alias | Description | Flags |
+|---|---|---|---|
+| `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) | — |
+| `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 | — |
+| `diff` | — | Show diff between local and remote catalog | — |
+| `verify` | — | Verify catalog integrity (sources, ratings, duplicates) | — |
+| `profiles` | — | List all profiles with active indicator | — |
+| `profile` | — | Show or switch active profile | — |
+
+### 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 an npm package
+/ct add lodash npm:lodash
+```
+
+### Removing Packages
+
+```bash
+/ct remove my-skill
+```
+
+## `cat.yaml` Format
+
+The catalog is stored in `cat.yaml`. Example:
+
+```yaml
+meta:
+  pi_version: "0.70.0"
+  activeProfile: default
+
+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
+
+| 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
+
+**NPM source:**
+```yaml
+packages:
+  lodash:
+    source: "npm:lodash"
+    rating: useful
+```
+
+**Git source:**
+```yaml
+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
+```
+
+## Profiles
+
+Profiles let you maintain different package sets for different machines or contexts (e.g., work vs. personal).
+
+```yaml
+meta:
+  pi_version: "0.70.0"
+  activeProfile: work
+
+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:**
+- `/ct profiles` — list all profiles (shows active with a marker)
+- `/ct profile <name>` — switch active profile
+- `--profile=<name>` flag on `sync`, `push`, `pull` — operate on a specific profile
+
+The `default` profile always exists and uses the base `packages` section. Profile packages override base packages with the same key.
+
+## Configuration
+
+### File Locations
+
+| File | Path | Purpose |
+|---|---|---|
+| Catalog | `~/.pi/sf/catalog/cat.yaml` | Declarative package manifest |
+| Lock file | `~/.pi/sf/catalog/catalog.lock.json` | Installed versions and hashes |
+| Gist cache | `~/.pi/sf/catalog/` | Cached gist ID for sync |
+
+### GitHub Gist Setup
+
+Sync uses GitHub Gists for cloud storage. Prerequisites:
+
+1. Install the [GitHub CLI (`gh`)](https://cli.github.com/)
+2. Authenticate: `gh auth login`
+3. Run `/ct login` inside pi to verify and cache your token
+
+On first `ct push` or `ct sync`, a secret gist is created automatically.
+
+## Development
+
+```bash
+pnpm install          # Install dependencies
+pnpm -F @pi-stef/catalog test    # Run tests
+pnpm -F @pi-stef/catalog typecheck  # Type check
+```
+
+## License
+
+MIT

package/extensions/catalog.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerCatalog } from "../src/register.js";
+
+export default function catalogExtension(pi: ExtensionAPI): void {
+  registerCatalog(pi);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pi-stef/catalog",
+  "version": "0.2.2",
+  "description": "Pi extension for managing skill/package catalogs.",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "src/",
+    "extensions/"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "catalog"
+  ],
+  "dependencies": {
+    "@octokit/rest": "^21.0.0",
+    "js-yaml": "^4.1.0",
+    "@sinclair/typebox": "*",
+    "zod": "^3.25.62",
+    "@pi-stef/paths": "0.2.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/catalog/crud.ts

@@ -0,0 +1,143 @@
+import type { CatalogYaml, CatalogPackage } from "../config/schema.js";
+import type { RatingValue } from "./ratings.js";
+import { isValidSource, isDisabled, nextRating } from "./ratings.js";
+
+// ---------------------------------------------------------------------------
+// Immutable helpers
+// ---------------------------------------------------------------------------
+
+/** Shallow-clone the catalog and deep-clone the packages record. */
+function cloneCatalog(catalog: CatalogYaml): CatalogYaml {
+  return {
+    ...catalog,
+    packages: { ...catalog.packages },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Add a new package to the catalog.
+ *
+ * @throws if a package with the same name already exists
+ * @throws if the source format is invalid
+ */
+export function addPackage(
+  catalog: CatalogYaml,
+  name: string,
+  source: string,
+  rating: RatingValue,
+  type?: "skill" | "pi-native",
+): CatalogYaml {
+  if (catalog.packages[name]) {
+    throw new Error(`Package "${name}" already exists`);
+  }
+
+  if (!isValidSource(source)) {
+    throw new Error(
+      `Invalid source "${source}": must start with "npm:" or "git:"`,
+    );
+  }
+
+  const entry: CatalogPackage = { source, rating };
+  if (type !== undefined) {
+    entry.type = type;
+  }
+
+  const next = cloneCatalog(catalog);
+  next.packages[name] = entry;
+  return next;
+}
+
+/**
+ * Remove a package from the catalog.
+ *
+ * @throws if the package is not found
+ */
+export function removePackage(
+  catalog: CatalogYaml,
+  name: string,
+): CatalogYaml {
+  if (!catalog.packages[name]) {
+    throw new Error(`Package "${name}" not found`);
+  }
+
+  const next = cloneCatalog(catalog);
+  delete next.packages[name];
+  return next;
+}
+
+/**
+ * Toggle a package's rating through the cycle:
+ * core → useful → debatable → disabled → core
+ *
+ * @throws if the package is not found
+ */
+export function togglePackage(
+  catalog: CatalogYaml,
+  name: string,
+): CatalogYaml {
+  const entry = catalog.packages[name];
+  if (!entry) {
+    throw new Error(`Package "${name}" not found`);
+  }
+
+  const next = cloneCatalog(catalog);
+  next.packages[name] = {
+    ...entry,
+    rating: nextRating(entry.rating),
+  };
+  return next;
+}
+
+/**
+ * Enable a disabled package, restoring its previous rating (or "core").
+ * No-op when the package is already enabled.
+ *
+ * @throws if the package is not found
+ */
+export function enablePackage(
+  catalog: CatalogYaml,
+  name: string,
+): CatalogYaml {
+  const entry = catalog.packages[name];
+  if (!entry) {
+    throw new Error(`Package "${name}" not found`);
+  }
+
+  // No-op if already enabled
+  if (!isDisabled(entry.rating)) {
+    return catalog;
+  }
+
+  const restored = entry.previousRating ?? "core";
+  const next = cloneCatalog(catalog);
+  const { previousRating: _, ...clean } = entry;
+  next.packages[name] = { ...clean, rating: restored };
+  return next;
+}
+
+/**
+ * Disable a package, saving its current rating for later restoration.
+ *
+ * @throws if the package is not found
+ */
+export function disablePackage(
+  catalog: CatalogYaml,
+  name: string,
+): CatalogYaml {
+  const entry = catalog.packages[name];
+  if (!entry) {
+    throw new Error(`Package "${name}" not found`);
+  }
+
+  const next = cloneCatalog(catalog);
+  next.packages[name] = {
+    ...entry,
+    previousRating: entry.rating,
+    rating: "disabled",
+  };
+  return next;
+}

package/src/catalog/install.ts

@@ -0,0 +1,181 @@
+/**
+ * Scanning installed pi packages from settings.json.
+ *
+ * S-302: scanInstalled reads ~/.pi/agent/settings.json and optionally
+ * <cwd>/.pi/settings.json (project variant), parses the `packages`
+ * array from each, and returns a merged map keyed by package name
+ * with source, name, and version info. Project settings take
+ * precedence over global for the same package key.
+ */
+
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+
+import { parseSource } from "./source.js";
+import { npmNodeModulesDir } from "../config/paths.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface InstalledPackage {
+  /** The raw source string as it appears in settings.json. */
+  source: string;
+  /**
+   * Human-readable / identity name derived from the source.
+   * For npm: the npm package name (e.g. "@foo/bar").
+   * For git: host/path (e.g. "github.com/user/repo").
+   * For local: directory basename or the path itself.
+   */
+  name: string;
+  /** Installed version if discoverable, otherwise undefined. */
+  version: string | undefined;
+}
+
+export type InstalledMap = Record<string, InstalledPackage>;
+
+// ---------------------------------------------------------------------------
+// Version resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to read the version from an installed npm package's package.json.
+ * Returns undefined if the file doesn't exist or can't be read.
+ */
+function readNpmVersion(
+  home: string,
+  npmName: string,
+): string | undefined {
+  const pkgJsonPath = path.join(
+    npmNodeModulesDir(home),
+    npmName,
+    "package.json",
+  );
+  try {
+    const raw = fs.readFileSync(pkgJsonPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === "string" ? parsed.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Attempt to read the version from a local path package's package.json.
+ * Returns undefined if the file doesn't exist or can't be read.
+ */
+function readLocalVersion(home: string, localPath: string): string | undefined {
+  // Resolve relative paths against home (settings dir)
+  const settingsDir = path.join(home, ".pi", "agent");
+  const resolved = path.resolve(settingsDir, localPath);
+  const pkgJsonPath = path.join(resolved, "package.json");
+  try {
+    const raw = fs.readFileSync(pkgJsonPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === "string" ? parsed.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// scanInstalled
+// ---------------------------------------------------------------------------
+
+/**
+ * Read packages from a settings.json file and return a map of installed packages.
+ * Returns empty map if the file doesn't exist or is malformed.
+ */
+function readPackagesFromSettings(
+  settingsPath: string,
+  home: string,
+): InstalledMap {
+  let settingsJson: string;
+  try {
+    settingsJson = fs.readFileSync(settingsPath, "utf-8");
+  } catch (err: unknown) {
+    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
+      return {};
+    }
+    throw err;
+  }
+
+  let settings: Record<string, unknown>;
+  try {
+    settings = JSON.parse(settingsJson);
+  } catch (parseErr: unknown) {
+    throw new Error(
+      `Malformed JSON in ${settingsPath}: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`,
+    );
+  }
+
+  const packages = settings.packages;
+  if (!Array.isArray(packages)) {
+    return {};
+  }
+
+  const result: InstalledMap = {};
+
+  for (const entry of packages) {
+    let rawSource: string;
+    if (typeof entry === "string") {
+      rawSource = entry;
+    } else if (
+      entry != null &&
+      typeof entry === "object" &&
+      "source" in entry &&
+      typeof (entry as { source: unknown }).source === "string"
+    ) {
+      rawSource = (entry as { source: string }).source;
+    } else {
+      continue;
+    }
+
+    const parsed = parseSource(rawSource);
+
+    let version: string | undefined;
+    if (parsed.type === "npm") {
+      version = readNpmVersion(home, parsed.npmName!);
+    } else if (parsed.type === "local") {
+      version = readLocalVersion(home, rawSource);
+    }
+
+    const key = parsed.type === "local" ? rawSource : parsed.name;
+
+    result[key] = {
+      source: rawSource,
+      name: parsed.name,
+      version,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Discover currently installed pi packages by reading
+ * `~/.pi/agent/settings.json` and optionally
+ * `<cwd>/.pi/settings.json`.
+ *
+ * When `cwd` is provided, project settings are merged on top of
+ * global settings — project packages take precedence for the same key.
+ *
+ * Returns a map keyed by package identity name, each entry containing
+ * the raw source, derived name, and version (if discoverable).
+ */
+export function scanInstalled(home?: string, cwd?: string): InstalledMap {
+  const resolvedHome = home ?? os.homedir();
+  const globalPath = path.join(resolvedHome, ".pi", "agent", "settings.json");
+
+  const result = readPackagesFromSettings(globalPath, resolvedHome);
+
+  if (cwd) {
+    const projectPath = path.join(cwd, ".pi", "settings.json");
+    const projectPackages = readPackagesFromSettings(projectPath, resolvedHome);
+    // Project packages override global for the same key
+    Object.assign(result, projectPackages);
+  }
+
+  return result;
+}

package/src/catalog/ratings.ts

@@ -0,0 +1,32 @@
+/** 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:
+ *   - npm:<package-name>
+ *   - git:<url>
+ *   - git:<url>#<subpath>
+ *   - local paths (relative or absolute)
+ */
+export function isValidSource(source: string): boolean {
+  if (!source) return false;
+  if (/^npm:/.test(source)) return true;
+  if (/^git:/.test(source)) return true;
+  // Local paths (relative or absolute) are also valid
+  if (source.startsWith("./") || source.startsWith("../") || source.startsWith("/")) return true;
+  return false;
+}