@ssobig/writer-cli 0.3.0 → 0.3.3

package/tools/writer-cli/src/command-registry.cjs

@@ -41,44 +41,45 @@ const COMMANDS = Object.freeze([
   command("version", "Show installed CLI version and integrity.", [option("check", null, "Check npm latest.", { type: "boolean" })], ["ssobig-writer version --check"]),
   command("doctor", "Run read-only installation and connectivity diagnostics.", [], ["ssobig-writer doctor"]),
   command("command-schema", "Discover groups, leaves, or exact machine-readable command metadata.", [positional("scope", "Optional group or group.command scope.", { required: false })], ["ssobig-writer command-schema component.get --compact"]),
-  command("auth.login", "Sign in through the staff authentication flow.", [option("no-open", null, "Print the login URL without opening a browser.", { type: "boolean" })], ["ssobig-writer auth login --no-open"], SERVER),
-  command("auth.whoami", "Show the current authenticated staff identity.", [], ["ssobig-writer auth whoami"], SERVER),
+  command("auth.login", "Sign in through the Writer member Google sign-in flow.", [option("no-open", null, "Print the login URL without opening a browser.", { type: "boolean" })], ["ssobig-writer auth login --no-open"], SERVER),
+  command("auth.whoami", "Show the current authenticated Writer member identity.", [], ["ssobig-writer auth whoami"], SERVER),
   command("auth.logout", "Clear local credentials and cached agent state.", [], ["ssobig-writer auth logout"]),
   command("agent.start", "Start the private local Writer daemon.", [], ["ssobig-writer agent start"], SERVER),
   command("agent.status", "Show local daemon status.", [], ["ssobig-writer agent status"]),
   command("agent.stop", "Stop the local daemon.", [], ["ssobig-writer agent stop"]),
-  command("agent.get", "Read one indexed match by identifier.", [option("match", "<match-id>", "Search match identifier.", { required: true }), option("max-characters", "<100-20000>", "Maximum returned characters.")], ["ssobig-writer agent get --match <match-id>"], SERVER),
-  command("agent.apply", "Apply an agent-produced reviewed plan.", [option("plan", "<plan-file>", "Reviewed plan path.", { required: true }), option("receipt", "<receipt-file>", "Receipt output path.", { required: true })], ["ssobig-writer agent apply --plan plan.json --receipt receipt.json"], { ...SERVER, ...MUTATE }),
+  command("agent.get", "Read a matched scalar from the authoritative server by search match identifier.", [option("match", "<match-id>", "Search match identifier.", { required: true }), option("max-characters", "<100-20000>", "Maximum returned characters.")], ["ssobig-writer agent get --match <match-id>"], SERVER),
+  command("agent.apply", "Apply an agent-produced reviewed plan.", [option("plan", "<plan-file>", "Reviewed plan path.", { required: true }), option("receipt", "<receipt-file>", "Receipt output path.", { required: true })], ["ssobig-writer agent apply --plan .ssobig-writer/plan.json --receipt .ssobig-writer/receipt.json"], { ...SERVER, ...MUTATE }),
   command("agent.purge", "Purge local manuscript indexes.", [], ["ssobig-writer agent purge"]),
   command("sync", "Refresh the local manuscript index.", [], ["ssobig-writer sync"], SERVER),
-  command("read", "Read indexed or authoritative Component data.", [option("project", "<slug|uuid>", "Limit to a project."), version, option("component", "<id|template-id>", "Limit to a Component."), option("pointer", "<json-pointer>", "Read a JSON pointer."), option("include-assets", null, "Include asset metadata.", { type: "boolean" }), option("fresh", null, "Prefer an authoritative refresh.", { type: "boolean" }), option("require-fresh", null, "Fail unless authoritative data is available.", { type: "boolean" })], ["ssobig-writer read --project <slug> --component <template-id> --fresh"], SERVER),
-  command("search", "Search Component values and paths.", [option("query", "<text>", "Text query."), option("value-json", "<json-scalar>", "Typed exact value."), option("mode", "<all|exact|substring|regex>", "Search mode."), option("project", "<slug|uuid>", "Limit to a project."), version, option("component", "<id|template-id>", "Limit to a Component."), option("path", "<json-pointer>", "Exact JSON pointer."), option("path-prefix", "<json-pointer>", "JSON pointer prefix."), option("path-glob", "<glob>", "JSON pointer glob."), option("field", "<field>", "Field selector."), option("value-type", "<type>", "Value type."), option("limit", "<n>", "Maximum matches."), option("flags", "<regex-flags>", "Regular-expression flags."), option("case-sensitive", null, "Use case-sensitive matching.", { type: "boolean" }), option("include-assets", null, "Include asset metadata.", { type: "boolean" }), option("fresh", null, "Prefer an authoritative refresh.", { type: "boolean" }), option("require-fresh", null, "Fail unless authoritative data is available.", { type: "boolean" })], ["ssobig-writer search --query <text> --project <slug>", "ssobig-writer search --mode all --path-prefix /characters"], SERVER),
+  command("read", "Read local indexed Component data (not authoritative).", [option("project", "<slug|uuid>", "Limit to a project."), version, option("component", "<id|template-id>", "Limit to a Component."), option("pointer", "<json-pointer>", "Read a JSON pointer."), option("include-assets", null, "Include asset metadata.", { type: "boolean" }), option("fresh", null, "Sync the corpus before reading the local index; output stays non-authoritative.", { type: "boolean" }), option("require-fresh", null, "Refresh a missing or known-stale index; not a server read on every call.", { type: "boolean" })], ["ssobig-writer read --project <slug> --component <template-id> --fresh"], SERVER),
+  command("search", "Search Component values and paths.", [option("query", "<text>", "Text query."), option("value-json", "<json-scalar>", "Typed exact value."), option("mode", "<all|exact|substring|regex>", "Search mode."), option("project", "<slug|uuid>", "Limit to a project."), version, option("component", "<id|template-id>", "Limit to a Component."), option("path", "<json-pointer>", "Exact JSON pointer."), option("path-prefix", "<json-pointer>", "JSON pointer prefix."), option("path-glob", "<glob>", "JSON pointer glob."), option("field", "<field>", "Field selector."), option("value-type", "<type>", "Value type."), option("limit", "<n>", "Maximum matches."), option("flags", "<regex-flags>", "Regular-expression flags."), option("case-sensitive", null, "Use case-sensitive matching.", { type: "boolean" }), option("include-assets", null, "Include asset metadata.", { type: "boolean" }), option("fresh", null, "Sync the corpus before reading the local index; output stays non-authoritative.", { type: "boolean" }), option("require-fresh", null, "Refresh a missing or known-stale index; not a server read on every call.", { type: "boolean" })], ["ssobig-writer search --query <text> --project <slug>", "ssobig-writer search --mode all --path-prefix /characters"], SERVER),
   command("project.list", "List visible Writer projects.", [option("status", "<active|archived>", "Project status.")], ["ssobig-writer project list --status active"], SERVER),
   command("project.show", "Show project identity and versions.", [project, option("status", "<active|archived>", "Project status.")], ["ssobig-writer project show --project <slug>"], SERVER),
-  command("project.plan-create", "Create a reviewed project creation plan.", [option("slug", "<slug>", "New project slug.", { required: true }), option("title", "<title>", "Project title.", { required: true }), out], ["ssobig-writer project plan-create --slug new-case --title 'New Case' --out plan.json"], { ...SERVER, ...PLAN }),
-  command("project.plan-import", "Create a reviewed import plan from a supported case export.", [option("source-root", "<case-directory>", "Source case root.", { required: true }), option("source-json", "<room-export.json>", "Source room export.", { required: true }), option("slug", "<slug>", "New project slug.", { required: true }), option("title", "<title>", "Project title.", { required: true }), out], ["ssobig-writer project plan-import --source-root case --source-json room.json --slug new-case --title 'New Case' --out plan.json"], { ...SERVER, ...PLAN }),
-  command("project.plan-archive", "Create a reviewed project archive plan.", [project, out], ["ssobig-writer project plan-archive --project <slug> --out plan.json"], { ...SERVER, ...PLAN }),
-  command("project.plan-restore", "Create a reviewed project restore plan.", [project, out], ["ssobig-writer project plan-restore --project <slug> --out plan.json"], { ...SERVER, ...PLAN }),
-  command("project.plan-set-catalog-demo", "Create a reviewed catalog-demo status plan.", [project, option("enabled", "<true|false>", "Catalog demo state.", { required: true }), out], ["ssobig-writer project plan-set-catalog-demo --project <slug> --enabled true --out plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-create", "Create a reviewed project creation plan.", [option("slug", "<slug>", "New project slug.", { required: true }), option("title", "<title>", "Project title.", { required: true }), out], ["ssobig-writer project plan-create --slug new-case --title 'New Case' --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-import", "Create a reviewed import plan from a supported case export.", [option("source-root", "<case-directory>", "Source case root.", { required: true }), option("source-json", "<room-export.json>", "Source room export.", { required: true }), option("slug", "<slug>", "New project slug.", { required: true }), option("title", "<title>", "Project title.", { required: true }), out], ["ssobig-writer project plan-import --source-root case --source-json room.json --slug new-case --title 'New Case' --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-archive", "Create a reviewed project archive plan.", [project, out], ["ssobig-writer project plan-archive --project <slug> --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-restore", "Create a reviewed project restore plan.", [project, out], ["ssobig-writer project plan-restore --project <slug> --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("project.plan-set-catalog-demo", "Create a reviewed catalog-demo status plan.", [project, option("enabled", "<true|false>", "Catalog demo state.", { required: true }), out], ["ssobig-writer project plan-set-catalog-demo --project <slug> --enabled true --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
   command("component.list", "List Components in a workspace.", [project, version], ["ssobig-writer component list --project <slug>"], SERVER),
   command("component.get", "Read one authoritative Component Instance.", [project, version, option("instance", "<id|template-id>", "Component Instance or Template identifier.", { required: true })], ["ssobig-writer component get --project <slug> --instance <template-id>"], SERVER),
-  command("component.plan-add", "Create a reviewed plan to add one registered optional Component.", [project, version, option("template", "<template-id>", "Registered optional Data Component Template.", { required: true }), option("instance", "<instance-id>", "Instance identifier; required for multi-instance Templates."), option("label", "<tab-label>", "User-facing Component label."), out], ["ssobig-writer component plan-add --project <slug> --template ssobig.timeline --out plan.json"], { ...SERVER, ...PLAN }),
-  command("component.plan-set-active", "Create a reviewed plan to toggle one optional Component.", [project, version, option("instance", "<instance-id>", "Stored optional Component Instance.", { required: true }), option("active", "<true|false>", "Use or archive the Component.", { required: true }), out], ["ssobig-writer component plan-set-active --project <slug> --instance clues --active false --out plan.json"], { ...SERVER, ...PLAN }),
-  command("component.plan-set-field", "Create a reviewed plan to toggle one optional Component field.", [project, version, option("instance", "<id|template-id>", "Active Component Instance or Template.", { required: true }), option("field", "<field-key>", "Registered optional field key.", { required: true }), option("enabled", "<true|false>", "Show or hide the optional field.", { required: true }), out, message], ["ssobig-writer component plan-set-field --project <slug> --instance clues --field image --enabled false --out plan.json"], { ...SERVER, ...PLAN }),
-  command("component.plan-patch", "Create a reviewed Component data patch plan.", [project, version, option("instance", "<id|template-id>", "Component Instance or Template identifier.", { required: true }), option("patch", "<file>", "JSON patch document.", { required: true }), out, message], ["ssobig-writer component plan-patch --project <slug> --instance <id> --patch patch.json --out plan.json"], { ...SERVER, ...PLAN }),
-  command("component.plan-layout-investigation-board", "Create a deterministic investigation-board layout plan.", [project, version, option("instance", "<id|template-id>", "Investigation board Component."), option("spec", "<layout-spec.json>", "Validated layout spec.", { required: true }), out, message], ["ssobig-writer component plan-layout-investigation-board --project <slug> --spec layout.json --out plan.json"], { ...SERVER, ...PLAN }),
-  command("component.plan-replace", "Create a reviewed indexed text replacement plan.", [option("match", "<match-id>", "Search match identifier.", { required: true }), option("old", "<text>", "Expected old text.", { required: true }), option("new", "<text>", "Replacement text.", { required: true }), out, option("occurrence", "<zero-based-index>", "Occurrence index."), message], ["ssobig-writer component plan-replace --match <id> --old old --new new --out plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-add", "Create a reviewed plan to add one registered optional Component.", [project, version, option("template", "<template-id>", "Registered optional Data Component Template.", { required: true }), option("instance", "<instance-id>", "Instance identifier; required for multi-instance Templates."), option("label", "<tab-label>", "User-facing Component label."), out], ["ssobig-writer component plan-add --project <slug> --template ssobig.timeline --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-set-active", "Create a reviewed plan to toggle one optional Component.", [project, version, option("instance", "<instance-id>", "Stored optional Component Instance.", { required: true }), option("active", "<true|false>", "Use or archive the Component.", { required: true }), out], ["ssobig-writer component plan-set-active --project <slug> --instance clues --active false --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-set-field", "Create a reviewed plan to toggle one optional Component field.", [project, version, option("instance", "<id|template-id>", "Active Component Instance or Template.", { required: true }), option("field", "<field-key>", "Registered optional field key.", { required: true }), option("enabled", "<true|false>", "Show or hide the optional field.", { required: true }), out, message], ["ssobig-writer component plan-set-field --project <slug> --instance clues --field image --enabled false --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-patch", "Create a reviewed Component data patch plan.", [project, version, option("instance", "<id|template-id>", "Component Instance or Template identifier.", { required: true }), option("patch", "<file>", "JSON patch document.", { required: true }), out, message], ["ssobig-writer component plan-patch --project <slug> --instance <id> --patch .ssobig-writer/patch.json --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-layout-investigation-board", "Create a deterministic investigation-board layout plan.", [project, version, option("instance", "<id|template-id>", "Investigation board Component."), option("spec", "<layout-spec.json>", "Semantic layout spec; see the installed ssobig-writer-cli skill references/layout-spec.md (bundled at tools/writer-cli/skills/ssobig-writer-cli/references/layout-spec.md).", { required: true }), out, message], ["ssobig-writer component plan-layout-investigation-board --project <slug> --spec .ssobig-writer/layout.json --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-migrate-timeline", "Create a reviewed timeline v2 migration plan.", [project, version, option("instance", "<id|template-id>", "Timeline Component."), out, message], ["ssobig-writer component plan-migrate-timeline --project <slug> --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("component.plan-replace", "Create a reviewed indexed text replacement plan.", [option("match", "<match-id>", "Search match identifier.", { required: true }), option("old", "<text>", "Expected old text.", { required: true }), option("new", "<text>", "Replacement text.", { required: true }), out, option("occurrence", "<zero-based-index>", "Occurrence index."), message], ["ssobig-writer component plan-replace --match <id> --old old --new new --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
   command("asset.list", "List immutable asset pointers.", [project, version], ["ssobig-writer asset list --project <slug>"], SERVER),
-  command("asset.plan-upload", "Create a reviewed asset upload plan.", [project, version, option("asset-id", "<id>", "Asset identifier.", { required: true }), option("file", "<path>", "JPEG, PNG, WebP, GIF, or JSON file.", { required: true }), out, message], ["ssobig-writer asset plan-upload --project <slug> --asset-id cover --file cover.webp --out plan.json"], { ...SERVER, ...PLAN }),
-  command("asset.plan-delete", "Create a reviewed asset delete plan.", [project, version, option("asset-id", "<id>", "Asset identifier.", { required: true }), out, message], ["ssobig-writer asset plan-delete --project <slug> --asset-id cover --out plan.json"], { ...SERVER, ...PLAN }),
+  command("asset.plan-upload", "Create a reviewed asset upload plan.", [project, version, option("asset-id", "<id>", "Asset identifier.", { required: true }), option("file", "<path>", "JPEG, PNG, WebP, GIF, or JSON file.", { required: true }), out, message], ["ssobig-writer asset plan-upload --project <slug> --asset-id cover --file cover.webp --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("asset.plan-delete", "Create a reviewed asset delete plan.", [project, version, option("asset-id", "<id>", "Asset identifier.", { required: true }), out, message], ["ssobig-writer asset plan-delete --project <slug> --asset-id cover --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
   command("checkpoint.list", "List workspace checkpoints.", [project, version, option("before", "<checkpoint-number>", "Pagination cursor."), option("limit", "<1-100>", "Maximum rows.")], ["ssobig-writer checkpoint list --project <slug> --limit 20"], SERVER),
   command("checkpoint.status", "Show the current checkpoint head.", [project, version], ["ssobig-writer checkpoint status --project <slug>"], SERVER),
   command("checkpoint.show", "Show one checkpoint snapshot.", [project, version, option("checkpoint", "<id|number>", "Checkpoint selector.", { required: true }), option("include-data", null, "Include manuscript data.", { type: "boolean" })], ["ssobig-writer checkpoint show --project <slug> --checkpoint 3"], SERVER),
   command("checkpoint.diff", "Diff two checkpoints or Latest.", [project, version, option("from", "<id|number|latest>", "Diff base.", { required: true }), option("to", "<id|number|latest>", "Diff target.", { required: true }), option("include-values", null, "Include changed values.", { type: "boolean" })], ["ssobig-writer checkpoint diff --project <slug> --from 2 --to latest"], SERVER),
-  command("checkpoint.plan-create", "Create a reviewed checkpoint creation plan.", [project, version, option("message", "<message>", "Checkpoint message.", { required: true }), out], ["ssobig-writer checkpoint plan-create --project <slug> --message review --out plan.json"], { ...SERVER, ...PLAN }),
-  command("checkpoint.plan-restore", "Create a reviewed checkpoint restore plan.", [project, version, option("checkpoint", "<id|number>", "Checkpoint selector.", { required: true }), option("message", "<message>", "Checkpoint message.", { required: true }), out], ["ssobig-writer checkpoint plan-restore --project <slug> --checkpoint 3 --message restore --out plan.json"], { ...SERVER, ...PLAN }),
+  command("checkpoint.plan-create", "Create a reviewed checkpoint creation plan.", [project, version, option("message", "<message>", "Checkpoint message.", { required: true }), out], ["ssobig-writer checkpoint plan-create --project <slug> --message review --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
+  command("checkpoint.plan-restore", "Create a reviewed checkpoint restore plan.", [project, version, option("checkpoint", "<id|number>", "Checkpoint selector.", { required: true }), option("message", "<message>", "Checkpoint message.", { required: true }), out], ["ssobig-writer checkpoint plan-restore --project <slug> --checkpoint 3 --message restore --out .ssobig-writer/plan.json"], { ...SERVER, ...PLAN }),
   command("validate", "Validate the authoritative Component composition.", [project, version], ["ssobig-writer validate --project <slug>"], SERVER),
-  command("apply", "Apply one reviewed plan and optionally write a receipt.", [positional("plan-file", "Reviewed plan file."), option("receipt", "<receipt-file>", "Private receipt output path.")], ["ssobig-writer apply plan.json --receipt receipt.json"], { ...SERVER, ...MUTATE }),
+  command("apply", "Apply one reviewed plan and optionally write a receipt.", [positional("plan-file", "Reviewed plan file."), option("receipt", "<receipt-file>", "Private receipt output path.")], ["ssobig-writer apply .ssobig-writer/plan.json --receipt .ssobig-writer/receipt.json"], { ...SERVER, ...MUTATE }),
   command("skills.install", "Install the bundled project-local agent skill.", [option("target", "<workspace>", "Workspace root.", { required: true }), option("codex", null, "Install only to .agents/skills.", { type: "boolean" }), option("claude", null, "Install only to .claude/skills.", { type: "boolean" }), option("dry-run", null, "Report without changing files.", { type: "boolean" })], ["ssobig-writer skills install --target . --dry-run"]),
   command("skills.status", "Inspect bundled skill installation state.", [option("target", "<workspace>", "Workspace root.", { required: true })], ["ssobig-writer skills status --target ."]),
   command("skills.update", "Safely update managed skill files.", [option("target", "<workspace>", "Workspace root.", { required: true }), option("codex", null, "Update only .agents/skills.", { type: "boolean" }), option("claude", null, "Update only .claude/skills.", { type: "boolean" }), option("dry-run", null, "Report without changing files.", { type: "boolean" })], ["ssobig-writer skills update --target . --dry-run"]),
@@ -89,7 +90,7 @@ const BY_PATH = new Map(COMMANDS.map(item => [item.path, item]));
 if (BY_PATH.size !== COMMANDS.length) throw new Error("Writer CLI command registry contains duplicate paths.");
 
 const GROUP_DESCRIPTIONS = Object.freeze({
-  version: "installation version", doctor: "installation diagnostics", "command-schema": "targeted machine metadata", auth: "staff authentication", agent: "local agent backend",
+  version: "installation version", doctor: "installation diagnostics", "command-schema": "targeted machine metadata", auth: "Writer member authentication", agent: "local agent backend",
   sync: "local index refresh", read: "targeted manuscript read", search: "targeted manuscript search", project: "project identity and plans",
   component: "Component data and plans", asset: "asset pointers and plans", checkpoint: "workspace history", validate: "composition validation",
   apply: "reviewed plan mutation", skills: "project-local agent skills"

package/tools/writer-cli/src/commands.cjs

@@ -20,6 +20,7 @@ const {
   createComponentFieldPlan,
   createComponentPlan,
   createInvestigationBoardLayoutPlan,
+  createTimelineMigrationPlan,
   createAssetPlan,
   createProjectCreationPlan,
   createProjectImportPlan,
@@ -648,7 +649,7 @@ async function execute(argv, deps) {
       return { command: "project.plan-set-catalog-demo", data: { planFile: outputPath, planId: plan.planId, digest: plan.digest, operation: plan.operation, project: plan.project, target: plan.target } };
     }
 
-    if (command === "component" && ["list", "get", "plan-add", "plan-set-active", "plan-set-field", "plan-patch", "plan-layout-investigation-board"].includes(subcommand)) {
+    if (command === "component" && ["list", "get", "plan-add", "plan-set-active", "plan-set-field", "plan-patch", "plan-layout-investigation-board", "plan-migrate-timeline"].includes(subcommand)) {
       assertAllowedOptions(options, `component.${subcommand}`);
       const projectRef = requireOption(options, "project");
       const validated = validateLoadedVersion(await gateway.loadLatestVersion(projectRef, optionalVersionOption(options)));
@@ -725,6 +726,26 @@ async function execute(argv, deps) {
           }
         };
       }
+      if (subcommand === "plan-migrate-timeline") {
+        const timelinePlanOptions = planOptions(deps);
+        if (options.message !== undefined) timelinePlanOptions.checkpointMessage = String(options.message);
+        const plan = createTimelineMigrationPlan(validated, options.instance || "timeline", user.email, timelinePlanOptions);
+        const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+        return {
+          command: "component.plan-migrate-timeline",
+          data: {
+            planFile: outputPath,
+            planId: plan.planId,
+            digest: plan.digest,
+            operation: plan.operation,
+            checkpointMessage: plan.checkpointMessage,
+            target: plan.target,
+            migration: plan.migration,
+            beforeHash: plan.beforeHash,
+            afterHash: plan.afterHash
+          }
+        };
+      }
       const selector = requireOption(options, "instance");
       if (subcommand === "get") {
         return { command: "component.get", data: { project: publicProject(validated.project, validated.instances), versionNumber: version, component: publicInstance(findInstance(validated, selector), true) } };

package/tools/writer-cli/src/domain.cjs

@@ -5,6 +5,7 @@ const componentContract = require("../../../templates/mystery-v1/component-stora
 const componentCatalog = require("../../../templates/mystery-v1/component-catalog-contract.js");
 const componentRegistry = require("../../../templates/mystery-v1/component-registry.js").createDefaultRegistry();
 const viewContract = require("../../../templates/mystery-v1/view-component-contract.js");
+const timelineModel = require("../../../templates/mystery-v1/timeline-model.js");
 const projectRuntime = require("../../../project-runtime.js");
 const { applyPatch } = require("./json-patch.cjs");
 const { clone, equalJson, sha256 } = require("./json.cjs");
@@ -399,6 +400,50 @@ function createInvestigationBoardLayoutPlan(validated, selector, spec, actorEmai
   return finalizePlan(plan);
 }
 
+function timelineEntryCountsByCharacter(entries) {
+  const counts = new Map();
+  for (const entry of entries) {
+    if (entry.lane?.kind !== "character") continue;
+    const characterId = String(entry.lane.characterId || "");
+    counts.set(characterId, (counts.get(characterId) || 0) + 1);
+  }
+  return Object.fromEntries([...counts.keys()].sort().map(characterId => [characterId, counts.get(characterId)]));
+}
+
+function createTimelineMigrationPlan(validated, selector, actorEmail, options = {}) {
+  const instance = findInstance(validated, selector || "timeline");
+  if (instance.templateId !== "ssobig.timeline") {
+    throw cliError("E_VALIDATION", "타임라인 v2 이관은 ssobig.timeline Component에만 사용할 수 있습니다.");
+  }
+  const shape = timelineModel.detectShape(instance.data);
+  if (shape === "v2") throw cliError("E_NO_CHANGES", "타임라인 Component가 이미 v2 모양입니다.");
+  if (shape !== "legacy") throw cliError("E_VALIDATION", "타임라인 Component data가 legacy 또는 v2 모양이 아닙니다.");
+  const converted = timelineModel.convertLegacyTimeline(instance.data, { idFactory: options.idFactory });
+  const review = timelineModel.compareLegacyToV2(instance.data, converted);
+  if (!review.ok) throw cliError("E_VALIDATION", `타임라인 v2 변환이 원본과 일치하지 않습니다: ${review.mismatches.join(" / ")}`);
+  const patch = [
+    { op: "test", path: "/events", value: clone(instance.data.events) },
+    { op: "remove", path: "/events" },
+    { op: "add", path: "/timeLevels", value: clone(converted.timeLevels) },
+    { op: "add", path: "/entries", value: clone(converted.entries) }
+  ];
+  const componentPlan = createComponentPlan(validated, instance.instanceId, patch, actorEmail, {
+    ...options,
+    checkpointMessage: options.checkpointMessage || "CLI: 타임라인 v2 이관"
+  });
+  const plan = clone(componentPlan);
+  delete plan.digest;
+  plan.migration = {
+    kind: "timeline-v2",
+    counts: clone(review.counts),
+    mismatches: clone(review.mismatches),
+    levelCount: converted.timeLevels.length,
+    entryCount: converted.entries.length,
+    entryCountByCharacter: timelineEntryCountsByCharacter(converted.entries)
+  };
+  return finalizePlan(plan);
+}
+
 function createAssetPlan(validated, operation, assetId, actorEmail, options = {}) {
   const assetInstance = componentContract.assetInstance(validated.instances);
   const manifest = componentContract.assetManifest(validated.instances);
@@ -959,6 +1004,7 @@ module.exports = Object.freeze({
   createComponentPlan,
   investigationBoardReferences,
   createInvestigationBoardLayoutPlan,
+  createTimelineMigrationPlan,
   createAssetPlan,
   createProjectCreationPlan,
   createProjectImportPlan,

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

@@ -6,6 +6,7 @@ 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 timelineModel = require("../../../templates/mystery-v1/timeline-model.js");
 const { inspectAssetFile } = require("./asset-policy.cjs");
 const { clone, equalJson, sha256 } = require("./json.cjs");
 const { cliError } = require("./errors.cjs");
@@ -142,6 +143,15 @@ function parseTimeline(source) {
   return events;
 }
 
+// 원본 표는 사건이 시간을 소유하는 legacy 행으로 읽고, 등록된 v2 모양으로만 Component data를 만든다.
+function timelineComponentData(events) {
+  const legacy = { events };
+  const converted = timelineModel.convertLegacyTimeline(legacy);
+  const review = timelineModel.compareLegacyToV2(legacy, converted);
+  if (!review.ok) throw cliError("E_VALIDATION", `타임라인 v2 변환이 원본과 일치하지 않습니다: ${review.mismatches.join(" / ")}`);
+  return { data: converted, review };
+}
+
 function characterComponent(characterSource) {
   const characters = {};
   const names = {};
@@ -354,6 +364,7 @@ function loadTrueWriterCase(input, options = {}) {
   const progress = progressComponent(jsonData.game_set.flow);
   const ending = endingComponent(jsonData.game_set.ending);
   const timelineEvents = parseTimeline(docs["03-timeline.md"]);
+  const timeline = timelineComponentData(timelineEvents);
   const resources = Object.keys(jsonData.resource).length;
   const components = normalizeImportComponents([
     component("basic", {
@@ -380,7 +391,7 @@ function loadTrueWriterCase(input, options = {}) {
     component("characters", characterComponent(jsonData.game_set.character)),
     component("assets", { assets: {} }),
     component("clues", cluesComponent(jsonData.resource)),
-    component("timeline", { events: timelineEvents }),
+    component("timeline", timeline.data),
     component("ending", ending),
     component("author-notes", {
       notes: [
@@ -417,6 +428,9 @@ function loadTrueWriterCase(input, options = {}) {
     endingGroups: Object.keys(jsonData.game_set.ending || {}).length,
     endingOutcomes: ending.outcomes.length,
     timelineEvents: timelineEvents.length,
+    timelineLevels: timeline.data.timeLevels.length,
+    timelineEntries: timeline.data.entries.length,
+    timelineConversion: { shape: "v2", lossless: timeline.review.ok, ...timeline.review.counts },
     components: components.length,
     assets: assetFiles.length,
     unexplained: 0