@lalalic/markcut 2.2.8 → 2.2.9

package/src/vision/cli.mjs

@@ -20,11 +20,7 @@
  *      f) Save complete metadata.json with metadata + userHint + perception
  *
  * Options:
- *   --label            Run full pipeline: preview → label → normalize → percept → segments
- *   --agent <tmpl>     Custom text LLM CLI for detect-scenes ({prompt})
- *   --itt <tmpl>       Custom ITT CLI template with {input}, {prompt}
- *   --vtt <tmpl>       Custom VTT CLI template with {input}, {prompt}
- *   --stt <tmpl>       Custom STT CLI template with {input}, {output}
+ *   --label            Open label preview → then continue with full AI pipeline
  *   --prompts-file <path> Path to prompts markdown file (default: vision_prompts.md)
  *   --vtt-sample-interval <n> Sample one video frame every N seconds (default: 5)
  *   --context "text"   Background context about people/places (injected into prompts)
@@ -32,7 +28,6 @@
  *   --skip-stt         Skip speech-to-text for videos
  *   --dry-run          Show what would be processed without running AI
  *   --show-prompts     Print the prompts file and exit
- *   --show-clis        Print the default ITT/VTT/STT CLI templates
  *   --help             Show this help
  *
  * Prompt overrides:
@@ -716,13 +711,13 @@ function mergeLabelsIntoMetadata(folder, metadata) {
 
 // ── Perception helpers ────────────────────────────────────────────────────
 
-function analyzeImage(imagePath, normPath, prompts, ittCli, context = "", userHint = "", userHints = null) {
+function analyzeImage(imagePath, normPath, prompts, context = "", userHint = "", userHints = null) {
   let ctxParts = [];
   if (context) ctxParts.push(`Context: ${context}`);
   if (userHint) ctxParts.push(`User hint: ${userHint}`);
   const ctx = ctxParts.length > 0 ? ctxParts.join("\n") + "\n\n" : "";
   const prompt = ctx + getPrompt(prompts, "image-perception");
-  const raw = runITT(normPath, prompt, ittCli);
+  const raw = runITT(normPath, prompt, DEFAULT_ITT_CLI);
   const parsed = looseJSONParse(raw);
   const rawText = stripThinkBlocks(extractRawText(raw));
   return normalizePerception({
@@ -790,7 +785,7 @@ function buildMergedCues(userHint, cues, sceneChangesMs, totalDurationMs) {
   return merged;
 }
 
-function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, context = "", userHint = "", ittCli = null, sampleInterval = DEFAULT_VTT_SAMPLE_INTERVAL, agentCli = null, userHints = null) {
+function analyzeVideo(videoPath, normInfo, normDir, prompts, context = "", userHint = "", sampleInterval = DEFAULT_VTT_SAMPLE_INTERVAL, userHints = null) {
   let ctxParts = [];
   if (context) ctxParts.push(`Context: ${context}`);
   if (userHint && typeof userHint === "string") ctxParts.push(`User hint: ${userHint}`);
@@ -800,13 +795,13 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
   // 1. VTT → overall video description
   emitInfo(`  Running video understanding...`);
   const descPrompt = ctx + getPrompt(prompts, "video-perception");
-  const descRaw = runVTT(normInfo.path, descPrompt, vttCli, ittCli, sampleInterval);
+  const descRaw = runVTT(normInfo.path, descPrompt, DEFAULT_VTT_CLI, DEFAULT_ITT_CLI, sampleInterval);
   const descText = stripThinkBlocks(extractRawText(descRaw));
   perception.desc = descText.slice(0, 500) || looseJSONParse(descRaw)?.desc || descRaw.slice(0, 500);
 
   // 2. STT → VTT subtitle
   emitInfo(`  Running speech-to-text...`);
-  perception.subtitle = runSTT(videoPath, normDir, sttCli);
+  perception.subtitle = runSTT(videoPath, normDir, DEFAULT_STT_CLI);
 
   // 3. Build merged cue timeline from VTT + user hints + ffprobe
   emitInfo(`  Building merged segment boundaries...`);
@@ -843,7 +838,7 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
     if (!existsSync(dummyInput)) {
       writeFileSync(dummyInput, Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "base64"));
     }
-    const segRaw = runAgent(dummyInput, `${segPrompt}\n\nInput:\n${segInput}`, agentCli || ittCli);
+    const segRaw = runAgent(dummyInput, `${segPrompt}\n\nInput:\n${segInput}`, DEFAULT_AGENT_CLI || DEFAULT_ITT_CLI);
     const segParsed = looseJSONParse(segRaw);
 
     if (segParsed && typeof segParsed === "object" && Object.keys(segParsed).length > 0) {
@@ -903,7 +898,7 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
       } else { clipPath = clipOut; }
 
       // Use runVTT for video clips (extracts frames, then runs ITT)
-      const segRawVis = runVTT(clipPath, visSegPrompt, vttCli, ittCli, sampleInterval);
+      const segRawVis = runVTT(clipPath, visSegPrompt, DEFAULT_VTT_CLI, DEFAULT_ITT_CLI, sampleInterval);
       const segVisText = extractRawText(segRawVis);
       seg.vision = stripThinkBlocks(looseJSONParse(segRawVis)?.desc || segVisText.slice(0, 300) || segRawVis.slice(0, 300));
       try { if (clipPath !== normInfo.path) rmSync(clipPath, { force: true }); } catch {}
@@ -917,7 +912,7 @@ function analyzeVideo(videoPath, normInfo, normDir, prompts, vttCli, sttCli, con
 
 // ── Full pipeline runner (step 2: label → normalize → percept → segments) ──
 
-async function runFullPipeline(folder, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, dryRun, agentCli = null) {
+async function runFullPipeline(folder, prompts, context, pickSet, vttSampleInterval, skipSTT, dryRun) {
   const metadataPath = join(folder, "metadata.json");
 
   // ── Ensure metadata exists ──────────────────────────────────────────
@@ -987,12 +982,12 @@ async function runFullPipeline(folder, prompts, ittCli, vttCli, sttCli, context,
     return;
   }
 
-  await runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, agentCli);
+  await runNormalizeAndPercept(folder, metadataPath, prompts, context, pickSet, vttSampleInterval, skipSTT);
 }
 
 // ── Normalize + Percept (internal step) ───────────────────────────────────
 
-async function runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, agentCli = null) {
+async function runNormalizeAndPercept(folder, metadataPath, prompts, context, pickSet, vttSampleInterval, skipSTT) {
   const { results, cacheMap } = loadMetadata(folder);
   const cache = { ...cacheMap };
   const normDir = join(folder, ".normalized");
@@ -1022,14 +1017,14 @@ async function runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vtt
     let cacheKey = "";
     const ctx = context ? `Context: ${context}\n\n` : "";
     const imgPrompt = (userHint ? `User hint: ${userHint}\n\n` : "") + ctx + getPrompt(prompts, "image-perception");
-    const imgInput = `${ittCli ? "" : "@"}${shQuote(normPath)}`;
-    const imgCmd = substituteTemplate(ittCli || DEFAULT_ITT_CLI, { input: imgInput, prompt: imgPrompt });
+    const imgInput = `@${shQuote(normPath)}`;
+    const imgCmd = substituteTemplate(DEFAULT_ITT_CLI, { input: imgInput, prompt: imgPrompt });
     cacheKey = perceptionCacheKey(imgPath, imgCmd, "image");
     if (cache[cacheKey]) {
       perception = cache[cacheKey];
       emitInfo(`  (cached)`);
     } else {
-      perception = analyzeImage(imgPath, normPath, prompts, ittCli, context, userHint, userHints);
+      perception = analyzeImage(imgPath, normPath, prompts, context, userHint, userHints);
       if (perception.desc) cache[cacheKey] = perception;
       emitInfo(`  ${perception.desc?.slice(0, 80)}...`);
     }
@@ -1057,27 +1052,25 @@ async function runNormalizeAndPercept(folder, metadataPath, prompts, ittCli, vtt
     emitInfo(`\n🎬 Video: ${base}${userHint ? ` (hint: "${userHint}")` : ""}`);
     const vidPath = join(folder, fileName);
     const normInfo = normalizeVideo(vidPath, normDir, meta.duration);
-    const stt = skipSTT ? null : sttCli;
-
     let perception = {};
     let cacheKey = "";
     const ctxV = context ? `Context: ${context}\n\n` : "";
     const vidPrompt = (userHint ? `User hint: ${userHint}\n\n` : "") + ctxV + getPrompt(prompts, "video-perception");
     let vttActualCmd;
-    if (vttCli) {
-      vttActualCmd = substituteTemplate(vttCli, { input: shQuote(normInfo.path), prompt: vidPrompt });
+    if (DEFAULT_VTT_CLI) {
+      vttActualCmd = substituteTemplate(DEFAULT_VTT_CLI, { input: shQuote(normInfo.path), prompt: vidPrompt });
     } else {
       const dur = meta.duration || 0;
       const n = Math.max(5, Math.min(10, Math.ceil(dur / vttSampleInterval)));
       const framePaths = Array.from({ length: n }, (_, i) => `${basename(normInfo.path, extname(normInfo.path))}_${String(i + 1).padStart(3, "0")}.jpg`);
-      vttActualCmd = substituteTemplate(ittCli || DEFAULT_ITT_CLI, { input: framePaths.map(p => `@${p}`).join(" "), prompt: vidPrompt });
+      vttActualCmd = substituteTemplate(DEFAULT_ITT_CLI, { input: framePaths.map(p => `@${p}`).join(" "), prompt: vidPrompt });
     }
     cacheKey = perceptionCacheKey(vidPath, vttActualCmd, "video");
     if (cache[cacheKey]) {
       perception = cache[cacheKey];
       emitInfo(`  (cached)`);
     } else {
-      perception = analyzeVideo(vidPath, normInfo, normDir, prompts, vttCli, stt, context, userHint, ittCli, vttSampleInterval, agentCli, userHints);
+      perception = analyzeVideo(vidPath, normInfo, normDir, prompts, context, userHint, vttSampleInterval, userHints);
       if (perception.desc) cache[cacheKey] = perception;
     }
 
@@ -1105,10 +1098,6 @@ Usage:
 
 Options:
   --label              Open label preview → then continue with full AI pipeline
-  --agent <template>   Custom text LLM CLI for detect-scenes ({prompt})
-  --itt <template>     Custom ITT CLI template with {input}, {prompt}
-  --vtt <template>     Custom VTT CLI template with {input}, {prompt}
-  --stt <template>     Custom STT CLI template with {input}, {output}
   --prompts-file <path> Path to prompts markdown file (default: vision_prompts.md)
   --vtt-sample-interval <n> Sample one video frame every N seconds (default: 5)
   --context "text"     Background context about people/places (injected into prompts)
@@ -1116,7 +1105,6 @@ Options:
   --skip-stt           Skip speech-to-text for videos
   --dry-run            Show what would be processed without running AI
   --show-prompts       Print the prompts file and exit
-  --show-clis          Print the default ITT/VTT/STT CLI templates
   --help               Show this help
 
 Prompt overrides:
@@ -1126,10 +1114,6 @@ Prompt overrides:
 
 export async function main(args) {
   let folder = "";
-  let agentCli = null;
-  let ittCli = null;
-  let vttCli = null;
-  let sttCli = null;
   let promptsFile = PROMPTS_FILE;
   let context = "";
   let vttSampleInterval = DEFAULT_VTT_SAMPLE_INTERVAL;
@@ -1147,20 +1131,12 @@ export async function main(args) {
     const flag = args[i++];
     if (flag === "--help") { printUsage(); return; }
     else if (flag === "--label") { doLabel = true; }
-    else if (flag === "--agent" && args[i]) { agentCli = args[i++]; }
-    else if (flag === "--itt" && args[i]) { ittCli = args[i++]; }
-    else if (flag === "--vtt" && args[i]) { vttCli = args[i++]; }
-    else if (flag === "--stt" && args[i]) { sttCli = args[i++]; }
+
     else if (flag === "--prompts-file" && args[i]) { promptsFile = resolve(args[i++]); }
     else if (flag === "--vtt-sample-interval" && args[i]) { vttSampleInterval = parseInt(args[i++], 10) || DEFAULT_VTT_SAMPLE_INTERVAL; }
     else if (flag === "--context" && args[i]) { context = args[i++]; }
     else if (flag === "--show-prompts") { console.log(readFileSync(promptsFile, "utf-8")); return; }
-    else if (flag === "--show-clis") {
-      console.log(`DEFAULT_ITT_CLI:\n${DEFAULT_ITT_CLI}\n`);
-      console.log(`DEFAULT_VTT_CLI: (empty — uses ITT via frame extraction, sample every ${DEFAULT_VTT_SAMPLE_INTERVAL}s)\n`);
-      console.log(`DEFAULT_STT_CLI:\n${DEFAULT_STT_CLI}`);
-      return;
-    }
+
     else if (flag === "--skip-stt") { skipSTT = true; }
     else if (flag === "--pick" && args[i]) { for (const f of args[i++].split(",")) pickSet.add(f.trim()); }
     else if (flag === "--dry-run") { dryRun = true; }
@@ -1175,7 +1151,7 @@ export async function main(args) {
   for (const [name, value] of promptOverrides) prompts.set(name, value);
 
   if (doLabel) {
-    await runFullPipeline(folder, prompts, ittCli, vttCli, sttCli, context, pickSet, vttSampleInterval, skipSTT, dryRun, agentCli);
+    await runFullPipeline(folder, prompts, context, pickSet, vttSampleInterval, skipSTT, dryRun);
   } else {
     await runMetadataMode(folder, pickSet, dryRun);
   }

package/skills/markcut/docs/template.md

@@ -1,212 +0,0 @@
-# Markcut Template System
-
-> How to design and build video templates that agents can follow to produce professional, consistent videos.
-
-## Why templates?
-
-Markcut templates encode **domain expertise + production polish** into a reusable package. An agent reading a template learns not just markcut syntax, but:
-
-- **What** makes a good video of this type (scene structure, pacing, rules)
-- **How** to assemble it (workflow: prompts → agents → render → review)
-- **Why** certain patterns work (production polish: transition timing, overlays, effects)
-
-## Template package structure
-
-```
-templates/<name>/
-  TEMPLATE.md          ← The single entry point. Everything except prompts & agents.
-  prompts/
-    <step>.md          ← Fill-in prompt templates. Run in the orchestrator's context.
-    ...
-  agents/
-    <name>.md          ← Subagent definitions. Run in separate, isolated sessions.
-    ...
-  example.md           ← (optional) A complete worked example.
-  example.mp4          ← (optional) Rendered output for reference.
-```
-
-### File type conventions
-
-| File | Context | Purpose |
-|---|---|---|
-| `TEMPLATE.md` | Orchestrator's context | Complete spec: inputs, structure, rules, workflow, quality gate, components, styles |
-| `prompts/*.md` | Orchestrator's context | Fill-in-the-blank prompt templates; the orchestrator replaces `{placeholder}` values and executes them |
-| `agents/*.md` | **Separate** session | Full agent definitions with system prompt + task template. Each runs in a fresh, isolated subagent session with its own tools and context |
-
-### Why separate prompts/ and agents/?
-
-- **prompts/** — tasks the orchestrator does itself (outline generation, scene writing, fix application). These run in the orchestrator's own session so they have full context of the entire project.
-- **agents/** — tasks that benefit from isolation (review, specialized generation). These run in separate sessions to avoid context pollution and to use specialized system prompts without interference.
-
-## Anatomy of TEMPLATE.md
-
-Every `TEMPLATE.md` follows this section order:
-
-```
-§0  Prerequisites       — tools, skills, environment checks
-§1  Inputs              — what the orchestrator must collect from the user
-§2  Scene grammar       — the canonical tree structure with hard rules
-§3  Authoring rules     — professional-quality bar for content (text, timing, media)
-§4  Components & styles — copy-verbatim code blocks with documented theme knobs
-§5  Workflow            — numbered steps: prompts → agents → render → review
-§6  Quality gate        — measurable exit criteria (the reviewer checks these)
-§7  Reference           — links to golden examples or related docs
-```
-
-### §0 Prerequisites
-
-What tools/skills the agent needs before starting. Always include:
-
-- The engine itself: `npx @lalalic/markcut` runnable
-- Required markcut skill (`SKILL.md` + `docs/markdown-descriptive.md`) — the agent must read these
-- Any domain-specific tools
-
-### §1 Inputs — the contract with the user
-
-A table of what the orchestrator must collect before starting. Each row:
-
-| Input | Required | Default | Notes |
-|---|---|---|---|
-
-**Rule:** never invent content beyond given material + well-established knowledge. Missing or ambiguous inputs → ask the user, never fabricate.
-
-### §2 Scene grammar — the tree shape
-
-The backbone. Show both:
-
-1. **An ASCII tree diagram** of the required structure with layout/transition annotations
-2. **Concrete code blocks** showing the exact node structure for each scene type
-
-Hard rules come here: number of scenes, layouts, transitions, `isBackground` usage, timing rules, etc.
-
-**Crucial design principle:** make the tree as explicit as possible. Show node types, `id:` values, `on:` events, positioning styles. Don't leave structural decisions to the agent.
-
-### §3 Authoring rules — the professional bar
-
-Rules the reviewer checks. Cover:
-
-- Slide/content rules (max bullets, text shape, emoji conventions, table usage)
-- Script/narration rules (pacing, per-sentence structure, example placement, tone)
-- Media rules (positioning, sizing, where media can overlay)
-- Multi-language variant rules
-- Domain-specific rules (e.g. "never fabricate facts" for courseware, "ground every line in clip captions" for vlog)
-
-### §4 Components & styles — copy verbatim
-
-The trickiest section. Two code blocks:
-
-1. **`~~~js imports` block** — all JSX component definitions the video needs. The agent copies this verbatim. Mark which parts are theme knobs (values that can change) vs structural (must stay the same).
-2. **`~~~css stylesheet` block** — all CSS. Same rules: theme knobs documented, structure immutable.
-
-In addition, a **theme knobs table** showing what the user can change (colors, fonts, sizes) and their defaults.
-
-**Best practice:** keep the component block minimal. One reusable `Slide` component is better than ten one-off components. Use standard markcut features (`- image`, `- video`, `- component`, `- effect`) before writing custom JSX.
-
-### §5 Workflow — the orchestrator's playbook
-
-Numbered steps from start to finish. Each step is one of:
-
-- **Fill a prompt** — "Fill `prompts/outline.md` → course outline. Present to user for confirmation."
-- **Run a subagent** — "Run `agents/reviewer.md` in a fresh session. Pass it these absolute paths."
-- **Execute a CLI command** — "`npx @lalalic/markcut render course.md`"
-- **User interaction** — "Get user approval before continuing."
-
-Include fix loops:
-
-> 6. **Fix loop** — on FAIL: fill `prompts/fix.md` with the findings, apply edits, re-render. Max 3 iterations, then escalate to user.
-
-### §6 Quality gate — measurable exit criteria
-
-The checklist the reviewer uses. Each item must be machine-verifiable (by reviewing source, extracting frames, running STT, measuring duration). Examples:
-
-- Total duration within ±15% of target
-- Structure matches §2 (hook, title, N concepts, summary, thanks)
-- No blank/black frames at scene boundaries
-- STT transcript matches scripts (≥90% content match)
-- Each bullet has a narration beat
-
-### §7 Reference — worked examples
-
-Link to golden example files in `tests/fixtures/templates/`. The golden example demonstrates every rule in the template applied correctly.
-
-## Production polish patterns (reusable)
-
-These are design patterns you can include in any template. They're documented in detail in the courseware template (§2.b) but summarized here:
-
-| Pattern | Technique | Use case |
-|---|---|---|
-| **Per-beat media** | `#### Beat` sub-scenes with `layout:parallel` (image + script per beat) | Courseware slides, tutorial demos |
-| **Transition-audio timing** | `start:<T>` on script nodes in `transitionSeries` | Any scripted scene with transitions |
-| **Persistent overlay** | `- image isBackground:true` at root level | Logo, watermark |
-| **Narrator PiP** | `- video/image isBackground:true` with border-radius + name label | Talking-head overlays |
-| **Entrance effects** | `effect:zoomIn` / `effect:fadeIn` on images/components | Reveal animations |
-| **Mermaid diagrams** | ` ```mermaid ` in slide markdown | Flowcharts, architecture, timelines |
-| **TTS expression** | `—` pauses, `*emphasis*`, rate adjustment, phonetic spelling | Natural speech |
-
-## Prompt design principles
-
-### prompts/*.md
-- Use `{placeholder}` values for every input. The orchestrator replaces these before executing.
-- Include constraints from TEMPLATE.md inline so the prompt is self-contained.
-- Output format should be a concrete template the orchestrator can parse and assemble.
-
-### agents/*.md
-- Must include a **system prompt** (top) and a **task template** (bottom, filled by orchestrator).
-- System prompt defines the agent's role, rules, and procedure.
-- Task template uses `{placeholder}` values for paths, params, and inputs.
-- Always mark the agent as `mode: read-only` if it shouldn't edit files.
-- Include an explicit output schema (JSON format) so the orchestrator can parse results reliably.
-- List which tools the agent needs (read, bash, ffmpeg, etc.).
-
-## Choosing prompts vs agents
-
-| Task type | Where | Why |
-|---|---|---|
-| Creative generation (write a scene) | `prompts/` | Needs full context of the project; best done by orchestrator |
-| Factual check (review) | `agents/` | Needs fresh context; strict rubric; no editing |
-| Research (find images, analyze) | `agents/` | Parallelizable; heavy tool use |
-| Outline / planning | `prompts/` | Needs user interaction (confirm outline) |
-| Quality fix | `prompts/` | Orchestrator applies edits, runs tools |
-
-## Testing a template
-
-1. **Generate** — have a model follow the template to produce a video markdown
-2. **Render** — `npx @lalalic/markcut render <output>.md`
-3. **Review** — run the reviewer agent on the rendered output
-4. **Fix** — apply fixes, re-render, re-review
-5. **Verify** — check frames visually, check STT transcript
-
-The courseware template's test loop is the reference:
-
-```
-Agent (deepseek-v4-flash + SKILL.md + markdown spec) → course.md
-└→ npx markcut render → course.mp4
-   └→ Reviewer agent (separate session) → PASS/FAIL + findings
-      └→ Fix → re-render → re-review (max 3x)
-```
-
-## Built-in templates
-All builtin templates are in `templates/` and can be used as-is or forked for your own. Each has a `TEMPLATE.md` with full instructions.
-
-## Cross-cutting concerns
-
-### Multi-language
-- Use variant blocks (`# <lang>` at file end) with per-language TTS voice.
-- Every script node has a `<lang>:"..."` twin; every slide source has a `<lang>-source` twin.
-- The engine resolves variants via `parseMarkdownVariants`.
-
-### Reviewer design
-- Always `mode: read-only` — reviewers report findings, never edit.
-- Two-phase: static (source vs rulebook) + dynamic (rendered artifact via ffprobe/ffmpeg/STT/vision).
-- Output: strict JSON with `{verdict, measured, findings[]}`. Each finding has `id`, `severity`, `scene`, `check`, `issue`, `evidence`, `fix_hint`.
-- PASS requires zero `blocker` and zero `major` findings.
-
-### The "orchestrator" role
-The orchestrator is the agent reading the template. It:
-1. Collects inputs from the user
-2. Executes prompts in its own context
-3. Spawns subagents in separate sessions for isolated tasks
-4. Assembles, renders, fixes, and iterates
-5. Escalates to the human user when stuck
-
-The template is written FOR the orchestrator. Every instruction is an actionable command: "fill this prompt", "run this agent", "render the file", "if FAIL, fix and re-render".