@lingjingai/scriptctl 0.12.2 → 0.13.1

package/dist/usecases/direct.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { CliError, DEFAULT_BATCH_MAX_CHARS, DEFAULT_BATCH_MIN_LINES, DEFAULT_BATCH_MODE, DEFAULT_BATCH_TARGET_LINES, DEFAULT_CONCURRENCY, DEFAULT_MODEL, DEFAULT_PROVIDER, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, REVIEW_TARGETS, SUPPORTED_EXTS, deletePath, directDir, exists, fmtId, readJson, readText, writeJson, } from "../common.js";
-import { compactBatchResult, compactEpisodeResult, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResults, normalizeEpisodeResult, normalizeInt, uniqueAdd, validateEpisodeExtractionQuality, _md_push_asset, curateScriptAssets, applyMetadataToScript, } from "../domain/direct-core.js";
+import { CliError, DEFAULT_BATCH_MAX_CHARS, DEFAULT_BATCH_MIN_LINES, DEFAULT_BATCH_MODE, DEFAULT_BATCH_TARGET_LINES, DEFAULT_CONCURRENCY, DEFAULT_MODEL, DEFAULT_PROVIDER, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, SUPPORTED_EXTS, deletePath, directDir, exists, fmtId, readJson, readText, writeJson, } from "../common.js";
+import { compactBatchResult, compactEpisodeResult, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResults, normalizeEpisodeResult, uniqueAdd, validateEpisodeExtractionQuality, _md_push_asset, curateScriptAssets, applyMetadataToScript, } from "../domain/direct-core.js";
 import { validateScript } from "../domain/script-core.js";
 import { makeProvider } from "../infra/providers.js";
 import { makeSourceManifest, prepareSource, } from "../infra/converters.js";
@@ -60,69 +60,6 @@ export function readRunState(workspace) {
         return {};
     }
 }
-export function addInspectedTarget(workspace, target) {
-    const state = readRunState(workspace);
-    const targets = [];
-    for (const item of asList(state["inspected_targets"])) {
-        const s = strOf(item);
-        if (s)
-            targets.push(s);
-    }
-    if (!targets.includes(target))
-        targets.push(target);
-    const missing = [];
-    for (const t of REVIEW_TARGETS) {
-        if (!targets.includes(t))
-            missing.push(t);
-    }
-    const reviewStatus = missing.length === 0 ? "reviewed" : "in_progress";
-    return updateRunState(workspace, {
-        inspected_targets: targets,
-        review_status: reviewStatus,
-        review_missing: missing,
-        last_inspect_target: target,
-    });
-}
-export function markPatched(workspace, count) {
-    const state = readRunState(workspace);
-    const patchCount = Number(state["patch_count"] ?? 0) + count;
-    return updateRunState(workspace, {
-        patch_count: patchCount,
-        review_status: "patched",
-        review_missing: [],
-    });
-}
-export function markMetadataConfidenceReviewed(workspace, operations) {
-    const metadataOps = new Set(["meta.worldview.set", "asset.role.set", "asset.describe"]);
-    if (!operations.some((op) => isDict(op) && metadataOps.has(strOf(op["op"]))))
-        return;
-    const p = path.join(directDir(workspace), "asset_metadata.json");
-    if (!exists(p))
-        return;
-    let metadata;
-    try {
-        metadata = readJson(p);
-    }
-    catch {
-        return;
-    }
-    if (!isDict(metadata) || metadata["confidence"] !== "low")
-        return;
-    metadata["confidence"] = "medium";
-    metadata["confidence_reviewed_at"] = checkpointTimestamp();
-    writeJson(p, metadata);
-}
-export function reviewBlockers(state) {
-    if (Number(state["patch_count"] ?? 0) > 0)
-        return [];
-    const inspected = new Set();
-    for (const item of asList(state["inspected_targets"])) {
-        const s = strOf(item);
-        if (s)
-            inspected.add(s);
-    }
-    return REVIEW_TARGETS.filter((t) => !inspected.has(t));
-}
 // ---------------------------------------------------------------------------
 // Paths for episode/batch results
 // ---------------------------------------------------------------------------
@@ -324,7 +261,7 @@ async function providerExtractAssetCurationLocal(provider, sourceText, script) {
 // Record a batch failure: write `<key>.error.json` (which marks the batch as
 // "tried and failed" → sticky on plain resume) and drop any stale result file.
 // The error_code (e.g. PROVIDER_CONTENT_FILTERED) is surfaced so the agent can
-// see WHY in `direct status` / `direct inspect` and decide whether to re-run.
+// see WHY in `direct status` / `direct review` and decide whether to re-run.
 //
 // Deliberate content-filter policy split: batch extraction is HARD (sticky
 // error, episode blocked until an explicit re-run) because batch content is the
@@ -941,10 +878,6 @@ export async function commandInit(opts) {
         batch_reused: reusedBatchCount,
         batch_failed: erroredBatches,
         last_error: null,
-        review_status: "pending",
-        review_missing: [...REVIEW_TARGETS],
-        inspected_targets: [],
-        patch_count: 0,
     });
     const title = passed
         ? "INIT COMPLETE: Initial script ready"
@@ -961,7 +894,6 @@ export async function commandInit(opts) {
             `episodes: ${results.length}/${totalEpisodes} complete`,
             `batches: ${doneBatches}/${totalBatches} done (reused ${reusedBatchCount})`,
             ...(titleDegraded.length > 0 ? [`titles degraded (deterministic): ${titleDegraded.join(", ")}`] : []),
-            "agent_review: pending",
         ],
         artifacts: [
             path.join(workspace, "source.txt"),
@@ -979,10 +911,10 @@ export async function commandInit(opts) {
         issues: summarizeIssues(asList(validation["issues"])),
         next: providerName === "mock"
             ? [
-                "Run inspect for issue, episode, and asset; apply patches if needed; then validate/export.",
+                "Run `direct review` (add --episode <n> for source↔extract); edit with --draft if needed; then validate/export.",
                 "Do not export mock-provider results for delivery.",
             ]
-            : ["Run inspect for issue, episode, and asset; apply patches if needed; then validate/export."],
+            : ["Run `direct review` (add --episode <n> for source↔extract); edit with --draft if needed; then validate/export."],
     };
     return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
@@ -1304,173 +1236,81 @@ function renderAssetCurationSummary(curation) {
     }
     return lines;
 }
-export function commandInspect(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const target = strOf(opts["target"]);
-    const itemId = opts["id"] ? strOf(opts["id"]) : null;
-    const dd = directDir(workspace);
-    const scriptPath = path.join(dd, "script.initial.json");
-    const validationPath = path.join(dd, "validation.json");
-    if (!exists(scriptPath) && target === "asset") {
-        throw new CliError("INSPECT BLOCKED: script.initial.json not found", "script.initial.json not found.", {
-            exitCode: EXIT_INPUT,
-            required: ["workspace/draft/scriptctl/direct/script.initial.json"],
-            received: [scriptPath],
-            nextSteps: ["Run scriptctl direct init first."],
-        });
-    }
-    const script = exists(scriptPath)
-        ? readJson(scriptPath)
-        : { episodes: [], actors: [], locations: [], props: [] };
-    let validation = exists(validationPath) ? readJson(validationPath) : { issues: [] };
-    if (target === "issue" && exists(scriptPath)) {
-        validation = validateScript(workspace, scriptPath, { requireSource: false });
-    }
-    const batchPlanPath = path.join(dd, "batch_plan.json");
-    const batchPlan = exists(batchPlanPath) ? readJson(batchPlanPath) : { batches: [] };
-    const batchCounts = new Map();
-    for (const batch of asList(batchPlan["batches"])) {
-        if (!isDict(batch))
-            continue;
-        const ep = Number(batch["episode"] ?? 0);
-        batchCounts.set(ep, (batchCounts.get(ep) ?? 0) + 1);
-    }
-    const failedByEpisode = new Map();
-    const batchResultsDir = path.join(dd, "batch_results");
-    if (exists(batchResultsDir)) {
-        const files = fs.readdirSync(batchResultsDir).filter((n) => n.endsWith(".error.json")).sort();
-        for (const name of files) {
-            const errorFile = path.join(batchResultsDir, name);
-            try {
-                const error = readJson(errorFile);
-                const episodeNum = Number(error["episode"] ?? 0);
-                if (!failedByEpisode.has(episodeNum))
-                    failedByEpisode.set(episodeNum, []);
-                failedByEpisode.get(episodeNum).push(strOf(error["batch_id"]) || name.replace(/\.error\.json$/, ""));
-            }
-            catch {
-                // ignore
-            }
-        }
-    }
-    const lines = [];
-    if (target === "episode") {
-        if (exists(scriptPath)) {
-            for (const ep of asList(script["episodes"])) {
-                if (itemId && itemId !== strOf(ep["episode_id"]))
-                    continue;
-                const scenes = asList(ep["scenes"]);
-                const sceneCount = scenes.length;
-                let actionCount = 0;
-                for (const scene of scenes)
-                    actionCount += asList(scene["actions"]).length;
-                const rawNum = normalizeInt(strOf(ep["episode_id"]), lines.length + 1);
-                const failed = (failedByEpisode.get(rawNum) ?? []).join(",") || "-";
-                lines.push(`${ep["episode_id"]}: scenes=${sceneCount}, actions=${actionCount}, batches=${batchCounts.get(rawNum) ?? 0}, failed_batches=${failed}, title=${ep["title"] || "-"}`);
-            }
+// Collect batch extraction failures (batch_results/<key>.error.json) keyed by
+// episode. Shared by both review views — these are direct-stage failures the
+// final-script `issues` query can't see.
+function collectBatchFailures(batchResultsDir) {
+    const byEpisode = new Map();
+    if (!exists(batchResultsDir))
+        return byEpisode;
+    const files = fs.readdirSync(batchResultsDir).filter((n) => n.endsWith(".error.json")).sort();
+    for (const name of files) {
+        try {
+            const error = readJson(path.join(batchResultsDir, name));
+            const episodeNum = Number(error["episode"] ?? 0);
+            if (!byEpisode.has(episodeNum))
+                byEpisode.set(episodeNum, []);
+            byEpisode.get(episodeNum).push(error);
         }
-        else {
-            const planPath = path.join(dd, "episode_plan.json");
-            const plan = exists(planPath) ? readJson(planPath) : { episodes: [] };
-            for (const ep of asList(plan["episodes"])) {
-                const epId = fmtId("ep", Number(ep["episode"] ?? 0));
-                if (itemId && itemId !== epId && itemId !== strOf(ep["episode"]))
-                    continue;
-                const episodeNum = Number(ep["episode"] ?? 0);
-                const failed = (failedByEpisode.get(episodeNum) ?? []).join(",") || "-";
-                lines.push(`${epId}: batches=${batchCounts.get(episodeNum) ?? 0}, failed_batches=${failed}, title=${ep["title"] || "-"}`);
-            }
+        catch {
+            // ignore unreadable error file
         }
     }
-    else if (target === "asset") {
-        const curationPath = path.join(dd, "asset_curation.json");
-        if (!itemId && exists(curationPath)) {
-            const curation = readJson(curationPath);
-            if (isDict(curation))
-                lines.push(...renderAssetCurationSummary(curation));
-        }
-        for (const [key, idKey, nameKey] of [["actors", "actor_id", "actor_name"], ["locations", "location_id", "location_name"], ["props", "prop_id", "prop_name"]]) {
-            for (const asset of asList(script[key])) {
-                if (itemId && itemId !== strOf(asset[idKey]) && itemId !== strOf(asset[nameKey]))
-                    continue;
-                const aliases = asList(asset["aliases"]).length;
-                const states = asList(asset["states"]).length;
-                const role = key === "actors" ? `, role_type=${asset["role_type"]}` : "";
-                const description = strOf(asset["description"]).trim() ? "yes" : "missing";
-                const singular = key.slice(0, -1);
-                lines.push(`${singular} ${asset[idKey]}: ${asset[nameKey]} aliases=${aliases}, states=${states}${role}, description=${description}`);
-            }
-        }
+    return byEpisode;
+}
+function parseEpisodeArg(episodeArg) {
+    try {
+        return episodeArg.split(",").map((s) => s.trim()).filter((s) => s).map((s) => {
+            const n = parseInt(s, 10);
+            if (Number.isNaN(n))
+                throw new Error("nan");
+            return n;
+        });
     }
-    else if (target === "issue") {
-        for (const errors of failedByEpisode.values()) {
-            for (const batchId of errors) {
-                const errorPath = path.join(batchResultsDir, `${batchId}.error.json`);
-                if (!exists(errorPath))
-                    continue;
-                let error;
-                try {
-                    error = readJson(errorPath);
-                }
-                catch {
-                    continue;
-                }
-                if (itemId && itemId !== strOf(error["batch_id"]) && itemId !== strOf(error["episode"]) && itemId !== strOf(error["error_type"]))
-                    continue;
-                lines.push(`error BATCH_FAILED: ${error["batch_id"]} episode ${error["episode"]} part ${error["part"]} - ${error["message"]}`);
-            }
-        }
-        for (const issue of asList(validation["issues"])) {
-            if (itemId && itemId !== strOf(issue["code"]) && itemId !== strOf(issue["severity"]))
-                continue;
-            const whereParts = [];
-            for (const k of ["episode", "scene", "action_index"]) {
-                if (issue[k] !== null && issue[k] !== undefined)
-                    whereParts.push(strOf(issue[k]));
-            }
-            const where = whereParts.join(" ");
-            lines.push(`${issue["severity"]} ${issue["code"]}: ${issue["summary"]}${where ? ` [${where}]` : ""}`);
-        }
+    catch {
+        throw new CliError("REVIEW BLOCKED: --episode must be integers", "--episode must be integers.", {
+            exitCode: EXIT_USAGE,
+            required: ["--episode <n>[,<n>...]"],
+            received: [`--episode ${episodeArg}`],
+            nextSteps: ["Pass episode numbers like --episode 1,15,30."],
+        });
     }
-    else if (target === "review") {
-        const episodeArg = strOf(opts["episode"]).trim();
-        if (!episodeArg) {
-            throw new CliError("INSPECT BLOCKED: --episode required for review", "--episode required for review.", {
-                exitCode: EXIT_USAGE,
-                required: ["--episode <n>[,<n>...]"],
-                received: ["--episode not provided"],
-                nextSteps: ["Pass --episode 1 (single) or --episode 1,15,30 (multiple)."],
-            });
-        }
-        let episodeFilters;
-        try {
-            episodeFilters = episodeArg.split(",").map((s) => s.trim()).filter((s) => s).map((s) => {
-                const n = parseInt(s, 10);
-                if (Number.isNaN(n))
-                    throw new Error("nan");
-                return n;
-            });
-        }
-        catch {
-            throw new CliError("INSPECT BLOCKED: --episode must be integers", "--episode must be integers.", {
-                exitCode: EXIT_USAGE,
-                required: ["--episode <n>[,<n>...]"],
-                received: [`--episode ${episodeArg}`],
-                nextSteps: ["Pass episode numbers like --episode 1,15,30."],
-            });
-        }
+}
+// ---------------------------------------------------------------------------
+// command_review — the direct-stage proofreading view. Read-only; no run_state
+// side effects. Two shapes:
+//   * `direct review`              workspace diagnostics: curation decisions +
+//                                  issues (validation + batch extraction errors)
+//   * `direct review --episode N`  per-episode source.txt ↔ script.initial.json
+//                                  side-by-side alignment (renderReviewEpisode)
+// Generic per-episode / per-asset listings live on the top-level `episodes` /
+// `assets` queries (use `--draft` to point them at script.initial.json).
+// ---------------------------------------------------------------------------
+export function commandReview(opts) {
+    const workspace = strOf(opts["workspace_path"] || "workspace");
+    const dd = directDir(workspace);
+    const scriptPath = path.join(dd, "script.initial.json");
+    const batchResultsDir = path.join(dd, "batch_results");
+    const episodeArg = strOf(opts["episode"]).trim();
+    // --episode: source ↔ extract alignment for the named episodes.
+    if (episodeArg) {
+        const episodeFilters = parseEpisodeArg(episodeArg);
         const sourcePath = path.join(workspace, "source.txt");
         if (!exists(sourcePath)) {
-            throw new CliError("INSPECT BLOCKED: source.txt not found", "source.txt not found.", {
+            throw new CliError("REVIEW BLOCKED: source.txt not found", "source.txt not found.", {
                 exitCode: EXIT_INPUT,
                 required: [sourcePath],
                 received: ["source.txt missing"],
                 nextSteps: ["Run scriptctl direct init first."],
             });
         }
+        const script = exists(scriptPath)
+            ? readJson(scriptPath)
+            : { episodes: [], actors: [], locations: [], props: [] };
         const sourceText = readText(sourcePath);
         const episodePlanPath = path.join(dd, "episode_plan.json");
         const episodePlan = exists(episodePlanPath) ? readJson(episodePlanPath) : { episodes: [] };
+        const lines = [];
         for (let idx = 0; idx < episodeFilters.length; idx++) {
             if (idx > 0) {
                 lines.push("");
@@ -1478,23 +1318,50 @@ export function commandInspect(opts) {
             }
             lines.push(...renderReviewEpisode(sourceText, episodePlan, script, episodeFilters[idx]));
         }
+        const report = {
+            title: `DIRECT REVIEW: episode ${episodeFilters.join(",")}`,
+            result: lines.length > 0 ? lines : ["No matching items."],
+            artifacts: [path.join(workspace, "source.txt"), path.join(dd, "episode_plan.json"), scriptPath],
+            next: ["Edit with `--draft` (e.g. `scriptctl replace … --draft`) if the extraction is wrong, then validate/export."],
+        };
+        return [report, EXIT_OK];
     }
-    else {
-        throw new CliError("INSPECT BLOCKED: Invalid target", "Invalid inspect target.", {
-            exitCode: EXIT_USAGE,
-            required: ["--target: episode, asset, issue, or review"],
-            received: [`--target: ${target}`],
-            nextSteps: ["Use one of the supported inspect targets."],
-        });
+    // No --episode: workspace-level diagnostics. Curation decisions + every issue
+    // (validation issues recomputed live, plus batch extraction failures).
+    const lines = [];
+    const curationPath = path.join(dd, "asset_curation.json");
+    if (exists(curationPath)) {
+        const curation = readJson(curationPath);
+        if (isDict(curation))
+            lines.push(...renderAssetCurationSummary(curation));
+    }
+    const batchFailures = collectBatchFailures(batchResultsDir);
+    for (const errors of batchFailures.values()) {
+        for (const error of errors) {
+            lines.push(`error BATCH_FAILED: ${error["batch_id"]} episode ${error["episode"]} part ${error["part"]} - ${error["message"]}`);
+        }
+    }
+    // persist:false keeps review read-only — it must not overwrite validation.json
+    // (the help/comment promise "no state side effects").
+    const validation = exists(scriptPath)
+        ? validateScript(workspace, scriptPath, { requireSource: false, persist: false })
+        : { issues: [] };
+    for (const issue of asList(validation["issues"])) {
+        const whereParts = [];
+        for (const k of ["episode", "scene", "action_index"]) {
+            if (issue[k] !== null && issue[k] !== undefined)
+                whereParts.push(strOf(issue[k]));
+        }
+        const where = whereParts.join(" ");
+        lines.push(`${issue["severity"]} ${issue["code"]}: ${issue["summary"]}${where ? ` [${where}]` : ""}`);
     }
-    const state = addInspectedTarget(workspace, target);
-    const missingReview = reviewBlockers(state);
     const report = {
-        title: `INSPECT: ${target}`,
-        result: lines.length > 0 ? lines : ["No matching items."],
+        title: "DIRECT REVIEW",
+        result: lines.length > 0 ? lines : ["No issues, curation decisions, or batch failures to review."],
+        artifacts: [scriptPath, path.join(dd, "asset_curation.json"), batchResultsDir],
         next: [
-            "Use inspect details to prepare a structured patch, or continue required review.",
-            missingReview.length === 0 ? "Review complete; run validate/export." : `Still inspect: ${missingReview.join(", ")}.`,
+            "Run `direct review --episode <n>` for source↔extract alignment.",
+            "Edit with `--draft` (e.g. `scriptctl rename … --draft`), then validate/export.",
         ],
     };
     return [report, EXIT_OK];