@ssobig/writer-cli 0.2.0

package/tools/writer-cli/src/platform-runner.cjs

@@ -0,0 +1,55 @@
+"use strict";
+
+const { cliError } = require("./errors.cjs");
+const { effectiveCacheDir, requestDaemon } = require("./daemon-runner.cjs");
+const { resolveAgentPaths } = require("./agent-paths.cjs");
+
+const IN_PROCESS_METHODS = Object.freeze({
+  "writer.sync": "sync",
+  "writer.search": "search",
+  "writer.read": "read",
+  "writer.get": "get",
+  "writer.plan_replace": "planReplace",
+  "writer.apply": "apply",
+  "writer.purge": "purge",
+  "writer.logout": "logout"
+});
+
+async function requestInProcess(method, params = {}, options = {}) {
+  const serviceMethod = IN_PROCESS_METHODS[String(method || "")];
+  if (!serviceMethod) throw cliError("E_DAEMON_METHOD", `Windows in-process backend가 지원하지 않는 method입니다: ${String(method || "")}`);
+  const platform = String(options.platform || process.platform);
+  const environment = options.environment || process.env;
+  const paths = resolveAgentPaths({
+    cacheDir: effectiveCacheDir(options, environment),
+    platform,
+    environment,
+    homeDirectory: options.homeDirectory
+  });
+  const serviceFactory = options.serviceFactory || (serviceOptions => require("./agent-service.cjs").createAgentService(serviceOptions));
+  const service = serviceFactory({
+    platform,
+    cacheDir: paths.cacheDir,
+    environment,
+    homeDirectory: options.homeDirectory,
+    fs: options.fs,
+    auth: options.auth,
+    authOptions: options.authOptions,
+    gatewayFactory: options.gatewayFactory,
+    indexFactory: options.indexFactory,
+    realtime: options.realtime
+  });
+  try {
+    return await service.handle(serviceMethod, params);
+  } finally {
+    await service.close();
+  }
+}
+
+function requestWriterService(method, params = {}, options = {}) {
+  return String(options.platform || process.platform) === "win32"
+    ? requestInProcess(method, params, options)
+    : requestDaemon(method, params, options);
+}
+
+module.exports = Object.freeze({ IN_PROCESS_METHODS, requestInProcess, requestWriterService });

package/tools/writer-cli/src/project-import.cjs

@@ -0,0 +1,485 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const catalogContract = require("../../../templates/mystery-v1/component-catalog-contract.js");
+const componentContract = require("../../../templates/mystery-v1/component-storage-contract.js");
+const viewContract = require("../../../templates/mystery-v1/view-component-contract.js");
+const { inspectAssetFile } = require("./asset-policy.cjs");
+const { clone, equalJson, sha256 } = require("./json.cjs");
+const { cliError } = require("./errors.cjs");
+
+const IMPORT_SOURCE_FORMAT = "true-writer-case-v1";
+const IMPORT_PROFILE = catalogContract.IMPORT_PROFILE;
+const CAPABILITIES = Object.freeze({ viewSelection: Object.freeze({ authoring: "json", preview: "raw", design: "theme", validation: "schema" }) });
+const IMPORT_VIEW_LABELS = Object.freeze({ "ssobig.ai-response": "AI 응답 작업 화면" });
+
+const IMPORT_DESCRIPTORS = catalogContract.forImportProfile(IMPORT_PROFILE)
+  .sort((left, right) => Number(right.required) - Number(left.required));
+const COMPONENT_BLUEPRINTS = Object.freeze(IMPORT_DESCRIPTORS.map(descriptor => blueprint(
+  descriptor.defaultInstanceId,
+  descriptor.templateId,
+  descriptor.tabLabel,
+  descriptor.required,
+  { internal: descriptor.internal }
+)));
+const VIEW_BLUEPRINTS = Object.freeze(IMPORT_DESCRIPTORS.filter(descriptor => descriptor.view).map(descriptor => view(
+  descriptor.view.instanceId,
+  descriptor.view.templateId,
+  IMPORT_VIEW_LABELS[descriptor.templateId] || descriptor.view.label,
+  descriptor.view.rendererId,
+  descriptor.defaultInstanceId,
+  descriptor.view.bindings.map(item => ({
+    key: item.key,
+    data: catalogContract.get(item.dataTemplateId).defaultInstanceId,
+    mode: item.accessMode,
+    required: item.required
+  }))
+)));
+
+const CHARACTER_IDS = Object.freeze({
+  "강공정": "kang-gongjeong",
+  "윤스타": "yoon-star",
+  "박근성": "park-geunseong",
+  "김PD": "kim-pd"
+});
+const CHARACTER_COLORS = Object.freeze({
+  "kang-gongjeong": "#497fa8",
+  "yoon-star": "#8068a8",
+  "park-geunseong": "#5f8f62",
+  "kim-pd": "#a86b49"
+});
+const CASE_DOCUMENTS = Object.freeze([
+  "00-overview.md", "01-truth.md", "02-characters.md", "03-timeline.md",
+  "04-clues.md", "05-ssobig-flow.md", "06-host-guide.md", "07-playtest-report.md"
+]);
+const ASSET_FILES = Object.freeze({
+  "background-main.webp": "workspace-background",
+  "cover.webp": "poster",
+  "logo.webp": "logo",
+  "role-kang-gongjeong.webp": "character-kang-gongjeong",
+  "role-yoon-star.webp": "character-yoon-star",
+  "role-park-geunseong.webp": "character-park-geunseong",
+  "role-kim-pd.webp": "character-kim-pd",
+  "share.webp": "share"
+});
+
+function blueprint(instanceId, templateId, tabLabel, required = false, options = {}) {
+  return Object.freeze({ instanceId, templateId, tabLabel, required, internal: options.internal === true });
+}
+
+function view(instanceId, templateId, label, rendererId, primaryData, bindings = null) {
+  return Object.freeze({
+    instanceId,
+    templateId,
+    label,
+    rendererId,
+    primaryData,
+    bindings: Object.freeze(bindings || [{ key: "primary", data: primaryData, mode: "read_write", required: true }])
+  });
+}
+
+function isObject(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }
+
+function readRequired(filePath, label, fsApi = fs) {
+  try { return fsApi.readFileSync(filePath); }
+  catch (error) { throw cliError("E_FILE_NOT_FOUND", `${label} 파일을 읽을 수 없습니다: ${filePath}`, null, error); }
+}
+
+function readText(filePath, label, fsApi = fs) { return readRequired(filePath, label, fsApi).toString("utf8"); }
+
+function parseJson(filePath, label, fsApi = fs) {
+  const source = readText(filePath, label, fsApi);
+  try { return JSON.parse(source); }
+  catch (error) { throw cliError("E_INVALID_JSON", `${label} 파일이 올바른 JSON이 아닙니다: ${filePath}`, null, error); }
+}
+
+function snapshotFile(root, filePath, kind, fsApi = fs) {
+  const buffer = readRequired(filePath, kind, fsApi);
+  const relativePath = path.relative(root, filePath).split(path.sep).join("/");
+  if (!relativePath || relativePath.startsWith("../") || path.isAbsolute(relativePath)) throw cliError("E_VALIDATION", `원본 파일이 case root 밖에 있습니다: ${filePath}`);
+  return Object.freeze({ path: path.resolve(filePath), relativePath, kind, size: buffer.length, contentHash: sha256(buffer) });
+}
+
+function text(value) { return typeof value === "string" ? value : value == null ? "" : JSON.stringify(value, null, 2); }
+
+function markdownSections(source) {
+  const sections = [];
+  let current = null;
+  for (const line of String(source || "").split(/\r?\n/)) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      current = { title: heading[1], lines: [] };
+      sections.push(current);
+    } else if (current) current.lines.push(line);
+  }
+  return sections;
+}
+
+function parseTimeline(source) {
+  const events = [];
+  for (const section of markdownSections(source)) {
+    if (!/사건 전|사건 당일/.test(section.title)) continue;
+    for (const line of section.lines) {
+      if (!/^\|/.test(line) || /^\|\s*(?:시간|---)/.test(line)) continue;
+      const cells = line.split("|").slice(1, -1).map(cell => cell.trim());
+      if (cells.length < 4 || cells.every(cell => /^-+$/.test(cell))) continue;
+      const memories = {};
+      for (const [name, characterId] of Object.entries(CHARACTER_IDS)) {
+        if (cells[2].includes(name)) memories[characterId] = { included: true, text: cells[3] };
+      }
+      events.push({
+        id: crypto.randomUUID(),
+        time: cells[0],
+        location: section.title,
+        truth: cells[1],
+        memories
+      });
+    }
+  }
+  if (!events.length) throw cliError("E_VALIDATION", "03-timeline.md에서 사건 타임라인 표를 찾지 못했습니다.");
+  return events;
+}
+
+function characterComponent(characterSource) {
+  const characters = {};
+  const names = {};
+  const order = [];
+  for (const [name, characterId] of Object.entries(CHARACTER_IDS)) {
+    const source = characterSource?.[name];
+    if (!isObject(source)) throw cliError("E_VALIDATION", `캐릭터 원본을 찾을 수 없습니다: ${name}`);
+    order.push(characterId);
+    names[characterId] = name;
+    const customSections = [
+      { title: "자기소개", body: text(source["자기소개"]) },
+      { title: "개별 서사", body: text(source["서사1"]) },
+      { title: "인물 목표", body: [text(source["목적1"]), text(source["목적2"])].filter(Boolean).join("\n\n") },
+      { title: "추가 서사", body: text(source["서사2"]) },
+      { title: "기억", body: text(source["기억"]) },
+      { title: "관계도", body: text(source["관계도"]) }
+    ].filter(section => section.body.trim()).map(section => ({ id: crypto.randomUUID(), ...section }));
+    characters[characterId] = {
+      isPlayable: true,
+      tag: "플레이어 캐릭터",
+      color: CHARACTER_COLORS[characterId],
+      customSections,
+      containers: [{ id: crypto.randomUUID(), role: "primary", title: "기본 정보", sectionIds: customSections.map(section => section.id) }],
+      authorNote: ""
+    };
+  }
+  return {
+    characters, names, order, customCharacters: [], deletedColumns: [],
+    enabledOptionalFields: ["image", "color", "tag", "authorNote"]
+  };
+}
+
+function progressComponent(flowSource) {
+  if (!isObject(flowSource) || !Object.keys(flowSource).length) throw cliError("E_VALIDATION", "진행 원본이 비어 있습니다.");
+  return {
+    steps: Object.entries(flowSource).map(([name, item], index) => {
+      const source = isObject(item) ? item : {};
+      const actions = [
+        source.guide && `진행 안내\n${source.guide}`,
+        source.rule && `규칙\n${source.rule}`,
+        source.notice && `주의\n${source.notice}`
+      ].filter(Boolean).join("\n\n");
+      return {
+        id: crypto.randomUUID(),
+        name,
+        time: "",
+        description: [text(source.script), text(source.script_19)].filter(Boolean).join("\n\n"),
+        actions
+      };
+    })
+  };
+}
+
+function cluesComponent(resourceSource, writerNote) {
+  if (!isObject(resourceSource)) throw cliError("E_VALIDATION", "단서 resource 원본이 객체가 아닙니다.");
+  const clues = [];
+  Object.entries(resourceSource).forEach(([sourceId, item]) => {
+    const source = isObject(item) ? item : {};
+    const name = text(source.title) || sourceId;
+    clues.push({
+      id: crypto.randomUUID(),
+      name,
+      title: name,
+      location: source.verification === undefined ? "1차 조사" : "2차 조사",
+      description: text(source.content),
+      secret: text(source.verification),
+      tags: [source.verification === undefined ? "자료" : "제보"],
+      color: source.verification === undefined ? "#497fa8" : "#a86b49",
+      confirmed: true,
+      sourceId
+    });
+  });
+  return {
+    clues,
+    enabledOptionalFields: ["confirmed", "image", "location", "tags", "color", "secret"],
+    writerNote
+  };
+}
+
+function firstNonEmpty(...values) {
+  return values.map(text).find(value => value.trim()) || "";
+}
+
+function addEndingPair(conditions, outcomes, code, value, fallbackCondition = "") {
+  const source = isObject(value) ? value : {};
+  const body = isObject(value) ? firstNonEmpty(source.body, source.description, source.text) : text(value);
+  const title = isObject(value) ? text(source.title) || code : code;
+  const condition = isObject(value) ? text(source.condition_text ?? source.condition) : fallbackCondition;
+  const id = crypto.randomUUID();
+  conditions.push({ id, code, condition });
+  outcomes.push({ id, title, body, customSections: [] });
+}
+
+function endingComponent(endingSource) {
+  if (!isObject(endingSource)) throw cliError("E_VALIDATION", "엔딩 원본이 객체가 아닙니다.");
+  const conditions = [];
+  const outcomes = [];
+  for (const [id, value] of Object.entries(endingSource)) {
+    if (id === "character" && isObject(value)) {
+      for (const [name, variants] of Object.entries(value)) {
+        const characterId = CHARACTER_IDS[name] || `character-${conditions.length + 1}`;
+        for (const [variant, outcome] of Object.entries(isObject(variants) ? variants : {})) {
+          addEndingPair(conditions, outcomes, `${characterId}-${variant}`, outcome, `${name}의 ${variant} 조건`);
+        }
+      }
+    } else if (id === "program" && isObject(value)) {
+      for (const [variant, outcome] of Object.entries(value)) addEndingPair(conditions, outcomes, `program-${variant}`, outcome);
+    } else addEndingPair(conditions, outcomes, id, value);
+  }
+  return { conditions, outcomes };
+}
+
+function component(instanceId, data) {
+  const blueprintValue = COMPONENT_BLUEPRINTS.find(item => item.instanceId === instanceId);
+  if (!blueprintValue) throw cliError("E_CONFIGURATION", `Import Component blueprint가 없습니다: ${instanceId}`);
+  return { instanceId, templateId: blueprintValue.templateId, data };
+}
+
+function normalizeImportComponents(input) {
+  if (!Array.isArray(input)) throw cliError("E_VALIDATION", "Import components는 배열이어야 합니다.");
+  const seenIds = new Set();
+  const seenTemplates = new Set();
+  const output = input.map(value => {
+    if (!isObject(value)) throw cliError("E_VALIDATION", "Import Component 항목은 객체여야 합니다.");
+    const instanceId = String(value.instanceId || "");
+    const blueprintValue = COMPONENT_BLUEPRINTS.find(item => item.instanceId === instanceId);
+    if (!blueprintValue
+      || String(value.templateId || "") !== blueprintValue.templateId
+      || !isObject(value.data)) {
+      throw cliError("E_VALIDATION", `Import Component identity 또는 data가 올바르지 않습니다: ${instanceId || "(비어 있음)"}`);
+    }
+    if (seenIds.has(instanceId) || seenTemplates.has(blueprintValue.templateId)) throw cliError("E_VALIDATION", `Import Component가 중복되었습니다: ${instanceId}`);
+    seenIds.add(instanceId);
+    seenTemplates.add(blueprintValue.templateId);
+    const spec = componentContract.componentSpec(blueprintValue.templateId);
+    const invalid = spec?.validate(value.data);
+    if (!spec || invalid) throw cliError("E_VALIDATION", invalid || `지원되지 않는 Component입니다: ${blueprintValue.templateId}`);
+    return Object.freeze({ instanceId, templateId: blueprintValue.templateId, data: clone(value.data) });
+  });
+  for (const required of COMPONENT_BLUEPRINTS.filter(item => item.required)) {
+    if (!seenIds.has(required.instanceId)) throw cliError("E_VALIDATION", `필수 Import Component가 없습니다: ${required.instanceId}`);
+  }
+  return Object.freeze(output);
+}
+
+function importCompositionRows(components, projectId = "11111111-1111-4111-8111-111111111111") {
+  const normalized = normalizeImportComponents(components);
+  const byId = new Map(normalized.map(item => [item.instanceId, item]));
+  const activeBlueprints = COMPONENT_BLUEPRINTS.filter(item => byId.has(item.instanceId));
+  const componentRows = activeBlueprints.map((definition, order) => ({
+    project_id: projectId,
+    version_number: 1,
+    instance_id: definition.instanceId,
+    template_id: definition.templateId,
+    tab_label: definition.tabLabel,
+    sort_order: order,
+    is_enabled: true,
+    is_archived: false,
+    is_required: definition.required,
+    is_removable: !definition.required,
+    editor_view_id: "json",
+    preview_view_id: "raw",
+    capabilities: clone(CAPABILITIES),
+    config: definition.internal ? { hidden: true } : {},
+    data: clone(byId.get(definition.instanceId).data),
+    revision: 1
+  }));
+  const enabledViews = VIEW_BLUEPRINTS.filter(definition => byId.has(definition.primaryData));
+  const viewRows = enabledViews.map((definition, order) => ({
+    view_instance_id: definition.instanceId,
+    view_template_id: definition.templateId,
+    label: definition.label,
+    description: "",
+    renderer_id: definition.rendererId,
+    supported_modes: ["authoring", "preview"],
+    sort_order: order,
+    is_enabled: true,
+    config: {},
+    revision: 1
+  }));
+  const bindingRows = enabledViews.flatMap(definition => definition.bindings
+    .filter(binding => byId.has(binding.data) && (binding.required || byId.has(binding.data)))
+    .map((binding, order) => ({
+      view_instance_id: definition.instanceId,
+      binding_key: binding.key,
+      data_instance_id: binding.data,
+      access_mode: binding.mode,
+      is_required: binding.required,
+      sort_order: order
+    })));
+  const set = { project_id: projectId, version_number: 1, revision: 1, canonical_status: "active", component_checksum: "sha256:import-plan" };
+  const composition = componentContract.validateActiveComposition(set, componentRows);
+  if (!composition.ok) throw cliError("E_VALIDATION", composition.error.message, null, composition.error);
+  const views = viewContract.validateProjectViews(viewRows, bindingRows, composition.instances);
+  if (!views.ok) throw cliError("E_VALIDATION", views.error.message, null, views.error);
+  return Object.freeze({ components: normalized, componentRows, viewRows, bindingRows, instances: composition.instances, views: views.views });
+}
+
+function loadTrueWriterCase(input, options = {}) {
+  const fsApi = options.fs || fs;
+  const root = path.resolve(String(input.sourceRoot || ""));
+  const sourceJsonPath = path.resolve(String(input.sourceJson || ""));
+  if (!root || !sourceJsonPath) throw cliError("E_USAGE", "--source-root와 --source-json이 필요합니다.");
+  const docs = Object.fromEntries(CASE_DOCUMENTS.map(name => [name, readText(path.join(root, name), name, fsApi)]));
+  const source = parseJson(sourceJsonPath, "SsoBig source", fsApi);
+  const jsonData = source?.customParam?.jsonData;
+  if (!isObject(jsonData?.game_set) || !isObject(jsonData.resource)) throw cliError("E_VALIDATION", "SsoBig source에 game_set/resource가 없습니다.");
+  const game = isObject(source.game) ? source.game : {};
+  const title = String(input.title || game.title || jsonData.game_set.game_name || "").trim();
+  if (!title) throw cliError("E_VALIDATION", "작품명을 확인할 수 없습니다.");
+
+  const overviewIntro = markdownSections(docs["00-overview.md"]).find(section => section.title === "한 문장 소개")?.lines.join("\n").trim() || "";
+  const progress = progressComponent(jsonData.game_set.flow);
+  const ending = endingComponent(jsonData.game_set.ending);
+  const timelineEvents = parseTimeline(docs["03-timeline.md"]);
+  const resources = Object.keys(jsonData.resource).length;
+  const components = normalizeImportComponents([
+    component("basic", {
+      title,
+      intro: overviewIntro,
+      detail: docs["00-overview.md"],
+      minPlayers: Number(game.maxPlayerCount || 4),
+      maxPlayers: Number(game.maxPlayerCount || 4),
+      brandColor: "#7a4f64",
+      backgroundColor: "#f4f0f2",
+      theme: "light",
+      font: String(game.fontFamily || "Noto Sans KR")
+    }),
+    component("progress", progress),
+    component("common", {
+      sections: {
+        overview: docs["00-overview.md"],
+        prologue: text(jsonData.game_set.flow?.["00 - 프롤로그"]?.script)
+      },
+      customSections: [],
+      sectionOrder: ["overview", "prologue"],
+      baseTitles: { overview: "작품 개요", prologue: "프롤로그" },
+      deletedBaseSections: []
+    }),
+    component("characters", characterComponent(jsonData.game_set.character)),
+    component("assets", { assets: {} }),
+    component("clues", cluesComponent(jsonData.resource, docs["04-clues.md"])),
+    component("timeline", { events: timelineEvents }),
+    component("ending", ending),
+    component("postgame", {
+      truth: [{ id: crypto.randomUUID(), title: "사건의 진실", body: docs["01-truth.md"] }],
+      epilogue: [{ id: crypto.randomUUID(), title: "에필로그", body: text(jsonData.game_set.flow?.["14 - 에필로그"]?.script) }],
+      intro: { truth: "디자이너 전용 정답 및 사건의 전말", epilogue: "게임 종료 후 공개 문서" }
+    }),
+    component("author-notes", {
+      notes: [
+        ["character-design", "캐릭터 설계 원문", docs["02-characters.md"]],
+        ["timeline-design", "타임라인 설계 원문", docs["03-timeline.md"]],
+        ["flow-design", "게임 진행 설계 원문", docs["05-ssobig-flow.md"]],
+        ["host-guide", "호스트 가이드", docs["06-host-guide.md"]],
+        ["playtest-report", "플레이테스트 보고서", docs["07-playtest-report.md"]]
+      ].map(([, noteTitle, body]) => ({ id: crypto.randomUUID(), title: noteTitle, body }))
+    })
+  ]);
+  importCompositionRows(components);
+
+  const documentPaths = CASE_DOCUMENTS.map(name => path.join(root, name));
+  const assetFiles = [];
+  for (const [name, assetId] of Object.entries(ASSET_FILES)) {
+    const filePath = path.join(root, "assets", name);
+    const inspected = inspectAssetFile(filePath, assetId, { fs: fsApi });
+    assetFiles.push({ assetId, path: inspected.path, name: inspected.name, type: inspected.type, extension: inspected.extension, size: inspected.size, contentHash: inspected.contentHash });
+  }
+  const sourceAsset = inspectAssetFile(sourceJsonPath, "source-runtime-json", { fs: fsApi });
+  assetFiles.push({ assetId: "source-runtime-json", path: sourceAsset.path, name: sourceAsset.name, type: sourceAsset.type, extension: sourceAsset.extension, size: sourceAsset.size, contentHash: sourceAsset.contentHash });
+  const sourceFiles = [
+    ...documentPaths.map(filePath => snapshotFile(root, filePath, "canonical-document", fsApi)),
+    snapshotFile(root, sourceJsonPath, "runtime-json", fsApi),
+    ...assetFiles.filter(item => item.assetId !== "source-runtime-json").map(item => snapshotFile(root, item.path, "asset", fsApi))
+  ].sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+  const sourceHash = sha256(sourceFiles.map(item => ({ relativePath: item.relativePath, contentHash: item.contentHash, size: item.size })));
+  const coverage = Object.freeze({
+    canonicalDocuments: CASE_DOCUMENTS.length,
+    characters: Object.keys(jsonData.game_set.character || {}).length,
+    progressSteps: progress.steps.length,
+    resources,
+    endingGroups: Object.keys(jsonData.game_set.ending || {}).length,
+    endingOutcomes: ending.outcomes.length,
+    timelineEvents: timelineEvents.length,
+    components: components.length,
+    assets: assetFiles.length,
+    unexplained: 0
+  });
+  return Object.freeze({
+    title,
+    components,
+    assets: Object.freeze(assetFiles.map(clone)),
+    coverage,
+    source: Object.freeze({
+      format: IMPORT_SOURCE_FORMAT,
+      profile: IMPORT_PROFILE,
+      root,
+      jsonPath: sourceJsonPath,
+      sourceHash,
+      sourceGameId: String(game.documentId || game.id || ""),
+      sourceLastModified: String(game.lastModifiedDate || ""),
+      files: Object.freeze(sourceFiles)
+    })
+  });
+}
+
+function assertSourceSnapshot(source, options = {}) {
+  const fsApi = options.fs || fs;
+  if (!isObject(source) || source.format !== IMPORT_SOURCE_FORMAT || source.profile !== IMPORT_PROFILE || !Array.isArray(source.files)) {
+    throw cliError("E_INVALID_PLAN", "Import source snapshot이 올바르지 않습니다.");
+  }
+  const observed = source.files.map(file => snapshotFile(String(source.root || ""), String(file.path || ""), String(file.kind || "source"), fsApi));
+  if (!equalJson(observed, source.files)) throw cliError("E_CONFLICT", "plan 생성 후 true-writer 원본 파일이 변경되었습니다. 새 import plan을 만들어 주세요.");
+  const sourceHash = sha256(observed.map(item => ({ relativePath: item.relativePath, contentHash: item.contentHash, size: item.size })));
+  if (sourceHash !== source.sourceHash) throw cliError("E_CONFLICT", "plan의 true-writer source hash가 현재 파일과 다릅니다.");
+  return source;
+}
+
+function sourceProvenance(source, coverage) {
+  return Object.freeze({
+    format: IMPORT_SOURCE_FORMAT,
+    profile: IMPORT_PROFILE,
+    sourceHash: String(source.sourceHash || ""),
+    sourceGameId: String(source.sourceGameId || ""),
+    sourceLastModified: String(source.sourceLastModified || ""),
+    fileCount: Array.isArray(source.files) ? source.files.length : 0,
+    coverage: clone(coverage)
+  });
+}
+
+module.exports = Object.freeze({
+  IMPORT_SOURCE_FORMAT,
+  IMPORT_PROFILE,
+  COMPONENT_BLUEPRINTS,
+  VIEW_BLUEPRINTS,
+  loadTrueWriterCase,
+  normalizeImportComponents,
+  importCompositionRows,
+  assertSourceSnapshot,
+  sourceProvenance
+});