@almightygpt/core 0.7.2 → 0.8.0

package/dist/auth/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare class AuthMissingError extends Error {
+    readonly provider: ProviderId;
+    readonly envVar: string;
+    constructor(provider: ProviderId, envVar: string);
+}
+/** Maps each provider to the canonical env var name(s) we read. */
+export declare const PROVIDER_ENV_VARS: Record<ProviderId, readonly string[]>;
+/**
+ * Browser-launchable URL where a user creates / manages keys for each
+ * provider. Used by the `almightygpt auth <provider>` flow.
+ */
+export declare const PROVIDER_KEY_URLS: Record<ProviderId, string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE3D,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,UAAU,CAAC;IACrB,MAAM,EAAE,SAAS,CAAC;IAClB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM;CAUjD;AAED,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAKnE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAIxD,CAAC"}

package/dist/auth/types.js

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+/**
+ * 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 {
+    provider;
+    envVar;
+    constructor(provider, envVar) {
+        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 = {
+    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 = {
+    openai: "https://platform.openai.com/api-keys",
+    anthropic: "https://console.anthropic.com/settings/keys",
+    google: "https://aistudio.google.com/apikey",
+};
+//# sourceMappingURL=types.js.map

package/dist/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAeH;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,QAAQ,CAAa;IACrB,MAAM,CAAS;IACxB,YAAY,QAAoB,EAAE,MAAc;QAC9C,KAAK,CACH,wBAAwB,QAAQ,IAAI;YAClC,yBAAyB,QAAQ,iCAAiC;YAClE,aAAa,MAAM,iBAAiB,CACvC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAA0C;IACtE,MAAM,EAAE,CAAC,gBAAgB,CAAC;IAC1B,SAAS,EAAE,CAAC,mBAAmB,CAAC;IAChC,6DAA6D;IAC7D,MAAM,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC7C,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA+B;IAC3D,MAAM,EAAE,sCAAsC;IAC9C,SAAS,EAAE,6CAA6C;IACxD,MAAM,EAAE,oCAAoC;CAC7C,CAAC"}

package/dist/auth/validator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function validateKey(provider: ProviderId, key: string): Promise<ValidationResult>;
+//# sourceMappingURL=validator.d.ts.map

package/dist/auth/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/auth/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAUD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,UAAU,EACpB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,gBAAgB,CAAC,CAgB3B"}

package/dist/auth/validator.js

@@ -0,0 +1,130 @@
+/**
+ * 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.
+ */
+const DEFAULT_VALIDATION_MODELS = {
+    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, key) {
+    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) {
+    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());
+        return { ok: true, model: data.model ?? model };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function validateAnthropic(key) {
+    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());
+        return { ok: true, model: data.model ?? model };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function validateGoogle(key) {
+    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);
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/auth/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/auth/validator.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -12,7 +12,7 @@
  *   - review/     ✅ task #11 diff review pipeline (with #12/#13/#14 wiring)
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
-export declare const VERSION = "0.7.2";
+export declare const VERSION = "0.8.0";
 export { checkGitStatus, assertSafeToWrite, GitStatusDirtyError, type GitStatusCheck, } from "./git/status.js";
 export { installTemplate, hasExistingConfig, type InstallOptions, type InstallResult, } from "./templates/install.js";
 export { loadConfig, ConfigError } from "./config/load.js";
@@ -30,4 +30,8 @@ export { collectGitDiff, type DiffOptions, type DiffResult } from "./review/diff
 export { writeHumanReviewFile, ReviewFileExistsError, reviewFilePathFor, preflightReviewFileCollision, type WriteReviewFileOptions, } from "./review/write.js";
 export { BudgetTracker, BudgetExceededError, type BudgetCaps, } from "./review/budget.js";
 export type { ReviewEvent, ReviewEventHandler, AgentRoleInRun, } from "./review/events.js";
+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";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,OAAO,EACP,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,EACd,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,KAAK,MAAM,EACX,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,OAAO,EACP,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,EACd,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,GAC1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -12,7 +12,7 @@
  *   - review/     ✅ task #11 diff review pipeline (with #12/#13/#14 wiring)
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
-export const VERSION = "0.7.2";
+export const VERSION = "0.8.0";
 // Git safety primitives
 export { checkGitStatus, assertSafeToWrite, GitStatusDirtyError, } from "./git/status.js";
 // Template installer
@@ -35,4 +35,9 @@ export { runWorkerReviewerReview, } from "./review/run-worker-reviewer.js";
 export { collectGitDiff } from "./review/diff.js";
 export { writeHumanReviewFile, ReviewFileExistsError, reviewFilePathFor, preflightReviewFileCollision, } from "./review/write.js";
 export { BudgetTracker, BudgetExceededError, } from "./review/budget.js";
+// Auth subsystem (v0.8.0+) — resolver, keychain, validator
+export { resolveApiKey, requireApiKey, } from "./auth/resolver.js";
+export { getKeychain, _resetKeychainCache, } from "./auth/keychain.js";
+export { validateKey } from "./auth/validator.js";
+export { AuthMissingError, PROVIDER_ENV_VARS, PROVIDER_KEY_URLS, } from "./auth/types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,wBAAwB;AACxB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GAEpB,MAAM,iBAAiB,CAAC;AAEzB,qBAAqB;AACrB,OAAO,EACL,eAAe,EACf,iBAAiB,GAGlB,MAAM,wBAAwB,CAAC;AAEhC,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,GAGhB,MAAM,oBAAoB,CAAC;AAE5B,WAAW;AACX,OAAO,EACL,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,GAQd,MAAM,qBAAqB,CAAC;AAE7B,sBAAsB;AACtB,OAAO,EAAE,aAAa,EAA6C,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO;AACP,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,GAElB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,GAIf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,cAAc,GAGf,MAAM,kBAAkB,CAAC;AAE1B,kBAAkB;AAClB,OAAO,EACL,aAAa,GAGd,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,GAGxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAqC,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,GAE7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,mBAAmB,GAEpB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,wBAAwB;AACxB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,GAEpB,MAAM,iBAAiB,CAAC;AAEzB,qBAAqB;AACrB,OAAO,EACL,eAAe,EACf,iBAAiB,GAGlB,MAAM,wBAAwB,CAAC;AAEhC,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,GAGhB,MAAM,oBAAoB,CAAC;AAE5B,WAAW;AACX,OAAO,EACL,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,GAQd,MAAM,qBAAqB,CAAC;AAE7B,sBAAsB;AACtB,OAAO,EAAE,aAAa,EAA6C,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GAGrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO;AACP,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,iBAAiB,GAElB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,cAAc,GAIf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,cAAc,GAGf,MAAM,kBAAkB,CAAC;AAE1B,kBAAkB;AAClB,OAAO,EACL,aAAa,GAGd,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,GAGxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,cAAc,EAAqC,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,GAE7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,mBAAmB,GAEpB,MAAM,oBAAoB,CAAC;AAO5B,2DAA2D;AAC3D,OAAO,EACL,aAAa,EACb,aAAa,GAEd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,mBAAmB,GAEpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAyB,MAAM,qBAAqB,CAAC;AACzE,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAIlB,MAAM,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almightygpt/core",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Core orchestrator, adapters, config, runs, and review logic for AlmightyGPT",
   "license": "MIT",
   "type": "module",
@@ -31,5 +31,8 @@
     "p-limit": "^5.0.0",
     "yaml": "^2.4.0",
     "zod": "^3.23.0"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.1.6"
   }
 }

package/src/adapters/claude.ts

@@ -21,6 +21,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 }> = {
   // Claude 4.x family (current)
@@ -47,7 +48,9 @@ export class ClaudeAdapter implements Adapter {
   readonly name: string;
   readonly provider = "anthropic";
 
-  private readonly client: Anthropic | null;
+  private client: Anthropic | null = null;
+  private resolved = false;
+  private readonly explicitApiKey: string | undefined;
   readonly defaultModel: string;
   private readonly defaultMaxOutputTokens: number;
   private readonly defaultTimeoutMs: number;
@@ -57,19 +60,33 @@ export class ClaudeAdapter implements Adapter {
     this.defaultModel = options.defaultModel ?? DEFAULT_MODEL;
     this.defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? 4096;
     this.defaultTimeoutMs = options.defaultTimeoutMs ?? 120_000;
+    this.explicitApiKey = options.apiKey;
+  }
 
-    const apiKey = options.apiKey ?? process.env["ANTHROPIC_API_KEY"];
-    this.client = apiKey ? new Anthropic({ apiKey }) : null;
+  /**
+   * Lazily resolve the API key on first need. Goes through the
+   * unified resolver: explicit → env → keychain → missing.
+   */
+  private async ensureClient(): Promise<Anthropic | null> {
+    if (this.resolved) return this.client;
+    this.resolved = true;
+    const opts = this.explicitApiKey ? { explicit: this.explicitApiKey } : {};
+    const result = await resolveApiKey("anthropic", opts);
+    if (result.source === "missing") return null;
+    this.client = new Anthropic({ apiKey: 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(
-        "ANTHROPIC_API_KEY is not set. Export it in your environment.",
+        'No Anthropic API key found. Run "almightygpt auth anthropic" ' +
+          "or export ANTHROPIC_API_KEY in your environment.",
         this.name,
       );
     }
@@ -81,7 +98,7 @@ export class ClaudeAdapter implements Adapter {
     const start = Date.now();
     let response: Anthropic.Message;
     try {
-      response = await this.client.messages.create(
+      response = await client.messages.create(
         {
           model,
           max_tokens: maxOutputTokens,

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,