@kenkaiiii/gg-editor 0.7.0 → 0.7.2

package/dist/core/python.test.js

@@ -0,0 +1,129 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+function ok(stdout) {
+    return { pid: 0, status: 0, signal: null, output: [], stdout, stderr: "" };
+}
+function fail() {
+    return { pid: 0, status: 1, signal: null, output: [], stdout: "", stderr: "" };
+}
+describe("findPython caching", () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    afterEach(() => {
+        vi.doUnmock("node:child_process");
+        vi.resetModules();
+    });
+    it("returns the same PythonCmd on every call and only spawns once", async () => {
+        const calls = [];
+        vi.doMock("node:child_process", () => ({
+            spawnSync: (cmd, args) => {
+                calls.push({ cmd, args });
+                if (cmd === "python3")
+                    return ok("Python 3.11.4\n");
+                return fail();
+            },
+            spawn: () => {
+                throw new Error("spawn should not be called by findPython");
+            },
+        }));
+        const mod = await import("./python.js");
+        mod.__resetPythonCacheForTests();
+        const first = mod.findPython();
+        expect(first?.cmd).toBe("python3");
+        // Two probes on first call: --version, then sys.prefix.
+        expect(calls.length).toBe(2);
+        for (let i = 0; i < 25; i++) {
+            const next = mod.findPython();
+            expect(next).toBe(first);
+        }
+        // Cache hit — no further spawns.
+        expect(calls.length).toBe(2);
+    });
+    it("does not cache a negative result", async () => {
+        let probeCount = 0;
+        vi.doMock("node:child_process", () => ({
+            spawnSync: () => {
+                probeCount++;
+                return fail();
+            },
+            spawn: () => {
+                throw new Error("spawn should not be called");
+            },
+        }));
+        const mod = await import("./python.js");
+        mod.__resetPythonCacheForTests();
+        expect(mod.findPython()).toBeUndefined();
+        const probesAfterFirst = probeCount;
+        expect(probesAfterFirst).toBeGreaterThanOrEqual(3); // tries python3, python, py
+        // Second call must re-probe — Python may have been installed since.
+        expect(mod.findPython()).toBeUndefined();
+        expect(probeCount).toBeGreaterThan(probesAfterFirst);
+    });
+    it("falls back to `python` when `python3` is absent and caches it", async () => {
+        const calls = [];
+        vi.doMock("node:child_process", () => ({
+            spawnSync: (cmd) => {
+                calls.push(cmd);
+                if (cmd === "python")
+                    return ok("Python 3.12.1\n");
+                return fail();
+            },
+            spawn: () => {
+                throw new Error("spawn should not be called");
+            },
+        }));
+        const mod = await import("./python.js");
+        mod.__resetPythonCacheForTests();
+        const first = mod.findPython();
+        expect(first?.cmd).toBe("python");
+        const before = calls.length;
+        const second = mod.findPython();
+        expect(second).toBe(first);
+        expect(calls.length).toBe(before);
+    });
+    it("rejects a Python 2 candidate and keeps probing", async () => {
+        vi.doMock("node:child_process", () => ({
+            spawnSync: (cmd) => {
+                if (cmd === "python3")
+                    return fail();
+                if (cmd === "python")
+                    return ok("Python 2.7.18\n");
+                if (cmd === "py")
+                    return ok("Python 3.10.6\n");
+                return fail();
+            },
+            spawn: () => {
+                throw new Error("spawn should not be called");
+            },
+        }));
+        const mod = await import("./python.js");
+        mod.__resetPythonCacheForTests();
+        const py = mod.findPython();
+        expect(py?.cmd).toBe("py");
+        expect(py?.args).toEqual(["-3"]);
+    });
+    it("__resetPythonCacheForTests forces a fresh probe", async () => {
+        let probes = 0;
+        vi.doMock("node:child_process", () => ({
+            spawnSync: (cmd) => {
+                probes++;
+                if (cmd === "python3")
+                    return ok("Python 3.11.4\n");
+                return fail();
+            },
+            spawn: () => {
+                throw new Error("spawn should not be called");
+            },
+        }));
+        const mod = await import("./python.js");
+        mod.__resetPythonCacheForTests();
+        mod.findPython();
+        const afterFirst = probes;
+        mod.findPython();
+        expect(probes).toBe(afterFirst); // cached
+        mod.__resetPythonCacheForTests();
+        mod.findPython();
+        expect(probes).toBeGreaterThan(afterFirst); // re-probed
+    });
+});
+//# sourceMappingURL=python.test.js.map

package/dist/core/python.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.test.js","sourceRoot":"","sources":["../../src/core/python.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAgBzE,SAAS,EAAE,CAAC,MAAc;IACxB,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC7E,CAAC;AAED,SAAS,IAAI;IACX,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACjF,CAAC;AAED,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,YAAY,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC;QAClC,EAAE,CAAC,YAAY,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,KAAK,GAAoD,EAAE,CAAC;QAClE,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAC;YACrC,SAAS,EAAE,CAAC,GAAW,EAAE,IAAuB,EAAE,EAAE;gBAClD,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC1B,IAAI,GAAG,KAAK,SAAS;oBAAE,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;gBACpD,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YACD,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;YAC9D,CAAC;SACF,CAAC,CAAC,CAAC;QAEJ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QAEjC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACnC,wDAAwD;QACxD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,iCAAiC;QACjC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;QAChD,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAC;YACrC,SAAS,EAAE,GAAG,EAAE;gBACd,UAAU,EAAE,CAAC;gBACb,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YACD,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;YAChD,CAAC;SACF,CAAC,CAAC,CAAC;QAEJ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QAEjC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC;QACzC,MAAM,gBAAgB,GAAG,UAAU,CAAC;QACpC,MAAM,CAAC,gBAAgB,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,4BAA4B;QAEhF,oEAAoE;QACpE,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,aAAa,EAAE,CAAC;QACzC,MAAM,CAAC,UAAU,CAAC,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAC;YACrC,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE;gBACzB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAChB,IAAI,GAAG,KAAK,QAAQ;oBAAE,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;gBACnD,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YACD,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;YAChD,CAAC;SACF,CAAC,CAAC,CAAC;QAEJ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QAEjC,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;QAC/B,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAElC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC5B,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAC;YACrC,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE;gBACzB,IAAI,GAAG,KAAK,SAAS;oBAAE,OAAO,IAAI,EAAE,CAAC;gBACrC,IAAI,GAAG,KAAK,QAAQ;oBAAE,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;gBACnD,IAAI,GAAG,KAAK,IAAI;oBAAE,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;gBAC/C,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YACD,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;YAChD,CAAC;SACF,CAAC,CAAC,CAAC;QAEJ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QAEjC,MAAM,EAAE,GAAG,GAAG,CAAC,UAAU,EAAE,CAAC;QAC5B,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;QAC/D,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,EAAE,CAAC,MAAM,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,CAAC;YACrC,SAAS,EAAE,CAAC,GAAW,EAAE,EAAE;gBACzB,MAAM,EAAE,CAAC;gBACT,IAAI,GAAG,KAAK,SAAS;oBAAE,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;gBACpD,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YACD,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;YAChD,CAAC;SACF,CAAC,CAAC,CAAC;QAEJ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;QACxC,GAAG,CAAC,0BAA0B,EAAE,CAAC;QAEjC,GAAG,CAAC,UAAU,EAAE,CAAC;QACjB,MAAM,UAAU,GAAG,MAAM,CAAC;QAC1B,GAAG,CAAC,UAAU,EAAE,CAAC;QACjB,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QAE1C,GAAG,CAAC,0BAA0B,EAAE,CAAC;QACjC,GAAG,CAAC,UAAU,EAAE,CAAC;QACjB,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/core/retention-structure.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Retention-structure auditor.
+ *
+ * Long-form videos live or die at the 3-min and 6-min marks. Per the
+ * MrBeast manual: every ~3 minutes a "mini-hook" / re-engagement is
+ * required — a twist, a reveal, a visual spectacle, an escalation. Flat
+ * stretches between mini-hooks bleed retention; the YouTube graph
+ * shows the dip almost every time.
+ *
+ * This module:
+ *   1. Builds a 60s window centred on each requested checkpoint.
+ *   2. Bundles all windows + a compact transcript outline into ONE LLM call.
+ *   3. Parses the response into a structured report with per-checkpoint
+ *      scores + an overall escalation pattern score.
+ *
+ * Pure parser + window-builder for unit tests; the network call lives
+ * here too but is exported as `runRetentionAudit` so the wrapper tool
+ * stays thin.
+ */
+import type { Transcript } from "./whisper.js";
+export interface RetentionWindow {
+    /** Centre of the window. */
+    atSec: number;
+    /** Inclusive [startSec, endSec]. */
+    startSec: number;
+    endSec: number;
+    /** Concatenated transcript text falling inside the window. */
+    text: string;
+}
+export interface CheckpointScore {
+    atSec: number;
+    /** 0-1. ≥0.5 = re-engagement detected. <0.5 = flat / weak. */
+    score: number;
+    /** ≤120 char description of what's happening at this checkpoint. */
+    summary: string;
+    /** ≤200 char actionable suggestion when score < 0.5. Empty otherwise. */
+    suggestion: string;
+}
+export interface RetentionAuditResult {
+    checkpoints: CheckpointScore[];
+    /** 0-1. Does the video build progressively (1) or stay flat (0)? */
+    escalationScore: number;
+    /** ≤200 char overall verdict. */
+    overallSummary: string;
+    /** atSec of the lowest-scoring checkpoint (-1 when checkpoints is empty). */
+    weakestCheckpoint: number;
+}
+/**
+ * Build a 60s window centred on `atSec`, clamped to [0, totalSec].
+ * Returns the concatenated transcript text inside the window for LLM
+ * context. Pure — exported for testing.
+ */
+export declare function buildWindow(t: Transcript, atSec: number, totalSec: number, windowSec?: number): RetentionWindow;
+/**
+ * Compact transcript outline — every Nth segment trimmed to ~60 chars
+ * with a leading [t]s tag. Keeps the LLM grounded in overall pacing
+ * without blowing the context budget on a long transcript.
+ */
+export declare function buildOutline(t: Transcript, maxLines?: number): string;
+export interface RetentionAuditOptions {
+    apiKey?: string;
+    model?: string;
+    /** Default [180, 360] (3min, 6min). */
+    checkpoints?: number[];
+    /** Override transcript.durationSec (e.g. when you trust ffprobe more). */
+    durationSec?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Run ONE LLM audit pass and return the structured result. Throws on
+ * network / parse error so the wrapper can convert to err().
+ */
+export declare function runRetentionAudit(t: Transcript, opts?: RetentionAuditOptions): Promise<RetentionAuditResult>;
+/**
+ * Parse the model's JSON. Robust to missing keys; pads checkpoints to
+ * match the requested order so the caller can correlate by index.
+ *
+ * Pure — exported for testing.
+ */
+export declare function parseAuditResponse(content: string, requested: number[]): RetentionAuditResult;
+//# sourceMappingURL=retention-structure.d.ts.map

package/dist/core/retention-structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-structure.d.ts","sourceRoot":"","sources":["../../src/core/retention-structure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,UAAU,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,SAAK,GACb,eAAe,CAWjB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,SAAK,GAAG,MAAM,CAWjE;AAqCD,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,CAAC,EAAE,UAAU,EACb,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAuD/B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAiD7F"}

package/dist/core/retention-structure.js

@@ -0,0 +1,206 @@
+/**
+ * Retention-structure auditor.
+ *
+ * Long-form videos live or die at the 3-min and 6-min marks. Per the
+ * MrBeast manual: every ~3 minutes a "mini-hook" / re-engagement is
+ * required — a twist, a reveal, a visual spectacle, an escalation. Flat
+ * stretches between mini-hooks bleed retention; the YouTube graph
+ * shows the dip almost every time.
+ *
+ * This module:
+ *   1. Builds a 60s window centred on each requested checkpoint.
+ *   2. Bundles all windows + a compact transcript outline into ONE LLM call.
+ *   3. Parses the response into a structured report with per-checkpoint
+ *      scores + an overall escalation pattern score.
+ *
+ * Pure parser + window-builder for unit tests; the network call lives
+ * here too but is exported as `runRetentionAudit` so the wrapper tool
+ * stays thin.
+ */
+import { resolveApiKey } from "./auth/api-keys.js";
+/**
+ * Build a 60s window centred on `atSec`, clamped to [0, totalSec].
+ * Returns the concatenated transcript text inside the window for LLM
+ * context. Pure — exported for testing.
+ */
+export function buildWindow(t, atSec, totalSec, windowSec = 60) {
+    const half = windowSec / 2;
+    const startSec = Math.max(0, atSec - half);
+    const endSec = Math.min(totalSec, atSec + half);
+    const parts = [];
+    for (const seg of t.segments) {
+        if (seg.end <= startSec || seg.start >= endSec)
+            continue;
+        const txt = seg.text.trim();
+        if (txt)
+            parts.push(txt);
+    }
+    return { atSec, startSec, endSec, text: parts.join(" ").trim() };
+}
+/**
+ * Compact transcript outline — every Nth segment trimmed to ~60 chars
+ * with a leading [t]s tag. Keeps the LLM grounded in overall pacing
+ * without blowing the context budget on a long transcript.
+ */
+export function buildOutline(t, maxLines = 40) {
+    const segs = t.segments.filter((s) => s.text.trim().length > 0);
+    if (segs.length === 0)
+        return "";
+    const stride = Math.max(1, Math.floor(segs.length / maxLines));
+    const lines = [];
+    for (let i = 0; i < segs.length; i += stride) {
+        const s = segs[i];
+        const txt = s.text.trim().slice(0, 80);
+        lines.push(`[${s.start.toFixed(1)}s] ${txt}`);
+    }
+    return lines.join("\n");
+}
+const SYSTEM = `You audit long-form videos for retention structure. Per MrBeast's documented manual, every ~3 minutes a "mini-hook" / re-engagement is required: a twist, reveal, escalation, visual spectacle, or stakes shift. Flat stretches without re-engagement bleed retention.
+
+You receive:
+  - The CHECKPOINT WINDOWS (one 60s block of transcript text per requested checkpoint).
+  - An OUTLINE of the whole transcript for global context.
+
+Output a JSON object with these EXACT keys:
+{
+  "checkpoints": [
+    { "atSec": <number>, "score": <0..1>, "summary": "<≤120 char>", "suggestion": "<≤200 char or empty>" }
+    ...one per input checkpoint, in input order...
+  ],
+  "escalationScore": <0..1>,
+  "overallSummary":  "<≤200 char>"
+}
+
+Scoring rubric:
+
+score (per checkpoint):
+  1.0  = clear re-engagement — twist / reveal / shift in stakes / new visual element introduced.
+  0.6  = something shifts but it's understated.
+  0.3  = mostly flat — same energy as the surrounding minutes.
+  0.0  = dead zone — no shift, no escalation, no surprise.
+
+escalationScore (whole video):
+  1.0 = each act bigger than the last (stakes, spectacle, payoff escalate).
+  0.5 = some progression but inconsistent.
+  0.0 = flat from start to finish (no build).
+
+suggestion (only when score < 0.5):
+  Concrete and short, e.g. "Insert a b-roll cutaway here" or "Add a stakes-raising line: 'but then…'" or
+  "Punch in + sound effect on the reveal." Empty string when score ≥ 0.5.
+
+Be honest — flat stretches must score low even when the content is competent. Sparse-but-real beats dense-but-fake.`;
+/**
+ * Run ONE LLM audit pass and return the structured result. Throws on
+ * network / parse error so the wrapper can convert to err().
+ */
+export async function runRetentionAudit(t, opts = {}) {
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for audit_retention_structure.");
+    const model = opts.model ?? "gpt-4o-mini";
+    const totalSec = opts.durationSec ?? t.durationSec;
+    const checkpoints = (opts.checkpoints ?? [180, 360]).filter((c) => c > 0 && c < totalSec);
+    if (checkpoints.length === 0) {
+        return {
+            checkpoints: [],
+            escalationScore: 0,
+            overallSummary: "video too short for any requested checkpoint",
+            weakestCheckpoint: -1,
+        };
+    }
+    const windows = checkpoints.map((c) => buildWindow(t, c, totalSec));
+    const outline = buildOutline(t);
+    const userParts = [];
+    userParts.push(`DURATION: ${totalSec.toFixed(1)}s`);
+    userParts.push(`OUTLINE:\n${outline}`);
+    for (const w of windows) {
+        userParts.push(`CHECKPOINT @${w.atSec}s (window ${w.startSec.toFixed(1)}s\u2013${w.endSec.toFixed(1)}s):\n${w.text || "[no speech in window]"}`);
+    }
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: SYSTEM },
+            { role: "user", content: userParts.join("\n\n") },
+        ],
+        response_format: { type: "json_object" },
+        temperature: 0,
+    };
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`OpenAI HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices[0]?.message?.content;
+    if (!content)
+        throw new Error("audit_retention_structure: empty model response");
+    return parseAuditResponse(content, checkpoints);
+}
+/**
+ * Parse the model's JSON. Robust to missing keys; pads checkpoints to
+ * match the requested order so the caller can correlate by index.
+ *
+ * Pure — exported for testing.
+ */
+export function parseAuditResponse(content, requested) {
+    const start = content.indexOf("{");
+    const end = content.lastIndexOf("}");
+    if (start < 0 || end < start) {
+        throw new Error("audit_retention_structure: no JSON object in response");
+    }
+    const parsed = JSON.parse(content.slice(start, end + 1));
+    const cpRaw = Array.isArray(parsed.checkpoints) ? parsed.checkpoints : [];
+    const byAt = new Map();
+    for (const c of cpRaw) {
+        if (typeof c !== "object" || c === null)
+            continue;
+        const r = c;
+        const atSec = Number(r.atSec);
+        if (!Number.isFinite(atSec))
+            continue;
+        byAt.set(Math.round(atSec), {
+            atSec: Math.round(atSec),
+            score: clamp01(Number(r.score)),
+            summary: String(r.summary ?? "").slice(0, 200),
+            suggestion: String(r.suggestion ?? "").slice(0, 240),
+        });
+    }
+    // Re-order to match the requested checkpoint list. If the LLM dropped
+    // one, fill in a zero-score placeholder so the caller still gets N.
+    const checkpoints = requested.map((at) => {
+        const hit = byAt.get(at);
+        if (hit)
+            return { ...hit, atSec: at };
+        return {
+            atSec: at,
+            score: 0,
+            summary: "no response from model for this checkpoint",
+            suggestion: "",
+        };
+    });
+    const escalationScore = clamp01(Number(parsed.escalationScore));
+    const overallSummary = String(parsed.overallSummary ?? "").slice(0, 240);
+    let weakestCheckpoint = -1;
+    let lowest = Infinity;
+    for (const c of checkpoints) {
+        if (c.score < lowest) {
+            lowest = c.score;
+            weakestCheckpoint = c.atSec;
+        }
+    }
+    return { checkpoints, escalationScore, overallSummary, weakestCheckpoint };
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+}
+//# sourceMappingURL=retention-structure.js.map

package/dist/core/retention-structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-structure.js","sourceRoot":"","sources":["../../src/core/retention-structure.ts"],"names":[],"mappings":"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"}

package/dist/core/retention-structure.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=retention-structure.test.d.ts.map

package/dist/core/retention-structure.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-structure.test.d.ts","sourceRoot":"","sources":["../../src/core/retention-structure.test.ts"],"names":[],"mappings":""}

package/dist/core/retention-structure.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { buildOutline, buildWindow, parseAuditResponse } from "./retention-structure.js";
+const FIXTURE = {
+    language: "en",
+    durationSec: 600,
+    segments: Array.from({ length: 30 }, (_, i) => ({
+        start: i * 20,
+        end: (i + 1) * 20,
+        text: `segment ${i} content here some words`,
+    })),
+};
+describe("buildWindow", () => {
+    it("centres a 60s window on the requested timestamp", () => {
+        const w = buildWindow(FIXTURE, 180, 600);
+        expect(w.atSec).toBe(180);
+        expect(w.startSec).toBe(150);
+        expect(w.endSec).toBe(210);
+        expect(w.text).toContain("segment");
+    });
+    it("clamps to [0, totalSec]", () => {
+        const start = buildWindow(FIXTURE, 10, 600);
+        expect(start.startSec).toBe(0);
+        const end = buildWindow(FIXTURE, 590, 600);
+        expect(end.endSec).toBe(600);
+    });
+    it("returns empty text when no segments fall inside the window", () => {
+        const t = { language: "en", durationSec: 600, segments: [] };
+        const w = buildWindow(t, 180, 600);
+        expect(w.text).toBe("");
+    });
+    it("respects custom windowSec", () => {
+        const w = buildWindow(FIXTURE, 180, 600, 30);
+        expect(w.startSec).toBe(165);
+        expect(w.endSec).toBe(195);
+    });
+});
+describe("buildOutline", () => {
+    it("returns a stride-sampled outline with timestamps", () => {
+        const out = buildOutline(FIXTURE, 10);
+        expect(out.split("\n").length).toBeGreaterThan(0);
+        expect(out.split("\n").length).toBeLessThanOrEqual(15);
+        expect(out).toMatch(/\[\d+\.\d+s\]/);
+    });
+    it("returns empty string when no segments exist", () => {
+        const t = { language: "en", durationSec: 0, segments: [] };
+        expect(buildOutline(t)).toBe("");
+    });
+});
+describe("parseAuditResponse", () => {
+    it("matches checkpoints to the requested order", () => {
+        const content = JSON.stringify({
+            checkpoints: [
+                { atSec: 360, score: 0.9, summary: "twist", suggestion: "" },
+                { atSec: 180, score: 0.4, summary: "flat", suggestion: "add b-roll" },
+            ],
+            escalationScore: 0.7,
+            overallSummary: "ok",
+        });
+        const r = parseAuditResponse(content, [180, 360]);
+        expect(r.checkpoints[0].atSec).toBe(180);
+        expect(r.checkpoints[0].score).toBeCloseTo(0.4);
+        expect(r.checkpoints[1].atSec).toBe(360);
+        expect(r.weakestCheckpoint).toBe(180);
+    });
+    it("fills in placeholders when the model drops a checkpoint", () => {
+        const content = JSON.stringify({
+            checkpoints: [{ atSec: 180, score: 0.5, summary: "ok" }],
+            escalationScore: 0.5,
+            overallSummary: "",
+        });
+        const r = parseAuditResponse(content, [180, 360]);
+        expect(r.checkpoints).toHaveLength(2);
+        expect(r.checkpoints[1].score).toBe(0);
+        expect(r.checkpoints[1].summary).toMatch(/no response/);
+    });
+    it("clamps escalationScore to [0,1]", () => {
+        const content = JSON.stringify({
+            checkpoints: [],
+            escalationScore: 5,
+            overallSummary: "",
+        });
+        expect(parseAuditResponse(content, []).escalationScore).toBe(1);
+    });
+    it("throws on non-JSON content", () => {
+        expect(() => parseAuditResponse("not json", [180])).toThrow();
+    });
+});
+//# sourceMappingURL=retention-structure.test.js.map

package/dist/core/retention-structure.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention-structure.test.js","sourceRoot":"","sources":["../../src/core/retention-structure.test.ts"],"names":[],"mappings":"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"}

package/dist/core/review.d.ts

@@ -1,5 +1,17 @@
+import { type AgentTool } from "@kenkaiiii/gg-agent";
 import type { Usage } from "@kenkaiiii/gg-ai";
 import type { VideoHost } from "./hosts/types.js";
+import { type SkillSource } from "./skills-loader.js";
+/**
+ * Self-critique pass over the timeline + transcripts.
+ *
+ * Runs a fresh Agent with a READ-ONLY subset of editor tools and a critique
+ * prompt. The reviewer inspects the current state against the user's stated
+ * intent and returns a one-paragraph critique + a structured flags array.
+ *
+ * Token cost: a sub-agent over many turns can burn context; we cap at
+ * maxTurns=10 by default.
+ */
 export interface ReviewFlag {
     severity: "ok" | "warn" | "block";
     note: string;
@@ -25,6 +37,11 @@ export interface ReviewResult {
     turns: number;
     usage: Usage;
 }
+/**
+ * Build only the 6 read-only tools needed by the reviewer, without instantiating
+ * the full ~100-tool set. Exported so callers can compose a reviewer independently.
+ */
+export declare function createReadOnlyEditorTools(host: VideoHost, cwd: string, skills?: SkillSource[]): AgentTool[];
 export declare function runReview(opts: ReviewOptions): Promise<ReviewResult>;
 /**
  * Parse the trailing ```json {...} ``` block out of the final assistant message.

package/dist/core/review.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/core/review.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAyBlD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC5E,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE;QACN,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;QACtD,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;CACd;AA6BD,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAmD1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,CA2B1F"}
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/core/review.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAUlD,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtE;;;;;;;;;GASG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAC5E,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE;QACN,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;QACtD,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;CACd;AA6BD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,EAAE,GACrB,SAAS,EAAE,CAWb;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAiD1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,CA2B1F"}

package/dist/core/review.js

@@ -1,25 +1,7 @@
 import { Agent } from "@kenkaiiii/gg-agent";
-import { createEditorTools } from "../tools/index.js";
-/**
- * Self-critique pass over the timeline + transcripts.
- *
- * Runs a fresh Agent with a READ-ONLY subset of editor tools and a critique
- * prompt. The reviewer inspects the current state against the user's stated
- * intent and returns a one-paragraph critique + a structured flags array.
- *
- * Token cost: a sub-agent over many turns can burn context; we cap at
- * maxTurns=10 by default.
- */
-/** Tools the reviewer is allowed to call. Strictly read-only. */
-const READ_ONLY_TOOL_NAMES = new Set([
-    "host_info",
-    "get_timeline",
-    "get_markers",
-    "read_transcript",
-    "score_shot",
-    "probe_media",
-    "read_skill",
-]);
+import { createGetMarkersTool, createGetTimelineTool, createHostInfoTool, createProbeMediaTool, createReadSkillTool, createReadTranscriptTool, createScoreShotTool, } from "../tools/index.js";
+import { discoverSkills } from "./skills-loader.js";
+import { SKILLS } from "../skills.js";
 const REVIEW_SYSTEM = `You are the GG Editor REVIEWER — a read-only critic of an edit-in-progress.
 
 Your job: read the timeline + relevant transcripts/media, measure them against the stated INTENT, and write a tight critique.
@@ -46,11 +28,25 @@ severity:
 - block: ship-stopper (wrong take kept, missing captions on long-form, hook missing)
 
 Be direct. Don't praise the work just to be nice. If it's good, say "ok". If it's not, say what's wrong.`;
+/**
+ * Build only the 6 read-only tools needed by the reviewer, without instantiating
+ * the full ~100-tool set. Exported so callers can compose a reviewer independently.
+ */
+export function createReadOnlyEditorTools(host, cwd, skills) {
+    const resolvedSkills = skills ?? discoverSkills({ cwd, bundled: Object.values(SKILLS) });
+    return [
+        createHostInfoTool(host),
+        createGetTimelineTool(host),
+        createGetMarkersTool(host),
+        createReadTranscriptTool(cwd),
+        createScoreShotTool(cwd),
+        createProbeMediaTool(cwd),
+        createReadSkillTool(resolvedSkills),
+    ];
+}
 export async function runReview(opts) {
     const { intent, focus, host, cwd, config, signal } = opts;
-    // Build the read-only tool subset by name-allowlist filter.
-    const allTools = createEditorTools({ host, cwd });
-    const tools = allTools.filter((t) => READ_ONLY_TOOL_NAMES.has(t.name));
+    const tools = createReadOnlyEditorTools(host, cwd);
     const userPrompt = [
         `INTENT: ${intent}`,
         focus && focus.length > 0 ? `FOCUS: ${focus.join(", ")}` : null,