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
This commit is contained in:
Michael Wang
2026-11-18 22:45:29 +00:00
committed by GitHub
parent 3229c3a8da
commit 8ace95ce94
9 changed files with 72 additions and 169 deletions
+2 -2
View File
@@ -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
+4 -6
View File
@@ -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.
+1 -2
View File
@@ -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"));
@@ -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));
+4 -107
View File
@@ -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<string, string>, 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`,
);
});
});
-22
View File
@@ -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";
+1 -1
View File
@@ -18,7 +18,7 @@
"files": 13
},
"media-use": {
"hash": "6dee8b534a8fe0a9",
"hash": "6d018bd953cd09b1",
"files": 130
},
"remotion-to-hyperframes": {
+7 -16
View File
@@ -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);
@@ -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/,
);
},
);