@lingjingai/scriptctl 0.20.0 → 0.22.0

package/dist/usecases/script/lib.js

@@ -0,0 +1,849 @@
+import * as path from "node:path";
+import { CliError, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_USAGE, directDir, } from "../../common.js";
+import { applyPatchOperations } from "../../domain/script/patch/apply.js";
+import { renumberSceneIds } from "../../domain/script/lookups.js";
+import { isDangerousRegex, MAX_GREP_PATTERN_LEN, parseInSelector, selectorSingleActionPoint, WHOLE_SCRIPT, } from "../../domain/script/selector.js";
+import { parseAnyAddress, } from "../../domain/script/address.js";
+import { summarizeIssues, } from "../direct.js";
+import { sortDeep } from "../../domain/direct-core.js";
+import { asList, isDict, strOf, } from "../../domain/script/shared.js";
+import { loadScriptForEdit, validateSession, saveScriptSession, syncValidationResult, scriptSourceText, } from "./session.js";
+export function tokenizeLine(line) {
+    const out = [];
+    let cur = "";
+    let started = false;
+    let quoted = false;
+    let inSingle = false;
+    let inDouble = false;
+    const flush = () => { if (started) {
+        out.push({ text: cur, quoted });
+        cur = "";
+        started = false;
+        quoted = false;
+    } };
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inSingle) {
+            if (ch === "'")
+                inSingle = false;
+            else {
+                cur += ch;
+                quoted = true;
+            }
+        }
+        else if (inDouble) {
+            if (ch === '"')
+                inDouble = false;
+            else if (ch === "\\" && i + 1 < line.length) {
+                cur += line[++i];
+                quoted = true;
+            }
+            else {
+                cur += ch;
+                quoted = true;
+            }
+        }
+        else if (ch === "'") {
+            inSingle = true;
+            started = true;
+        }
+        else if (ch === '"') {
+            inDouble = true;
+            started = true;
+        }
+        else if (ch === "\\" && i + 1 < line.length) {
+            cur += line[++i];
+            started = true;
+            quoted = true;
+        }
+        else if (ch === " " || ch === "\t" || ch === "\r") {
+            flush();
+        }
+        else {
+            cur += ch;
+            started = true;
+        }
+    }
+    flush();
+    return out;
+}
+// A token is a flag only if it was unquoted AND starts with `--`.
+function isDoFlag(t) {
+    return !t.quoted && t.text.startsWith("--");
+}
+// Per-verb flag arity. Everything else takes the next token as its value.
+export const DO_BOOL_FLAGS = {
+    replace: new Set(["all", "regex"]),
+    "state-change": new Set(["clear"]),
+    transition: new Set(["clear"]),
+    context: new Set(["clear", "remove"]),
+    delete: new Set(["force"]),
+};
+export const DO_REPEAT_FLAGS = {
+    alias: new Set(["add", "remove"]),
+    overlap: new Set(["line"]),
+    "add-actor": new Set(["alias"]),
+};
+function pushFlag(flags, repeats, name, val) {
+    if (repeats.has(name)) {
+        const arr = flags[name] ?? [];
+        arr.push(val);
+        flags[name] = arr;
+    }
+    else {
+        flags[name] = val;
+    }
+}
+export function parseDoLine(tokens) {
+    if (tokens.length === 0 || isDoFlag(tokens[0])) {
+        throw doErr("a line must start with a verb (not a flag)");
+    }
+    const verb = tokens[0].text;
+    const bools = DO_BOOL_FLAGS[verb] ?? new Set();
+    const repeats = DO_REPEAT_FLAGS[verb] ?? new Set();
+    const args = [];
+    const flags = {};
+    for (let i = 1; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (isDoFlag(t)) {
+            let name = t.text.slice(2);
+            // Support `--flag=value` (a common CLI habit) alongside `--flag value`.
+            const eq = name.indexOf("=");
+            if (eq >= 0) {
+                const inlineVal = name.slice(eq + 1);
+                name = name.slice(0, eq);
+                if (!name)
+                    throw doErr(`empty flag name in "${t.text}"`);
+                // A boolean flag written as `--all=false` must become false, not the
+                // truthy string "false" — `--force=false` especially must NOT force.
+                if (bools.has(name)) {
+                    flags[name] = !["false", "0", "no", "off"].includes(inlineVal.toLowerCase());
+                }
+                else {
+                    pushFlag(flags, repeats, name, inlineVal);
+                }
+                continue;
+            }
+            if (!name)
+                throw doErr(`empty flag name "${t.text}"`);
+            if (bools.has(name)) {
+                flags[name] = true;
+                continue;
+            }
+            // A value-taking flag must be followed by an actual value, not another
+            // unquoted `--flag` (or end-of-line) — otherwise `--to --from x` silently
+            // binds '--from' as --to's value. A quoted `"--x"` IS a valid value.
+            const next = tokens[i + 1];
+            if (next === undefined || isDoFlag(next)) {
+                throw doErr(`--${name} needs a value`);
+            }
+            pushFlag(flags, repeats, name, tokens[++i].text);
+        }
+        else {
+            args.push(t.text);
+        }
+    }
+    return { verb, args, flags };
+}
+export function doErr(detail) {
+    return new CliError("DO BLOCKED: line invalid", detail, {
+        exitCode: EXIT_USAGE,
+        required: ["a valid <verb> ...args... line"],
+        received: [detail],
+        nextSteps: ["Each line is a scriptctl verb minus the leading `scriptctl`; see `scriptctl do --help`."],
+        errorCode: "DO_LINE_INVALID",
+    });
+}
+// ---- shared op-template builders ------------------------------------------
+// One source of truth for the verbs whose op has validation/defaults, so the
+// typed CLI handler and `do`'s lineToOp can never drift. Each returns the op
+// WITHOUT `at` (the caller adds the single address or sweeps it over a selector)
+// and throws the SAME CliError the handler used to throw inline.
+export function stateChangeTemplate(target, f) {
+    const toSet = f.to !== undefined;
+    const clearSet = Boolean(f.clear);
+    if (toSet && clearSet) {
+        throw new CliError("VERB BLOCKED: state-change flags mutually exclusive", "state-change: --to and --clear are mutually exclusive.", {
+            exitCode: EXIT_USAGE, required: ["exactly one of --to <state> / --clear"], received: ["--to", "--clear"],
+            nextSteps: ["Pick one and retry."], errorCode: "STATE_CHANGE_FLAG_CONFLICT",
+        });
+    }
+    if (!toSet && !clearSet) {
+        throw new CliError("VERB BLOCKED: state-change flag missing", "state-change: must specify --to <state> or --clear.", {
+            exitCode: EXIT_USAGE, required: ["one of --to <state> / --clear"], received: ["<missing>"],
+            nextSteps: ["Pick exactly one flag."], errorCode: "STATE_CHANGE_FLAG_MISSING",
+        });
+    }
+    return clearSet
+        ? { op: "action.state.remove", target }
+        : { op: "action.state.change", target, to: f.to, from: f.from, effective: f.effective || "after" };
+}
+export function transitionTemplate(target, f) {
+    const setBoth = f.process !== undefined || f.contrast !== undefined;
+    const clearSet = Boolean(f.clear);
+    if (setBoth && clearSet) {
+        throw new CliError("VERB BLOCKED: transition flags mutually exclusive", "transition: --clear is mutually exclusive with --process/--contrast.", {
+            exitCode: EXIT_USAGE, required: ["either --clear, or --process + --contrast"], received: ["--clear", "--process/--contrast"],
+            nextSteps: ["Pick one mode and retry."], errorCode: "TRANSITION_FLAG_CONFLICT",
+        });
+    }
+    if (!setBoth && !clearSet) {
+        throw new CliError("VERB BLOCKED: transition flag missing", "transition: must specify --process/--contrast or --clear.", {
+            exitCode: EXIT_USAGE, required: ["--process + --contrast, or --clear"], received: ["<missing>"],
+            nextSteps: ["Pick exactly one mode."], errorCode: "TRANSITION_FLAG_MISSING",
+        });
+    }
+    return clearSet
+        ? { op: "action.transition.clear", target }
+        : { op: "action.transition.set", target, process: f.process, contrast: f.contrast };
+}
+export function contextTemplate(target, f) {
+    const stateSet = f.state !== undefined;
+    const clearSet = Boolean(f.clear);
+    const removeSet = Boolean(f.remove);
+    const n = (stateSet ? 1 : 0) + (clearSet ? 1 : 0) + (removeSet ? 1 : 0);
+    if (n === 0) {
+        throw new CliError("VERB BLOCKED: context flag missing", "context: must specify --state X, --clear, or --remove.", {
+            exitCode: EXIT_USAGE, required: ["one of --state <state_id> / --clear / --remove"], received: ["<missing>"],
+            nextSteps: ["Pick exactly one flag."], errorCode: "CONTEXT_FLAG_MISSING",
+        });
+    }
+    if (n > 1) {
+        const passed = [];
+        if (stateSet)
+            passed.push("--state");
+        if (clearSet)
+            passed.push("--clear");
+        if (removeSet)
+            passed.push("--remove");
+        throw new CliError("VERB BLOCKED: context flags mutually exclusive", "context: --state / --clear / --remove are mutually exclusive.", {
+            exitCode: EXIT_USAGE, required: ["exactly one of --state / --clear / --remove"], received: passed,
+            nextSteps: ["Pick one and retry."], errorCode: "CONTEXT_FLAG_CONFLICT",
+        });
+    }
+    if (removeSet)
+        return { op: "context.ref.remove", target };
+    if (clearSet)
+        return { op: "context.clear", target };
+    return { op: "context.set", target, state: f.state === "none" ? "" : f.state };
+}
+export function dialogueTemplate(speakers, f) {
+    return { op: "dialogue.speakers", speakers, delivery: strOf(f.delivery).trim() || (speakers.length > 1 ? "simultaneous" : "single") };
+}
+// Translate one parsed verb line into a patch op dict (the SAME ops `patch`
+// consumes). `do` = the human/agent-friendly notation for those ops: no JSON,
+// no field-name guessing — the verbs you already type. Multipolar verbs
+// (delete/move/insert/merge/describe) pick their op by the address kind.
+export function lineToOp(verb, args, flags) {
+    const a0 = strOf(args[0]);
+    const a1 = strOf(args[1]);
+    switch (verb) {
+        case "replace":
+            return flags["regex"]
+                ? { op: "action.content.regex-replace", at: a0, pattern: regexPattern(strOf(flags["from"])), to: flags["to"] ?? "", all: Boolean(flags["all"]) }
+                : { op: "action.content.replace", at: a0, from: strOf(flags["from"]), to: flags["to"] ?? "", all: Boolean(flags["all"]) };
+        case "type":
+            return { op: "action.type.set", at: a0, type: a1 };
+        case "actor":
+            return { op: "action.actor.set", at: a0, actor_id: a1 };
+        case "state-change":
+            return { ...stateChangeTemplate(a1, { to: flags["to"], from: flags["from"], effective: flags["effective"], clear: Boolean(flags["clear"]) }), at: a0 };
+        case "transition":
+            return { ...transitionTemplate(a1, { process: flags["process"], contrast: flags["contrast"], clear: Boolean(flags["clear"]) }), at: a0 };
+        case "context":
+            return { ...contextTemplate(a1, { state: flags["state"], clear: Boolean(flags["clear"]), remove: Boolean(flags["remove"]) }), at: a0 };
+        case "dialogue":
+            return { ...dialogueTemplate(splitSpeakerList(flags["speakers"]), { delivery: flags["delivery"] }), at: a0 };
+        case "overlap":
+            return { op: "dialogue.overlap", at: a0, lines: flags["line"] ?? [] };
+        case "rename":
+            return { op: "asset.rename", target: a0, name: a1 };
+        case "role":
+            return { op: "asset.role.set", target: a0, role_type: a1 };
+        case "worldview":
+            return { op: "meta.worldview.set", worldview: a0 };
+        case "alias": {
+            const add = flags["add"] ?? [];
+            const remove = flags["remove"] ?? [];
+            if (add.length)
+                return { op: "asset.alias.add", target: a0, alias: add };
+            if (remove.length)
+                return { op: "asset.alias.remove", target: a0, alias: remove };
+            throw doErr("alias needs --add <alias> or --remove <alias>");
+        }
+        case "describe": {
+            const addr = parseAnyAddress(a0);
+            if (addr.kind === "state")
+                return { op: "state.describe", target: a0, description: a1 };
+            if (addr.kind === "asset")
+                return { op: "asset.describe", target: a0, description: a1 };
+            throw doErr(`describe cannot operate on a ${addr.kind} address (${a0}); use an asset or asset/state target`);
+        }
+        case "state-add":
+            return { op: "state.add", target: a0, name: a1, description: flags["description"], state_id: flags["state-id"] };
+        case "state-rename":
+            return { op: "state.rename", target: a0, name: a1 };
+        case "state-delete":
+            return { op: "state.delete", target: a0, strategy: flags["strategy"], replacement: flags["replacement"] };
+        case "add-actor":
+            return { op: "actor.add", name: a0, role_type: flags["role"], description: flags["description"], aliases: flags["alias"] ?? undefined };
+        case "add-location":
+            return { op: "location.add", name: a0, description: flags["description"] };
+        case "add-prop":
+            return { op: "prop.add", name: a0, description: flags["description"] };
+        case "add-episode":
+            return { op: "episode.add", title: flags["title"], episode_id: flags["id"] };
+        case "add-speaker":
+            return { op: "speaker.add", kind: flags["kind"], name: flags["name"], source_id: flags["source-id"], voice_desc: flags["voice-desc"], speaker_id: flags["speaker-id"] };
+        case "split":
+            return { op: "scene.split", at: a0, at_index: flags["at"], new_scene_id: flags["new-scene-id"] };
+        case "delete": {
+            const addr = parseAnyAddress(a0);
+            if (addr.kind === "action")
+                return { op: "action.delete", at: a0 };
+            if (addr.kind === "scene")
+                return { op: "scene.delete", at: a0, force: Boolean(flags["force"]) };
+            if (addr.kind === "speaker")
+                return { op: "speaker.delete", target: a0, strategy: flags["strategy"], replacement: flags["replacement"] };
+            if (addr.kind === "asset")
+                return { op: "asset.delete", target: a0, strategy: flags["strategy"], replacement: flags["replacement"] };
+            throw doErr(`delete cannot operate on a ${addr.kind} address (${a0}); episodes/states have no delete op`);
+        }
+        case "move": {
+            const addr = parseAnyAddress(a0);
+            if (addr.kind === "scene")
+                return { op: "scene.move", at: a0, to: a1, at_index: flags["at"] };
+            if (addr.kind === "action")
+                return { op: "action.move", at: a0, to: a1 };
+            throw doErr(`move cannot operate on a ${addr.kind} address (${a0}); move an action or a scene`);
+        }
+        case "merge": {
+            const addr = parseAnyAddress(a0);
+            if (addr.kind === "scene")
+                return { op: "scene.merge", from: a0, into: strOf(flags["into"]) };
+            if (addr.kind === "asset")
+                return { op: "asset.merge", from: a0, into: strOf(flags["into"]) };
+            throw doErr(`merge cannot operate on a ${addr.kind} address (${a0}); merge two assets or two scenes`);
+        }
+        case "insert": {
+            const addr = parseAnyAddress(a0);
+            if (addr.kind === "episode") {
+                return { op: "scene.insert", at: a0, location: flags["location"], time: flags["time"], space: flags["space"], at_index: flags["at"], before: flags["before"], after: flags["after"], scene_id: flags["scene-id"] };
+            }
+            if (addr.kind === "scene") {
+                return { op: "action.insert", at: a0, type: flags["type"], content: flags["content"], at_index: flags["at"], before: flags["before"], after: flags["after"], actor_id: flags["actor"], speaker_id: flags["speaker"] };
+            }
+            throw doErr(`insert needs ep_NNN (scene insert) or ep_NNN/scn_NNN (action insert), got a ${addr.kind} address (${a0})`);
+        }
+        default:
+            throw doErr(`unknown verb '${verb}' (structural/edit/create verbs are supported; queries are not)`);
+    }
+}
+export function actionAddress(epId, sceneId, idx) {
+    return `${epId}/${sceneId}#${idx}`;
+}
+export function formatInspectAction(epId, sceneId, idx, action) {
+    const addr = actionAddress(epId, sceneId, idx);
+    const type = strOf(action["type"]).trim() || "action";
+    const delivery = strOf(action["delivery"]).trim();
+    const tag = delivery ? `${type} ${delivery}` : type;
+    // Prefer the speaker_id (concrete) over actor_id (asset), and skip both when
+    // the action is narrative (no speaker). Format kept on a single line so agents
+    // can grep the output.
+    const speakerId = strOf(action["speaker_id"]).trim();
+    const actorId = strOf(action["actor_id"]).trim();
+    const who = speakerId || actorId;
+    let content = strOf(action["content"]);
+    if (!content) {
+        const lines = asList(action["lines"]);
+        if (lines.length > 0)
+            content = lines.map((l) => strOf(l["content"])).join(" / ");
+    }
+    const prefix = who ? `${addr} [${tag} ${who}]` : `${addr} [${tag}]`;
+    return content ? `${prefix} ${content}` : prefix;
+}
+// ---------------------------------------------------------------------------
+// command_script_patch
+// ---------------------------------------------------------------------------
+export const SKIPPABLE_EDIT_CODES = new Set([
+    "REGEX_NO_MATCH",
+    "FROM_TEXT_NOT_FOUND",
+    "OVERLAP_DIALOGUE_UNSUPPORTED",
+]);
+// ---------------------------------------------------------------------------
+// Single-op helpers
+// ---------------------------------------------------------------------------
+export async function applySingleScriptOp(opts, op) {
+    const workspace = strOf(opts["workspace_path"] || "workspace");
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const applied = applyPatchOperations(script, scriptSourceText(workspace), [op]);
+    const opName = applied[0] ?? strOf(op["op"]);
+    const [newRevision, idempotent] = await saveScriptSession(session, opts, opName);
+    const validation = validateSession(session);
+    await syncValidationResult(session, validation, newRevision);
+    const passed = Boolean(validation["passed"]);
+    const resultLines = [
+        `operation: ${opName}`,
+        `validation: ${passed ? "passed" : "needs repair"}`,
+    ];
+    if (session.remote) {
+        resultLines.push(`revision: ${newRevision}`);
+        resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
+    }
+    const report = {
+        title: passed ? "SCRIPT OP APPLIED" : "SCRIPT OP APPLIED: Validation needs repair",
+        op: opName,
+        changed: applied.length > 0,
+        summary: summarizeScriptOp(script, op),
+        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
+        result: resultLines,
+        issues: summarizeIssues(asList(validation["issues"])),
+        artifacts: [session.artifactLabel, path.join(directDir(workspace), "validation.json")],
+        next: [passed ? "Continue editing the final script." : "Inspect issues and apply another patch."],
+    };
+    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
+}
+export function summarizeScriptOp(_script, op) {
+    const kind = strOf(op["op"]);
+    if (kind === "actor.add")
+        return `已新增人物 ${op["name"] || op["actor_name"]}${op["role_type"] ? `（${op["role_type"]}）` : ""}`;
+    if (kind === "location.add")
+        return `已新增场景地点 ${op["name"] || op["location_name"]}`;
+    if (kind === "prop.add")
+        return `已新增道具 ${op["name"] || op["prop_name"]}`;
+    if (kind === "episode.add")
+        return `已新增分集${op["episode_id"] ? ` ${op["episode_id"]}` : "（自动编号）"}${op["title"] ? `：${op["title"]}` : ""}`;
+    if (kind === "state.add")
+        return `已为 ${op["target"]} 新增状态 ${op["state_id"]}: ${op["name"] || op["state_name"]}`;
+    if (kind === "action.state.change")
+        return `已在 ${op["at"]} 为 ${op["target"]} 设置状态切换到 ${op["to"] || op["to_state_id"]}`;
+    if (kind.startsWith("state."))
+        return `已执行 ${kind}: ${op["target"]}`;
+    if (kind.startsWith("dialogue."))
+        return `已执行 ${kind}: ${op["at"]}`;
+    return `已执行 ${kind}`;
+}
+// Accept `/re/flags` as-is; wrap a bare pattern as `/pattern/` so
+// `replace --regex --from '^\s*\[[^\]]*\]'` works without the user typing slashes.
+export function regexPattern(raw) {
+    const s = raw.trim();
+    if (s.length >= 2 && s.startsWith("/") && s.lastIndexOf("/") > 0)
+        return s;
+    return `/${s}/`;
+}
+// The selector-driven write runner. Resolves `opts` to its matched actions
+// (range/region + predicates) and applies one op template to each, as a single
+// in-memory pass committed once. Guardrail: with no --apply it's a DRY-RUN that
+// reports the blast radius and writes nothing; --apply commits. Per-action
+// "no match here / overlap dialogue" errors are skipped (a sweep); anything else
+// aborts the whole edit before any write. Shared by every selector-capable verb.
+export async function applySelectorEdits(opts, template, verbLabel) {
+    const workspace = strOf(opts["workspace_path"] || "workspace");
+    const apply = Boolean(opts["apply"]);
+    const opName = strOf(template["op"]);
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const targets = resolveActionTargets(script, opts);
+    const refs = targets.map((t) => `${t.epId}/${t.sceneId}#${t.idx}`);
+    const source = scriptSourceText(workspace);
+    let applied = 0;
+    let skipped = 0;
+    for (const ref of refs) {
+        try {
+            // Skip the per-op scene renumber; selector verbs are all non-structural,
+            // so we renumber once after the whole sweep instead of N times.
+            applyPatchOperations(script, source, [{ ...template, at: ref }], { renumber: false });
+            applied += 1;
+        }
+        catch (err) {
+            if (err instanceof CliError && err.errorCode && SKIPPABLE_EDIT_CODES.has(err.errorCode)) {
+                skipped += 1;
+                continue;
+            }
+            throw err;
+        }
+    }
+    if (applied > 0)
+        renumberSceneIds(script);
+    const sample = refs.slice(0, 12);
+    const blast = [
+        `verb: ${verbLabel} (${opName})`,
+        `matched: ${refs.length} action(s)`,
+        `${apply ? "applied" : "would-apply"}: ${applied}`,
+        `${apply ? "skipped" : "would-skip"}: ${skipped}`,
+        ...(sample.length ? [`targets: ${sample.join(", ")}${refs.length > sample.length ? ` … (+${refs.length - sample.length} more)` : ""}`] : []),
+    ];
+    if (!apply) {
+        const validation = validateSession(session);
+        const passed = Boolean(validation["passed"]);
+        const report = {
+            title: refs.length === 0 ? "SELECTOR EDIT DRY-RUN: no match" : "SELECTOR EDIT DRY-RUN (no write)",
+            op: `${opName}.dry-run`,
+            changed: false,
+            summary: `matched ${refs.length} action(s); would apply ${applied}, skip ${skipped} — pass --apply to commit`,
+            result: [...blast, `validation: ${passed ? "would pass" : "would need repair"}`, "dry-run: no write performed"],
+            warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
+            issues: summarizeIssues(asList(validation["issues"])),
+            artifacts: [session.artifactLabel],
+            next: [refs.length === 0 ? "Widen the selection (--in / --grep / predicates)." : "Re-run with --apply to commit."],
+        };
+        return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
+    }
+    if (refs.length === 0) {
+        return [{
+                title: "SELECTOR EDIT: no match",
+                op: opName,
+                changed: false,
+                summary: "matched 0 action(s); nothing written",
+                result: blast,
+                artifacts: [session.artifactLabel],
+                next: ["Widen the selection (--in / --grep / predicates)."],
+            }, EXIT_OK];
+    }
+    const [newRevision, idempotent] = await saveScriptSession(session, opts, opName);
+    const validation = validateSession(session);
+    await syncValidationResult(session, validation, newRevision);
+    const passed = Boolean(validation["passed"]);
+    const resultLines = [...blast, `validation: ${passed ? "passed" : "needs repair"}`];
+    if (session.remote) {
+        resultLines.push(`revision: ${newRevision}`);
+        resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
+    }
+    const report = {
+        title: passed ? "SELECTOR EDIT APPLIED" : "SELECTOR EDIT APPLIED: Validation needs repair",
+        op: opName,
+        changed: applied > 0,
+        summary: `matched ${refs.length} action(s); applied ${applied}, skipped ${skipped}`,
+        result: resultLines,
+        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
+        issues: summarizeIssues(asList(validation["issues"])),
+        artifacts: [session.artifactLabel, path.join(directDir(workspace), "validation.json")],
+        next: [passed ? "Continue editing the final script." : "Inspect issues and apply another edit."],
+    };
+    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
+}
+export { sortDeep };
+// ===========================================================================
+// 0.6.0 plural-noun query commands (replace `commandScriptInspect --target X`)
+// ===========================================================================
+//
+// Each command is a thin read-only wrapper around the underlying script
+// document. They all return a Report shaped like inspect's existing output but
+// without the `--target` flag — the verb itself encodes the target. Filters
+// use `--in <addr>` (compose with the address parsers) plus per-target
+// predicates (--name / --kind / --has / --grep / --context / --type / --actor
+// / --speaker / --severity / --code / --has-{actor,location,prop}).
+// Resolve the speaker_id → source actor mapping once per call. Used by
+// commandActions's --actor filter when the action speaks via a speaker.
+export function speakerSourceActorMap(script) {
+    const map = new Map();
+    for (const s of asList(script["speakers"])) {
+        const sourceKind = strOf(s["source_kind"]);
+        if (sourceKind === "actor") {
+            const sid = strOf(s["speaker_id"]);
+            const src = strOf(s["source_id"]);
+            if (sid && src)
+                map.set(sid, src);
+        }
+    }
+    return map;
+}
+export function speakerIdsInAction(action) {
+    const ids = new Set();
+    const direct = strOf(action["speaker_id"]).trim();
+    if (direct)
+        ids.add(direct);
+    for (const sp of asList(action["speakers"])) {
+        const id = strOf(sp["speaker_id"]).trim();
+        if (id)
+            ids.add(id);
+    }
+    for (const line of asList(action["lines"])) {
+        const id = strOf(line["speaker_id"]).trim();
+        if (id)
+            ids.add(id);
+    }
+    return ids;
+}
+export function actorIdsInAction(action, speakerToActor) {
+    const ids = new Set();
+    const direct = strOf(action["actor_id"]).trim();
+    if (direct)
+        ids.add(direct);
+    for (const spkId of speakerIdsInAction(action)) {
+        const actor = speakerToActor.get(spkId);
+        if (actor)
+            ids.add(actor);
+    }
+    return ids;
+}
+// Build a grep matcher. /pattern/flags → RegExp, otherwise literal substring.
+// Pre-flight checks block the common ReDoS shapes before they hit V8's regex
+// engine: nested quantifiers like (a+)+, (a*)+, (a*|b*)+ etc. compile fine
+// but hang the process on adversarial input. Since --grep accepts caller-
+// controlled patterns and runs over every action in scope, the safe move is
+// to reject patterns with quantifier-on-group-with-internal-quantifier and
+// cap the pattern length.
+export function buildGrepMatcher(raw) {
+    if (!raw)
+        return null;
+    const m = /^\/(.+)\/([gimsuy]*)$/.exec(raw);
+    if (m) {
+        const pattern = m[1];
+        if (isDangerousRegex(pattern)) {
+            throw new CliError("QUERY BLOCKED: regex unsafe", "regex pattern has nested quantifiers (ReDoS risk) or exceeds the length limit.", {
+                exitCode: EXIT_USAGE,
+                required: [`pattern length <= ${MAX_GREP_PATTERN_LEN}; no quantifier-on-group-with-internal-quantifier (e.g. (a+)+)`],
+                received: [`length=${pattern.length}, sample=${pattern.slice(0, 80)}`],
+                nextSteps: ["Rewrite the regex to avoid nested quantifiers, or use a literal substring (drop the /…/ wrapper)."],
+                errorCode: "REGEX_UNSAFE",
+            });
+        }
+        try {
+            const re = new RegExp(pattern, m[2]);
+            return (hay) => re.test(hay);
+        }
+        catch {
+            // Malformed regex — treat as literal.
+        }
+    }
+    return (hay) => hay.includes(raw);
+}
+export function buildReport(op, title, lines, artifactLabel, next) {
+    return {
+        title,
+        op,
+        changed: false,
+        summary: `${lines.length} item(s)`,
+        result: lines.length > 0 ? lines : ["No matching items."],
+        artifacts: [artifactLabel],
+        next,
+    };
+}
+// ----- summary --------------------------------------------------------------
+export function synopsisPreview(text, limit) {
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    return oneLine.length > limit ? `${oneLine.slice(0, limit)}…` : oneLine;
+}
+export function episodeInSelector(selector, epId, scenes) {
+    if (selector.isEmpty)
+        return true;
+    if (selector.matchesScene(epId, "scn_000000"))
+        return true;
+    for (const scene of scenes) {
+        if (selector.matchesScene(epId, strOf(scene["scene_id"])))
+            return true;
+    }
+    return false;
+}
+export function nameMaps(script) {
+    const out = { actor: new Map(), location: new Map(), prop: new Map() };
+    for (const a of asList(script["actors"]))
+        out.actor.set(strOf(a["actor_id"]), strOf(a["actor_name"]));
+    for (const l of asList(script["locations"]))
+        out.location.set(strOf(l["location_id"]), strOf(l["location_name"]));
+    for (const p of asList(script["props"]))
+        out.prop.set(strOf(p["prop_id"]), strOf(p["prop_name"]));
+    return out;
+}
+export function formatScene(epId, scene, names) {
+    const ctx = isDict(scene["context"]) ? scene["context"] : {};
+    const env = isDict(scene["environment"]) ? scene["environment"] : {};
+    const space = strOf(env["space"]) || "-";
+    const time = strOf(env["time"]) || "-";
+    const locations = asList(ctx["locations"]).map((r) => {
+        const id = strOf(r["location_id"]);
+        return `${id}(${names.location.get(id) || "?"})`;
+    });
+    const actors = asList(ctx["actors"]).map((r) => {
+        const id = strOf(r["actor_id"]);
+        return `${id}(${names.actor.get(id) || "?"})`;
+    });
+    const props = asList(ctx["props"]).map((r) => {
+        const id = strOf(r["prop_id"]);
+        return `${id}(${names.prop.get(id) || "?"})`;
+    });
+    const actionCount = asList(scene["actions"]).length;
+    return `${epId}/${scene["scene_id"]} [${space} ${time}] location=${locations.join(",") || "-"} actors=${actors.join(",") || "-"} props=${props.join(",") || "-"} actions=${actionCount}`;
+}
+export const HAS_FILTERS = new Set(["state-changes", "transition", "lines"]);
+// Resolve a selection (--in range/region selector + --type/--actor/--speaker/
+// --grep/--has predicates, AND-combined) to the matching actions, in document
+// order. The single matcher behind both `actions` queries and selector-driven
+// writes. Does NOT enforce "at least one filter" — that policy is caller-owned
+// (queries refuse a bare dump; writes gate on --all). Validates the --has value.
+export function resolveActionTargets(script, opts) {
+    const selector = parseInSelector(strOf(opts["in"]));
+    const typeFilter = strOf(opts["type"]).trim();
+    const actorFilter = strOf(opts["actor"]).trim();
+    const speakerFilter = strOf(opts["speaker"]).trim();
+    const hasFilter = strOf(opts["has"]).trim();
+    // Whitelist --has: silently accepting unknown values means a typo like
+    // "state_changes" (underscore) passed the filter-missing guard but bypassed
+    // every concrete predicate, returning the whole script.
+    if (hasFilter && !HAS_FILTERS.has(hasFilter)) {
+        throw new CliError("QUERY BLOCKED: --has value invalid", "--has value invalid.", {
+            exitCode: EXIT_USAGE,
+            required: [`--has: one of ${[...HAS_FILTERS].join(", ")}`],
+            received: [hasFilter],
+            nextSteps: ["Use a supported --has value."],
+            errorCode: "HAS_FILTER_INVALID",
+        });
+    }
+    const grepMatcher = buildGrepMatcher(strOf(opts["grep"]));
+    const speakerToActor = (actorFilter || speakerFilter) ? speakerSourceActorMap(script) : new Map();
+    const out = [];
+    for (const ep of asList(script["episodes"])) {
+        const epId = strOf(ep["episode_id"]);
+        for (const scene of asList(ep["scenes"])) {
+            const sceneId = strOf(scene["scene_id"]);
+            if (!selector.matchesScene(epId, sceneId))
+                continue;
+            const actions = asList(scene["actions"]);
+            for (let i = 0; i < actions.length; i++) {
+                if (!selector.matchesAction(epId, sceneId, i))
+                    continue;
+                const a = actions[i];
+                if (typeFilter && strOf(a["type"]).trim() !== typeFilter)
+                    continue;
+                if (speakerFilter && !speakerIdsInAction(a).has(speakerFilter))
+                    continue;
+                if (actorFilter && !actorIdsInAction(a, speakerToActor).has(actorFilter))
+                    continue;
+                if (hasFilter === "state-changes" && asList(a["state_changes"]).length === 0)
+                    continue;
+                if (hasFilter === "transition" && !isDict(a["transition_prompt"]))
+                    continue;
+                if (hasFilter === "lines" && asList(a["lines"]).length === 0)
+                    continue;
+                if (grepMatcher) {
+                    let hay = strOf(a["content"]);
+                    for (const line of asList(a["lines"]))
+                        hay += "\n" + strOf(line["content"]);
+                    if (!grepMatcher(hay))
+                        continue;
+                }
+                out.push({ epId, sceneId, idx: i, action: a });
+            }
+        }
+    }
+    return out;
+}
+// Whether a selection in `opts` has any filter at all (scope or predicate).
+export function selectionHasAnyFilter(opts) {
+    return Boolean(!parseInSelector(strOf(opts["in"])).isEmpty ||
+        strOf(opts["grep"]) || strOf(opts["type"]).trim() || strOf(opts["actor"]).trim() ||
+        strOf(opts["speaker"]).trim() || strOf(opts["has"]).trim());
+}
+export function listAssetsByKind(script, kind, opts) {
+    const lines = [];
+    const [key, idKey, nameKey] = (() => {
+        switch (kind) {
+            case "actor": return ["actors", "actor_id", "actor_name"];
+            case "location": return ["locations", "location_id", "location_name"];
+            case "prop": return ["props", "prop_id", "prop_name"];
+        }
+    })();
+    // Build the set of asset ids referenced inside the --in scope. A range or
+    // multi-region selector takes the union of context refs over every matched
+    // scene; a bare single action point (e.g. ep_001/scn_003#2) keeps the legacy
+    // "narrow to that one action's actor" behavior.
+    // WHOLE_SCRIPT ('--in *') means "all assets" — it must NOT narrow to the set
+    // of assets referenced in scene context (that would drop registered-but-not-
+    // yet-placed assets). Only a real address-region selector narrows.
+    let scopeIds = null;
+    if (!opts.selector.isEmpty && opts.selector !== WHOLE_SCRIPT) {
+        scopeIds = new Set();
+        const single = selectorSingleActionPoint(opts.selector);
+        const pluralKey = kind === "actor" ? "actors" : kind === "location" ? "locations" : "props";
+        for (const ep of asList(script["episodes"])) {
+            const epId = strOf(ep["episode_id"]);
+            for (const scene of asList(ep["scenes"])) {
+                const sceneId = strOf(scene["scene_id"]);
+                if (!opts.selector.matchesScene(epId, sceneId))
+                    continue;
+                if (single) {
+                    // Single action point: matchesScene already isolates the target
+                    // scene. Legacy narrowing is implemented for actor only.
+                    if (kind === "actor") {
+                        const a = asList(scene["actions"])[single.idx];
+                        const aid = a ? strOf(a["actor_id"]).trim() : "";
+                        if (aid)
+                            scopeIds.add(aid);
+                    }
+                    continue;
+                }
+                const ctx = isDict(scene["context"]) ? scene["context"] : {};
+                for (const ref of asList(ctx[pluralKey])) {
+                    scopeIds.add(strOf(ref[idKey]));
+                }
+            }
+        }
+    }
+    for (const asset of asList(script[key])) {
+        const id = strOf(asset[idKey]);
+        const name = strOf(asset[nameKey]);
+        if (opts.id && opts.id !== id)
+            continue;
+        if (opts.name && !name.includes(opts.name))
+            continue;
+        if (scopeIds && !scopeIds.has(id))
+            continue;
+        const aliases = asList(asset["aliases"]).map((s) => strOf(s));
+        const role = strOf(asset["role_type"]);
+        const descPresent = strOf(asset["description"]).trim() ? "yes" : "missing";
+        const states = asList(asset["states"]).length;
+        const extra = [];
+        if (aliases.length > 0)
+            extra.push(`aliases=(${aliases.join(",")})`);
+        if (role)
+            extra.push(`role=${role}`);
+        extra.push(`states=${states}`, `description=${descPresent}`);
+        lines.push(`${kind} ${id}: ${name || "-"} ${extra.join(" ")}`);
+    }
+    return lines;
+}
+export function splitSpeakerList(raw) {
+    if (Array.isArray(raw))
+        return raw.map((v) => strOf(v)).filter((v) => v);
+    return strOf(raw).split(",").map((s) => s.trim()).filter((s) => s);
+}
+export function blankCreateReport(session, validation, idempotent) {
+    const passed = Boolean(validation["passed"]);
+    const resultLines = ["created: blank script (schema v2)", `validation: ${passed ? "passed" : "needs repair"}`];
+    if (session.remote) {
+        resultLines.push(`revision: ${session.revision}`);
+        if (idempotent !== null)
+            resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
+    }
+    return {
+        title: passed ? "SCRIPT CREATED: Blank scaffold" : "SCRIPT CREATED: Validation needs repair",
+        op: "script.create",
+        changed: true,
+        summary: "已创建空白剧本（schema v2，待填充人物/地点/道具/分集）",
+        result: resultLines,
+        warnings: summarizeIssues(asList(validation["issues"])),
+        artifacts: [session.artifactLabel],
+        next: [
+            "用 worldview 设定世界观，用 add-actor / add-location / add-prop 注册资产，用 add-episode + insert 搭出分集与场景。",
+        ],
+    };
+}
+// ----- add-* (register new entities) ----------------------------------------
+// Read the single positional <name> arg shared by add-actor/location/prop, or
+// throw the common ARGS_MISSING usage error with a verb-specific example.
+export function requireNameArg(opts, verb, example) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError(`VERB BLOCKED: ${verb} name missing`, "Name missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<name>"],
+            received: ["<empty>"],
+            nextSteps: [example],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return args[0];
+}
+//# sourceMappingURL=lib.js.map