@1agh/maude 0.42.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/endpoints.ts

@@ -14,6 +14,8 @@
 // echoed, or persisted (it is stripped from the JSON we return on error).
 
 import type { Context } from '../context.ts';
+import { parseGitHubRemote } from '../github/endpoints.ts';
+import { createPullRequest, GitHubApiError } from '../github/service.ts';
 import { getGithubToken } from '../github/token.ts';
 import {
   type GitFileStatus,
@@ -284,19 +286,64 @@ export function createGitEndpoints(ctx: Context): GitEndpoints {
   }
 
   async function fold(body: unknown): Promise<GitEndpointResult> {
-    // Token resolution mirrors push (it publishes the Shared version): body token →
-    // keychain bridge → undefined → authRequired.
+    // Token resolution mirrors push: body token → keychain bridge → undefined. Needed
+    // for the GitHub PR API call; an ssh draft-push authenticates with the user's key.
     const token = readToken(body) ?? (await getGithubToken()) ?? undefined;
     const b = (body ?? {}) as { name?: unknown; remote?: unknown };
     const name = safeGitArg(b.name);
     if (name === undefined) return bad('Invalid draft name.');
     if (b.remote != null && safeRemoteArg(b.remote) === undefined) return bad('Invalid remote.');
     const res = await gitFoldDraft(dir, name, token, { remote: safeRemoteArg(b.remote) });
-    if (res.ok) return { status: 200, json: { ok: true, shared: res.shared } };
-    if (res.authRequired)
-      return { status: 401, json: { ok: false, authRequired: true, error: res.error } };
-    if (res.conflict) return { status: 409, json: { ok: false, conflict: true, error: res.error } };
-    return { status: 502, json: { ok: false, error: res.error ?? 'Could not add the draft.' } };
+    if (!res.ok) {
+      if (res.authRequired)
+        return { status: 401, json: { ok: false, authRequired: true, error: res.error } };
+      if (res.conflict)
+        return { status: 409, json: { ok: false, conflict: true, error: res.error } };
+      return { status: 502, json: { ok: false, error: res.error ?? 'Could not add the draft.' } };
+    }
+    // Local-merge path (no GitHub remote): the draft is already in the Shared version.
+    if (!res.prReady) return { status: 200, json: { ok: true, shared: res.shared } };
+    // PR path: the draft branch is pushed — open a pull request draft→shared. The merge
+    // itself happens on GitHub after review (this is how a protected `main` is added to).
+    const gh = res.remoteUrl ? parseGitHubRemote(res.remoteUrl) : null;
+    if (!gh)
+      return draftPublishedNoPr(
+        res.shared,
+        res.head,
+        'Draft published. Open a pull request on your Git host to add it to the Shared version.'
+      );
+    if (!token)
+      return draftPublishedNoPr(
+        res.shared,
+        res.head,
+        'Draft published. Sign in with GitHub in Maude to open the pull request.'
+      );
+    try {
+      const pr = await createPullRequest(token, gh.owner, gh.repo, {
+        head: res.head as string,
+        base: res.base as string,
+        title: `Add draft “${res.head}” to ${res.base}`,
+        body: 'Opened from Maude — “Add to Shared version”.',
+      });
+      return {
+        status: 200,
+        // Surface the resolved destination repo (F2): the user should SEE which
+        // owner/repo their draft was pushed to / PR'd against, not just "the Shared
+        // version" — a poisoned `origin` would otherwise silently target another repo.
+        json: {
+          ok: true,
+          shared: res.shared,
+          prUrl: pr.html_url,
+          prNumber: pr.number,
+          repo: `${gh.owner}/${gh.repo}`,
+        },
+      };
+    } catch (e) {
+      // The draft IS pushed — a PR-creation failure is a partial success, not a hard
+      // fail. Surface the reason and keep the draft so the user can retry / open it.
+      const msg = e instanceof GitHubApiError ? e.message : 'Could not open the pull request.';
+      return draftPublishedNoPr(res.shared, res.head, msg);
+    }
   }
 
   async function fetchRemote(body: unknown): Promise<GitEndpointResult> {
@@ -335,6 +382,20 @@ function readToken(body: unknown): string | null {
   return typeof t === 'string' && t.length > 0 ? t : null;
 }
 
+/** Fold partial-success: the draft branch was pushed but no PR could be opened (no
+ *  sign-in, a non-GitHub remote, or the PR call failed). `ok:true` because the work IS
+ *  published; the UI shows `error` as a heads-up and keeps the draft for a retry. */
+function draftPublishedNoPr(
+  shared: string | undefined,
+  head: string | undefined,
+  error: string
+): GitEndpointResult {
+  return {
+    status: 200,
+    json: { ok: true, shared, published: head, prUnavailable: true, error },
+  };
+}
+
 /** DDR-112 — expand each selected path to include any DIRTY same-directory,
  *  same-stem sidecar (`<stem>.meta.json`, `<stem>.annotations.svg`, …). The `.`
  *  delimiter prevents `ui/Pricing` from grabbing `ui/Pricing v3.*`. */