@1agh/maude 0.43.0 → 0.45.0

package/apps/studio/bin/_transcribe.mjs

@@ -0,0 +1,419 @@
+#!/usr/bin/env bun
+// _transcribe.mjs — internal shim behind `maude design transcribe` (DDR-062).
+// Local, no-key speech-to-text for automatic subtitles: spawn whisper.cpp
+// (whisper-cli) on an audio/video file, parse its word-level JSON, and emit
+// SRT/VTT through the SHARED captions.ts reflow (the same rules the cloud STT
+// providers — ElevenLabs Scribe, Groq Whisper — run through, so local + cloud
+// subtitles never drift on line-length / timing). Runs under Bun so it can
+// import the `.ts` caption module directly (mirrors _svg-optimize.mjs).
+//
+// whisper.cpp is a SOFT dependency (plugins/design/dependencies.json): absent →
+// this exits non-zero with an actionable message (install it, or use the cloud
+// Scribe path). No dev server, no ffmpeg of our own — mirrors the footage-probe
+// shim shape.
+//
+// Model + binary resolution (whisper.cpp ships neither a default model nor
+// auto-download): `--model <path>` or $MAUDE_WHISPER_MODEL (a ggml .bin);
+// `--whisper <path>` or $MAUDE_WHISPER_CLI, else whisper-cli / whisper / main.
+//
+// Stdout (last line): the produced .srt path. Stderr: progress/diagnostics.
+// Exit: 0 ok / 1 dependency-or-input problem / 3 transcription failed.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+
+import { wordsToSrt, wordsToVtt } from '../generation/captions.ts';
+import { resolveWhisperModel } from '../generation/whisper-models.ts';
+
+/** Read `.design/config.json` → generation.transcription.whisperModel, or null
+ *  (the preferred managed model id, e.g. "base"). */
+function readConfigWhisperModel(repo) {
+  try {
+    const cfg = JSON.parse(readFileSync(join(repo, '.design', 'config.json'), 'utf8'));
+    const m = cfg?.generation?.transcription?.whisperModel;
+    return typeof m === 'string' ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * whisper.cpp can't decode arbitrary containers (mp4/mov/m4a) unless built with
+ * ffmpeg — the owner hit this on a real clip (GOTCHA C). If the input isn't
+ * already a WAV and system ffmpeg is present, transcode to a temp 16 kHz mono
+ * WAV (whisper's native rate) and transcribe THAT. Best-effort: no ffmpeg → we
+ * pass the original through and let whisper try (with the existing hint on
+ * failure). Returns { path, cleanup } — cleanup removes the temp file (if any).
+ */
+function ensureWav(input) {
+  if (/\.wav$/i.test(input)) return { path: input, cleanup: () => {} };
+  const ffmpeg = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' });
+  if (ffmpeg.error) return { path: input, cleanup: () => {} }; // no ffmpeg → try as-is
+  // Security (ethical-hacker Finding 1): write into a FRESH 0700 private dir
+  // (mkdtemp), NOT a predictable `/tmp/maude-transcribe-<name>-<pid>.wav`. On a
+  // shared/multi-user host (Linux CI, the hub Docker image) a co-tenant could
+  // pre-plant a symlink at a guessable path and ffmpeg's `-y` would follow it
+  // and overwrite the target. An unguessable per-run dir removes the primitive.
+  const dir = mkdtempSync(join(tmpdir(), 'maude-transcribe-'));
+  const wav = join(dir, `${basename(input, extname(input))}.wav`);
+  process.stderr.write('transcribe: converting to 16 kHz mono WAV via ffmpeg…\n');
+  const conv = spawnSync(
+    'ffmpeg',
+    ['-y', '-i', input, '-ar', '16000', '-ac', '1', '-c:a', 'pcm_s16le', wav],
+    { stdio: ['ignore', 'ignore', 'inherit'] }
+  );
+  const cleanup = () => rmSync(dir, { recursive: true, force: true });
+  if (conv.status !== 0 || !existsSync(wav)) {
+    cleanup();
+    return { path: input, cleanup: () => {} }; // conversion failed → fall back
+  }
+  return { path: wav, cleanup };
+}
+
+/**
+ * whisper.cpp `-oj` JSON → word timings. With `-ml 1` each `transcription[]`
+ * entry is ~one word; `offsets.from/to` are milliseconds from the audio start.
+ * Pure + exported so the parsing is unit-testable without whisper installed.
+ */
+export function whisperJsonToWords(jsonText) {
+  let doc;
+  try {
+    doc = JSON.parse(jsonText);
+  } catch {
+    return [];
+  }
+  const segs = Array.isArray(doc?.transcription) ? doc.transcription : [];
+  const words = [];
+  for (const s of segs) {
+    const text = typeof s?.text === 'string' ? s.text.trim() : '';
+    if (!text) continue;
+    const from = Number(s?.offsets?.from);
+    const to = Number(s?.offsets?.to);
+    words.push({
+      text,
+      start: Number.isFinite(from) ? from / 1000 : 0,
+      end: Number.isFinite(to) ? to / 1000 : 0,
+    });
+  }
+  return words;
+}
+
+function parseArgs(argv) {
+  const out = { format: 'srt', words: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    if (a === '--source') out.source = next();
+    else if (a === '--root') out.root = next();
+    else if (a === '--out') out.out = next();
+    else if (a === '--format')
+      out.format = next(); // srt | vtt | both
+    else if (a === '--model') out.model = next();
+    else if (a === '--whisper') out.whisper = next();
+    else if (a === '--provider')
+      out.provider = next(); // whisper | elevenlabs | groq
+    else if (a === '--lang') out.lang = next();
+    else if (a === '--segments')
+      out.words = false; // segment-level, not per-word
+    else if (a === '--help' || a === '-h') out.help = true;
+  }
+  return out;
+}
+
+const CLOUD_PROVIDERS = new Set(['elevenlabs', 'groq']);
+const KNOWN_PROVIDERS = new Set(['whisper', 'elevenlabs', 'groq']);
+
+/**
+ * Resolve the transcription engine as an EXPLICIT choice (Task 2.6): the
+ * --provider flag wins; else the project's `generation.transcription.provider`
+ * config default; else `whisper` (local, free) — and we SAY which we chose.
+ * Maude never silently reaches for a paid cloud engine. Returns { provider,
+ * defaulted } where `defaulted` means neither the flag nor config set it.
+ */
+export function resolveProvider(flag, repo) {
+  if (flag) {
+    if (!KNOWN_PROVIDERS.has(flag)) {
+      process.stderr.write(
+        `transcribe: unknown --provider '${flag}' (use whisper | elevenlabs | groq)\n`
+      );
+      process.exit(2);
+    }
+    return { provider: flag, defaulted: false };
+  }
+  const configured = readConfigProvider(repo);
+  if (configured && KNOWN_PROVIDERS.has(configured))
+    return { provider: configured, defaulted: false };
+  return { provider: 'whisper', defaulted: true };
+}
+
+/** Read `.design/config.json` → generation.transcription.provider, or null. */
+function readConfigProvider(repo) {
+  try {
+    const raw = readFileSync(join(repo, '.design', 'config.json'), 'utf8');
+    const cfg = JSON.parse(raw);
+    const p = cfg?.generation?.transcription?.provider;
+    return typeof p === 'string' ? p : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveWhisper(explicit) {
+  // Security (Phase-2 ethical-hacker): do NOT include the bare name `main`
+  // (whisper.cpp's legacy binary) in the fallback chain — it is one of the most
+  // common executable names in the wild, and the probe below EXECUTES each
+  // candidate (`--help`). A user running this inside an untrusted repo with `.`
+  // on $PATH could otherwise auto-run a seeded `main`. Only the explicit
+  // --whisper / $MAUDE_WHISPER_CLI (owner's own choice) and the specific
+  // whisper-cli / whisper names are probed.
+  const candidates = [explicit, process.env.MAUDE_WHISPER_CLI, 'whisper-cli', 'whisper'].filter(
+    Boolean
+  );
+  for (const c of candidates) {
+    const probe = spawnSync(c, ['--help'], { stdio: 'ignore' });
+    if (!probe.error) return c;
+  }
+  return null;
+}
+
+/**
+ * Cloud STT path (Task 2.6): the user CHOSE elevenlabs / groq. The transcription
+ * runs on the dev server's privileged generate route (the key is resolved
+ * server-side — never handed to this CLI), which writes the SRT sidecar next to
+ * the source and returns its `assets/<sha8>.srt` path. No-silent-switch: if the
+ * server is down or the source isn't an assets/ path, we ERROR clearly naming
+ * the fix AND the local alternative — we NEVER quietly fall back to whisper.
+ */
+async function runCloud(args, repo, provider) {
+  const source = args.source;
+  if (!source.startsWith('assets/') || source.includes('..')) {
+    process.stderr.write(
+      `transcribe: cloud engine '${provider}' needs a content-addressed source (assets/<sha8>.<ext>).\n` +
+        '  Ingest the file into the project first, or use --provider whisper for an arbitrary local path.\n'
+    );
+    process.exit(2);
+  }
+  const serverPath = join(repo, '.design', '_server.json');
+  if (!existsSync(serverPath)) {
+    process.stderr.write(
+      `transcribe: cloud engine '${provider}' needs the dev server running (it resolves your key server-side).\n` +
+        '  Start it: maude design server-up   — or use --provider whisper (local, no server, no key).\n'
+    );
+    process.exit(1);
+  }
+  let port;
+  try {
+    port = JSON.parse(readFileSync(serverPath, 'utf8'))?.port;
+  } catch {
+    /* handled below */
+  }
+  if (!port) {
+    process.stderr.write(`transcribe: could not read a port from ${serverPath}\n`);
+    process.exit(1);
+  }
+
+  const base = `http://127.0.0.1:${port}/_api/generate-jobs`;
+  const body = { modality: 'transcription', provider, sourceAsset: source };
+  if (args.model) body.model = args.model;
+  if (args.lang) body.params = { language: args.lang };
+
+  process.stderr.write(`transcribe: submitting to ${provider} (cloud STT)…\n`);
+  let jobId;
+  try {
+    const res = await fetch(base, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      process.stderr.write(
+        `transcribe: ${provider} enqueue rejected: ${json?.error ?? res.status}\n`
+      );
+      process.exit(3);
+    }
+    jobId = json.jobId;
+  } catch (err) {
+    process.stderr.write(`transcribe: could not reach the dev server: ${err?.message ?? err}\n`);
+    process.exit(1);
+  }
+  if (!jobId) {
+    process.stderr.write('transcribe: enqueue returned no job id\n');
+    process.exit(3);
+  }
+
+  const deadline = Date.now() + 300_000;
+  for (;;) {
+    await new Promise((r) => setTimeout(r, 2000));
+    let job;
+    try {
+      const jobs = await (await fetch(base)).json();
+      job = Array.isArray(jobs?.jobs) ? jobs.jobs.find((j) => j.id === jobId) : null;
+    } catch {
+      /* transient — keep polling until the deadline */
+    }
+    if (job?.status === 'done') {
+      const out = job.assets?.[0];
+      if (!out) {
+        process.stderr.write('transcribe: job done but produced no caption sidecar\n');
+        process.exit(3);
+      }
+      // Chosen engine may only produce SRT; the shared reflow output is SRT. If a
+      // VTT was asked for, note that the cloud path currently writes SRT only.
+      process.stdout.write(`${out.startsWith('/') ? out.slice(1) : out}\n`);
+      return;
+    }
+    if (job?.status === 'failed') {
+      process.stderr.write(
+        `transcribe: ${provider} transcription failed: ${job.error ?? 'unknown'}\n`
+      );
+      process.exit(3);
+    }
+    if (Date.now() >= deadline) {
+      process.stderr.write(`transcribe: timed out waiting for ${provider} (job ${jobId})\n`);
+      process.exit(3);
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stderr.write(
+      'usage: maude design transcribe --source <assets/x.mp4|file> [--root <repo>]\n' +
+        '  [--provider whisper|elevenlabs|groq] [--format srt|vtt|both] [--model <id>]\n' +
+        '  [--whisper <bin>] [--lang <code>] [--segments]\n' +
+        '\n' +
+        '  The engine is an EXPLICIT choice: --provider wins, else the project\n' +
+        '  generation.transcription.provider, else local whisper (never a silent\n' +
+        '  switch to a paid cloud engine). whisper = local/free/no-key;\n' +
+        '  elevenlabs|groq = cloud (needs the dev server + a key in Settings).\n'
+    );
+    process.exit(0);
+  }
+  if (!args.source) {
+    process.stderr.write('transcribe: --source is required\n');
+    process.exit(1);
+  }
+
+  const repo = args.root || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  // Resolve the engine as an explicit choice (Task 2.6). A chosen cloud engine
+  // routes through the dev server (key server-side); the local default stays
+  // whisper. We NEVER auto-switch between them.
+  const { provider, defaulted } = resolveProvider(args.provider, repo);
+  if (defaulted)
+    process.stderr.write(
+      'transcribe: no engine configured — using local whisper ' +
+        '(set generation.transcription.provider or pass --provider to choose)\n'
+    );
+  if (CLOUD_PROVIDERS.has(provider)) {
+    await runCloud(args, repo, provider);
+    return;
+  }
+
+  // Resolve the input: an `assets/<name>` under the design root, or a plain path.
+  // For the assets/ form, reject `..` so the content-addressed branch can't be
+  // used to climb out of <designRoot>/assets/ (parity with api.readAssetBytes —
+  // the network Scribe path is fully contained; keep this local path close). The
+  // plain-path branch intentionally accepts an owner-named file (transcribing an
+  // arbitrary local clip is a legitimate CLI use; there is no untrusted caller).
+  if (args.source.startsWith('assets/') && args.source.includes('..')) {
+    process.stderr.write('transcribe: invalid assets/ path (no "..")\n');
+    process.exit(1);
+  }
+  const input = args.source.startsWith('assets/')
+    ? join(repo, '.design', args.source)
+    : resolve(repo, args.source);
+  if (!existsSync(input)) {
+    process.stderr.write(`transcribe: input not found: ${input}\n`);
+    process.exit(1);
+  }
+
+  const whisper = resolveWhisper(args.whisper);
+  if (!whisper) {
+    process.stderr.write(
+      'transcribe: whisper.cpp not found (whisper-cli / whisper / main).\n' +
+        '  Install: brew install whisper-cpp  (or build https://github.com/ggml-org/whisper.cpp)\n' +
+        '  Or set $MAUDE_WHISPER_CLI. For cloud STT instead, use ElevenLabs Scribe / Groq Whisper.\n'
+    );
+    process.exit(1);
+  }
+
+  // Model resolution (Task 2.7 — one-click): explicit --model / $MAUDE_WHISPER_MODEL
+  // wins; otherwise auto-resolve a model downloaded via Settings ("Download &
+  // enable"), preferring the configured `generation.transcription.whisperModel`.
+  const model =
+    args.model ||
+    process.env.MAUDE_WHISPER_MODEL ||
+    resolveWhisperModel(readConfigWhisperModel(repo));
+  if (!model || !existsSync(model)) {
+    process.stderr.write(
+      'transcribe: no whisper.cpp model available.\n' +
+        '  One-click: open Settings (⌘,) → Subtitles → "Download model" (base is a good multilingual default).\n' +
+        '  Or pass --model <ggml-*.bin> / set $MAUDE_WHISPER_MODEL, or use a cloud engine (--provider elevenlabs|groq).\n'
+    );
+    process.exit(1);
+  }
+
+  // The owner's Czech-footage gotcha: an English-only `.en` model garbles other
+  // languages. Warn (don't block — the user may know their audio is English).
+  if (/\.en\.bin$/i.test(model) && args.lang && args.lang.toLowerCase() !== 'en') {
+    process.stderr.write(
+      `transcribe: WARNING — model ${basename(model)} is English-only but --lang ${args.lang} was given; expect garbled output. Use a multilingual model (e.g. ggml-base.bin).\n`
+    );
+  }
+
+  // Transcode to a WAV whisper.cpp can always read (GOTCHA C), when needed.
+  const wav = ensureWav(input);
+
+  const outBase = args.out
+    ? args.out.replace(/\.(srt|vtt|json)$/i, '')
+    : join(dirname(input), basename(input, extname(input)));
+
+  // whisper.cpp: JSON output for the shared reflow, `-ml 1` for word-level timings.
+  const flags = ['-m', model, '-f', wav.path, '-oj', '-of', outBase];
+  if (args.words) flags.push('-ml', '1');
+  if (args.lang) flags.push('-l', args.lang);
+
+  process.stderr.write(`transcribe: running ${whisper} (${basename(model)})…\n`);
+  const run = spawnSync(whisper, flags, { stdio: ['ignore', 'inherit', 'inherit'] });
+  wav.cleanup();
+  if (run.status !== 0) {
+    process.stderr.write(
+      `transcribe: whisper.cpp exited ${run.status ?? '?'} — if the input is a non-WAV container, install ffmpeg so Maude can auto-convert it (or convert to 16 kHz mono WAV first).\n`
+    );
+    process.exit(3);
+  }
+
+  const jsonPath = `${outBase}.json`;
+  if (!existsSync(jsonPath)) {
+    process.stderr.write(`transcribe: whisper produced no JSON at ${jsonPath}\n`);
+    process.exit(3);
+  }
+  const words = whisperJsonToWords(readFileSync(jsonPath, 'utf8'));
+  if (words.length === 0) {
+    process.stderr.write('transcribe: no words recognized (silent or unsupported audio?)\n');
+    process.exit(3);
+  }
+
+  const written = [];
+  if (args.format === 'srt' || args.format === 'both') {
+    const p = `${outBase}.srt`;
+    writeFileSync(p, wordsToSrt(words));
+    written.push(p);
+  }
+  if (args.format === 'vtt' || args.format === 'both') {
+    const p = `${outBase}.vtt`;
+    writeFileSync(p, wordsToVtt(words));
+    written.push(p);
+  }
+  // Last stdout line = the primary (SRT-preferred) caption path, for $(…) capture.
+  process.stdout.write(`${written[0]}\n`);
+}
+
+// Only run main when invoked directly (import.meta.main) so the parser can be
+// imported by the test without spawning whisper (mirrors the F3 CLI-guard fix).
+if (import.meta.main) main();

package/apps/studio/bin/_transcribe.test.mjs

@@ -0,0 +1,80 @@
+// _transcribe.test.mjs — the whisper.cpp JSON → word-timings parser (Phase 2).
+// The spawn/model resolution is a soft-dep live gate; this covers the pure,
+// deterministic parsing that turns whisper.cpp `-oj` output into CaptionWords
+// (then captions.ts renders the SRT — covered in captions.test.ts).
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { wordsToSrt } from '../generation/captions.ts';
+import { resolveProvider, whisperJsonToWords } from './_transcribe.mjs';
+
+function tmpRepo(config) {
+  const root = mkdtempSync(join(tmpdir(), 'maude-transcribe-'));
+  mkdirSync(join(root, '.design'), { recursive: true });
+  if (config !== undefined)
+    writeFileSync(join(root, '.design', 'config.json'), JSON.stringify(config));
+  return root;
+}
+
+const WHISPER_JSON = JSON.stringify({
+  transcription: [
+    { offsets: { from: 0, to: 480 }, text: ' Hello' },
+    { offsets: { from: 480, to: 900 }, text: ' there.' },
+    { offsets: { from: 1200, to: 1800 }, text: ' Maude' },
+    { offsets: { from: 0, to: 0 }, text: '   ' }, // blank → dropped
+  ],
+});
+
+describe('whisperJsonToWords', () => {
+  test('maps offsets (ms) to seconds and trims text', () => {
+    const words = whisperJsonToWords(WHISPER_JSON);
+    expect(words).toHaveLength(3);
+    expect(words[0]).toEqual({ text: 'Hello', start: 0, end: 0.48 });
+    expect(words[1]).toEqual({ text: 'there.', start: 0.48, end: 0.9 });
+    expect(words[2].text).toBe('Maude');
+  });
+
+  test('feeds captions.ts to produce a valid SRT', () => {
+    const srt = wordsToSrt(whisperJsonToWords(WHISPER_JSON));
+    expect(srt).toContain('00:00:00,000 --> 00:00:00,900');
+    expect(srt).toContain('Hello there.');
+  });
+
+  test('malformed / empty JSON yields no words (never throws)', () => {
+    expect(whisperJsonToWords('not json')).toEqual([]);
+    expect(whisperJsonToWords('{}')).toEqual([]);
+    expect(whisperJsonToWords(JSON.stringify({ transcription: [] }))).toEqual([]);
+  });
+
+  test('tolerates missing offsets', () => {
+    const words = whisperJsonToWords(JSON.stringify({ transcription: [{ text: 'x' }] }));
+    expect(words).toEqual([{ text: 'x', start: 0, end: 0 }]);
+  });
+});
+
+describe('resolveProvider (Task 2.6 — explicit engine choice, no silent switch)', () => {
+  test('an explicit valid flag wins over config', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'groq' } } });
+    expect(resolveProvider('elevenlabs', repo)).toEqual({
+      provider: 'elevenlabs',
+      defaulted: false,
+    });
+  });
+
+  test('falls back to the project config default', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'groq' } } });
+    expect(resolveProvider(undefined, repo)).toEqual({ provider: 'groq', defaulted: false });
+  });
+
+  test('defaults to local whisper (marked defaulted) when nothing is set', () => {
+    const repo = tmpRepo(); // no config
+    expect(resolveProvider(undefined, repo)).toEqual({ provider: 'whisper', defaulted: true });
+  });
+
+  test('a malformed config provider is ignored → whisper default', () => {
+    const repo = tmpRepo({ generation: { transcription: { provider: 'bogus' } } });
+    expect(resolveProvider(undefined, repo)).toEqual({ provider: 'whisper', defaulted: true });
+  });
+});

package/apps/studio/bin/audio-search.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# audio-search.sh — feature-ai-media-generation (Task 2.5, DDR-164). Reuse-before-
+# you-pay for AUDIO: before generating a new music/SFX/VO track, search the
+# project's own generated audio + the user's ElevenLabs history and prefer an
+# existing suitable track over spending credits. The search + reuse run
+# server-side (the key is resolved by the sidecar), so this is a pure fetch to
+# the running dev server — mirrors generate.sh.
+#
+# Reached via `maude design audio-search` (never a raw bin path — DDR-062).
+#
+# Usage:
+#   audio-search.sh --query "<text>" [--root <repo>] [--reuse <historyId>] [--json]
+#
+# Requires a running dev server (caller runs `maude design server-up` first).
+#
+# Stdout (last line, --reuse): the localized /assets/<sha8>.mp3 path.
+# Exit: 0 ok / 1 server problem / 2 bad args / 3 search/reuse failed.
+
+set -euo pipefail
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "audio-search.sh: bun is required (hard dependency — see plugins/design/dependencies.json)." >&2
+  echo "  Install: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bun run "$SCRIPT_DIR/_audio-search.mjs" "$@"

package/apps/studio/bin/generate.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# generate.sh — feature-ai-media-generation (Phase 0, DDR-16x). Headless BYOK
+# AI-media generation: POST a GenRequest to the running dev server's privileged
+# /_api/generate-jobs route, poll the job to completion, and print the produced
+# content-addressed asset path (`/assets/<sha8>.<ext>`).
+#
+# The thin, non-browser sibling of the studio generate dialog — the provider call
+# happens SERVER-SIDE (the sidecar resolves the key from the OS keychain /
+# ~/.config/maude/keys.json and calls the provider directly), so this verb is a
+# pure JSON curl + poll, exactly like photo-adjust.sh. No client-side inference,
+# so a harness canvas + agent-browser would be pure overhead.
+#
+# Reached via `maude design generate` (never a raw bin path — DDR-062).
+#
+# Usage:
+#   generate.sh --prompt "<text>" [--provider gemini|elevenlabs] [--model <id>]
+#     [--modality image|audio|video] [--aspect 16:9] [--source assets/<sha8>.<ext>]
+#     [--kind music|sfx|tts] [--voice <voice_id>] [--duration <seconds>]
+#     [--root <repo>] [--timeout <sec>]
+#
+# --source turns an IMAGE call into a maskless EDIT (Nano Banana): the content-
+# addressed source image is read server-side into the request and the prompt
+# describes the change; a NEW content-addressed asset is produced (the original
+# is never mutated). For --modality video it is the image-to-video SEED (a still
+# → a clip, so a generated clip can match a generated hero's style).
+#
+# --modality audio (provider elevenlabs): --kind music (default) | sfx | tts.
+# tts needs --voice <voice_id>; music/sfx take an optional --duration in seconds.
+# Produces assets/<sha8>.mp3. (Transcription is a separate verb: `maude design
+# transcribe`, which writes SRT/VTT.)
+#
+# --modality video (provider gemini / Veo 3.1): ASYNC — the clip takes ~1–10 min;
+# the poll timeout defaults to 600s for video (180s otherwise). Produces
+# assets/<sha8>.mp4 + a provenance assets/<sha8>.footage.json stub so the clip is
+# reel-ready (see /design:reel Step 1.5).
+#
+# The key is NEVER passed here — it lives server-side. Add it in Settings
+# (⌘,) or drop it into ~/.config/maude/keys.json (mode 0600).
+#
+# Requires a running dev server (caller runs `maude design server-up` first);
+# reads the port from <designRoot>/_server.json.
+#
+# Stdout (last line): the produced asset path `/assets/<sha8>.<ext>` (for $(...)).
+# Stderr: progress / diagnostics.
+# Exit:   0 ok / 1 server problem / 2 bad args / 3 generation failed.
+
+set -euo pipefail
+
+PROMPT="" PROVIDER="gemini" MODEL="" MODALITY="image" ASPECT="" SOURCE="" REPO="" TIMEOUT=""
+# Audio params (Phase 2) — kind = music|sfx|tts; voice = an ElevenLabs voice_id
+# (required for tts); duration = seconds (music/sfx length).
+KIND="" VOICE="" DURATION=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --prompt)   PROMPT="$2"; shift 2 ;;
+    --provider) PROVIDER="$2"; shift 2 ;;
+    --model)    MODEL="$2"; shift 2 ;;
+    --modality) MODALITY="$2"; shift 2 ;;
+    --aspect)   ASPECT="$2"; shift 2 ;;
+    --source)   SOURCE="$2"; shift 2 ;;
+    --kind)     KIND="$2"; shift 2 ;;
+    --voice)    VOICE="$2"; shift 2 ;;
+    --duration) DURATION="$2"; shift 2 ;;
+    --root)     REPO="$2"; shift 2 ;;
+    --timeout)  TIMEOUT="$2"; shift 2 ;;
+    --help|-h)  sed -n '2,41p' "$0" | sed 's/^# \?//'; exit 0 ;;
+    *) echo "generate.sh: unknown arg '$1'" >&2; exit 2 ;;
+  esac
+done
+
+# generate.sh produces MEDIA (image / audio) from a prompt. Transcription is a
+# different shape (audio → captions) reached via `maude design transcribe`, which
+# writes SRT/VTT files — not this verb, whose contract is "print the produced
+# asset path".
+[ -n "$PROMPT" ] || { echo "generate.sh: --prompt is required" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "generate.sh: jq is required" >&2; exit 1; }
+
+# Async video (Veo) takes minutes — default the poll window wider than the
+# seconds-fast image/audio calls unless the caller pinned --timeout explicitly.
+if [ -z "$TIMEOUT" ]; then
+  if [ "$MODALITY" = "video" ]; then TIMEOUT="600"; else TIMEOUT="180"; fi
+fi
+
+if [ -z "$REPO" ]; then
+  REPO="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+fi
+DESIGN_ROOT="$REPO/.design"
+[ -d "$DESIGN_ROOT" ] || { echo "generate.sh: no .design/ under $REPO" >&2; exit 1; }
+
+STATE="$DESIGN_ROOT/_server.json"
+[ -f "$STATE" ] || { echo "generate.sh: no _server.json (start the dev server first)" >&2; exit 1; }
+PORT=$(jq -r '.port // empty' "$STATE" 2>/dev/null)
+[ -n "$PORT" ] || { echo "generate.sh: could not read port from $STATE" >&2; exit 1; }
+
+BASE="http://127.0.0.1:$PORT/_api/generate-jobs"
+
+# Normalize a --source to the `assets/<sha8>.<ext>` form the route validates
+# (strip a leading slash the canvas-relative writers emit).
+SOURCE="${SOURCE#/}"
+
+# Build the audio params object (only the set keys) — audioKind / voice_id /
+# durationSeconds are opaque to the spine; each adapter validates its own subset.
+PARAMS=$(jq -n --arg kind "$KIND" --arg voice "$VOICE" --arg dur "$DURATION" '
+  {}
+  + (if $kind  != "" then { audioKind: $kind }               else {} end)
+  + (if $voice != "" then { voice_id: $voice }               else {} end)
+  + (if $dur   != "" then { durationSeconds: ($dur|tonumber) } else {} end)')
+
+# Build the request body — jq handles all prompt escaping. Omit empty optionals.
+BODY=$(jq -n \
+  --arg modality "$MODALITY" --arg provider "$PROVIDER" --arg model "$MODEL" \
+  --arg prompt "$PROMPT" --arg aspect "$ASPECT" --arg source "$SOURCE" \
+  --argjson params "$PARAMS" '
+  { modality: $modality, provider: $provider }
+  + (if $prompt != "" then { prompt: $prompt }      else {} end)
+  + (if $model  != "" then { model: $model }        else {} end)
+  + (if $aspect != "" then { aspectRatio: $aspect } else {} end)
+  + (if $source != "" then { sourceAsset: $source } else {} end)
+  + (if ($params|length) > 0 then { params: $params } else {} end)')
+
+echo "generate.sh: submitting to $PROVIDER ($MODALITY)…" >&2
+RESP=$(curl -s -X POST -H 'Content-Type: application/json' -d "$BODY" "$BASE")
+JOB_ID=$(printf '%s' "$RESP" | jq -r '.jobId // empty' 2>/dev/null || echo "")
+if [ -z "$JOB_ID" ]; then
+  echo "generate.sh: enqueue rejected: $RESP" >&2
+  exit 3
+fi
+echo "generate.sh: job $JOB_ID queued — polling…" >&2
+
+# Poll the job list until this job is done/failed, or the timeout elapses.
+DEADLINE=$(( $(date +%s) + TIMEOUT ))
+while :; do
+  JOBS=$(curl -s "$BASE" 2>/dev/null || echo '{}')
+  JOB=$(printf '%s' "$JOBS" | jq -c --arg id "$JOB_ID" '.jobs[]? | select(.id == $id)' 2>/dev/null || echo "")
+  STATUS=$(printf '%s' "$JOB" | jq -r '.status // empty' 2>/dev/null || echo "")
+  case "$STATUS" in
+    done)
+      ASSET=$(printf '%s' "$JOB" | jq -r '.assets[0] // empty' 2>/dev/null || echo "")
+      [ -n "$ASSET" ] || { echo "generate.sh: job done but produced no asset" >&2; exit 3; }
+      # Normalize to the leading-slash canvas-relative form writers use.
+      printf '/%s\n' "${ASSET#/}"
+      exit 0 ;;
+    failed)
+      ERR=$(printf '%s' "$JOB" | jq -r '.error // "unknown error"' 2>/dev/null || echo "unknown")
+      echo "generate.sh: generation failed: $ERR" >&2
+      exit 3 ;;
+  esac
+  if [ "$(date +%s)" -ge "$DEADLINE" ]; then
+    echo "generate.sh: timed out after ${TIMEOUT}s (job still $STATUS)" >&2
+    exit 3
+  fi
+  sleep 2
+done