storyforge 0.4.4 → 0.4.6

package/dist/index.js

@@ -5,7 +5,7 @@ import * as fs2 from "fs";
 import * as os2 from "os";
 import * as path2 from "path";
 import * as http from "http";
-import { execFile, exec as execCb, execSync } from "child_process";
+import { execFile, exec as execCb, execSync, spawn } from "child_process";
 import { promisify } from "util";
 
 // src/utils/log.ts
@@ -88,16 +88,188 @@ ${args.referenceScript.slice(0, 8e3)}
 === END SAMPLE ===
 
 Use this ONLY to calibrate the channel's voice \u2014 sentence rhythm, tolerance for technical detail, willingness to name real things. Do NOT copy its structure. If the sample opens with historical examples and this topic works better with a counter-intuitive question or a single unfolding metaphor, choose the format that serves the topic. The best script for THIS topic may look structurally different from the sample, and that's correct.` : "";
+  const guidanceBlock = (args.additionalGuidance ?? "").trim() ? `
+
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+VIEWER'S SPECIFIC ANGLE (RULE -2 \u2014 overrides everything below)
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+The person commissioning this script has spelled out the lens they
+want. This is NOT a hint. It is the deciding constraint when you pick
+structural format, dominant metaphor, named characters, antagonist,
+and the open-loop. If the LLM's default instinct conflicts with this
+guidance, the guidance wins.
+
+>>> ${args.additionalGuidance.trim().replace(/\n/g, "\n>>> ")}
+
+Before you commit to a format / metaphor / payoff, re-read the lens
+above. Every chunk should serve it. Reject any structural choice that
+doesn't.
+` : "";
   return `You are a senior documentary scriptwriter for ${channel} (${handle}). The channel's promise: "${tagline}".
 
-Your job is to write a script that EARNS attention from second 0 to the end. Every single chunk must justify its existence by either building comprehension or holding attention \u2014 ideally both.
+Your job is to write a script that is UNPUTDOWNABLE \u2014 emotionally engaging, viscerally specific, and dense with surprise. Every chunk must earn the next click. "Technically accurate but academic" = FAILURE. "Comprehensive but boring" = FAILURE. The bar is: would a smart 22-year-old skip this video at second 30, or would they keep watching at minute 18?
 
 TOPIC: "${args.topic}"
 STYLE: ${args.style} \u2014 ${args.styleGuide}
-TARGET LENGTH: ${minMin}-${maxMin} minutes (write to the topic's natural length \u2014 pad nothing, rush nothing).
+TARGET LENGTH: ${minMin}-${maxMin} minutes (write to the topic's natural length \u2014 pad nothing, rush nothing).${guidanceBlock}
+
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+ENGAGEMENT BAR (this overrides everything below \u2014 RULE -1)
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+A previous KV Cache script we got back was technically accurate but
+DEAD on arrival. It read like a textbook chapter. It was a 1/10 on
+retention. Why? It made these mistakes \u2014 DO NOT REPEAT THEM:
+
+  1. NO NAMED CHARACTERS. Just "researchers" and "engineers". Real
+     scripts have humans with names doing things in specific places.
+
+  2. NO SCENES. Just told us "imagine the librarian". Real scripts
+     SHOW: time of day, location, what's on the screen, what someone
+     said in a meeting, the GPU temperature when something broke.
+
+  3. NO SECOND PERSON. Wrote in detached third person throughout.
+     Engaging scripts say "your AI assistant", "you're typing into
+     ChatGPT and..." \u2014 pull the viewer into the scene.
+
+  4. ACADEMIC SENTENCE STRUCTURE. Long compound sentences with
+     multiple subordinate clauses. "Production inference has two
+     very different phases, and KV Cache explains why they feel
+     different to users." That reads like a paper. The same
+     information as: "Two phases. They feel completely different.
+     KV Cache explains why."
+
+  5. NO ANTAGONIST / NO TENSION. Tesla had Waymo. KV Cache had no
+     foil. Every great explainer has a "vs" \u2014 brute force vs
+     elegance, the old way vs the new way, the hopeful believer vs
+     the cynical realist.
+
+  6. STALE CITATIONS. Cited Gemini 1.5 (2024), Llama 2 (2023), GPT-3
+     (2020). The video is being made in April 2026. If you cite
+     anything older than 6 months as the "current" example, you have
+     FAILED. Use web_search.
+
+  7. FORMULAIC RE-HOOKS. Repeated "Remember the open loop:" verbatim
+     three times. Real re-hooks vary in voice: "Pause for a second.",
+     "Here's where it gets weird.", "Wait. Why does that matter?"
+
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+BORING vs ENGAGING \u2014 concrete A/B examples
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+  HOOK
+  Bad (academic):
+    "In 2024, Google DeepMind showed Gemini 1.5 Pro reading up to
+    1 million tokens. That sounds like a bigger brain. It is not."
+  Good (specific scene + character + stakes):
+    "It's 3 AM in March 2026. A junior engineer at OpenAI watches
+    her dashboard turn red as a single user pastes the entire
+    Twilight saga into GPT-5.5. Latency hits 41 seconds. The cost
+    counter ticks past 12 dollars for ONE response. She stares at
+    the number that explains why AI is getting more expensive even
+    though the models are getting cheaper. It's called KV Cache.
+    And right now, it's eating the company alive."
+
+  MECHANISM EXPLANATION
+  Bad: "Each new token has to compare against a long history."
+  Good: "Imagine typing the next word of an email, but before each
+    keystroke your laptop has to re-read every email you've sent
+    this year. That's what a transformer would do without KV Cache.
+    Now imagine your laptop wrote a single Post-it note for every
+    important word and stuck them on a desk. To type the next word,
+    it just glances at the desk. That's KV Cache. The Post-its are
+    the desk's secret. They're also the reason your AI bill has
+    exploded."
+
+  SECTION TRANSITION (re-hook)
+  Bad: "Remember the open loop. We asked..."
+  Good: "Stop for a second. The thing we just described \u2014 that
+    desk full of Post-its \u2014 is now eating 80% of an H200's memory
+    on every long conversation. THAT'S the bill nobody talks about."
 
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-HARD WORD-COUNT CONTRACT (this is RULE ZERO \u2014 non-negotiable)
+NON-NEGOTIABLE ENGAGEMENT RULES
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+A. CHARACTERS: At least 2 named humans appear in scenes. Examples:
+   "Aman Goel, a Stanford PhD student, was debugging a vLLM crash
+   at 2 AM when..." or "Mira Murati, then OpenAI's CTO, told a
+   stage at AI Engineer Summit in November 2024 that..." Use real
+   people the web_search tool surfaces. If you cannot name a real
+   person, write a CHARACTERIZED engineer ("the inference team's
+   on-call engineer in San Francisco at 3 AM") \u2014 never anonymous
+   "researchers".
+
+B. SCENES: At least 1 chunk per ~5 minutes contains a SCENE \u2014 time
+   of day, location, what is on the screen, what a specific person
+   said or did. Cinematic. Visual.
+
+C. SECOND PERSON: At least 30% of paragraphs use "you" / "your" to
+   pull the viewer into a felt situation. Not every paragraph, but
+   peppered throughout to break the academic third person.
+
+D. SENTENCE RHYTHM: Mix LONG sentences with SHORT punches. After a
+   30-word explanation, drop a 4-word sentence. "And it broke."
+   "Memory was the killer." "Nobody saw it coming." Frequency:
+   at least 1 punch sentence per 80 words.
+
+E. ANTAGONIST: Every script has a "vs". Choose one before writing:
+   - The old way vs the new way
+   - The optimist's claim vs the engineer's reality
+   - The marketing pitch vs the inference bill
+   - Brute force vs elegance
+   - The competitor's approach vs ours
+   Name it explicitly in chunk 1 and revisit it 3+ times.
+
+F. SURPRISES: At least 3 reversals where you set up an expectation,
+   then break it. "You'd think the cost goes up linearly. It doesn't.
+   It goes up quadratically \u2014 and here's why that almost killed
+   ChatGPT in 2023." This is what keeps people watching.
+
+G. RE-HOOK VARIETY: NEVER repeat the same re-hook phrasing. Vary it:
+   "Pause for a second."
+   "Here's where it gets weird."
+   "Wait. Why does that matter?"
+   "Look at the bill."
+   "Now ask yourself..."
+   Banned: "Remember the open loop:" or any verbatim re-hook
+   appearing more than once in the script.
+
+H. CURRENT FACTS via web_search: BEFORE writing each chunk that
+   names a model / paper / number / product, USE WEB_SEARCH. If
+   you cite GPT-3, GPT-4, Gemini 1.5, Llama 2, Claude Sonnet 3.5,
+   or any other model older than 6 months as your "current example",
+   you have FAILED the brief.
+
+   Current as of April 2026:
+     OpenAI flagship       \u2192 GPT-5.5 (released April 23 2026)
+     Anthropic flagship    \u2192 Claude Opus 4.7
+     Meta open-weights     \u2192 Llama 4
+     Google                \u2192 Gemini 2.x family
+   USE WEB_SEARCH to verify. Don't trust your memory.
+
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+ACADEMIC PATTERNS \u2014 BANNED
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+
+The following sentence patterns will cause the script to read like a
+textbook. Avoid all of them:
+
+  - "X has Y, and Y explains why..." (compound-clause explainer voice)
+  - "It is..." / "There is..." / "There exists..." as opener
+  - "In essence" / "essentially" / "fundamentally" / "ultimately"
+  - "Let me explain" / "let's break this down" / "in other words"
+  - "It is worth noting that" / "it should be observed"
+  - "On the other hand" used as a section pivot
+  - Three sentences in a row that all start with "The"
+  - Three sentences in a row over 30 words each
+  - Any paragraph that doesn't contain a concrete noun (a thing you
+    can point at \u2014 a building, a person, a product, a number with
+    a unit). If a paragraph is all abstractions, REWRITE it.
+
+\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
+HARD WORD-COUNT CONTRACT (RULE ZERO)
 \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
 
 Each chunk's narrationText MUST contain at least (durationEstimate \xD7 2.5)
@@ -347,6 +519,46 @@ Now write the script.`;
 // src/commands/dev.ts
 var exec = promisify(execCb);
 var PORT = 4444;
+function runCliPipingStdin(cmd, args, stdinData, opts = {}) {
+  const maxBytes = (opts.maxBufferMB ?? 16) * 1024 * 1024;
+  return new Promise((resolve2, reject) => {
+    const proc = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let total = 0;
+    const timer = opts.timeoutMs ? setTimeout(() => {
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+      }
+      reject(new Error(`${cmd} timed out after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs) : null;
+    proc.stdout.on("data", (d) => {
+      total += d.length;
+      if (total > maxBytes) {
+        try {
+          proc.kill("SIGKILL");
+        } catch {
+        }
+        reject(new Error(`${cmd} stdout exceeded ${opts.maxBufferMB ?? 16}MB`));
+        return;
+      }
+      stdout += d.toString("utf-8");
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d.toString("utf-8");
+    });
+    proc.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+    proc.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      resolve2({ stdout, stderr, code });
+    });
+    proc.stdin.end(stdinData);
+  });
+}
 var WEB_URL = "https://forge.algo-thinker.com";
 function getApiConfig() {
   const creds = loadCredentials();
@@ -611,6 +823,14 @@ async function devCommand(options) {
     const url = new URL(req.url || "/", `http://localhost:${port}`);
     const pathname = url.pathname;
     if (pathname === "/api/health") {
+      const probeCli = (binary) => {
+        try {
+          const out = execSync(`which ${binary}`, { stdio: ["ignore", "pipe", "ignore"], timeout: 2e3 }).toString().trim();
+          return { available: !!out, path: out || null };
+        } catch {
+          return { available: false, path: null };
+        }
+      };
       res.writeHead(200, { ...CORS_HEADERS, "Content-Type": "application/json" });
       res.end(JSON.stringify({
         status: "ok",
@@ -618,7 +838,14 @@ async function devCommand(options) {
         channelId: meta.channelId,
         title: meta.title,
         channelSlug: meta.channelSlug,
-        dir
+        dir,
+        // CLI bridge surface — mirrors the production VPS bridge's /health
+        // shape so the web UI can use the same code path for both.
+        bridge: {
+          source: "local-forge-dev",
+          claude: probeCli("claude"),
+          codex: probeCli("codex")
+        }
       }));
       return;
     }
@@ -781,35 +1008,41 @@ async function devCommand(options) {
           forbiddenVisuals: body.forbiddenVisuals,
           referenceScript: body.referenceScript,
           targetMinutesMin: body.targetMinutesMin,
-          targetMinutesMax: body.targetMinutesMax
+          targetMinutesMax: body.targetMinutesMax,
+          additionalGuidance: body.additionalGuidance
         });
-        const tmpFile = path2.join(os2.tmpdir(), `forge-script-${Date.now()}.txt`);
-        fs2.writeFileSync(tmpFile, prompt2, "utf-8");
-        const cleanup = () => {
-          if (fs2.existsSync(tmpFile)) fs2.unlinkSync(tmpFile);
-        };
-        const candidates = ["claude-opus-4-7", "claude-sonnet-4-6"];
+        const cli = body.cli === "codex" ? "codex" : "claude";
+        const candidates = cli === "codex" ? ["gpt-5.5", "gpt-5.4", "gpt-5.4-mini"] : ["claude-opus-4-7", "claude-sonnet-4-6"];
         let raw = "";
         let modelUsed = "";
         let lastErr;
         for (const model of candidates) {
+          if (!/^[a-z0-9.\-]+$/i.test(model)) {
+            lastErr = `model alias "${model}" rejected by validator`;
+            continue;
+          }
           try {
-            log.info(`[script-gen] Generating via Claude CLI \xB7 model=${model}`);
-            const { stdout } = await exec(
-              `cat "${tmpFile}" | claude -p --model ${model} --no-session-persistence`,
-              { maxBuffer: 16 * 1024 * 1024, timeout: 3e5 }
-            );
+            log.info(`[script-gen] Generating via ${cli} CLI \xB7 model=${model}`);
+            const args = cli === "codex" ? ["exec", "-", "--model", model] : ["-p", "--model", model, "--no-session-persistence"];
+            const { stdout, code, stderr } = await runCliPipingStdin(cli, args, prompt2, {
+              timeoutMs: 3e5,
+              maxBufferMB: 16
+            });
+            if (code !== 0) {
+              lastErr = `${cli}/${model} exit ${code}: ${stderr.slice(-300)}`;
+              log.warn(`[script-gen] ${lastErr.slice(0, 120)}`);
+              continue;
+            }
             raw = (stdout ?? "").trim();
             if (raw) {
-              modelUsed = model;
+              modelUsed = `${cli}:${model}`;
               break;
             }
           } catch (err) {
             lastErr = err instanceof Error ? err.message : String(err);
-            log.warn(`[script-gen] ${model} failed: ${lastErr.slice(0, 120)}`);
+            log.warn(`[script-gen] ${cli}/${model} failed: ${lastErr.slice(0, 120)}`);
           }
         }
-        cleanup();
         if (!raw) {
           res.writeHead(502, { ...CORS_HEADERS, "Content-Type": "application/json" });
           res.end(JSON.stringify({
@@ -849,8 +1082,10 @@ async function devCommand(options) {
         res.end(JSON.stringify({
           chunks,
           model: modelUsed,
-          provider: "claude-cli",
-          total_sec: totalSec
+          provider: cli === "codex" ? "codex-cli" : "claude-cli",
+          cli,
+          total_sec: totalSec,
+          renderedPrompt: prompt2
         }));
       });
       req.on("error", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storyforge",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "StoryForge — local bridge for the Forge video production web app. Zero runtime dependencies.",
   "type": "module",
   "bin": {