From 8ace95ce949b953224b164833b84495edecb2eb7 Mon Sep 17 00:00:00 2001 From: Michael Wang Date: Wed, 18 Nov 2026 22:45:29 +0000 Subject: [PATCH] fix(cli): a project .env provider key gives way only in a received project (#8099) * fix(cli): a project .env provider key gives way only in a received project Your own or a cloned project's .env provider keys are used as set again, as the docs describe. Capture no longer drops a project .env vision key next to a shell credential, and the audio scripts no longer drop an own project's Gemini key next to the shell's other Gemini key. A received project's keys still give way to your own credential, and the notes that name a project key when it is used stay. * test(cli): check the note for a cloned project's key; say when a received key is ignored --- docs/guides/authentication.mdx | 4 +- docs/packages/cli.mdx | 10 +- packages/cli/src/capture/captureAttempt.ts | 3 +- .../cli/src/capture/contentExtractor.test.ts | 46 ++++++-- packages/cli/src/utils/dotEnv.test.ts | 111 +----------------- packages/cli/src/utils/dotEnv.ts | 22 ---- skills-manifest.json | 2 +- skills/media-use/audio/scripts/lib/heygen.mjs | 23 ++-- .../audio/scripts/lib/heygen.test.mjs | 20 +++- 9 files changed, 72 insertions(+), 169 deletions(-) diff --git a/docs/guides/authentication.mdx b/docs/guides/authentication.mdx index 77a76bb5b9..05f39e1ddd 100644 --- a/docs/guides/authentication.mdx +++ b/docs/guides/authentication.mdx @@ -153,10 +153,10 @@ to a shared space with `--space`. | `HYPERFRAMES_ENV` | `prod` (default) or `dev`; `dev` keeps credentials in a separate `dev/` directory under the root. Hosts and the OAuth client id come from `HEYGEN_API_URL`, `HYPERFRAMES_OAUTH_*` and `HYPERFRAMES_PUBLISHED_PROJECTS_API_URL`. | | `HYPERFRAMES_OAUTH_CLIENT_ID` | Override the public client ID for a controlled OAuth environment. | | `ELEVENLABS_API_KEY` | ElevenLabs TTS, used when no HeyGen credential is present. A key from a received project's `.env` is never used next to your own HeyGen credential. A note names the file whenever a project `.env` key is used. | -| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Explicit Gemini TTS selection and Lyria music generation; capture descriptions use `GEMINI_API_KEY`. In speech and music, one from a project's `.env` gives way to the other set in your shell. A note names the file whenever a project `.env` key is used. | +| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Explicit Gemini TTS selection and Lyria music generation; capture descriptions use `GEMINI_API_KEY`. One from a received project's `.env` is ignored when you set a competing credential yourself: in the CLI, the other Gemini key, a Google service account, OpenRouter or Vertex; in the media-use audio scripts, the other Gemini key or a Google service account. A note names the file whenever a project `.env` key is used. | | `GOOGLE_APPLICATION_CREDENTIALS` / `GCS_CREDS` | Gemini TTS service-account JSON file path / injected JSON. Used when neither API key is set. | | `GOOGLE_CLOUD_PROJECT` / `GCLOUD_PROJECT_ID` | Gemini OAuth quota project; first set value wins, then the service account project. | -| `OPENROUTER_API_KEY` | Capture descriptions; takes priority over Gemini for that step, unless it comes from a project's `.env` and your shell has a complete Gemini or Vertex credential. A note names the file whenever a project `.env` key is used. | +| `OPENROUTER_API_KEY` | Capture descriptions; takes priority over Gemini for that step. One from a received project's `.env` gives way to your own Gemini or Vertex credential. A note names the file whenever a project `.env` key is used. | ## Related topics diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index a872da1918..a93ce1acd4 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -404,12 +404,10 @@ For AI image descriptions, set `GEMINI_API_KEY` in a `.env` file [OpenRouter](https://openrouter.ai) — it wins if both are set, and `HYPERFRAMES_OPENROUTER_MODEL` overrides the model. -A project's `.env` never replaces a vision credential you set in your shell: -when your shell holds a complete credential for another vision provider, -capture ignores the `.env` vision key, with a note naming the file. -Model and timeout settings in the `.env` still apply. A received project's -`.env` (one its received-files record lists) also gives way to your own -project's `.env`, for every command. When capture or `snapshot --describe` uses +A received project's `.env` (one its received-files record lists) never +replaces a vision or Gemini credential you set in your shell or your own +project's `.env`: its competing keys are ignored, with a note naming the file. +Keys in your own or a cloned project's `.env` are used as set. When capture or `snapshot --describe` uses a vision key from a project's `.env`, a note naming the file prints before the first request. diff --git a/packages/cli/src/capture/captureAttempt.ts b/packages/cli/src/capture/captureAttempt.ts index b87b38f610..d3de981f48 100644 --- a/packages/cli/src/capture/captureAttempt.ts +++ b/packages/cli/src/capture/captureAttempt.ts @@ -16,7 +16,7 @@ import { setupAnimationCapture, startCdpAnimationCapture } from "./animationCata import type { DiscoveredLottie } from "./mediaCapture.js"; import { detectLibraries } from "./contentExtractor.js"; import { loadEnvFile, generateProjectScaffold } from "./scaffolding.js"; -import { yieldProjectVisionKeys, yieldReceivedProviderKeys } from "../utils/dotEnv.js"; +import { yieldReceivedProviderKeys } from "../utils/dotEnv.js"; import { captureProtocolTimeoutMs } from "./captureTimeout.js"; import { CAPTURE_PHASE_SCHEMA, DEFAULT_MAX_SCREENSHOTS } from "./types.js"; import type { @@ -115,7 +115,6 @@ export async function captureWebsiteAttempt( // Load .env file from repo root if it exists (for GEMINI_API_KEY, etc.) loadEnvFile(outputDir); await yieldReceivedProviderKeys((line) => console.error(line)); - yieldProjectVisionKeys((line) => console.error(line)); // Create output directories ensureCaptureDirSync(outputDir, join(outputDir, "extracted")); diff --git a/packages/cli/src/capture/contentExtractor.test.ts b/packages/cli/src/capture/contentExtractor.test.ts index 651cf075e6..37138a5679 100644 --- a/packages/cli/src/capture/contentExtractor.test.ts +++ b/packages/cli/src/capture/contentExtractor.test.ts @@ -8,7 +8,7 @@ import { type VisionCaptionOutcome, } from "./contentExtractor.js"; import { loadOptionalPackage } from "../utils/optionalPackages.js"; -import { yieldProjectVisionKeys, yieldReceivedProviderKeys } from "../utils/dotEnv.js"; +import { yieldReceivedProviderKeys } from "../utils/dotEnv.js"; import { loadEnvFile } from "./scaffolding.js"; const { generateContentMock, clientOptions, sharpState } = vi.hoisted(() => ({ @@ -424,10 +424,11 @@ describe("captionImagesWithGemini — Gemini provider", () => { dirs.length = 0; }); - it.each([ - ["a received project's", true], - ["a cloned project's", false], - ])("captions with the shell's Gemini key, never %s OpenRouter key", async (_, received) => { + /** A project whose `.env` sets an OpenRouter key, captioned with a Gemini key in the shell. */ + async function captionNextToShellGemini( + received: boolean, + fetchMock: (...args: never[]) => unknown, + ) { const dir = makeProjectWithImages(); dirs.push(dir); if (received) { @@ -437,7 +438,7 @@ describe("captionImagesWithGemini — Gemini provider", () => { JSON.stringify({ files: [".env"] }), ); } - writeFileSync(join(dir, ".env"), "OPENROUTER_API_KEY=received-key\n"); + writeFileSync(join(dir, ".env"), "OPENROUTER_API_KEY=project-key\n"); for (const key of [ "OPENROUTER_API_KEY", "GOOGLE_API_KEY", @@ -447,19 +448,44 @@ describe("captionImagesWithGemini — Gemini provider", () => { ]) vi.stubEnv(key, undefined); vi.stubEnv("GEMINI_API_KEY", "own-gemini-key"); - const fetchMock = vi.fn(); vi.stubGlobal("fetch", fetchMock); generateContentMock.mockResolvedValue({ text: "A caption." }); loadEnvFile(join(dir, "out")); await yieldReceivedProviderKeys(() => {}); - yieldProjectVisionKeys(() => {}); - const captions = await captionImagesWithGemini(dir, () => {}, []); + return { dir, captions: await captionImagesWithGemini(dir, () => {}, []) }; + } + + it("captions with the shell's Gemini key, never a received project's OpenRouter key", async () => { + const fetchMock = vi.fn(); + const { captions } = await captionNextToShellGemini(true, fetchMock); expect(fetchMock).not.toHaveBeenCalled(); expect(captions).toEqual({ "hero.png": "A caption." }); }); + it("captions with a cloned project's OpenRouter key ahead of the shell's Gemini key", async () => { + let authorization: string | null = null; + const fetchMock = vi.fn(async (_url: string, init?: RequestInit) => { + authorization = new Headers(init?.headers).get("authorization"); + return new Response(JSON.stringify({ choices: [{ message: { content: "Routed." } }] }), { + status: 200, + headers: { "content-type": "application/json" }, + }); + }); + const errors = vi.spyOn(console, "error").mockImplementation(() => {}); + const { dir, captions } = await captionNextToShellGemini(false, fetchMock); + const notes = errors.mock.calls.map(([line]) => String(line)); + errors.mockRestore(); + + expect(captions).toEqual({ "hero.png": "Routed." }); + expect(authorization).toBe("Bearer project-key"); + expect(generateContentMock).not.toHaveBeenCalled(); + expect(notes).toEqual([ + `[hyperframes] Using OPENROUTER_API_KEY from ${join(dir, ".env")}, a project .env: images go to that key's OpenRouter account.`, + ]); + }); + // fails without the fix: a received project's Gemini key captioned images with no note. it("notes once that a received project's Gemini key is captioning, naming its .env", async () => { const dir = makeProjectWithImages(); @@ -484,7 +510,6 @@ describe("captionImagesWithGemini — Gemini provider", () => { loadEnvFile(join(dir, "out")); await yieldReceivedProviderKeys(() => {}); - yieldProjectVisionKeys(() => {}); await captionImagesWithGemini(dir, () => {}, []); const captions = await captionImagesWithGemini(dir, () => {}, []); const notes = errors.mock.calls.map(([line]) => String(line)); @@ -633,7 +658,6 @@ describe("captionImagesWithGemini — Vertex AI provider", () => { loadEnvFile(join(dir, "out")); await yieldReceivedProviderKeys(() => {}); - yieldProjectVisionKeys(() => {}); await captionImagesWithGemini(dir, () => {}, []); const captions = await captionImagesWithGemini(dir, () => {}, []); const notes = errors.mock.calls.map(([line]) => String(line)); diff --git a/packages/cli/src/utils/dotEnv.test.ts b/packages/cli/src/utils/dotEnv.test.ts index 8c2b817dd3..7c98a793f3 100644 --- a/packages/cli/src/utils/dotEnv.test.ts +++ b/packages/cli/src/utils/dotEnv.test.ts @@ -6,7 +6,6 @@ import { applyDotEnv, loadProjectDotEnv, noteProjectProviderKey, - yieldProjectVisionKeys, yieldReceivedProviderKeys, } from "./dotEnv.js"; @@ -246,105 +245,6 @@ describe("yieldReceivedProviderKeys", () => { }); }); -describe("yieldProjectVisionKeys", () => { - const VISION_KEYS = [ - "OPENROUTER_API_KEY", - "GEMINI_API_KEY", - "GOOGLE_API_KEY", - "HYPERFRAMES_VERTEX_PROJECT_ID", - "HYPERFRAMES_VERTEX_SERVICE_ACCOUNT", - ]; - const dirs: string[] = []; - - afterEach(() => { - vi.unstubAllEnvs(); - for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true }); - }); - - /** Loads `env` from the person's own project `.env` over `shell`, then runs the startup rule. */ - async function loadOwn(shell: Record, env: string) { - for (const key of VISION_KEYS) vi.stubEnv(key, shell[key]); - const dir = mkdtempSync(join(tmpdir(), "hf-dotenv-vision-")); - dirs.push(dir); - writeFileSync(join(dir, ".env"), env); - loadProjectDotEnv(dir, process.env, vi.fn()); - await yieldReceivedProviderKeys(vi.fn()); - return dir; - } - - it("leaves the person's own project keys alone at startup, so snapshot keeps its Gemini key", async () => { - await loadOwn({ OPENROUTER_API_KEY: "own" }, "GEMINI_API_KEY=mine\n"); - expect(process.env.GEMINI_API_KEY).toBe("mine"); - }); - - it("drops a project .env's OpenRouter key for capture when the shell has a Gemini key", async () => { - const dir = await loadOwn({ GEMINI_API_KEY: "own" }, "OPENROUTER_API_KEY=cloned\n"); - const warn = vi.fn(); - yieldProjectVisionKeys(warn); - expect(process.env.OPENROUTER_API_KEY).toBeUndefined(); - expect(process.env.GEMINI_API_KEY).toBe("own"); - expect(warn).toHaveBeenCalledWith( - `[hyperframes] .env: ignoring OPENROUTER_API_KEY from a project .env (${join(dir, ".env")}); capture uses your own GEMINI_API_KEY`, - ); - }); - - it("names the credential capture will pick in the note", async () => { - await loadOwn( - { - GEMINI_API_KEY: "own", - HYPERFRAMES_VERTEX_PROJECT_ID: "own", - HYPERFRAMES_VERTEX_SERVICE_ACCOUNT: "/own/sa.json", - }, - "OPENROUTER_API_KEY=cloned\n", - ); - const warn = vi.fn(); - yieldProjectVisionKeys(warn); - expect(warn).toHaveBeenCalledWith( - expect.stringContaining( - "capture uses your own HYPERFRAMES_VERTEX_PROJECT_ID and HYPERFRAMES_VERTEX_SERVICE_ACCOUNT", - ), - ); - }); - - it("keeps the project half of a Vertex credential whose other half is in the shell", async () => { - await loadOwn( - { HYPERFRAMES_VERTEX_SERVICE_ACCOUNT: "/own/sa.json" }, - "HYPERFRAMES_VERTEX_PROJECT_ID=mine\n", - ); - const warn = vi.fn(); - yieldProjectVisionKeys(warn); - expect(process.env.HYPERFRAMES_VERTEX_PROJECT_ID).toBe("mine"); - expect(warn).not.toHaveBeenCalled(); - }); - - it("keeps a project key next to an incomplete shell Vertex credential", async () => { - await loadOwn({ HYPERFRAMES_VERTEX_PROJECT_ID: "own" }, "GEMINI_API_KEY=mine\n"); - yieldProjectVisionKeys(vi.fn()); - expect(process.env.GEMINI_API_KEY).toBe("mine"); - }); - - it("drops both Vertex parts from a project .env when the shell has a Gemini key, keeping its model", async () => { - await loadOwn( - { GEMINI_API_KEY: "own" }, - "HYPERFRAMES_VERTEX_PROJECT_ID=cloned\nHYPERFRAMES_VERTEX_SERVICE_ACCOUNT=/cloned/sa.json\nHYPERFRAMES_GEMINI_MODEL=gemini-x\n", - ); - yieldProjectVisionKeys(vi.fn()); - expect(process.env.HYPERFRAMES_VERTEX_PROJECT_ID).toBeUndefined(); - expect(process.env.HYPERFRAMES_VERTEX_SERVICE_ACCOUNT).toBeUndefined(); - expect(process.env.HYPERFRAMES_GEMINI_MODEL).toBe("gemini-x"); - }); - - it("does not bring a dropped key back when capture reads the same .env again", async () => { - const dir = await loadOwn({ GEMINI_API_KEY: "own" }, "OPENROUTER_API_KEY=cloned\n"); - yieldProjectVisionKeys(vi.fn()); - loadProjectDotEnv(dir, process.env, vi.fn()); - const warn = vi.fn(); - yieldProjectVisionKeys(warn); - expect(process.env.OPENROUTER_API_KEY).toBeUndefined(); - expect(warn).not.toHaveBeenCalled(); - }); -}); - describe("project .env key notes", () => { const dirs: string[] = []; // Windows refuses control characters in folder names, so there the path is plain. @@ -407,16 +307,13 @@ describe("project .env key notes", () => { }); // fails without the fix: the ignoring note printed the folder name's control characters raw. - it("escapes the path in the note that a project vision key is ignored", async () => { - vi.stubEnv("HYPERFRAMES_VERTEX_PROJECT_ID", undefined); - vi.stubEnv("HYPERFRAMES_VERTEX_SERVICE_ACCOUNT", undefined); - vi.stubEnv("GOOGLE_API_KEY", undefined); + it("escapes the path in the note that a received project's key is ignored", async () => { vi.stubEnv("GEMINI_API_KEY", "own"); - const dir = load({ OPENROUTER_API_KEY: "cloned" }, false); + const dir = load({ OPENROUTER_API_KEY: "received" }, true); const warn = vi.fn(); - yieldProjectVisionKeys(warn); + await yieldReceivedProviderKeys(warn); expect(warn).toHaveBeenCalledWith( - `[hyperframes] .env: ignoring OPENROUTER_API_KEY from a project .env (${shown(dir)}); capture uses your own GEMINI_API_KEY`, + `[hyperframes] .env: ignoring OPENROUTER_API_KEY from a received project (${shown(dir)}); using your own GEMINI_API_KEY`, ); }); }); diff --git a/packages/cli/src/utils/dotEnv.ts b/packages/cli/src/utils/dotEnv.ts index d98f2d3a1c..009249c68f 100644 --- a/packages/cli/src/utils/dotEnv.ts +++ b/packages/cli/src/utils/dotEnv.ts @@ -180,28 +180,6 @@ const VISION_CREDENTIALS: readonly (readonly string[])[] = [ ["GOOGLE_API_KEY"], ]; -const setOutsideProjectEnv = (parts: readonly string[]) => - parts.every((part) => Boolean(process.env[part]) && projectEnvDir(part) === undefined); - -/** Unsets capture's vision keys from a project `.env` when the person set another complete vision credential. */ -export function yieldProjectVisionKeys(warn: (line: string) => void): void { - for (const credential of VISION_CREDENTIALS) { - if (credential.every((part) => projectEnvDir(part) === undefined)) continue; - const own = VISION_CREDENTIALS.find( - (other) => other !== credential && setOutsideProjectEnv(other), - ); - if (own === undefined) continue; - for (const name of credential) { - const dir = projectEnvDir(name); - if (dir === undefined) continue; - yieldKey(name, dir); - warn( - `[hyperframes] .env: ignoring ${name} from a project .env (${terminalText(join(dir, ".env"))}); capture uses your own ${own.join(" and ")}`, - ); - } - } -} - export const geminiKeyName = (): string => process.env.GEMINI_API_KEY ? "GEMINI_API_KEY" : "GOOGLE_API_KEY"; diff --git a/skills-manifest.json b/skills-manifest.json index e63bdb9ad6..230ae21b58 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 13 }, "media-use": { - "hash": "6dee8b534a8fe0a9", + "hash": "6d018bd953cd09b1", "files": 130 }, "remotion-to-hyperframes": { diff --git a/skills/media-use/audio/scripts/lib/heygen.mjs b/skills/media-use/audio/scripts/lib/heygen.mjs index fe83dfc99d..bc646b38ff 100644 --- a/skills/media-use/audio/scripts/lib/heygen.mjs +++ b/skills/media-use/audio/scripts/lib/heygen.mjs @@ -154,30 +154,21 @@ function untrustedOrigin(name) { return state === null ? null : RECEIVED_ORIGIN[state]; } -// 0: set outside any project .env; 1: the person's own project .env; 2: a received or unreadable one. -function keyRank(name) { - if (projectKeyDir(name) === undefined) return 0; - return untrustedOrigin(name) === null ? 1 : 2; -} - -// A credential for a competing provider from a source the person controls more surely, named for the note. The -// person's own project key gives way only to the other API key, which speech and music both accept, and an own -// ElevenLabs key stays for an explicit provider choice. +// The person's own credential that the provider of a received project's key competes with, named for the note; +// undefined when the key is the person's own or nothing competes. function ownCompetingCredential(name) { - const rank = keyRank(name); - const surer = (other) => other !== name && process.env[other] && keyRank(other) < rank; - if (name !== "ELEVENLABS_API_KEY") - return (rank === 2 ? GEMINI_CREDENTIALS : ["GEMINI_API_KEY", "GOOGLE_API_KEY"]).find(surer); - if (rank < 2) return undefined; + if (untrustedOrigin(name) === null) return undefined; + const own = (other) => other !== name && process.env[other] && untrustedOrigin(other) === null; + if (name !== "ELEVENLABS_API_KEY") return GEMINI_CREDENTIALS.find(own); if (process.env.HEYGEN_ACCESS_TOKEN) return "HEYGEN_ACCESS_TOKEN"; - const heygenKey = ["HEYGEN_API_KEY", "HYPERFRAMES_API_KEY"].find(surer); + const heygenKey = ["HEYGEN_API_KEY", "HYPERFRAMES_API_KEY"].find(own); if (heygenKey) return heygenKey; return storedCredential() ? "saved HeyGen credentials" : undefined; } const projectOrigin = (name) => untrustedOrigin(name) ?? "a project .env"; -// A project .env's provider key gives way to the person's own credential for a competing provider. +// A received project .env's provider key gives way to the person's own credential for a competing provider. function yieldProjectProviderKeys() { for (const name of ["GEMINI_API_KEY", "GOOGLE_API_KEY", "ELEVENLABS_API_KEY"]) { const dir = projectKeyDir(name); diff --git a/skills/media-use/audio/scripts/lib/heygen.test.mjs b/skills/media-use/audio/scripts/lib/heygen.test.mjs index 2e31482aae..83b998c349 100644 --- a/skills/media-use/audio/scripts/lib/heygen.test.mjs +++ b/skills/media-use/audio/scripts/lib/heygen.test.mjs @@ -15,6 +15,7 @@ import { heygenMessage, loadEnvFromDir, noteProjectElevenLabsKey, + noteProjectProviderKey, } from "./heygen.mjs"; const HEYGEN_ENV = [ @@ -708,15 +709,30 @@ test("loadEnvFromDir keeps a person's own .env Gemini key next to a shell servic ); }); -test("loadEnvFromDir leaves out a project .env's Gemini key when the shell has the other Gemini API key", () => { +test("loadEnvFromDir keeps a cloned project's .env Gemini key next to the shell's other Gemini API key", () => { withProviderProject( { shell: { GOOGLE_API_KEY: "own" }, env: "GEMINI_API_KEY=cloned\n" }, + (project, notes) => { + loadEnvFromDir(project); + assert.equal(process.env.GEMINI_API_KEY, "cloned"); + assert.deepEqual(notes, []); + noteProjectProviderKey("GEMINI_API_KEY", "speech goes to that key's Gemini account"); + assert.deepEqual(notes, [ + `[hyperframes] Using GEMINI_API_KEY from ${join(project, ".env")}, a project .env: speech goes to that key's Gemini account.\n`, + ]); + }, + ); +}); + +test("loadEnvFromDir leaves out a received .env's Gemini key when the shell has the other Gemini API key", () => { + withProviderProject( + { shell: { GOOGLE_API_KEY: "own" }, env: "GEMINI_API_KEY=received\n", received: true }, (project, notes) => { loadEnvFromDir(project); assert.equal(process.env.GEMINI_API_KEY, undefined); assert.match( notes.join(""), - /ignoring GEMINI_API_KEY from a project \.env .*using your own GOOGLE_API_KEY/, + /ignoring GEMINI_API_KEY from a received project .*using your own GOOGLE_API_KEY/, ); }, );