@ssobig/writer-cli 0.2.2 → 0.3.0

package/templates/mystery-v1/component-renderers.js

@@ -10,7 +10,6 @@
     aiResponse: root.WriterWorkbenchAiResponseRenderer,
     timeline: root.WriterWorkbenchTimelineRenderer,
     ending: root.WriterWorkbenchEndingRenderer,
-    postgame: root.WriterWorkbenchPostgameRenderer,
     authorNotes: root.WriterWorkbenchAuthorNotesRenderer,
     investigationBoard: root.WriterWorkbenchInvestigationBoardRenderer,
     documents: root.WriterWorkbenchDocumentRenderers
@@ -26,7 +25,6 @@
     aiResponse: require("./renderers/ai-response.js"),
     timeline: require("./renderers/timeline.js"),
     ending: require("./renderers/ending.js"),
-    postgame: require("./renderers/postgame.js"),
     authorNotes: require("./renderers/author-notes.js"),
     investigationBoard: require("./renderers/investigation-board.js"),
     documents: require("./renderers/documents.js")
@@ -36,8 +34,8 @@
   if (root) root.WriterWorkbenchComponentRenderers = api;
 })(typeof globalThis !== "undefined" ? globalThis : this, function (dependencies) {
   "use strict";
-  const { appearance, shared, basic, common, character, clues, clueCombinations, aiResponse, timeline, ending, postgame, authorNotes, investigationBoard, documents } = dependencies;
-  if (!appearance || !shared || !basic || !common || !character || !clues || !clueCombinations || !aiResponse || !timeline || !ending || !postgame || !authorNotes || !investigationBoard || !documents) throw new Error("Component renderer modules are incomplete");
+  const { appearance, shared, basic, common, character, clues, clueCombinations, aiResponse, timeline, ending, authorNotes, investigationBoard, documents } = dependencies;
+  if (!appearance || !shared || !basic || !common || !character || !clues || !clueCombinations || !aiResponse || !timeline || !ending || !authorNotes || !investigationBoard || !documents) throw new Error("Component renderer modules are incomplete");
 
   const renderers = new Map();
   function register(renderer) {
@@ -45,9 +43,10 @@
     if (renderers.has(key)) throw new Error(`중복 Component 렌더러입니다: ${key}`);
     renderers.set(key, Object.freeze({ ...renderer }));
   }
-  [basic, common, { ...common, templateId: "ssobig.choice" }, character, clues, clueCombinations, aiResponse, timeline, ending, postgame, authorNotes, investigationBoard].forEach(register);
+  [basic, common, character, clues, clueCombinations, aiResponse, timeline, ending, authorNotes, investigationBoard].forEach(register);
   Object.entries(documents.definitions).forEach(([templateId, definition]) => register({
     templateId,
+    unifiedAuthoring: definition.unifiedAuthoring === true,
     renderAuthoring: documents.renderAuthoring,
     renderPreview: documents.renderPreview,
     bind: documents.bind
@@ -71,6 +70,8 @@
     return renderer;
   }
   function defaultView() { return "preview"; }
+  function usesUnifiedAuthoring(instance) { return resolve(instance).unifiedAuthoring === true; }
+  function usesUnifiedAuthoringView(viewModel) { return resolveView(viewModel).unifiedAuthoring === true; }
   function context(instance, data, extra = {}) {
     return { instance, data, ...extra, view: shared.rendererView(extra, defaultView(instance)) };
   }
@@ -90,8 +91,9 @@
       .replace(/data-renderer-view="(?:input|preview)"/, `data-renderer-view="${view}"`);
   }
   function renderAuthoring(instance, data, extra) {
-    const rendererContext = context(instance, data, extra);
-    return applyRendererView(resolve(instance).renderAuthoring(rendererContext), rendererContext.view);
+    const renderer = resolve(instance);
+    const rendererContext = context(instance, data, renderer.unifiedAuthoring === true ? { ...extra, view: "preview" } : extra);
+    return applyRendererView(renderer.renderAuthoring(rendererContext), rendererContext.view);
   }
   function renderPreview(instance, data = instance?.data, extra) { return resolve(instance).renderPreview(context(instance, data, extra)); }
   function bind(instance, root, data, extra) {
@@ -102,7 +104,7 @@
   }
   function renderAuthoringView(viewModel, extra) {
     const renderer = resolveView(viewModel);
-    const rendererContext = viewContext(viewModel, extra);
+    const rendererContext = viewContext(viewModel, renderer.unifiedAuthoring === true ? { ...extra, view: "preview" } : extra);
     return applyRendererView(renderer.renderAuthoring(rendererContext), rendererContext.view);
   }
   function renderPreviewView(viewModel, extra) {
@@ -119,6 +121,8 @@
     resolve,
     resolveView,
     defaultView,
+    usesUnifiedAuthoring,
+    usesUnifiedAuthoringView,
     renderAuthoring,
     renderPreview,
     bind,

package/templates/mystery-v1/markdown-live-editor.js

@@ -0,0 +1,350 @@
+(function (root, factory) {
+  const api = factory(root?.WriterCodeMirror6);
+  if (typeof module === "object" && module.exports) module.exports = api;
+  if (root) root.WriterMarkdownLiveEditor = api;
+})(typeof globalThis !== "undefined" ? globalThis : this, function (CodeMirror6) {
+  "use strict";
+
+  const INLINE_MARKERS = Object.freeze([
+    { marker: "++", type: "brand" },
+    { marker: "**", type: "strong" },
+    { marker: "~~", type: "strikethrough" },
+    { marker: "==", type: "highlight" },
+    { marker: "`", type: "code" }
+  ]);
+  function lineStarts(source) {
+    const starts = [0];
+    for (let index = 0; index < source.length; index += 1) {
+      if (source[index] === "\n") starts.push(index + 1);
+    }
+    return starts;
+  }
+
+  function lineAt(starts, offset) {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low <= high) {
+      const middle = (low + high) >> 1;
+      if (starts[middle] <= offset) low = middle + 1;
+      else high = middle - 1;
+    }
+    return Math.max(0, high);
+  }
+
+  function inlineTokens(source) {
+    const tokens = [];
+    let index = 0;
+    while (index < source.length) {
+      const definition = INLINE_MARKERS.find(item => source.startsWith(item.marker, index));
+      if (!definition || (index > 0 && source[index - 1] === "\\")) {
+        index += 1;
+        continue;
+      }
+      const contentFrom = index + definition.marker.length;
+      const closeFrom = source.indexOf(definition.marker, contentFrom);
+      const crossesBlockBoundary = closeFrom > contentFrom && /\n[ \t]*\n/.test(source.slice(contentFrom, closeFrom));
+      if (closeFrom <= contentFrom || crossesBlockBoundary || (closeFrom > 0 && source[closeFrom - 1] === "\\")) {
+        index += definition.marker.length;
+        continue;
+      }
+      const to = closeFrom + definition.marker.length;
+      tokens.push({
+        type: definition.type,
+        marker: definition.marker,
+        from: index,
+        openTo: contentFrom,
+        contentFrom,
+        contentTo: closeFrom,
+        closeFrom,
+        to
+      });
+      index = to;
+    }
+    return tokens;
+  }
+
+  function normalizeSelections(selections, sourceLength) {
+    const values = Array.isArray(selections) ? selections : [{ anchor: 0, head: 0 }];
+    return values.map(selection => {
+      const anchor = Math.max(0, Math.min(sourceLength, Number(selection?.anchor) || 0));
+      const head = Math.max(0, Math.min(sourceLength, Number(selection?.head) || 0));
+      return { anchor, head, from: Math.min(anchor, head), to: Math.max(anchor, head) };
+    });
+  }
+
+  function selectionTouchesRange(selection, from, to) {
+    return selection.from === selection.to
+      ? selection.head >= from && selection.head <= to
+      : selection.to >= from && selection.from <= to;
+  }
+
+  function lineSyntax(text) {
+    const heading = text.match(/^( {0,3})(#{1,4})(?:[ \t]+|$)/);
+    const quote = text.match(/^( {0,3})>[ \t]?/);
+    const unordered = text.match(/^([-*])[ \t]+(.+)$/);
+    const ordered = text.match(/^(\d+[.)])[ \t]+(.+)$/);
+    return {
+      headingLevel: heading ? heading[2].length : 0,
+      headingMarkerFrom: heading ? heading[1].length : -1,
+      headingMarkerTo: heading ? heading[0].length : -1,
+      quoteMarkerFrom: quote ? quote[1].length : -1,
+      quoteMarkerTo: quote ? quote[0].length : -1,
+      listType: unordered ? "unordered" : ordered ? "ordered" : "",
+      empty: !text.trim()
+    };
+  }
+
+  function layoutLines(source, starts) {
+    const lines = source.split("\n").map((text, index) => ({
+      index,
+      text,
+      from: starts[index],
+      to: starts[index] + text.length,
+      ...lineSyntax(text),
+      blockId: -1,
+      blockType: "",
+      blockStart: false,
+      blockEnd: false,
+      nestedQuote: false,
+      firstListItem: false
+    }));
+    const blocks = [];
+    let paragraph = null;
+    let quote = null;
+    let listType = "";
+    let listGroup = 0;
+    let nextBlockId = 0;
+    const openBlock = (type, line, extra = {}) => {
+      const block = { id: nextBlockId++, type, lines: [], ...extra };
+      blocks.push(block);
+      line.blockId = block.id;
+      line.blockType = type;
+      line.blockStart = true;
+      block.lines.push(line.index);
+      return block;
+    };
+    const appendBlock = (block, line) => {
+      line.blockId = block.id;
+      line.blockType = block.type;
+      block.lines.push(line.index);
+    };
+
+    lines.forEach(line => {
+      if (line.quoteMarkerFrom >= 0) {
+        paragraph = null;
+        const nestedQuote = Boolean(listType);
+        if (!quote || quote.nestedQuote !== nestedQuote || quote.listGroup !== listGroup) {
+          quote = openBlock("quote", line, { nestedQuote, listGroup: nestedQuote ? listGroup : 0 });
+        } else appendBlock(quote, line);
+        line.nestedQuote = nestedQuote;
+        return;
+      }
+      quote = null;
+      if (line.empty) {
+        paragraph = null;
+        listType = "";
+        return;
+      }
+      if (line.headingLevel) {
+        paragraph = null;
+        listType = "";
+        openBlock(`heading${line.headingLevel}`, line);
+        return;
+      }
+      if (line.listType) {
+        paragraph = null;
+        const firstListItem = line.listType !== listType;
+        if (firstListItem) listGroup += 1;
+        listType = line.listType;
+        line.firstListItem = firstListItem;
+        openBlock("listItem", line, { listGroup, firstListItem });
+        return;
+      }
+      listType = "";
+      if (!paragraph) paragraph = openBlock("paragraph", line);
+      else appendBlock(paragraph, line);
+    });
+
+    blocks.forEach(block => {
+      const lastLine = lines[block.lines.at(-1)];
+      if (lastLine) lastLine.blockEnd = true;
+    });
+    const listGroups = new Map();
+    blocks.forEach(block => {
+      if (!block.listGroup) return;
+      if (!listGroups.has(block.listGroup)) listGroups.set(block.listGroup, []);
+      listGroups.get(block.listGroup).push(block);
+    });
+    listGroups.forEach(group => {
+      const last = group.at(-1);
+      if (last) last.listEnd = true;
+    });
+
+    return { lines, blocks };
+  }
+
+  function previewModel(value, selections = [{ anchor: 0, head: 0 }]) {
+    const source = String(value ?? "").replace(/\r\n?/g, "\n");
+    const starts = lineStarts(source);
+    const normalizedSelections = normalizeSelections(selections, source.length);
+    const activeLines = new Set();
+    normalizedSelections.forEach(selection => {
+      const first = lineAt(starts, selection.from);
+      const last = lineAt(starts, selection.to);
+      for (let line = first; line <= last; line += 1) activeLines.add(line);
+    });
+    const layout = layoutLines(source, starts);
+    layout.lines.forEach(line => { line.active = activeLines.has(line.index); });
+    const tokens = inlineTokens(source).map(token => ({
+      ...token,
+      active: normalizedSelections.some(selection => selectionTouchesRange(selection, token.from, token.to))
+    }));
+    return { source, starts, lines: layout.lines, blocks: layout.blocks, tokens };
+  }
+
+  function classNames(line) {
+    const values = ["writer-md-line"];
+    if (line.empty) values.push("writer-md-empty-line");
+    if (line.active) values.push("writer-md-active-line");
+    if (line.blockStart) values.push("writer-md-block-start");
+    if (line.blockEnd) values.push("writer-md-block-end");
+    if (line.blockType) {
+      const blockClass = line.blockType
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/(\d+)$/, "-$1")
+        .toLowerCase();
+      values.push(`writer-md-${blockClass}`);
+    }
+    if (line.nestedQuote) values.push("writer-md-nested-quote");
+    if (line.firstListItem) values.push("writer-md-first-list-item");
+    return values.join(" ");
+  }
+
+  function mount(options = {}) {
+    const cm = CodeMirror6;
+    if (!cm?.EditorState || !cm?.StateEffect || !cm?.EditorView || !cm?.Decoration || !cm?.StateField) {
+      throw new Error("Markdown 편집기를 초기화하지 못했습니다.");
+    }
+    if (!options.parent) throw new Error("Markdown 편집기 표시 영역이 없습니다.");
+    let destroyed = false;
+    const ownerDocument = options.parent.ownerDocument || document;
+    const focusEffect = cm.StateEffect.define();
+    const focusField = cm.StateField.define({
+      create() { return false; },
+      update(focused, transaction) {
+        for (const effect of transaction.effects) {
+          if (effect.is(focusEffect)) focused = Boolean(effect.value);
+        }
+        return focused;
+      }
+    });
+    const buildDecorations = state => {
+      const selections = state.field(focusField)
+        ? state.selection.ranges.map(range => ({ anchor: range.anchor, head: range.head }))
+        : [];
+      const model = previewModel(state.doc.toString(), selections);
+      const ranges = [];
+      const syntaxDecoration = active => cm.Decoration.mark({
+        class: active ? "writer-md-syntax" : "writer-md-syntax-hidden"
+      });
+      model.lines.forEach(line => {
+        ranges.push(cm.Decoration.line({ attributes: { class: classNames(line) } }).range(line.from));
+        if (line.headingMarkerFrom >= 0) {
+          const from = line.from + line.headingMarkerFrom;
+          const to = line.from + line.headingMarkerTo;
+          ranges.push(syntaxDecoration(line.active).range(from, to));
+        } else if (line.quoteMarkerFrom >= 0) {
+          const from = line.from + line.quoteMarkerFrom;
+          const to = line.from + line.quoteMarkerTo;
+          ranges.push(syntaxDecoration(line.active).range(from, to));
+        }
+      });
+      model.tokens.forEach(token => {
+        ranges.push(cm.Decoration.mark({ class: `writer-md-${token.type}` }).range(token.contentFrom, token.contentTo));
+        const markerDecoration = syntaxDecoration(token.active);
+        ranges.push(markerDecoration.range(token.from, token.openTo));
+        ranges.push(markerDecoration.range(token.closeFrom, token.to));
+      });
+      return cm.Decoration.set(ranges, true);
+    };
+    const previewField = cm.StateField.define({
+      create(state) {
+        return buildDecorations(state);
+      },
+      update(decorations, transaction) {
+        const focusChanged = transaction.effects.some(effect => effect.is(focusEffect));
+        return transaction.docChanged || transaction.selection || focusChanged ? buildDecorations(transaction.state) : decorations;
+      },
+      provide: field => cm.EditorView.decorations.from(field)
+    });
+    const state = cm.EditorState.create({
+      doc: String(options.value ?? "").replace(/\r\n?/g, "\n"),
+      extensions: [
+        cm.EditorView.editorAttributes.of({
+          class: "writer-markdown-live-editor",
+          ...(options.placeholder ? { "data-placeholder": String(options.placeholder) } : {})
+        }),
+        cm.history(),
+        cm.keymap.of([
+          { key: "Escape", run() { options.onEscape?.(); return true; } },
+          ...cm.defaultKeymap,
+          ...cm.historyKeymap
+        ]),
+        cm.markdown(),
+        cm.EditorView.lineWrapping,
+        focusField,
+        previewField,
+        cm.EditorView.contentAttributes.of({
+          role: "textbox",
+          "aria-multiline": "true",
+          "aria-label": String(options.ariaLabel || "Markdown 편집")
+        }),
+        cm.EditorView.updateListener.of(update => {
+          if (update.docChanged) options.onChange?.(update.state.doc.toString());
+        }),
+        cm.EditorView.domEventHandlers({
+          focus() {
+            view.dispatch({ effects: focusEffect.of(true) });
+          },
+          blur() {
+            view.dispatch({ effects: focusEffect.of(false) });
+            setTimeout(() => {
+              if (!destroyed && !view.dom.contains(ownerDocument.activeElement)) options.onBlur?.();
+            }, 0);
+          }
+        })
+      ]
+    });
+    const view = new cm.EditorView({ state, parent: options.parent });
+    return Object.freeze({
+      getValue: () => view.state.doc.toString(),
+      getSelection: () => view.state.selection.ranges.map(range => ({ anchor: range.anchor, head: range.head })),
+      focusAtPosition(position, options = {}) {
+        const anchor = Math.max(0, Math.min(view.state.doc.length, Number(position) || 0));
+        view.dispatch({ selection: { anchor }, scrollIntoView: options.scrollIntoView !== false });
+        view.focus();
+        return anchor;
+      },
+      focusAtEnd() {
+        view.dispatch({ selection: { anchor: view.state.doc.length }, scrollIntoView: true });
+        view.focus();
+      },
+      focusAtClientPoint(clientX, clientY) {
+        const position = Number.isFinite(clientX) && Number.isFinite(clientY)
+          ? view.posAtCoords({ x: clientX, y: clientY }, false)
+          : null;
+        const anchor = position == null ? view.state.doc.length : position;
+        view.dispatch({ selection: { anchor } });
+        view.focus();
+        return anchor;
+      },
+      destroy() {
+        if (destroyed) return;
+        destroyed = true;
+        view.destroy();
+      }
+    });
+  }
+
+  return Object.freeze({ inlineTokens, lineSyntax, layoutLines, previewModel, mount });
+});

package/templates/mystery-v1/page-header.js

@@ -18,8 +18,9 @@
     const title = escapeHtml(options.title || "");
     const description = escapeHtml(options.description || "");
     const className = ["page-header", options.className].filter(Boolean).join(" ");
+    const titleMetaMarkup = String(options.titleMetaMarkup || "");
     const metaMarkup = String(options.metaMarkup || "");
-    return `<header class="${escapeHtml(className)}"><div class="page-header-copy"><h2>${title}</h2>${description ? `<p>${description}</p>` : ""}</div>${metaMarkup ? `<div class="page-header-meta">${metaMarkup}</div>` : ""}</header>`;
+    return `<header class="${escapeHtml(className)}"><div class="page-header-copy"><div class="page-header-title-row"><h2>${title}</h2>${titleMetaMarkup ? `<div class="page-header-title-meta">${titleMetaMarkup}</div>` : ""}</div>${description ? `<p>${description}</p>` : ""}</div>${metaMarkup ? `<div class="page-header-meta">${metaMarkup}</div>` : ""}</header>`;
   }
 
   return Object.freeze({ escapeHtml, render });

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

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

package/tools/writer-cli/package.json

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

package/tools/writer-cli/skills/ssobig-writer-cli/SKILL.md

@@ -35,4 +35,4 @@ For every production mutation, follow this sequence without shortcuts:
 
 A general request to inspect code or explain behavior does not authorize manuscript mutation. Plan and receipt files can contain confidential content; store them in a private ignored directory and never commit them.
 
-`E_CODE_CHANGE_REQUIRED` is a hard stop. It means the requested operation changes shared schemas, Component composition, Renderer/View behavior, identity, or another boundary outside the content CLI. Do not work around it. Report the boundary and separate the request into a reviewed code or migration task.
+`E_CODE_CHANGE_REQUIRED` is a hard stop. Supported Component-management mutations are registered optional Component addition through `component plan-add`, archive/restore through `component plan-set-active`, and registered optional-field selection through `component plan-set-field`. Shared schemas, unregistered composition, reorder behavior, Renderer/View behavior, identity, and other boundaries remain outside the content CLI. Do not work around them.

package/tools/writer-cli/skills/ssobig-writer-cli/references/projects-components.md

@@ -2,6 +2,6 @@
 
 Project commands expose identity, versions, and reviewed project-level plans. Component commands are the supported path for authoritative manuscript values. Read first, preserve the selected project/version/Instance identity, and use a dedicated `plan-*` command for changes.
 
-Generic Component patching changes only an existing Instance's `data`. It cannot change Component composition, metadata, View bindings, templates, schemas, project identity, or storage paths. If the CLI returns `E_CODE_CHANGE_REQUIRED`, stop and report that a separate code or migration review is required.
+Generic Component patching changes only an existing Instance's `data`. Check `component list` for `addableTemplates` and `archivedComponents`. Use `component plan-add` for a never-created registered optional Component, `component plan-set-active` for its data-preserving archive/restore toggle, and `component plan-set-field` for a registered optional field shown in the Component screen. These commands cannot edit arbitrary composition, metadata, View bindings, templates, schemas, project identity, or storage paths. If the CLI returns `E_CODE_CHANGE_REQUIRED`, stop and report that a separate code or migration review is required.
 
 Never apply a generated plan until the user has reviewed a human-readable summary and explicitly authorized the production mutation. Read back the same Component after apply.

package/tools/writer-cli/src/agent-service.cjs

@@ -11,7 +11,7 @@ const {
   verifyPlan,
   validateLoadedVersion
 } = require("./domain.cjs");
-const { applyProjectCreationPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan } = require("./mutations.cjs");
+const { applyProjectCreationPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentActivePlan, applyComponentAddPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan } = require("./mutations.cjs");
 const { pointerSegments } = require("./json-patch.cjs");
 const { equalJson, sha256 } = require("./json.cjs");
 const { cliError, normalizeError } = require("./errors.cjs");
@@ -418,6 +418,8 @@ function createAgentService(options = {}) {
         if (plan.operation === "project.create") receipt = await applyProjectCreationPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
         else if (plan.operation === "project.catalog-demo") receipt = await applyCatalogDemoPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
         else if (plan.operation.startsWith("project.")) receipt = await applyProjectStatusPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
+        else if (plan.operation === "component.set-active") receipt = await applyComponentActivePlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
+        else if (plan.operation === "component.add") receipt = await applyComponentAddPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
         else if (plan.operation === "component.patch") receipt = await applyComponentPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
         else if (plan.operation.startsWith("checkpoint.")) receipt = await applyCheckpointPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
         else receipt = await applyAssetPlan(gateway, plan, context.user.email, { appliedAt: isoNow(), now: Date.now });

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

@@ -62,6 +62,9 @@ const COMMANDS = Object.freeze([
   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("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 }),

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

@@ -5,6 +5,8 @@ const fs = require("node:fs");
 const path = require("node:path");
 const config = require("../../../config.js");
 const projectRuntime = require("../../../project-runtime.js");
+const componentCatalog = require("../../../templates/mystery-v1/component-catalog-contract.js");
+const componentRegistry = require("../../../templates/mystery-v1/component-registry.js").createDefaultRegistry();
 const { createAuthManager } = require("./auth.cjs");
 const { createSupabaseGateway } = require("./gateway.cjs");
 const { inspectAssetFile, assertAssetId } = require("./asset-policy.cjs");
@@ -13,6 +15,9 @@ const {
   componentContract,
   validateLoadedVersion,
   findInstance,
+  createComponentActivePlan,
+  createComponentAddPlan,
+  createComponentFieldPlan,
   createComponentPlan,
   createInvestigationBoardLayoutPlan,
   createAssetPlan,
@@ -25,7 +30,7 @@ const {
   verifyPlan
 } = require("./domain.cjs");
 const { loadTrueWriterCase } = require("./project-import.cjs");
-const { applyProjectCreationPlan, applyProjectImportPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan } = require("./mutations.cjs");
+const { applyProjectCreationPlan, applyProjectImportPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentActivePlan, applyComponentAddPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan } = require("./mutations.cjs");
 const { snapshotSummary, diffSnapshots } = require("./checkpoint-diff.cjs");
 const { cliError, normalizeError, redact } = require("./errors.cjs");
 const { startDaemon, stopDaemon } = require("./daemon-runner.cjs");
@@ -186,10 +191,43 @@ function publicInstance(instance, includeData = false) {
     required: instance.required,
     removable: instance.removable
   };
+  const fields = componentRegistry.get(instance.templateId)?.fieldConfiguration || [];
+  if (fields.length) {
+    const hasSelection = Array.isArray(instance.data?.enabledOptionalFields);
+    const enabled = new Set(hasSelection ? instance.data.enabledOptionalFields : fields.filter(field => !field.required).map(field => field.key));
+    result.fieldConfiguration = fields.map(field => ({
+      key: field.key,
+      label: field.label,
+      description: field.description,
+      required: field.required,
+      enabled: field.required || enabled.has(field.key)
+    }));
+  }
   if (includeData) result.data = instance.data;
   return result;
 }
 
+function publicComponentAvailability(validated) {
+  const archivedComponents = componentContract.archivedInstances(validated.componentRows);
+  const occupiedSingletonTemplates = new Set(validated.componentRows.map(row => String(row.template_id)));
+  const addableTemplates = componentCatalog.list()
+    .filter(template => !template.required && !template.internal && template.view
+      && (template.allowMultiple || !occupiedSingletonTemplates.has(template.templateId)))
+    .map(template => ({
+      templateId: template.templateId,
+      defaultInstanceId: template.defaultInstanceId,
+      tabLabel: template.tabLabel,
+      displayLabel: template.displayLabel,
+      description: template.description,
+      allowMultiple: template.allowMultiple,
+      requiresInstanceId: template.allowMultiple
+    }));
+  return {
+    archivedComponents: archivedComponents.map(item => publicInstance(item)),
+    addableTemplates
+  };
+}
+
 function publicCheckpoint(row, projectId, versionNumber) {
   return normalizeCheckpoint({
     ...row,
@@ -610,13 +648,53 @@ 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-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"].includes(subcommand)) {
       assertAllowedOptions(options, `component.${subcommand}`);
       const projectRef = requireOption(options, "project");
       const validated = validateLoadedVersion(await gateway.loadLatestVersion(projectRef, optionalVersionOption(options)));
       const version = validated.versionNumber;
       if (subcommand === "list") {
-        return { command: "component.list", data: { project: publicProject(validated.project, validated.instances), versionNumber: version, components: validated.instances.map(item => publicInstance(item)) } };
+        return { command: "component.list", data: { project: publicProject(validated.project, validated.instances), versionNumber: version, components: validated.instances.map(item => publicInstance(item)), ...publicComponentAvailability(validated) } };
+      }
+      if (subcommand === "plan-add") {
+        const plan = createComponentAddPlan(validated, {
+          templateId: requireOption(options, "template"),
+          instanceId: options.instance,
+          tabLabel: options.label
+        }, user.email, planOptions(deps));
+        const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+        return {
+          command: "component.plan-add",
+          data: {
+            planFile: outputPath,
+            planId: plan.planId,
+            digest: plan.digest,
+            operation: plan.operation,
+            target: plan.target,
+            initialData: plan.initialData,
+            initialDataHash: plan.initialDataHash,
+            composition: plan.composition
+          }
+        };
+      }
+      if (subcommand === "plan-set-active") {
+        const activeValue = requireOption(options, "active");
+        if (!new Set(["true", "false"]).has(activeValue)) throw cliError("E_USAGE", "--active는 true 또는 false여야 합니다.");
+        const plan = createComponentActivePlan(validated, {
+          instanceId: requireOption(options, "instance"),
+          active: activeValue === "true"
+        }, user.email, planOptions(deps));
+        const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+        return { command: "component.plan-set-active", data: { planFile: outputPath, planId: plan.planId, digest: plan.digest, operation: plan.operation, target: plan.target, composition: plan.composition } };
+      }
+      if (subcommand === "plan-set-field") {
+        const enabledValue = requireOption(options, "enabled");
+        if (!new Set(["true", "false"]).has(enabledValue)) throw cliError("E_USAGE", "--enabled는 true 또는 false여야 합니다.");
+        const fieldPlanOptions = planOptions(deps);
+        if (options.message !== undefined) fieldPlanOptions.checkpointMessage = String(options.message);
+        const plan = createComponentFieldPlan(validated, requireOption(options, "instance"), requireOption(options, "field"), enabledValue === "true", user.email, fieldPlanOptions);
+        const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+        return { command: "component.plan-set-field", data: { planFile: outputPath, planId: plan.planId, digest: plan.digest, operation: plan.operation, checkpointMessage: plan.checkpointMessage, target: plan.target, fieldSelection: plan.fieldSelection, beforeHash: plan.beforeHash, afterHash: plan.afterHash } };
       }
       if (subcommand === "plan-layout-investigation-board") {
         const spec = readJson(requireOption(options, "spec"), "추리 보드 layout spec", deps.fs).value;
@@ -783,6 +861,10 @@ async function execute(argv, deps) {
           receipt = await applyCatalogDemoPlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
         } else if (plan.operation.startsWith("project.")) {
           receipt = await applyProjectStatusPlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
+        } else if (plan.operation === "component.set-active") {
+          receipt = await applyComponentActivePlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
+        } else if (plan.operation === "component.add") {
+          receipt = await applyComponentAddPlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
         } else if (plan.operation === "component.patch") {
           receipt = await applyComponentPlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
         } else if (plan.operation.startsWith("checkpoint.")) {