@1agh/maude 0.45.1 → 0.46.0

package/cli/commands/design.mjs

@@ -1,11 +1,21 @@
 import { execSync, spawn, spawnSync } from 'node:child_process';
-import { chmodSync, existsSync, readFileSync } from 'node:fs';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 import { runAdopt, runLink, runStatus, runUnlink } from '../lib/design-link.mjs';
 import { writeGitignoreBlock } from '../lib/gitignore-block.mjs';
+import { isCompiledBinary } from '../lib/pkg-root.mjs';
 
 const SUBCOMMANDS = new Set([
   'serve',
@@ -77,6 +87,14 @@ const BIN_VERBS = new Set([
   // reads the clip as a file:// resource).
   'ingest-footage',
   'probe-footage',
+  // feature-scene-aware-keyframes. `smart-frames` is the scene-AWARE sibling of
+  // `probe-footage`: it selects keyframes at scene cuts + semantic action beats +
+  // endpoints (three tiers, auto-detected — gemma scout / ffmpeg scene-detect /
+  // blind Chromium floor) instead of a blind frame rate, and emits a SUPERSET of
+  // probe-footage's manifest (drop-in for the footage-analyst). No dev server.
+  // Owned by skill `footage-keyframes`; --engine auto self-detects deps so it
+  // works standalone as a terminal video analyzer.
+  'smart-frames',
   // feature-ai-media-generation (Phase 0, DDR-16x). `generate` is the thin
   // non-browser BYOK verb (curl → /_api/generate-jobs → poll → print the
   // produced /assets/<sha8>.<ext>). The provider call happens server-side (the
@@ -133,6 +151,89 @@ export async function run({ args, pkgRoot }) {
 // pass straight through — preserves `$(maude design slug …)` capture,
 // `eval "$(maude design prep --shell-export …)"`, and non-zero gating idioms.
 // maude writes nothing of its own on this path (no banner on stdout).
+/** True if a `bun` executable is reachable on the given PATH string (POSIX). */
+function bunOnPath(pathStr) {
+  for (const dir of (pathStr || '').split(':')) {
+    if (dir && existsSync(join(dir, 'bun'))) return true;
+  }
+  return false;
+}
+
+/** A bun-capable compiled binary to borrow as `bun` (RCA G3), or null.
+ *  Prefer the dev-server binary the sidecar hands us, else our own compiled
+ *  self (the `maude` CLI is `bun --compile`d too), else a resolvable server bin. */
+function resolveBunnable(pkgRoot) {
+  const dev = process.env.MAUDE_DEV_SERVER_BIN;
+  if (dev && existsSync(dev)) return dev;
+  if (isCompiledBinary()) return process.execPath;
+  const server = resolveServerBinary({ pkgRoot });
+  if (server && existsSync(server)) return server;
+  return null;
+}
+
+/**
+ * Ensure the design helpers' `command -v bun` / `exec bun run` resolve, even on a
+ * machine with NO standalone `bun` (RCA G3 — the desktop `.app` and the npm
+ * package ship compiled Bun BINARIES, never a `bun` CLI). The compiled binaries
+ * ARE Bun: run with `BUN_BE_BUN=1` a `bun --compile` executable behaves as the
+ * `bun` CLI. So if no real `bun` is on PATH, stage a tiny `bun` shim
+ * (→ `BUN_BE_BUN=1 <compiled-binary> "$@"`) in a per-user cache dir (0700) and
+ * PREPEND it to the child's PATH. No-op when a real `bun` is already present (dev)
+ * or no compiled binary exists to borrow (pure-source dev without bun — where a
+ * real `bun` is expected anyway). Returns the (possibly PATH-augmented) env.
+ */
+/** POSIX single-quote escape: wrap in '…' and encode embedded quotes as '\''.
+ *  Neutralizes $, backticks, ${}, and every other sh metachar — unlike
+ *  JSON.stringify, which leaves them live inside sh double-quotes. */
+function shSingleQuote(s) {
+  return `'${String(s).replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Provide a `bun` to a design helper that has none (RCA G3), then have the caller
+ * REMOVE it after the spawn. Returns `{ env, shimDir }` — `shimDir` is a fresh
+ * dir the caller must `rmSync` once the helper exits (null when no shim was made).
+ *
+ * Security (ethical-hacker review, DDR-177 addendum): the shim goes in a fresh,
+ * unpredictable, owner-only `mkdtemp` dir created PER SPAWN and torn down right
+ * after — NEVER a stable, guessable `~/.cache/maude/bun-shim/bun`. A stable path
+ * on a child's PATH with an unqualified `bun` lookup is the exact PATH-shadow
+ * primitive `sidecar.rs` deliberately refuses (Attacker-F4/DDR-168): an untrusted
+ * SAME-UID actor (in scope per DDR-054 — a poisoned dependency in an opened
+ * project, a prompt-injected agent's Bash tool) could pre-plant/symlink/race a
+ * stable shim and hijack the interpreter of every future helper. A per-spawn
+ * mkdtemp dir has no pre-existing entry to symlink-follow and no guessable name to
+ * race, and is gone before the next spawn. Fails CLOSED with no HOME (never plants
+ * an executable in world-writable /tmp).
+ */
+function ensureBunOnPath(childEnv, pkgRoot) {
+  if (bunOnPath(childEnv.PATH)) return { env: childEnv, shimDir: null };
+  const bunnable = resolveBunnable(pkgRoot);
+  if (!bunnable) return { env: childEnv, shimDir: null }; // helper's own guard reports the miss
+  const home = homedir();
+  if (!home) return { env: childEnv, shimDir: null }; // fail closed — no /tmp fallback for an executable
+  try {
+    const cacheParent = join(home, '.cache', 'maude');
+    mkdirSync(cacheParent, { recursive: true, mode: 0o700 });
+    // Fresh + unpredictable + 0700, one per spawn. mkdtemp guarantees a brand-new
+    // dir (fails if it exists), so there's nothing to symlink-follow on the write.
+    const shimDir = mkdtempSync(join(cacheParent, 'bun-shim-'));
+    const shim = join(shimDir, 'bun');
+    // Single-quote the binary path (NOT JSON.stringify — that leaves $/backticks
+    // live inside sh double-quotes, so a binary path with shell metacharacters
+    // would run command substitution when the shim executes).
+    writeFileSync(
+      shim,
+      `#!/bin/sh\n# maude bun shim (RCA G3) — the bundled compiled binary IS Bun;\n# BUN_BE_BUN=1 makes it act as the \`bun\` CLI so design helpers run with no\n# user-installed bun. Ephemeral: written per-spawn, removed after (design.mjs).\nBUN_BE_BUN=1 exec ${shSingleQuote(bunnable)} "$@"\n`,
+      { mode: 0o755 }
+    );
+    chmodSync(shim, 0o755);
+    return { env: { ...childEnv, PATH: `${shimDir}:${childEnv.PATH || ''}` }, shimDir };
+  } catch {
+    return { env: childEnv, shimDir: null }; // best-effort; the helper reports the miss
+  }
+}
+
 function runBinDispatch(verb, { args, pkgRoot }) {
   if (!BIN_VERBS.has(verb)) {
     process.stderr.write(`maude design: "${verb}" is not a dev-tooling verb.\n${usage()}`);
@@ -164,10 +265,22 @@ function runBinDispatch(verb, { args, pkgRoot }) {
     const bin = resolveServerBinary({ pkgRoot });
     if (bin) childEnv.MAUDE_DEV_SERVER_BIN = bin;
   }
+  // RCA G3 — make `bun` resolvable to the helper from the bundled compiled binary
+  // when no standalone `bun` is installed (desktop / npm). No-op in dev. The shim
+  // dir is ephemeral (per-spawn mkdtemp) — remove it as soon as the helper exits,
+  // so nothing bun-named lingers on a guessable path (ethical-hacker review).
+  const { env: finalEnv, shimDir } = ensureBunOnPath(childEnv, pkgRoot);
   const child = spawnSync('bash', [script, ...rest], {
     stdio: 'inherit',
-    env: childEnv,
+    env: finalEnv,
   });
+  if (shimDir) {
+    try {
+      rmSync(shimDir, { recursive: true, force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
   if (child.error) {
     process.stderr.write(`maude design ${verb}: ${child.error.message}\n`);
     process.exit(1);
@@ -185,7 +298,7 @@ Dev-tooling (dispatch to the dev-server bash helpers — DDR-062):
   screenshot · server-up · prep · slug · bootstrap-check · runtime-health
   smoke · canvas-edit · handoff · asset-sweep · visual-sanity · fetch-asset
   draw-build · draw-proof · svg-optimize · to-lottie · read-annotations · annotate
-  canvas-rects · ingest-footage · probe-footage
+  canvas-rects · ingest-footage · probe-footage · smart-frames
   generate · transcribe · audio-search
         Invoke the bundled helper of the same name. maude resolves it from its
         own package root and sets CLAUDE_PLUGIN_ROOT for the child; stdout,

package/cli/lib/pkg-root.mjs

@@ -59,14 +59,41 @@ export function isPkgRoot(dir) {
 
 /**
  * Resolve maude's own package root — real disk path, safe inside a compiled
- * binary. Priority: (0) explicit override, (1) dev-mode `import.meta.url`
- * (plain `node`/`bun run cli/bin/maude.mjs`), (2) compiled-binary walk-up
- * from `process.execPath` (matches the npm-install layout: binary at
- * `@1agh/maude-<platform>/maude` walks up to `@1agh/maude/`, which ships
- * `apps/studio/` via `package.json` `files`; matches the Tauri desktop layout
- * too, where the bundled `maude` binary and the `Resources/apps/studio`
- * bundle share a common ancestor within the walk-up depth).
+ * binary. Priority: (0) explicit `MAUDE_PKG_ROOT` override (sidecar.rs sets this
+ * on the desktop), (1) dev-mode `import.meta.url` (plain `node`/`bun run
+ * cli/bin/maude.mjs`), (2) compiled-binary walk-up from `process.execPath`
+ * (matches the npm-install layout: binary at `@1agh/maude-<platform>/maude`
+ * walks up to `@1agh/maude/`, which ships `apps/studio/` via `package.json`
+ * `files`), (3) the Tauri **`.app` sibling probe** below.
+ *
+ * Why (3) exists: in a packaged `Maude.app` the bundled `maude` binary lives in
+ * `Contents/MacOS/` but the staged package tree (`apps/studio/`, `cli/`,
+ * `package.json`) lives in the SIBLING `Contents/Resources/` — NOT an ancestor
+ * of the binary, so the walk-up in (2) never reaches it and used to fall through
+ * to `dirname(execPath)` = `Contents/MacOS/`, breaking every `maude design
+ * <verb>` with "helper not found" (RCA issue-acp-panel-hangs-on-nodeless-machine
+ * G2, reproduced on the shipped v0.45.1 `.app`). The earlier claim that the
+ * binary + `Resources/apps/studio` "share a common ancestor within the walk-up
+ * depth" was WRONG — `Contents/` is the common ancestor but `apps/studio` sits
+ * under `Contents/Resources/`, not `Contents/`, and `cli/` isn't in the ancestry
+ * at all. We probe the known Tauri resource-dir siblings explicitly instead.
  */
+/**
+ * Probe the Tauri packaged-app resource dir relative to the binary's own dir.
+ * From `<app>/Contents/MacOS/maude`, the staged package tree is at the SIBLING
+ * `<app>/Contents/Resources`. Covers macOS (`Resources`), the lower-cased
+ * resource dir other Tauri targets use, and a binary co-located with a
+ * `resources/` dir (dev staging). Returns the first valid pkgRoot, or null.
+ * Exported so the RCA-G2 fix is unit-testable without spawning a real `.app`.
+ */
+export function resolveTauriResourcePkgRoot(execDir) {
+  for (const rel of [['..', 'Resources'], ['..', 'resources'], ['resources']]) {
+    const cand = join(execDir, ...rel);
+    if (isPkgRoot(cand)) return cand;
+  }
+  return null;
+}
+
 export function resolvePkgRoot() {
   const override = process.env.MAUDE_PKG_ROOT;
   if (override && !isVirtualBunfsPath(override) && isPkgRoot(override)) return override;
@@ -84,12 +111,13 @@ export function resolvePkgRoot() {
   // from there (e.g. ~/Library/Caches/…/bin-link/) never reaches the repo
   // root. Dereference first. Falls back to the raw path if the file somehow
   // doesn't exist (shouldn't happen — we ARE that running process).
-  let cur;
+  let execDir;
   try {
-    cur = dirname(realpathSync(process.execPath));
+    execDir = dirname(realpathSync(process.execPath));
   } catch {
-    cur = dirname(process.execPath);
+    execDir = dirname(process.execPath);
   }
+  let cur = execDir;
   for (let i = 0; i < 10; i++) {
     if (isPkgRoot(cur)) return cur;
     const parent = dirname(cur);
@@ -97,6 +125,10 @@ export function resolvePkgRoot() {
     cur = parent;
   }
 
+  // (3) Tauri `.app` sibling probe — the packaged layout the walk-up can't reach.
+  const sibling = resolveTauriResourcePkgRoot(execDir);
+  if (sibling) return sibling;
+
   // Final fallback for unanchored test contexts — callers should expect
   // existsSync-based lookups to fail and surface a clear error, same
   // contract as paths.ts's own resolver. Never join a VIRTUAL importDir here

package/cli/lib/pkg-root.test.mjs

@@ -16,7 +16,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 
-import { isPkgRoot, resolvePkgRoot } from './pkg-root.mjs';
+import { isPkgRoot, resolvePkgRoot, resolveTauriResourcePkgRoot } from './pkg-root.mjs';
 
 function makeRealRoot(base) {
   mkdirSync(join(base, 'apps', 'studio', 'bin'), { recursive: true });
@@ -52,6 +52,38 @@ test('isPkgRoot requires BOTH anchors — the staged-resources false-positive is
   }
 });
 
+test('resolveTauriResourcePkgRoot finds the .app sibling Resources tree (RCA G2)', () => {
+  // Mirror the packaged macOS layout: binary in Contents/MacOS, staged tree in
+  // the SIBLING Contents/Resources — NOT an ancestor of the binary, which is why
+  // the plain walk-up misses it and every `maude design <verb>` broke.
+  const app = mkdtempSync(join(tmpdir(), 'maude-app-'));
+  try {
+    const macosDir = join(app, 'Contents', 'MacOS');
+    const resources = join(app, 'Contents', 'Resources');
+    mkdirSync(macosDir, { recursive: true });
+    makeRealRoot(resources); // stages apps/studio/bin/screenshot.sh + cli/commands/design.mjs
+
+    // From the binary's own dir, the sibling probe must find Resources.
+    assert.equal(resolveTauriResourcePkgRoot(macosDir), resources);
+
+    // Regression guard: Resources WITHOUT cli/ (the shipped-broken v0.45.1 shape)
+    // must NOT resolve — that's exactly the false-positive isPkgRoot rejects.
+    const broken = mkdtempSync(join(tmpdir(), 'maude-app-broken-'));
+    try {
+      const bMacos = join(broken, 'Contents', 'MacOS');
+      const bRes = join(broken, 'Contents', 'Resources', 'apps', 'studio', 'bin');
+      mkdirSync(bMacos, { recursive: true });
+      mkdirSync(bRes, { recursive: true });
+      writeFileSync(join(bRes, 'screenshot.sh'), '#!/bin/sh\n'); // no cli/ staged
+      assert.equal(resolveTauriResourcePkgRoot(bMacos), null);
+    } finally {
+      rmSync(broken, { recursive: true, force: true });
+    }
+  } finally {
+    rmSync(app, { recursive: true, force: true });
+  }
+});
+
 test('resolvePkgRoot honors MAUDE_PKG_ROOT only when it actually satisfies both anchors', () => {
   const real = mkdtempSync(join(tmpdir(), 'maude-pkgroot-real-'));
   const fake = mkdtempSync(join(tmpdir(), 'maude-pkgroot-fake-'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.45.1",
+  "version": "0.46.0",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -51,13 +51,13 @@
     "test:e2e:desktop:acp-cold-start": "pnpm --filter @maude/desktop-e2e e2e:acp-cold-start"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.45.1",
-    "@1agh/maude-darwin-x64": "0.45.1",
-    "@1agh/maude-linux-arm64": "0.45.1",
-    "@1agh/maude-linux-arm64-musl": "0.45.1",
-    "@1agh/maude-linux-x64": "0.45.1",
-    "@1agh/maude-linux-x64-musl": "0.45.1",
-    "@1agh/maude-win32-x64": "0.45.1"
+    "@1agh/maude-darwin-arm64": "0.46.0",
+    "@1agh/maude-darwin-x64": "0.46.0",
+    "@1agh/maude-linux-arm64": "0.46.0",
+    "@1agh/maude-linux-arm64-musl": "0.46.0",
+    "@1agh/maude-linux-x64": "0.46.0",
+    "@1agh/maude-linux-x64-musl": "0.46.0",
+    "@1agh/maude-win32-x64": "0.46.0"
   },
   "files": [
     "cli",
@@ -102,6 +102,8 @@
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1"
+    "ajv-formats": "^3.0.1",
+    "happy-dom": "20.10.6",
+    "svgo": "^4.0.1"
   }
 }

package/plugins/design/dependencies.json

@@ -213,6 +213,41 @@
       "fallbackBehavior": "feature-ai-media-generation Phase 2 (DDR-164) — `maude design transcribe` uses whisper.cpp for local, no-key, word-timestamped subtitles (the DEFAULT subtitle path). Without it, transcription falls back to cloud STT (ElevenLabs Scribe / Groq Whisper) via a provider key. whisper.cpp also needs a ggml model file (--model / $MAUDE_WHISPER_MODEL); it ships no default and does not auto-download — see https://huggingface.co/ggerganov/whisper.cpp (e.g. ggml-large-v3-turbo.bin).",
       "usedBy": ["dev-server/bin/transcribe.sh", "dev-server/bin/_transcribe.mjs"],
       "docsUrl": "https://github.com/ggml-org/whisper.cpp"
+    },
+    {
+      "id": "ffmpeg",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "ffmpeg -version",
+        "expectExit": 0
+      },
+      "install": {
+        "darwin": "brew install ffmpeg",
+        "linux": "apt-get install -y ffmpeg || dnf install -y ffmpeg",
+        "preferred": "https://ffmpeg.org/download.html"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "feature-scene-aware-keyframes — the `ffmpeg` tier of `maude design smart-frames` (skill footage-keyframes) uses ffmpeg scene-detection to pick keyframes at real shot cuts. Without it, the extractor falls back to the blind Chromium tier (probe-footage, even-spaced) — still works, just not scene-aware.",
+      "usedBy": ["dev-server/bin/smart-frames.sh", "dev-server/bin/_smart-frames.mjs"],
+      "docsUrl": "https://ffmpeg.org"
+    },
+    {
+      "id": "mlx-vlm",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "python3 -c \"import mlx_vlm\"",
+        "expectExit": 0
+      },
+      "install": {
+        "darwin": "pip install mlx-vlm",
+        "preferred": "https://github.com/Blaizzy/mlx-vlm"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "feature-scene-aware-keyframes — OPT-IN. The `gemma` tier of `maude design smart-frames` runs a local Gemma-4 MLX scout (Apple Silicon only) to flag semantic action beats. Without it, smart-frames uses the ffmpeg or blind tier — no model download required. The scout also needs a Gemma-4 MLX model (--engine gemma / $MAUDE_GEMMA_MODEL, one-click in Studio Settings → Scene-aware keyframes).",
+      "usedBy": ["dev-server/bin/_smart-frames.mjs"],
+      "docsUrl": "https://github.com/Blaizzy/mlx-vlm"
     }
   ]
 }