codeguilds 0.2.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "codeguilds",
+  "version": "0.2.0",
+  "description": "CLI for the CodeGuilds registry — install MCP servers, skills, agents, hooks, and prompts for Claude Code",
+  "bin": {
+    "codeguilds": "./dist/index.js"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.1.1",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.57",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/commands/info.ts

@@ -0,0 +1,37 @@
+import chalk from "chalk";
+import ora from "ora";
+import { fetchPackage } from "../lib/api.js";
+import { formatNumber } from "../lib/format.js";
+
+export async function info(slug: string): Promise<void> {
+  const spinner = ora(`Fetching ${chalk.cyan(slug)}...`).start();
+
+  try {
+    const pkg = await fetchPackage(slug);
+    spinner.stop();
+
+    if (!pkg) {
+      console.log(chalk.yellow(`Package ${chalk.cyan(slug)} not found`));
+      process.exit(1);
+    }
+
+    console.log(`
+${chalk.bold(pkg.name)} ${chalk.dim(`v${pkg.current_version}`)}
+${pkg.description ?? ""}
+
+  ${chalk.dim("Type:")}       ${pkg.package_type}
+  ${chalk.dim("Publisher:")}  @${pkg.publisher?.username ?? "unknown"}
+  ${chalk.dim("Downloads:")}  ${formatNumber(pkg.download_count)}
+  ${chalk.dim("Stars:")}      ${pkg.star_count}
+  ${chalk.dim("License:")}    ${pkg.license ?? "unknown"}
+  ${chalk.dim("Published:")}  ${pkg.published_at ? new Date(pkg.published_at).toLocaleDateString() : "—"}
+  ${pkg.source_url ? `${chalk.dim("Source:")}     ${pkg.source_url}` : ""}
+
+${chalk.dim("Install:")}
+  ${chalk.cyan(`codeguilds install ${pkg.slug}`)}
+`);
+  } catch (err) {
+    spinner.fail((err as Error).message);
+    process.exit(1);
+  }
+}

package/src/commands/install.ts

@@ -0,0 +1,55 @@
+import chalk from "chalk";
+import ora from "ora";
+import { fetchPackage, recordDownload } from "../lib/api.js";
+import { installPackage, type Scope } from "../lib/installers.js";
+import { addToLock, readLock } from "../lib/lock.js";
+
+const VALID_STRATEGIES = ["append", "prepend", "replace"] as const;
+
+export async function install(slug: string, options: { project?: boolean; strategy?: string }): Promise<void> {
+  const scope: Scope = options.project ? "project" : "global";
+
+  if (options.strategy && !VALID_STRATEGIES.includes(options.strategy as never)) {
+    console.error(`Invalid strategy '${options.strategy}'. Must be: append, prepend, replace`);
+    process.exit(1);
+  }
+  const strategy = (options.strategy ?? "append") as "append" | "prepend" | "replace";
+
+  const spinner = ora(`Looking up ${chalk.cyan(slug)}...`).start();
+
+  try {
+    const pkg = await fetchPackage(slug);
+    if (!pkg) {
+      spinner.fail(`Package ${chalk.cyan(slug)} not found in registry`);
+      process.exit(1);
+    }
+
+    const lock = readLock();
+    if (lock.packages[slug]) {
+      spinner.info(
+        `${chalk.cyan(pkg.name)} ${chalk.dim(`v${lock.packages[slug].current_version}`)} is already installed`
+      );
+      return;
+    }
+
+    spinner.text = `Installing ${chalk.cyan(pkg.name)} v${pkg.current_version}...`;
+    const result = await installPackage(pkg, scope, strategy);
+
+    await recordDownload(pkg.id);
+    addToLock({
+      slug: pkg.slug,
+      name: pkg.name,
+      current_version: pkg.current_version,
+      package_type: pkg.package_type,
+      installed_at: new Date().toISOString(),
+    });
+
+    spinner.succeed(
+      `Installed ${chalk.green(pkg.name)} ${chalk.dim(`v${pkg.current_version}`)} → ${chalk.dim(result.destination)}`
+    );
+    if (result.note) console.log(`  ${chalk.dim("ℹ")} ${result.note}`);
+  } catch (err) {
+    spinner.fail((err as Error).message);
+    process.exit(1);
+  }
+}

package/src/commands/list.ts

@@ -0,0 +1,31 @@
+import chalk from "chalk";
+import { readLock } from "../lib/lock.js";
+
+const TYPE_LABELS: Record<string, string> = {
+  mcp_server: "MCP",
+  skill: "skill",
+  agent: "agent",
+  hook: "hook",
+  prompt: "prompt",
+  claude_md_template: "template",
+};
+
+export function list(): void {
+  const lock = readLock();
+  const entries = Object.values(lock.packages);
+
+  if (entries.length === 0) {
+    console.log(chalk.dim("No packages installed. Run `codeguilds install <slug>` to get started."));
+    return;
+  }
+
+  console.log(`\n${chalk.bold(`${entries.length} package${entries.length === 1 ? "" : "s"} installed`)}\n`);
+
+  for (const entry of entries.sort((a, b) => a.slug.localeCompare(b.slug))) {
+    const typeLabel = TYPE_LABELS[entry.package_type] ?? entry.package_type;
+    const date = new Date(entry.installed_at).toLocaleDateString();
+    console.log(
+      `  ${chalk.cyan(entry.slug.padEnd(36))} ${chalk.dim(typeLabel.padEnd(10))} ${chalk.dim(`v${entry.current_version.padEnd(10)}`)} ${chalk.dim(date)}`
+    );
+  }
+}

package/src/commands/login.ts

@@ -0,0 +1,116 @@
+import { createServer } from "http";
+import { createHash, randomBytes } from "crypto";
+import { spawn } from "child_process";
+import chalk from "chalk";
+import ora from "ora";
+import { saveAuth, readAuth } from "../lib/auth.js";
+
+const WEB_BASE = process.env.CODEGUILDS_WEB_URL ?? "https://codeguilds.dev";
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+
+function randomPort(): number {
+  return 10000 + Math.floor(Math.random() * 50000);
+}
+
+function openBrowser(url: string): void {
+  const cmd =
+    process.platform === "darwin" ? "open" :
+    process.platform === "win32" ? "start" :
+    "xdg-open";
+  spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
+}
+
+export async function login(): Promise<void> {
+  const existing = readAuth();
+  if (existing) {
+    const saved = new Date(existing.saved_at).toLocaleDateString();
+    console.log(chalk.yellow(`Already logged in (session saved ${saved}).`));
+    console.log(`Run ${chalk.cyan("codeguilds logout")} to clear the session.\n`);
+    return;
+  }
+
+  const port = randomPort();
+  const state = randomBytes(16).toString("hex");
+  const authUrl = `${WEB_BASE}/cli-auth?port=${port}&state=${encodeURIComponent(state)}`;
+
+  const spinner = ora("Waiting for browser authentication...").start();
+
+  const result = await new Promise<{ access_token: string; refresh_token: string } | null>((resolve) => {
+    const timeout = setTimeout(() => {
+      server.close();
+      resolve(null);
+    }, LOGIN_TIMEOUT_MS);
+
+    // OAuth tokens are delivered via localhost redirect — standard practice for CLI tools
+    // (used by GitHub CLI, VS Code, Spotify CLI). The loopback interface is local-only.
+    // Tokens arrive as query params; they are immediately consumed and the server shuts down.
+    const server = createServer((req, res) => {
+      if (!req.url?.startsWith("/callback")) {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url, `http://localhost:${port}`);
+      const receivedState = url.searchParams.get("state");
+      const accessToken = url.searchParams.get("access_token");
+      const refreshToken = url.searchParams.get("refresh_token");
+
+      // Constant-time state comparison
+      const expectedBuf = Buffer.from(state);
+      const receivedBuf = Buffer.from(receivedState ?? "");
+      const stateValid =
+        expectedBuf.length === receivedBuf.length &&
+        createHash("sha256").update(expectedBuf).digest().equals(
+          createHash("sha256").update(receivedBuf).digest()
+        );
+
+      if (!stateValid || !accessToken || !refreshToken) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end("<html><body><h2>Authentication failed. Please try again.</h2></body></html>");
+        clearTimeout(timeout);
+        server.close();
+        resolve(null);
+        return;
+      }
+
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(
+        "<html><body style='font-family:sans-serif;text-align:center;padding:4rem'>" +
+        "<h2>✅ Logged in successfully!</h2>" +
+        "<p>You can close this tab and return to your terminal.</p>" +
+        "</body></html>"
+      );
+
+      clearTimeout(timeout);
+      server.close();
+      resolve({ access_token: accessToken, refresh_token: refreshToken });
+    });
+
+    server.listen(port, "127.0.0.1", () => {
+      spinner.text = `Opening browser... ${chalk.dim(authUrl)}`;
+      openBrowser(authUrl);
+      console.log(`\n${chalk.dim("If the browser did not open, visit:")}`);
+      console.log(`${chalk.cyan(authUrl)}\n`);
+    });
+
+    server.on("error", () => {
+      clearTimeout(timeout);
+      resolve(null);
+    });
+  });
+
+  if (!result) {
+    spinner.fail("Login timed out or was cancelled.");
+    process.exit(1);
+  }
+
+  saveAuth(result);
+  spinner.succeed(chalk.green("Logged in successfully! Credentials saved to ~/.codeguilds/auth.json"));
+}
+
+export async function logout(): Promise<void> {
+  const { clearAuth } = await import("../lib/auth.js");
+  clearAuth();
+  console.log(chalk.green("Logged out. Session cleared."));
+}

package/src/commands/search.ts

@@ -0,0 +1,45 @@
+import chalk from "chalk";
+import ora from "ora";
+import { searchPackages } from "../lib/api.js";
+import { formatNumber } from "../lib/format.js";
+
+const TYPE_LABELS: Record<string, string> = {
+  mcp_server: "MCP",
+  skill: "skill",
+  agent: "agent",
+  hook: "hook",
+  prompt: "prompt",
+  claude_md_template: "template",
+};
+
+export async function search(query: string): Promise<void> {
+  const spinner = ora(`Searching for "${query}"...`).start();
+
+  try {
+    const results = await searchPackages(query);
+    spinner.stop();
+
+    if (results.length === 0) {
+      console.log(chalk.yellow(`No packages found for "${query}"`));
+      return;
+    }
+
+    console.log(`\n${chalk.bold(`Found ${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`)}\n`);
+
+    for (const pkg of results) {
+      const typeLabel = TYPE_LABELS[pkg.package_type] ?? pkg.package_type;
+      const publisher = pkg.publisher?.username ?? "unknown";
+      console.log(
+        `  ${chalk.cyan(pkg.slug.padEnd(36))} ${chalk.dim(typeLabel.padEnd(10))} ${chalk.dim(`↓ ${formatNumber(pkg.download_count).padEnd(8)}`)} ${chalk.dim(`by @${publisher}`)}`
+      );
+      if (pkg.description) {
+        console.log(`  ${chalk.dim("  " + pkg.description.slice(0, 72))}`);
+      }
+    }
+
+    console.log(`\n${chalk.dim(`Install with: codeguilds install <slug>`)}`);
+  } catch (err) {
+    spinner.fail((err as Error).message);
+    process.exit(1);
+  }
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,33 @@
+import chalk from "chalk";
+import ora from "ora";
+import { fetchPackage } from "../lib/api.js";
+import { uninstallPackage, type Scope } from "../lib/installers.js";
+import { removeFromLock, readLock } from "../lib/lock.js";
+
+export async function uninstall(slug: string, options: { project?: boolean }): Promise<void> {
+  const scope: Scope = options.project ? "project" : "global";
+  const lock = readLock();
+
+  if (!lock.packages[slug]) {
+    console.log(chalk.yellow(`${chalk.cyan(slug)} is not in the lock file — may not be installed`));
+  }
+
+  const spinner = ora(`Uninstalling ${chalk.cyan(slug)}...`).start();
+
+  try {
+    const pkg = await fetchPackage(slug);
+    if (!pkg) {
+      removeFromLock(slug);
+      spinner.succeed(`Removed ${chalk.cyan(slug)} from lock file (package not found in registry)`);
+      return;
+    }
+
+    const result = uninstallPackage(pkg, scope);
+    removeFromLock(slug);
+    spinner.succeed(`Uninstalled ${chalk.green(pkg.name)}`);
+    console.log(`  ${chalk.dim("ℹ")} ${result.message}`);
+  } catch (err) {
+    spinner.fail((err as Error).message);
+    process.exit(1);
+  }
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+import { Command } from "commander";
+import { install } from "./commands/install.js";
+import { uninstall } from "./commands/uninstall.js";
+import { search } from "./commands/search.js";
+import { list } from "./commands/list.js";
+import { info } from "./commands/info.js";
+import { login, logout } from "./commands/login.js";
+
+const program = new Command();
+
+program
+  .name("codeguilds")
+  .description("CLI for the CodeGuilds registry — install packages for Claude Code")
+  .version("0.1.0");
+
+program
+  .command("install <slug>")
+  .description("Install a package from the registry")
+  .option("--project", "Install into project-local .claude/ instead of global")
+  .option("--strategy <strategy>", "Merge strategy for CLAUDE.md templates: append | prepend | replace", "append")
+  .action(install);
+
+program
+  .command("uninstall <slug>")
+  .alias("remove")
+  .description("Uninstall a package and undo config changes")
+  .option("--project", "Target project-local .claude/ scope")
+  .action(uninstall);
+
+program
+  .command("search <query>")
+  .description("Search the registry")
+  .action(search);
+
+program
+  .command("list")
+  .alias("ls")
+  .description("List installed packages")
+  .action(list);
+
+program
+  .command("info <slug>")
+  .description("Show details about a package")
+  .action(info);
+
+program
+  .command("login")
+  .description("Authenticate via browser OAuth")
+  .action(login);
+
+program
+  .command("logout")
+  .description("Clear saved credentials")
+  .action(logout);
+
+program.parse();

package/src/lib/api.ts

@@ -0,0 +1,53 @@
+import type { RegistryPackage } from "./types.js";
+
+const REGISTRY_URL = "https://wfolayipdobqxxhmejwq.supabase.co";
+
+// This is the Supabase anon (publishable) key — it is intentionally public.
+// Anon keys are safe to ship in client-side code; they are not secret.
+// The service role key (which IS secret) is never used in the CLI.
+const PUBLIC_ANON_KEY =
+  process.env.CODEGUILDS_ANON_KEY ??
+  "sb_publishable_n5NyXLvcPMLSAWpQodcuWQ_kOz_LUTs";
+const ANON_KEY = PUBLIC_ANON_KEY;
+
+async function restGet<T>(path: string): Promise<T> {
+  const res = await fetch(`${REGISTRY_URL}/rest/v1/${path}`, {
+    headers: {
+      apikey: ANON_KEY,
+      Authorization: `Bearer ${ANON_KEY}`,
+    },
+  });
+  if (!res.ok) throw new Error(`Registry error ${res.status}: ${await res.text()}`);
+  return res.json() as Promise<T>;
+}
+
+export async function fetchPackage(slug: string): Promise<RegistryPackage | null> {
+  const rows = await restGet<RegistryPackage[]>(
+    `packages?slug=eq.${encodeURIComponent(slug)}&status=eq.published&select=id,slug,name,description,package_type,current_version,download_count,star_count,install_config,source_url,readme_content,license,published_at,publisher:profiles!packages_publisher_id_fkey(username,display_name)&limit=1`
+  );
+  return rows[0] ?? null;
+}
+
+export async function searchPackages(query: string): Promise<RegistryPackage[]> {
+  // Strip PostgREST glob characters (* and ?) from user input to prevent unintended wildcard expansion
+  const safeQuery = query.replace(/[*?]/g, "");
+  return restGet<RegistryPackage[]>(
+    `packages?status=eq.published&or=(name.ilike.*${encodeURIComponent(safeQuery)}*,description.ilike.*${encodeURIComponent(safeQuery)}*)&select=id,slug,name,description,package_type,current_version,download_count,star_count,published_at,publisher:profiles!packages_publisher_id_fkey(username,display_name)&limit=20&order=download_count.desc`
+  );
+}
+
+export async function recordDownload(packageId: string): Promise<void> {
+  try {
+    await fetch(`${REGISTRY_URL}/rpc/record_download`, {
+      method: "POST",
+      headers: {
+        apikey: ANON_KEY,
+        Authorization: `Bearer ${ANON_KEY}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ p_package_id: packageId, p_source: "cli" }),
+    });
+  } catch {
+    // non-fatal
+  }
+}

package/src/lib/auth.ts

@@ -0,0 +1,47 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+
+const CONFIG_DIR = join(homedir(), ".codeguilds");
+const AUTH_FILE = join(CONFIG_DIR, "auth.json");
+
+export interface AuthTokens {
+  access_token: string;
+  refresh_token: string;
+  saved_at: string;
+}
+
+export function readAuth(): AuthTokens | null {
+  try {
+    if (!existsSync(AUTH_FILE)) return null;
+    const raw = readFileSync(AUTH_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<AuthTokens>;
+    if (!parsed.access_token) return null;
+    return parsed as AuthTokens;
+  } catch {
+    return null;
+  }
+}
+
+export function saveAuth(tokens: Omit<AuthTokens, "saved_at">): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  const data: AuthTokens = { ...tokens, saved_at: new Date().toISOString() };
+  writeFileSync(AUTH_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+
+export function clearAuth(): void {
+  try {
+    if (existsSync(AUTH_FILE)) {
+      unlinkSync(AUTH_FILE);
+    }
+  } catch {
+    // ignore
+  }
+}
+
+export function getAuthHeader(): string | null {
+  const auth = readAuth();
+  return auth ? `Bearer ${auth.access_token}` : null;
+}

package/src/lib/claude-settings.ts

@@ -0,0 +1,107 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { resolve, dirname } from "path";
+import { homedir } from "os";
+
+interface McpServer {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+interface Hook {
+  matcher?: string;
+  hooks: Array<{ type: string; command: string }>;
+}
+
+interface ClaudeSettings {
+  mcpServers?: Record<string, McpServer>;
+  hooks?: Record<string, Hook[]>;
+  [key: string]: unknown;
+}
+
+export function getSettingsPath(scope: "global" | "project"): string {
+  if (scope === "global") {
+    return resolve(homedir(), ".claude", "settings.json");
+  }
+  return resolve(process.cwd(), ".claude", "settings.json");
+}
+
+function readSettings(path: string): ClaudeSettings {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as ClaudeSettings;
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(path: string, settings: ClaudeSettings): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+}
+
+export function addMcpServer(
+  serverName: string,
+  command: string,
+  args: string[],
+  env: Record<string, string>,
+  scope: "global" | "project"
+): void {
+  const path = getSettingsPath(scope);
+  const settings = readSettings(path);
+  settings.mcpServers = settings.mcpServers ?? {};
+  settings.mcpServers[serverName] = {
+    command,
+    ...(args.length ? { args } : {}),
+    ...(Object.keys(env).length ? { env } : {}),
+  };
+  writeSettings(path, settings);
+}
+
+export function removeMcpServer(serverName: string, scope: "global" | "project"): boolean {
+  const path = getSettingsPath(scope);
+  const settings = readSettings(path);
+  if (!settings.mcpServers?.[serverName]) return false;
+  delete settings.mcpServers[serverName];
+  writeSettings(path, settings);
+  return true;
+}
+
+export function addHook(
+  event: string,
+  matcher: string,
+  command: string,
+  scope: "global" | "project"
+): void {
+  const path = getSettingsPath(scope);
+  const settings = readSettings(path);
+  settings.hooks = settings.hooks ?? {};
+  settings.hooks[event] = settings.hooks[event] ?? [];
+  const existing = settings.hooks[event].find((h) => h.matcher === matcher);
+  if (existing) {
+    existing.hooks = existing.hooks.filter((h) => h.command !== command);
+    existing.hooks.push({ type: "command", command });
+  } else {
+    settings.hooks[event].push({
+      ...(matcher ? { matcher } : {}),
+      hooks: [{ type: "command", command }],
+    } as Hook);
+  }
+  writeSettings(path, settings);
+}
+
+export function removeHook(event: string, command: string, scope: "global" | "project"): boolean {
+  const path = getSettingsPath(scope);
+  const settings = readSettings(path);
+  if (!settings.hooks?.[event]) return false;
+  let removed = false;
+  settings.hooks[event] = settings.hooks[event]
+    .map((h) => {
+      const filtered = h.hooks.filter((hk) => hk.command !== command);
+      if (filtered.length !== h.hooks.length) removed = true;
+      return { ...h, hooks: filtered };
+    })
+    .filter((h) => h.hooks.length > 0);
+  if (removed) writeSettings(path, settings);
+  return removed;
+}

package/src/lib/format.ts

@@ -0,0 +1,5 @@
+export function formatNumber(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}