@codewithjuber/forgekit 0.8.0

package/src/providers.js

@@ -0,0 +1,320 @@
+// forge providers — multi-provider model configuration. Supports Anthropic (default),
+// OpenRouter, and custom API endpoints. Config lives in .forge/providers.json; defaults
+// are hardcoded so the system works with zero config. Never stores API keys — only env
+// var names (the key is resolved at runtime from the environment).
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { MODELS } from "./model_tiers.js";
+
+const PROVIDERS_FILE = "providers.json";
+const PROVIDERS_DIR = ".forge";
+
+const ANTHROPIC_DEFAULT_URL = "https://api.anthropic.com";
+
+function providersPath(root) {
+  return join(root, PROVIDERS_DIR, PROVIDERS_FILE);
+}
+
+const BUILTIN_PROVIDERS = {
+  anthropic: {
+    type: "anthropic",
+    label: "Anthropic (direct)",
+    baseUrl: "https://api.anthropic.com",
+    envKey: "ANTHROPIC_API_KEY",
+    models: Object.fromEntries(Object.entries(MODELS).map(([key, m]) => [key, m.id])),
+  },
+  openrouter: {
+    type: "openrouter",
+    label: "OpenRouter",
+    baseUrl: "https://openrouter.ai/api/v1",
+    envKey: "OPENROUTER_API_KEY",
+    models: Object.fromEntries(
+      Object.entries(MODELS).map(([key, m]) => [key, `anthropic/${m.id}`]),
+    ),
+  },
+  litellm: {
+    type: "litellm",
+    label: "LiteLLM Gateway",
+    baseUrl: "http://localhost:4000",
+    envKey: "ANTHROPIC_API_KEY",
+    models: {
+      haiku: "forge-simple",
+      sonnet: "forge-medium",
+      opus: "forge-complex",
+      fable: "forge-complex",
+    },
+  },
+};
+
+function defaults() {
+  return {
+    active: "anthropic",
+    providers: { ...BUILTIN_PROVIDERS },
+  };
+}
+
+/** Load providers config, falling back to built-in defaults. */
+export function loadProviders(root = process.cwd()) {
+  const path = providersPath(root);
+  if (!existsSync(path)) return defaults();
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    const merged = defaults();
+    if (data.active) merged.active = data.active;
+    if (data.providers) {
+      for (const [name, cfg] of Object.entries(data.providers)) {
+        merged.providers[name] = { ...merged.providers[name], ...cfg };
+      }
+    }
+    return merged;
+  } catch {
+    return defaults();
+  }
+}
+
+/** Write providers config. */
+function saveProviders(root, config) {
+  const dir = join(root, PROVIDERS_DIR);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(providersPath(root), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+/** The active provider config. Explicit .forge/providers.json wins; otherwise auto-detects from env. */
+export function activeProvider(root = process.cwd()) {
+  if (existsSync(providersPath(root))) {
+    const config = loadProviders(root);
+    const name = config.active;
+    const provider = config.providers[name];
+    if (provider) return { name, ...provider };
+  }
+
+  const detected = autoDetectProvider();
+  if (detected) {
+    const { source, ...rest } = detected;
+    return { ...rest, _autoDetected: true, _source: source };
+  }
+
+  return { name: "anthropic", ...BUILTIN_PROVIDERS.anthropic };
+}
+
+/** Resolve a tier key (haiku/sonnet/opus/fable) to the active provider's model ID. */
+export function resolveModel(root, tierKey) {
+  const provider = activeProvider(root);
+  return provider.models?.[tierKey] ?? MODELS[tierKey]?.id ?? null;
+}
+
+/** Switch the active provider. Returns the new active config. */
+export function setProvider(root, name) {
+  const config = loadProviders(root);
+  if (!config.providers[name]) {
+    return {
+      ok: false,
+      reason: `unknown provider "${name}" — add it first with forge config provider add`,
+    };
+  }
+  config.active = name;
+  saveProviders(root, config);
+  return { ok: true, name, provider: config.providers[name] };
+}
+
+/**
+ * Register a custom provider.
+ * @param {string} root
+ * @param {string} name
+ * @param {{type?: string, label?: string, baseUrl?: string, envKey?: string, models?: Record<string,string>}} cfg
+ */
+export function addProvider(root, name, cfg) {
+  if (!name || !cfg.baseUrl) {
+    return { ok: false, reason: "name and --base-url are required" };
+  }
+  const config = loadProviders(root);
+  config.providers[name] = {
+    type: cfg.type || "custom",
+    label: cfg.label || name,
+    baseUrl: cfg.baseUrl,
+    envKey: cfg.envKey || "",
+    models: cfg.models || Object.fromEntries(Object.entries(MODELS).map(([key, m]) => [key, m.id])),
+  };
+  saveProviders(root, config);
+  return { ok: true, name, provider: config.providers[name] };
+}
+
+/** List all configured providers. */
+export function listProviders(root = process.cwd()) {
+  const config = loadProviders(root);
+  return Object.entries(config.providers).map(([name, p]) => ({
+    name,
+    active: name === config.active,
+    type: p.type,
+    label: p.label || name,
+    baseUrl: p.baseUrl,
+    envKey: p.envKey,
+    hasKey: p.envKey ? Boolean(process.env[p.envKey]) : false,
+  }));
+}
+
+/**
+ * Auto-detect the best provider from environment variables.
+ * Pure read — never writes config. Returns null if nothing detected.
+ */
+export function autoDetectProvider() {
+  const litellmUrl = (process.env.LITELLM_BASE_URL || "").replace(/\/+$/, "");
+  if (litellmUrl) {
+    return {
+      name: "litellm",
+      type: "litellm",
+      label: "LiteLLM Gateway (hosted)",
+      baseUrl: litellmUrl,
+      envKey: process.env.LITELLM_API_KEY ? "LITELLM_API_KEY" : "ANTHROPIC_API_KEY",
+      models: Object.fromEntries(Object.entries(MODELS).map(([key, m]) => [key, m.id])),
+      source: "LITELLM_BASE_URL",
+    };
+  }
+
+  const baseUrl = (process.env.ANTHROPIC_BASE_URL || "").replace(/\/+$/, "");
+  if (baseUrl && baseUrl.toLowerCase() !== ANTHROPIC_DEFAULT_URL) {
+    return {
+      name: "anthropic-proxy",
+      type: "anthropic",
+      label: "Anthropic (via proxy)",
+      baseUrl,
+      envKey: "ANTHROPIC_API_KEY",
+      models: Object.fromEntries(Object.entries(MODELS).map(([key, m]) => [key, m.id])),
+      source: "ANTHROPIC_BASE_URL",
+    };
+  }
+
+  if (process.env.OPENROUTER_API_KEY) {
+    return { name: "openrouter", ...BUILTIN_PROVIDERS.openrouter, source: "OPENROUTER_API_KEY" };
+  }
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    return { name: "anthropic", ...BUILTIN_PROVIDERS.anthropic, source: "ANTHROPIC_API_KEY" };
+  }
+
+  return null;
+}
+
+/** List all providers that could be auto-detected from the current environment. */
+export function listDetectedProviders() {
+  const detected = [];
+  const litellmUrl = (process.env.LITELLM_BASE_URL || "").replace(/\/+$/, "");
+  if (litellmUrl) {
+    detected.push({
+      name: "litellm",
+      type: "litellm",
+      label: "LiteLLM Gateway (hosted)",
+      source: "LITELLM_BASE_URL",
+      available: true,
+    });
+  }
+  const baseUrl = (process.env.ANTHROPIC_BASE_URL || "").replace(/\/+$/, "");
+  if (baseUrl && baseUrl.toLowerCase() !== ANTHROPIC_DEFAULT_URL) {
+    detected.push({
+      name: "anthropic-proxy",
+      type: "anthropic",
+      label: "Anthropic (via proxy)",
+      source: "ANTHROPIC_BASE_URL",
+      available: true,
+    });
+  }
+  if (process.env.OPENROUTER_API_KEY) {
+    detected.push({
+      name: "openrouter",
+      type: "openrouter",
+      label: "OpenRouter",
+      source: "OPENROUTER_API_KEY",
+      available: true,
+    });
+  }
+  if (process.env.ANTHROPIC_API_KEY) {
+    detected.push({
+      name: "anthropic",
+      type: "anthropic",
+      label: "Anthropic (direct)",
+      source: "ANTHROPIC_API_KEY",
+      available: true,
+    });
+  }
+  return detected;
+}
+
+/** Check provider health: env key set, gateway reachable (litellm), base URL valid. */
+export function providerStatus(root = process.cwd()) {
+  const prov = activeProvider(root);
+  const checks = [];
+
+  if (prov._autoDetected) {
+    checks.push({
+      id: "auto-detect",
+      ok: true,
+      detail: `Auto-detected from ${prov._source}`,
+    });
+  }
+
+  if (prov.envKey) {
+    checks.push({
+      id: "api-key",
+      ok: Boolean(process.env[prov.envKey]),
+      detail: process.env[prov.envKey]
+        ? `${prov.envKey} is set`
+        : `${prov.envKey} is NOT set — get it from the Anthropic Console (console.anthropic.com/settings/keys) or your provider's dashboard`,
+    });
+  }
+  if (prov.type === "litellm") {
+    let reachable = false;
+    try {
+      const out = execFileSync(
+        "curl",
+        ["-sf", "-o", "/dev/null", "-w", "%{http_code}", `${prov.baseUrl}/health`],
+        { encoding: "utf8", timeout: 5000 },
+      );
+      reachable = out.startsWith("2");
+    } catch {}
+    checks.push({
+      id: "gateway",
+      ok: reachable,
+      detail: reachable
+        ? `LiteLLM gateway reachable at ${prov.baseUrl}`
+        : `LiteLLM gateway NOT reachable at ${prov.baseUrl}`,
+    });
+  }
+
+  const envScan = [
+    { key: "LITELLM_BASE_URL", set: Boolean(process.env.LITELLM_BASE_URL) },
+    { key: "LITELLM_API_KEY", set: Boolean(process.env.LITELLM_API_KEY) },
+    { key: "ANTHROPIC_BASE_URL", set: Boolean(process.env.ANTHROPIC_BASE_URL) },
+    { key: "OPENROUTER_API_KEY", set: Boolean(process.env.OPENROUTER_API_KEY) },
+    { key: "ANTHROPIC_API_KEY", set: Boolean(process.env.ANTHROPIC_API_KEY) },
+  ];
+
+  return {
+    provider: prov.name,
+    type: prov.type,
+    autoDetected: Boolean(prov._autoDetected),
+    source: prov._source || null,
+    checks,
+    envScan,
+  };
+}
+
+/**
+ * Apply a routed model recommendation to ~/.claude/settings.json.
+ * @param {string} tierKey - the recommended tier (haiku/sonnet/opus/fable)
+ * @param {{settingsPath?: string}} [opts]
+ */
+export function applyRoute(tierKey, { settingsPath } = {}) {
+  const target = settingsPath || join(homedir(), ".claude", "settings.json");
+  let settings = {};
+  try {
+    settings = JSON.parse(readFileSync(target, "utf8"));
+  } catch {}
+  const modelId = MODELS[tierKey]?.id;
+  if (!modelId) return { ok: false, reason: `unknown tier "${tierKey}"` };
+  const prev = settings.model;
+  settings.model = tierKey;
+  writeFileSync(target, `${JSON.stringify(settings, null, 2)}\n`);
+  return { ok: true, model: tierKey, modelId, prev, path: target };
+}

package/src/recall.js

@@ -0,0 +1,103 @@
+// forge recall — file-based cross-session memory: one fact per file + a MEMORY.md
+// index. Refuses to persist secrets. Consolidation is deterministic (exact-dupe
+// prune) — honest: no model call, so it can't hallucinate a "merged" memory.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Secret-refusal now lives in the PCM ledger core (ledger.js) so NO claim kind can
+// persist a credential; re-exported here because recall is where callers historically
+// imported it from (lessons_store, guards, tests). See ledger.js for the precision
+// rationale (credential formats + key-assigned-to-value, never a bare English mention).
+import { SECRET_RE } from "./ledger.js";
+// The merged read helper (P2 read flip). Import cycle note: ledger_read → lessons_store
+// → recall is function-level only (no module-eval use on either side), so ESM resolves
+// it safely — same pattern as lessons_store's own SECRET_RE import from here.
+import { mergeFactSlugs } from "./ledger_read.js";
+
+export { SECRET_RE };
+
+export function defaultStore() {
+  return join(process.env.FORGE_HOME || join(homedir(), ".forge"), "recall");
+}
+
+const factsDir = (store) => join(store, "facts");
+
+import { slug as slugify } from "./util.js";
+
+export function add(store, name, body) {
+  if (SECRET_RE.test(`${name}\n${body}`)) {
+    return {
+      ok: false,
+      reason: "refused: looks like a secret/credential — store a pointer, not the value",
+    };
+  }
+  const dir = factsDir(store);
+  mkdirSync(dir, { recursive: true });
+  const slug = slugify(name) || "fact";
+  writeFileSync(join(dir, `${slug}.md`), `# ${name}\n\n${body.trim()}\n`);
+  reindex(store);
+  return { ok: true, slug };
+}
+
+/** Parse one stored fact back into {name, text} — THE parser for the fact format
+ *  (`# name\n\ntext`), CRLF-tolerant so a Windows checkout can't fork the format.
+ *  Everything that reads fact files (bridge import, consolidation) must use this. */
+export function readFact(store, slug) {
+  const path = join(factsDir(store), `${slug}.md`);
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+  const m = raw.match(/^# (.*)\n\n([\s\S]*)$/);
+  return m ? { name: m[1].trim(), text: m[2].trim() } : { name: slug, text: raw.trim() };
+}
+
+/** File-backed fact slugs ONLY — the store the write path (add/consolidate) manages.
+ *  The ledger bridge reconciles against THIS list: a merged teammate fact has no file,
+ *  and treating it as "deleted from the store" would tombstone it away. */
+export function listStored(store) {
+  const dir = factsDir(store);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => f.replace(/\.md$/, ""))
+    .sort();
+}
+
+/** The read view (P2 read flip): file facts ∪ live facts from the personal ledger this
+ *  store shadows into (`<store>/ledger` — see `forge recall add`). A file wins on slug
+ *  collision (the file is the canonical local value). */
+export function list(store) {
+  return mergeFactSlugs(listStored(store), join(store, "ledger"));
+}
+
+export function reindex(store) {
+  const items = list(store);
+  mkdirSync(store, { recursive: true });
+  writeFileSync(
+    join(store, "MEMORY.md"),
+    ["# Durable memory index", "", ...items.map((s) => `- ${s}`), ""].join("\n"),
+  );
+  return items.length;
+}
+
+export function consolidate(store) {
+  const dir = factsDir(store);
+  if (!existsSync(dir)) return { removed: 0, kept: 0 };
+  const seen = new Map();
+  let removed = 0;
+  for (const file of readdirSync(dir)
+    .filter((f) => f.endsWith(".md"))
+    .sort()) {
+    // Dedupe on the fact BODY (after the "# title" line), so two facts with
+    // different names but identical content collapse to one.
+    const raw = readFileSync(join(dir, file), "utf8");
+    const sep = raw.indexOf("\n\n");
+    const key = (sep >= 0 ? raw.slice(sep + 2) : raw).replace(/\s+/g, " ").trim();
+    if (seen.has(key)) {
+      rmSync(join(dir, file));
+      removed += 1;
+    } else seen.set(key, file);
+  }
+  reindex(store);
+  return { removed, kept: seen.size };
+}