@ssobig/writer-cli 0.2.2 → 0.3.2

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

@@ -41,41 +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-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"]),
@@ -86,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

@@ -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,8 +15,12 @@ const {
   componentContract,
   validateLoadedVersion,
   findInstance,
+  createComponentActivePlan,
+  createComponentAddPlan,
+  createComponentFieldPlan,
   createComponentPlan,
   createInvestigationBoardLayoutPlan,
+  createTimelineMigrationPlan,
   createAssetPlan,
   createProjectCreationPlan,
   createProjectImportPlan,
@@ -25,7 +31,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 +192,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 +649,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", "plan-migrate-timeline"].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;
@@ -647,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) } };
@@ -783,6 +882,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.")) {