blume 2.0.2 → 2.1.0

package/src/cli/commands/translate.ts

@@ -28,9 +28,10 @@ import {
   computeWorkList,
   scanForTranslation,
 } from "../../translate/work-list.ts";
+import { parseTimeoutSeconds } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
-import { flushStdout, logger, reportDiagnostics } from "../log.ts";
+import { logger, reportDiagnostics } from "../log.ts";
 
 /** Wall-clock ceiling per file, in seconds. */
 const DEFAULT_TIMEOUT_S = DEFAULT_TRANSLATE_TIMEOUT_MS / 1000;
@@ -80,12 +81,7 @@ const parseFlags = (args: TranslateFlags): ParsedTranslateFlags => {
     );
     process.exit(1);
   }
-  const timeoutS =
-    args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
-  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
-    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
-    process.exit(1);
-  }
+  const timeoutS = parseTimeoutSeconds(args.timeout, DEFAULT_TIMEOUT_S);
   const concurrency =
     args.concurrency === undefined
       ? DEFAULT_CONCURRENCY
@@ -228,8 +224,9 @@ export const translateCommand = defineCommand({
           process.stdout.write(checkReportJson(workList));
         }
         if (hasDrift(workList)) {
-          await flushStdout();
-          process.exit(1);
+          // Set the code and return rather than `process.exit`, which waits for
+          // neither a piped stderr (the drift report) nor a piped stdout.
+          process.exitCode = 1;
         }
         return;
       }
@@ -290,9 +287,9 @@ export const translateCommand = defineCommand({
       }
       if (result.counts.failed > 0 || result.counts.partial > 0) {
         // The ledger write above already persisted every success, so a failed
-        // rerun only retries what actually failed.
-        await flushStdout();
-        process.exit(1);
+        // rerun only retries what actually failed. Set the code rather than
+        // `process.exit`, which would cut off a piped stderr summary.
+        process.exitCode = 1;
       }
     } catch (error) {
       if (error instanceof BlumeError) {

package/src/cli/commands/validate.ts

@@ -119,7 +119,9 @@ export const validateCommand = defineCommand({
       logger.success("No broken links found.");
     }
     if (hadErrors || strictFailure) {
-      process.exit(1);
+      // Set the code and return rather than `process.exit`, which doesn't wait
+      // for a piped stderr: a long diagnostic list would be cut off.
+      process.exitCode = 1;
     }
   },
 });

package/src/cli/dev-lock.ts

@@ -1,8 +1,11 @@
 import {
   existsSync,
+  linkSync,
   mkdirSync,
   readFileSync,
+  renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 
@@ -29,6 +32,83 @@ export interface DevLockInfo {
 
 const lockPath = (outDir: string): string => join(outDir, "dev.lock");
 
+/** The mutex a process holds while it clears a stale lock. */
+const reapPath = (outDir: string): string => join(outDir, "dev.lock.reap");
+
+/**
+ * How long a lock file that doesn't parse counts as one being written right
+ * now. Blume creates a lock with its whole content in place (see
+ * {@link createExclusive}), but one left empty or cut off — by a crash, or by
+ * an older Blume that opened the file before writing it — would otherwise
+ * read as stale the instant it appears. Past this age it's debris.
+ */
+const PARTIAL_LOCK_GRACE_MS = 2000;
+
+/** Pause between claim attempts while another process is mid-claim. */
+const RETRY_DELAY_MS = 5;
+
+const pause = (ms: number): void => {
+  // A synchronous sleep: the claim is synchronous, and what it waits on is
+  // another process, so there's nothing in this one to yield to.
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+/** Per-process counter that keeps concurrent temp file names apart. */
+let tempSequence = 0;
+
+/** A private sibling of `path` to stage a write in. */
+const tempPath = (path: string): string => {
+  tempSequence += 1;
+  return `${path}.${process.pid}.${tempSequence}.tmp`;
+};
+
+/**
+ * Create `path` holding `payload`, atomically and exclusively. The payload
+ * goes to a private temp file first, which is then hard-linked into place:
+ * the link fails when `path` exists, exactly like a `wx` open, but the file
+ * appears with its whole content — no reader ever sees it empty or half
+ * written. Returns false when `path` already exists.
+ */
+const createExclusive = (path: string, payload: string): boolean => {
+  const temp = tempPath(path);
+  writeFileSync(temp, payload);
+  try {
+    linkSync(temp, path);
+    return true;
+  } catch (error) {
+    // SAFETY: `linkSync` failures are errno exceptions.
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+    return false;
+  } finally {
+    rmSync(temp, { force: true });
+  }
+};
+
+/** Replace `path` with `payload` in one step, so readers see old or new. */
+const replaceFile = (path: string, payload: string): void => {
+  const temp = tempPath(path);
+  writeFileSync(temp, payload);
+  renameSync(temp, path);
+};
+
+/** A file's text, or null when it doesn't exist (anymore). */
+const readIfExists = (
+  path: string
+): { raw: string; mtimeMs: number } | null => {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return { mtimeMs: statSync(path).mtimeMs, raw };
+  } catch (error) {
+    // SAFETY: `readFileSync`/`statSync` failures are errno exceptions.
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+    return null;
+  }
+};
+
 /** What `JSON.parse` can yield for a lock file body. */
 type LockFileValue =
   | string
@@ -85,17 +165,44 @@ const isProcessAlive = (pid: number): boolean => {
   }
 };
 
+/** What the lock file on a dir says, read once. */
+type LockState =
+  | { kind: "absent" }
+  /** Unparseable but brand new: another process is writing it right now. */
+  | { kind: "busy" }
+  | { kind: "live"; lock: DevLockInfo }
+  /** A dead holder's lock, or unparseable debris. */
+  | { kind: "stale" };
+
+const inspectLock = (outDir: string): LockState => {
+  const file = readIfExists(lockPath(outDir));
+  if (!file) {
+    return { kind: "absent" };
+  }
+  const lock = parseLock(file.raw);
+  if (!lock) {
+    return Date.now() - file.mtimeMs < PARTIAL_LOCK_GRACE_MS
+      ? { kind: "busy" }
+      : { kind: "stale" };
+  }
+  return isProcessAlive(lock.pid) ? { kind: "live", lock } : { kind: "stale" };
+};
+
+/**
+ * Whether this process may clear the lock to claim the dir: a dead holder's
+ * lock and debris, or this process's own leftover.
+ */
+const isClaimable = (state: LockState): boolean =>
+  state.kind === "stale" ||
+  (state.kind === "live" && state.lock.pid === process.pid);
+
 /**
  * Read the lock on `outDir` held by a live `blume dev`, or null. A lock left
  * by a process that has since exited (stale) is treated as absent.
  */
 export const readDevLock = (outDir: string): DevLockInfo | null => {
-  const path = lockPath(outDir);
-  if (!existsSync(path)) {
-    return null;
-  }
-  const lock = parseLock(readFileSync(path, "utf-8"));
-  return lock && isProcessAlive(lock.pid) ? lock : null;
+  const state = inspectLock(outDir);
+  return state.kind === "live" ? state.lock : null;
 };
 
 /** Whether another live `blume dev` holds the lock on `outDir`. */
@@ -110,10 +217,6 @@ const lockPayload = (port?: number): string => {
   return JSON.stringify(info);
 };
 
-const writeLock = (outDir: string, port?: number): void => {
-  writeFileSync(lockPath(outDir), lockPayload(port));
-};
-
 /** Thrown when another live `blume dev` already holds the lock. */
 export class DevLockHeldError extends Error {
   readonly lock: DevLockInfo;
@@ -138,43 +241,58 @@ const ownsLock = (outDir: string): boolean => {
 };
 
 /**
- * One atomic claim attempt. Returns `true` when this process wins the `wx`
- * write, `false` when the dir held a stale or our-own leftover lock (now
- * cleared, so the caller should retry). Throws {@link DevLockHeldError} when a
- * live foreign holder owns the dir.
+ * Clear a claimable lock without racing anyone else doing the same. Two
+ * processes can both read the same stale lock; if each simply deleted the
+ * file, the slower one could delete the lock the faster one had claimed in
+ * between, and both would win. So removing a lock takes the reap mutex
+ * (created the same atomic way), and whoever holds it reads the lock again
+ * first: a live lock claimed since is left alone. A mutex whose holder died
+ * mid-reap is cleared for the next attempt.
  */
-const tryClaimLock = (outDir: string, port?: number): boolean => {
-  try {
-    writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
-    return true;
-  } catch (error) {
-    // SAFETY: `writeFileSync` failures are errno exceptions.
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-      throw error;
+const reapStaleLock = (outDir: string): void => {
+  const mutex = reapPath(outDir);
+  if (!createExclusive(mutex, lockPayload())) {
+    const holder = readIfExists(mutex);
+    const pid = holder ? parseLock(holder.raw)?.pid : undefined;
+    if (pid !== undefined && pid !== process.pid && isProcessAlive(pid)) {
+      pause(RETRY_DELAY_MS);
+    } else if (holder) {
+      rmSync(mutex, { force: true });
     }
-    const existing = readDevLock(outDir);
-    if (existing && existing.pid !== process.pid) {
-      throw new DevLockHeldError(existing);
+    return;
+  }
+  try {
+    if (isClaimable(inspectLock(outDir))) {
+      rmSync(lockPath(outDir), { force: true });
     }
-    // Stale or our own leftover: clear it and race for the claim again.
-    rmSync(lockPath(outDir), { force: true });
-    return false;
+  } finally {
+    rmSync(mutex, { force: true });
   }
 };
 
 /**
  * Write the current process's dev lock into `outDir` and return a release
- * function. The claim is atomic (`wx`): two `blume dev` processes racing the
- * same dir can't both pass a check-then-write — the loser gets a
- * {@link DevLockHeldError} naming the live holder. A stale lock (dead pid) or
- * this process's own leftover is cleared and re-claimed. The release only
- * removes the file if it's still ours, so a newer dev server's lock is never
- * clobbered.
+ * function. Two `blume dev` processes starting at the same moment can't both
+ * win: the lock appears whole and exclusively (a hard link, which fails when
+ * the file exists), a lock still being written is waited on rather than read
+ * as stale, and a stale lock (dead pid) or this process's own leftover is only
+ * cleared under the reap mutex — the loser gets a {@link DevLockHeldError}
+ * naming the live holder. The release only removes the file if it's still
+ * ours, so a newer dev server's lock is never clobbered.
  */
 export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
   mkdirSync(outDir, { recursive: true });
-  while (!tryClaimLock(outDir, port)) {
-    // Retry until we win the claim or a live holder makes us throw.
+  const payload = lockPayload(port);
+  while (!createExclusive(lockPath(outDir), payload)) {
+    const state = inspectLock(outDir);
+    if (isClaimable(state)) {
+      reapStaleLock(outDir);
+    } else if (state.kind === "live") {
+      throw new DevLockHeldError(state.lock);
+    } else if (state.kind === "busy") {
+      pause(RETRY_DELAY_MS);
+    }
+    // "absent": the holder released it just now — race for the claim again.
   }
   let released = false;
   return () => {
@@ -199,7 +317,9 @@ export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
  */
 export const updateDevLockPort = (outDir: string, port: number): void => {
   if (ownsLock(outDir)) {
-    writeLock(outDir, port);
+    // Replaced in one step: rewriting in place would leave a moment where a
+    // concurrent claim reads an empty lock.
+    replaceFile(lockPath(outDir), lockPayload(port));
   }
 };
 

package/src/cli/index.ts

@@ -81,6 +81,11 @@ const main = defineCommand({
       () => import("./commands/preview.ts"),
       "previewCommand"
     ),
+    skill: lazyCommand(
+      commandMeta.skill,
+      () => import("./commands/skill.ts"),
+      "skillCommand"
+    ),
     sync: lazyCommand(
       commandMeta.sync,
       () => import("./commands/sync.ts"),

package/src/cli/report-format.ts

@@ -11,12 +11,17 @@ export const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
 export const money = (cost: number | undefined): string =>
   cost === undefined ? "" : `$${cost.toFixed(2)}`;
 
-/** Milliseconds as `12.3s` under a minute, `4m 12s` from there up. */
+/**
+ * Milliseconds as `12.3s` under a minute, `4m 12s` from there up. Rounding
+ * happens before the split, so a value just under a boundary carries over
+ * (`59_990` → `1m 0s`, `119_700` → `2m 0s`) instead of printing `60.0s` or
+ * `1m 60s`.
+ */
 export const duration = (ms: number): string => {
-  if (ms < 60_000) {
-    return seconds(ms);
+  const tenths = Math.round(ms / 100);
+  if (tenths < 600) {
+    return `${(tenths / 10).toFixed(1)}s`;
   }
-  const minutes = Math.floor(ms / 60_000);
-  const rest = Math.round((ms % 60_000) / 1000);
-  return `${minutes}m ${rest}s`;
+  const total = Math.round(ms / 1000);
+  return `${Math.floor(total / 60)}m ${total % 60}s`;
 };

package/src/cli/required-secrets.ts

@@ -2,6 +2,60 @@ import { resolveAskBackend } from "../ai/ask.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import type { Diagnostic } from "../core/types.ts";
 
+/** A feature, and the secrets the adapter behind it reads. */
+interface SecretOwner {
+  feature: string;
+  note?: string;
+  secrets: string[];
+}
+
+/**
+ * The adapters that name their own secrets. The built-ins mostly declare
+ * none: analytics ships public tokens in the page, consent managers load
+ * public scripts, reference adapters read public specs, and host adapters
+ * read platform-injected env.
+ */
+const adapterSecretOwners = (config: ResolvedConfig): SecretOwner[] => {
+  const { consent, deployment, rateLimit } = config;
+  const { provider } = config.search;
+  const owners: SecretOwner[] = [
+    // Each search adapter declares the secrets its generated runtime reads.
+    { feature: `Search (${provider.kind})`, secrets: provider.requiredSecrets },
+    ...config.analytics.map((adapter) => ({
+      feature: `Analytics (${adapter.kind})`,
+      secrets: adapter.requiredSecrets,
+    })),
+    // Each content source adapter declares the env vars its fetch reads.
+    ...config.content.sources.map((source) => ({
+      feature: `Content source (${source.kind})`,
+      secrets: source.requiredSecrets,
+    })),
+    ...config.reference.map((adapter) => ({
+      feature: `API reference (${adapter.kind})`,
+      secrets: adapter.requiredSecrets,
+    })),
+    {
+      feature: `Deployment (${deployment.kind})`,
+      secrets: deployment.requiredSecrets,
+    },
+  ];
+  if (consent) {
+    owners.push({
+      feature: `Consent (${consent.kind})`,
+      secrets: consent.requiredSecrets,
+    });
+  }
+  // Upstash's endpoint and token.
+  if (rateLimit) {
+    owners.push({
+      feature: `Rate limiting (${rateLimit.kind})`,
+      note: "read at request time; without it the routes count in memory",
+      secrets: rateLimit.requiredSecrets,
+    });
+  }
+  return owners;
+};
+
 /**
  * Warn early when an enabled feature needs a secret env var that isn't set, so
  * the failure surfaces at `blume dev`/`build` instead of at the first request in
@@ -26,47 +80,35 @@ export const checkRequiredSecrets = (config: ResolvedConfig): Diagnostic[] => {
 
   if (config.ai.assistant?.enabled && !config.ai.assistant.endpoint) {
     // The adapter descriptor names the env vars its route reads.
-    const { provider } = config.ai.assistant;
+    const { captcha, provider } = config.ai.assistant;
     const backend = resolveAskBackend(provider);
     for (const env of provider.requiredSecrets) {
       requireSecret(`Assistant (${backend.label})`, env, backend.secretNote);
     }
-  }
-
-  // Each search adapter declares the secrets its generated runtime reads.
-  const { provider } = config.search;
-  for (const env of provider.requiredSecrets) {
-    requireSecret(`Search (${provider.kind})`, env);
-  }
-
-  // Adapters name their own secrets; the built-in analytics adapters ship
-  // public tokens in the page and declare none.
-  for (const adapter of config.analytics) {
-    for (const env of adapter.requiredSecrets) {
-      requireSecret(`Analytics (${adapter.kind})`, env);
+    // The bot check's secret key, which the route verifies tokens with.
+    for (const env of captcha?.requiredSecrets ?? []) {
+      requireSecret(`Assistant bot check (${captcha?.kind})`, env);
     }
   }
 
-  // Each content source adapter declares the env vars its fetch reads.
-  for (const source of config.content.sources) {
-    for (const env of source.requiredSecrets) {
-      requireSecret(`Content source (${source.kind})`, env);
+  // Generated narration reads its key at build, not at runtime; without it the
+  // build skips the audio and pages read with browser voices.
+  const { narration } = config;
+  if (narration.enabled && narration.provider) {
+    for (const env of narration.provider.requiredSecrets) {
+      requireSecret(
+        "Narration audio",
+        env,
+        "read at build; without it pages use browser voices"
+      );
     }
   }
 
-  // Adapters name their own secrets; the built-in reference adapters read
-  // public specs and declare none.
-  for (const adapter of config.reference) {
-    for (const env of adapter.requiredSecrets) {
-      requireSecret(`API reference (${adapter.kind})`, env);
+  for (const owner of adapterSecretOwners(config)) {
+    for (const env of owner.secrets) {
+      requireSecret(owner.feature, env, owner.note);
     }
   }
 
-  // The deployment adapter names its own secrets; the built-in host adapters
-  // read platform-injected env and declare none.
-  for (const env of config.deployment.requiredSecrets) {
-    requireSecret(`Deployment (${config.deployment.kind})`, env);
-  }
-
   return diagnostics;
 };

package/src/components/BlumePage.astro

@@ -49,6 +49,7 @@ import TreeRoot from "./content/Tree.astro";
 import TreeFile from "./content/TreeFile.astro";
 import TreeFolder from "./content/TreeFolder.astro";
 import TypeTable from "./content/TypeTable.astro";
+import View from "./content/View.astro";
 import Visibility from "./content/Visibility.astro";
 import YouTube from "./content/YouTube.astro";
 
@@ -96,6 +97,7 @@ const components = {
   Tooltip,
   Tree,
   TypeTable,
+  View,
   Visibility,
   YouTube,
   ...extra,

package/src/components/colors.ts

@@ -49,6 +49,25 @@ export const STROKE = {
   yellow: "border-yellow-500/40 text-yellow-800 dark:text-yellow-300",
 } satisfies Record<Hue, string>;
 
+/**
+ * The theme accent's label color: the accent mixed halfway toward the
+ * foreground. The accent is whatever the site configures (a preset, any CSS
+ * color, or the neutral black/white default), so no fixed shade can promise
+ * the contrast rule above, and the raw accent as text misses it (every preset
+ * sits under 3.5:1 over its tint in light mode). Pulling it toward the
+ * foreground darkens it in light mode and lightens it in dark, since the
+ * foreground contrasts with the page by construction: every preset clears
+ * 7:1 over its 15% tint in both modes.
+ */
+const ACCENT_LABEL =
+  "text-[color-mix(in_oklab,var(--blume-accent)_50%,var(--blume-foreground))]";
+
+/** `TINT` for the theme accent (`<Badge variant="accent">`). */
+export const ACCENT_TINT = `bg-accent/15 ${ACCENT_LABEL}`;
+
+/** `STROKE` for the theme accent. */
+export const ACCENT_STROKE = `border-accent/40 ${ACCENT_LABEL}`;
+
 /** The neutral fallback every table falls through to. */
 export const MUTED = "bg-muted text-muted-foreground";
 

package/src/components/content/ApiEndpoint.astro

@@ -0,0 +1,18 @@
+---
+// The method and path at the top of a page with `api` frontmatter, as an
+// OpenAPI operation page shows them. `markdown/api-rail.ts` places it.
+import MethodBadge from "../openapi/MethodBadge.astro";
+import { readEndpointSpec } from "./api-page.ts";
+
+interface Props {
+  /** The endpoint, as the page's plugin wrote it. */
+  spec: string;
+}
+
+const { method, target } = readEndpointSpec(Astro.props.spec);
+---
+
+<div class="not-prose mb-6 flex flex-wrap items-center gap-3">
+  <MethodBadge method={method} />
+  <code class="break-all font-mono text-foreground text-sm">{target}</code>
+</div>

package/src/components/content/ApiField.astro

@@ -0,0 +1,79 @@
+---
+// The row behind `<ParamField>` and `<ResponseField>`: the name with its
+// labels, location, type, and flags, the default, then the description from
+// the slot, which may hold any MDX, nested fields in an `<Expandable>`
+// included. Styled like the OpenAPI reference's rows, so a hand-written API
+// page reads like a generated one. Narration skips it, as it does type tables.
+import { defaultLabel, isOn } from "./api-field.ts";
+import type { FieldValue, FlagProp } from "./api-field.ts";
+
+interface Props {
+  default?: FieldValue;
+  deprecated?: FlagProp;
+  location?: string;
+  name?: string;
+  post?: string[];
+  pre?: string[];
+  required?: FlagProp;
+  type?: string;
+}
+
+const {
+  default: value,
+  deprecated,
+  location,
+  name,
+  post = [],
+  pre = [],
+  required,
+  type,
+} = Astro.props;
+const shownDefault = defaultLabel(value);
+const labelClass =
+  "rounded bg-muted px-1.5 py-0.5 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide";
+---
+
+<div
+  class="border-border border-b py-4"
+  data-blume-field
+  data-blume-narration="skip"
+>
+  <div class="not-prose flex flex-wrap items-baseline gap-x-2 gap-y-1">
+    {pre.map((label) => <span class={labelClass}>{label}</span>)}
+    {name && <code class="font-mono text-foreground text-sm">{name}</code>}
+    {post.map((label) => <span class={labelClass}>{label}</span>)}
+    {location && <span class={labelClass}>{location}</span>}
+    {type && <span class="text-muted-foreground text-xs">{type}</span>}
+    {
+      isOn(required) && (
+        <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
+          required
+        </span>
+      )
+    }
+    {
+      isOn(deprecated) && (
+        <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
+          deprecated
+        </span>
+      )
+    }
+  </div>
+  {
+    shownDefault !== null && (
+      <div class="not-prose mt-2 text-muted-foreground text-xs">
+        Default:{" "}
+        <code class="rounded bg-muted px-1 py-0.5 text-foreground">
+          {shownDefault}
+        </code>
+      </div>
+    )
+  }
+  {
+    Astro.slots.has("default") && (
+      <div class="mt-2 text-muted-foreground text-sm [&>:first-child]:mt-0 [&>:last-child]:mb-0">
+        <slot />
+      </div>
+    )
+  }
+</div>