@ssobig/writer-cli 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssobig/writer-cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Official agent CLI for SSOBIG WRITER",
   "type": "commonjs",
   "license": "UNLICENSED",

package/templates/mystery-v1/component-catalog-contract.js

@@ -103,7 +103,7 @@
       templateId: "ssobig.timeline", defaultInstanceId: "timeline", tabLabel: "타임라인",
       description: "사건이 일어난 시간과 장소, 캐릭터별 기억과 행동을 시간순으로 정리합니다.",
       guide: guide("사건의 객관적 흐름과 인물별 기억을 시간축으로 맞춥니다.", "22시 로비 사건과 각 캐릭터가 기억하는 행동을 나란히 기록합니다.", "시간·장소·진실과 캐릭터별 기억을 사건 단위로 편집합니다.", "context", "캐릭터 정보를 읽어 인물별 기억을 연결하지만 독립 플레이 화면은 제공하지 않습니다.", ["ssobig.character"], "타임라인 제작 화면 예시"),
-      defaultData: { events: [] },
+      defaultData: { timeGroups: [], events: [], places: [] },
       view: view("ssobig.view.timeline-workbench", "timeline-workbench", "타임라인 작업 화면", "ssobig.timeline", [
         binding("primary", "ssobig.timeline", "read_write"), binding("character-context", "ssobig.character", "read", false)
       ]),

package/templates/mystery-v1/component-field-contracts.js

@@ -312,6 +312,37 @@
     })
   ]);
 
+  const EVENT_TIMELINE_CONTRACT = component({
+    templateId: "ssobig.timeline",
+    root: shape({ timeGroups: field("array", { item: "group" }), events: field("array", { item: "event" }), places: field("array", { item: "place" }) }),
+    items: {
+      group: shape({ id: field("uuid"), name: field("non-empty-string"), type: field("enum", { values: ["text", "timeline"] }) }),
+      place: shape({ id: field("uuid"), name: field("non-empty-string") }),
+      event: shape({ id: field("uuid"), description: field("string"), timeGroupId: field("uuid"),
+        placeId: field("nullable-uuid"), characterId: field("nullable-stable-key")
+      }, { timeRange: field("object", { item: "range" }), included: field("boolean") }),
+      range: shape({ start: field("object", { item: "point" }), end: field("object", { item: "point" }) }),
+      point: shape({ day: field("integer", { minimum: 0, maximum: 999999 }), hour: field("integer", { minimum: 0, maximum: 23 }), minute: field("integer", { minimum: 0, maximum: 59 }) })
+    }
+  });
+  function eventTimelineError(data) {
+    const invalid = validateShape(data, EVENT_TIMELINE_CONTRACT.root, EVENT_TIMELINE_CONTRACT, "$");
+    if (invalid) return invalid;
+    const groups = new Map(data.timeGroups.map(group => [group.id, group]));
+    const places = new Set(data.places.map(place => place.id));
+    const minutes = point => point.day * 1440 + point.hour * 60 + point.minute;
+    for (const event of data.events) {
+      const group = groups.get(event.timeGroupId);
+      if (!group) return "사건의 시간 그룹이 존재하지 않습니다.";
+      if (event.placeId !== null && !places.has(event.placeId)) return "사건의 장소가 존재하지 않습니다.";
+      if (group.type === "timeline") {
+        if (!event.timeRange) return "타임라인 그룹의 사건에는 시작·종료 시간이 필수입니다.";
+        if (minutes(event.timeRange.end) <= minutes(event.timeRange.start)) return "종료는 시작 이후여야 합니다.";
+      } else if (Object.hasOwn(event, "timeRange")) return "텍스트 그룹의 사건에는 시간 범위를 저장하지 않습니다.";
+    }
+    return null;
+  }
+
   const BY_ID = new Map(CONTRACTS.map(contract => [contract.templateId, contract]));
   const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
   const STABLE_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
@@ -352,6 +383,8 @@
       case "non-empty-string": return { type: "string", minLength: 1, pattern: "\\S" };
       case "stable-key": return { type: "string", pattern: STABLE_KEY_PATTERN.source };
       case "uuid": return { type: "string", format: "uuid" };
+      case "nullable-uuid": return { anyOf: [{ type: "null" }, { type: "string", format: "uuid" }] };
+      case "nullable-stable-key": return { anyOf: [{ type: "null" }, { type: "string", pattern: STABLE_KEY_PATTERN.source }] };
       case "hex-color": return { type: "string", pattern: HEX_COLOR_PATTERN.source };
       case "hex-color-or-empty": return { type: "string", pattern: `^(?:|#[0-9a-fA-F]{6})$` };
       case "safe-storage-relative-path": return { type: "string", minLength: 1 };
@@ -397,6 +430,7 @@
   }
   function jsonSchemaFor(templateId) {
     const contract = getContract(templateId);
+    if (templateId === "ssobig.timeline") return { oneOf: [clone(schemaForShape(contract.root, contract)), clone(schemaForShape(EVENT_TIMELINE_CONTRACT.root, EVENT_TIMELINE_CONTRACT))] };
     return contract ? clone(schemaForShape(contract.root, contract)) : null;
   }
 
@@ -433,6 +467,8 @@
   }
   function validateField(value, definition, contract, path) {
     switch (definition.type) {
+      case "nullable-uuid": return value === null || (typeof value === "string" && UUID_PATTERN.test(value)) ? null : `${path} 값은 UUID 또는 null이어야 합니다.`;
+      case "nullable-stable-key": return value === null || (typeof value === "string" && STABLE_KEY_PATTERN.test(value)) ? null : `${path} 값은 캐릭터 ID 또는 null이어야 합니다.`;
       case "string": return typeof value === "string" ? null : `${path} 값은 문자열이어야 합니다.`;
       case "non-empty-string": return typeof value === "string" && value.trim() ? null : `${path} 값은 비어 있지 않은 문자열이어야 합니다.`;
       case "stable-key": return typeof value === "string" && STABLE_KEY_PATTERN.test(value) ? null : `${path} 값은 안정 식별자 형식이어야 합니다.`;
@@ -658,6 +694,7 @@
     }
   }
   function validateTargetData(templateId, data) {
+    if (templateId === "ssobig.timeline" && isObject(data) && Object.hasOwn(data, "timeGroups")) return eventTimelineError(data);
     const contract = getContract(templateId);
     if (!contract) return `지원하지 않는 Component 계약입니다: ${templateId}`;
     const invalid = validateShape(data, contract.root, contract, "$");

package/templates/mystery-v1/component-storage-contract.js

@@ -152,7 +152,9 @@
       // 타임라인의 모양 배타, 시간 레벨 참조, lane/when 종류별 규칙은 validateComponentData가 이미 검증한다.
       // 여기서는 다른 Component를 봐야 판정할 수 있는 character 참조만 확인한다.
       for (const timeline of instances.filter(instance => instance.templateId === "ssobig.timeline")) {
-        const invalid = Array.isArray(timeline.data.events)
+        const invalid = Array.isArray(timeline.data.timeGroups)
+          ? (timeline.data.events.some(event => event.characterId !== null && !characterIds.has(event.characterId)) ? `${timeline.instanceId} 사건이 존재하지 않는 캐릭터를 가리킵니다.` : null)
+          : Array.isArray(timeline.data.events)
           ? legacyTimelineError(timeline, characterIds)
           : timelineLaneCharacterError(timeline, characterIds);
         if (invalid) return invalid;

package/templates/mystery-v1/timeline-model.js

@@ -16,6 +16,7 @@
   // events는 사건이 시간을 소유하는 legacy 모양, timeLevels/entries는 항목이 시간을 소유하는 v2 모양이다.
   function detectShape(data) {
     if (!isObject(data)) return "invalid";
+    if (Object.hasOwn(data, "timeGroups")) return Array.isArray(data.timeGroups) && Array.isArray(data.events) && Array.isArray(data.places) && !Object.hasOwn(data, "timeLevels") && !Object.hasOwn(data, "entries") ? "events" : "invalid";
     const events = Array.isArray(data.events);
     const levels = Array.isArray(data.timeLevels);
     const entries = Array.isArray(data.entries);
@@ -224,12 +225,72 @@
   }
 
   // 활성 런타임이 중립 이름으로 소비하는 정규화 진입점: 어떤 등록 모양이든 v2 data를 돌려준다.
+  // Explicit, reviewed migration only. Rendering and ordinary saves never call this.
+  function convertToEventTimeline(data) {
+    if (detectShape(data) !== "v2") throw new Error("시간 그룹 이관은 timeLevels/entries 원본만 지원합니다.");
+    if (data.entries.some(entry => entry.lane.kind === "unresolved")) throw new Error("미연결 캐릭터를 먼저 해결해 주세요.");
+    const places = JSON.parse(JSON.stringify(data.places || []));
+    const groups = data.timeLevels.map(level => ({ id: level.id, name: level.name, type: level.mode === "clock" ? "timeline" : "text" }));
+    const events = data.entries.map(entry => {
+      const group = groups.find(group => group.id === entry.timeLevelId);
+      if (!group) throw new Error("존재하지 않는 시간 그룹입니다.");
+      const ids = entry.placeIds || [];
+      const matched = places.find(place => place.name.trim() === text(entry.location).trim());
+      const placeId = ids.at(-1) || matched?.id || null;
+      const annotations = [];
+      const location = text(entry.location).trim();
+      if (ids.length > 1) annotations.push(`기존 이동 경로: ${entryPlaceNames(data, entry).join(" → ")}`);
+      if (location && ![places.find(place => place.id === placeId)?.name, entryPlaceNames(data, entry).join(" → ")].includes(location)) annotations.push(`기존 장소 메모: ${location}`);
+      if (!ids.length && !matched && location && !annotations.some(value => value.endsWith(location))) annotations.push(`기존 장소 메모: ${location}`);
+      const event = { id: entry.id, timeGroupId: entry.timeLevelId, description: entry.text, characterId: entry.lane.kind === "character" ? entry.lane.characterId : null, placeId };
+      if (entry.included === false) event.included = false;
+      if (group.type === "timeline") {
+        if (entry.when.kind !== "clock") throw new Error("시각이 없는 사건의 시간 범위를 먼저 지정해 주세요.");
+        const start = (entry.when.dayOffset || 0) * 1440 + entry.when.startMinute;
+        const end = entry.when.endMinute === undefined ? start + 30 : (entry.when.dayOffset || 0) * 1440 + entry.when.endMinute;
+        if (end <= start) throw new Error("시작 이후의 종료 시간을 지정해 주세요.");
+        event.timeRange = { start: minutePoint(start), end: minutePoint(end) };
+        const clockLabel = minute => `${String(Math.floor(minute / 60)).padStart(2, "0")}:${String(minute % 60).padStart(2, "0")}`;
+        const canonical = clockLabel(entry.when.startMinute) + (entry.when.endMinute === undefined ? "" : `~${clockLabel(entry.when.endMinute)}`);
+        const normalized = text(entry.timeLabel).replace(/[–—−-]/g, "~").replace(/\s/g, "");
+        if (normalized && normalized !== canonical) annotations.push(`기존 시간 표현: ${entry.timeLabel}`);
+      } else if (text(entry.timeLabel).trim()) annotations.push(`기존 시간 표현: ${entry.timeLabel}`);
+      if (annotations.length) event.description += `${event.description ? "\n\n" : ""}${annotations.join("\n")}`;
+      return event;
+    });
+    return { timeGroups: groups, events, places };
+  }
+
+  function pointMinutes(point) { return point.day * 1440 + point.hour * 60 + point.minute; }
+  function minutePoint(value) { return { day: Math.floor(value / 1440), hour: Math.floor(value % 1440 / 60), minute: value % 60 }; }
+  function defaultRange(start = { day: 0, hour: 9, minute: 0 }) { return { start: { ...start }, end: minutePoint(pointMinutes(start) + 30) }; }
+  function pointLabel(point) { return `${point.day + 1}일차 ${String(point.hour).padStart(2, "0")}:${String(point.minute).padStart(2, "0")}`; }
+  function rangeLabel(range) { return range ? `${pointLabel(range.start)}–${pointLabel(range.end)}` : ""; }
+  function orderedEvents(data) {
+    const groups = new Map(data.timeGroups.map((group, index) => [group.id, { ...group, index }]));
+    return data.events.map((event, index) => ({ event, index })).sort((a, b) => {
+      const ga = groups.get(a.event.timeGroupId), gb = groups.get(b.event.timeGroupId);
+      return ga.index - gb.index || (ga.type === "timeline" ? pointMinutes(a.event.timeRange.start) - pointMinutes(b.event.timeRange.start) : 0) || a.index - b.index;
+    }).map(item => item.event);
+  }
+  // Projection only: old board/output consumers never own this derived representation.
+  function eventTimelineProjection(data) {
+    return { timeLevels: data.timeGroups.map(group => ({ id: group.id, name: group.name, mode: group.type === "timeline" ? "clock" : "manual" })), places: data.places,
+      entries: orderedEvents(data).map(event => ({ id: event.id, timeLevelId: event.timeGroupId,
+        lane: event.characterId === null ? { kind: "truth" } : { kind: "character", characterId: event.characterId },
+        when: event.timeRange ? { kind: "clock", dayOffset: event.timeRange.start.day, startMinute: event.timeRange.start.hour * 60 + event.timeRange.start.minute,
+          endMinute: pointMinutes(event.timeRange.end) - event.timeRange.start.day * 1440 } : { kind: "unspecified" },
+        timeLabel: rangeLabel(event.timeRange), text: event.description, included: event.included !== false,
+        placeIds: event.placeId === null ? [] : [event.placeId], location: "" })) };
+  }
+
   function normalizedTimelineData(data, options = {}) {
+    if (detectShape(data) === "events") return eventTimelineProjection(data);
     const shape = detectShape(data);
     if (shape === "v2") return data;
     if (shape === "legacy") return convertLegacyTimeline(data, options);
     throw new Error("타임라인 data가 등록된 모양이 아닙니다.");
   }
 
-  return Object.freeze({ detectShape, convertLegacyTimeline, compareLegacyToV2, normalizedTimelineData, entryPlaceNames, orderedEntries, overlapGroups, deriveClusters });
+  return Object.freeze({ convertToEventTimeline, pointMinutes, minutePoint, defaultRange, pointLabel, rangeLabel, orderedEvents, eventTimelineProjection, detectShape, convertLegacyTimeline, compareLegacyToV2, normalizedTimelineData, entryPlaceNames, orderedEntries, overlapGroups, deriveClusters });
 });

package/tools/writer-cli/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@ssobig/writer-cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ssobig/writer-cli",
-      "version": "0.3.3",
+      "version": "0.3.4",
       "dependencies": {
         "@supabase/supabase-js": "2.110.9"
       },

package/tools/writer-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssobig/writer-cli",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "private": true,
   "description": "Internal agent-safe CLI for SSOBIG WRITER manuscript and asset operations",
   "type": "commonjs",