blume 2.1.0 → 2.1.2

package/src/eval/report.ts

@@ -10,27 +10,40 @@ import { duration, money, seconds } from "../cli/report-format.ts";
 import { countBySeverity } from "../core/diagnostics.ts";
 import type { EvalResult, QuestionResult, QuestionStatus } from "./run.ts";
 
+/** How a question reads in the report: its status, or `warn` for a warned miss. */
+type ShownStatus = QuestionStatus | "warn";
+
 const GLYPH = {
   error: "!",
   fail: "✖",
   pass: "✔",
   skip: "⊘",
-} satisfies Record<QuestionStatus, string>;
+  warn: "⚠",
+} satisfies Record<ShownStatus, string>;
 
 const STATUS_COLOR = {
   error: colors.yellow,
   fail: colors.red,
   pass: colors.green,
   skip: colors.dim,
-} satisfies Record<QuestionStatus, ColorFunction>;
+  warn: colors.yellow,
+} satisfies Record<ShownStatus, ColorFunction>;
+
+/**
+ * A failed `severity: warning` question: its miss never counts against the
+ * gate, so the report shows and counts it as a warning, not a failure.
+ */
+const warned = (result: QuestionResult): boolean =>
+  result.status === "fail" && result.severity === "warning";
 
 /** Longest id gets the room; everything shorter aligns to it. */
 const ID_PAD = 28;
 
 /** One question's progress/report line: glyph, id, status, score, time, cost. */
 export const questionLine = (result: QuestionResult): string => {
-  const color = STATUS_COLOR[result.status];
-  const glyph = color(GLYPH[result.status]);
+  const shown: ShownStatus = warned(result) ? "warn" : result.status;
+  const color = STATUS_COLOR[shown];
+  const glyph = color(GLYPH[shown]);
   const id = result.id.padEnd(ID_PAD);
   if (result.status === "skip") {
     return `  ${glyph} ${id} ${colors.dim("skipped")}`;
@@ -38,7 +51,7 @@ export const questionLine = (result: QuestionResult): string => {
   const score = result.score === undefined ? "" : result.score.toFixed(2);
   const cost = money(result.costUsd);
   const cells = [
-    color(result.status),
+    color(shown),
     score,
     colors.dim(seconds(result.durationMs)),
     cost === "" ? "" : colors.dim(cost),
@@ -75,9 +88,12 @@ export const questionDetails = (
 /** The one-line totals: `9 passed · 2 failed · 1 skipped · 1m 42s · $0.71`. */
 export const summaryLine = (result: EvalResult): string => {
   const { counts } = result;
+  const warnings = result.results.filter(warned).length;
+  const failures = counts.fail - warnings;
   const parts = [
     `${counts.pass} passed`,
-    counts.fail > 0 ? `${counts.fail} failed` : "",
+    failures > 0 ? `${failures} failed` : "",
+    warnings > 0 ? `${warnings} warned` : "",
     counts.error > 0 ? `${counts.error} errored` : "",
     counts.skip > 0 ? `${counts.skip} skipped` : "",
     duration(result.durationMs),
@@ -98,10 +114,11 @@ export const startLine = (id: string, index: number, total: number): string =>
  * `fix:` pointers for failed questions, naming the file that resolves each. A
  * question whose agent run errored gets a `run failed:` line pointing at the
  * question instead: the run never graded the docs, so there's no page to fix.
+ * A `severity: warning` question's miss is a warning line instead.
  */
 export const fixLines = (result: EvalResult, root: string): string[] =>
   result.diagnostics
-    .filter((diagnostic) => diagnostic.code !== "BLUME_EVAL_ROUTE_UNKNOWN")
+    .filter((diagnostic) => diagnostic.severity !== "warning")
     .map((finding) => {
       const site = finding.file
         ? `${relative(root, finding.file)}${finding.line ? `:${finding.line}` : ""}`
@@ -113,10 +130,13 @@ export const fixLines = (result: EvalResult, root: string): string[] =>
       return `  ${label} ${site} ${colors.dim(finding.message)}`;
     });
 
-/** Dim warnings for route hints that no longer match a page. */
+/**
+ * Dim warnings: route hints that no longer match a page, and the misses of
+ * `severity: warning` questions.
+ */
 export const warningLines = (result: EvalResult, root: string): string[] =>
   result.diagnostics
-    .filter((diagnostic) => diagnostic.code === "BLUME_EVAL_ROUTE_UNKNOWN")
+    .filter((diagnostic) => diagnostic.severity === "warning")
     .map((finding) => {
       const site = finding.file
         ? ` ${relative(root, finding.file)}${finding.line ? `:${finding.line}` : ""}`
@@ -140,10 +160,11 @@ export const formatEvalReport = (
   }
   lines.push("");
 
-  // The finding tells the author which file fixes which failure.
-  const failures = fixLines(result, root);
-  lines.push(...failures);
-  if (failures.length > 0) {
+  // The finding tells the author which file fixes which failure, warnings
+  // first, as the command prints them.
+  const findings = [...warningLines(result, root), ...fixLines(result, root)];
+  lines.push(...findings);
+  if (findings.length > 0) {
     lines.push("");
   }
 

package/src/eval/run.ts

@@ -40,6 +40,8 @@ export interface QuestionResult {
   question: string;
   routes: string[];
   score?: number;
+  /** The question's severity: a `warning` miss is reported as a warning. */
+  severity?: EvalQuestion["severity"];
   status: QuestionStatus;
 }
 
@@ -99,6 +101,7 @@ const errored = (
   missing: [],
   question: question.question,
   routes: question.routes,
+  severity: question.severity,
   status: "error",
 });
 
@@ -177,6 +180,7 @@ const runQuestion = async (
     question: question.question,
     routes: question.routes,
     score: verdict.score,
+    severity: question.severity,
     status: verdict.pass ? "pass" : "fail",
   };
 };
@@ -250,6 +254,7 @@ export const runEval = async (options: EvalRunOptions): Promise<EvalResult> => {
         missing: [],
         question: question.question,
         routes: question.routes,
+        severity: question.severity,
         status: "skip",
       });
       continue;

package/src/markdown/base-links.ts

@@ -24,6 +24,21 @@ interface MdastUrlContext {
 const isUrl = (url: string | null | undefined): url is string =>
   typeof url === "string";
 
+/** Record `based(url)` on the node when its root-relative URL changes. */
+const rebase = (
+  node: UrlNode,
+  ctx: MdastUrlContext,
+  based: (url: string) => string
+): void => {
+  const { url } = node;
+  if (isUrl(url) && isInternalPath(url)) {
+    const next = based(url);
+    if (next !== url) {
+      ctx.setProperty(node, "url", next);
+    }
+  }
+};
+
 export interface BaseLinksPluginOptions {
   /**
    * The `blume:data` JSON file, for an ejected app: with no CLI in the process
@@ -72,20 +87,6 @@ export const baseLinksPlugin = (
   const servesPage = (route: string): boolean =>
     servesRoute(servedRoutes(), route);
 
-  /** Record `based(url)` on the node when its root-relative URL changes. */
-  const rebase = (
-    node: UrlNode,
-    ctx: MdastUrlContext,
-    based: (url: string) => string
-  ): void => {
-    const { url } = node;
-    if (isUrl(url) && isInternalPath(url)) {
-      const next = based(url);
-      if (next !== url) {
-        ctx.setProperty(node, "url", next);
-      }
-    }
-  };
   const rebaseLink = (node: UrlNode, ctx: MdastUrlContext): void =>
     rebase(node, ctx, (url) =>
       withAuthoredBasePath(deployBase, basePath, url, servesPage)

package/src/markdown/package-commands.ts

@@ -205,6 +205,9 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
   return words.join(" ");
 };
 
+const normalizeCommand = (command: string): string =>
+  command.replaceAll(WHITESPACE_RUN, " ").trim();
+
 /**
  * Convert an install command into the equivalent for every supported package
  * manager. Accepts a bare package list (`react`) or a full command
@@ -212,14 +215,12 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
  */
 export const toPackageCommands = (input: string) => {
   const intent = parseIntent(input);
-  const normalize = (command: string): string =>
-    command.replaceAll(WHITESPACE_RUN, " ").trim();
   return {
-    aube: normalize(buildCommand("aube", intent)),
-    bun: normalize(buildCommand("bun", intent)),
-    npm: normalize(buildCommand("npm", intent)),
-    nub: normalize(buildCommand("nub", intent)),
-    pnpm: normalize(buildCommand("pnpm", intent)),
-    yarn: normalize(buildCommand("yarn", intent)),
+    aube: normalizeCommand(buildCommand("aube", intent)),
+    bun: normalizeCommand(buildCommand("bun", intent)),
+    npm: normalizeCommand(buildCommand("npm", intent)),
+    nub: normalizeCommand(buildCommand("nub", intent)),
+    pnpm: normalizeCommand(buildCommand("pnpm", intent)),
+    yarn: normalizeCommand(buildCommand("yarn", intent)),
   } satisfies Record<PackageManager, string>;
 };

package/src/markdown/relative-links.ts

@@ -266,8 +266,9 @@ export const relativeLinksPlugin = (
 
   // A component's string `href` (`<Card href="./install">`) is the same kind
   // of link, and `blume validate` reads it as one. Lowercase elements are
-  // raw HTML in a `.md` page, which neither rewrites nor checks, so only
-  // components are rewritten; an expression-valued `href={…}` is left alone.
+  // raw HTML in a `.md` page, which isn't rewritten, so only components are
+  // rewritten (validate reads a raw `<a href>` as the browser does); an
+  // expression-valued `href={…}` is left alone.
   const rewriteHref = (node: JsxNode, ctx: RelativeLinksContext): void => {
     if (!node.name || !COMPONENT_NAME.test(node.name)) {
       return;

package/src/narration/build.ts

@@ -10,15 +10,24 @@ import {
   writeFile,
 } from "node:fs/promises";
 
+import type * as OpenAISdk from "@ai-sdk/openai";
+import type { OpenAIProvider } from "@ai-sdk/openai";
 import { createGateway, generateSpeech } from "ai";
+import type { SpeechModel } from "ai";
 import { HTMLElement, parse, TextNode } from "node-html-parser";
 import type { Node } from "node-html-parser";
 import { dirname, join } from "pathe";
 
 import { normalizeBasePath } from "../core/base-path.ts";
+import { nodeRequire } from "../core/node-require.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ProjectContext } from "../core/types.ts";
-import type { NarrationProvider } from "./provider.ts";
+import { hasCredentials, OPENAI_SPEECH_DEP } from "./provider.ts";
+import type {
+  GatewayNarrationProvider,
+  NarrationProvider,
+  OpenAINarrationProvider,
+} from "./provider.ts";
 import {
   extractNarration,
   isNarratable,
@@ -37,10 +46,11 @@ import type {
  * carries the player exactly as the browser will (same walker, same blocks),
  * split it into sentences, and give each sentence a clip from the configured
  * speech model. Clips are cached by what decides their sound (text, language,
- * model, voice, instructions, provider options), so a rebuild only pays for
- * sentences that changed, and one sentence shared by many pages is generated
- * once. Each page gets a manifest listing its clips; the player plays them in
- * order and falls back to browser voices wherever a manifest is missing.
+ * model, voice, instructions, provider options, endpoint), so a rebuild only
+ * pays for sentences that changed, and one sentence shared by many pages is
+ * generated once. Each page gets a manifest listing its clips; the player
+ * plays them in order and falls back to browser voices wherever a manifest is
+ * missing.
  */
 
 /** How the build logs: the integration's Astro logger. */
@@ -54,7 +64,10 @@ export type Speak = (text: string, lang: string) => Promise<Uint8Array>;
 
 /** What a narration build did, for the log line and tests. */
 export interface NarrationBuildResult {
-  /** Clips that failed to generate; their pages get no manifest. */
+  /**
+   * Clips that failed to generate, or that a missing key left ungenerated;
+   * their pages get no manifest.
+   */
   failed: number;
   /** Clips generated by the speech model on this build. */
   generated: number;
@@ -67,6 +80,13 @@ export interface NarrationBuildResult {
 // Bump to regenerate every clip: part of every cache key.
 const CLIP_FORMAT = 1;
 
+// Where `openai()` speaks with neither a `baseUrl` nor `OPENAI_BASE_URL`.
+const OPENAI_API_URL = "https://api.openai.com/v1";
+
+// What `generateSpeech` reports for bytes it recognized as MP3. Bytes it can't
+// place at all (a web page, raw PCM) default to `audio/mp3` instead.
+const MP3_MEDIA_TYPE = "audio/mpeg";
+
 // Parallel speech requests. Low enough to stay inside provider rate limits on
 // a first build of a large site, where every sentence is new.
 const CONCURRENCY = 4;
@@ -144,23 +164,52 @@ export const readPlayerPage = (html: string): PlayerPage | null => {
 const speechLanguage = (lang: string): string =>
   lang.toLowerCase().replaceAll("_", "-").split("-")[0] ?? lang;
 
+/**
+ * The server `openai()` speaks to: its `baseUrl`, else `OPENAI_BASE_URL` as
+ * OpenAI's SDKs read it, else OpenAI, without a trailing slash, which the SDK
+ * drops too. Resolved here rather than left to the SDK, so the clip key names
+ * the server the clips come from.
+ */
+const openaiEndpoint = (provider: OpenAINarrationProvider): string =>
+  (
+    provider.options.baseUrl ||
+    process.env.OPENAI_BASE_URL ||
+    OPENAI_API_URL
+  ).replace(/\/+$/u, "");
+
+/** The server a provider's clips come from: none named for `gateway()`. */
+const speakerEndpoint = (provider: NarrationProvider): string | undefined =>
+  provider.kind === "openai" ? openaiEndpoint(provider) : undefined;
+
 /**
  * A clip's cache key: a digest of everything that decides how it sounds. The
  * Blume version is deliberately left out, unlike the OG card's: an upgrade
- * shouldn't pay to regenerate audio that would sound the same.
+ * shouldn't pay to regenerate audio that would sound the same. A build
+ * resolves `endpoint` once and passes it in, rather than reading the
+ * environment for every sentence.
  */
 export const clipKey = (
   provider: NarrationProvider,
   lang: string,
-  text: string
+  text: string,
+  endpoint = speakerEndpoint(provider)
 ): string => {
   const { instructions, model, providerOptions, voice } = provider.options;
+  const gateway = provider.kind === "gateway";
   return createHash("sha256")
     .update(
       JSON.stringify({
+        // Which server speaks: none for `gateway()`, which JSON drops, so its
+        // clips keep the keys they had before narration took other providers.
+        endpoint: gateway
+          ? undefined
+          : { baseUrl: endpoint, kind: provider.kind },
         format: CLIP_FORMAT,
         instructions,
-        lang: speechLanguage(lang),
+        // Only the gateway is sent a language (`openaiSpeaker` sends none), so
+        // an `openai()` sentence sounds the same in every locale and is
+        // generated once.
+        lang: gateway ? speechLanguage(lang) : undefined,
         model,
         providerOptions,
         text,
@@ -172,7 +221,7 @@ export const clipKey = (
 };
 
 /** Speak through the Vercel AI Gateway with the provider's model and voice. */
-export const gatewaySpeaker = (provider: NarrationProvider): Speak => {
+export const gatewaySpeaker = (provider: GatewayNarrationProvider): Speak => {
   const { apiKeyEnv, headers, instructions, model, providerOptions, voice } =
     provider.options;
   const gateway = createGateway({ apiKey: process.env[apiKeyEnv], headers });
@@ -190,6 +239,104 @@ export const gatewaySpeaker = (provider: NarrationProvider): Speak => {
   };
 };
 
+/**
+ * `fetch` for a keyless request: `createOpenAI` always sends the key as a
+ * bearer token, so an empty one would arrive as a bare `Bearer` that servers
+ * and proxies checking auth can reject. An `Authorization` from `headers`
+ * stays.
+ */
+const withoutEmptyBearer = async (
+  input: Parameters<typeof fetch>[0],
+  init?: RequestInit
+): Promise<Response> => {
+  const headers = new Headers(init?.headers);
+  if (headers.get("authorization") === "Bearer") {
+    headers.delete("authorization");
+  }
+  return await fetch(input, { ...init, headers });
+};
+
+/**
+ * Speak through OpenAI's speech API, or with `baseUrl` through any server
+ * that serves it (`POST /audio/speech`): Kokoro-FastAPI, Speaches, LiteLLM.
+ * That API takes no language, so none is sent and the model or voice
+ * decides it. Without a key, no bearer token is sent (an `Authorization` in
+ * `headers` still is). A build resolves `baseURL` once and passes it in.
+ */
+export const openaiSpeaker = (
+  provider: OpenAINarrationProvider,
+  baseURL = openaiEndpoint(provider)
+): Speak => {
+  const { apiKeyEnv, headers, instructions, model, providerOptions, voice } =
+    provider.options;
+  // Made on the first clip rather than up front, so what can go wrong here
+  // fails that clip and the build carries on with browser voices: an ejected
+  // app's `astro build` runs no dependency preflight, and `OPENAI_BASE_URL`
+  // isn't validated the way `baseUrl` is.
+  const connect = (): OpenAIProvider => {
+    if (hasCredentials(baseURL)) {
+      throw new Error(
+        "OPENAI_BASE_URL has credentials in it, which fetch won't send: name the env var holding the key in apiKeyEnv instead"
+      );
+    }
+    // `require`, not `import()`: this runs in `astro:build:done` (see
+    // `core/node-require.ts`).
+    const { createOpenAI }: typeof OpenAISdk = nodeRequire(OPENAI_SPEECH_DEP);
+    const apiKey = apiKeyEnv ? process.env[apiKeyEnv] : undefined;
+    return createOpenAI({
+      // Never undefined: the SDK would fall back to OPENAI_API_KEY and send
+      // that to a custom endpoint that names no key.
+      apiKey: apiKey ?? "",
+      baseURL,
+      // SAFETY: the SDK only calls it, so Bun's `fetch.preconnect` (which its
+      // `typeof fetch` adds) is never read.
+      fetch: apiKey ? undefined : (withoutEmptyBearer as typeof fetch),
+      headers,
+    });
+  };
+  let openai: OpenAIProvider | undefined;
+  return async (text) => {
+    openai ??= connect();
+    const { audio, responses } = await generateSpeech({
+      instructions,
+      // SAFETY: both sides are the same `SpeechModelV4` spec. `ai` and
+      // `@ai-sdk/openai` each pin their own `@ai-sdk/provider`, and the type
+      // only differs between those copies, not in what `generateSpeech` calls.
+      model: openai.speech(model) as SpeechModel,
+      outputFormat: "mp3",
+      providerOptions,
+      text,
+      voice,
+    });
+    // The SDK takes any 2xx body as audio, and the clip is cached and served
+    // as an MP3 whatever it holds, so a page a redirect led to (an SSO
+    // proxy's sign-in, say) or WAV from a server that ignores
+    // `response_format` would be reused on every build after: fail the clip
+    // unless its bytes are MP3.
+    if (audio.mediaType !== MP3_MEDIA_TYPE) {
+      const type = responses[0]?.headers?.["content-type"] ?? "no content type";
+      throw new Error(`The speech server answered with ${type}, not MP3 audio`);
+    }
+    return audio.uint8Array;
+  };
+};
+
+/**
+ * The env var a build needs to generate with `provider` and doesn't have, or
+ * `null` when it can go ahead: the key is set, Vercel's OIDC token stands in
+ * for the gateway's, or the provider names no key (`openai()` with a
+ * `baseUrl` and no `apiKeyEnv`).
+ */
+export const missingKey = (provider: NarrationProvider): string | null => {
+  const env = provider.options.apiKeyEnv;
+  if (env === undefined || process.env[env]) {
+    return null;
+  }
+  return provider.kind === "gateway" && process.env.VERCEL_OIDC_TOKEN
+    ? null
+    : env;
+};
+
 /** Every `.html` file under `dir`. */
 const listHtml = async (dir: string): Promise<string[]> => {
   const entries = await readdir(dir, { recursive: true, withFileTypes: true });
@@ -274,35 +421,23 @@ const manifestFor = (plan: PagePlan): NarrationManifest => ({
   version: 1,
 });
 
+/** What a build narrates: each page's plan, and every clip by its key. */
+interface SitePlan {
+  /** Where the clips are published, or `null` with no narratable page. */
+  audioDir: string | null;
+  plans: PagePlan[];
+  texts: Map<string, { lang: string; text: string }>;
+}
+
 /**
- * Generate the narration for a built site in `distDir`: a clip per sentence
- * and a manifest per page. Does nothing unless `narration.provider` is set,
- * and warns instead of generating when the provider's key is missing (the
- * pages then read with browser voices). `speak` replaces the gateway call.
+ * Read every built page that carries the player and plan its narration,
+ * keying each sentence's clip with `keyFor`.
  */
-export const buildNarration = async (
-  project: BlumeProject,
+const planSite = async (
   distDir: string,
-  logger: NarrationLogger,
-  speak?: Speak
-): Promise<NarrationBuildResult | null> => {
-  const { narration } = project.config;
-  const { provider } = narration;
-  if (!(narration.enabled && provider)) {
-    return null;
-  }
-  const env = provider.options.apiKeyEnv;
-  if (!(speak || process.env[env] || process.env.VERCEL_OIDC_TOKEN)) {
-    logger.warn(
-      `Narration audio was not generated: ${env} is not set, so pages will be read with browser voices.`
-    );
-    return null;
-  }
-  const say = speak ?? gatewaySpeaker(provider);
-  const base = normalizeBasePath(project.config.deployment.options.base);
-
-  // Read every page first, so the log can say what generation will cost
-  // before any of it is spent.
+  base: string,
+  keyFor: (lang: string, text: string) => string
+): Promise<SitePlan> => {
   const plans: PagePlan[] = [];
   const texts = new Map<string, { lang: string; text: string }>();
   let audioDir: string | null = null;
@@ -322,7 +457,7 @@ export const buildNarration = async (
     audioDir ??= distPath(distDir, base, page.audioBase);
     const segments = segmentNarration(extract, page.lang);
     const keys = segments.map((segment) => {
-      const key = clipKey(provider, page.lang, segment.text);
+      const key = keyFor(page.lang, segment.text);
       texts.set(key, { lang: page.lang, text: segment.text });
       return key;
     });
@@ -333,6 +468,37 @@ export const buildNarration = async (
       segments,
     });
   }
+  return { audioDir, plans, texts };
+};
+
+/**
+ * Generate the narration for a built site in `distDir`: a clip per sentence
+ * and a manifest per page. Does nothing unless `narration.provider` is set.
+ * When new clips are needed and the provider's key is missing, it warns and
+ * generates nothing, so only pages whose clips are all cached get audio (the
+ * rest read with browser voices). `speak` replaces the provider call.
+ */
+export const buildNarration = async (
+  project: BlumeProject,
+  distDir: string,
+  logger: NarrationLogger,
+  speak?: Speak
+): Promise<NarrationBuildResult | null> => {
+  const { narration } = project.config;
+  const { provider } = narration;
+  if (!(narration.enabled && provider)) {
+    return null;
+  }
+  const endpoint = speakerEndpoint(provider);
+  const base = normalizeBasePath(project.config.deployment.options.base);
+
+  // Read every page first, so the log can say what generation will cost
+  // before any of it is spent.
+  const { audioDir, plans, texts } = await planSite(
+    distDir,
+    base,
+    (lang, text) => clipKey(provider, lang, text, endpoint)
+  );
   if (!audioDir || plans.length === 0) {
     return { failed: 0, generated: 0, pages: 0, reused: 0 };
   }
@@ -341,7 +507,14 @@ export const buildNarration = async (
   const cached = (key: string) => join(cacheDir, `${key}.mp3`);
   const missing = [...texts.keys()].filter((key) => !existsSync(cached(key)));
   const reused = texts.size - missing.length;
-  if (missing.length > 0) {
+  // Checked only once something needs generating, so a build without the key
+  // (a fork's pull request, say) still ships every clip the cache restored.
+  const env = speak || missing.length === 0 ? null : missingKey(provider);
+  if (env) {
+    logger.warn(
+      `Narration audio was not generated: ${env} is not set, so pages missing clips will be read with browser voices.`
+    );
+  } else if (missing.length > 0) {
     const chars = missing.reduce(
       (total, key) => total + (texts.get(key)?.text.length ?? 0),
       0
@@ -350,13 +523,18 @@ export const buildNarration = async (
       `Generating narration: ${missing.length} new clip(s), ${chars.toLocaleString("en-US")} characters, with ${provider.options.model}`
     );
   }
+  const say =
+    speak ??
+    (provider.kind === "gateway"
+      ? gatewaySpeaker(provider)
+      : openaiSpeaker(provider, endpoint));
 
   // The AI SDK already retries a transient failure, so one that gets through
   // (a bad key, an unknown model, a spent quota) would fail every clip after
   // it too: stop generating at the first, and keep what's already cached.
-  const failures = new Set<string>();
+  const failures = new Set(env ? missing : []);
   let firstError: string | null = null;
-  await eachLimited(missing, CONCURRENCY, async (key) => {
+  await eachLimited(env ? [] : missing, CONCURRENCY, async (key) => {
     const entry = texts.get(key);
     if (!entry || firstError !== null) {
       failures.add(key);