@lingjingai/scriptctl 0.19.2 → 0.21.0

package/dist/usecases/script/episodes.js

@@ -0,0 +1,36 @@
+import { EXIT_OK, } from "../../common.js";
+import { parseInSelector, } from "../../domain/script/selector.js";
+import { asList, strOf, } from "../../domain/script/shared.js";
+import { loadScriptForEdit, parseBound, episodeCharCounts, } from "./session.js";
+import { buildReport, synopsisPreview, episodeInSelector, } from "./lib.js";
+export async function commandEpisodes(opts) {
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const itemId = strOf(opts["id"]).trim();
+    const selector = parseInSelector(strOf(opts["in"]));
+    const minChars = parseBound(opts["min_chars"]);
+    const maxChars = parseBound(opts["max_chars"]);
+    const lines = [];
+    for (const ep of asList(script["episodes"])) {
+        const epId = strOf(ep["episode_id"]);
+        if (itemId && itemId !== epId)
+            continue;
+        const scenes = asList(ep["scenes"]);
+        if (!episodeInSelector(selector, epId, scenes))
+            continue;
+        let actionCount = 0;
+        const chars = episodeCharCounts(scenes);
+        for (const scene of scenes)
+            actionCount += asList(scene["actions"]).length;
+        if (minChars !== null && chars.total < minChars)
+            continue;
+        if (maxChars !== null && chars.total > maxChars)
+            continue;
+        const epSynopsis = strOf(ep["synopsis"]).trim();
+        const synopsisField = epSynopsis ? `, synopsis=${synopsisPreview(epSynopsis, 60)}` : "";
+        lines.push(`${ep["episode_id"]}: scenes=${scenes.length}, actions=${actionCount}, chars=${chars.total} (dialogue=${chars.dialogue}, action=${chars.action}), title=${ep["title"] || "-"}${synopsisField}`);
+    }
+    return [buildReport("query.episodes", "EPISODES", lines, session.artifactLabel, ["Use `scriptctl scenes --in <ep>` to drill in, or edit verbs to mutate."]), EXIT_OK];
+}
+// ----- scenes ---------------------------------------------------------------
+//# sourceMappingURL=episodes.js.map

package/dist/usecases/script/episodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodes.js","sourceRoot":"","sources":["../../../src/usecases/script/episodes.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,OAAO,GAWR,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAIL,eAAe,GAGhB,MAAM,iCAAiC,CAAC;AAwBzC,OAAO,EACL,MAAM,EAIN,KAAK,GACN,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,iBAAiB,EAC6B,UAAU,EAAE,iBAAiB,GAC5E,MAAM,cAAc,CAAC;AACtB,OAAO,EACwS,WAAW,EAAE,eAAe,EAAE,iBAAiB,GAC7V,MAAM,UAAU,CAAC;AAElB,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAU;IAC9C,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,EAAE,IAAI,MAAM,CAAO,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;QACrC,IAAI,MAAM,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QACxC,MAAM,MAAM,GAAG,MAAM,CAAO,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1C,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC;YAAE,SAAS;QACzD,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QACxC,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,WAAW,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3E,IAAI,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,GAAG,QAAQ;YAAE,SAAS;QAC1D,IAAI,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,GAAG,QAAQ;YAAE,SAAS;QAC1D,MAAM,UAAU,GAAG,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,CAAC,cAAc,eAAe,CAAC,UAAU,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,KAAK,CAAC,IAAI,CACR,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,MAAM,CAAC,MAAM,aAAa,WAAW,WAAW,KAAK,CAAC,KAAK,cAAc,KAAK,CAAC,QAAQ,YAAY,KAAK,CAAC,MAAM,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,GAAG,GAAG,aAAa,EAAE,CAC/L,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,EAC5E,CAAC,wEAAwE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1F,CAAC;AAED,+EAA+E"}

package/dist/usecases/script/export.d.ts

@@ -0,0 +1,3 @@
+import { type Report } from "../../common.js";
+import { type Dict } from "../../domain/script/shared.js";
+export declare function commandExport(opts: Dict): Promise<[Report, number]>;

package/dist/usecases/script/export.js

@@ -0,0 +1,117 @@
+import * as path from "node:path";
+import { CliError, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_USAGE, directDir, exists, readJson, sha256Text, } from "../../common.js";
+import { validateScript } from "../../domain/script/validate.js";
+import { ScriptOutputApiError, } from "../../infra/script-output-store.js";
+import { readRunState, summarizeIssues, updateRunState, } from "../direct.js";
+import { sortDeep } from "../../domain/direct-core.js";
+import { asList, isDict, strOf, } from "../../domain/script/shared.js";
+import { ScriptEditSession, scriptOutputClient, apiErrorToCli, currentRevisionOrZero, syncValidationResult, } from "./session.js";
+export async function commandExport(opts) {
+    const workspace = strOf(opts["workspace_path"] || "workspace");
+    const force = Boolean(opts["force"]);
+    const scriptPath = path.join(directDir(workspace), "script.initial.json");
+    if (!exists(scriptPath)) {
+        throw new CliError("EXPORT 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 state = readRunState(workspace);
+    const provider = strOf(state["provider"]);
+    if (provider === "mock" && process.env.SCRIPTCTL_ALLOW_MOCK_EXPORT !== "1") {
+        const report = {
+            title: "EXPORT BLOCKED: Mock provider result",
+            result: ["script.initial.json was produced by --provider mock and was not exported."],
+            artifacts: [path.join(directDir(workspace), "run_state.json")],
+            next: ["Rerun init with --provider anthropic for deliverable conversion."],
+        };
+        return [report, EXIT_NEEDS_AGENT];
+    }
+    const validation = validateScript(workspace, scriptPath);
+    const blockingOrError = Boolean(validation["has_blocking"]) ||
+        asList(validation["issues"]).some((it) => isDict(it) && (it["severity"] === "blocking" || it["severity"] === "error"));
+    if (!validation["passed"] && (!force || blockingOrError)) {
+        const title = force
+            ? "EXPORT BLOCKED: Validation errors require repair"
+            : "EXPORT BLOCKED: Validation needs agent repair";
+        const report = {
+            title,
+            result: ["script.initial.json was not exported."],
+            artifacts: [path.join(directDir(workspace), "validation.json")],
+            issues: summarizeIssues(asList(validation["issues"])),
+            next: ["Inspect issues and apply structured patches, then validate/export."],
+        };
+        return [report, EXIT_NEEDS_AGENT];
+    }
+    let script;
+    try {
+        script = readJson(scriptPath);
+    }
+    catch (exc) {
+        throw new CliError("EXPORT BLOCKED: script.initial.json invalid", "script.initial.json invalid.", {
+            exitCode: EXIT_INPUT,
+            required: ["valid script.initial.json"],
+            received: [`${scriptPath}: ${exc.message}`],
+            nextSteps: ["Fix script.initial.json or rerun direct init."],
+            errorCode: "SCRIPT_JSON_INVALID",
+        });
+    }
+    if (!isDict(script)) {
+        throw new CliError("EXPORT BLOCKED: script root invalid", "script root invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["script root object"],
+            received: [Array.isArray(script) ? "array" : typeof script],
+            nextSteps: ["Use a valid script document object."],
+            errorCode: "SCRIPT_ROOT_INVALID",
+        });
+    }
+    const client = scriptOutputClient(opts);
+    const baseRevision = await currentRevisionOrZero(client);
+    // Sorted-keys serialization mirrors Python json.dumps(sort_keys=True, separators=(",",":"))
+    const sortedScript = sortDeep(script);
+    const scriptHash = sha256Text(JSON.stringify(sortedScript));
+    const requestId = strOf(opts["request_id"]).trim() || `scriptctl-direct-export:${scriptHash}`;
+    let replaceRes;
+    try {
+        replaceRes = await client.replaceScript({
+            requestId,
+            baseRevision,
+            script,
+            source: "ctl",
+        });
+    }
+    catch (exc) {
+        if (exc instanceof ScriptOutputApiError) {
+            throw apiErrorToCli("SCRIPT API BLOCKED: Export write failed", exc);
+        }
+        throw exc;
+    }
+    const revision = Number(replaceRes["revision"] ?? 0);
+    const remoteSession = new ScriptEditSession({
+        workspace,
+        script,
+        client,
+        projectGroupNo: client.projectGroupNo,
+        revision,
+    });
+    await syncValidationResult(remoteSession, validation, revision);
+    const outputLabel = remoteSession.artifactLabel;
+    updateRunState(workspace, { status: "exported", output_path: outputLabel });
+    const report = {
+        title: "EXPORT COMPLETE: Final script stored in DB",
+        result: [
+            `validation: ${validation["passed"] ? "passed" : "forced"}`,
+            `base_revision: ${baseRevision}`,
+            `revision: ${revision}`,
+            `idempotent: ${String(Boolean(replaceRes["idempotent"])).toLowerCase()}`,
+        ],
+        artifacts: [outputLabel, path.join(directDir(workspace), "validation.json")],
+        next: ["Proceed to downstream asset or footage stages."],
+    };
+    return [report, EXIT_OK];
+}
+// sortDeep is the canonical helper in domain/direct-core; re-exported here for
+// back-compat with existing importers of `usecases/script`.
+//# sourceMappingURL=export.js.map

package/dist/usecases/script/export.js.map

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

package/dist/usecases/script/insert.d.ts

@@ -0,0 +1,3 @@
+import { type Report } from "../../common.js";
+import { type Dict } from "../../domain/script/shared.js";
+export declare function commandInsert(opts: Dict): Promise<[Report, number]>;

package/dist/usecases/script/insert.js

@@ -0,0 +1,87 @@
+import { CliError, EXIT_USAGE, } from "../../common.js";
+import { parseAnyAddress, } from "../../domain/script/address.js";
+import { asList, } from "../../domain/script/shared.js";
+import { applySingleScriptOp, } from "./lib.js";
+export async function commandInsert(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Insert address missing", "Insert address missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<addr>: ep_NNN/scn_NNN (action insert) or ep_NNN (scene insert)"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl insert ep_001/scn_001 --type action --content \"...\""],
+            errorCode: "ADDRESS_MISSING",
+        });
+    }
+    const addr = parseAnyAddress(args[0]);
+    // Per-kind flag whitelist. Silently dropping mismatched flags hid two
+    // real bugs:
+    //   - scene insert was ignoring --scene-id (the user lost custom IDs).
+    //   - mixing action + scene insert flags (`--type` with episode addr, or
+    //     `--location` with scene addr) ran the wrong dispatch silently.
+    const flagsUsed = {
+        type: opts["type"] !== undefined,
+        content: opts["content"] !== undefined,
+        actor: (opts["actor_id"] ?? opts["actor"]) !== undefined,
+        speaker: (opts["speaker_id"] ?? opts["speaker"]) !== undefined,
+        location: opts["location"] !== undefined,
+        time: opts["time"] !== undefined,
+        space: opts["space"] !== undefined,
+        "scene-id": opts["scene_id"] !== undefined,
+    };
+    function rejectFlags(kind, allowed) {
+        const allow = new Set(allowed);
+        const bad = [];
+        for (const f of Object.keys(flagsUsed)) {
+            if (flagsUsed[f] && !allow.has(f))
+                bad.push(`--${f}`);
+        }
+        if (bad.length > 0) {
+            throw new CliError("VERB BLOCKED: flag not applicable", `${bad.join(", ")} cannot be used with ${kind} insert.`, {
+                exitCode: EXIT_USAGE,
+                required: [`for ${kind} insert: ${allowed.map((f) => `--${f}`).join(" / ")}`],
+                received: bad,
+                nextSteps: ["Drop the unsupported flag(s) and retry."],
+                errorCode: "INSERT_FLAG_INVALID",
+            });
+        }
+    }
+    if (addr.kind === "scene") {
+        rejectFlags("action", ["type", "content", "actor", "speaker"]);
+        return applySingleScriptOp(opts, {
+            op: "action.insert",
+            at: args[0],
+            type: opts["type"],
+            content: opts["content"],
+            at_index: opts["at_index"] ?? opts["at"],
+            before: opts["before"],
+            after: opts["after"],
+            actor_id: opts["actor_id"] ?? opts["actor"],
+            speaker_id: opts["speaker_id"] ?? opts["speaker"],
+        });
+    }
+    if (addr.kind === "episode") {
+        rejectFlags("scene", ["location", "time", "space", "scene-id"]);
+        return applySingleScriptOp(opts, {
+            op: "scene.insert",
+            at: addr.episodeId,
+            location: opts["location"],
+            time: opts["time"],
+            space: opts["space"],
+            // Forward --scene-id (was previously silently dropped — scene.insert op
+            // reads `scene_id` to honor user-supplied ids for round-trip stability).
+            scene_id: opts["scene_id"],
+            at_index: opts["at_index"] ?? opts["at"],
+            before: opts["before"],
+            after: opts["after"],
+        });
+    }
+    throw new CliError("VERB BLOCKED: insert cannot operate on this address", "insert cannot operate on this address.", {
+        exitCode: EXIT_USAGE,
+        required: ["ep_NNN (scene insert) or ep_NNN/scn_NNN (action insert)"],
+        received: [args[0]],
+        nextSteps: ["Use an episode or scene address."],
+        errorCode: "ADDRESS_UNSUPPORTED",
+    });
+}
+//# sourceMappingURL=insert.js.map

package/dist/usecases/script/insert.js.map

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

package/dist/usecases/script/issues.d.ts

@@ -0,0 +1,3 @@
+import { type Report } from "../../common.js";
+import { type Dict } from "../../domain/script/shared.js";
+export declare function commandIssues(opts: Dict): Promise<[Report, number]>;

package/dist/usecases/script/issues.js

@@ -0,0 +1,27 @@
+import { EXIT_OK, } from "../../common.js";
+import { asList, strOf, } from "../../domain/script/shared.js";
+import { loadScriptForEdit, validateSession, } from "./session.js";
+import { buildReport, } from "./lib.js";
+export async function commandIssues(opts) {
+    const session = await loadScriptForEdit(opts);
+    const severityFilter = strOf(opts["severity"]).trim();
+    const codeFilter = strOf(opts["code"]).trim();
+    const validation = validateSession(session);
+    const lines = [];
+    for (const issue of asList(validation["issues"])) {
+        if (severityFilter && severityFilter !== strOf(issue["severity"]))
+            continue;
+        if (codeFilter && codeFilter !== strOf(issue["code"]))
+            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}]` : ""}`);
+    }
+    return [buildReport("query.issues", "ISSUES", lines, session.artifactLabel, ["Use the relevant edit verb to repair each issue."]), EXIT_OK];
+}
+// ----- refs (unified reverse lookup) ----------------------------------------
+//# sourceMappingURL=issues.js.map

package/dist/usecases/script/issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.js","sourceRoot":"","sources":["../../../src/usecases/script/issues.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,OAAO,GAWR,MAAM,iBAAiB,CAAC;AAmCzB,OAAO,EACL,MAAM,EAIN,KAAK,GACN,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,iBAAiB,EAAE,eAAe,GAEnC,MAAM,cAAc,CAAC;AACtB,OAAO,EACwS,WAAW,GACzT,MAAM,UAAU,CAAC;AAElB,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAU;IAC5C,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QACvD,IAAI,cAAc,IAAI,cAAc,KAAK,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAAE,SAAS;QAC5E,IAAI,UAAU,IAAI,UAAU,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAAE,SAAS;QAChE,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,CAAC;YACrD,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;gBAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpF,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxG,CAAC;IACD,OAAO,CAAC,WAAW,CAAC,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,EACxE,CAAC,kDAAkD,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACpE,CAAC;AAED,+EAA+E"}

package/dist/usecases/script/lib.d.ts

@@ -0,0 +1,77 @@
+import { CliError, type Report } from "../../common.js";
+import { type InSelector } from "../../domain/script/selector.js";
+import { sortDeep } from "../../domain/direct-core.js";
+import { type Dict } from "../../domain/script/shared.js";
+import { ScriptEditSession } from "./session.js";
+export interface DoToken {
+    text: string;
+    quoted: boolean;
+}
+export declare function tokenizeLine(line: string): DoToken[];
+export declare const DO_BOOL_FLAGS: Record<string, Set<string>>;
+export declare const DO_REPEAT_FLAGS: Record<string, Set<string>>;
+export interface ParsedDoLine {
+    verb: string;
+    args: string[];
+    flags: Dict;
+}
+export declare function parseDoLine(tokens: DoToken[]): ParsedDoLine;
+export declare function doErr(detail: string): CliError;
+export declare function stateChangeTemplate(target: string, f: {
+    to?: unknown;
+    from?: unknown;
+    effective?: unknown;
+    clear?: boolean;
+}): Dict;
+export declare function transitionTemplate(target: string, f: {
+    process?: unknown;
+    contrast?: unknown;
+    clear?: boolean;
+}): Dict;
+export declare function contextTemplate(target: string, f: {
+    state?: unknown;
+    clear?: boolean;
+    remove?: boolean;
+}): Dict;
+export declare function dialogueTemplate(speakers: string[], f: {
+    delivery?: unknown;
+}): Dict;
+export declare function lineToOp(verb: string, args: string[], flags: Dict): Dict;
+export declare function actionAddress(epId: string, sceneId: string, idx: number): string;
+export declare function formatInspectAction(epId: string, sceneId: string, idx: number, action: Dict): string;
+export declare const SKIPPABLE_EDIT_CODES: Set<string>;
+export declare function applySingleScriptOp(opts: Dict, op: Dict): Promise<[Report, number]>;
+export declare function summarizeScriptOp(_script: Dict, op: Dict): string;
+export declare function regexPattern(raw: string): string;
+export declare function applySelectorEdits(opts: Dict, template: Dict, verbLabel: string): Promise<[Report, number]>;
+export { sortDeep };
+export declare function speakerSourceActorMap(script: Dict): Map<string, string>;
+export declare function speakerIdsInAction(action: Dict): Set<string>;
+export declare function actorIdsInAction(action: Dict, speakerToActor: Map<string, string>): Set<string>;
+export declare function buildGrepMatcher(raw: string): ((hay: string) => boolean) | null;
+export declare function buildReport(op: string, title: string, lines: string[], artifactLabel: string, next: string[]): Report;
+export declare function synopsisPreview(text: string, limit: number): string;
+export declare function episodeInSelector(selector: InSelector, epId: string, scenes: Dict[]): boolean;
+export declare function nameMaps(script: Dict): {
+    actor: Map<string, string>;
+    location: Map<string, string>;
+    prop: Map<string, string>;
+};
+export declare function formatScene(epId: string, scene: Dict, names: ReturnType<typeof nameMaps>): string;
+export interface ActionTarget {
+    epId: string;
+    sceneId: string;
+    idx: number;
+    action: Dict;
+}
+export declare const HAS_FILTERS: Set<string>;
+export declare function resolveActionTargets(script: Dict, opts: Dict): ActionTarget[];
+export declare function selectionHasAnyFilter(opts: Dict): boolean;
+export declare function listAssetsByKind(script: Dict, kind: "actor" | "location" | "prop", opts: {
+    id: string;
+    name: string;
+    selector: InSelector;
+}): string[];
+export declare function splitSpeakerList(raw: unknown): string[];
+export declare function blankCreateReport(session: ScriptEditSession, validation: Dict, idempotent: boolean | null): Report;
+export declare function requireNameArg(opts: Dict, verb: string, example: string): string;