@pi-stef/catalog 0.3.5 → 0.4.0

package/package.json

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

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/commands/add.ts

@@ -13,6 +13,8 @@
 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 { PI_STEF_PACKAGES } from "../catalog/packages.js";
 import { readCatalog, writeCatalog } from "../config/io.js";
 import { piInstall } from "../util/exec.js";
 
@@ -75,18 +77,95 @@ function resolveType(
 /**
  * Execute the `ct add` subcommand.
  *
+ * New syntax (preferred): `ct add <source> [--rating ...] [--type ...]`
+ *   — name is auto-derived from source via `sourceToKey()`.
+ *
+ * Legacy syntax (deprecated): `ct add <name> <source> [--rating ...] [--type ...]`
+ *   — still accepted but emits a deprecation warning.
+ *
  * Reads the catalog, validates inputs, prompts for type if needed,
  * adds the package, writes the catalog, and runs `pi install`.
  */
 export async function addCommand(args: CommandArgs, ctx: AddCtx): Promise<void> {
   const { positional, flags } = args;
-  const name = positional[0];
-  const source = positional[1];
 
-  // --- Validate required args -----------------------------------------------
-  if (!name || !source) {
+  // --- Handle --scope batch mode ---------------------------------------------
+  if ("scope" in flags) {
+    const scope = flags["scope"];
+    if (scope !== "@pi-stef") {
+      ctx.ui.notify(`Unsupported scope: "${scope}". Use --scope @pi-stef.`, "error");
+      return;
+    }
+
+    const catalog = readCatalog(ctx.home);
+    const rating = resolveRating(flags);
+    let added = 0;
+    let skipped = 0;
+    let currentCatalog = catalog;
+
+    for (const pkg of PI_STEF_PACKAGES) {
+      const npmSource = `npm:${pkg}`;
+
+      // Skip if already in catalog
+      if (currentCatalog.packages[pkg]) {
+        skipped++;
+        continue;
+      }
+
+      try {
+        currentCatalog = addPackage(currentCatalog, pkg, npmSource, rating);
+        added++;
+      } catch (err: unknown) {
+        // Unexpected validation error — warn but continue
+        ctx.ui.notify(
+          `Warning: failed to add "${pkg}": ${err instanceof Error ? err.message : String(err)}`,
+          "warning",
+        );
+        skipped++;
+      }
+    }
+
+    if (added > 0) {
+      writeCatalog(currentCatalog, ctx.home);
+    }
+
+    // Install all added packages
+    if (added > 0) {
+      for (const pkg of PI_STEF_PACKAGES) {
+        if (currentCatalog.packages[pkg]?.source === `npm:${pkg}`) {
+          try {
+            await piInstall(`npm:${pkg}`);
+          } catch {
+            ctx.ui.notify(`Warning: install of "${pkg}" failed`, "warning");
+          }
+        }
+      }
+    }
+
+    ctx.ui.notify(
+      `Scope @pi-stef: added ${added}, skipped ${skipped} (already in catalog)`,
+      "info",
+    );
+    return;
+  }
+
+  // --- Handle legacy 2-arg syntax: ct add <name> <source> -------------------
+  let name: string;
+  let source: string;
+
+  if (positional.length >= 2) {
+    name = positional[0];
+    source = positional[1];
+    ctx.ui.notify(
+      `"ct add <name> <source>" is legacy. Use "ct add <source>" — name is auto-derived.`,
+      "warning",
+    );
+  } else if (positional.length === 1) {
+    source = positional[0];
+    name = sourceToKey(source);
+  } else {
     ctx.ui.notify(
-      "Usage: ct add <name> <source> [--rating <core|useful|debatable>] [--type <skill|pi-native>]",
+      "Usage: ct add <source> [--rating <core|useful|debatable>] [--type <skill|pi-native>]",
       "error",
     );
     return;

package/src/commands/definitions.ts

@@ -31,6 +31,7 @@ export const SUBCOMMAND_DEFS: readonly SubcommandDef[] = [
   { 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: "update", aliases: ["up"], description: "Update packages to latest versions" },
   { name: "disable", description: "Disable a package" },
   { name: "enable", description: "Enable a package" },
   { name: "push", description: "Push catalog to remote gist" },
@@ -41,6 +42,7 @@ export const SUBCOMMAND_DEFS: readonly SubcommandDef[] = [
   { name: "verify", description: "Verify catalog integrity" },
   { name: "profiles", description: "List available profiles" },
   { name: "profile", description: "Show or switch active profile" },
+  { name: "reset", description: "Reset catalog: uninstall all @pi-stef packages and delete config" },
 ] as const;
 
 // ---------------------------------------------------------------------------

package/src/commands/remove.ts

@@ -12,6 +12,7 @@
 
 import type { CommandArgs, CommandCtx } from "./types.js";
 import { removePackage } from "../catalog/crud.js";
+import { isPiStefSource } from "../catalog/packages.js";
 import { readCatalog, writeCatalog, readLock, writeLock } from "../config/io.js";
 import { piUninstall } from "../util/exec.js";
 
@@ -41,6 +42,77 @@ export async function removeCommand(
   ctx: RemoveCtx,
 ): Promise<void> {
   const { positional, flags } = args;
+
+  // --- Handle --scope batch mode ---------------------------------------------
+  if ("scope" in flags) {
+    const scope = flags["scope"];
+    if (scope !== "@pi-stef") {
+      ctx.ui.notify(`Unsupported scope: "${scope}". Use --scope @pi-stef.`, "error");
+      return;
+    }
+
+    const catalog = readCatalog(ctx.home);
+    const lock = readLock(ctx.home);
+
+    // isPiStefSource returns false for @pi-stef/catalog by design (see packages.ts)
+    const piStefNames = Object.keys(catalog.packages).filter(
+      (name) => isPiStefSource(catalog.packages[name].source),
+    );
+
+    if (piStefNames.length === 0) {
+      ctx.ui.notify("No @pi-stef packages found in catalog", "info");
+      return;
+    }
+
+    // Confirmation
+    const skipConfirm = "yes" in flags || "y" in flags;
+    if (!skipConfirm && ctx.ui.confirm) {
+      const confirmed = await ctx.ui.confirm(
+        `Remove ${piStefNames.length} @pi-stef packages from catalog?`,
+      );
+      if (!confirmed) {
+        ctx.ui.notify("Removal cancelled", "info");
+        return;
+      }
+    }
+
+    // Capture sources before removing
+    const sources: Record<string, string> = {};
+    for (const name of piStefNames) {
+      sources[name] = catalog.packages[name].source;
+    }
+
+    // Remove all from catalog and lock file
+    for (const name of piStefNames) {
+      delete catalog.packages[name];
+      if (lock.packages[name]) {
+        delete lock.packages[name];
+      }
+    }
+
+    writeCatalog(catalog, ctx.home);
+    writeLock(lock, ctx.home);
+
+    // Uninstall all
+    let uninstalled = 0;
+    let failed = 0;
+    for (const name of piStefNames) {
+      try {
+        await piUninstall(sources[name]);
+        uninstalled++;
+      } catch {
+        ctx.ui.notify(`Warning: uninstall of "${name}" failed`, "warning");
+        failed++;
+      }
+    }
+
+    ctx.ui.notify(
+      `Scope @pi-stef: removed ${piStefNames.length}, uninstalled ${uninstalled}${failed > 0 ? ` (${failed} uninstall failed)` : ""}`,
+      failed > 0 ? "warning" : "info",
+    );
+    return;
+  }
+
   const name = positional[0];
 
   // --- Validate required args -----------------------------------------------

package/src/commands/reset.ts

@@ -0,0 +1,134 @@
+/**
+ * `ct reset` subcommand implementation.
+ *
+ * Full nuke: uninstalls all @pi-stef packages, deletes gist refs,
+ * deletes config files (cat.yaml, catalog.lock.json, .gist),
+ * and removes the empty catalog directory.
+ *
+ * Usage:
+ *   - `ct reset` — prompts for confirmation
+ *   - `ct reset --yes` — skips confirmation
+ *
+ * This is a destructive operation. The catalog can be re-initialized
+ * with `ct init` after resetting.
+ */
+
+import fs from "node:fs";
+import type { CommandArgs, CommandCtx } from "./types.js";
+import { isPiStefSource } from "../catalog/packages.js";
+import { catalogDir, catalogFile, lockFile } from "../config/paths.js";
+import { piUninstall } from "../util/exec.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Context for `resetCommand`, extending the base with `confirm`. */
+export interface ResetCtx extends CommandCtx {
+  ui: CommandCtx["ui"] & {
+    confirm?: (message: string) => Promise<boolean>;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resetCommand
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute the `ct reset` subcommand.
+ *
+ * 1. Check cat.yaml exists
+ * 2. Confirm (skippable with --yes)
+ * 3. Find @pi-stef packages (isPiStefSource excludes catalog)
+ * 4. pi uninstall each
+ * 5. Delete config files with fs.rmSync({ recursive: true, force: true })
+ * 6. Remove empty catalog directory
+ */
+export async function resetCommand(
+  args: CommandArgs,
+  ctx: ResetCtx,
+): Promise<void> {
+  const { flags } = args;
+
+  // --- Check cat.yaml exists ------------------------------------------------
+  const catPath = catalogFile(ctx.home);
+  if (!fs.existsSync(catPath)) {
+    ctx.ui.notify("No catalog found. Run `ct init` first.", "error");
+    return;
+  }
+
+  // --- Confirmation ----------------------------------------------------------
+  const skipConfirm = "yes" in flags || "y" in flags;
+  if (!skipConfirm && ctx.ui.confirm) {
+    const confirmed = await ctx.ui.confirm(
+      "This will uninstall all @pi-stef packages and delete all catalog config. Continue?",
+    );
+    if (!confirmed) {
+      ctx.ui.notify("Reset cancelled", "info");
+      return;
+    }
+  }
+
+  // --- Find @pi-stef packages -----------------------------------------------
+  // Read catalog directly (raw YAML) to avoid schema validation on corrupt files
+  let packages: Record<string, { source: string }> = {};
+  try {
+    const yaml = await import("js-yaml");
+    const content = fs.readFileSync(catPath, "utf8");
+    const parsed = yaml.load(content) as { packages?: Record<string, { source: string }> };
+    packages = parsed?.packages ?? {};
+  } catch {
+    // If YAML is corrupt, we still want to delete config files
+    ctx.ui.notify("Warning: could not parse cat.yaml — skipping uninstall step", "warning");
+  }
+
+  const piStefNames = Object.keys(packages).filter(
+    (name) => isPiStefSource(packages[name].source),
+  );
+
+  // --- Uninstall @pi-stef packages ------------------------------------------
+  let uninstalled = 0;
+  let failed = 0;
+
+  for (const name of piStefNames) {
+    try {
+      await piUninstall(packages[name].source);
+      uninstalled++;
+    } catch {
+      ctx.ui.notify(`Warning: uninstall of "${name}" failed`, "warning");
+      failed++;
+    }
+  }
+
+  // --- Delete config files --------------------------------------------------
+  const dir = catalogDir(ctx.home);
+  const gistPath = `${dir}/.gist`;
+
+  // Delete individual files first, then the directory
+  for (const filePath of [catPath, lockFile(ctx.home), gistPath]) {
+    try {
+      fs.rmSync(filePath, { force: true });
+    } catch {
+      // Ignore errors — file may not exist
+    }
+  }
+
+  // Remove the catalog directory itself
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Ignore errors — directory may not exist or be non-empty
+  }
+
+  // --- Report ----------------------------------------------------------------
+  const parts: string[] = [];
+  if (piStefNames.length > 0) {
+    parts.push(`uninstalled ${uninstalled}/${piStefNames.length} packages`);
+  }
+  parts.push("deleted config files");
+
+  ctx.ui.notify(
+    `Reset complete: ${parts.join(", ")}${failed > 0 ? ` (${failed} uninstall failed)` : ""}`,
+    failed > 0 ? "warning" : "info",
+  );
+}

package/src/commands/update.ts

@@ -0,0 +1,85 @@
+/**
+ * `ct update` subcommand implementation.
+ *
+ * Updates packages to their latest versions by running `pi update <source>`.
+ *
+ * Usage:
+ *   - `ct update <name>` — update a single package by catalog name
+ *   - `ct update --all` — update all packages in the catalog
+ *
+ * After updating, a `/ct sync` should be run to persist changes to the remote gist.
+ */
+
+import type { CommandArgs, CommandCtx } from "./types.js";
+import { readCatalog } from "../config/io.js";
+import { piUpdate } from "../util/exec.js";
+
+// ---------------------------------------------------------------------------
+// updateCommand
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute the `ct update` subcommand.
+ *
+ * Reads the catalog, resolves the target package(s), and runs
+ * `pi update <source>` for each.
+ */
+export async function updateCommand(
+  args: CommandArgs,
+  ctx: CommandCtx,
+): Promise<void> {
+  const { positional, flags } = args;
+  const updateAll = "all" in flags;
+  const name = positional[0];
+
+  if (!name && !updateAll) {
+    ctx.ui.notify("Usage: ct update <name> | ct update --all", "error");
+    return;
+  }
+
+  const catalog = readCatalog(ctx.home);
+  const packages = catalog.packages;
+
+  // --- Single package update ------------------------------------------------
+  if (name) {
+    const entry = packages[name];
+    if (!entry) {
+      ctx.ui.notify(`Package "${name}" not found in catalog`, "error");
+      return;
+    }
+
+    try {
+      await piUpdate(entry.source);
+      ctx.ui.notify(`Updated "${name}"`, "info");
+    } catch {
+      ctx.ui.notify(`Warning: update of "${name}" failed`, "warning");
+    }
+    return;
+  }
+
+  // --- Update all -----------------------------------------------------------
+  const names = Object.keys(packages);
+  if (names.length === 0) {
+    ctx.ui.notify("Catalog is empty — nothing to update", "info");
+    return;
+  }
+
+  let updated = 0;
+  let failed = 0;
+
+  for (const pkgName of names) {
+    const entry = packages[pkgName];
+    try {
+      await piUpdate(entry.source);
+      updated++;
+    } catch {
+      ctx.ui.notify(`Warning: update of "${pkgName}" failed`, "warning");
+      failed++;
+    }
+  }
+
+  ctx.ui.notify(
+    `Updated ${updated}/${names.length} packages${failed > 0 ? ` (${failed} failed)` : ""}`,
+    failed > 0 ? "warning" : "info",
+  );
+}

package/src/register.ts

@@ -15,6 +15,8 @@ import {
 import { addCommand, type AddCtx } from "./commands/add.js";
 import { initCommand, type InitContext } from "./commands/init.js";
 import { removeCommand, type RemoveCtx } from "./commands/remove.js";
+import { updateCommand } from "./commands/update.js";
+import { resetCommand, type ResetCtx } from "./commands/reset.js";
 import {
   toggleCommand,
   enableCommand,
@@ -109,6 +111,9 @@ async function handleSubcommand(
     case "toggle":
       await toggleCommand(parsed, ctx as ToggleCtx);
       break;
+    case "update":
+      await updateCommand(parsed, ctx);
+      break;
     case "enable":
       await enableCommand(parsed, ctx as ToggleCtx);
       break;
@@ -133,6 +138,9 @@ async function handleSubcommand(
     case "profile":
       await profileCommand(parsed, ctx as ProfilesCtx);
       break;
+    case "reset":
+      await resetCommand(parsed, ctx as ResetCtx);
+      break;
     default:
       ctx.ui.notify(`ct ${canonical}: not yet implemented`, "info");
   }
@@ -209,24 +217,27 @@ export function registerCatalog(pi: ExtensionAPI): void {
     name: "ct_add",
     label: "Catalog Add",
     description:
-      "Add a package to the catalog by name and source. Source must start with 'npm:' or 'git:'.",
+      "Add a package to the catalog by source. Name is auto-derived from source. Source must start with 'npm:' or 'git:'.",
     promptSnippet: "Add a package to the catalog",
     promptGuidelines: [
       "Use ct_add when the user asks to add a new package or skill to their catalog.",
     ],
     parameters: Type.Object({
-      name: Type.String({ description: "Package name" }),
       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.name, params.source],
-          flags: params.rating ? { rating: params.rating } : {},
+          positional: params.scope ? [] : [params.source],
+          flags,
         };
         await addCommand(args, ctx as unknown as AddCtx);
-        return { content: [{ type: "text" as const, text: `Added ${params.name}.` }], details: undefined as unknown };
+        return { content: [{ type: "text" as const, text: `Added ${params.source}.` }], details: undefined as unknown };
       } catch (err) {
         return { content: [{ type: "text" as const, text: `Add failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
       }
@@ -242,13 +253,20 @@ export function registerCatalog(pi: ExtensionAPI): void {
       "Use ct_remove when the user asks to remove or uninstall a package from their catalog.",
     ],
     parameters: Type.Object({
-      name: Type.String({ description: "Package name to remove" }),
+      name: Type.Optional(Type.String({ description: "Package name to remove" })),
+      scope: Type.Optional(Type.String({ description: "Batch scope: '@pi-stef' to remove all @pi-stef packages" })),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
-        const args: CommandArgs = { positional: [params.name], flags: {} };
+        const flags: Record<string, true | string> = {};
+        if (params.scope) flags.scope = params.scope;
+        const args: CommandArgs = {
+          positional: params.name ? [params.name] : [],
+          flags,
+        };
         await removeCommand(args, ctx as unknown as RemoveCtx);
-        return { content: [{ type: "text" as const, text: `Removed ${params.name}.` }], details: undefined as unknown };
+        const label = params.scope ? `Scope ${params.scope}` : `${params.name}`;
+        return { content: [{ type: "text" as const, text: `Removed ${label}.` }], details: undefined as unknown };
       } catch (err) {
         return { content: [{ type: "text" as const, text: `Remove failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
       }
@@ -278,6 +296,58 @@ export function registerCatalog(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: "ct_update",
+    label: "Catalog Update",
+    description:
+      "Update packages to their latest versions. Run `pi update` behind the scenes.",
+    promptSnippet: "Update catalog packages",
+    promptGuidelines: [
+      "Use ct_update when the user asks to update one or more packages in their catalog.",
+    ],
+    parameters: Type.Object({
+      name: Type.Optional(Type.String({ description: "Package name to update (omit for --all)" })),
+      all: Type.Optional(Type.Boolean({ description: "Update all packages" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const positional = params.name ? [params.name] : [];
+        const flags: Record<string, true | string> = {};
+        if (params.all) flags.all = true;
+        const args: CommandArgs = { positional, flags };
+        await updateCommand(args, ctx);
+        return { content: [{ type: "text" as const, text: "Update completed." }], details: undefined as unknown };
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Update failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "ct_reset",
+    label: "Catalog Reset",
+    description:
+      "Full nuke: uninstall all @pi-stef packages, delete gist refs, delete config files.",
+    promptSnippet: "Reset catalog completely",
+    promptGuidelines: [
+      "Use ct_reset when the user wants to completely remove all @pi-stef packages and catalog config.",
+    ],
+    parameters: Type.Object({
+      yes: Type.Optional(Type.Boolean({ description: "Skip confirmation prompt" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const flags: Record<string, true | string> = {};
+        if (params.yes) flags.yes = true;
+        const args: CommandArgs = { positional: [], flags };
+        await resetCommand(args, ctx as unknown as ResetCtx);
+        return { content: [{ type: "text" as const, text: "Reset completed." }], details: undefined as unknown };
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Reset failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
+      }
+    },
+  });
+
   pi.registerTool({
     name: "ct_status",
     label: "Catalog Status",

package/src/util/exec.ts

@@ -158,3 +158,15 @@ export function piUninstall(
 ): Promise<ExecResult> {
   return execCommand("pi", ["uninstall", packageName], options);
 }
+
+/**
+ * Update a pi package from the given source.
+ *
+ * Runs `pi update <source>`.
+ */
+export function piUpdate(
+  source: string,
+  options?: PiExecOptions,
+): Promise<ExecResult> {
+  return execCommand("pi", ["update", source], options);
+}