@almightygpt/core 0.7.1 → 0.8.0

package/src/adapters/openai.ts

@@ -14,6 +14,7 @@
 
 import OpenAI from "openai";
 import { AdapterError, type Adapter, type AdapterInput, type AdapterOutput } from "./types.js";
+import { resolveApiKey } from "../auth/resolver.js";
 
 /** USD per 1M tokens, by model. Lowercased keys. */
 const PRICING_USD_PER_1M: Record<string, { input: number; output: number }> = {
@@ -42,7 +43,10 @@ export class OpenAIAdapter implements Adapter {
   readonly name: string;
   readonly provider = "openai";
 
-  private readonly client: OpenAI | null;
+  private client: OpenAI | null = null;
+  private resolved = false;
+  private readonly explicitApiKey: string | undefined;
+  private readonly organization: string | undefined;
   readonly defaultModel: string;
   private readonly defaultMaxOutputTokens: number;
   private readonly defaultTimeoutMs: number;
@@ -55,27 +59,34 @@ export class OpenAIAdapter implements Adapter {
     this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
     this.defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? 4096;
     this.defaultTimeoutMs = options.defaultTimeoutMs ?? 120_000;
+    this.explicitApiKey = options.apiKey;
+    this.organization = options.organization;
+  }
 
-    const apiKey = options.apiKey ?? process.env["OPENAI_API_KEY"];
-    if (apiKey && apiKey.length > 0) {
-      this.client = new OpenAI({
-        apiKey,
-        ...(options.organization ? { organization: options.organization } : {}),
-      });
-    } else {
-      this.client = null;
-    }
+  /** Lazily resolve via the unified resolver: explicit → env → keychain. */
+  private async ensureClient(): Promise<OpenAI | null> {
+    if (this.resolved) return this.client;
+    this.resolved = true;
+    const opts = this.explicitApiKey ? { explicit: this.explicitApiKey } : {};
+    const result = await resolveApiKey("openai", opts);
+    if (result.source === "missing") return null;
+    this.client = new OpenAI({
+      apiKey: result.key!,
+      ...(this.organization ? { organization: this.organization } : {}),
+    });
+    return this.client;
   }
 
   async isAvailable(): Promise<boolean> {
-    return this.client !== null;
+    return (await this.ensureClient()) !== null;
   }
 
   async execute(input: AdapterInput): Promise<AdapterOutput> {
-    if (!this.client) {
+    const client = await this.ensureClient();
+    if (!client) {
       throw new AdapterError(
-        "OPENAI_API_KEY is not set. Export it in your environment or pass it " +
-          "via the adapter constructor.",
+        'No OpenAI API key found. Run "almightygpt auth openai" ' +
+          "or export OPENAI_API_KEY in your environment.",
         this.name,
       );
     }
@@ -87,7 +98,7 @@ export class OpenAIAdapter implements Adapter {
     const start = Date.now();
     let response: OpenAI.Chat.Completions.ChatCompletion;
     try {
-      response = await this.client.chat.completions.create(
+      response = await client.chat.completions.create(
         {
           model,
           max_tokens: maxOutputTokens,

package/src/auth/keychain.ts

@@ -0,0 +1,132 @@
+/**
+ * OS keychain wrapper — @napi-rs/keyring loaded via DYNAMIC IMPORT.
+ *
+ * The native binary is an OPTIONAL runtime capability:
+ *   - If @napi-rs/keyring is installed and loads → real keychain access
+ *     (macOS Keychain, Windows Credential Manager, Linux Secret Service).
+ *   - If it's NOT installed (optionalDependencies skipped on exotic OS,
+ *     or just plain missing) → returns an unavailable shim. Resolver
+ *     falls through to env vars without crashing.
+ *
+ * This pattern means `npm install almightygpt` NEVER blocks on keychain
+ * binary failure. Codex's review explicitly flagged this as the
+ * correct strategy.
+ *
+ * Service name: `almightygpt` (consistent across all platforms; what
+ * users see in macOS Keychain Access.app, Windows credential UI, etc.)
+ */
+
+import type { ProviderId } from "./types.js";
+
+const KEYCHAIN_SERVICE = "almightygpt";
+
+export interface KeychainAdapter {
+  available: boolean;
+  get(provider: ProviderId): Promise<string | undefined>;
+  set(provider: ProviderId, key: string): Promise<void>;
+  remove(provider: ProviderId): Promise<boolean>;
+  /** Optional diagnostic — backend name, or "unavailable". */
+  describeBackend(): string;
+}
+
+/**
+ * Lazy-loaded singleton. We never throw on import failure; instead the
+ * resulting adapter reports `available: false` and the resolver knows
+ * to skip it.
+ */
+let cached: KeychainAdapter | null = null;
+
+export async function getKeychain(): Promise<KeychainAdapter> {
+  if (cached) return cached;
+  cached = await loadKeychain();
+  return cached;
+}
+
+async function loadKeychain(): Promise<KeychainAdapter> {
+  try {
+    // Dynamic import — never crashes the module if the package is
+    // missing or its native binary fails to load on the host.
+    const mod = (await import("@napi-rs/keyring")) as {
+      Entry: new (service: string, account: string) => {
+        getPassword(): string | null;
+        setPassword(password: string): void;
+        deletePassword(): boolean;
+      };
+    };
+
+    const entryFor = (provider: ProviderId) =>
+      new mod.Entry(KEYCHAIN_SERVICE, provider);
+
+    // Probe: try to construct an Entry. If the native binding throws
+    // (no Secret Service daemon on Linux, etc.), we degrade.
+    try {
+      entryFor("openai");
+    } catch {
+      return makeUnavailable("native binding failed to initialize");
+    }
+
+    return {
+      available: true,
+      describeBackend: () => detectBackend(),
+      async get(provider) {
+        try {
+          const v = entryFor(provider).getPassword();
+          return v === null ? undefined : v;
+        } catch {
+          return undefined;
+        }
+      },
+      async set(provider, key) {
+        entryFor(provider).setPassword(key);
+      },
+      async remove(provider) {
+        try {
+          return entryFor(provider).deletePassword();
+        } catch {
+          return false;
+        }
+      },
+    };
+  } catch (err) {
+    return makeUnavailable(
+      err instanceof Error ? err.message : "import failed",
+    );
+  }
+}
+
+function makeUnavailable(reason: string): KeychainAdapter {
+  return {
+    available: false,
+    describeBackend: () => `unavailable (${reason})`,
+    async get() {
+      return undefined;
+    },
+    async set() {
+      throw new Error(
+        `Keychain unavailable: ${reason}. Set the API key via an environment ` +
+          `variable instead (e.g. ANTHROPIC_API_KEY).`,
+      );
+    },
+    async remove() {
+      return false;
+    },
+  };
+}
+
+function detectBackend(): string {
+  switch (process.platform) {
+    case "darwin":
+      return "macos-keychain";
+    case "win32":
+      return "windows-credential-manager";
+    case "linux":
+      return "linux-secret-service";
+    default:
+      return process.platform;
+  }
+}
+
+/** Exposed for tests that want to reset the singleton between cases. */
+export function _resetKeychainCache(): void {
+  cached = null;
+}

package/src/auth/resolver.ts

@@ -0,0 +1,81 @@
+/**
+ * API key resolver — the single entry point every adapter must call
+ * to find its key. Replaces direct `process.env[...]` reads.
+ *
+ * Priority order (top to bottom):
+ *   1. Explicit parameter (caller passed a key — tests, extension handoff)
+ *   2. Environment variable (per-process override; wins over keychain)
+ *   3. OS keychain (persistent convenience; optional capability)
+ *   4. Missing → throw AuthMissingError
+ *
+ * Env wins over keychain by design — see types.ts header for the
+ * bug-class reasoning that drove the decision.
+ */
+
+import { getKeychain } from "./keychain.js";
+import {
+  AuthMissingError,
+  PROVIDER_ENV_VARS,
+  type KeyResolution,
+  type ProviderId,
+} from "./types.js";
+
+export interface ResolveOptions {
+  /** Optional caller-supplied key — wins over all other sources. */
+  explicit?: string;
+  /** Skip keychain lookup entirely (used by tests). */
+  skipKeychain?: boolean;
+}
+
+/**
+ * Resolve where the API key for `provider` lives.
+ * Returns a KeyResolution describing the source even when not found
+ * (caller can decide whether to throw).
+ */
+export async function resolveApiKey(
+  provider: ProviderId,
+  options: ResolveOptions = {},
+): Promise<KeyResolution> {
+  // 1. Explicit override
+  if (options.explicit) {
+    return { provider, source: "explicit", key: options.explicit };
+  }
+
+  // 2. Environment variable
+  for (const envVar of PROVIDER_ENV_VARS[provider]) {
+    const v = process.env[envVar];
+    if (v && v.length > 0) {
+      return { provider, source: "env", key: v, envVar };
+    }
+  }
+
+  // 3. OS keychain (optional)
+  if (!options.skipKeychain) {
+    const keychain = await getKeychain();
+    if (keychain.available) {
+      const v = await keychain.get(provider);
+      if (v && v.length > 0) {
+        return { provider, source: "keychain", key: v };
+      }
+    }
+  }
+
+  // 4. Missing
+  return { provider, source: "missing" };
+}
+
+/**
+ * Convenience wrapper that throws AuthMissingError on absence — for
+ * callers (adapters) that need the key or can't proceed.
+ */
+export async function requireApiKey(
+  provider: ProviderId,
+  options: ResolveOptions = {},
+): Promise<string> {
+  const resolved = await resolveApiKey(provider, options);
+  if (resolved.source === "missing") {
+    const primaryEnv = PROVIDER_ENV_VARS[provider][0]!;
+    throw new AuthMissingError(provider, primaryEnv);
+  }
+  return resolved.key!;
+}

package/src/auth/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Auth subsystem types — provider identifiers, resolution sources,
+ * error classes.
+ *
+ * The auth module's job is to answer one question per call:
+ * "where is the API key for <provider>, and what is it?"
+ *
+ * Resolution priority (top to bottom):
+ *   1. Explicit parameter (passed by caller — tests, extension handoff)
+ *   2. Environment variable (per-process override; wins over keychain)
+ *   3. OS keychain (persistent convenience; @napi-rs/keyring optional)
+ *   4. Missing -> throw AuthMissingError
+ *
+ * Env-wins-over-keychain is intentional. The original draft had the
+ * order flipped; Codex's independent review caught that it would
+ * silently override the VS Code extension's freshly-stored key with
+ * a stale keychain copy. See docs/claude/v0.8-auth-plan.md.
+ */
+
+export type ProviderId = "openai" | "anthropic" | "google";
+
+export type KeySource = "explicit" | "env" | "keychain" | "missing";
+
+export interface KeyResolution {
+  provider: ProviderId;
+  source: KeySource;
+  /** Present iff source !== "missing". */
+  key?: string;
+  /** Which env var was used (only set when source === "env"). */
+  envVar?: string;
+}
+
+/**
+ * Thrown when no key is found in any source. Caller should surface
+ * the message verbatim — it tells the user exactly how to fix it.
+ */
+export class AuthMissingError extends Error {
+  readonly provider: ProviderId;
+  readonly envVar: string;
+  constructor(provider: ProviderId, envVar: string) {
+    super(
+      `No API key found for ${provider}. ` +
+        `Run "almightygpt auth ${provider}" to set one up interactively, ` +
+        `or export ${envVar} in your shell.`,
+    );
+    this.name = "AuthMissingError";
+    this.provider = provider;
+    this.envVar = envVar;
+  }
+}
+
+/** Maps each provider to the canonical env var name(s) we read. */
+export const PROVIDER_ENV_VARS: Record<ProviderId, readonly string[]> = {
+  openai: ["OPENAI_API_KEY"],
+  anthropic: ["ANTHROPIC_API_KEY"],
+  // Google's SDK historically accepted both names; honor both.
+  google: ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+};
+
+/**
+ * Browser-launchable URL where a user creates / manages keys for each
+ * provider. Used by the `almightygpt auth <provider>` flow.
+ */
+export const PROVIDER_KEY_URLS: Record<ProviderId, string> = {
+  openai: "https://platform.openai.com/api-keys",
+  anthropic: "https://console.anthropic.com/settings/keys",
+  google: "https://aistudio.google.com/apikey",
+};

package/src/auth/validator.ts

@@ -0,0 +1,145 @@
+/**
+ * Model-level key validation.
+ *
+ * Codex's review caught that listing models (e.g. `GET /v1/models`) can
+ * succeed when the key lacks model permission, has quota issues, or
+ * has billing-state problems. The user doesn't care that list-models
+ * works — they care that AlmightyGPT can run the configured review
+ * model.
+ *
+ * So we validate with the same operation class real reviews use:
+ *   - OpenAI:    tiny chat completion against gpt-4o
+ *   - Anthropic: tiny messages call against claude-sonnet-4-6
+ *   - Google:    tiny generateContent call against gemini-2.5-flash
+ *
+ * Cost is fractions of a cent per call. Latency is ~1-3 seconds.
+ * Failure surfaces the provider's exact error message so the user
+ * can fix it.
+ */
+
+import type { ProviderId } from "./types.js";
+
+export interface ValidationResult {
+  ok: boolean;
+  /** Provider-reported model used (e.g. "gpt-4o-2024-08-06"). */
+  model?: string;
+  /** Provider's error message verbatim if ok === false. */
+  error?: string;
+}
+
+const DEFAULT_VALIDATION_MODELS: Record<ProviderId, string> = {
+  openai: "gpt-4o",
+  anthropic: "claude-sonnet-4-6",
+  google: "gemini-2.5-flash",
+};
+
+const VALIDATION_TIMEOUT_MS = 15_000;
+
+/**
+ * Validate that a key can actually invoke the model real reviews use.
+ * Returns a result object — never throws on validation failure (only
+ * on programmer errors like an unsupported provider).
+ */
+export async function validateKey(
+  provider: ProviderId,
+  key: string,
+): Promise<ValidationResult> {
+  try {
+    switch (provider) {
+      case "openai":
+        return await validateOpenAI(key);
+      case "anthropic":
+        return await validateAnthropic(key);
+      case "google":
+        return await validateGoogle(key);
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+async function validateOpenAI(key: string): Promise<ValidationResult> {
+  const model = DEFAULT_VALIDATION_MODELS.openai;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
+  try {
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: "hi" }],
+        max_tokens: 1,
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: await res.text().catch(() => res.statusText) };
+    }
+    const data = (await res.json()) as { model?: string };
+    return { ok: true, model: data.model ?? model };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function validateAnthropic(key: string): Promise<ValidationResult> {
+  const model = DEFAULT_VALIDATION_MODELS.anthropic;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
+  try {
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-api-key": key,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 5,
+        messages: [{ role: "user", content: "hi" }],
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: await res.text().catch(() => res.statusText) };
+    }
+    const data = (await res.json()) as { model?: string };
+    return { ok: true, model: data.model ?? model };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function validateGoogle(key: string): Promise<ValidationResult> {
+  const model = DEFAULT_VALIDATION_MODELS.google;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
+  try {
+    const url =
+      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=` +
+      encodeURIComponent(key);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: "hi" }] }],
+        generationConfig: { maxOutputTokens: 5 },
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: await res.text().catch(() => res.statusText) };
+    }
+    return { ok: true, model };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/index.ts

@@ -13,7 +13,7 @@
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
 
-export const VERSION = "0.7.1";
+export const VERSION = "0.8.0";
 
 // Git safety primitives
 export {
@@ -127,3 +127,24 @@ export type {
   ReviewEventHandler,
   AgentRoleInRun,
 } from "./review/events.js";
+
+// Auth subsystem (v0.8.0+) — resolver, keychain, validator
+export {
+  resolveApiKey,
+  requireApiKey,
+  type ResolveOptions,
+} from "./auth/resolver.js";
+export {
+  getKeychain,
+  _resetKeychainCache,
+  type KeychainAdapter,
+} from "./auth/keychain.js";
+export { validateKey, type ValidationResult } from "./auth/validator.js";
+export {
+  AuthMissingError,
+  PROVIDER_ENV_VARS,
+  PROVIDER_KEY_URLS,
+  type ProviderId,
+  type KeySource,
+  type KeyResolution,
+} from "./auth/types.js";

package/src/templates/install.ts

@@ -43,8 +43,32 @@ export interface InstallResult {
   skipped: { path: string; reason: string }[];
   /** Files that were backed up before being overwritten. */
   backedUp: { from: string; to: string }[];
+  /**
+   * Entries appended to the target repo's `.gitignore`. Empty if everything
+   * was already covered (e.g. user had `.almightygpt/` blanket-ignored, or
+   * had previously run init).
+   */
+  gitignoreAppended: string[];
+  /** Entries that were already present in `.gitignore` and didn't need adding. */
+  gitignoreAlreadyPresent: string[];
+  /** True if init created the `.gitignore` file (didn't exist). */
+  gitignoreCreated: boolean;
 }
 
+/**
+ * Entries appended to the host repo's `.gitignore`. The product's machine
+ * metadata (per-run outputs) must never land in git — but `.almightygpt/
+ * config.yaml` and `.almightygpt/rules.md` MUST. So we ignore the runs
+ * subfolder, not the whole `.almightygpt/` directory.
+ */
+const GITIGNORE_HEADER =
+  "# AlmightyGPT — machine-only run metadata (do not commit)";
+const GITIGNORE_ENTRIES = [
+  ".almightygpt/runs/",
+  ".almightygpt/credentials.yaml",
+  ".almightygpt/credentials.json",
+];
+
 const __filename = fileURLToPath(import.meta.url);
 // In dev (ts-node-esm) and in built form, the templates package lives at the
 // same monorepo root. Find it by walking up until we hit packages/templates.
@@ -162,7 +186,83 @@ export async function installTemplate(
     written.push(destRel);
   }
 
-  return { written, skipped, backedUp };
+  const gitignoreResult = await ensureGitignoreCovers(targetDir, dryRun);
+
+  return {
+    written,
+    skipped,
+    backedUp,
+    gitignoreAppended: gitignoreResult.added,
+    gitignoreAlreadyPresent: gitignoreResult.alreadyPresent,
+    gitignoreCreated: gitignoreResult.created,
+  };
+}
+
+/**
+ * Ensure the host repo's `.gitignore` covers `.almightygpt/runs/` and
+ * credential files. Creates `.gitignore` if it doesn't exist. Appends only
+ * the missing entries (idempotent — safe to call on every `init`).
+ *
+ * Returns a report so the CLI can show the user what changed.
+ */
+async function ensureGitignoreCovers(
+  targetDir: string,
+  dryRun: boolean,
+): Promise<{ added: string[]; alreadyPresent: string[]; created: boolean }> {
+  const gitignorePath = join(targetDir, ".gitignore");
+  let existing = "";
+  let created = false;
+  try {
+    existing = await readFile(gitignorePath, "utf-8");
+  } catch {
+    // File doesn't exist — we'll create it.
+    created = true;
+  }
+
+  const lines = new Set(
+    existing
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean),
+  );
+
+  // An entry is already covered if (a) it's literally there, (b) its
+  // no-trailing-slash form is there, or (c) the user has `.almightygpt/`
+  // or `.almightygpt` ignoring the whole folder.
+  const alreadyCovers = (entry: string): boolean => {
+    if (lines.has(entry)) return true;
+    if (lines.has(entry.replace(/\/$/, ""))) return true;
+    if (lines.has(".almightygpt/")) return true;
+    if (lines.has(".almightygpt")) return true;
+    return false;
+  };
+
+  const toAdd: string[] = [];
+  const alreadyPresent: string[] = [];
+  for (const entry of GITIGNORE_ENTRIES) {
+    if (alreadyCovers(entry)) alreadyPresent.push(entry);
+    else toAdd.push(entry);
+  }
+
+  if (toAdd.length === 0 || dryRun) {
+    return { added: toAdd, alreadyPresent, created: created && !dryRun };
+  }
+
+  const hasHeader = existing.includes(GITIGNORE_HEADER);
+  const headerLine = hasHeader ? "" : `${GITIGNORE_HEADER}\n`;
+  const block = headerLine + toAdd.join("\n") + "\n";
+
+  let newContent: string;
+  if (!existing) {
+    newContent = block;
+  } else if (existing.endsWith("\n")) {
+    newContent = existing + (existing.endsWith("\n\n") ? "" : "\n") + block;
+  } else {
+    newContent = existing + "\n\n" + block;
+  }
+
+  await writeFile(gitignorePath, newContent);
+  return { added: toAdd, alreadyPresent, created };
 }
 
 /**