@pi-stef/catalog 0.2.2

package/src/catalog/reconcile.ts

@@ -0,0 +1,339 @@
+/**
+ * Reconciliation engine for catalog packages.
+ *
+ * S-303: reconcile(catalog, installed, options?) compares the desired catalog
+ * state against currently installed packages and returns a ReconcilePlan with
+ * install, uninstall, upgrade actions and orphan reports.
+ *
+ * executeActions(plan, options?) runs the shell commands via piInstall /
+ * piUninstall and updates the lock file on success.
+ */
+
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { piInstall, piUninstall } from "../util/exec.js";
+import { lockFile } from "../config/paths.js";
+import type { LockFile } from "../config/schema.js";
+import type { InstalledMap } from "./install.js";
+import {
+  sourceToKey,
+  extractNpmVersion,
+  extractVersionFromSource,
+} from "./source.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A catalog entry as consumed by reconcile. */
+export interface CatalogEntry {
+  /** Source string (e.g. "npm:@foo/bar@1.0.0", "git:github.com/user/repo"). */
+  source: string;
+  /** Whether the package should be managed. Defaults to true when absent. */
+  enabled?: boolean;
+}
+
+export interface InstallAction {
+  type: "install";
+  /** Catalog key for the package. */
+  key: string;
+  source: string;
+}
+
+export interface UninstallAction {
+  type: "uninstall";
+  /** Installed-map key to uninstall. */
+  key: string;
+  source: string;
+}
+
+export interface UpgradeAction {
+  type: "upgrade";
+  /** Installed-map key. */
+  key: string;
+  source: string;
+  currentVersion?: string;
+  targetVersion?: string;
+}
+
+export interface OrphanReport {
+  /** Installed-map key of the orphan package. */
+  key: string;
+  source: string;
+  version?: string;
+}
+
+export interface ReconcilePlan {
+  installs: InstallAction[];
+  uninstalls: UninstallAction[];
+  upgrades: UpgradeAction[];
+  orphans: OrphanReport[];
+}
+
+export interface ReconcileOptions {
+  /** If true, uninstall actions are also generated for orphans. */
+  removeOrphans?: boolean;
+}
+
+export interface ActionError {
+  action: InstallAction | UninstallAction | UpgradeAction;
+  error: Error;
+}
+
+export interface ExecuteResult {
+  success: boolean;
+  errors: ActionError[];
+}
+
+export interface ExecuteOptions {
+  /** Home directory override (for lock file path). */
+  home?: string;
+  /** Lock file writer override (for testing). Defaults to fs.writeFileSync. */
+  lockFileWriter?: (filePath: string, content: string) => void;
+  /** If true, skip actual shell execution and lock file writes. Returns success with no errors. */
+  dryRun?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Plan helpers
+// ---------------------------------------------------------------------------
+
+/** Returns true when the plan contains at least one action. */
+function hasActions(plan: ReconcilePlan): boolean {
+  return (
+    plan.installs.length > 0 ||
+    plan.uninstalls.length > 0 ||
+    plan.upgrades.length > 0
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Lock-file helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Produce a deterministic content hash from a source string.
+ *
+ * NOTE: This hashes the *source specifier*, not the installed file contents.
+ * A future milestone should replace this with actual content hashing after
+ * extraction.
+ */
+function sourceHashForSource(source: string): string {
+  return (
+    "sha256-" +
+    createHash("sha256").update(source).digest("hex").slice(0, 16)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// reconcile
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare the desired catalog state against currently installed packages
+ * and produce a plan of actions.
+ *
+ * @param catalog  Map of catalog keys to entries (from cat.yaml).
+ * @param installed  Map of installed keys to package info (from scanInstalled).
+ * @param options  Optional flags controlling orphan handling.
+ */
+export function reconcile(
+  catalog: Record<string, CatalogEntry>,
+  installed: InstalledMap,
+  options?: ReconcileOptions,
+): ReconcilePlan {
+  const plan: ReconcilePlan = {
+    installs: [],
+    uninstalls: [],
+    upgrades: [],
+    orphans: [],
+  };
+
+  // Track which installed keys are referenced by at least one catalog entry
+  const matchedInstalledKeys = new Set<string>();
+
+  // --- Process catalog entries ---
+  for (const [catKey, entry] of Object.entries(catalog)) {
+    const isEnabled = entry.enabled !== false;
+    const installedKey = sourceToKey(entry.source);
+    const installedPkg = installed[installedKey];
+
+    if (installedPkg) {
+      matchedInstalledKeys.add(installedKey);
+
+      if (!isEnabled) {
+        // Disabled + installed → uninstall
+        plan.uninstalls.push({
+          type: "uninstall",
+          key: installedKey,
+          source: entry.source,
+        });
+      } else {
+        // Enabled + installed → check for upgrade
+        const sourcesDiffer = installedPkg.source !== entry.source;
+
+        if (sourcesDiffer) {
+          const isNpm = entry.source.startsWith("npm:");
+          const targetVersion = isNpm
+            ? extractNpmVersion(entry.source.slice(4))
+            : undefined;
+          const currentVersion = installedPkg.version;
+
+          // For npm without version pin, don't upgrade (already installed)
+          const isVersionlessNpm = isNpm && targetVersion === undefined;
+
+          if (!isVersionlessNpm) {
+            plan.upgrades.push({
+              type: "upgrade",
+              key: installedKey,
+              source: entry.source,
+              currentVersion,
+              targetVersion,
+            });
+          }
+        }
+        // If sources match → no action needed
+      }
+    } else {
+      // Not installed
+      if (isEnabled) {
+        plan.installs.push({
+          type: "install",
+          key: catKey,
+          source: entry.source,
+        });
+      }
+      // Not installed + disabled → no action
+    }
+  }
+
+  // --- Detect orphans (installed but not in catalog) ---
+  for (const [installedKey, installedPkg] of Object.entries(installed)) {
+    if (!matchedInstalledKeys.has(installedKey)) {
+      plan.orphans.push({
+        key: installedKey,
+        source: installedPkg.source,
+        version: installedPkg.version,
+      });
+
+      if (options?.removeOrphans) {
+        plan.uninstalls.push({
+          type: "uninstall",
+          key: installedKey,
+          source: installedPkg.source,
+        });
+      }
+    }
+  }
+
+  return plan;
+}
+
+// ---------------------------------------------------------------------------
+// executeActions
+// ---------------------------------------------------------------------------
+
+export async function executeActions(
+  plan: ReconcilePlan,
+  options?: ExecuteOptions,
+): Promise<ExecuteResult> {
+  const errors: ActionError[] = [];
+
+  // --- Dry-run: preview mode, skip execution and lock file write ---
+  if (options?.dryRun) {
+    return { success: true, errors };
+  }
+
+  // --- Uninstalls first ---
+  for (const action of plan.uninstalls) {
+    try {
+      await piUninstall(action.key);
+    } catch (err) {
+      errors.push({
+        action,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+    }
+  }
+
+  // --- Installs ---
+  for (const action of plan.installs) {
+    try {
+      await piInstall(action.source);
+    } catch (err) {
+      errors.push({
+        action,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+    }
+  }
+
+  // --- Upgrades (reinstall) ---
+  for (const action of plan.upgrades) {
+    try {
+      await piInstall(action.source);
+    } catch (err) {
+      errors.push({
+        action,
+        error: err instanceof Error ? err : new Error(String(err)),
+      });
+    }
+  }
+
+  const success = errors.length === 0;
+
+  // Write lock file only on full success and when there were actions
+  if (success && hasActions(plan)) {
+    const lfPath = lockFile(options?.home);
+
+    // Read existing lock to preserve entries not touched in this run
+    let existingPackages: LockFile["packages"] = {};
+    try {
+      const raw = fs.readFileSync(lfPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed?.packages && typeof parsed.packages === "object") {
+        existingPackages = parsed.packages;
+      }
+    } catch {
+      // No existing lock or malformed — start fresh
+    }
+
+    const lockPackages = { ...existingPackages };
+    const now = new Date().toISOString();
+
+    // Add/update entries for successful installs
+    for (const action of plan.installs) {
+      lockPackages[action.key] = {
+        version: extractVersionFromSource(action.source),
+        sourceHash: sourceHashForSource(action.source),
+        installedAt: now,
+        syncState: "synced",
+      };
+    }
+
+    // Add/update entries for successful upgrades
+    for (const action of plan.upgrades) {
+      lockPackages[action.key] = {
+        version: extractVersionFromSource(action.source),
+        sourceHash: sourceHashForSource(action.source),
+        installedAt: now,
+        syncState: "synced",
+      };
+    }
+
+    // Remove entries for successful uninstalls
+    for (const action of plan.uninstalls) {
+      delete lockPackages[action.key];
+    }
+
+    const lockContent =
+      JSON.stringify({ packages: lockPackages }, null, 2) + "\n";
+
+    const writer =
+      options?.lockFileWriter ??
+      ((p, c) => fs.writeFileSync(p, c, "utf-8"));
+    writer(lfPath, lockContent);
+  }
+
+  return { success, errors };
+}

package/src/catalog/source.ts

@@ -0,0 +1,173 @@
+/**
+ * Shared source-parsing logic for package source strings.
+ *
+ * Centralises npm-name extraction, git-name cleaning, and source-to-key
+ * derivation so that `install.ts` and `reconcile.ts` don't duplicate the
+ * same logic.
+ */
+
+import path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ParsedSource {
+  /** Identity key for deduplication. */
+  name: string;
+  /** Source type. */
+  type: "npm" | "git" | "local";
+  /** For npm: the package name without the npm: prefix. */
+  npmName?: string;
+  /** For npm with optional version pin: the version after @, or undefined. */
+  npmVersion?: string;
+}
+
+// ---------------------------------------------------------------------------
+// npm helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the npm package name from "pkg@version" or "@scope/pkg@version".
+ */
+export function extractNpmName(spec: string): string {
+  // Scoped package: @scope/pkg@version -> @scope/pkg
+  if (spec.startsWith("@")) {
+    const secondAt = spec.indexOf("@", 1);
+    return secondAt === -1 ? spec : spec.slice(0, secondAt);
+  }
+  // Unscoped: pkg@version -> pkg
+  const atIdx = spec.indexOf("@");
+  return atIdx === -1 ? spec : spec.slice(0, atIdx);
+}
+
+/**
+ * Extract version from an npm spec (the part after the last relevant @).
+ */
+export function extractNpmVersion(spec: string): string | undefined {
+  if (spec.startsWith("@")) {
+    const secondAt = spec.indexOf("@", 1);
+    return secondAt === -1 ? undefined : spec.slice(secondAt + 1);
+  }
+  const atIdx = spec.indexOf("@");
+  return atIdx === -1 ? undefined : spec.slice(atIdx + 1);
+}
+
+// ---------------------------------------------------------------------------
+// git helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Clean a git/URL source into a canonical host/path name.
+ *
+ * Examples:
+ *   "github.com/user/repo@v1"         -> "github.com/user/repo"
+ *   "git@github.com:user/repo"        -> "github.com/user/repo"
+ *   "https://github.com/user/repo@v2" -> "github.com/user/repo"
+ *   "ssh://git@github.com/user/repo"  -> "github.com/user/repo"
+ */
+export function cleanGitName(raw: string): string {
+  let cleaned = raw;
+
+  // Strip protocol prefix
+  cleaned = cleaned.replace(/^(https?:\/\/|ssh:\/\/|git:\/\/)/, "");
+  // Strip user@ prefix (e.g. git@)
+  cleaned = cleaned.replace(/^[^@/]+@/, "");
+  // Convert colon to slash for git@host:path style
+  cleaned = cleaned.replace(/:/g, "/");
+
+  // Strip trailing @ref
+  const atIdx = cleaned.lastIndexOf("@");
+  if (atIdx !== -1) {
+    cleaned = cleaned.slice(0, atIdx);
+  }
+
+  // Strip trailing .git
+  if (cleaned.endsWith(".git")) {
+    cleaned = cleaned.slice(0, -4);
+  }
+
+  return cleaned;
+}
+
+// ---------------------------------------------------------------------------
+// Composite helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a raw source string into a structured form.
+ */
+export function parseSource(raw: string): ParsedSource {
+  // npm:pkg@version or npm:pkg
+  if (raw.startsWith("npm:")) {
+    const rest = raw.slice(4);
+    const npmName = extractNpmName(rest);
+    const npmVersion = extractNpmVersion(rest);
+    return { name: npmName, type: "npm", npmName, npmVersion };
+  }
+
+  // git: shorthand
+  if (raw.startsWith("git:")) {
+    const rest = raw.slice(4);
+    const name = cleanGitName(rest);
+    return { name, type: "git" };
+  }
+
+  // HTTPS / SSH protocol URLs treated as git sources
+  if (
+    raw.startsWith("https://") ||
+    raw.startsWith("http://") ||
+    raw.startsWith("ssh://") ||
+    raw.startsWith("git://")
+  ) {
+    const name = cleanGitName(raw);
+    return { name, type: "git" };
+  }
+
+  // Everything else is a local path — derive name from directory basename
+  const name = path.basename(path.resolve(raw));
+  return { name, type: "local" };
+}
+
+/**
+ * Derive the installed-map key from a source string.
+ *
+ * - npm sources → npm package name (e.g. "@foo/bar")
+ * - git sources → cleaned host/path (e.g. "github.com/user/repo")
+ * - local paths → the raw source string itself
+ */
+export function sourceToKey(source: string): string {
+  if (source.startsWith("npm:")) {
+    return extractNpmName(source.slice(4));
+  }
+  if (source.startsWith("git:")) {
+    return cleanGitName(source.slice(4));
+  }
+  if (
+    source.startsWith("https://") ||
+    source.startsWith("http://") ||
+    source.startsWith("ssh://") ||
+    source.startsWith("git://")
+  ) {
+    return cleanGitName(source);
+  }
+  // Local path — key is the raw source itself (matches scanInstalled behavior)
+  return source;
+}
+
+/**
+ * Extract a version string from a source for lock-file recording.
+ *
+ * Returns `"unknown"` when the source carries no version/ref information.
+ */
+export function extractVersionFromSource(source: string): string {
+  if (source.startsWith("npm:")) {
+    return extractNpmVersion(source.slice(4)) ?? "unknown";
+  }
+  if (source.startsWith("git:")) {
+    const rest = source.slice(4);
+    const atIdx = rest.lastIndexOf("@");
+    return atIdx !== -1 ? rest.slice(atIdx + 1) : "unknown";
+  }
+  return "unknown";
+}

package/src/commands/add.ts

@@ -0,0 +1,135 @@
+/**
+ * `ct add` subcommand implementation.
+ *
+ * Adds a new package to the catalog. Supports:
+ *   - Full args: `ct add <name> <source> [--rating <r>] [--type <t>]`
+ *   - Git source without `--type`: prompts for type via `ctx.ui.select()`
+ *   - After adding, runs `pi install` to install the package
+ *
+ * Uses `addPackage` from `crud.ts` for validation and catalog mutation,
+ * 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 { readCatalog, writeCatalog } from "../config/io.js";
+import { piInstall } from "../util/exec.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Context for `addCommand`, extending the base with `select` for type prompts. */
+export interface AddCtx extends CommandCtx {
+  ui: CommandCtx["ui"] & {
+    select?: <T>(options: {
+      message: string;
+      choices: { value: T; label: string }[];
+    }) => Promise<T>;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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 {
+  const raw =
+    "s" in flags
+      ? flags["s"]
+      : "type" in flags
+        ? flags["type"]
+        : undefined;
+
+  if (raw === true || raw === undefined) return undefined;
+  if (raw === "skill" || raw === "pi-native") return raw;
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// addCommand
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute the `ct add` subcommand.
+ *
+ * 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) {
+    ctx.ui.notify(
+      "Usage: ct add <name> <source> [--rating <core|useful|debatable>] [--type <skill|pi-native>]",
+      "error",
+    );
+    return;
+  }
+
+  const rating = resolveRating(flags);
+  let type = resolveType(flags);
+
+  // --- Read catalog ---------------------------------------------------------
+  const catalog = readCatalog(ctx.home);
+
+  // --- Prompt for type when git source and no explicit type -----------------
+  if (source.startsWith("git:") && type === undefined) {
+    if (ctx.ui.select) {
+      type = await ctx.ui.select<"skill" | "pi-native">({
+        message: `Select type for "${name}"`,
+        choices: [
+          { value: "skill", label: "Skill" },
+          { value: "pi-native", label: "Pi-native" },
+        ],
+      });
+    }
+  }
+
+  // --- Add package ----------------------------------------------------------
+  try {
+    const updated = addPackage(catalog, name, source, rating, type);
+    writeCatalog(updated, ctx.home);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(message, "error");
+    return;
+  }
+
+  ctx.ui.notify(`Added "${name}" to catalog`, "info");
+
+  // --- Run pi install -------------------------------------------------------
+  try {
+    await piInstall(source);
+  } catch {
+    ctx.ui.notify(
+      `Warning: package "${name}" added to catalog but install failed`,
+      "warning",
+    );
+  }
+}