Add CLI package, config file support, and workspace setup

Add cli/ package with initial scaffolding. Add config-schema to shared
package for typed configuration. Add server config-file loader for
paperclip.config.ts support. Register cli in pnpm workspace. Add
.paperclip/ and .pnpm-store/ to gitignore. Minor Companies page fix.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

cli/src/commands/configure.ts

@@ -0,0 +1,113 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readConfig, writeConfig, configExists } from "../config/store.js";
+import type { PaperclipConfig } from "../config/schema.js";
+import { promptDatabase } from "../prompts/database.js";
+import { promptLlm } from "../prompts/llm.js";
+import { promptLogging } from "../prompts/logging.js";
+import { promptServer } from "../prompts/server.js";
+
+type Section = "llm" | "database" | "logging" | "server";
+
+const SECTION_LABELS: Record<Section, string> = {
+  llm: "LLM Provider",
+  database: "Database",
+  logging: "Logging",
+  server: "Server",
+};
+
+export async function configure(opts: {
+  config?: string;
+  section?: string;
+}): Promise<void> {
+  p.intro(pc.bgCyan(pc.black(" paperclip configure ")));
+
+  if (!configExists(opts.config)) {
+    p.log.error("No config file found. Run `paperclip onboard` first.");
+    p.outro("");
+    return;
+  }
+
+  const config = readConfig(opts.config);
+  if (!config) {
+    p.log.error("Could not read config file. Run `paperclip onboard` to recreate.");
+    p.outro("");
+    return;
+  }
+
+  let section: Section | undefined = opts.section as Section | undefined;
+
+  if (section && !SECTION_LABELS[section]) {
+    p.log.error(`Unknown section: ${section}. Choose from: ${Object.keys(SECTION_LABELS).join(", ")}`);
+    p.outro("");
+    return;
+  }
+
+  // Section selection loop
+  let continueLoop = true;
+  while (continueLoop) {
+    if (!section) {
+      const choice = await p.select({
+        message: "Which section do you want to configure?",
+        options: Object.entries(SECTION_LABELS).map(([value, label]) => ({
+          value: value as Section,
+          label,
+        })),
+      });
+
+      if (p.isCancel(choice)) {
+        p.cancel("Configuration cancelled.");
+        return;
+      }
+
+      section = choice;
+    }
+
+    p.log.step(pc.bold(SECTION_LABELS[section]));
+
+    switch (section) {
+      case "database":
+        config.database = await promptDatabase();
+        break;
+      case "llm": {
+        const llm = await promptLlm();
+        if (llm) {
+          config.llm = llm;
+        } else {
+          delete config.llm;
+        }
+        break;
+      }
+      case "logging":
+        config.logging = await promptLogging();
+        break;
+      case "server":
+        config.server = await promptServer();
+        break;
+    }
+
+    config.$meta.updatedAt = new Date().toISOString();
+    config.$meta.source = "configure";
+
+    writeConfig(config, opts.config);
+    p.log.success(`${SECTION_LABELS[section]} configuration updated.`);
+
+    // If section was provided via CLI flag, don't loop
+    if (opts.section) {
+      continueLoop = false;
+    } else {
+      const another = await p.confirm({
+        message: "Configure another section?",
+        initialValue: false,
+      });
+
+      if (p.isCancel(another) || !another) {
+        continueLoop = false;
+      } else {
+        section = undefined; // Reset to show picker again
+      }
+    }
+  }
+
+  p.outro("Configuration saved.");
+}

cli/src/commands/doctor.ts

@@ -0,0 +1,120 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { readConfig } from "../config/store.js";
+import {
+  configCheck,
+  databaseCheck,
+  llmCheck,
+  logCheck,
+  portCheck,
+  type CheckResult,
+} from "../checks/index.js";
+
+const STATUS_ICON = {
+  pass: pc.green("✓"),
+  warn: pc.yellow("!"),
+  fail: pc.red("✗"),
+} as const;
+
+export async function doctor(opts: {
+  config?: string;
+  repair?: boolean;
+  yes?: boolean;
+}): Promise<void> {
+  p.intro(pc.bgCyan(pc.black(" paperclip doctor ")));
+
+  const results: CheckResult[] = [];
+
+  // 1. Config check (must pass before others)
+  const cfgResult = configCheck(opts.config);
+  results.push(cfgResult);
+  printResult(cfgResult);
+
+  if (cfgResult.status === "fail") {
+    printSummary(results);
+    return;
+  }
+
+  const config = readConfig(opts.config)!;
+
+  // 2. Database check
+  const dbResult = await databaseCheck(config);
+  results.push(dbResult);
+  printResult(dbResult);
+  await maybeRepair(dbResult, opts);
+
+  // 3. LLM check
+  const llmResult = await llmCheck(config);
+  results.push(llmResult);
+  printResult(llmResult);
+
+  // 4. Log directory check
+  const logResult = logCheck(config);
+  results.push(logResult);
+  printResult(logResult);
+  await maybeRepair(logResult, opts);
+
+  // 5. Port check
+  const portResult = await portCheck(config);
+  results.push(portResult);
+  printResult(portResult);
+
+  // Summary
+  printSummary(results);
+}
+
+function printResult(result: CheckResult): void {
+  const icon = STATUS_ICON[result.status];
+  p.log.message(`${icon} ${pc.bold(result.name)}: ${result.message}`);
+  if (result.status !== "pass" && result.repairHint) {
+    p.log.message(`  ${pc.dim(result.repairHint)}`);
+  }
+}
+
+async function maybeRepair(
+  result: CheckResult,
+  opts: { repair?: boolean; yes?: boolean },
+): Promise<void> {
+  if (result.status === "pass" || !result.canRepair || !result.repair) return;
+  if (!opts.repair) return;
+
+  let shouldRepair = opts.yes;
+  if (!shouldRepair) {
+    const answer = await p.confirm({
+      message: `Repair "${result.name}"?`,
+      initialValue: true,
+    });
+    if (p.isCancel(answer)) return;
+    shouldRepair = answer;
+  }
+
+  if (shouldRepair) {
+    try {
+      await result.repair();
+      p.log.success(`Repaired: ${result.name}`);
+    } catch (err) {
+      p.log.error(`Repair failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+
+function printSummary(results: CheckResult[]): void {
+  const passed = results.filter((r) => r.status === "pass").length;
+  const warned = results.filter((r) => r.status === "warn").length;
+  const failed = results.filter((r) => r.status === "fail").length;
+
+  const parts: string[] = [];
+  parts.push(pc.green(`${passed} passed`));
+  if (warned) parts.push(pc.yellow(`${warned} warnings`));
+  if (failed) parts.push(pc.red(`${failed} failed`));
+
+  p.note(parts.join(", "), "Summary");
+
+  if (failed > 0) {
+    p.outro(pc.red("Some checks failed. Fix the issues above and re-run doctor."));
+  } else if (warned > 0) {
+    p.outro(pc.yellow("All critical checks passed with some warnings."));
+  } else {
+    p.outro(pc.green("All checks passed!"));
+  }
+}

cli/src/commands/onboard.ts

@@ -0,0 +1,127 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { configExists, readConfig, writeConfig } from "../config/store.js";
+import type { PaperclipConfig } from "../config/schema.js";
+import { promptDatabase } from "../prompts/database.js";
+import { promptLlm } from "../prompts/llm.js";
+import { promptLogging } from "../prompts/logging.js";
+import { promptServer } from "../prompts/server.js";
+
+export async function onboard(opts: { config?: string }): Promise<void> {
+  p.intro(pc.bgCyan(pc.black(" paperclip onboard ")));
+
+  // Check for existing config
+  if (configExists(opts.config)) {
+    const existing = readConfig(opts.config);
+    if (existing) {
+      const overwrite = await p.confirm({
+        message: "A config file already exists. Overwrite it?",
+        initialValue: false,
+      });
+
+      if (p.isCancel(overwrite) || !overwrite) {
+        p.cancel("Keeping existing configuration.");
+        return;
+      }
+    }
+  }
+
+  // Database
+  p.log.step(pc.bold("Database"));
+  const database = await promptDatabase();
+
+  if (database.mode === "postgres" && database.connectionString) {
+    const s = p.spinner();
+    s.start("Testing database connection...");
+    try {
+      const { createDb } = await import("@paperclip/db");
+      const db = createDb(database.connectionString);
+      await db.execute("SELECT 1");
+      s.stop("Database connection successful");
+    } catch (err) {
+      s.stop(pc.yellow("Could not connect to database — you can fix this later with `paperclip doctor`"));
+    }
+  }
+
+  // LLM
+  p.log.step(pc.bold("LLM Provider"));
+  const llm = await promptLlm();
+
+  if (llm?.apiKey) {
+    const s = p.spinner();
+    s.start("Validating API key...");
+    try {
+      if (llm.provider === "claude") {
+        const res = await fetch("https://api.anthropic.com/v1/messages", {
+          method: "POST",
+          headers: {
+            "x-api-key": llm.apiKey,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({
+            model: "claude-sonnet-4-5-20250929",
+            max_tokens: 1,
+            messages: [{ role: "user", content: "hi" }],
+          }),
+        });
+        if (res.ok || res.status === 400) {
+          s.stop("API key is valid");
+        } else if (res.status === 401) {
+          s.stop(pc.yellow("API key appears invalid — you can update it later"));
+        } else {
+          s.stop(pc.yellow("Could not validate API key — continuing anyway"));
+        }
+      } else {
+        const res = await fetch("https://api.openai.com/v1/models", {
+          headers: { Authorization: `Bearer ${llm.apiKey}` },
+        });
+        if (res.ok) {
+          s.stop("API key is valid");
+        } else if (res.status === 401) {
+          s.stop(pc.yellow("API key appears invalid — you can update it later"));
+        } else {
+          s.stop(pc.yellow("Could not validate API key — continuing anyway"));
+        }
+      }
+    } catch {
+      s.stop(pc.yellow("Could not reach API — continuing anyway"));
+    }
+  }
+
+  // Logging
+  p.log.step(pc.bold("Logging"));
+  const logging = await promptLogging();
+
+  // Server
+  p.log.step(pc.bold("Server"));
+  const server = await promptServer();
+
+  // Assemble and write config
+  const config: PaperclipConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: new Date().toISOString(),
+      source: "onboard",
+    },
+    ...(llm && { llm }),
+    database,
+    logging,
+    server,
+  };
+
+  writeConfig(config, opts.config);
+
+  p.note(
+    [
+      `Database: ${database.mode}`,
+      llm ? `LLM: ${llm.provider}` : "LLM: not configured",
+      `Logging: ${logging.mode} → ${logging.logDir}`,
+      `Server: port ${server.port}`,
+    ].join("\n"),
+    "Configuration saved",
+  );
+
+  p.log.info(`Run ${pc.cyan("pnpm paperclip doctor")} to verify your setup.`);
+  p.outro("You're all set!");
+}