@1agh/maude 0.43.0 → 0.44.0

package/apps/studio/generation/whisper-models.ts

@@ -0,0 +1,257 @@
+// generation/whisper-models.ts — managed local whisper.cpp GGML models (Task 2.7,
+// approach A, DDR-164). The "one-click local subtitles" story WITHOUT a heavy
+// WASM dependency: keep the fast native whisper.cpp engine, but remove the
+// hand-fetch-a-ggml-from-Hugging-Face friction the owner hit in testing — a
+// Settings button downloads a model into a Maude-managed, gitignored cache and
+// `maude design transcribe --provider whisper` auto-resolves it (no --model).
+//
+// The whisper.cpp BINARY is still a soft dep (brew / build); this closes the
+// MODEL half of the friction. Models live OUTSIDE any served project tree (a
+// per-machine cache, re-downloadable), never in `.design/`, never committed.
+//
+// This module owns the model REGISTRY + dir + list/resolve (fs, server-side).
+// The actual download (streamed, SSRF-hardened, progress-tracked) lives in the
+// http route so the egress discipline sits next to the other provider egress.
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { mkdir, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export interface WhisperModelDescriptor {
+  /** Stable id used by the config + route (`base`, `base.en`, …). */
+  id: string;
+  /** The on-disk ggml filename. */
+  file: string;
+  label: string;
+  /** Approximate download size, for the consent copy + the download size cap. */
+  sizeMB: number;
+  /** Multilingual vs English-only (the owner's Czech-footage gotcha: `.en`
+   *  garbles non-English — surface this in the picker). */
+  multilingual: boolean;
+  note: string;
+}
+
+// The subset of ggerganov/whisper.cpp ggml models Maude offers. Kept small +
+// curated (a fixed allowlist — the download URL is derived from `file`, never
+// user input, so this is also the SSRF allowlist for the model host).
+export const WHISPER_MODELS: readonly WhisperModelDescriptor[] = [
+  {
+    id: 'tiny',
+    file: 'ggml-tiny.bin',
+    label: 'Tiny (multilingual)',
+    sizeMB: 75,
+    multilingual: true,
+    note: 'Fastest, lowest accuracy. Good for a quick draft in any language.',
+  },
+  {
+    id: 'base',
+    file: 'ggml-base.bin',
+    label: 'Base (multilingual)',
+    sizeMB: 142,
+    multilingual: true,
+    note: 'The recommended default — works in any language (incl. Czech). Modest accuracy.',
+  },
+  {
+    id: 'base.en',
+    file: 'ggml-base.en.bin',
+    label: 'Base (English-only)',
+    sizeMB: 142,
+    multilingual: false,
+    note: 'English audio only — do NOT use for other languages (it garbles them).',
+  },
+  {
+    id: 'small',
+    file: 'ggml-small.bin',
+    label: 'Small (multilingual)',
+    sizeMB: 466,
+    multilingual: true,
+    note: 'Noticeably more accurate than base, ~3× larger.',
+  },
+  {
+    id: 'large-v3-turbo',
+    file: 'ggml-large-v3-turbo.bin',
+    label: 'Large v3 Turbo (multilingual)',
+    sizeMB: 1560,
+    multilingual: true,
+    note: 'Best accuracy, ~1.5 GB. Slower and disk-heavy, but close to cloud quality.',
+  },
+];
+
+const MODEL_HOST = 'https://huggingface.co';
+const MODEL_REPO_PATH = '/ggerganov/whisper.cpp/resolve/main';
+
+/** The fixed, non-interpolated download URL for a model (SSRF-safe — the file
+ *  comes from the frozen registry above, never from a request). */
+export function whisperModelUrl(m: WhisperModelDescriptor): string {
+  return `${MODEL_HOST}${MODEL_REPO_PATH}/${m.file}`;
+}
+
+export function getWhisperModel(id: unknown): WhisperModelDescriptor | null {
+  return WHISPER_MODELS.find((m) => m.id === id) ?? null;
+}
+
+/** Maude-managed model cache dir — per-machine, gitignored, never in a project.
+ *  XDG_CACHE_HOME-aware (falls back to ~/.cache), mirroring keys.ts's XDG logic
+ *  but a CACHE location (large, re-downloadable) not a config one. */
+export function whisperModelsDir(): string {
+  const xdg = process.env.XDG_CACHE_HOME;
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.cache');
+  return join(base, 'maude', 'whisper-models');
+}
+
+export interface WhisperModelStatus extends WhisperModelDescriptor {
+  downloaded: boolean;
+  /** Absolute path when downloaded. */
+  path?: string;
+  /** Actual on-disk bytes when downloaded (for the "Remove" affordance). */
+  bytes?: number;
+}
+
+/** The absolute on-disk path a model WOULD live at (whether present or not). */
+export function whisperModelPath(m: WhisperModelDescriptor): string {
+  return join(whisperModelsDir(), m.file);
+}
+
+/** Every registered model + whether it's already downloaded. */
+export function listWhisperModels(): WhisperModelStatus[] {
+  return WHISPER_MODELS.map((m) => {
+    const p = whisperModelPath(m);
+    let downloaded = false;
+    let bytes: number | undefined;
+    try {
+      const st = statSync(p);
+      if (st.isFile() && st.size > 0) {
+        downloaded = true;
+        bytes = st.size;
+      }
+    } catch {
+      /* not downloaded */
+    }
+    return { ...m, downloaded, ...(downloaded ? { path: p, bytes } : {}) };
+  });
+}
+
+/**
+ * Resolve a downloaded model's path for `maude design transcribe` (no --model
+ * needed once one is downloaded). Preference order: the caller-preferred id
+ * (from `generation.transcription.whisperModel`) → any downloaded MULTILINGUAL
+ * model (safe for non-English) → any downloaded model → null.
+ */
+export function resolveWhisperModel(preferId?: string): string | null {
+  const dir = whisperModelsDir();
+  if (!existsSync(dir)) return null;
+  let present: Set<string>;
+  try {
+    present = new Set(readdirSync(dir));
+  } catch {
+    return null;
+  }
+  const has = (m: WhisperModelDescriptor) => present.has(m.file);
+  if (preferId) {
+    const pref = getWhisperModel(preferId);
+    if (pref && has(pref)) return join(dir, pref.file);
+  }
+  const multi = WHISPER_MODELS.find((m) => m.multilingual && has(m));
+  if (multi) return join(dir, multi.file);
+  const any = WHISPER_MODELS.find(has);
+  return any ? join(dir, any.file) : null;
+}
+
+/**
+ * Download one model into the managed cache, streamed with a progress callback
+ * (Task 2.7). Egress discipline: the URL is derived from the FROZEN registry
+ * (initial host is always huggingface.co, asserted https + fixed host); the
+ * redirect the HF blob store issues is followed but the FINAL hop is re-asserted
+ * https + a `*.huggingface.co` host (ethical-hacker Finding 2); the body is
+ * size-capped per-chunk to the model's expected size (+20% margin) before it can
+ * fill the disk; written to a `.part` temp and atomically renamed so a
+ * partial/aborted download never looks complete. Pass an AbortSignal (a timeout)
+ * so a stalled connection can't wedge the single download slot. Not a full
+ * `_fetch-asset.mjs` (no resolved-IP private-range guard) — proportionate because
+ * the host is pinned to HF and the route is loopback + same-origin only. Throws
+ * on any failure (the temp file is cleaned up); the caller owns progress state.
+ */
+export async function downloadWhisperModel(
+  id: string,
+  onProgress: (received: number, total: number) => void,
+  signal?: AbortSignal
+): Promise<string> {
+  const m = getWhisperModel(id);
+  if (!m) throw new Error(`unknown whisper model: ${id}`);
+  const url = whisperModelUrl(m);
+  const u = new URL(url);
+  if (u.protocol !== 'https:') throw new Error('model URL must be https');
+  if (u.hostname !== 'huggingface.co') throw new Error('model host not allowlisted');
+
+  const dir = whisperModelsDir();
+  await mkdir(dir, { recursive: true });
+  const finalPath = join(dir, m.file);
+  const tmpPath = `${finalPath}.part`;
+
+  const cap = Math.ceil(m.sizeMB * 1.2) * 1024 * 1024; // expected size + 20% margin
+  // huggingface.co 302-redirects model blobs to its own LFS CDN, so we must
+  // follow — but re-assert the FINAL hop is still https + a huggingface.co host
+  // (ethical-hacker Finding 2): an open-redirect/on-path must not land the fetch
+  // on an arbitrary host. A wall-clock timeout is layered by the caller's signal.
+  const res = await fetch(url, { signal, redirect: 'follow' });
+  try {
+    const finalUrl = new URL(res.url || url);
+    if (finalUrl.protocol !== 'https:' || !/(^|\.)huggingface\.co$/.test(finalUrl.hostname))
+      throw new Error(`model download redirected off huggingface.co (${finalUrl.hostname})`);
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith('model download redirected')) throw err;
+    throw new Error('model download resolved to an invalid URL');
+  }
+  if (!res.ok) throw new Error(`model download failed: HTTP ${res.status}`);
+  const declared = Number(res.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > cap)
+    throw new Error(`model larger than expected (${declared} > ${cap} bytes)`);
+  const total = Number.isFinite(declared) && declared > 0 ? declared : m.sizeMB * 1024 * 1024;
+
+  const body = res.body;
+  if (!body) throw new Error('empty model response');
+  const reader = body.getReader();
+  const writer = Bun.file(tmpPath).writer();
+  let received = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        received += value.byteLength;
+        if (received > cap) throw new Error(`model exceeded ${cap} bytes`);
+        writer.write(value);
+        onProgress(received, total);
+      }
+    }
+    await writer.end();
+    if (received === 0) throw new Error('model download was empty');
+    await rename(tmpPath, finalPath);
+    return finalPath;
+  } catch (err) {
+    try {
+      await writer.end();
+    } catch {
+      /* ignore */
+    }
+    await rm(tmpPath, { force: true }).catch(() => {});
+    throw err;
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      /* already released */
+    }
+  }
+}
+
+/** Remove a downloaded model (reclaim disk). Returns true if a file was removed. */
+export async function removeWhisperModel(id: string): Promise<boolean> {
+  const m = getWhisperModel(id);
+  if (!m) return false;
+  const p = whisperModelPath(m);
+  if (!existsSync(p)) return false;
+  await rm(p, { force: true });
+  return true;
+}

package/apps/studio/generation/whisper-spike-results.md

@@ -0,0 +1,61 @@
+# Task 2.7 feasibility spike — transformers.js whisper (word timestamps in the sidecar)
+
+**Date:** 2026-07-11 · **Spike verdict: B is functionally feasible.** · **Build outcome: approach A shipped** (B blocked on a native-dep / DDR-070 conflict — see the resolution note at the bottom).
+
+The plan gated the one-click local-subtitle build on a spike (DDR-164 Open-Question 7):
+in-process transformers.js whisper must produce word-level timestamps, at tolerable
+speed + memory, running MAIN-origin / in the sidecar (not the untrusted canvas realm).
+
+## Result (Node sidecar, `@huggingface/transformers` v3, `onnx-community/whisper-base_timestamped`, q8)
+
+| Criterion | Measured | Gate |
+| --- | --- | --- |
+| Word-level timestamps | `hasWordTimestamps: true` — `"And" [0.22–0.52] "so" [0.52–0.84] "my" [0.84–1.2]…` | ✅ |
+| Transcript accuracy | "And so my fellow Americans ask not what your country can do for you…" (JFK 11s clip, verbatim) | ✅ |
+| Speed | 2.66× realtime (4.14 s for 11.0 s audio) | ✅ tolerable; show an ETA for long clips |
+| Memory | ~676 MB peak RSS | ✅ fits |
+| In-process, main-origin | Node/Bun via onnxruntime-node — no browser CSP surface | ✅ |
+
+## Build notes (feed the DDR + the implementation)
+
+1. **Must use a `_timestamped` model variant.** Plain `onnx-community/whisper-base`
+   throws `Model outputs must contain cross attentions to extract timestamps` —
+   word timestamps need the cross-attention export. Use `onnx-community/whisper-*_timestamped`.
+2. **Model size default.** `base` (q8) is the sweet spot for the WASM/sidecar default
+   (accuracy vs download size vs the 2.66× speed). Offer `tiny`/`small` in the size picker.
+3. **onnxruntime-node teardown quirk.** A cosmetic `mutex lock failed` SIGABRT fires on
+   process exit AFTER all output is produced — the shim must `process.exit(0)` cleanly
+   once the SRT is written (the inference itself is unaffected).
+4. **Packaging fork (the genuinely consequential decision — DDR-worthy).** transformers.js
+   in Node defaults to **onnxruntime-node** (native `.node` binaries) — fast, but a heavy
+   per-platform native dep that fights the `bun --compile` standalone-binary distribution
+   (DDR-045) and bloats the npm tarball. Alternatives that avoid that: (a) transformers.js
+   with **onnxruntime-web (WASM)** in the browser proof-canvas harness — mirrors the shipped
+   `@imgly/background-removal` precedent (DDR-161) exactly, no native dep, but slower and
+   in a browser context; (b) native **whisper.cpp + a managed model-download button** (the
+   plan's fallback A) — fastest, but needs the binary. This fork is surfaced to the owner
+   before the heavy dep ships to every user.
+
+## Repro
+
+`scratchpad/whisper-spike/spike3.mjs` (stereo→mono + 44.1k→16k resample; the earlier
+garbled "[BIRDS CHIRPING]" run was a WAV-parse bug in the harness, not the model).
+
+## Resolution (2026-07-11) — shipped approach A, not B
+
+Building B revealed the packaging fork wasn't a preference but a **blocker**:
+`@huggingface/transformers@3.8.1` hard-depends on **`sharp` + `onnxruntime-node`**,
+the exact native "bun-compile-hostile" class **DDR-070 excludes**. A clean `npm add`
+is impossible; B would require vendoring the prebuilt browser bundle + allowlisting
+`cdn.jsdelivr.net` (WASM) and `huggingface.co` (models) in the canvas CSP — a
+DDR-worthy vendoring + CDN commitment. `device:'wasm'` is also unsupported in the
+transformers.js **Node** build (only `cpu` = onnxruntime-node), so sidecar-WASM is
+out — B would have to run in a browser proof-canvas harness (the @imgly pattern).
+
+**Owner chose approach A:** keep the fast native whisper.cpp engine (already validated
+on real footage) and remove the *friction* instead — a one-click managed model
+download (`generation/whisper-models.ts` + `/_api/generate/whisper-model` + a Settings
+card), `--provider whisper` model auto-resolution, and auto-ffmpeg container decode.
+No new runtime dependency; native binary still required (brew / build). True
+binary-free zero-install (B) stays a documented future option behind the vendoring
+decision.

package/apps/studio/git/service.ts

@@ -209,7 +209,9 @@ function underPrefix(filepath: string, prefix: string): boolean {
  *      double-transports through git. */
 function isMaudeRuntimeState(p: string): boolean {
   return (
-    /(^|\/)_(?:server|active|sync|preflight|locator|export-history)\.json$/.test(p) ||
+    /(^|\/)_(?:server|active|sync|preflight|locator|export-history|generate-history)\.json$/.test(
+      p
+    ) ||
     /(^|\/)_server\.(?:lock|log)$/.test(p) ||
     /(^|\/)_(?:history|trash|draw|photo|smoke|canvas-state|state|chat|comments|untrusted|export-jobs)(?:\/|$)/.test(
       p