@llmkb/claude-code 0.1.0

package/lib/color.ts

@@ -0,0 +1,61 @@
+/** Terminal color helpers for llmkb output.
+
+Uses picocolors (14× smaller, 2× faster than chalk).
+Respects NO_COLOR env var automatically.
+*/
+
+import pc from "picocolors";
+
+// ---------------------------------------------------------------------------
+// Severity helpers
+// ---------------------------------------------------------------------------
+
+export const success = pc.green;
+export const error = pc.red;
+export const warning = pc.yellow;
+export const info = pc.cyan;
+export const highlight = (s: string) => pc.bold(pc.white(s));
+export const muted = pc.dim;
+
+// ---------------------------------------------------------------------------
+// Icon-label mapping
+// ---------------------------------------------------------------------------
+
+const ICON_COLORS: Record<string, (s: string) => string> = {
+  "✔": success,
+  "✓": success,
+  "✖": error,
+  "✗": error,
+  "⚠": warning,
+  "ℹ": info,
+  "⌚": info,
+};
+
+/** Apply color to an icon label (e.g. ``"✔"`` → green). */
+export function label(icon: string, text: string): string {
+  const colorFn = ICON_COLORS[icon];
+  if (colorFn) {
+    return `${colorFn(icon)} ${text}`;
+  }
+  return `${icon} ${text}`;
+}
+
+/** Color a status badge: active→green, expired→yellow, revoked→red, etc. */
+export function badge(status: string): string {
+  switch (status?.toLowerCase()) {
+    case "active":
+    case "present":
+    case "complete":
+    case "passed":
+      return pc.green(status);
+    case "expired":
+    case "missing":
+    case "failed":
+      return pc.red(status);
+    case "pending":
+    case "warning":
+      return pc.yellow(status);
+    default:
+      return status;
+  }
+}

package/lib/config-validation.ts

@@ -0,0 +1,332 @@
+/** Configuration validation utilities for the ``llmkb doctor`` command.
+
+Provides functions to validate ``.llmkb/config.yml``, ``.llmkb/spaces.yml``,
+access token status, and backend connectivity.
+*/
+
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { getToken } from "./credentials.js";
+
+// ---------------------------------------------------------------------------
+// Validation Result
+// ---------------------------------------------------------------------------
+
+export interface ValidationResult {
+  name: string;
+  passed: boolean;
+  message: string;
+  detail?: string;
+}
+
+// ---------------------------------------------------------------------------
+// URL Validation
+// ---------------------------------------------------------------------------
+
+/** Validate that a URL has a proper scheme and host. */
+export function validateBaseUrl(url: string): ValidationResult {
+  try {
+    const parsed = new URL(url);
+    if (!parsed.protocol || !parsed.host) {
+      return {
+        name: "Base URL format",
+        passed: false,
+        message: "URL missing scheme or host",
+        detail: `Got: ${url}`,
+      };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return {
+        name: "Base URL format",
+        passed: false,
+        message: `Unsupported protocol: ${parsed.protocol}`,
+        detail: `Got: ${url}`,
+      };
+    }
+    return {
+      name: "Base URL format",
+      passed: true,
+      message: `Valid URL: ${url}`,
+    };
+  } catch {
+    return {
+      name: "Base URL format",
+      passed: false,
+      message: "Invalid URL format",
+      detail: `Got: ${url}. Must include scheme (e.g., https://api.llmkb.ai)`,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config.yml Validation
+// ---------------------------------------------------------------------------
+
+/** Validate ``.llmkb/config.yml`` — parse, check required keys, check for invalid keys. */
+export async function validateConfigYml(projectDir: string): Promise<ValidationResult> {
+  const filePath = join(projectDir, ".llmkb", "config.yml");
+  if (!existsSync(filePath)) {
+    return {
+      name: "config.yml",
+      passed: false,
+      message: "File not found",
+      detail: "Run `llmkb init` to create it.",
+    };
+  }
+
+  try {
+    const content = await readFile(filePath, "utf-8");
+    const cfg = parse(content) as Record<string, unknown> | null;
+
+    // Comment-only YAML files parse to null — treat as empty config
+    if (cfg === null) {
+      return {
+        name: "config.yml",
+        passed: true,
+        message: "Valid config file (all defaults)",
+      };
+    }
+
+    if (cfg.llmkb_base_url !== undefined) {
+      const urlResult = validateBaseUrl(String(cfg.llmkb_base_url));
+      if (!urlResult.passed) {
+        return {
+          name: "config.yml",
+          passed: false,
+          message: "llmkb_base_url has invalid value",
+          detail: urlResult.detail,
+        };
+      }
+    }
+
+    return {
+      name: "config.yml",
+      passed: true,
+      message: "Valid config file",
+    };
+  } catch (err) {
+    return {
+      name: "config.yml",
+      passed: false,
+      message: "Invalid YAML",
+      detail: (err as Error).message,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Spaces.yml Validation
+// ---------------------------------------------------------------------------
+
+/** Validate ``.llmkb/spaces.yml`` — parse, check required fields. */
+export async function validateSpacesYml(projectDir: string): Promise<ValidationResult> {
+  const filePath = join(projectDir, ".llmkb", "spaces.yml");
+  if (!existsSync(filePath)) {
+    return {
+      name: "spaces.yml",
+      passed: false,
+      message: "File not found",
+      detail: "Run `llmkb init` or `llmkb login` to create it.",
+    };
+  }
+
+  try {
+    const content = await readFile(filePath, "utf-8");
+    const cfg = parse(content) as Record<string, unknown>;
+
+    if (cfg.project_space && Array.isArray(cfg.project_space)) {
+      for (const ps of cfg.project_space) {
+        if (!ps.id) {
+          return {
+            name: "spaces.yml",
+            passed: false,
+            message: "project_space entry missing required 'id' field",
+          };
+        }
+      }
+    }
+
+    if (cfg.spaces && Array.isArray(cfg.spaces)) {
+      for (const s of cfg.spaces) {
+        if (!s.id) {
+          return {
+            name: "spaces.yml",
+            passed: false,
+            message: "spaces entry missing required 'id' field",
+          };
+        }
+      }
+    }
+
+    return {
+      name: "spaces.yml",
+      passed: true,
+      message: `Valid config (${(cfg.spaces as unknown[])?.length ?? 0} space(s))`,
+    };
+  } catch (err) {
+    return {
+      name: "spaces.yml",
+      passed: false,
+      message: "Invalid YAML",
+      detail: (err as Error).message,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Access Token Validation
+// ---------------------------------------------------------------------------
+
+/** Check if an access token is stored in the keychain and is still valid. */
+export async function validateAccessToken(endpoint: string): Promise<ValidationResult> {
+  const token = await getToken();
+  if (!token) {
+    return {
+      name: "Access token",
+      passed: false,
+      message: "No access token found",
+      detail: "Set LLMKB_ACCESS_TOKEN env var or run `llmkb login --project-space <id>`.",
+    };
+  }
+
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/v1/auth/me`;
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (res.ok) {
+      const body = (await res.json()) as {
+        data?: { attributes?: { token_status?: string; email?: string } };
+      };
+      const attrs = body.data?.attributes;
+      const status = attrs?.token_status;
+      if (status === "active") {
+        return {
+          name: "Access token",
+          passed: true,
+          message: `Token is valid (user: ${attrs?.email ?? "unknown"})`,
+        };
+      }
+      return {
+        name: "Access token",
+        passed: false,
+        message: `Token status: ${status}`,
+        detail: "Generate a new token at /settings/access-tokens.",
+      };
+    }
+
+    return {
+      name: "Access token",
+      passed: false,
+      message: `Server returned ${res.status}`,
+      detail: "Token may be expired or invalid. Run `llmkb login --project-space <id>`.",
+    };
+  } catch (err) {
+    return {
+      name: "Access token",
+      passed: false,
+      message: "Cannot validate — server unreachable",
+      detail: (err as Error).message,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Backend Connectivity
+// ---------------------------------------------------------------------------
+
+/** Check if the backend server is reachable. */
+export async function checkBackendConnectivity(endpoint: string): Promise<ValidationResult> {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/health`;
+    const res = await fetch(url);
+    if (res.ok) {
+      return {
+        name: "Backend connectivity",
+        passed: true,
+        message: `Server reachable at ${endpoint}`,
+      };
+    }
+    return {
+      name: "Backend connectivity",
+      passed: false,
+      message: `Server returned ${res.status}`,
+      detail: "Check that the server is running.",
+    };
+  } catch (err) {
+    return {
+      name: "Backend connectivity",
+      passed: false,
+      message: "Server unreachable",
+      detail: (err as Error).message,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Space Access
+// ---------------------------------------------------------------------------
+
+/** Role hierarchy for write-permission checks. */
+const WRITE_ROLES = new Set(["owner", "admin"]);
+
+/** Check if the user has access to a specific space and has write permission. */
+export async function checkSpaceAccess(
+  endpoint: string,
+  spaceId: string,
+  token: string,
+  checkWrite?: boolean,
+): Promise<ValidationResult> {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/v1/auth/spaces`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (res.ok) {
+      const body = (await res.json()) as {
+        data?: Array<{ attributes?: { space_id?: string; role?: string } }>;
+      };
+      const space = body.data?.find((d) => d.attributes?.space_id === spaceId);
+      if (space) {
+        const role = space.attributes!.role ?? "guest";
+        if (checkWrite && !WRITE_ROLES.has(role)) {
+          return {
+            name: `Space access (${spaceId})`,
+            passed: false,
+            message: `Access granted (role: ${role}) but no write permission`,
+            detail: `Role "${role}" is read-only. Need owner or admin to sync. Ask the space owner to upgrade your role.`,
+          };
+        }
+        return {
+          name: `Space access (${spaceId})`,
+          passed: true,
+          message: `Access granted (role: ${role})${checkWrite ? " — write permission OK" : ""}`,
+        };
+      }
+      return {
+        name: `Space access (${spaceId})`,
+        passed: false,
+        message: "No access to this space",
+        detail: "Ask the space owner to invite you.",
+      };
+    }
+
+    return {
+      name: `Space access (${spaceId})`,
+      passed: false,
+      message: `Server returned ${res.status}`,
+    };
+  } catch (err) {
+    return {
+      name: `Space access (${spaceId})`,
+      passed: false,
+      message: "Cannot check — server unreachable",
+      detail: (err as Error).message,
+    };
+  }
+}

package/lib/config.ts

@@ -0,0 +1,61 @@
+/** Configuration for the llmkb plugin.
+
+Configuration is resolved in priority order:
+1. ``.llmkb/config.yml`` — project-level settings
+2. Environment variables — CI/headless override
+3. Built-in defaults
+
+Call ``getConfig()`` on startup — it is synchronous for env-only,
+but also provides ``resolveEndpoint()`` for config-file-aware resolution.
+*/
+
+import { env } from "node:process";
+
+/** Resolved plugin configuration. */
+export interface PluginConfig {
+  /** llmkb API endpoint (default ``http://localhost:8000``). */
+  endpoint: string;
+}
+
+const DEFAULT_ENDPOINT = "http://localhost:8000";
+
+/** Read configuration from environment variables.
+ *
+ * For config-file-aware resolution (reading ``llmkb_base_url`` from
+ * ``.llmkb/config.yml``), use ``resolveEndpoint()`` or the `doctor`
+ * command instead.
+ */
+export function getConfig(): PluginConfig {
+  return {
+    endpoint: env["LLMKB_ENDPOINT"] ?? DEFAULT_ENDPOINT,
+  };
+}
+
+/**
+ * Resolve the API endpoint with config-file awareness.
+ *
+ * Priority: ``.llmkb/config.yml`` → ``LLMKB_ENDPOINT`` env → default.
+ *
+ * This is async because it reads the config file from disk.
+ * CLI commands that are called once per session (login, sync, query)
+ * should use this instead of ``getConfig()``.
+ */
+export async function resolveEndpoint(): Promise<string> {
+  const envEndpoint = env["LLMKB_ENDPOINT"];
+  if (envEndpoint) return envEndpoint;
+
+  try {
+    const { findProjectRoot, readPluginConfig } = await import("./parser.js");
+    const root = findProjectRoot();
+    if (root) {
+      const pluginCfg = await readPluginConfig(root);
+      if (pluginCfg?.llmkb_base_url) {
+        return pluginCfg.llmkb_base_url;
+      }
+    }
+  } catch {
+    // ignore — fall back to default
+  }
+
+  return DEFAULT_ENDPOINT;
+}

package/lib/credentials.ts

@@ -0,0 +1,164 @@
+/** OS keychain integration with environment-variable fallback for access_token.
+
+Tokens are resolved in a 2-step chain:
+1. ``LLMKB_ACCESS_TOKEN`` env var
+2. OS keychain: ``llmkb/user/access_token``
+3. Error
+
+Never writes tokens to config files or checked-in files.
+*/
+
+import { env } from "node:process";
+
+// ---------------------------------------------------------------------------
+// Keychain integration (lazy-loaded)
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let kcGetPassword: any | null = null;
+let kcSetPassword: any | null = null;
+let kcDeletePassword: any | null = null;
+let keychainAvailable = false;
+
+async function ensureKeychain(): Promise<boolean> {
+  if (keychainAvailable) return true;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod: any = await import("keychain");
+    const kc = mod.default ?? mod;
+    if (typeof kc.setPassword === "function") {
+      kcGetPassword = kc.getPassword.bind(kc);
+      kcSetPassword = kc.setPassword.bind(kc);
+      kcDeletePassword = kc.deletePassword.bind(kc);
+      keychainAvailable = true;
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Credential Store interface
+// ---------------------------------------------------------------------------
+
+export interface CredentialStore {
+  getToken(): Promise<string | null>;
+  setToken(token: string): Promise<void>;
+  deleteToken(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// 2-Step Token Resolution
+//
+// 1. LLMKB_ACCESS_TOKEN env var
+// 2. OS keychain llmkb/user/access_token
+// 3. Error
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the user's access token.
+ *
+ * Tries environment variable first (CI/headless), then OS keychain.
+ */
+export async function getToken(): Promise<string | null> {
+  // Step 1: LLMKB_ACCESS_TOKEN env var
+  const envVal = env["LLMKB_ACCESS_TOKEN"];
+  if (envVal) return envVal;
+
+  // Step 2: OS keychain
+  const kcToken = await keychainGet();
+  if (kcToken) return kcToken;
+
+  return null;
+}
+
+/**
+ * Resolve an access token, throwing a descriptive error if not found.
+ * Convenience wrapper around ``getToken`` for call sites that expect a
+ * mandatory token.
+ */
+export async function requireToken(): Promise<string> {
+  const token = await getToken();
+  if (!token) {
+    throw new Error(
+      "No access token found. Set LLMKB_ACCESS_TOKEN env var or run `llmkb login --project-space <id>`.",
+    );
+  }
+  return token;
+}
+
+// ---------------------------------------------------------------------------
+// Keychain primitives
+// ---------------------------------------------------------------------------
+
+async function keychainGet(): Promise<string | null> {
+  const available = await ensureKeychain();
+  if (!available) return null;
+
+  return new Promise<string | null>((resolve) => {
+    try {
+      kcGetPassword(
+        { service: "llmkb", account: "user/access_token" },
+        (err: Error | null, password: string | null) => {
+          if (err) resolve(null);
+          else resolve(password);
+        },
+      );
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Token storage (keychain write)
+// ---------------------------------------------------------------------------
+
+/**
+ * Store an access token in the OS keychain.
+ *
+ * @throws If the keychain is unavailable (no fallback for writes — env vars
+ *   are read-only).
+ */
+export async function setToken(token: string): Promise<void> {
+  const available = await ensureKeychain();
+  if (!available) {
+    throw new Error(
+      "Keychain is not available. Set LLMKB_ACCESS_TOKEN env var instead.",
+    );
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    kcSetPassword(
+      {
+        service: "llmkb",
+        account: "user/access_token",
+        password: token,
+      },
+      (err: Error | null) => {
+        if (err) reject(err);
+        else resolve();
+      },
+    );
+  });
+}
+
+/**
+ * Remove the access token from the OS keychain.
+ */
+export async function deleteToken(): Promise<void> {
+  const available = await ensureKeychain();
+  if (!available) return;
+
+  return new Promise<void>((resolve, reject) => {
+    kcDeletePassword(
+      { service: "llmkb", account: "user/access_token" },
+      (err: Error | null) => {
+        if (err) reject(err);
+        else resolve();
+      },
+    );
+  });
+}