@almightygpt/core 0.7.2 → 0.8.1

package/src/adapters/gemini.ts

@@ -29,6 +29,7 @@ import {
   type AdapterInput,
   type AdapterOutput,
 } from "./types.js";
+import { resolveApiKey } from "../auth/resolver.js";
 
 const PRICING_USD_PER_1M: Record<string, { input: number; output: number }> = {
   "gemini-2.5-pro": { input: 1.25, output: 10.0 },
@@ -58,7 +59,9 @@ export class GeminiAdapter implements Adapter {
   readonly name: string;
   readonly provider = "google";
 
-  private readonly client: GoogleGenerativeAI | null;
+  private client: GoogleGenerativeAI | null = null;
+  private resolved = false;
+  private readonly explicitApiKey: string | undefined;
   readonly defaultModel: string;
   private readonly defaultMaxOutputTokens: number;
   private readonly defaultTimeoutMs: number;
@@ -73,23 +76,30 @@ export class GeminiAdapter implements Adapter {
     // below to make sure the visible response gets the full budget.
     this.defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? 8192;
     this.defaultTimeoutMs = options.defaultTimeoutMs ?? 120_000;
+    this.explicitApiKey = options.apiKey;
+  }
 
-    const apiKey =
-      options.apiKey ??
-      process.env["GOOGLE_API_KEY"] ??
-      process.env["GEMINI_API_KEY"];
-    this.client = apiKey ? new GoogleGenerativeAI(apiKey) : null;
+  /** Lazily resolve via the unified resolver: explicit → env → keychain. */
+  private async ensureClient(): Promise<GoogleGenerativeAI | null> {
+    if (this.resolved) return this.client;
+    this.resolved = true;
+    const opts = this.explicitApiKey ? { explicit: this.explicitApiKey } : {};
+    const result = await resolveApiKey("google", opts);
+    if (result.source === "missing") return null;
+    this.client = new GoogleGenerativeAI(result.key!);
+    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(
-        "GOOGLE_API_KEY (or GEMINI_API_KEY) is not set. " +
-          "Export one in your environment.",
+        'No Google API key found. Run "almightygpt auth google" ' +
+          "or export GOOGLE_API_KEY (or GEMINI_API_KEY) in your environment.",
         this.name,
       );
     }
@@ -112,7 +122,7 @@ export class GeminiAdapter implements Adapter {
       generationConfig["responseMimeType"] = "application/json";
     }
 
-    const generative = this.client.getGenerativeModel({
+    const generative = client.getGenerativeModel({
       model,
       systemInstruction: input.systemPrompt,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any

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/config/schema.ts

@@ -24,6 +24,14 @@ export const ConfigSchema = z
   .object({
     version: z.literal(1),
     reviewsDir: z.string().min(1).default("docs/codex-reviews"),
+    /**
+     * Where `almightygpt precommit` writes its output. Separated from
+     * `reviewsDir` so quick-reviewer (typically Gemini Flash) output
+     * doesn't accumulate alongside deep cross-AI reviews. Falls back to
+     * `reviewsDir` if unset (preserves pre-v0.8.1 behavior for existing
+     * configs that don't have this field).
+     */
+    precommitDir: z.string().min(1).default("docs/precommit-reviews"),
     runsDir: z.string().min(1).default(".almightygpt/runs"),
     agents: z.record(z.string(), AgentConfigSchema).default({}),
     defaults: z

package/src/index.ts

@@ -13,7 +13,7 @@
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
 
-export const VERSION = "0.7.2";
+export const VERSION = "0.8.1";
 
 // 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/review/run-diff-review.ts

@@ -58,6 +58,12 @@ export interface DiffReviewOptions {
   range?: string;
   /** Bypass the git status safety check. */
   force?: boolean;
+  /**
+   * Override the output directory. Defaults to `config.reviewsDir`.
+   * Used by `almightygpt precommit` to write into `config.precommitDir`
+   * so quick reviews don't pile into the main `docs/codex-reviews/`.
+   */
+  reviewsDirOverride?: string;
 }
 
 export interface DiffReviewResult {
@@ -115,12 +121,14 @@ export async function runDiffReview(
     );
   }
 
+  const outputDir = opts.reviewsDirOverride ?? config.reviewsDir;
+
   // Preflight the review-file collision BEFORE any paid adapter call.
   // (Codex review v0.5: previously the check ran post-adapter, burning API
   // money on duplicate-topic runs that were going to fail anyway.)
   await preflightReviewFileCollision(
     opts.repoRoot,
-    config.reviewsDir,
+    outputDir,
     opts.topic,
     opts.force ?? false,
   );
@@ -250,7 +258,7 @@ export async function runDiffReview(
 
     const writeOpts: Parameters<typeof writeHumanReviewFile>[0] = {
       repoRoot: opts.repoRoot,
-      reviewsDir: config.reviewsDir,
+      reviewsDir: outputDir,
       topic: opts.topic,
       reviewerName,
       reviewerProvider: adapter.provider,