@1agh/maude 0.43.0 → 0.45.0

package/apps/studio/generation/jobs.ts

@@ -0,0 +1,243 @@
+// generation/jobs.ts — the background AI-media generation job queue (DDR-16x).
+//
+// Modelled on exporters/jobs.ts: `enqueue()` returns immediately with a job id +
+// a Promise, the job progresses queued → running → done|failed in the
+// background, and `bus.emit('generate:job', job)` fires on every transition so
+// ws.ts can push a live snapshot to the notification center (reusing the
+// export-center chrome). Concurrency is capped by the same hand-rolled counting
+// semaphore (no new dependency).
+//
+// Unlike exports there is NO per-job byte store — a generation's output is a set
+// of `assets/<sha8>.<ext>` rel paths that already live in the durable,
+// content-addressed asset store (the job just records the paths). The only
+// on-disk state is a small `_generate-history.json` ledger (DDR-115 runtime
+// state — registered in all three ignore lists) so the notification center
+// survives a restart. Job records themselves are in-memory only.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import type { Bus } from '../context.ts';
+import type { Modality } from './types.ts';
+
+export type GenerationJobStatus = 'queued' | 'running' | 'done' | 'failed';
+
+export interface GenerationJob {
+  id: string;
+  provider: string;
+  modality: Modality;
+  model?: string;
+  status: GenerationJobStatus;
+  progress?: number;
+  createdAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  /** `assets/<sha8>.<ext>` rel paths produced by this job. */
+  assets?: string[];
+  usage?: { cost?: number; ms?: number };
+  error?: string;
+}
+
+/** The one job's work — submit → result → localize each asset. Given the abort
+ *  signal so a timed-out/cancelled job tears down its provider request. */
+export type GenerationRun = (
+  signal: AbortSignal
+) => Promise<{ assets: string[]; usage?: { cost?: number; ms?: number } }>;
+
+export interface EnqueueGenArgs {
+  provider: string;
+  modality: Modality;
+  model?: string;
+  run: GenerationRun;
+}
+
+export interface GenerationHistoryEntry {
+  id: string;
+  provider: string;
+  modality: string;
+  model?: string;
+  status: 'done' | 'failed';
+  assets?: string[];
+  at: string;
+  error?: string;
+}
+
+export interface GenerationJobQueue {
+  enqueue(args: EnqueueGenArgs): { id: string; result: Promise<GenerationJob> };
+  get(id: string): GenerationJob | undefined;
+  list(): GenerationJob[];
+  loadHistory(): GenerationHistoryEntry[];
+}
+
+const HISTORY_DEPTH = 20;
+const MAX_JOB_AGE_MS = 24 * 60 * 60 * 1000;
+// Generation spans sync image (seconds) → async video (minutes). Size generously
+// but bound it so a wedged provider request can't hold a slot forever.
+const DEFAULT_JOB_TIMEOUT_MS = Math.max(
+  30_000,
+  Number(process.env.MAUDE_GENERATE_TIMEOUT_MS) || 10 * 60 * 1000
+);
+
+export class GenerationQueueFullError extends Error {
+  constructor() {
+    super('generation queue is full — too many pending jobs, try again shortly');
+    this.name = 'GenerationQueueFullError';
+  }
+}
+
+/** Small counting semaphore — mirrors exporters/jobs.ts's Semaphore. */
+class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+  constructor(private readonly max: number) {}
+  async acquire(): Promise<() => void> {
+    if (this.active >= this.max) {
+      await new Promise<void>((resolve) => this.waiters.push(resolve));
+    }
+    this.active += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.active -= 1;
+      const next = this.waiters.shift();
+      if (next) next();
+    };
+  }
+}
+
+function isFinished(job: GenerationJob): boolean {
+  return job.status === 'done' || job.status === 'failed';
+}
+
+export function createGenerationJobQueue(bus: Bus, designRoot: string): GenerationJobQueue {
+  const historyPath = path.join(designRoot, '_generate-history.json');
+  const maxConcurrent = Math.max(1, Number(process.env.MAUDE_GENERATE_MAX_CONCURRENT) || 2);
+  // Bound queued+running jobs — a flood of POSTs must not grow the Map unbounded
+  // (the backpressure the background export queue added). Read per-instance so
+  // it's env-overridable at construction (mirrors maxConcurrent).
+  const maxPending = Math.max(1, Number(process.env.MAUDE_GENERATE_MAX_QUEUED) || 12);
+  const semaphore = new Semaphore(maxConcurrent);
+  const jobs = new Map<string, GenerationJob>();
+
+  // Seed the ledger from disk ONCE (the only read). Every later persist derives
+  // fresh from `jobs` and overwrites — no read-modify-write, so concurrent
+  // completions can't drop entries.
+  try {
+    const parsed = JSON.parse(readFileSync(historyPath, 'utf8')) as unknown;
+    if (Array.isArray(parsed)) {
+      for (const entry of parsed) {
+        if (!entry || typeof entry !== 'object') continue;
+        const e = entry as Record<string, unknown>;
+        const id = typeof e.id === 'string' && e.id ? e.id : crypto.randomUUID();
+        jobs.set(id, {
+          id,
+          provider: String(e.provider ?? ''),
+          modality: (e.modality as Modality) ?? 'image',
+          model: e.model as string | undefined,
+          status: e.status === 'failed' ? 'failed' : 'done',
+          createdAt: (e.at as string) ?? new Date().toISOString(),
+          finishedAt: e.at as string | undefined,
+          assets: Array.isArray(e.assets) ? (e.assets as string[]) : undefined,
+          error: e.error as string | undefined,
+        });
+      }
+    }
+  } catch {
+    /* no ledger yet — start empty */
+  }
+
+  function emit(job: GenerationJob): void {
+    bus.emit('generate:job', { ...job });
+  }
+
+  function deriveHistory(): GenerationHistoryEntry[] {
+    return Array.from(jobs.values())
+      .filter(isFinished)
+      .sort((a, b) => (b.finishedAt ?? '').localeCompare(a.finishedAt ?? ''))
+      .slice(0, HISTORY_DEPTH)
+      .map((j) => ({
+        id: j.id,
+        provider: j.provider,
+        modality: j.modality,
+        model: j.model,
+        status: j.status as 'done' | 'failed',
+        assets: j.assets,
+        at: j.finishedAt ?? j.createdAt,
+        error: j.error,
+      }));
+  }
+
+  async function persistAndEvict(): Promise<void> {
+    await Bun.write(historyPath, JSON.stringify(deriveHistory(), null, 2));
+    const finished = Array.from(jobs.values())
+      .filter(isFinished)
+      .sort((a, b) => (b.finishedAt ?? '').localeCompare(a.finishedAt ?? ''));
+    const now = Date.now();
+    for (const [i, job] of finished.entries()) {
+      const finishedAt = job.finishedAt ? Date.parse(job.finishedAt) : Number.NaN;
+      const aged = Number.isFinite(finishedAt) && now - finishedAt > MAX_JOB_AGE_MS;
+      if (i >= HISTORY_DEPTH || aged) jobs.delete(job.id);
+    }
+  }
+
+  function enqueue(args: EnqueueGenArgs): { id: string; result: Promise<GenerationJob> } {
+    let pending = 0;
+    for (const job of jobs.values()) {
+      if (job.status === 'queued' || job.status === 'running') pending += 1;
+    }
+    if (pending >= maxPending) throw new GenerationQueueFullError();
+
+    const id = `gen_${crypto.randomUUID()}`;
+    const job: GenerationJob = {
+      id,
+      provider: args.provider,
+      modality: args.modality,
+      model: args.model,
+      status: 'queued',
+      createdAt: new Date().toISOString(),
+    };
+    jobs.set(id, job);
+    emit(job);
+
+    const controller = new AbortController();
+    const result = (async (): Promise<GenerationJob> => {
+      const release = await semaphore.acquire();
+      const timer = setTimeout(() => controller.abort(), DEFAULT_JOB_TIMEOUT_MS);
+      try {
+        job.status = 'running';
+        job.startedAt = new Date().toISOString();
+        emit(job);
+
+        const out = await args.run(controller.signal);
+
+        job.status = 'done';
+        job.finishedAt = new Date().toISOString();
+        job.assets = out.assets;
+        job.usage = out.usage;
+        emit(job);
+        await persistAndEvict();
+        return job;
+      } catch (err) {
+        job.status = 'failed';
+        job.finishedAt = new Date().toISOString();
+        job.error = err instanceof Error ? err.message : String(err);
+        emit(job);
+        await persistAndEvict();
+        throw err;
+      } finally {
+        clearTimeout(timer);
+        release();
+      }
+    })();
+
+    return { id, result };
+  }
+
+  return {
+    enqueue,
+    get: (id) => jobs.get(id),
+    list: () => Array.from(jobs.values()).sort((a, b) => b.createdAt.localeCompare(a.createdAt)),
+    loadHistory: deriveHistory,
+  };
+}

package/apps/studio/generation/keys.test.ts

@@ -0,0 +1,75 @@
+// generation/keys.test.ts — key custody: 0600 mode assert, round-trip, and
+// missing-key returns null. Points MAUDE_GEN_KEYS_PATH at a sandbox file so the
+// user's real ~/.config/maude/keys.json is never touched.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
+import { platform, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  configuredProviders,
+  deleteProviderKey,
+  getProviderKey,
+  isConfigured,
+  keysConfigPath,
+  setProviderKey,
+} from './keys.ts';
+
+let dir: string;
+const prevPath = process.env.MAUDE_GEN_KEYS_PATH;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'maude-keys-'));
+  process.env.MAUDE_GEN_KEYS_PATH = join(dir, 'keys.json');
+});
+
+afterEach(() => {
+  if (prevPath === undefined) delete process.env.MAUDE_GEN_KEYS_PATH;
+  else process.env.MAUDE_GEN_KEYS_PATH = prevPath;
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('generation key custody', () => {
+  test('missing key resolves to null; isConfigured false', async () => {
+    expect(await getProviderKey('gemini')).toBeNull();
+    expect(isConfigured('gemini')).toBe(false);
+    expect(configuredProviders()).toEqual([]);
+  });
+
+  test('set → get round-trips and reports configured', async () => {
+    setProviderKey('gemini', 'AIza-secret-123');
+    expect(await getProviderKey('gemini')).toBe('AIza-secret-123');
+    expect(isConfigured('gemini')).toBe(true);
+    expect(configuredProviders()).toContain('gemini');
+  });
+
+  test('the keys file is written mode 0600', () => {
+    setProviderKey('elevenlabs', 'sk-eleven');
+    const path = keysConfigPath();
+    expect(existsSync(path)).toBe(true);
+    if (platform() !== 'win32') {
+      const mode = statSync(path).mode & 0o777;
+      expect(mode).toBe(0o600);
+    }
+  });
+
+  test('set trims whitespace and rejects empties', () => {
+    setProviderKey('gemini', '  padded-key  ');
+    expect(isConfigured('gemini')).toBe(true);
+    expect(() => setProviderKey('gemini', '   ')).toThrow();
+  });
+
+  test('delete removes the key', async () => {
+    setProviderKey('gemini', 'k');
+    deleteProviderKey('gemini');
+    expect(await getProviderKey('gemini')).toBeNull();
+    expect(isConfigured('gemini')).toBe(false);
+  });
+
+  test('a malformed provider id never resolves or writes', async () => {
+    expect(await getProviderKey('../etc')).toBeNull();
+    expect(() => setProviderKey('../etc', 'x')).toThrow();
+    expect(isConfigured('../etc')).toBe(false);
+  });
+});

package/apps/studio/generation/keys.ts

@@ -0,0 +1,162 @@
+// generation/keys.ts — BYOK provider-key custody for AI media generation (DDR-16x).
+//
+// Keys live OUTSIDE the served `.design/` tree so a canvas file-route can never
+// read them: `~/.config/maude/keys.json`, mode 0600 (XDG-aware, same location
+// discipline as sync/hubs-config.ts's hubs.json). A provider key is resolved at
+// REQUEST TIME and NEVER cached, logged, or returned to the canvas realm — the
+// exact template is github/token.ts (fetch-at-request-time, null when absent).
+//
+// Native tier (Phase 5.1, DDR-16x): when the Tauri keychain bridge env is
+// present (`MAUDE_GEN_KEY_ENDPOINT`/`_KEY`, mirroring MAUDE_TOKEN_ENDPOINT for
+// GitHub), `getProviderKey` prefers the keychain over the file. The bridge is
+// not wired in Phase 0 — the hook is here so `keys.ts` never has to change when
+// the native keychain lands; the file store is the whole Phase-0 custody.
+//
+// The Settings panel POSTs a key to a PRIVILEGED main-origin route which calls
+// `setProviderKey`; that route NEVER echoes a key back (it returns
+// `{ configured: true }`, mirroring `github_is_signed_in`). `isConfigured` backs
+// the GET status probe — it reveals only presence, never the value.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** Slug-shaped provider id — the JSON key + keychain lookup. Never a path. */
+const PROVIDER_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Resolve the on-disk path to keys.json (mirrors hubs-config.ts's XDG logic). */
+export function keysConfigPath(): string {
+  if (process.env.MAUDE_GEN_KEYS_PATH) return process.env.MAUDE_GEN_KEYS_PATH;
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
+  return join(base, 'maude', 'keys.json');
+}
+
+interface KeysFile {
+  keys: Record<string, string>;
+}
+
+let _modeWarnedFor: string | null = null;
+function warnIfWorldOrGroupReadable(path: string): void {
+  if (platform() === 'win32') return; // POSIX-mode semantics don't apply
+  if (_modeWarnedFor === path) return;
+  try {
+    const mode = statSync(path).mode & 0o777;
+    if ((mode & 0o077) !== 0) {
+      console.warn(
+        `[generation] ${path} is mode ${mode.toString(8)} — recommend 'chmod 600 ${path}' (only owner can read provider keys).`
+      );
+      _modeWarnedFor = path;
+    }
+  } catch {
+    /* raced with a delete — next read retries */
+  }
+}
+
+function readKeysFile(): KeysFile {
+  const path = keysConfigPath();
+  if (!existsSync(path)) return { keys: {} };
+  warnIfWorldOrGroupReadable(path);
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed.keys !== 'object' || parsed.keys === null) return { keys: {} };
+    return parsed as KeysFile;
+  } catch {
+    return { keys: {} };
+  }
+}
+
+/** Write keys.json atomically-ish with a hard 0600 mode (create + chmod). */
+function writeKeysFile(data: KeysFile): void {
+  const path = keysConfigPath();
+  mkdirSync(dirname(path), { recursive: true });
+  // Write then chmod — writeFileSync's mode is masked by umask, so we assert
+  // 0600 explicitly afterwards (same guarantee cli/lib/hubs-config.mjs makes).
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  if (platform() !== 'win32') {
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      /* best-effort — the warn-on-read path is the backstop */
+    }
+  }
+}
+
+/** Whether the native keychain bridge is configured (Phase 5.1 / DDR-16x). */
+function keychainBridgeAvailable(): boolean {
+  return Boolean(process.env.MAUDE_GEN_KEY_ENDPOINT && process.env.MAUDE_GEN_KEY_KEY);
+}
+
+/** Fetch a key from the Tauri keychain bridge over loopback (Phase 5.1). */
+async function getKeyFromBridge(providerId: string): Promise<string | null> {
+  const endpoint = process.env.MAUDE_GEN_KEY_ENDPOINT;
+  const key = process.env.MAUDE_GEN_KEY_KEY;
+  if (!endpoint || !key) return null;
+  try {
+    const res = await fetch(`${endpoint}?provider=${encodeURIComponent(providerId)}`, {
+      headers: { 'X-Maude-Token-Key': key },
+      signal: AbortSignal.timeout(3000),
+    });
+    if (res.status !== 200) return null; // 404 = not set; 403 = bad key
+    const token = (await res.text()).trim();
+    return token.length > 0 ? token : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a provider's API key at request time. Prefers the native keychain
+ * bridge when present, otherwise the 0600 file. Returns null when unset (the
+ * caller degrades to "add a key in Settings"). NEVER cache the result — a key
+ * can be rotated in Settings and the store is the single source of truth.
+ */
+export async function getProviderKey(providerId: string): Promise<string | null> {
+  if (!PROVIDER_ID_RE.test(providerId)) return null;
+  if (keychainBridgeAvailable()) {
+    const fromBridge = await getKeyFromBridge(providerId);
+    if (fromBridge) return fromBridge;
+    // Fall through to the file store even under the bridge, so a key added via
+    // the browser Settings panel still resolves in the native app.
+  }
+  const key = readKeysFile().keys[providerId];
+  return typeof key === 'string' && key.length > 0 ? key : null;
+}
+
+/** Persist a provider key to the 0600 file store (Settings panel write path). */
+export function setProviderKey(providerId: string, value: string): void {
+  if (!PROVIDER_ID_RE.test(providerId)) throw new Error('invalid provider id');
+  const trimmed = value.trim();
+  if (!trimmed) throw new Error('empty key');
+  const file = readKeysFile();
+  file.keys[providerId] = trimmed;
+  writeKeysFile(file);
+}
+
+/** Remove a provider key (Settings "remove key"). No-op when absent. */
+export function deleteProviderKey(providerId: string): void {
+  if (!PROVIDER_ID_RE.test(providerId)) return;
+  const file = readKeysFile();
+  if (providerId in file.keys) {
+    delete file.keys[providerId];
+    writeKeysFile(file);
+  }
+}
+
+/**
+ * Presence-only check for the status GET. Reveals whether a key exists (file or
+ * bridge) — NEVER the value. Synchronous file check + a cheap bridge-present
+ * signal (the bridge itself is only queried at real request time).
+ */
+export function isConfigured(providerId: string): boolean {
+  if (!PROVIDER_ID_RE.test(providerId)) return false;
+  const key = readKeysFile().keys[providerId];
+  return typeof key === 'string' && key.length > 0;
+}
+
+/** The set of provider ids that currently have a key configured (file store). */
+export function configuredProviders(): string[] {
+  return Object.entries(readKeysFile().keys)
+    .filter(([, v]) => typeof v === 'string' && v.length > 0)
+    .map(([id]) => id);
+}

package/apps/studio/generation/prefs.test.ts

@@ -0,0 +1,95 @@
+// prefs.test.ts — non-secret generation preferences (Task 2.6). The transcription
+// engine choice must round-trip through `.design/config.json`, default to whisper
+// when unset, reject an invalid engine, and NEVER clobber other config fields.
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  isTranscriptionProvider,
+  readTranscriptionProvider,
+  writeTranscriptionProvider,
+} from './prefs.ts';
+
+function tmpRepo(config?: unknown): string {
+  const root = mkdtempSync(join(tmpdir(), 'maude-prefs-'));
+  mkdirSync(join(root, '.design'), { recursive: true });
+  if (config !== undefined)
+    writeFileSync(join(root, '.design', 'config.json'), JSON.stringify(config, null, 2));
+  return root;
+}
+
+describe('isTranscriptionProvider', () => {
+  test('accepts the three engines, rejects anything else', () => {
+    expect(isTranscriptionProvider('whisper')).toBe(true);
+    expect(isTranscriptionProvider('elevenlabs')).toBe(true);
+    expect(isTranscriptionProvider('groq')).toBe(true);
+    expect(isTranscriptionProvider('openai')).toBe(false);
+    expect(isTranscriptionProvider('')).toBe(false);
+    expect(isTranscriptionProvider(null)).toBe(false);
+  });
+});
+
+describe('readTranscriptionProvider', () => {
+  test('defaults to whisper when no config exists', () => {
+    expect(readTranscriptionProvider(tmpRepo())).toBe('whisper');
+  });
+
+  test('defaults to whisper when the block is absent', () => {
+    expect(readTranscriptionProvider(tmpRepo({ name: 'x' }))).toBe('whisper');
+  });
+
+  test('reads a configured engine', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'groq' } } });
+    expect(readTranscriptionProvider(repo)).toBe('groq');
+  });
+
+  test('ignores a malformed engine value', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'bogus' } } });
+    expect(readTranscriptionProvider(repo)).toBe('whisper');
+  });
+});
+
+describe('writeTranscriptionProvider', () => {
+  test('round-trips the choice', async () => {
+    const repo = tmpRepo({ name: 'x' });
+    await writeTranscriptionProvider(repo, 'elevenlabs');
+    expect(readTranscriptionProvider(repo)).toBe('elevenlabs');
+  });
+
+  test('preserves other config fields and other generation keys', async () => {
+    const repo = tmpRepo({
+      name: 'proj',
+      generation: { defaultImageProvider: 'gemini', transcription: { model: 'scribe_v1' } },
+    });
+    await writeTranscriptionProvider(repo, 'groq');
+    const cfg = JSON.parse(readFileSync(join(repo, '.design', 'config.json'), 'utf8'));
+    expect(cfg.name).toBe('proj');
+    expect(cfg.generation.defaultImageProvider).toBe('gemini');
+    expect(cfg.generation.transcription.model).toBe('scribe_v1'); // sibling key kept
+    expect(cfg.generation.transcription.provider).toBe('groq');
+  });
+
+  test('creates the generation block when absent', async () => {
+    const repo = tmpRepo(); // no config file at all
+    await writeTranscriptionProvider(repo, 'whisper');
+    expect(readTranscriptionProvider(repo)).toBe('whisper');
+  });
+
+  test('rejects an invalid engine', async () => {
+    const repo = tmpRepo();
+    await expect(writeTranscriptionProvider(repo, 'openai')).rejects.toThrow(/invalid/);
+  });
+
+  test('fails closed on an existing-but-corrupt config (never clobbers it)', async () => {
+    const repo = mkdtempSync(join(tmpdir(), 'maude-prefs-'));
+    mkdirSync(join(repo, '.design'), { recursive: true });
+    const corrupt = '{ this is not json ';
+    writeFileSync(join(repo, '.design', 'config.json'), corrupt);
+    await expect(writeTranscriptionProvider(repo, 'groq')).rejects.toThrow(/valid JSON/);
+    // The corrupt file is left untouched, not overwritten with a partial config.
+    expect(readFileSync(join(repo, '.design', 'config.json'), 'utf8')).toBe(corrupt);
+  });
+});

package/apps/studio/generation/prefs.ts

@@ -0,0 +1,82 @@
+// generation/prefs.ts — read/write the NON-SECRET generation preferences in
+// `.design/config.json` (Task 2.6, DDR-164). The Settings panel's transcription-
+// engine selector persists here so the choice survives restarts and the
+// `maude design transcribe` CLI reads the same default.
+//
+// SECRET-FREE by construction: this module only ever touches the `generation`
+// block's non-secret routing/UI keys (provider ids, model ids, toggles). Keys
+// live in the OS keychain / ~/.config/maude/keys.json — NEVER here. The writer
+// preserves every other config field verbatim (additive merge over the parsed
+// JSON), so a hand-authored config is never clobbered.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The transcription engines the selector offers (mirrors the config schema enum). */
+export const TRANSCRIPTION_PROVIDERS = ['whisper', 'elevenlabs', 'groq'] as const;
+export type TranscriptionProvider = (typeof TRANSCRIPTION_PROVIDERS)[number];
+
+export function isTranscriptionProvider(v: unknown): v is TranscriptionProvider {
+  return typeof v === 'string' && (TRANSCRIPTION_PROVIDERS as readonly string[]).includes(v);
+}
+
+function configPath(repoRoot: string): string {
+  return join(repoRoot, '.design', 'config.json');
+}
+
+/** Parse `.design/config.json` (or {} when missing / unreadable). */
+function readConfig(repoRoot: string): Record<string, unknown> {
+  const p = configPath(repoRoot);
+  if (!existsSync(p)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The current transcription-engine preference, or 'whisper' (the default). */
+export function readTranscriptionProvider(repoRoot: string): TranscriptionProvider {
+  const cfg = readConfig(repoRoot);
+  const gen = cfg.generation as Record<string, unknown> | undefined;
+  const t = gen?.transcription as Record<string, unknown> | undefined;
+  return isTranscriptionProvider(t?.provider) ? (t?.provider as TranscriptionProvider) : 'whisper';
+}
+
+/**
+ * Persist the transcription-engine choice into `.design/config.json`, preserving
+ * every other field. Returns true on a successful write. Throws on an invalid
+ * provider (the route validates first, so this is a defensive guard).
+ */
+export async function writeTranscriptionProvider(
+  repoRoot: string,
+  provider: string
+): Promise<boolean> {
+  if (!isTranscriptionProvider(provider))
+    throw new Error(`invalid transcription provider: ${provider}`);
+  // Fail CLOSED on an existing-but-unparseable config: never overwrite a corrupt
+  // file with a generation-only block (that would silently drop the user's other
+  // settings). A MISSING file is fine — we start from {}. (Defender note, 2026-07-11.)
+  const p = configPath(repoRoot);
+  if (existsSync(p)) {
+    try {
+      JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      throw new Error(
+        '.design/config.json is present but not valid JSON — fix it before changing generation prefs (refusing to overwrite it)'
+      );
+    }
+  }
+  const cfg = readConfig(repoRoot);
+  const gen = (cfg.generation as Record<string, unknown>) ?? {};
+  const transcription = (gen.transcription as Record<string, unknown>) ?? {};
+  const next = {
+    ...cfg,
+    generation: { ...gen, transcription: { ...transcription, provider } },
+  };
+  await Bun.write(configPath(repoRoot), `${JSON.stringify(next, null, 2)}\n`);
+  return true;
+}