@ssobig/writer-cli 0.2.0

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

@@ -0,0 +1,841 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const config = require("../../../config.js");
+const projectRuntime = require("../../../project-runtime.js");
+const { createAuthManager } = require("./auth.cjs");
+const { createSupabaseGateway } = require("./gateway.cjs");
+const { inspectAssetFile, assertAssetId } = require("./asset-policy.cjs");
+const { sha256 } = require("./json.cjs");
+const {
+  componentContract,
+  validateLoadedVersion,
+  findInstance,
+  createComponentPlan,
+  createInvestigationBoardLayoutPlan,
+  createAssetPlan,
+  createProjectCreationPlan,
+  createProjectImportPlan,
+  createProjectStatusPlan,
+  createCatalogDemoPlan,
+  createCheckpointPlan,
+  normalizeCheckpoint,
+  verifyPlan
+} = require("./domain.cjs");
+const { loadTrueWriterCase } = require("./project-import.cjs");
+const { applyProjectCreationPlan, applyProjectImportPlan, applyProjectStatusPlan, applyCatalogDemoPlan, 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");
+const { requestWriterService } = require("./platform-runner.cjs");
+const { purgeAllAgentIndexes } = require("./agent-paths.cjs");
+const { versionReport, doctorReport } = require("./diagnostics.cjs");
+const { helpFor, commandSchema, getCommand, allowedOptions, booleanOptions, normalizeScope } = require("./command-registry.cjs");
+const { installOrUpdate, skillStatus, removeManaged } = require("./skill-manager.cjs");
+const { checkRequiredUpdate } = require("./update-gate.cjs");
+
+const HELP = helpFor();
+const BOOLEAN_OPTIONS = booleanOptions();
+
+function parseArgs(tokens) {
+  const options = {};
+  const positional = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+    const name = token.slice(2);
+    if (!name) throw cliError("E_USAGE", "비어 있는 option은 사용할 수 없습니다.");
+    if (BOOLEAN_OPTIONS.has(name)) {
+      options[name] = true;
+      continue;
+    }
+    const value = tokens[index + 1];
+    if (value === undefined || value.startsWith("--")) throw cliError("E_USAGE", `--${name} option 값이 필요합니다.`);
+    if (Object.hasOwn(options, name)) throw cliError("E_USAGE", `--${name} option을 중복 지정할 수 없습니다.`);
+    options[name] = value;
+    index += 1;
+  }
+  return { options, positional };
+}
+
+function requireOption(options, name) {
+  const value = options[name];
+  if (value === undefined || String(value).trim() === "") throw cliError("E_USAGE", `--${name} option이 필요합니다.`);
+  return String(value);
+}
+
+function versionOption(options) {
+  const version = Number(requireOption(options, "version"));
+  if (!Number.isSafeInteger(version) || version < 1) throw cliError("E_USAGE", "--version에는 1 이상의 정수가 필요합니다.");
+  return version;
+}
+
+function optionalVersionOption(options) {
+  return options.version === undefined ? null : versionOption(options);
+}
+
+function integerValue(value, label, minimum = 0) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < minimum) throw cliError("E_USAGE", `${label}에는 ${minimum} 이상의 정수가 필요합니다.`);
+  return number;
+}
+
+function statusOption(options, fallback = "active") {
+  const status = String(options.status || fallback);
+  if (!["active", "archived"].includes(status)) throw cliError("E_USAGE", "--status는 active 또는 archived여야 합니다.");
+  return status;
+}
+
+function assertAllowedOptions(options, commandPath) {
+  const permitted = allowedOptions(commandPath);
+  const unknown = Object.keys(options).find(key => !permitted.has(key));
+  if (unknown) throw cliError("E_USAGE", `지원하지 않는 option입니다: --${unknown}`);
+}
+
+function readJson(filePath, label, fsApi = fs) {
+  const absolutePath = path.resolve(String(filePath || ""));
+  let source;
+  try { source = fsApi.readFileSync(absolutePath, "utf8"); }
+  catch (error) { throw cliError("E_FILE_NOT_FOUND", `${label} 파일을 읽을 수 없습니다: ${absolutePath}`, null, error); }
+  try { return { path: absolutePath, value: JSON.parse(source) }; }
+  catch (error) { throw cliError("E_INVALID_JSON", `${label} 파일이 올바른 JSON이 아닙니다: ${absolutePath}`, null, error); }
+}
+
+function reservePrivateJson(filePath, fsApi = fs) {
+  const absolutePath = path.resolve(String(filePath || ""));
+  fsApi.mkdirSync(path.dirname(absolutePath), { recursive: true, mode: 0o700 });
+  let handle;
+  try { handle = fsApi.openSync(absolutePath, "wx", 0o600); }
+  catch (error) {
+    if (error.code === "EEXIST") throw cliError("E_FILE_EXISTS", `기존 파일을 덮어쓰지 않습니다: ${absolutePath}`);
+    throw cliError("E_FILE_WRITE", `파일을 쓸 수 없습니다: ${absolutePath}`, null, error);
+  }
+  let open = true;
+  return {
+    path: absolutePath,
+    commit(value) {
+      if (!open) throw cliError("E_FILE_WRITE", `이미 닫힌 파일 reservation입니다: ${absolutePath}`);
+      try {
+        fsApi.writeFileSync(handle, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8" });
+        fsApi.closeSync(handle);
+        open = false;
+      } catch (error) {
+        try { fsApi.closeSync(handle); } catch (closeError) { void closeError; }
+        open = false;
+        throw cliError("E_FILE_WRITE", `파일을 쓸 수 없습니다: ${absolutePath}`, null, error);
+      }
+      return absolutePath;
+    },
+    discard() {
+      if (open) {
+        try { fsApi.closeSync(handle); } catch (error) { void error; }
+        open = false;
+      }
+      try { fsApi.unlinkSync(absolutePath); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    }
+  };
+}
+
+function writePrivateJson(filePath, value, fsApi = fs) {
+  const reservation = reservePrivateJson(filePath, fsApi);
+  try { return reservation.commit(value); }
+  catch (error) { reservation.discard(); throw error; }
+}
+
+function publicProject(project, instances = []) {
+  const manuscriptTitle = Array.isArray(instances)
+    ? instances.find(instance => instance.templateId === "ssobig.basic")?.data?.title
+    : undefined;
+  return {
+    id: project.id,
+    slug: project.slug,
+    identityTitle: project.title,
+    ...(manuscriptTitle ? { manuscriptTitle } : {}),
+    identitySummary: project.summary,
+    authorName: project.author_name,
+    engineKey: project.engine_key,
+    storageNamespace: project.storage_namespace,
+    status: project.status,
+    isCatalogDemo: project.is_catalog_demo === true,
+    updatedAt: project.updated_at
+  };
+}
+
+function publicVersion(version) {
+  return {
+    versionNumber: Number(version.version_number),
+    identityTitle: version.title,
+    displayName: version.display_name,
+    createdFromVersion: version.created_from_version,
+    updatedAt: version.updated_at
+  };
+}
+
+function publicInstance(instance, includeData = false) {
+  const result = {
+    instanceId: instance.instanceId,
+    templateId: instance.templateId,
+    tab: instance.tab,
+    order: instance.order,
+    revision: instance.revision,
+    required: instance.required,
+    removable: instance.removable
+  };
+  if (includeData) result.data = instance.data;
+  return result;
+}
+
+function publicCheckpoint(row, projectId, versionNumber) {
+  return normalizeCheckpoint({
+    ...row,
+    project_id: row.project_id || projectId,
+    version_number: row.version_number || versionNumber
+  }, { projectId, versionNumber });
+}
+
+function latestSnapshot(validated) {
+  return {
+    checkpoint: {
+      type: "latest",
+      projectId: String(validated.project.id),
+      versionNumber: validated.versionNumber,
+      componentSetRevision: Number(validated.componentSet.revision),
+      componentChecksum: String(validated.componentSet.component_checksum)
+    },
+    entries: validated.componentRows.map(row => ({
+      ...row,
+      source_revision: row.revision,
+      data_hash: `sha256:${sha256(row.data)}`,
+      changed_from_parent: false
+    }))
+  };
+}
+
+function unsupportedCommand(command, subcommand = "") {
+  const topLevel = new Set(["sql", "database", "migration", "schema", "view", "renderer"]);
+  const component = new Set(["add", "create", "instantiate", "set", "remove", "delete", "reorder", "archive", "enable", "disable", "rename"]);
+  const project = new Set(["create", "delete", "rename", "slug", "transfer", "archive", "restore"]);
+  if (topLevel.has(command) || (command === "component" && component.has(subcommand)) || (command === "project" && project.has(subcommand))) {
+    throw cliError("E_CODE_CHANGE_REQUIRED", "이 작업은 Writer 콘텐츠 CLI의 범위를 벗어납니다. 코드 또는 검토된 migration 작업으로 분리해 주세요.");
+  }
+}
+
+function nowIso(deps) {
+  const value = typeof deps.now === "function" ? deps.now() : new Date();
+  return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+
+function planOptions(deps) {
+  return {
+    planId: typeof deps.randomUUID === "function" ? deps.randomUUID() : crypto.randomUUID(),
+    operationId: typeof deps.randomUUID === "function" ? deps.randomUUID() : crypto.randomUUID(),
+    createdAt: nowIso(deps)
+  };
+}
+
+function latestLoadedFromCorpus(corpus, project) {
+  const componentSet = corpus.componentSetRows.find(row => String(row.project_id) === String(project.id)
+    && String(row.canonical_status) === "active");
+  if (!componentSet) throw cliError("E_MIGRATION_REQUIRED", `${project.slug}의 단일 Latest workspace를 찾을 수 없습니다.`);
+  const versionNumber = Number(componentSet.version_number);
+  const sameWorkspace = row => String(row.project_id) === String(project.id) && Number(row.version_number) === versionNumber;
+  const version = corpus.versionRows.find(sameWorkspace);
+  if (!version) throw cliError("E_VERSION_NOT_FOUND", `${project.slug}의 v${versionNumber}을 찾을 수 없습니다.`);
+  return {
+    project,
+    version,
+    componentSet,
+    componentRows: corpus.componentRows.filter(sameWorkspace),
+    viewRows: corpus.viewRows.filter(sameWorkspace),
+    bindingRows: corpus.bindingRows.filter(sameWorkspace)
+  };
+}
+
+async function execute(argv, deps) {
+  const [command = "help", subcommand = "", ...rest] = argv;
+  if (["help", "--help", "-h"].includes(command)) {
+    const target = command === "help" ? [subcommand, ...rest].filter(Boolean) : [];
+    return { command: "help", data: { scope: normalizeScope(target), help: helpFor(target) } };
+  }
+  if (["--help", "-h"].includes(subcommand)) return { command: "help", data: { scope: command, help: helpFor(command) } };
+  unsupportedCommand(command, subcommand);
+  const topLevelOptionCommand = ["version", "doctor", "read", "search", "sync", "command-schema"].includes(command);
+  const { options, positional } = parseArgs(topLevelOptionCommand ? [subcommand, ...rest].filter(Boolean) : rest);
+  if (!["apply", "validate", "command-schema"].includes(command) && positional.length) throw cliError("E_USAGE", `예상하지 않은 인자입니다: ${positional.join(" ")}`);
+  const commandPath = getCommand(`${command}.${subcommand}`) ? `${command}.${subcommand}` : command;
+  if (options.help) return { command: "help", data: { scope: commandPath, help: helpFor(commandPath) } };
+  if (command === "command-schema") {
+    assertAllowedOptions(options, "command-schema");
+    if (positional.length > 2) throw cliError("E_USAGE", "command-schema에는 group 또는 정확한 leaf 하나만 지정할 수 있습니다.");
+    const scope = positional.length === 2 ? positional.join(".") : (positional[0] || "");
+    return { command: "command-schema", data: commandSchema(scope) };
+  }
+  if (command === "version") {
+    assertAllowedOptions(options, "version");
+    return { command: "version", data: await (deps.versionReport || versionReport)({
+      checkLatest: options.check === true,
+      fetch: deps.fetch,
+      fetchLatest: deps.fetchLatest,
+      computeFingerprint: deps.computeFingerprint,
+      nodeVersion: deps.nodeVersion,
+      platform: deps.platform,
+      arch: deps.arch
+    }) };
+  }
+  if (command === "doctor") {
+    assertAllowedOptions(options, "doctor");
+    return { command: "doctor", data: await (deps.doctorReport || doctorReport)({
+      fs: deps.fs,
+      fetch: deps.fetch,
+      nodeVersion: deps.nodeVersion,
+      platform: deps.platform,
+      computeFingerprint: deps.computeFingerprint,
+      keychainCheck: deps.keychainCheck,
+      credentialStoreCheck: deps.credentialStoreCheck,
+      credentialOptions: deps.credentialOptions,
+      sessionStatus: deps.sessionStatus,
+      healthCheck: deps.healthCheck,
+      probeDaemon: deps.probeDaemon,
+      now: deps.now,
+      checkLatestVersion: deps.enforceUpdates === true,
+      fetchLatest: deps.fetchLatest,
+      currentVersion: deps.currentVersion
+    }) };
+  }
+  if (command === "skills") {
+    if (!getCommand(`skills.${subcommand}`)) throw cliError("E_USAGE", "skills subcommand는 install, status, update, remove 중 하나여야 합니다.");
+    assertAllowedOptions(options, `skills.${subcommand}`);
+    const skillOptions = {
+      target: requireOption(options, "target"),
+      codex: options.codex === true,
+      claude: options.claude === true,
+      dryRun: options["dry-run"] === true,
+      managedOnly: options["managed-only"] === true,
+      fs: deps.fs,
+      payloadRoot: deps.skillPayloadRoot
+    };
+    if (subcommand === "status") return { command: "skills.status", data: (deps.skillStatus || skillStatus)(skillOptions) };
+    if (subcommand === "remove") return { command: "skills.remove", data: (deps.removeManagedSkill || removeManaged)(skillOptions) };
+    return { command: `skills.${subcommand}`, data: (deps.installOrUpdateSkill || installOrUpdate)(skillOptions) };
+  }
+  const registeredCommand = getCommand(commandPath);
+  if (!registeredCommand) throw cliError("E_USAGE", "지원하지 않는 Writer CLI 명령입니다. --help로 명령 목록을 확인해 주세요.");
+  if (deps.enforceUpdates === true && registeredCommand.updatePolicy === "required") {
+    const update = await (deps.updateCheck || checkRequiredUpdate)({
+      currentVersion: deps.currentVersion,
+      fetchLatest: deps.fetchLatest,
+      fetch: deps.fetch,
+      timeoutMs: deps.updateTimeoutMs,
+      ttlMs: deps.updateTtlMs,
+      fs: deps.fs,
+      cacheDir: deps.cacheDir,
+      platform: deps.platform,
+      environment: deps.environment,
+      homeDirectory: deps.homeDirectory,
+      now: deps.now
+    });
+    if (update?.warning) deps.stderr.write(`${JSON.stringify({ warning: { code: "W_CLI_UPDATE_CHECK_UNAVAILABLE", message: update.warning } })}\n`);
+  }
+  const platform = String(deps.platform || process.platform);
+  const authOptions = { ...(deps.authOptions || {}), platform };
+  const auth = deps.auth || createAuthManager(config, authOptions);
+  const gatewayFactory = deps.gatewayFactory || (client => createSupabaseGateway(client, { bucketName: config.assetBucket }));
+  const daemonRequest = deps.requestDaemon || ((method, params, options = {}) => requestWriterService(method, params, {
+    ...options,
+    platform,
+    fs: deps.fs,
+    environment: deps.environment,
+    homeDirectory: deps.homeDirectory,
+    cacheDir: deps.cacheDir,
+    authOptions,
+    gatewayFactory: deps.agentGatewayFactory,
+    indexFactory: deps.indexFactory,
+    realtime: deps.realtime,
+    serviceFactory: deps.serviceFactory
+  }));
+  const daemonStart = deps.startDaemon || startDaemon;
+  const daemonStop = deps.stopDaemon || stopDaemon;
+
+  if (command === "auth") {
+    if (subcommand === "login") {
+      assertAllowedOptions(options, "auth.login");
+      if (platform !== "win32") {
+        try { await daemonStop({ timeoutMs: 5_000 }); }
+        catch (error) { if (error.code !== "E_DAEMON_UNAVAILABLE") throw error; }
+      }
+      const user = await auth.login({
+        openBrowser: options["no-open"] !== true,
+        onUrl: url => { if (options["no-open"] === true) deps.stderr.write(`브라우저에서 다음 URL을 여세요:\n${url}\n`); }
+      });
+      return { command: "auth.login", data: { user } };
+    }
+    if (subcommand === "whoami") {
+      assertAllowedOptions(options, "auth.whoami");
+      return { command: "auth.whoami", data: { user: await auth.whoami() } };
+    }
+    if (subcommand === "logout") {
+      assertAllowedOptions(options, "auth.logout");
+      try {
+        const data = await daemonRequest("writer.logout", {}, { autoStart: false, timeoutMs: 120_000 });
+        return { command: "auth.logout", data };
+      } catch (error) {
+        if (error.code !== "E_DAEMON_UNAVAILABLE") throw error;
+        const data = await auth.logout();
+        const purged = purgeAllAgentIndexes({ fs: deps.fs, platform, environment: deps.environment, homeDirectory: deps.homeDirectory });
+        return { command: "auth.logout", data: { ...data, localIndexPurged: true, removedIndexFiles: purged.removedFiles } };
+      }
+    }
+    throw cliError("E_USAGE", "auth subcommand는 login, whoami, logout 중 하나여야 합니다.");
+  }
+
+  if (command === "agent") {
+    if (subcommand === "start") {
+      assertAllowedOptions(options, "agent.start");
+      if (platform === "win32") throw cliError("E_PLATFORM_UNSUPPORTED", "Windows에서는 background daemon을 지원하지 않습니다. CLI는 안전한 in-process backend를 자동으로 사용합니다.");
+      return { command: "agent.start", data: await daemonStart() };
+    }
+    if (subcommand === "status") {
+      assertAllowedOptions(options, "agent.status");
+      if (platform === "win32") return { command: "agent.status", data: { running: false, supported: false, mode: "in-process" } };
+      try { return { command: "agent.status", data: await daemonRequest("daemon.status", {}, { autoStart: false, timeoutMs: 5_000 }) }; }
+      catch (error) {
+        if (error.code === "E_DAEMON_UNAVAILABLE") return { command: "agent.status", data: { running: false } };
+        throw error;
+      }
+    }
+    if (subcommand === "stop") {
+      assertAllowedOptions(options, "agent.stop");
+      if (platform === "win32") throw cliError("E_PLATFORM_UNSUPPORTED", "Windows에서는 background daemon을 실행하지 않으므로 중지할 daemon이 없습니다.");
+      return { command: "agent.stop", data: await daemonStop() };
+    }
+    if (subcommand === "get") {
+      assertAllowedOptions(options, "agent.get");
+      return { command: "agent.get", data: await daemonRequest("writer.get", {
+        matchId: requireOption(options, "match"),
+        ...(options["max-characters"] !== undefined
+          ? { maximumCharacters: integerValue(options["max-characters"], "--max-characters", 100) }
+          : {})
+      }) };
+    }
+    if (subcommand === "apply") {
+      assertAllowedOptions(options, "agent.apply");
+      return { command: "agent.apply", data: await daemonRequest("writer.apply", {
+        planPath: path.resolve(requireOption(options, "plan")),
+        receiptPath: path.resolve(requireOption(options, "receipt"))
+      }, { timeoutMs: 600_000 }) };
+    }
+    if (subcommand === "purge") {
+      assertAllowedOptions(options, "agent.purge");
+      try { return { command: "agent.purge", data: await daemonRequest("writer.purge", {}, { autoStart: false }) }; }
+      catch (error) {
+        if (error.code !== "E_DAEMON_UNAVAILABLE") throw error;
+        const purged = purgeAllAgentIndexes({ fs: deps.fs, platform, environment: deps.environment, homeDirectory: deps.homeDirectory, cacheDir: deps.cacheDir });
+        return { command: "agent.purge", data: { purged: true, removedIndexFiles: purged.removedFiles, cacheAuthoritative: false } };
+      }
+    }
+    throw cliError("E_USAGE", "agent subcommand는 start, status, stop, get, apply, purge 중 하나여야 합니다.");
+  }
+
+  if (command === "sync") {
+    const parsed = parseArgs([subcommand, ...rest].filter(Boolean));
+    if (parsed.positional.length) throw cliError("E_USAGE", `예상하지 않은 인자입니다: ${parsed.positional.join(" ")}`);
+    assertAllowedOptions(parsed.options, "sync");
+    return { command: "sync", data: await daemonRequest("writer.sync", {}, { timeoutMs: 120_000 }) };
+  }
+
+  if (command === "read") {
+    const parsed = parseArgs([subcommand, ...rest].filter(Boolean));
+    if (parsed.positional.length) throw cliError("E_USAGE", `예상하지 않은 인자입니다: ${parsed.positional.join(" ")}`);
+    assertAllowedOptions(parsed.options, "read");
+    const request = {
+      ...(parsed.options.project !== undefined ? { project: String(parsed.options.project) } : {}),
+      ...(parsed.options.version !== undefined ? { version: integerValue(parsed.options.version, "--version", 1) } : {}),
+      ...(parsed.options.component !== undefined ? { component: String(parsed.options.component) } : {}),
+      ...(parsed.options.pointer !== undefined ? { pointer: String(parsed.options.pointer) } : {}),
+      includeAssets: parsed.options["include-assets"] === true,
+      fresh: parsed.options.fresh === true,
+      requireFresh: parsed.options["require-fresh"] === true
+    };
+    return { command: "read", data: await daemonRequest("writer.read", request, { timeoutMs: 120_000 }) };
+  }
+
+  if (command === "search") {
+    const parsed = parseArgs([subcommand, ...rest].filter(Boolean));
+    if (parsed.positional.length) throw cliError("E_USAGE", `예상하지 않은 인자입니다: ${parsed.positional.join(" ")}`);
+    assertAllowedOptions(parsed.options, "search");
+    const mode = String(parsed.options.mode || (parsed.options["value-json"] !== undefined ? "exact" : "substring"));
+    if (parsed.options.query !== undefined && parsed.options["value-json"] !== undefined) throw cliError("E_USAGE", "--query와 --value-json은 함께 사용할 수 없습니다.");
+    let typedValue;
+    if (parsed.options["value-json"] !== undefined) {
+      try { typedValue = JSON.parse(parsed.options["value-json"]); }
+      catch (error) { throw cliError("E_INVALID_JSON", "--value-json이 올바른 JSON scalar가 아닙니다.", null, error); }
+      if (typedValue !== null && !["string", "number", "boolean"].includes(typeof typedValue)) throw cliError("E_USAGE", "--value-json에는 JSON scalar만 사용할 수 있습니다.");
+    }
+    if (mode !== "all" && parsed.options.query === undefined && parsed.options["value-json"] === undefined) throw cliError("E_USAGE", "--query 또는 --value-json option이 필요합니다.");
+    const search = {
+      ...(parsed.options.query !== undefined ? { query: String(parsed.options.query) } : {}),
+      ...(parsed.options["value-json"] !== undefined ? { value: typedValue } : {}),
+      mode,
+      ...(parsed.options.project ? { project: parsed.options.project } : {}),
+      ...(parsed.options.version ? { version: integerValue(parsed.options.version, "--version", 1) } : {}),
+      ...(parsed.options.component ? { component: parsed.options.component } : {}),
+      ...(parsed.options.path ? { path: parsed.options.path } : {}),
+      ...(parsed.options["path-prefix"] ? { pathPrefix: parsed.options["path-prefix"] } : {}),
+      ...(parsed.options["path-glob"] ? { pathGlob: parsed.options["path-glob"] } : {}),
+      ...(parsed.options.field ? { field: parsed.options.field } : {}),
+      ...(parsed.options["value-type"] ? { valueType: parsed.options["value-type"] } : {}),
+      ...(parsed.options.limit ? { limit: integerValue(parsed.options.limit, "--limit", 1) } : {}),
+      ...(parsed.options.flags ? { flags: parsed.options.flags } : {}),
+      caseSensitive: parsed.options["case-sensitive"] === true,
+      includeAssets: parsed.options["include-assets"] === true,
+      fresh: parsed.options.fresh === true,
+      requireFresh: parsed.options["require-fresh"] === true
+    };
+    return { command: "search", data: await daemonRequest("writer.search", search, { timeoutMs: 120_000 }) };
+  }
+
+  if (command === "component" && subcommand === "plan-replace") {
+    assertAllowedOptions(options, "component.plan-replace");
+    if (options.new === undefined) throw cliError("E_USAGE", "--new option이 필요합니다.");
+    return { command: "component.plan-replace", data: await daemonRequest("writer.plan_replace", {
+      matchId: requireOption(options, "match"),
+      oldText: requireOption(options, "old"),
+      newText: String(options.new),
+      out: path.resolve(requireOption(options, "out")),
+      ...(options.occurrence !== undefined ? { occurrenceIndex: integerValue(options.occurrence, "--occurrence", 0) } : {}),
+      ...(options.message !== undefined ? { checkpointMessage: String(options.message) } : {})
+    }, { timeoutMs: 120_000 }) };
+  }
+
+  return auth.withSession(async ({ client, user }) => {
+    const gateway = gatewayFactory(client);
+    if (command === "project" && subcommand === "list") {
+      assertAllowedOptions(options, "project.list");
+      const status = statusOption(options);
+      return { command: "project.list", data: { status, projects: (await gateway.listProjects(status)).map(publicProject) } };
+    }
+    if (command === "project" && subcommand === "show") {
+      assertAllowedOptions(options, "project.show");
+      const status = statusOption(options);
+      const project = await gateway.getProject(requireOption(options, "project"), status);
+      try { projectRuntime.resolveProject(project); }
+      catch (error) { throw cliError("E_MIGRATION_REQUIRED", error.message, null, error); }
+      const versions = await gateway.listVersions(project.id);
+      return { command: "project.show", data: { project: publicProject(project), versions: versions.map(publicVersion) } };
+    }
+    if (command === "project" && subcommand === "plan-create") {
+      assertAllowedOptions(options, "project.plan-create");
+      const plan = createProjectCreationPlan({
+        slug: requireOption(options, "slug"),
+        title: requireOption(options, "title"),
+        authorName: String(user.displayName || user.email.split("@")[0])
+      }, user.email, planOptions(deps));
+      if (await gateway.findProjectBySlug(plan.target.slug)) {
+        throw cliError("E_CONFLICT", `이미 사용 중인 작품 slug입니다: ${plan.target.slug}`);
+      }
+      const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+      return {
+        command: "project.plan-create",
+        data: {
+          planFile: outputPath,
+          planId: plan.planId,
+          digest: plan.digest,
+          operation: plan.operation,
+          target: plan.target
+        }
+      };
+    }
+    if (command === "project" && subcommand === "plan-import") {
+      assertAllowedOptions(options, "project.plan-import");
+      const imported = loadTrueWriterCase({
+        sourceRoot: requireOption(options, "source-root"),
+        sourceJson: requireOption(options, "source-json"),
+        title: requireOption(options, "title")
+      }, { fs: deps.fs });
+      const plan = createProjectImportPlan({
+        slug: requireOption(options, "slug"),
+        title: imported.title,
+        authorName: String(user.displayName || user.email.split("@")[0]),
+        components: imported.components,
+        source: imported.source,
+        coverage: imported.coverage,
+        assets: imported.assets
+      }, user.email, planOptions(deps));
+      if (await gateway.findProjectBySlug(plan.target.slug)) {
+        throw cliError("E_CONFLICT", `이미 사용 중인 작품 slug입니다: ${plan.target.slug}`);
+      }
+      const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+      return {
+        command: "project.plan-import",
+        data: {
+          planFile: outputPath,
+          planId: plan.planId,
+          digest: plan.digest,
+          operation: plan.operation,
+          target: plan.target,
+          source: {
+            format: plan.source.format,
+            sourceHash: plan.source.sourceHash,
+            sourceGameId: plan.source.sourceGameId,
+            sourceLastModified: plan.source.sourceLastModified,
+            fileCount: plan.source.files.length
+          },
+          coverage: plan.coverage,
+          components: plan.components.map(item => ({ instanceId: item.instanceId, templateId: item.templateId, dataHash: sha256(item.data) })),
+          assets: plan.assets.map(item => ({ assetId: item.assetId, name: item.name, type: item.type, size: item.size, contentHash: item.contentHash }))
+        }
+      };
+    }
+    if (command === "project" && ["plan-archive", "plan-restore"].includes(subcommand)) {
+      assertAllowedOptions(options, `project.${subcommand}`);
+      const operation = subcommand === "plan-archive" ? "project.archive" : "project.restore";
+      const expectedStatus = operation === "project.archive" ? "active" : "archived";
+      const project = await gateway.getProject(requireOption(options, "project"), expectedStatus);
+      const plan = createProjectStatusPlan(project, operation, user.email, planOptions(deps));
+      const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+      return { command: `project.${subcommand}`, data: { planFile: outputPath, planId: plan.planId, digest: plan.digest, operation: plan.operation, project: plan.project, target: plan.target } };
+    }
+    if (command === "project" && subcommand === "plan-set-catalog-demo") {
+      assertAllowedOptions(options, "project.plan-set-catalog-demo");
+      const enabledValue = requireOption(options, "enabled");
+      if (!new Set(["true", "false"]).has(enabledValue)) throw cliError("E_USAGE", "--enabled는 true 또는 false여야 합니다.");
+      const project = await gateway.getProject(requireOption(options, "project"), "active");
+      const plan = createCatalogDemoPlan(project, enabledValue === "true", user.email, planOptions(deps));
+      const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+      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)) {
+      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)) } };
+      }
+      if (subcommand === "plan-layout-investigation-board") {
+        const spec = readJson(requireOption(options, "spec"), "추리 보드 layout spec", deps.fs).value;
+        const layoutPlanOptions = planOptions(deps);
+        if (options.message !== undefined) layoutPlanOptions.checkpointMessage = String(options.message);
+        const plan = createInvestigationBoardLayoutPlan(
+          validated,
+          options.instance || "investigation-board",
+          spec,
+          user.email,
+          layoutPlanOptions
+        );
+        const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+        return {
+          command: "component.plan-layout-investigation-board",
+          data: {
+            planFile: outputPath,
+            planId: plan.planId,
+            digest: plan.digest,
+            operation: plan.operation,
+            checkpointMessage: plan.checkpointMessage,
+            target: plan.target,
+            specHash: plan.layout.specHash,
+            algorithmVersion: plan.layout.algorithmVersion,
+            review: plan.layout.review,
+            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) } };
+      }
+      const patch = readJson(requireOption(options, "patch"), "patch", deps.fs).value;
+      const componentPlanOptions = planOptions(deps);
+      if (options.message !== undefined) componentPlanOptions.checkpointMessage = String(options.message);
+      const plan = createComponentPlan(validated, selector, patch, user.email, componentPlanOptions);
+      const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+      return { command: "component.plan-patch", data: { planFile: outputPath, planId: plan.planId, digest: plan.digest, operation: plan.operation, checkpointMessage: plan.checkpointMessage, target: plan.target, patch: plan.patch, beforeHash: plan.beforeHash, afterHash: plan.afterHash } };
+    }
+
+    if (command === "asset" && ["list", "plan-upload", "plan-delete"].includes(subcommand)) {
+      assertAllowedOptions(options, `asset.${subcommand}`);
+      const projectRef = requireOption(options, "project");
+      const validated = validateLoadedVersion(await gateway.loadLatestVersion(projectRef, optionalVersionOption(options)));
+      const version = validated.versionNumber;
+      const manifest = componentContract.assetManifest(validated.instances);
+      if (subcommand === "list") {
+        const assetInstance = componentContract.assetInstance(validated.instances);
+        return { command: "asset.list", data: { project: publicProject(validated.project, validated.instances), versionNumber: version, revision: assetInstance.revision, assets: manifest.assets } };
+      }
+      const assetId = assertAssetId(requireOption(options, "asset-id"));
+      const operation = subcommand === "plan-upload" ? "asset.upload" : "asset.delete";
+      const optionsForPlan = planOptions(deps);
+      if (options.message !== undefined) optionsForPlan.checkpointMessage = String(options.message);
+      if (operation === "asset.upload") optionsForPlan.file = inspectAssetFile(requireOption(options, "file"), assetId);
+      const plan = createAssetPlan(validated, operation, assetId, user.email, optionsForPlan);
+      const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+      return { command: subcommand === "plan-upload" ? "asset.plan-upload" : "asset.plan-delete", data: { planFile: outputPath, planId: plan.planId, digest: plan.digest, operation: plan.operation, checkpointMessage: plan.checkpointMessage, target: plan.target, file: plan.file || null, previousEntry: plan.previousEntry } };
+    }
+
+    if (command === "checkpoint" && ["list", "status", "show", "diff", "plan-create", "plan-restore"].includes(subcommand)) {
+      assertAllowedOptions(options, `checkpoint.${subcommand}`);
+      const validated = validateLoadedVersion(await gateway.loadLatestVersion(
+        requireOption(options, "project"),
+        optionalVersionOption(options)
+      ));
+      const workspace = {
+        project: publicProject(validated.project, validated.instances),
+        versionNumber: validated.versionNumber
+      };
+      if (subcommand === "list" || subcommand === "status") {
+        const limit = subcommand === "status" ? 1 : integerValue(options.limit || 50, "--limit", 1);
+        if (limit > 100) throw cliError("E_USAGE", "--limit은 100 이하여야 합니다.");
+        const before = options.before === undefined ? null : integerValue(options.before, "--before", 1);
+        const rows = await gateway.listCheckpoints({
+          projectId: validated.project.id,
+          versionNumber: validated.versionNumber,
+          beforeCheckpointNumber: before,
+          limit
+        });
+        const checkpoints = rows.map(row => publicCheckpoint(row, validated.project.id, validated.versionNumber));
+        if (subcommand === "status") {
+          const head = checkpoints[0] || null;
+          return { command: "checkpoint.status", data: { ...workspace, head, latestChanged: head?.latestChanged ?? null } };
+        }
+        return {
+          command: "checkpoint.list",
+          data: {
+            ...workspace,
+            checkpoints,
+            nextBeforeCheckpointNumber: checkpoints.length === limit ? checkpoints.at(-1).number : null
+          }
+        };
+      }
+      if (subcommand === "show") {
+        const snapshot = await gateway.getCheckpointSnapshot(
+          validated.project.id,
+          validated.versionNumber,
+          requireOption(options, "checkpoint"),
+          { includeData: options["include-data"] === true }
+        );
+        snapshot.checkpoint = publicCheckpoint(snapshot.checkpoint, validated.project.id, validated.versionNumber);
+        return { command: "checkpoint.show", data: { ...workspace, ...snapshotSummary(snapshot, options["include-data"] === true) } };
+      }
+      if (subcommand === "diff") {
+        const loadSnapshot = async selector => {
+          if (String(selector).toLowerCase() === "latest") return latestSnapshot(validated);
+          const snapshot = await gateway.getCheckpointSnapshot(validated.project.id, validated.versionNumber, selector, { includeData: true });
+          snapshot.checkpoint = publicCheckpoint(snapshot.checkpoint, validated.project.id, validated.versionNumber);
+          return snapshot;
+        };
+        const [from, to] = await Promise.all([
+          loadSnapshot(requireOption(options, "from")),
+          loadSnapshot(requireOption(options, "to"))
+        ]);
+        return { command: "checkpoint.diff", data: { ...workspace, ...diffSnapshots(from, to, { includeValues: options["include-values"] === true }) } };
+      }
+      const plan = subcommand === "plan-create"
+        ? createCheckpointPlan(validated, "checkpoint.create", requireOption(options, "message"), user.email, planOptions(deps))
+        : createCheckpointPlan(validated, "checkpoint.restore", requireOption(options, "message"), user.email, {
+          ...planOptions(deps),
+          target: await gateway.getCheckpoint(validated.project.id, validated.versionNumber, requireOption(options, "checkpoint"))
+        });
+      const outputPath = writePrivateJson(requireOption(options, "out"), plan, deps.fs);
+      return {
+        command: `checkpoint.${subcommand}`,
+        data: {
+          planFile: outputPath,
+          planId: plan.planId,
+          digest: plan.digest,
+          operation: plan.operation,
+          checkpointMessage: plan.checkpointMessage,
+          ...(plan.target ? { target: plan.target } : {}),
+          readiness: plan.readiness
+        }
+      };
+    }
+
+    if (command === "validate") {
+      const parsed = parseArgs([subcommand, ...rest].filter(Boolean));
+      if (parsed.positional.length) throw cliError("E_USAGE", `예상하지 않은 인자입니다: ${parsed.positional.join(" ")}`);
+      assertAllowedOptions(parsed.options, "validate");
+      const validated = validateLoadedVersion(await gateway.loadLatestVersion(requireOption(parsed.options, "project"), optionalVersionOption(parsed.options)));
+      return { command: "validate", data: { valid: true, project: publicProject(validated.project, validated.instances), versionNumber: validated.versionNumber, componentSetRevision: Number(validated.componentSet.revision), componentChecksum: validated.componentSet.component_checksum, componentCount: validated.instances.length, viewCount: validated.views.length } };
+    }
+
+    if (command === "apply") {
+      const applyTokens = [subcommand, ...rest].filter(Boolean);
+      const parsed = parseArgs(applyTokens);
+      assertAllowedOptions(parsed.options, "apply");
+      if (parsed.positional.length !== 1) throw cliError("E_USAGE", "apply에는 plan 파일 하나가 필요합니다.");
+      const planRead = readJson(parsed.positional[0], "plan", deps.fs);
+      const plan = verifyPlan(planRead.value);
+      const receiptReservation = parsed.options.receipt ? reservePrivateJson(parsed.options.receipt, deps.fs) : null;
+      let receipt;
+      try {
+        if (plan.operation === "project.create") {
+          receipt = await applyProjectCreationPlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
+        } else if (plan.operation === "project.import") {
+          receipt = await applyProjectImportPlan(gateway, plan, user.email, { appliedAt: nowIso(deps), fs: deps.fs });
+        } else if (plan.operation === "project.catalog-demo") {
+          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.patch") {
+          receipt = await applyComponentPlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
+        } else if (plan.operation.startsWith("checkpoint.")) {
+          receipt = await applyCheckpointPlan(gateway, plan, user.email, { appliedAt: nowIso(deps) });
+        } else {
+          receipt = await applyAssetPlan(gateway, plan, user.email, { appliedAt: nowIso(deps), now: deps.timestamp || Date.now, fs: deps.fs });
+        }
+      } catch (error) {
+        receiptReservation?.discard();
+        throw error;
+      }
+      let receiptFile = null;
+      let receiptFileWarning = null;
+      if (receiptReservation) {
+        try { receiptFile = receiptReservation.commit(receipt); }
+        catch (error) {
+          try { receiptReservation.discard(); } catch (discardError) { void discardError; }
+          const normalized = normalizeError(error);
+          receiptFileWarning = { code: normalized.code, message: normalized.message };
+        }
+      }
+      return { command: "apply", data: { planFile: planRead.path, receiptFile, ...(receiptFileWarning ? { receiptFileWarning } : {}), receipt } };
+    }
+
+    throw cliError("E_USAGE", "지원하지 않는 Writer CLI 명령입니다. --help로 명령 목록을 확인해 주세요.");
+  });
+}
+
+async function runCli(argv, providedDeps = {}) {
+  const deps = {
+    stdout: providedDeps.stdout || process.stdout,
+    stderr: providedDeps.stderr || process.stderr,
+    fs: providedDeps.fs || fs,
+    ...providedDeps
+  };
+  const compact = argv.includes("--compact");
+  try {
+    const result = await execute(argv, deps);
+    deps.stdout.write(`${JSON.stringify({ ok: true, ...result }, null, compact ? 0 : 2)}\n`);
+    return 0;
+  } catch (error) {
+    const normalized = normalizeError(error);
+    const payload = {
+      ok: false,
+      error: {
+        code: normalized.code,
+        message: redact(normalized.message),
+        ...(normalized.details ? { details: normalized.details } : {})
+      }
+    };
+    deps.stderr.write(`${JSON.stringify(payload, null, compact ? 0 : 2)}\n`);
+    return normalized.code === "E_USAGE" ? 2 : 1;
+  }
+}
+
+module.exports = Object.freeze({ HELP, parseArgs, readJson, reservePrivateJson, writePrivateJson, execute, runCli });