@patterkit/ops 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -142,10 +142,17 @@ declare function defaultGameScopesDir(root: string): string;
  * engine's, which is that engine's to declare). The project keeps its copy. When the walk-up from the
  * project would not find `dir`, the project names it (`gameScopes`), so it is found next time. Returns
  * the writes (the folder comes with the first), and the project as it should now be saved.
+ *
+ * A folder another tool already made is JOINED, never overwritten: an existing `game.scopes.json` keeps
+ * every scope it holds, and gains only the project's game scopes it doesn't declare yet (as the
+ * Storylet Engine's share adds `@world` only when the file has none). One that won't parse is an error,
+ * and nothing is written.
  */
 declare function planShareScopes(root: string, project: ProjectFile, dir: string): {
     writes: PlannedWrite[];
     project: ProjectFile;
+} | {
+    error: string;
 };
 
 interface LoadedProject {
@@ -921,6 +928,26 @@ interface ReplacePlan {
  */
 declare function runReplace(loaded: LoadedProject, opts: ReplaceOptions): ReplacePlan;
 
+/** One address written down. */
+interface PinnedName {
+    /** The node's immutable id. */
+    id: string;
+    kind: "scene" | "block";
+    /** The scene it belongs to (itself, for a scene). */
+    sceneId: string;
+    /** The address, now pinned: the same one it had while it followed the name. */
+    gameId: string;
+}
+interface PinPlan {
+    pinned: PinnedName[];
+    /** Flow-shard writes the caller commits through the VC layer (one per touched scene). */
+    writes: PlannedWrite[];
+    /** The rewritten scenes, index-aligned with `writes`. */
+    scenes: Scene[];
+}
+/** Plan pinning every scene and block address still following its name. */
+declare function planPins(loaded: LoadedProject): PinPlan;
+
 /** The source-shard extensions a document carries (the merge-friendly truth). */
 declare const SHARD_EXTENSIONS: readonly [".patterflow", ".patterloc", ".patterx", ".patterproj"];
 /** Manifest embedded at the document root - what this envelope is and contains. */
@@ -1087,4 +1114,4 @@ declare function classesForChannel(classes: DocumentationClass[], channel: strin
  */
 declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
 
-export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, GAME_SCOPES_OWNER, type GameScopes, type GameScopesIssue, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, extractLoc, findProjectFile, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, hostScopeTokens, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, patterScopesFile, patterScopesStale, patterScopesWrite, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, proposeCoverageDrivers, reachabilityIssues, readGameScopes, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };
+export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, GAME_SCOPES_OWNER, type GameScopes, type GameScopesIssue, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PinPlan, type PinnedName, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, extractLoc, findProjectFile, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, hostScopeTokens, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, patterScopesFile, patterScopesStale, patterScopesWrite, planPins, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, proposeCoverageDrivers, reachabilityIssues, readGameScopes, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };

package/dist/index.js

@@ -211,18 +211,23 @@ function defaultGameScopesDir(root) {
 }
 function planShareScopes(root, project, dir) {
   const target = resolve(dir);
-  const game = {
-    version: 1,
-    owner: GAME_SCOPES_OWNER,
-    scopes: (project.scopeRegistry?.scopes ?? []).filter((h) => isGameToken(h.token, void 0)).map((h) => ({
-      token: h.token,
-      ...h.writable !== void 0 ? { writable: h.writable } : {},
-      ...h.declarations ? { declarations: h.declarations.map((d) => ({ ...d })) } : {}
-    }))
-  };
+  const gamePath = join(target, GAME_SCOPES_FILE);
+  let existing = { version: 1, owner: GAME_SCOPES_OWNER, scopes: [] };
+  if (existsSync(gamePath)) {
+    const parsed = parseScopesFile(readFileSync(gamePath, "utf8"), GAME_SCOPES_FILE);
+    if (!parsed.file) return { error: `${GAME_SCOPES_FILE} in ${target} won't parse, so it was left alone: ${parsed.issues.map((i) => i.message).join("; ")}` };
+    existing = parsed.file;
+  }
+  const held = new Set(existing.scopes.map((s) => s.token));
+  const added = (project.scopeRegistry?.scopes ?? []).filter((h) => isGameToken(h.token, void 0) && !held.has(h.token)).map((h) => ({
+    token: h.token,
+    ...h.writable !== void 0 ? { writable: h.writable } : {},
+    ...h.declarations ? { declarations: h.declarations.map((d) => ({ ...d })) } : {}
+  }));
+  const game = { ...existing, scopes: [...existing.scopes, ...added] };
   const writes = [
     { path: join(target, PATTER_SCOPES_FILE), content: serialiseScopesFile(patterScopesFile(project)) },
-    { path: join(target, GAME_SCOPES_FILE), content: serialiseScopesFile(game) }
+    { path: gamePath, content: serialiseScopesFile(game) }
   ];
   let found = false;
   for (let at = resolve(root); ; ) {
@@ -3872,18 +3877,54 @@ function runReplace(loaded, opts) {
   return plan;
 }
 
+// src/pin.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { canonicalStringify as canonicalStringify8, parseSource as parseSource4 } from "@patterkit/core";
+import { effectiveGameId as effectiveGameId2, gameIdify } from "@patterkit/model";
+function toPin(node) {
+  if (node.gameId?.trim()) return void 0;
+  if (!gameIdify(node.name)) return void 0;
+  return effectiveGameId2(node);
+}
+function planPins(loaded) {
+  const plan = { pinned: [], writes: [], scenes: [] };
+  for (const scene of loaded.scenes) {
+    const path = loaded.sceneFiles[scene.id];
+    if (!path) continue;
+    let changed = false;
+    const sceneGameId = toPin(scene);
+    if (sceneGameId !== void 0) {
+      plan.pinned.push({ id: scene.id, kind: "scene", sceneId: scene.id, gameId: sceneGameId });
+      changed = true;
+    }
+    const blocks = scene.blocks.map((block) => {
+      const gameId = toPin(block);
+      if (gameId === void 0) return block;
+      plan.pinned.push({ id: block.id, kind: "block", sceneId: scene.id, gameId });
+      changed = true;
+      return { ...block, gameId };
+    });
+    if (!changed) continue;
+    const next = { ...scene, ...sceneGameId !== void 0 ? { gameId: sceneGameId } : {}, blocks };
+    const file = parseSource4(readFileSync5(path, "utf8"));
+    plan.writes.push({ path, content: canonicalStringify8({ ...file, scene: next }) });
+    plan.scenes.push(next);
+  }
+  return plan;
+}
+
 // src/pack.ts
 import JSZip from "jszip";
-import { readFileSync as readFileSync5 } from "fs";
+import { readFileSync as readFileSync6 } from "fs";
 import { dirname as dirname5, relative as relative3, sep as sep2 } from "path";
-import { parseSource as parseSource4 } from "@patterkit/core";
+import { parseSource as parseSource5 } from "@patterkit/core";
 import { ARCHIVE_ENTRY_OPTS } from "@wildwinter/toolkit/archive";
 var SHARD_EXTENSIONS = [".patterflow", ".patterloc", ".patterx", ".patterproj"];
 var ENTRY_OPTS = ARCHIVE_ENTRY_OPTS;
 async function runPack(startPath) {
   const projectFile = findProjectFile(startPath);
   const root = dirname5(projectFile);
-  const project = parseSource4(readFileSync5(projectFile, "utf8"));
+  const project = parseSource5(readFileSync6(projectFile, "utf8"));
   const unresolved = sidecarIssues(walkFiles(root, CONFLICT_SIDECAR));
   if (unresolved.length) {
     throw new Error(
@@ -3901,7 +3942,7 @@ async function runPack(startPath) {
   };
   const zip = new JSZip();
   zip.file("patter.manifest.json", JSON.stringify(manifest, null, 2) + "\n", ENTRY_OPTS);
-  for (const f of files) zip.file(f.rel, readFileSync5(f.abs, "utf8"), ENTRY_OPTS);
+  for (const f of files) zip.file(f.rel, readFileSync6(f.abs, "utf8"), ENTRY_OPTS);
   for (const f of scopes) zip.file(`${GAME_SCOPES_DIR}/${f.fileName}`, f.text, ENTRY_OPTS);
   return zip.generateAsync({ type: "nodebuffer", compression: "DEFLATE", streamFiles: false });
 }
@@ -3909,8 +3950,8 @@ async function runPack(startPath) {
 // src/unpack.ts
 import JSZip2 from "jszip";
 import { join as join7, resolve as resolve5, sep as sep3 } from "path";
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
-import { parseSource as parseSource5, canonicalStringify as canonicalStringify8 } from "@patterkit/core";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
+import { parseSource as parseSource6, canonicalStringify as canonicalStringify9 } from "@patterkit/core";
 import { isUnsafeEntry } from "@wildwinter/toolkit/archive";
 import { SCOPES_FILE_SUFFIX as SCOPES_FILE_SUFFIX2 } from "@wildwinter/scoperegistry/scopes";
 import { isUnsafeEntry as isUnsafeEntry2 } from "@wildwinter/toolkit/archive";
@@ -3956,7 +3997,7 @@ function checkProvenance(returned, base, target) {
 }
 function targetProjectId(projectDir) {
   try {
-    const pf = parseSource5(readFileSync6(findProjectFile(projectDir), "utf8"));
+    const pf = parseSource6(readFileSync7(findProjectFile(projectDir), "utf8"));
     return pf.project?.id;
   } catch {
     return void 0;
@@ -3983,17 +4024,17 @@ async function runUnpackMerge(returnedBytes, baseBytes, projectDir) {
     }
     const readSide = (side, text) => {
       try {
-        return parseSource5(text);
+        return parseSource6(text);
       } catch (e) {
         throw new Error(`${rel}: the ${side} copy is not readable Patter source - ${e instanceof Error ? e.message : String(e)}`);
       }
     };
-    const oursObj = readSide("ours", readFileSync6(outPath, "utf8"));
+    const oursObj = readSide("ours", readFileSync7(outPath, "utf8"));
     const theirsObj = readSide("theirs", theirText);
     const baseText = base.get(rel);
     const baseObj = baseText !== void 0 ? readSide("base", baseText) : {};
     const result = runMerge(baseObj, oursObj, theirsObj);
-    writes.push({ path: outPath, content: canonicalStringify8(result.merged) });
+    writes.push({ path: outPath, content: canonicalStringify9(result.merged) });
     if (rel === projectRel && baseText !== void 0) {
       projectSides = { ours: oursObj, base: baseObj, theirs: theirsObj, merged: result.merged };
     }
@@ -4064,6 +4105,7 @@ export {
   patterScopesFile,
   patterScopesStale,
   patterScopesWrite,
+  planPins,
   planReturnedWorld,
   planShareScopes,
   planWorldSave,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/ops",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "The shared operations layer: every project operation (load, validate, export, format, play, ...) as a pure function, consumed by the patter CLI and Patterpad alike.",
   "type": "module",
   "license": "MIT",