@pi-stef/catalog 0.3.5 → 0.5.0

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

@@ -0,0 +1,113 @@
+/**
+ * `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";
+import { checkSetupForSource, formatSetupStatus } from "../catalog/setup.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;
+    }
+
+    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;
+  }
+
+  // --- 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;
+  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?.();
+
+  const parts: string[] = [
+    `Updated ${updated}/${names.length} packages${failed > 0 ? ` (${failed} failed)` : ""}`,
+  ];
+  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

@@ -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,25 @@ 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.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 +251,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 };
       }
@@ -259,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" }),
@@ -278,6 +294,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/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);

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