@pi-stef/catalog 0.2.2

package/src/sync/pull.ts

@@ -0,0 +1,76 @@
+import yaml from "js-yaml";
+
+import { CatalogYamlSchema, LockFileSchema } from "../config/schema.js";
+import type { CatalogYaml, LockFile } from "../config/schema.js";
+import { readGist, findGistByDescription } from "./gist.js";
+import { readCachedGistId, writeCachedGistId } from "./cache.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result of a pull operation. */
+export interface PullResult {
+  catalog: CatalogYaml;
+  lock: LockFile;
+}
+
+// ---------------------------------------------------------------------------
+// pullCatalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a catalog and lock file from a GitHub Gist and deserialize them.
+ *
+ * Strategy:
+ *  1. Check for a cached gist ID in `~/.pi/sf/catalog/.gist`.
+ *  2. If no cached ID, search for an existing gist by description.
+ *  3. Fetch the gist and read its files.
+ *  4. Deserialize `cat.yaml` → CatalogYaml and `catalog.lock.json` → LockFile.
+ *  5. Cache the discovered gist ID for future pulls.
+ *
+ * Throws if no gist is found for the given profile.
+ */
+export async function pullCatalog(
+  profile: string,
+  home?: string,
+): Promise<PullResult> {
+  const description = `catalog-${profile}`;
+
+  // 1. Check for cached gist ID
+  let gistId = readCachedGistId(home);
+  let discovered = false;
+
+  // 2. If no cached ID, find existing gist by description
+  if (!gistId) {
+    const existing = await findGistByDescription(description);
+    if (existing) {
+      gistId = existing.id;
+      discovered = true;
+    }
+  }
+
+  if (!gistId) {
+    throw new Error(`No gist found for profile "${profile}" (description: "${description}")`);
+  }
+
+  // 3. Fetch gist files
+  const gist = await readGist(gistId);
+
+  // 4. Deserialize
+  const catYamlContent = gist.files["cat.yaml"]?.content ?? "";
+  const lockJsonContent = gist.files["catalog.lock.json"]?.content ?? "";
+
+  const parsedYaml = yaml.load(catYamlContent);
+  const catalog: CatalogYaml = CatalogYamlSchema.parse(parsedYaml);
+
+  const parsedLock = JSON.parse(lockJsonContent);
+  const lock: LockFile = LockFileSchema.parse(parsedLock);
+
+  // 5. Cache the discovered gist ID for future pulls
+  if (discovered) {
+    writeCachedGistId(gistId, home);
+  }
+
+  return { catalog, lock };
+}

package/src/sync/push.ts

@@ -0,0 +1,78 @@
+import yaml from "js-yaml";
+
+import type { CatalogYaml, LockFile } from "../config/schema.js";
+import {
+  createGist,
+  updateGist,
+  findGistByDescription,
+} from "./gist.js";
+import { readCachedGistId, writeCachedGistId } from "./cache.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result of a push operation. */
+export interface PushResult {
+  gistId: string;
+  gistUrl: string;
+}
+
+// ---------------------------------------------------------------------------
+// pushCatalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a catalog and lock file, then push them to a GitHub Gist.
+ *
+ * Strategy:
+ *  1. Check for a cached gist ID in `~/.pi/sf/catalog/.gist`.
+ *  2. If no cached ID, search for an existing gist by description.
+ *  3. If found, update the gist; otherwise create a new one.
+ *  4. Cache the gist ID for future lookups.
+ *
+ * The gist description format is `catalog-<profile>`.
+ * The gist contains two files: `cat.yaml` and `catalog.lock.json`.
+ */
+export async function pushCatalog(
+  catalog: CatalogYaml,
+  lock: LockFile,
+  profile: string,
+  home?: string,
+): Promise<PushResult> {
+  const description = `catalog-${profile}`;
+
+  const files: Record<string, string> = {
+    "cat.yaml": yaml.dump(catalog),
+    "catalog.lock.json": JSON.stringify(lock, null, 2),
+  };
+
+  // 1. Check for cached gist ID
+  let gistId = readCachedGistId(home);
+
+  // 2. If no cached ID, find existing gist by description
+  if (!gistId) {
+    const existing = await findGistByDescription(description);
+    if (existing) {
+      gistId = existing.id;
+    }
+  }
+
+  let result;
+
+  if (gistId) {
+    // 3a. Update existing gist
+    result = await updateGist(gistId, files);
+  } else {
+    // 3b. Create new gist
+    result = await createGist(files, description);
+  }
+
+  // 4. Cache the gist ID
+  writeCachedGistId(result.id, home);
+
+  return {
+    gistId: result.id,
+    gistUrl: result.url ?? `https://gist.github.com/${result.id}`,
+  };
+}

package/src/update/pi-update.ts

@@ -0,0 +1,60 @@
+/**
+ * Pi update checker for @earendil-works/pi-coding-agent.
+ *
+ * Checks npm registry for the latest version of pi,
+ * compares with the current version, and reports availability.
+ * Does NOT auto-install. Rate-limited to once per hour via lock file cache.
+ */
+import { fetchLatestVersion } from "./registry.js";
+import { readUpdateCache, writeUpdateCache } from "./update-cache.js";
+import { isNewer } from "./semver.js";
+import type { UpdateCheckResult } from "./types.js";
+
+/** Cache key used in the lock file. */
+const CACHE_KEY = "pi-update";
+
+/**
+ * Check whether a newer version of pi is available.
+ *
+ * @param currentVersion - The currently installed version string.
+ * @param home - Optional home directory override (for testing).
+ * @returns Update check result with current, latest, and updateAvailable.
+ */
+export async function checkPiUpdate(
+  currentVersion: string,
+  home?: string,
+): Promise<UpdateCheckResult> {
+  // Check rate-limited cache first
+  const cached = readUpdateCache(CACHE_KEY, home);
+  if (cached) {
+    return {
+      current: currentVersion,
+      latest: cached.latest,
+      updateAvailable: isNewer(cached.latest, currentVersion),
+    };
+  }
+
+  // Fetch latest version from npm registry
+  const latest = await fetchLatestVersion("@earendil-works/pi-coding-agent");
+
+  if (latest === undefined) {
+    // Network error — skip silently
+    return {
+      current: currentVersion,
+      latest: undefined,
+      updateAvailable: false,
+    };
+  }
+
+  // Cache the result
+  writeUpdateCache(CACHE_KEY, {
+    latest,
+    checkedAt: new Date().toISOString(),
+  }, home);
+
+  return {
+    current: currentVersion,
+    latest,
+    updateAvailable: isNewer(latest, currentVersion),
+  };
+}

package/src/update/registry.ts

@@ -0,0 +1,27 @@
+/**
+ * Fetches the latest version of an npm package by running `npm view <pkg> version`.
+ *
+ * Returns the version string (trimmed), or undefined on any error.
+ */
+import { execFile } from "node:child_process";
+
+export async function fetchLatestVersion(
+  packageName: string,
+  timeout = 10_000,
+): Promise<string | undefined> {
+  return new Promise<string | undefined>((resolve) => {
+    execFile(
+      "npm",
+      ["view", packageName, "version"],
+      { timeout },
+      (error, stdout) => {
+        if (error) {
+          resolve(undefined);
+          return;
+        }
+        const version = typeof stdout === "string" ? stdout.trim() : "";
+        resolve(version.length > 0 ? version : undefined);
+      },
+    );
+  });
+}

package/src/update/self-update.ts

@@ -0,0 +1,60 @@
+/**
+ * Self-update checker for @pi-stef/catalog.
+ *
+ * Checks npm registry for the latest version of @pi-stef/catalog,
+ * compares with the current version, and reports availability.
+ * Does NOT auto-install. Rate-limited to once per hour via lock file cache.
+ */
+import { fetchLatestVersion } from "./registry.js";
+import { readUpdateCache, writeUpdateCache } from "./update-cache.js";
+import { isNewer } from "./semver.js";
+import type { UpdateCheckResult } from "./types.js";
+
+/** Cache key used in the lock file. */
+const CACHE_KEY = "self-update";
+
+/**
+ * Check whether a newer version of @pi-stef/catalog is available.
+ *
+ * @param currentVersion - The currently installed version string.
+ * @param home - Optional home directory override (for testing).
+ * @returns Update check result with current, latest, and updateAvailable.
+ */
+export async function checkSelfUpdate(
+  currentVersion: string,
+  home?: string,
+): Promise<UpdateCheckResult> {
+  // Check rate-limited cache first
+  const cached = readUpdateCache(CACHE_KEY, home);
+  if (cached) {
+    return {
+      current: currentVersion,
+      latest: cached.latest,
+      updateAvailable: isNewer(cached.latest, currentVersion),
+    };
+  }
+
+  // Fetch latest version from npm registry
+  const latest = await fetchLatestVersion("@pi-stef/catalog");
+
+  if (latest === undefined) {
+    // Network error — skip silently
+    return {
+      current: currentVersion,
+      latest: undefined,
+      updateAvailable: false,
+    };
+  }
+
+  // Cache the result
+  writeUpdateCache(CACHE_KEY, {
+    latest,
+    checkedAt: new Date().toISOString(),
+  }, home);
+
+  return {
+    current: currentVersion,
+    latest,
+    updateAvailable: isNewer(latest, currentVersion),
+  };
+}

package/src/update/semver.ts

@@ -0,0 +1,38 @@
+/**
+ * Simple semver comparison utilities.
+ *
+ * Compares version strings of the form "major.minor.patch" (with optional
+ * pre-release tags). Returns -1 if a < b, 0 if equal, 1 if a > b.
+ *
+ * **Note:** Pre-release tags (e.g. `-beta`, `-rc.1`) are stripped before
+ * comparison, so `1.0.0-beta` compares equal to `1.0.0`. This is safe for
+ * the npm `latest` dist-tag, which never returns pre-release versions, but
+ * could misreport if a pre-release is ever returned.
+ */
+
+/**
+ * Compare two semver-like version strings.
+ * Pre-release tags are stripped (e.g. "1.0.0-beta" → "1.0.0").
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ */
+export function compareVersions(a: string, b: string): number {
+  const partsA = a.replace(/-.*/, "").split(".").map(Number);
+  const partsB = b.replace(/-.*/, "").split(".").map(Number);
+
+  for (let i = 0; i < 3; i++) {
+    const valA = partsA[i] ?? 0;
+    const valB = partsB[i] ?? 0;
+    if (valA < valB) return -1;
+    if (valA > valB) return 1;
+  }
+
+  // Versions are equal (ignoring pre-release)
+  return 0;
+}
+
+/**
+ * Returns true if `latest` is strictly greater than `current`.
+ */
+export function isNewer(latest: string, current: string): boolean {
+  return compareVersions(latest, current) > 0;
+}

package/src/update/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared types for update checking.
+ */
+
+/** Result of an update check. */
+export interface UpdateCheckResult {
+  /** The currently installed version. */
+  current: string;
+  /** The latest version available on the registry (undefined on network error). */
+  latest: string | undefined;
+  /** Whether an update is available. */
+  updateAvailable: boolean;
+}
+
+/** Cache entry stored in the lock file under _updateCache. */
+export interface UpdateCacheEntry {
+  /** The latest version found at check time. */
+  latest: string;
+  /** ISO-8601 timestamp of when the check was performed. */
+  checkedAt: string;
+}

package/src/update/update-cache.ts

@@ -0,0 +1,54 @@
+/**
+ * Rate-limited update check cache stored in the lock file.
+ *
+ * The cache lives under the `_updateCache` key in catalog.lock.json.
+ * Each checker has its own cache entry keyed by a cache key (e.g. "self-update").
+ *
+ * Rate limit: check no more than once per hour.
+ */
+import { readLock, writeLock } from "../config/io.js";
+import type { UpdateCacheEntry } from "./types.js";
+
+/** 1 hour in milliseconds. */
+const RATE_LIMIT_MS = 60 * 60 * 1000;
+
+/** The key used in the lock file for the update cache. */
+const CACHE_KEY = "_updateCache";
+
+/**
+ * Read a cached update check result.
+ *
+ * Returns the cached entry if it exists and is less than 1 hour old,
+ * or undefined if no valid cache exists.
+ */
+export function readUpdateCache(
+  cacheKey: string,
+  home?: string,
+): UpdateCacheEntry | undefined {
+  const lock = readLock(home) as Record<string, unknown>;
+  const cache = lock[CACHE_KEY] as Record<string, UpdateCacheEntry> | undefined;
+  if (!cache) return undefined;
+
+  const entry = cache[cacheKey];
+  if (!entry) return undefined;
+
+  const age = Date.now() - new Date(entry.checkedAt).getTime();
+  if (age >= RATE_LIMIT_MS) return undefined;
+
+  return entry;
+}
+
+/**
+ * Write a cached update check result to the lock file.
+ */
+export function writeUpdateCache(
+  cacheKey: string,
+  entry: UpdateCacheEntry,
+  home?: string,
+): void {
+  const lock = readLock(home) as Record<string, unknown>;
+  const cache = (lock[CACHE_KEY] ?? {}) as Record<string, UpdateCacheEntry>;
+  cache[cacheKey] = entry;
+  (lock as Record<string, unknown>)[CACHE_KEY] = cache;
+  writeLock(lock as import("../config/schema.js").LockFile, home);
+}

package/src/util/errors.ts

@@ -0,0 +1,144 @@
+/**
+ * User-facing error formatting utilities for the catalog extension.
+ *
+ * Translates raw system/network errors into actionable messages that
+ * guide the user toward a fix (e.g., suggest `ct init --force` for
+ * corrupt YAML, or `ct login` for missing gist credentials).
+ */
+
+// ---------------------------------------------------------------------------
+// Predicate helpers
+// ---------------------------------------------------------------------------
+
+/** Returns true when the error looks like a YAML parse failure. */
+export function isCorruptYamlError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  const lower = msg.toLowerCase();
+  return (
+    msg.includes("YAMLException") ||
+    msg.includes("YAML") && msg.includes("line") ||
+    lower.includes("unexpected") && lower.includes("stream") ||
+    lower.includes("could not") && lower.includes("yaml") ||
+    msg.includes("ZodError") ||
+    msg.includes("Expected") && msg.includes("received")
+  );
+}
+
+/** Returns true when the error indicates a missing gist / no remote. */
+export function isMissingGistError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  return (
+    msg.includes("No gist found") ||
+    msg.includes("gist not found") ||
+    msg.includes("gist was not found")
+  );
+}
+
+/** Returns true when the error is network-related. */
+export function isNetworkError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message.toLowerCase();
+  return (
+    msg.includes("econnrefused") ||
+    msg.includes("etimedout") ||
+    msg.includes("enotfound") ||
+    msg.includes("econnreset") ||
+    msg.includes("timed out") ||
+    msg.includes("network") ||
+    msg.includes("socket hang up") ||
+    msg.includes("fetch failed")
+  );
+}
+
+/** Returns true when the error is a filesystem permission error. */
+export function isPermissionError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  return msg.includes("EACCES") || msg.includes("EPERM");
+}
+
+// ---------------------------------------------------------------------------
+// Auth error detection
+// ---------------------------------------------------------------------------
+
+function isAuthError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  return (
+    msg.includes("401") ||
+    msg.includes("Unauthorized") ||
+    msg.includes("403") ||
+    msg.includes("Forbidden")
+  );
+}
+
+// ---------------------------------------------------------------------------
+// File not found detection
+// ---------------------------------------------------------------------------
+
+function isFileNotFoundError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const msg = err.message ?? "";
+  return msg.includes("ENOENT");
+}
+
+// ---------------------------------------------------------------------------
+// formatUserError
+// ---------------------------------------------------------------------------
+
+/**
+ * Translate a raw error into a user-friendly message with actionable advice.
+ *
+ * Returns a string suitable for displaying via `ctx.ui.notify(msg, "error")`.
+ */
+export function formatUserError(err: unknown): string {
+  // Handle null/undefined
+  if (err == null) {
+    return "An unknown error occurred. Please try again or run `ct init` to start fresh.";
+  }
+
+  // Handle non-Error values
+  if (!(err instanceof Error)) {
+    return `Error: ${String(err)}`;
+  }
+
+  const msg = err.message ?? "";
+
+  // Corrupt / invalid YAML
+  if (isCorruptYamlError(err)) {
+    return `${msg}\nYour cat.yaml appears to be corrupt or has an invalid format. Run \`ct init --force\` to regenerate it from your installed packages.`;
+  }
+
+  // Auth errors
+  if (isAuthError(err)) {
+    return `${msg}\nAuthentication failed. Run \`ct login\` to set up your GitHub credentials.`;
+  }
+
+  // Missing gist
+  if (isMissingGistError(err)) {
+    return `${msg}\nNo remote catalog found. Run \`ct login\` to link your GitHub account, then use \`ct sync\` to create a remote gist.`;
+  }
+
+  // Permission errors
+  if (isPermissionError(err)) {
+    return `${msg}\nPermission denied writing to the catalog directory. Check the permissions on \`~/.pi/sf/catalog/\` and try again.`;
+  }
+
+  // Network errors
+  if (isNetworkError(err)) {
+    if (msg.toLowerCase().includes("timed out")) {
+      return `${msg}\nNetwork request timed out. Check your internet connection and retry.`;
+    }
+    return `${msg}\nA network error occurred. Check your internet connection and retry.`;
+  }
+
+  // File not found
+  if (isFileNotFoundError(err)) {
+    return `${msg}\nA required file was not found. Run \`ct init\` to create a new catalog.`;
+  }
+
+  // Generic fallback — always show the message, never a raw stack trace
+  return msg;
+}