@pi-stef/catalog 0.2.2

package/src/commands/definitions.ts

@@ -0,0 +1,78 @@
+/**
+ * Single source of truth for catalog subcommand definitions.
+ *
+ * Both `dispatch.ts` (parse-time resolution) and `register.ts` (registration)
+ * import from this module, eliminating duplicate subcommand/alias definitions.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SubcommandDef {
+  name: string;
+  aliases?: string[];
+  description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Canonical subcommand definitions
+// ---------------------------------------------------------------------------
+
+/**
+ * Ordered list of all catalog subcommands with their aliases and descriptions.
+ *
+ * Adding a new subcommand requires updating ONLY this array; `dispatch.ts`
+ * and `register.ts` derive everything they need from it.
+ */
+export const SUBCOMMAND_DEFS: readonly SubcommandDef[] = [
+  { name: "sync", description: "Sync catalog with remote gist" },
+  { name: "init", description: "Initialize a new catalog" },
+  { 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: "disable", description: "Disable a package" },
+  { name: "enable", description: "Enable a package" },
+  { name: "push", description: "Push catalog to remote gist" },
+  { name: "pull", description: "Pull catalog from remote gist" },
+  { name: "login", description: "Authenticate with GitHub for sync" },
+  { name: "status", description: "Show catalog status" },
+  { name: "diff", description: "Show diff between local and remote catalog" },
+  { name: "verify", description: "Verify catalog integrity" },
+  { name: "profiles", description: "List available profiles" },
+  { name: "profile", description: "Show or switch active profile" },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Derived helpers
+// ---------------------------------------------------------------------------
+
+/** Ordered list of canonical subcommand names. */
+export function getSubcommandNames(): readonly string[] {
+  return SUBCOMMAND_DEFS.map((d) => d.name);
+}
+
+/** Resolve a token to its canonical subcommand name, or `undefined`. */
+export function resolveCanonical(token: string): string | undefined {
+  for (const def of SUBCOMMAND_DEFS) {
+    if (def.name === token) return def.name;
+    if (def.aliases?.includes(token)) return def.name;
+  }
+  return undefined;
+}
+
+/**
+ * Build a lookup `Map` from subcommand name or alias → canonical name.
+ *
+ * Useful for registration-time alias mapping.
+ */
+export function getAliasMap(): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const def of SUBCOMMAND_DEFS) {
+    map.set(def.name, def.name);
+    for (const alias of def.aliases ?? []) {
+      map.set(alias, def.name);
+    }
+  }
+  return map;
+}

package/src/commands/diff.ts

@@ -0,0 +1,158 @@
+/**
+ * `ct diff` subcommand implementation.
+ *
+ * Shows local vs remote gist differences by pulling the remote gist
+ * content and comparing it line-by-line with the local cat.yaml.
+ */
+
+import yaml from "js-yaml";
+
+import type { CommandArgs, CommandCtx } from "./types.js";
+import { readCatalog } from "../config/io.js";
+import { readCachedGistId } from "../sync/cache.js";
+import { readGist } from "../sync/gist.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Context for `diffCommand`. Uses the base `CommandCtx`. */
+export type DiffCtx = CommandCtx;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface DiffLine {
+  type: "added" | "removed" | "unchanged";
+  content: string;
+}
+
+/**
+ * Compute a simple line-by-line diff between two strings.
+ * Returns lines marked as added (in remote only), removed (in local only),
+ * or unchanged.
+ */
+function lineDiff(local: string, remote: string): DiffLine[] {
+  const localLines = local.split("\n");
+  const remoteLines = remote.split("\n");
+
+  const localSet = new Map<string, number>();
+  for (const line of localLines) {
+    localSet.set(line, (localSet.get(line) ?? 0) + 1);
+  }
+
+  const remoteSet = new Map<string, number>();
+  for (const line of remoteLines) {
+    remoteSet.set(line, (remoteSet.get(line) ?? 0) + 1);
+  }
+
+  // Build a merged set of unique lines preserving order
+  const seen = new Set<string>();
+  const allLines: string[] = [];
+  for (const line of localLines) {
+    if (!seen.has(line)) {
+      seen.add(line);
+      allLines.push(line);
+    }
+  }
+  for (const line of remoteLines) {
+    if (!seen.has(line)) {
+      seen.add(line);
+      allLines.push(line);
+    }
+  }
+
+  const result: DiffLine[] = [];
+  for (const line of allLines) {
+    const localCount = localSet.get(line) ?? 0;
+    const remoteCount = remoteSet.get(line) ?? 0;
+
+    if (line === "") {
+      // Skip trailing empty lines in diff output
+      continue;
+    }
+
+    if (localCount > 0 && remoteCount > 0) {
+      result.push({ type: "unchanged", content: line });
+    } else if (localCount > 0) {
+      result.push({ type: "removed", content: line });
+    } else {
+      result.push({ type: "added", content: line });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// diffCommand
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute the `ct diff` subcommand.
+ *
+ * Fetches the remote gist content and compares it against the local
+ * cat.yaml serialization. Shows added/removed lines.
+ */
+export async function diffCommand(
+  _args: CommandArgs,
+  ctx: DiffCtx,
+): Promise<void> {
+  // --- 1. Check for cached gist ID ---
+  const gistId = readCachedGistId(ctx.home);
+  if (!gistId) {
+    ctx.ui.notify(
+      `No remote gist configured. Use \`ct sync\` or \`ct push\` first.`,
+      "error",
+    );
+    return;
+  }
+
+  // --- 2. Read local catalog as serialized YAML ---
+  const catalog = readCatalog(ctx.home);
+  const localYaml = yaml.dump(catalog);
+
+  // --- 3. Fetch remote gist ---
+  let remoteYaml: string;
+  try {
+    const gist = await readGist(gistId);
+    const catFile = gist.files["cat.yaml"];
+    remoteYaml = catFile?.content ?? "";
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to read remote gist: ${message}`, "error");
+    return;
+  }
+
+  // --- 4. Compute diff ---
+  if (localYaml === remoteYaml) {
+    ctx.ui.notify("Local and remote are identical.", "info");
+    return;
+  }
+
+  // If remote is empty, all local lines are additions from remote's perspective
+  if (!remoteYaml.trim()) {
+    ctx.ui.notify("Remote is empty. Local has content to push.", "info");
+    return;
+  }
+
+  const diff = lineDiff(localYaml, remoteYaml);
+
+  const parts: string[] = ["Local vs Remote diff:"];
+  const changed = diff.filter(
+    (d) => d.type === "added" || d.type === "removed",
+  );
+
+  if (changed.length === 0) {
+    ctx.ui.notify("Local and remote are identical.", "info");
+    return;
+  }
+
+  for (const line of changed) {
+    const prefix = line.type === "added" ? "+ " : "- ";
+    parts.push(`${prefix}${line.content}`);
+  }
+
+  ctx.ui.notify(parts.join("\n"), "info");
+}

package/src/commands/dispatch.ts

@@ -0,0 +1,102 @@
+/**
+ * Command dispatcher and argument parsing for the `/ct` extension commands.
+ *
+ * `parseSubcommand` splits a raw argument list (e.g. `["sync", "--force"]`)
+ * into a structured `{ subcommand, flags, positional }` object.
+ *
+ * Subcommand names and aliases are derived from the shared definitions in
+ * `definitions.ts` — the single source of truth.
+ */
+
+import {
+  getSubcommandNames,
+  resolveCanonical,
+} from "./definitions.js";
+
+// ---------------------------------------------------------------------------
+// Re-export derived constants for backward compatibility
+// ---------------------------------------------------------------------------
+
+/** Canonical subcommand names accepted by the `/ct` command. */
+export const SUBCOMMANDS = getSubcommandNames() as readonly string[];
+
+/** Canonical subcommand name type derived from the definitions. */
+export type SubcommandName = (typeof SUBCOMMANDS)[number];
+
+// ---------------------------------------------------------------------------
+// resolveAlias (delegates to shared definitions)
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a token to its canonical subcommand name.
+ *
+ * Delegates to `resolveCanonical` from the shared definitions module.
+ */
+export function resolveAlias(token: string): SubcommandName | undefined {
+  return resolveCanonical(token) as SubcommandName | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ParsedCommand {
+  /** Canonical subcommand name, or `undefined` when the first token is not
+   *  a recognized subcommand or alias. */
+  subcommand: SubcommandName | undefined;
+  /** Parsed flags. Boolean flags are `true`; key=value flags hold the string
+   *  value (no type coercion beyond that). */
+  flags: Record<string, true | string>;
+  /** Positional (non-flag) arguments, in order of appearance. */
+  positional: string[];
+}
+
+// ---------------------------------------------------------------------------
+// parseSubcommand
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the raw argument string array that accompanies a `/ct` invocation.
+ *
+ * The first token is treated as the subcommand (subject to alias resolution).
+ * Tokens starting with `--` are flags:
+ *   - `--flag`        →  `{ flag: true }`
+ *   - `--key=value`   →  `{ key: "value" }`
+ * All other tokens are collected as positional arguments.
+ */
+export function parseSubcommand(args: string[]): ParsedCommand {
+  const flags: Record<string, true | string> = {};
+  const positional: string[] = [];
+
+  let subcommand: SubcommandName | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+
+    // First non-flag token is the subcommand.
+    if (subcommand === undefined && !token.startsWith("--")) {
+      subcommand = resolveAlias(token);
+      continue;
+    }
+
+    // Flag tokens.
+    if (token.startsWith("--")) {
+      const body = token.slice(2);
+
+      if (body.includes("=")) {
+        const eqIdx = body.indexOf("=");
+        const key = body.slice(0, eqIdx);
+        const value = body.slice(eqIdx + 1);
+        flags[key] = value;
+      } else {
+        flags[body] = true;
+      }
+      continue;
+    }
+
+    // Everything else is positional.
+    positional.push(token);
+  }
+
+  return { subcommand, flags, positional };
+}

package/src/commands/init.ts

@@ -0,0 +1,127 @@
+/**
+ * `ct init` command implementation.
+ *
+ * Scans currently installed pi packages and generates `cat.yaml`.
+ * With `--from-gist <id>`, imports catalog content from a public GitHub Gist.
+ */
+
+import yaml from "js-yaml";
+
+import { scanInstalled } from "../catalog/install.js";
+import { CatalogYamlSchema } from "../config/schema.js";
+import type { CatalogYaml } from "../config/schema.js";
+import type { CommandArgs, CommandCtx } from "./types.js";
+import { writeCatalog } from "../config/io.js";
+import { readGist } from "../sync/gist.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Context for `initCommand`. Uses the base `CommandCtx`. */
+export type InitContext = CommandCtx;
+
+// ---------------------------------------------------------------------------
+// initCommand
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize a new catalog.
+ *
+ * - Without flags: scans installed packages and generates a catalog with
+ *   `rating: 'core'` for every discovered package.
+ * - With `--from-gist=<id>`: fetches the gist, reads its `cat.yaml` file,
+ *   validates it, and writes it as the local catalog.
+ */
+export async function initCommand(
+  args: CommandArgs,
+  ctx: InitContext,
+): Promise<void> {
+  const { flags } = args;
+
+  // --from-gist mode
+  const gistId = typeof flags["from-gist"] === "string" ? flags["from-gist"] : undefined;
+
+  if (gistId) {
+    await initFromGist(gistId, ctx);
+    return;
+  }
+
+  // Default: scan installed packages
+  initFromScan(ctx);
+}
+
+// ---------------------------------------------------------------------------
+// initFromScan
+// ---------------------------------------------------------------------------
+
+function initFromScan(ctx: InitContext): void {
+  let installed: Record<string, { source: string }>;
+  try {
+    installed = scanInstalled(ctx.home);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to scan installed packages: ${message}`, "error");
+    return;
+  }
+  const names = Object.keys(installed);
+
+  const packages: CatalogYaml["packages"] = {};
+  for (const [name, pkg] of Object.entries(installed)) {
+    packages[name] = {
+      source: pkg.source,
+      rating: "core",
+    };
+  }
+
+  const catalog: CatalogYaml = {
+    meta: { pi_version: "0.0.0" },
+    packages,
+  };
+
+  writeCatalog(catalog, ctx.home);
+
+  ctx.ui.notify(
+    `Initialized catalog with ${names.length} package${names.length === 1 ? "" : "s"}.`,
+    "info",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// initFromGist
+// ---------------------------------------------------------------------------
+
+async function initFromGist(gistId: string, ctx: InitContext): Promise<void> {
+  let gistContent: string;
+
+  try {
+    const gist = await readGist(gistId);
+    const catFile = gist.files["cat.yaml"];
+
+    if (!catFile?.content) {
+      ctx.ui.notify(
+        `Gist "${gistId}" does not contain a cat.yaml file.`,
+        "error",
+      );
+      return;
+    }
+
+    gistContent = catFile.content;
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to fetch gist: ${message}`, "error");
+    return;
+  }
+
+  // Validate and write
+  const parsed = yaml.load(gistContent);
+  const catalog = CatalogYamlSchema.parse(parsed);
+
+  writeCatalog(catalog, ctx.home);
+
+  const count = Object.keys(catalog.packages).length;
+  ctx.ui.notify(
+    `Imported catalog from gist with ${count} package${count === 1 ? "" : "s"}.`,
+    "info",
+  );
+}

package/src/commands/login.ts

@@ -0,0 +1,105 @@
+/**
+ * `ct login` subcommand implementation.
+ *
+ * Authenticates the user via the GitHub CLI (`gh`) and auto-pulls their
+ * remote catalog on success.
+ *
+ * Flow:
+ *   1. Detect whether `gh` CLI is installed.
+ *   2. Check if the user is authenticated via `gh auth status`.
+ *   3. Verify a valid token is available via `getToken()`.
+ *   4. Auto-pull the remote catalog on success.
+ */
+
+import type { CommandArgs, CommandCtx } from "./types.js";
+import { checkAuth, getToken, isGhInstalled } from "../sync/auth.js";
+import { pullCatalog } from "../sync/pull.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Context for `loginCommand`. Uses the base `CommandCtx`. */
+export type LoginCtx = CommandCtx;
+
+// ---------------------------------------------------------------------------
+// loginCommand
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute the `ct login` subcommand.
+ *
+ * Detects `gh` CLI, checks authentication status, verifies token,
+ * and auto-pulls the remote catalog on success.
+ */
+export async function loginCommand(
+  args: CommandArgs,
+  ctx: LoginCtx,
+): Promise<void> {
+  const { flags } = args;
+  const profile =
+    typeof flags["profile"] === "string" ? flags["profile"] : "default";
+
+  // --- 1. Detect gh CLI -----------------------------------------------------
+  const ghInstalled = await isGhInstalled();
+
+  if (!ghInstalled) {
+    ctx.ui.notify(
+      "GitHub CLI (`gh`) is not installed. Install it from https://cli.github.com, then re-run `ct login`.",
+      "info",
+    );
+    return;
+  }
+
+  // --- 2. Check authentication status ----------------------------------------
+  const isAuthenticated = await checkAuth();
+
+  if (!isAuthenticated) {
+    ctx.ui.notify(
+      "Not authenticated with GitHub. Run the following to log in:\n" +
+        "  gh auth login\n" +
+        "Then re-run `ct login` to connect your catalog.",
+      "info",
+    );
+    return;
+  }
+
+  // --- 3. Verify token ------------------------------------------------------
+  const token = await getToken();
+
+  if (!token) {
+    ctx.ui.notify(
+      "Authenticated, but no token available. Run `gh auth login` with the `read:gist` scope, then re-run `ct login`.",
+      "warning",
+    );
+    return;
+  }
+
+  // --- 4. Already authenticated — auto-pull ---------------------------------
+  ctx.ui.notify("Already authenticated with GitHub.", "info");
+
+  try {
+    await pullCatalog(profile, ctx.home);
+    ctx.ui.notify(
+      `Login successful. Pulled remote catalog for profile "${profile}".`,
+      "info",
+    );
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    // If no gist exists, provide first-time guidance
+    if (message.includes("No gist found")) {
+      ctx.ui.notify(
+        "Login successful, but no remote catalog found. " +
+          "Use `ct add` to add packages, then `ct sync` to create and push your catalog.",
+        "info",
+      );
+      return;
+    }
+
+    ctx.ui.notify(
+      `Login successful, but pull failed: ${message}`,
+      "warning",
+    );
+  }
+}