@lingjingai/scriptctl 0.62.0 → 0.62.1

package/changes/0.62.1.md

@@ -0,0 +1,15 @@
+# 0.62.1
+
+## Added
+- `scriptctl refs` and `sc refs` locate asset and appearance references with scene/action addresses, surrounding text, and pagination. Explicit scene bindings, speakers, and textual mentions are reported separately; mentions do not imply presence or a particular appearance.
+- The screenplay SDK exports read-only `references` and `formatReferences`, shared by the CLI and review agents.
+- The Mastra screenplay review agent exposes `refs` during both episode review and whole-series convergence, querying the current in-memory document after edits.
+
+## Changed
+- Review instructions and the packaged scriptctl skill document reference lookup and distinguish read-only `refs` from the binding mutation `ref`.
+
+## Fixed
+- None.
+
+## Breaking
+- None.

package/dist/bin.js

@@ -4552,6 +4552,67 @@ function spanAddresses(doc2, actions) {
   });
 }
 
+// packages/screenplay/dist/references.js
+function references(doc2, address, opts = {}) {
+  const offset = opts.offset ?? 0, limit = opts.limit ?? 20, context = opts.context ?? 3;
+  for (const [name, value, minimum] of [["offset", offset, 0], ["limit", limit, 1], ["context", context, 0]]) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+      throw new Error(`${name} must be an integer >= ${minimum}`);
+  }
+  const node = resolve6(doc2, address);
+  if (node.t !== "asset" && node.t !== "state")
+    throw new Error("references requires an asset or asset/state address; use read for episodes/scenes/actions");
+  const asset2 = node.asset;
+  const state2 = node.t === "state" ? node.state.id : null;
+  const names = [.../* @__PURE__ */ new Set([asset2.id, asset2.name, ...asset2.aliases])].filter(Boolean);
+  const hits = [];
+  for (const ep of doc2.episodes)
+    for (const scene of ep.scenes) {
+      const bindings = [...scene.location ? [scene.location] : [], ...scene.actors, ...scene.props].filter((ref2) => ref2.id === asset2.id && (state2 === null || ref2.states.includes(state2)));
+      if (bindings.length)
+        hits.push({ kind: "scene_binding", scene, matched: bindings.flatMap((ref2) => ref2.states) });
+      for (const action of scene.actions) {
+        if (action.speaker?.id === asset2.id && (state2 === null || action.speaker.state === state2)) {
+          hits.push({ kind: "speaker", scene, action, matched: [asset2.id] });
+        }
+        if (state2 === null) {
+          const matched = names.filter((name) => action.content.includes(name));
+          if (matched.length)
+            hits.push({ kind: "text_mention", scene, action, matched });
+        }
+      }
+    }
+  const end = offset + limit;
+  return {
+    asset_id: asset2.id,
+    state_id: state2,
+    total: hits.length,
+    next_offset: end < hits.length ? end : null,
+    items: hits.slice(offset, end).map(({ kind, scene, action, matched }) => {
+      const index = action ? scene.actions.indexOf(action) : -1;
+      const nearby = action ? scene.actions.slice(Math.max(0, index - context), index + context + 1) : [];
+      const gutter = Math.max(0, ...nearby.map((row) => row.anchor.length));
+      return {
+        kind,
+        address: action?.anchor ?? scene.anchor,
+        scene_address: scene.anchor,
+        episode: scene.ep.no,
+        matched,
+        text: [formatSceneHead(doc2, scene), ...nearby.map((row) => (row === action ? "> " : "  ") + formatAction(doc2, row, gutter))].join("\n")
+      };
+    })
+  };
+}
+function formatReferences(result) {
+  return [
+    `${result.asset_id}${result.state_id === null ? "" : "/" + result.state_id}  ${result.total} references \xB7 showing ${result.items.length}`,
+    "scene_binding=explicit scene presence; speaker=explicit speaker; text_mention=name/alias mention only (not proof of presence).",
+    ...result.items.map((hit) => `${hit.address}  ${hit.kind}  ep=${hit.episode}
+${hit.text}`),
+    result.next_offset === null ? "end" : `Continue: --offset ${result.next_offset}`
+  ].join("\n\n");
+}
+
 // packages/screenplay/dist/tools.js
 var NON_ACTOR_NAMES = ["\u65C1\u767D", "\u5E7F\u64AD", "\u753B\u5916", "\u7FA4\u58F0"];
 var NON_ACTOR_KIND = {
@@ -5679,6 +5740,15 @@ ${issues(d, {})}`
     ...opts["full"] ? { full: true } : {}
   }), "find"), state2));
   describeArguments(find2, ["\u6B63\u5219\uFF1B\u53EA\u6309 speaker/type \u8FC7\u6EE4\u65F6\u53EF\u7701\u7565"]);
+  const refs = withScriptOpts(program.command("refs <addr>"), "read").description("\u53EA\u8BFB\u5B9A\u4F4D\u8D44\u4EA7/\u9020\u578B\u7684\u573A\u666F\u7ED1\u5B9A\u3001\u8BF4\u8BDD\u5F15\u7528\u548C\u6B63\u6587\u63D0\u53CA\uFF0C\u8FD4\u56DE\u53EF read \u7684\u5730\u5740\u53CA\u4E0A\u4E0B\u6587").option("--offset <n>", "\u4ECE\u7B2C\u51E0\u6761\u5F15\u7528\u7EE7\u7EED\uFF08\u4ECE 0 \u5F00\u59CB\uFF09").option("--limit <n>", "\u672C\u6279\u5F15\u7528\u6570\uFF08\u9ED8\u8BA4 20\uFF09").option("--context <n>", "\u6B63\u6587\u547D\u4E2D\u524D\u540E\u5404\u51E0\u6761 action\uFF08\u9ED8\u8BA4 3\uFF09").action(dispatch((opts) => {
+    const result = references(doc(opts), arg(opts), {
+      offset: num(opts, "offset"),
+      limit: num(opts, "limit"),
+      context: num(opts, "context")
+    });
+    return [{ text: formatReferences(result), data: { op: "refs", changed: false, ...result } }, EXIT_OK];
+  }, state2));
+  describeArguments(refs, ["\u4EBA\u7269/\u573A\u666F/\u9053\u5177 ID \u6216\u540D\u79F0\uFF0C\u6216 <\u8D44\u4EA7>/<\u9020\u578B>\uFF1B\u6B63\u6587\u63D0\u53CA\u4E0D\u7B49\u4E8E\u5B9E\u9645\u51FA\u573A"]);
   const span2 = withScriptOpts(program.command("span <range>"), "read").description("\u628A\u4E00\u6BB5 action \u6362\u7B97\u6210\u96C6\u5185\u89C6\u9891\u65F6\u95F4\u7A97\u53E3\uFF08\u534A\u5F00\u533A\u95F4\uFF09").action(dispatch((opts) => text(() => span(doc(opts), arg(opts)), "span"), state2));
   describeArguments(span2, [`${ADDR}\uFF0C\u6216 \`\u8D77ID..\u6B62ID\``]);
   withScriptOpts(program.command("validate"), "read").description("\u8DD1\u6574\u672C\u6821\u9A8C").action(dispatch((opts) => text(() => validate(doc(opts)), "validate"), state2));