@pi-stef/catalog 0.2.2

package/src/register.ts

@@ -0,0 +1,285 @@
+/**
+ * Extension registration for the catalog extension.
+ *
+ * Wires all catalog subcommands into pi's extension API as `/ct` commands
+ * and `ct_*` tools for LLM invocation.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+import {
+  SUBCOMMAND_DEFS,
+  getAliasMap,
+} from "./commands/definitions.js";
+import { parseSubcommand } from "./commands/dispatch.js";
+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 {
+  toggleCommand,
+  enableCommand,
+  disableCommand,
+  type ToggleCtx,
+} from "./commands/toggle.js";
+import {
+  syncCommand,
+  pushCommand,
+  pullCommand,
+  type SyncCtx,
+  type PushPullCtx,
+} from "./commands/sync.js";
+import { loginCommand, type LoginCtx } from "./commands/login.js";
+import { statusCommand, type StatusCtx } from "./commands/status.js";
+import { diffCommand, type DiffCtx } from "./commands/diff.js";
+import { verifyCommand, type VerifyCtx } from "./commands/verify.js";
+import {
+  profilesCommand,
+  profileCommand,
+  type ProfilesCtx,
+} from "./commands/profiles.js";
+import type { CommandArgs, CommandCtx } from "./commands/types.js";
+
+// ---------------------------------------------------------------------------
+// Alias map (derived from shared definitions)
+// ---------------------------------------------------------------------------
+
+const aliasMap = getAliasMap();
+
+// ---------------------------------------------------------------------------
+// Command handlers (delegate to implementation modules)
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle a parsed subcommand invocation.
+ *
+ * Delegates to the appropriate command implementation module.
+ */
+async function handleSubcommand(
+  subcommand: string,
+  args: string,
+  ctx: CommandCtx,
+): Promise<void> {
+  const canonical = aliasMap.get(subcommand);
+  if (!canonical) {
+    ctx.ui.notify(`Unknown subcommand: ${subcommand}`, "error");
+    return;
+  }
+
+  // Parse the raw argument string into structured { positional, flags }
+  const rawParts = (args ?? "").trim().split(/\s+/).filter(Boolean);
+  const parsed = parseSubcommand(rawParts);
+
+  switch (canonical) {
+    case "add":
+      await addCommand(parsed, ctx as AddCtx);
+      break;
+    case "init":
+      await initCommand(parsed, ctx as InitContext);
+      break;
+    case "remove":
+      await removeCommand(parsed, ctx as RemoveCtx);
+      break;
+    case "sync":
+      await syncCommand(parsed, ctx as SyncCtx);
+      break;
+    case "push":
+      await pushCommand(parsed, ctx as PushPullCtx);
+      break;
+    case "pull":
+      await pullCommand(parsed, ctx as PushPullCtx);
+      break;
+    case "toggle":
+      await toggleCommand(parsed, ctx as ToggleCtx);
+      break;
+    case "enable":
+      await enableCommand(parsed, ctx as ToggleCtx);
+      break;
+    case "disable":
+      await disableCommand(parsed, ctx as ToggleCtx);
+      break;
+    case "login":
+      await loginCommand(parsed, ctx as LoginCtx);
+      break;
+    case "status":
+      await statusCommand(parsed, ctx as StatusCtx);
+      break;
+    case "diff":
+      await diffCommand(parsed, ctx as DiffCtx);
+      break;
+    case "verify":
+      await verifyCommand(parsed, ctx as VerifyCtx);
+      break;
+    case "profiles":
+      await profilesCommand(parsed, ctx as ProfilesCtx);
+      break;
+    case "profile":
+      await profileCommand(parsed, ctx as ProfilesCtx);
+      break;
+    default:
+      ctx.ui.notify(`ct ${canonical}: not yet implemented`, "info");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Register all catalog commands and tools with the pi extension API.
+ *
+ * - `/ct` main command with subcommand routing and argument auto-completion
+ * - `/ct-sync`, `/ct-init`, … individual alias commands
+ * - `ct_sync`, `ct_add`, `ct_remove`, `ct_toggle`, `ct_status` LLM tools
+ */
+export function registerCatalog(pi: ExtensionAPI): void {
+  // ----- /ct main command --------------------------------------------------
+  pi.registerCommand("ct", {
+    description: "Catalog management: sync, add, remove, toggle, and more",
+    getArgumentCompletions(prefix: string) {
+      const items = SUBCOMMAND_DEFS.map((s) => ({
+        value: s.name,
+        label: s.name,
+        description: s.description,
+      }));
+      const filtered = items.filter((i) => i.value.startsWith(prefix));
+      return filtered.length > 0 ? filtered : null;
+    },
+    async handler(args, ctx) {
+      const parts = (args ?? "").trim().split(/\s+/);
+      const sub = parts[0] || "";
+      const rest = parts.slice(1).join(" ");
+      await handleSubcommand(sub, rest, ctx);
+    },
+  });
+
+  // ----- Individual alias commands (e.g. /ct-sync, /ct-init) ---------------
+  for (const sub of SUBCOMMAND_DEFS) {
+    pi.registerCommand(`ct-${sub.name}`, {
+      description: sub.description,
+      async handler(args, ctx) {
+        await handleSubcommand(sub.name, args ?? "", ctx);
+      },
+    });
+  }
+
+  // ----- LLM tools ---------------------------------------------------------
+
+  pi.registerTool({
+    name: "ct_sync",
+    label: "Catalog Sync",
+    description:
+      "Synchronize the catalog with the remote gist. Pushes local changes and pulls remote changes, resolving conflicts.",
+    promptSnippet: "Sync catalog with remote",
+    promptGuidelines: [
+      "Use ct_sync when the user asks to sync their catalog or when catalog state may be stale.",
+    ],
+    parameters: Type.Object({
+      force: Type.Optional(Type.Boolean({ description: "Force sync even if no changes detected" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const args: CommandArgs = { positional: [], flags: params.force ? { force: true } : {} };
+        await syncCommand(args, ctx as unknown as SyncCtx);
+        return { content: [{ type: "text" as const, text: "Sync completed." }], details: undefined as unknown };
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Sync failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "ct_add",
+    label: "Catalog Add",
+    description:
+      "Add a package to the catalog by name and 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)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const args: CommandArgs = {
+          positional: [params.name, params.source],
+          flags: params.rating ? { rating: params.rating } : {},
+        };
+        await addCommand(args, ctx as unknown as AddCtx);
+        return { content: [{ type: "text" as const, text: `Added ${params.name}.` }], 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 };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "ct_remove",
+    label: "Catalog Remove",
+    description: "Remove a package from the catalog by name.",
+    promptSnippet: "Remove a package from the catalog",
+    promptGuidelines: [
+      "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" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const args: CommandArgs = { positional: [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 };
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Remove failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
+      }
+    },
+  });
+
+  pi.registerTool({
+    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",
+    promptGuidelines: [
+      "Use ct_toggle when the user wants to cycle a package's rating.",
+    ],
+    parameters: Type.Object({
+      name: Type.String({ description: "Package name to toggle" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const args: CommandArgs = { positional: [params.name], flags: {} };
+        await toggleCommand(args, ctx as unknown as ToggleCtx);
+        return { content: [{ type: "text" as const, text: `Toggled ${params.name}.` }], details: undefined as unknown };
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Toggle failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "ct_status",
+    label: "Catalog Status",
+    description: "Show the current catalog status including package counts and sync state.",
+    promptSnippet: "Show catalog status",
+    promptGuidelines: [
+      "Use ct_status when the user wants to check catalog health, package counts, or sync state.",
+    ],
+    parameters: Type.Object({
+      verbose: Type.Optional(Type.Boolean({ description: "Show detailed status" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const args: CommandArgs = { positional: [], flags: params.verbose ? { verbose: true } : {} };
+        await statusCommand(args, ctx as unknown as StatusCtx);
+        return { content: [{ type: "text" as const, text: "Status displayed." }], details: undefined as unknown };
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Status failed: ${err instanceof Error ? err.message : String(err)}` }], details: undefined as unknown };
+      }
+    },
+  });
+}

package/src/sync/auth.ts

@@ -0,0 +1,109 @@
+import { execFile } from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of running a child-process command.
+ * Minimal version used internally by this module.
+ */
+interface ShellResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a command via `execFile` and resolve with a ShellResult regardless of
+ * exit code. Rejects only on truly unexpected errors (e.g. bad arguments).
+ */
+function runQuiet(
+  command: string,
+  args: string[],
+  timeout = 5_000,
+): Promise<ShellResult> {
+  return new Promise<ShellResult>((resolve) => {
+    execFile(
+      command,
+      args,
+      { timeout, maxBuffer: 1024 * 1024 },
+      (error, stdout, stderr) => {
+        const out = typeof stdout === "string" ? stdout : String(stdout ?? "");
+        const err = typeof stderr === "string" ? stderr : String(stderr ?? "");
+
+        if (error) {
+          const exitCode =
+            typeof (error as Error & { status?: number }).status === "number"
+              ? (error as Error & { status?: number }).status!
+              : 1;
+          resolve({ stdout: out, stderr: err, exitCode });
+        } else {
+          resolve({ stdout: out, stderr: err, exitCode: 0 });
+        }
+      },
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the GitHub CLI (`gh`) is installed on the system.
+ *
+ * Returns `true` when `gh --version` exits with code 0, `false` otherwise.
+ */
+export async function isGhInstalled(): Promise<boolean> {
+  try {
+    const result = await runQuiet("gh", ["--version"]);
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check whether the GitHub CLI (`gh`) is installed and the user is
+ * authenticated.
+ *
+ * Returns `true` when `gh auth status` exits with code 0, `false` otherwise
+ * (including when `gh` is not installed at all).
+ */
+export async function checkAuth(): Promise<boolean> {
+  const result = await runQuiet("gh", ["auth", "status"]);
+  return result.exitCode === 0;
+}
+
+/**
+ * Obtain a GitHub personal-access token.
+ *
+ * Strategy:
+ *  1. Try `gh auth token` — if it succeeds, return the trimmed token.
+ *  2. Fall back to the `GITHUB_TOKEN` environment variable.
+ *  3. Return `undefined` when neither source yields a token.
+ */
+export async function getToken(): Promise<string | undefined> {
+  // 1. Try gh CLI
+  const result = await runQuiet("gh", ["auth", "token"]);
+  if (result.exitCode === 0) {
+    const token = result.stdout.trim();
+    if (token.length > 0) {
+      return token;
+    }
+  }
+
+  // 2. Fall back to environment variable
+  const envToken = process.env.GITHUB_TOKEN;
+  if (envToken && envToken.length > 0) {
+    return envToken;
+  }
+
+  // 3. Nothing available
+  return undefined;
+}

package/src/sync/cache.ts

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { catalogDir } from "../config/paths.js";
+
+// ---------------------------------------------------------------------------
+// Gist ID cache
+// ---------------------------------------------------------------------------
+
+/**
+ * Path to the `.gist` file that caches the gist ID for a profile.
+ * Located inside `~/.pi/sf/catalog/.gist`.
+ */
+export function gistCachePath(home?: string): string {
+  return path.join(catalogDir(home), ".gist");
+}
+
+/** Read the cached gist ID, or `undefined` if not cached. */
+export function readCachedGistId(home?: string): string | undefined {
+  const cacheFile = gistCachePath(home);
+  try {
+    if (fs.existsSync(cacheFile)) {
+      const id = fs.readFileSync(cacheFile, "utf-8").trim();
+      return id.length > 0 ? id : undefined;
+    }
+  } catch {
+    // ignore read errors
+  }
+  return undefined;
+}
+
+/** Persist the gist ID to the cache file. */
+export function writeCachedGistId(gistId: string, home?: string): void {
+  const cacheFile = gistCachePath(home);
+  const dir = path.dirname(cacheFile);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(cacheFile, gistId, "utf-8");
+}

package/src/sync/gist.ts

@@ -0,0 +1,253 @@
+import { execFile } from "node:child_process";
+import { Octokit } from "@octokit/rest";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Map of filename → file content for gist operations. */
+export interface GistFiles {
+  [filename: string]: string;
+}
+
+/** Result of a gist create or update operation. */
+export interface GistResult {
+  id: string;
+  url?: string;
+}
+
+/** Minimal shape of a gist returned from list/find operations. */
+export interface GistSummary {
+  id: string;
+  description?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a command via `execFile` and return a promise.
+ */
+function exec(
+  command: string,
+  args: string[],
+  options?: { stdin?: string },
+): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      command,
+      args,
+      { maxBuffer: 1024 * 1024 },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve({
+          stdout: typeof stdout === "string" ? stdout : String(stdout ?? ""),
+          stderr: typeof stderr === "string" ? stderr : String(stderr ?? ""),
+        });
+      },
+    );
+    if (options?.stdin !== undefined && child.stdin) {
+      child.stdin.write(options.stdin);
+      child.stdin.end();
+    }
+  });
+}
+
+/**
+ * Lazy-initialized Octokit instance (only created when needed as fallback).
+ */
+let _octokit: InstanceType<typeof Octokit> | null = null;
+function getOctokit(): InstanceType<typeof Octokit> {
+  if (!_octokit) {
+    _octokit = new Octokit();
+  }
+  return _octokit;
+}
+
+/** Reset the cached Octokit (used by tests to ensure fresh mocks). */
+export function _resetOctokit(): void {
+  _octokit = null;
+}
+
+/**
+ * Build the JSON body for the GitHub Gists API from a GistFiles map.
+ */
+function gistApiBody(files: GistFiles): Record<string, { content: string }> {
+  const result: Record<string, { content: string }> = {};
+  for (const [name, content] of Object.entries(files)) {
+    result[name] = { content };
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// createGist
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new GitHub Gist with the given files and description.
+ *
+ * Tries `gh api` first; falls back to the Octokit REST API if the
+ * `gh` CLI is unavailable.
+ */
+export async function createGist(
+  files: GistFiles,
+  description: string,
+): Promise<GistResult> {
+  // --- Try gh CLI first ---
+  try {
+    const body = JSON.stringify({
+      description,
+      public: false,
+      files: gistApiBody(files),
+    });
+
+    const { stdout } = await exec("gh", [
+      "api",
+      "--method", "POST",
+      "/gists",
+      "--input", "-",
+    ], { stdin: body });
+
+    const data = JSON.parse(stdout);
+    return { id: data.id, url: data.html_url };
+  } catch (ghError) {
+    // gh was found but the API call failed, or gh was not found (ENOENT).
+    // Fall through to octokit in either case.
+
+    // --- Fallback: Octokit REST API ---
+    const octokit = getOctokit();
+    const response = await octokit.gists.create({
+      description,
+      public: false,
+      files: gistApiBody(files),
+    });
+
+    return {
+      id: response.data.id!,
+      url: response.data.html_url ?? undefined,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// readGist
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a GitHub Gist by ID and return its files.
+ *
+ * Tries `gh gist view --json` first; falls back to Octokit.
+ */
+export async function readGist(gistId: string): Promise<{
+  id: string;
+  files: Record<string, { content: string }>;
+}> {
+  // --- Try gh CLI first ---
+  try {
+    const { stdout } = await exec("gh", [
+      "gist", "view", gistId, "--json", "id,files",
+    ]);
+
+    const data = JSON.parse(stdout);
+    return {
+      id: data.id,
+      files: data.files,
+    };
+  } catch {
+    // --- Fallback: Octokit REST API ---
+    const octokit = getOctokit();
+    const response = await octokit.gists.get({ gist_id: gistId });
+
+    const files: Record<string, { content: string }> = {};
+    for (const [name, file] of Object.entries(response.data.files ?? {})) {
+      files[name] = { content: (file as { content?: string }).content ?? "" };
+    }
+
+    return { id: response.data.id!, files };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// updateGist
+// ---------------------------------------------------------------------------
+
+/**
+ * Update an existing GitHub Gist with new file contents.
+ *
+ * Tries `gh api` first; falls back to Octokit.
+ */
+export async function updateGist(
+  gistId: string,
+  files: GistFiles,
+): Promise<GistResult> {
+  // --- Try gh CLI first ---
+  try {
+    const body = JSON.stringify({
+      files: gistApiBody(files),
+    });
+
+    const { stdout } = await exec("gh", [
+      "api",
+      "--method", "PATCH",
+      `/gists/${gistId}`,
+      "--input", "-",
+    ], { stdin: body });
+
+    const data = JSON.parse(stdout);
+    return { id: data.id, url: data.html_url };
+  } catch {
+    // --- Fallback: Octokit REST API ---
+    const octokit = getOctokit();
+    const response = await octokit.gists.update({
+      gist_id: gistId,
+      files: gistApiBody(files),
+    });
+
+    return {
+      id: response.data.id!,
+      url: response.data.html_url ?? undefined,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// findGistByDescription
+// ---------------------------------------------------------------------------
+
+/**
+ * Find an existing Gist by its description field.
+ *
+ * Tries `gh gist list --json` first; falls back to Octokit.
+ * Returns `undefined` if no matching gist is found.
+ */
+export async function findGistByDescription(
+  description: string,
+): Promise<GistSummary | undefined> {
+  // --- Try gh CLI first ---
+  try {
+    const { stdout } = await exec("gh", [
+      "gist", "list", "--json", "id,description",
+    ]);
+
+    const gists: Array<{ id: string; description?: string }> = JSON.parse(stdout);
+    return gists.find((g) => g.description === description);
+  } catch {
+    // --- Fallback: Octokit REST API ---
+    try {
+      const octokit = getOctokit();
+      const response = await octokit.gists.list();
+
+      const raw = response.data as Array<{ id: string; description: string | null | undefined }>;
+      const found = raw.find((g) => g.description === description);
+      if (!found) return undefined;
+      return { id: found.id, description: found.description ?? undefined };
+    } catch {
+      return undefined;
+    }
+  }
+}