@lingjingai/scriptctl 0.13.1 → 0.19.0

package/dist/domain/script-core.d.ts

@@ -2,6 +2,16 @@ type Dict = Record<string, unknown>;
 export declare function findAction(script: Dict, epId: string, sceneId: string, actionIndex: number): Dict;
 export declare function findEpisode(script: Dict, epId: string): Dict;
 export declare function findScene(script: Dict, epId: string, sceneId: string): Dict;
+/**
+ * Minimal schema-v2 script skeleton: every required top-level field present,
+ * all collections empty. It is the starting point for building a script
+ * bottom-up with the atomic add/insert verbs instead of assembling it from
+ * source material (direct) or md (parse). `worldview`/`style`/`title` are
+ * present-but-empty so the field-presence checks pass; they get filled in
+ * later via `worldview` / `patch`. A blank script validates clean: NO_EPISODES
+ * is a completeness warning (`incomplete_ok`), not a blocker.
+ */
+export declare function blankScript(title?: string): Dict;
 /**
  * Validate a script's schema and asset wiring.
  *
@@ -11,6 +21,11 @@ export declare function findScene(script: Dict, epId: string, sceneId: string):
  *
  * Callers that already have the script as a parsed object (episode draft / publish
  * after assembly) should prefer `scriptData` to avoid the write-validate-rm dance.
+ *
+ * Completeness issues (no episodes, empty episode/scene, scene without location,
+ * missing asset description) are emitted as warnings (`incomplete_ok`), not
+ * errors — an unfinished but structurally-sound script passes. Only integrity
+ * violations (dangling refs, dup ids, invalid enums, missing ids/names) fail it.
  */
 export declare function validateScript(workspace: string, scriptPath?: string | null, opts?: {
     requireSource?: boolean;

package/dist/domain/script-core.js

@@ -63,6 +63,54 @@ export function findScene(script, epId, sceneId) {
     });
 }
 // ---------------------------------------------------------------------------
+// blank scaffold
+// ---------------------------------------------------------------------------
+/**
+ * Minimal schema-v2 script skeleton: every required top-level field present,
+ * all collections empty. It is the starting point for building a script
+ * bottom-up with the atomic add/insert verbs instead of assembling it from
+ * source material (direct) or md (parse). `worldview`/`style`/`title` are
+ * present-but-empty so the field-presence checks pass; they get filled in
+ * later via `worldview` / `patch`. A blank script validates clean: NO_EPISODES
+ * is a completeness warning (`incomplete_ok`), not a blocker.
+ */
+export function blankScript(title = "") {
+    return {
+        version: SCRIPT_SCHEMA_VERSION,
+        title: title,
+        worldview: "",
+        style: "",
+        actors: [],
+        locations: [],
+        props: [],
+        speakers: [],
+        episodes: [],
+    };
+}
+// Completeness vs. integrity. A script can be structurally sound but unfinished
+// (no episodes yet, an empty episode/scene, a scene without a location, an asset
+// without a description). Those gaps are emitted as `severity: "warning"` with
+// `incomplete_ok: true` directly at their source below — they never block, so an
+// unfinished-but-sound script is editable AND publishable. Only integrity
+// violations (dangling refs, duplicate ids, invalid enums, missing ids/names —
+// things that would corrupt the normalized DB graph) are `severity: "error"`.
+// One SCHEMA_ENTITY_FIELD_MISSING issue for a missing asset field. A missing
+// description is a completeness gap (warning); a missing id/name is an identity
+// error that would dangle in the DB graph. Shared by the actor/location/prop
+// validation loops so the severity/incomplete_ok/repair-hint policy lives once.
+function entityFieldMissingIssue(kindLabel, field, idValue) {
+    const isDescription = field === "description";
+    return {
+        code: "SCHEMA_ENTITY_FIELD_MISSING",
+        severity: isDescription ? "warning" : "error",
+        ...(isDescription ? { incomplete_ok: true } : {}),
+        summary: `${kindLabel} missing ${field}: ${idValue}`,
+        repair_hint: isDescription
+            ? "Describe with `describe` when ready (an undescribed asset is publishable)."
+            : `Patch ${kindLabel.toLowerCase()} metadata.`,
+    };
+}
+// ---------------------------------------------------------------------------
 // validate_script
 // ---------------------------------------------------------------------------
 /**
@@ -74,6 +122,11 @@ export function findScene(script, epId, sceneId) {
  *
  * Callers that already have the script as a parsed object (episode draft / publish
  * after assembly) should prefer `scriptData` to avoid the write-validate-rm dance.
+ *
+ * Completeness issues (no episodes, empty episode/scene, scene without location,
+ * missing asset description) are emitted as warnings (`incomplete_ok`), not
+ * errors — an unfinished but structurally-sound script passes. Only integrity
+ * violations (dangling refs, dup ids, invalid enums, missing ids/names) fail it.
  */
 export function validateScript(workspace, scriptPath = null, opts = {}) {
     const requireSource = opts.requireSource ?? true;
@@ -175,12 +228,7 @@ export function validateScript(workspace, scriptPath = null, opts = {}) {
         const actorName = strOf(actor["actor_name"]).trim();
         for (const field of ["actor_id", "actor_name", "description"]) {
             if (!strOf(actor[field]).trim()) {
-                issues.push({
-                    code: "SCHEMA_ENTITY_FIELD_MISSING",
-                    severity: "error",
-                    summary: `Actor missing ${field}: ${actor["actor_id"] || idx}`,
-                    repair_hint: "Patch actor metadata.",
-                });
+                issues.push(entityFieldMissingIssue("Actor", field, strOf(actor["actor_id"]) || String(idx)));
             }
         }
         if (actorName && cleanName(actorName) !== actorName) {
@@ -223,12 +271,7 @@ export function validateScript(workspace, scriptPath = null, opts = {}) {
         const locationName = strOf(loc["location_name"]).trim();
         for (const field of ["location_id", "location_name", "description"]) {
             if (!strOf(loc[field]).trim()) {
-                issues.push({
-                    code: "SCHEMA_ENTITY_FIELD_MISSING",
-                    severity: "error",
-                    summary: `Location missing ${field}: ${loc["location_id"] || idx}`,
-                    repair_hint: "Patch location metadata.",
-                });
+                issues.push(entityFieldMissingIssue("Location", field, strOf(loc["location_id"]) || String(idx)));
             }
         }
         if (locationName && cleanName(locationName) !== locationName) {
@@ -255,12 +298,7 @@ export function validateScript(workspace, scriptPath = null, opts = {}) {
         const propName = strOf(prop["prop_name"]).trim();
         for (const field of ["prop_id", "prop_name", "description"]) {
             if (!strOf(prop[field]).trim()) {
-                issues.push({
-                    code: "SCHEMA_ENTITY_FIELD_MISSING",
-                    severity: "error",
-                    summary: `Prop missing ${field}: ${prop["prop_id"] || idx}`,
-                    repair_hint: "Patch prop metadata.",
-                });
+                issues.push(entityFieldMissingIssue("Prop", field, strOf(prop["prop_id"]) || String(idx)));
             }
         }
         if (propName && cleanName(propName) !== propName) {
@@ -424,7 +462,7 @@ export function validateScript(workspace, scriptPath = null, opts = {}) {
     }
     const episodes = asList(script["episodes"]);
     if (episodes.length === 0) {
-        issues.push({ code: "NO_EPISODES", severity: "blocking", summary: "No episodes in script.", repair_hint: "Rerun init or patch episodes." });
+        issues.push({ code: "NO_EPISODES", severity: "warning", incomplete_ok: true, summary: "No episodes in script.", repair_hint: "Add episodes with add-episode (an empty script is publishable but renders to nothing)." });
     }
     let totalScenes = 0;
     let totalActions = 0;
@@ -444,10 +482,11 @@ export function validateScript(workspace, scriptPath = null, opts = {}) {
         if (scenes.length === 0) {
             issues.push({
                 code: "EPISODE_WITHOUT_SCENES",
-                severity: "error",
+                severity: "warning",
+                incomplete_ok: true,
                 episode: ep["episode_id"],
                 summary: "Episode has no scenes.",
-                repair_hint: "Patch at least one scene into the episode.",
+                repair_hint: "Add scenes with insert (an empty episode is publishable but renders to nothing).",
             });
         }
         for (const scene of scenes) {
@@ -483,11 +522,12 @@ export function validateScript(workspace, scriptPath = null, opts = {}) {
             if (ctxLocations.length === 0) {
                 issues.push({
                     code: "SCENE_WITHOUT_LOCATION",
-                    severity: "error",
+                    severity: "warning",
+                    incomplete_ok: true,
                     episode: ep["episode_id"],
                     scene: scene["scene_id"],
                     summary: "Scene has no location.",
-                    repair_hint: "Patch scene.locations with a registered location_id.",
+                    repair_hint: "Set a location with context (an unlocated scene is publishable but cannot render).",
                 });
             }
             for (const ref of ctxLocations) {
@@ -566,11 +606,12 @@ export function validateScript(workspace, scriptPath = null, opts = {}) {
             if (actionsArr.length === 0) {
                 issues.push({
                     code: "SCENE_WITHOUT_ACTIONS",
-                    severity: "error",
+                    severity: "warning",
+                    incomplete_ok: true,
                     episode: ep["episode_id"],
                     scene: scene["scene_id"],
                     summary: "Scene has no actions.",
-                    repair_hint: "Patch actions from source spans.",
+                    repair_hint: "Add actions with insert (an empty scene is publishable but renders to nothing).",
                 });
             }
             for (let actionIndex = 0; actionIndex < actionsArr.length; actionIndex++) {
@@ -936,17 +977,14 @@ function resolvePatchAsset(script, op, assetType = null) {
     return [asset, idKey, nameKey];
 }
 function nextStateId(script) {
-    let maxSeen = 0;
+    const ids = [];
     for (const key of ["actors", "locations", "props"]) {
         for (const asset of asList(script[key])) {
-            for (const state of asList(asset["states"])) {
-                const m = /^st_(\d+)$/.exec(strOf(state["state_id"]));
-                if (m)
-                    maxSeen = Math.max(maxSeen, parseInt(m[1], 10));
-            }
+            for (const state of asList(asset["states"]))
+                ids.push(state["state_id"]);
         }
     }
-    return fmtId("st", maxSeen + 1);
+    return nextSeqId(ids, "st");
 }
 function normalizeStates(script, rawStates, assetKind = "") {
     if (!isList(rawStates)) {
@@ -1461,16 +1499,31 @@ export function collectAssetRefs(script, kind, targetId) {
     }
     return refs;
 }
-function nextSceneId(script) {
+// Asset id prefixes. props use `prp_` (not `prop_`); mirrors direct-init output.
+const ASSET_ID_PREFIX = { actor: "act", location: "loc", prop: "prp" };
+// Next free `<prefix>_NNN` id given the existing ids in a collection. Scans for
+// the max NNN so a manually-chosen id (e.g. act_007) never collides with a later
+// auto-id. The single id-allocation routine behind nextScene/Asset/Episode/State.
+function nextSeqId(existingIds, prefix) {
+    const re = new RegExp(`^${prefix}_(\\d+)$`);
     let maxSeen = 0;
-    for (const ep of asList(script["episodes"])) {
-        for (const scene of asList(ep["scenes"])) {
-            const m = /^scn_(\d+)$/.exec(strOf(scene["scene_id"]));
-            if (m)
-                maxSeen = Math.max(maxSeen, parseInt(m[1], 10));
-        }
+    for (const raw of existingIds) {
+        const m = re.exec(strOf(raw));
+        if (m)
+            maxSeen = Math.max(maxSeen, parseInt(m[1], 10));
     }
-    return fmtId("scn", maxSeen + 1);
+    return fmtId(prefix, maxSeen + 1);
+}
+function nextSceneId(script) {
+    const ids = asList(script["episodes"]).flatMap((ep) => asList(ep["scenes"]).map((s) => s["scene_id"]));
+    return nextSeqId(ids, "scn");
+}
+function nextAssetId(script, kind) {
+    const [key, idKey] = assetKeys(kind);
+    return nextSeqId(asList(script[key]).map((item) => item[idKey]), ASSET_ID_PREFIX[kind]);
+}
+function nextEpisodeId(script) {
+    return nextSeqId(asList(script["episodes"]).map((ep) => ep["episode_id"]), "ep");
 }
 function sceneIdExists(script, sceneId) {
     for (const ep of asList(script["episodes"])) {
@@ -1481,6 +1534,53 @@ function sceneIdExists(script, sceneId) {
     }
     return false;
 }
+// Shared body for actor.add / location.add / prop.add: validate the name,
+// allocate or accept an id, reject duplicates, and append a minimal entity
+// ({id, name, description, states:[]}). The caller layers on kind-specific
+// fields (actor role_type/aliases). Returns the pushed entity so the caller can
+// extend it. description defaults to "" — an empty description is a completeness
+// warning, not a hard error, so you can register an asset now and describe it
+// later.
+function pushAsset(script, kind, op) {
+    const [collKey, idKey, nameKey] = assetKeys(kind);
+    const name = strOf(op["name"] ?? op[nameKey]).trim();
+    if (!name) {
+        throw opErr("SCRIPT OP BLOCKED: Asset name empty", "Asset name empty.", {
+            required: ["name"], received: [JSON.stringify(op)],
+            nextSteps: [`Provide a ${kind} name.`], op: `${kind}.add`, errorCode: "ASSET_NAME_EMPTY",
+        });
+    }
+    // name is already whitespace-trimmed; cleanName additionally strips trailing/
+    // leading punctuation (：，、…) and embedded 【】（） state annotations. Reuse the
+    // same errorCode validateScript uses for this rule (ASSET_NAME_HAS_STATE_ANNOTATION)
+    // so op-time and validate-time speak one vocabulary; the message stays accurate
+    // for the punctuation-only case too. Suggest the canonical form when there is one
+    // (a name that is entirely punctuation/annotation reduces to "").
+    const canonical = cleanName(name);
+    if (canonical !== name) {
+        const suggestion = canonical
+            ? `Use "${canonical}", and register durable looks with state-add instead of putting them in the name.`
+            : "Provide a real name (this one is only punctuation/annotation); register durable looks with state-add.";
+        throw opErr("SCRIPT OP BLOCKED: Asset name not canonical", "Asset name is not canonical (trailing/leading punctuation or an embedded state annotation).", {
+            required: [canonical ? `canonical name, e.g. "${canonical}"` : "a canonical name without punctuation/annotation"],
+            received: [name],
+            nextSteps: [suggestion], op: `${kind}.add`, errorCode: "ASSET_NAME_HAS_STATE_ANNOTATION",
+        });
+    }
+    const id = strOf(op[idKey] ?? op["id"]).trim() || nextAssetId(script, kind);
+    if (!isList(script[collKey]))
+        script[collKey] = [];
+    const coll = script[collKey];
+    if (coll.some((a) => strOf(a[idKey]) === id)) {
+        throw opErr("SCRIPT OP BLOCKED: Asset id exists", "Asset id exists.", {
+            required: ["unused id"], received: [id],
+            nextSteps: ["Use another --id or omit it to auto-allocate."], op: `${kind}.add`, errorCode: "ASSET_ID_EXISTS",
+        });
+    }
+    const entity = { [idKey]: id, [nameKey]: name, description: strOf(op["description"]).trim(), states: [] };
+    coll.push(entity);
+    return entity;
+}
 function renumberSceneIds(script) {
     let counter = 0;
     for (const ep of asList(script["episodes"])) {
@@ -1512,6 +1612,10 @@ export const PATCH_OP_SCHEMA = {
     "state.describe": { required: ["target", "description"], optional: [], description: "Set a state's description." },
     "state.delete": { required: ["target", "strategy"], optional: ["replacement"], description: "Delete a state. strategy: replace|remove." },
     // asset
+    "actor.add": { required: ["name"], optional: ["actor_id", "role_type", "description", "aliases"], description: "Register a new actor (human/character). role_type: 主角|配角." },
+    "location.add": { required: ["name"], optional: ["location_id", "description"], description: "Register a new location." },
+    "prop.add": { required: ["name"], optional: ["prop_id", "description"], description: "Register a new prop." },
+    "episode.add": { required: [], optional: ["episode_id", "title"], description: "Append a new empty episode (no scenes)." },
     "asset.rename": { required: ["target", "name"], optional: [], description: "Rename an asset (actor / location / prop)." },
     "asset.describe": { required: ["target", "description"], optional: [], description: "Set asset description." },
     "asset.alias.set": { required: ["target", "aliases"], optional: [], description: "Bulk replace aliases[]." },
@@ -1909,6 +2013,69 @@ export function applyPatchOperations(script, sourceText, operations) {
             delete action["speaker_id"];
             applied.push(kind);
         }
+        else if (kind === "actor.add") {
+            const name = strOf(op["name"] ?? op["actor_name"]).trim();
+            // Reject non-human speakers as actors up front (validate would flag
+            // NONHUMAN_AS_ACTOR otherwise) — system/broadcast/prop voices belong in
+            // speakers[], not actors[].
+            if (name && inferNonActorSpeakerKind(name) !== "actor") {
+                throw opErr("SCRIPT OP BLOCKED: Non-human as actor", "Non-human speaker registered as actor.", {
+                    required: ["a human/character name"], received: [name],
+                    nextSteps: ["Register non-human voices with add-speaker (kind system/broadcast/prop/group/other)."],
+                    op: kind, errorCode: "NONHUMAN_AS_ACTOR",
+                });
+            }
+            const entity = pushAsset(script, "actor", op);
+            const roleType = strOf(op["role_type"] ?? op["role"]).trim();
+            if (roleType) {
+                if (!ROLE_TYPE_VALUES.includes(roleType)) {
+                    throw opErr("SCRIPT OP BLOCKED: Role type invalid", "Role type invalid.", {
+                        required: ["role_type: 主角 or 配角"], received: [roleType],
+                        nextSteps: ["Use a supported actor role_type, or omit to leave it unset."],
+                        op: kind, errorCode: "ROLE_TYPE_INVALID",
+                    });
+                }
+                entity["role_type"] = roleType;
+            }
+            // Only stamp aliases when there's at least one — keeps the entity shape
+            // identical to direct/parse-produced actors (which omit the key when empty).
+            const aliases = isList(op["aliases"]) ? op["aliases"].map((a) => strOf(a).trim()).filter(Boolean) : [];
+            if (aliases.length)
+                entity["aliases"] = aliases;
+            applied.push(kind);
+        }
+        else if (kind === "location.add") {
+            pushAsset(script, "location", op);
+            applied.push(kind);
+        }
+        else if (kind === "prop.add") {
+            pushAsset(script, "prop", op);
+            applied.push(kind);
+        }
+        else if (kind === "episode.add") {
+            // Append an empty episode. Scenes/actions are added afterwards with
+            // scene.insert / action.insert. episode_id auto-allocates as ep_NNN.
+            const epId = strOf(op["episode_id"] ?? op["id"]).trim() || nextEpisodeId(script);
+            if (!/^ep_\d+$/.test(epId)) {
+                throw opErr("SCRIPT OP BLOCKED: Episode id invalid", "Episode id must use ep_NNN format.", {
+                    required: ["episode_id: ep_NNN"], received: [epId],
+                    nextSteps: ["Pass --id ep_004 or omit to auto-allocate."],
+                    op: kind, errorCode: "EPISODE_ID_INVALID",
+                });
+            }
+            if (!isList(script["episodes"]))
+                script["episodes"] = [];
+            const eps = script["episodes"];
+            if (eps.some((e) => strOf(e["episode_id"]) === epId)) {
+                throw opErr("SCRIPT OP BLOCKED: Episode id exists", "Episode id exists.", {
+                    required: ["unused episode_id"], received: [epId],
+                    nextSteps: ["Use another --id or omit it to auto-allocate."],
+                    op: kind, errorCode: "EPISODE_ID_EXISTS",
+                });
+            }
+            eps.push({ episode_id: epId, title: strOf(op["title"]).trim(), scenes: [] });
+            applied.push(kind);
+        }
         else if (kind === "meta.worldview.set") {
             // 0.6.0 dot-style equivalent of the legacy `set_worldview` op.
             const worldview = strOf(op["worldview"] ?? op["value"]).trim();