@ssobig/writer-cli 0.2.0

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

@@ -0,0 +1,83 @@
+"use strict";
+
+const { validateLoadedVersion } = require("./domain.cjs");
+const { normalizeError } = require("./errors.cjs");
+const { sha256 } = require("./json.cjs");
+
+function rowKey(projectId, versionNumber) {
+  return `${String(projectId)}\u0000${Number(versionNumber)}`;
+}
+
+function groupRows(rows) {
+  const grouped = new Map();
+  for (const row of rows || []) {
+    const key = rowKey(row?.project_id, row?.version_number);
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key).push(row);
+  }
+  return grouped;
+}
+
+function buildValidatedSnapshot(corpus, actor, options = {}) {
+  const projects = new Map((corpus?.projects || []).map(project => [String(project.id), project]));
+  const sets = new Map((corpus?.componentSetRows || []).map(row => [rowKey(row.project_id, row.version_number), row]));
+  const components = groupRows(corpus?.componentRows);
+  const views = groupRows(corpus?.viewRows);
+  const bindings = groupRows(corpus?.bindingRows);
+  const versions = [];
+  const rejected = [];
+
+  for (const version of corpus?.versionRows || []) {
+    const project = projects.get(String(version.project_id));
+    const key = rowKey(version.project_id, version.version_number);
+    try {
+      const loaded = {
+        project,
+        version,
+        componentSet: sets.get(key) || null,
+        componentRows: components.get(key) || [],
+        viewRows: views.get(key) || [],
+        bindingRows: bindings.get(key) || []
+      };
+      const validated = validateLoadedVersion(loaded);
+      versions.push(Object.freeze({
+        ...loaded,
+        versionNumber: validated.versionNumber,
+        instances: validated.instances,
+        views: validated.views
+      }));
+    } catch (error) {
+      const normalized = normalizeError(error);
+      rejected.push(Object.freeze({
+        projectId: String(version.project_id || ""),
+        projectSlug: String(project?.slug || ""),
+        versionNumber: Number(version.version_number),
+        code: normalized.code,
+        message: normalized.message
+      }));
+    }
+  }
+
+  const syncedAtValue = typeof options.now === "function" ? options.now() : new Date();
+  const syncedAt = syncedAtValue instanceof Date ? syncedAtValue.toISOString() : new Date(syncedAtValue).toISOString();
+  const revisionVector = versions.map(item => ({
+    projectId: item.project.id,
+    versionNumber: item.versionNumber,
+    componentSetRevision: Number(item.componentSet.revision),
+    componentChecksum: String(item.componentSet.component_checksum)
+  }));
+  return Object.freeze({
+    snapshot: Object.freeze({
+      source: "supabase-authoritative-read",
+      authoritative: false,
+      disposable: true,
+      syncedAt,
+      actor: { id: String(actor?.id || ""), email: String(actor?.email || "") },
+      revisionVectorHash: sha256(revisionVector),
+      versions
+    }),
+    rejected: Object.freeze(rejected)
+  });
+}
+
+module.exports = Object.freeze({ buildValidatedSnapshot, groupRows, rowKey });

package/tools/writer-cli/src/daemon-app.cjs

@@ -0,0 +1,106 @@
+"use strict";
+
+const fs = require("node:fs");
+const { createAgentService } = require("./agent-service.cjs");
+const { resolveAgentPaths, ensurePrivateDirectory } = require("./agent-paths.cjs");
+const { createDaemonServer } = require("./daemon-server.cjs");
+const { cliError } = require("./errors.cjs");
+const { INDEX_SCHEMA_VERSION } = require("./local-index.cjs");
+const { computeSourceFingerprint } = require("./source-fingerprint.cjs");
+const { version: TOOL_VERSION } = require("../package.json");
+const { checkRequiredUpdate } = require("./update-gate.cjs");
+
+const METHOD_MAP = Object.freeze({
+  "writer.sync": "sync",
+  "writer.search": "search",
+  "writer.read": "read",
+  "writer.get": "get",
+  "writer.plan_replace": "planReplace",
+  "writer.apply": "apply",
+  "writer.purge": "purge",
+  "writer.logout": "logout"
+});
+
+async function runDaemon(options = {}) {
+  if (options.enforceUpdates === true) {
+    const update = await (options.updateCheck || checkRequiredUpdate)({
+      currentVersion: TOOL_VERSION,
+      fetchLatest: options.fetchLatest,
+      fetch: options.fetch,
+      timeoutMs: options.updateTimeoutMs,
+      ttlMs: options.updateTtlMs,
+      fs: options.fs,
+      cacheDir: options.cacheDir,
+      platform: options.platform,
+      environment: options.environment,
+      homeDirectory: options.homeDirectory,
+      now: options.now
+    });
+    if (update?.warning) (options.stderr || process.stderr).write(`${JSON.stringify({ warning: { code: "W_CLI_UPDATE_CHECK_UNAVAILABLE", message: update.warning } })}\n`);
+  }
+  const sourceFingerprint = String(options.sourceFingerprint || computeSourceFingerprint());
+  const paths = resolveAgentPaths({ cacheDir: options.cacheDir });
+  ensurePrivateDirectory(paths.cacheDir, options.fs || fs);
+  ensurePrivateDirectory(paths.daemonDir, options.fs || fs);
+  const service = options.service || createAgentService({
+    cacheDir: paths.cacheDir,
+    auth: options.auth,
+    authOptions: options.authOptions,
+    gatewayFactory: options.gatewayFactory,
+    indexFactory: options.indexFactory,
+    realtime: options.realtime
+  });
+  let closing = false;
+  let server;
+
+  async function close() {
+    if (closing) return;
+    closing = true;
+    await server?.close();
+    await service.close();
+  }
+
+  async function handler(request, context) {
+    if (request.method === "daemon.ping") return { running: true, protocol: request.protocol, toolVersion: TOOL_VERSION, indexSchemaVersion: INDEX_SCHEMA_VERSION, sourceFingerprint, pid: process.pid };
+    if (request.method === "daemon.status") return { ...(await service.status()), protocol: request.protocol, toolVersion: TOOL_VERSION, indexSchemaVersion: INDEX_SCHEMA_VERSION, sourceFingerprint };
+    if (request.method === "daemon.shutdown") {
+      setImmediate(() => close().catch(() => {}));
+      return { shuttingDown: true };
+    }
+    const method = METHOD_MAP[request.method];
+    if (!method) throw cliError("E_DAEMON_METHOD", `지원하지 않는 Writer daemon method입니다: ${request.method}`);
+    const result = await service.handle(method, request.params);
+    if (request.method === "writer.logout") {
+      setImmediate(() => close().catch(() => {}));
+    }
+    return result;
+  }
+
+  server = createDaemonServer({
+    cacheDir: paths.daemonDir,
+    socketPath: paths.socketPath,
+    handler,
+    requestLane: request => ["daemon.ping", "daemon.status", "writer.search", "writer.read"].includes(request.method) ? "local-read" : "authoritative-state",
+    requestTimeoutMs: options.requestTimeoutMs || 600_000,
+    closeTimeoutMs: options.closeTimeoutMs
+  });
+  await server.start();
+
+  const signalHandler = () => { close().catch(() => {}); };
+  process.once("SIGINT", signalHandler);
+  process.once("SIGTERM", signalHandler);
+  return Object.freeze({
+    cacheDir: paths.cacheDir,
+    daemonDir: paths.daemonDir,
+    socketPath: paths.socketPath,
+    service,
+    server,
+    close: async () => {
+      process.off("SIGINT", signalHandler);
+      process.off("SIGTERM", signalHandler);
+      await close();
+    }
+  });
+}
+
+module.exports = Object.freeze({ METHOD_MAP, runDaemon });

package/tools/writer-cli/src/daemon-client.cjs

@@ -0,0 +1,187 @@
+"use strict";
+
+const net = require("node:net");
+const { cliError, WriterCliError } = require("./errors.cjs");
+const { resolveDaemonPaths, verifyDaemonEndpoint } = require("./daemon-server.cjs");
+const {
+  PROTOCOL,
+  DEFAULT_MAX_REQUEST_BYTES,
+  DEFAULT_MAX_RESPONSE_BYTES,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  byteLimit,
+  timeoutLimit,
+  requestTimeoutError,
+  createRequest,
+  validateResponse,
+  encodeFrame,
+  parseFrame
+} = require("./daemon-protocol.cjs");
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 5_000;
+
+function createDaemonClient(options = {}) {
+  if (Object.hasOwn(options, "host") || Object.hasOwn(options, "port")) {
+    throw cliError("E_DAEMON_TCP_FORBIDDEN", "Writer daemon은 Unix domain socket만 사용할 수 있습니다.");
+  }
+  const netApi = options.net || net;
+  const paths = resolveDaemonPaths(options);
+  const { socketPath } = paths;
+  const maxRequestBytes = byteLimit(options.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, "maxRequestBytes");
+  const maxResponseBytes = byteLimit(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, "maxResponseBytes");
+  const defaultTimeoutMs = timeoutLimit(options.timeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+  const connectTimeoutMs = timeoutLimit(options.connectTimeoutMs, DEFAULT_CONNECT_TIMEOUT_MS);
+  const pending = new Map();
+  const reservedIds = new Set();
+  let socket = null;
+  let connectPromise = null;
+  let connectingSocket = null;
+  let rejectConnection = null;
+  let responseBuffer = Buffer.alloc(0);
+  let closed = false;
+
+  function rejectAll(error) {
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    pending.clear();
+  }
+
+  function failConnection(error) {
+    const normalized = error?.code?.startsWith?.("E_")
+      ? error
+      : cliError("E_DAEMON_UNAVAILABLE", "Writer daemon 연결이 종료되었습니다.", null, error);
+    rejectAll(normalized);
+    if (socket && !socket.destroyed) socket.destroy();
+    socket = null;
+    connectPromise = null;
+    responseBuffer = Buffer.alloc(0);
+  }
+
+  function receive(chunk) {
+    responseBuffer = Buffer.concat([responseBuffer, chunk]);
+    while (true) {
+      const newline = responseBuffer.indexOf(0x0a);
+      if (newline === -1) {
+        if (responseBuffer.length > maxResponseBytes) failConnection(cliError("E_DAEMON_RESPONSE_TOO_LARGE", "daemon response가 허용 크기를 초과했습니다."));
+        return;
+      }
+      if (newline > maxResponseBytes) {
+        failConnection(cliError("E_DAEMON_RESPONSE_TOO_LARGE", "daemon response가 허용 크기를 초과했습니다."));
+        return;
+      }
+      const frame = responseBuffer.subarray(0, newline);
+      responseBuffer = responseBuffer.subarray(newline + 1);
+      let response;
+      try { response = validateResponse(parseFrame(frame, "response")); }
+      catch (error) { failConnection(error); return; }
+      const entry = pending.get(response.id);
+      if (!entry) continue;
+      pending.delete(response.id);
+      clearTimeout(entry.timer);
+      if (response.ok) entry.resolve(response.result);
+      else entry.reject(new WriterCliError(response.error.code, response.error.message, response.error.details || null));
+    }
+  }
+
+  function connect() {
+    if (closed) return Promise.reject(cliError("E_DAEMON_CLIENT_CLOSED", "닫힌 Writer daemon client는 다시 사용할 수 없습니다."));
+    if (socket && !socket.destroyed && socket.readyState === "open") return Promise.resolve(socket);
+    if (connectPromise) return connectPromise;
+    verifyDaemonEndpoint(paths, { fs: options.fs, uid: options.uid });
+    connectPromise = new Promise((resolve, reject) => {
+      const candidate = netApi.createConnection({ path: socketPath });
+      connectingSocket = candidate;
+      let settled = false;
+      rejectConnection = error => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        candidate.destroy();
+        connectingSocket = null;
+        rejectConnection = null;
+        connectPromise = null;
+        reject(error);
+      };
+      const timer = setTimeout(() => {
+        rejectConnection?.(cliError("E_DAEMON_CONNECT_TIMEOUT", "Writer daemon 연결 시간이 초과되었습니다."));
+      }, connectTimeoutMs);
+      timer.unref?.();
+      candidate.once("connect", () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        socket = candidate;
+        connectingSocket = null;
+        rejectConnection = null;
+        connectPromise = null;
+        candidate.setNoDelay?.(true);
+        candidate.on("data", receive);
+        candidate.once("error", error => failConnection(error));
+        candidate.once("close", () => {
+          if (socket === candidate) failConnection(cliError("E_DAEMON_UNAVAILABLE", "Writer daemon 연결이 종료되었습니다."));
+        });
+        resolve(candidate);
+      });
+      candidate.once("error", error => {
+        if (settled) return;
+        rejectConnection?.(cliError("E_DAEMON_UNAVAILABLE", "Writer daemon에 연결할 수 없습니다.", null, error));
+      });
+    });
+    return connectPromise;
+  }
+
+  async function request(method, params = {}, requestOptions = {}) {
+    if (closed) throw cliError("E_DAEMON_CLIENT_CLOSED", "닫힌 Writer daemon client는 다시 사용할 수 없습니다.");
+    const timeoutMs = timeoutLimit(requestOptions.timeoutMs, defaultTimeoutMs);
+    const requestValue = createRequest(method, params, { id: requestOptions.id, timeoutMs });
+    if (pending.has(requestValue.id) || reservedIds.has(requestValue.id)) throw cliError("E_DAEMON_DUPLICATE_ID", "동일한 daemon request id가 이미 처리 중입니다.");
+    const frame = encodeFrame(requestValue, maxRequestBytes, "request");
+    reservedIds.add(requestValue.id);
+    let activeSocket;
+    try { activeSocket = await connect(); }
+    catch (error) { reservedIds.delete(requestValue.id); throw error; }
+    reservedIds.delete(requestValue.id);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (!pending.delete(requestValue.id)) return;
+        reject(requestTimeoutError(requestValue.id));
+      }, timeoutMs + 100);
+      timer.unref?.();
+      pending.set(requestValue.id, { resolve, reject, timer });
+      activeSocket.write(frame, error => {
+        if (!error) return;
+        const entry = pending.get(requestValue.id);
+        if (!entry) return;
+        pending.delete(requestValue.id);
+        clearTimeout(entry.timer);
+        reject(cliError("E_DAEMON_UNAVAILABLE", "Writer daemon 요청을 보낼 수 없습니다.", null, error));
+      });
+    });
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    rejectAll(cliError("E_DAEMON_CLIENT_CLOSED", "Writer daemon client가 닫혔습니다."));
+    reservedIds.clear();
+    if (rejectConnection) rejectConnection(cliError("E_DAEMON_CLIENT_CLOSED", "Writer daemon client가 닫혔습니다."));
+    else connectingSocket?.destroy();
+    connectingSocket = null;
+    rejectConnection = null;
+    const current = socket;
+    socket = null;
+    connectPromise = null;
+    if (!current || current.destroyed) return;
+    await new Promise(resolve => {
+      const timer = setTimeout(() => { current.destroy(); resolve(); }, 250);
+      timer.unref?.();
+      current.once("close", () => { clearTimeout(timer); resolve(); });
+      current.end();
+    });
+  }
+
+  return Object.freeze({ protocol: PROTOCOL, socketPath, request, close });
+}
+
+module.exports = Object.freeze({ DEFAULT_CONNECT_TIMEOUT_MS, createDaemonClient });

package/tools/writer-cli/src/daemon-protocol.cjs

@@ -0,0 +1,184 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const { TextDecoder } = require("node:util");
+const { cliError, normalizeError, redact } = require("./errors.cjs");
+
+const PROTOCOL = "ssobig-writer-daemon-v1";
+const DEFAULT_MAX_REQUEST_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+const MIN_MESSAGE_BYTES = 256;
+const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
+const MIN_TIMEOUT_MS = 50;
+const MAX_TIMEOUT_MS = 600_000;
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+function byteLimit(value, fallback, label) {
+  const candidate = value === undefined ? fallback : Number(value);
+  if (!Number.isSafeInteger(candidate) || candidate < MIN_MESSAGE_BYTES || candidate > MAX_MESSAGE_BYTES) {
+    throw cliError("E_DAEMON_CONFIG", `${label}은 ${MIN_MESSAGE_BYTES}~${MAX_MESSAGE_BYTES} byte 정수여야 합니다.`);
+  }
+  return candidate;
+}
+
+function timeoutLimit(value, fallback = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const candidate = value === undefined ? fallback : Number(value);
+  if (!Number.isSafeInteger(candidate) || candidate < MIN_TIMEOUT_MS || candidate > MAX_TIMEOUT_MS) {
+    throw cliError("E_DAEMON_CONFIG", `timeout은 ${MIN_TIMEOUT_MS}~${MAX_TIMEOUT_MS}ms 정수여야 합니다.`);
+  }
+  return candidate;
+}
+
+function requestTimeoutError(requestId) {
+  const id = assertRequestId(requestId);
+  return cliError(
+    "E_DAEMON_REQUEST_TIMEOUT",
+    "Writer daemon 요청 처리 시간이 초과되어 최종 결과를 알 수 없습니다. 같은 요청을 자동 재시도하지 마세요.",
+    { requestId: id, outcome: "unknown", doNotRetry: true }
+  );
+}
+
+function isRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function assertRequestId(id) {
+  const value = String(id || "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) {
+    throw cliError("E_DAEMON_PROTOCOL", "daemon request id 형식이 올바르지 않습니다.");
+  }
+  return value;
+}
+
+function assertMethod(method) {
+  const value = String(method || "");
+  if (!/^[a-z][a-z0-9_.:-]{0,127}$/.test(value)) {
+    throw cliError("E_DAEMON_PROTOCOL", "daemon method 형식이 올바르지 않습니다.");
+  }
+  return value;
+}
+
+function createRequest(method, params = {}, options = {}) {
+  if (!isRecord(params)) throw cliError("E_DAEMON_PROTOCOL", "daemon params는 JSON object여야 합니다.");
+  return {
+    protocol: PROTOCOL,
+    id: assertRequestId(options.id || crypto.randomUUID()),
+    method: assertMethod(method),
+    params,
+    timeoutMs: timeoutLimit(options.timeoutMs)
+  };
+}
+
+function validateRequest(value) {
+  if (!isRecord(value) || value.protocol !== PROTOCOL) {
+    throw cliError("E_DAEMON_PROTOCOL", "지원하지 않는 daemon protocol입니다.");
+  }
+  if (!isRecord(value.params)) throw cliError("E_DAEMON_PROTOCOL", "daemon params는 JSON object여야 합니다.");
+  const allowed = new Set(["protocol", "id", "method", "params", "timeoutMs"]);
+  const unknown = Object.keys(value).find(key => !allowed.has(key));
+  if (unknown) throw cliError("E_DAEMON_PROTOCOL", `지원하지 않는 daemon request 필드입니다: ${unknown}`);
+  return {
+    protocol: PROTOCOL,
+    id: assertRequestId(value.id),
+    method: assertMethod(value.method),
+    params: value.params,
+    timeoutMs: timeoutLimit(value.timeoutMs)
+  };
+}
+
+function successResponse(id, result) {
+  return { protocol: PROTOCOL, id: assertRequestId(id), ok: true, result: result === undefined ? null : result };
+}
+
+function sanitizeValue(value, key = "", depth = 0) {
+  if (/token|authorization|cookie|session/i.test(key)) return "[REDACTED]";
+  if (depth > 20) return "[REDACTED_DEPTH]";
+  if (typeof value === "string") return redact(value);
+  if (Array.isArray(value)) return value.map(item => sanitizeValue(item, "", depth + 1));
+  if (isRecord(value)) {
+    const output = {};
+    for (const [childKey, childValue] of Object.entries(value)) output[childKey] = sanitizeValue(childValue, childKey, depth + 1);
+    return output;
+  }
+  if (value === null || ["boolean", "number"].includes(typeof value)) return value;
+  return String(value ?? "");
+}
+
+function errorResponse(id, error) {
+  const normalized = normalizeError(error);
+  return {
+    protocol: PROTOCOL,
+    id: id === null ? null : assertRequestId(id),
+    ok: false,
+    error: {
+      code: normalized.code,
+      message: redact(normalized.message),
+      ...(normalized.details ? { details: sanitizeValue(normalized.details) } : {})
+    }
+  };
+}
+
+function validateResponse(value) {
+  if (!isRecord(value) || value.protocol !== PROTOCOL || typeof value.ok !== "boolean") {
+    throw cliError("E_DAEMON_PROTOCOL", "daemon response 형식이 올바르지 않습니다.");
+  }
+  const id = assertRequestId(value.id);
+  if (value.ok) {
+    if (!Object.hasOwn(value, "result")) throw cliError("E_DAEMON_PROTOCOL", "daemon success response에 result가 없습니다.");
+    return { protocol: PROTOCOL, id, ok: true, result: value.result };
+  }
+  if (!isRecord(value.error) || !/^E_[A-Z0-9_]+$/.test(String(value.error.code || "")) || typeof value.error.message !== "string") {
+    throw cliError("E_DAEMON_PROTOCOL", "daemon error response 형식이 올바르지 않습니다.");
+  }
+  return { protocol: PROTOCOL, id, ok: false, error: value.error };
+}
+
+function encodeFrame(value, maxBytes, kind = "message") {
+  let json;
+  try { json = JSON.stringify(value); }
+  catch (error) { throw cliError("E_DAEMON_PROTOCOL", `daemon ${kind}를 JSON으로 만들 수 없습니다.`, null, error); }
+  if (json === undefined) throw cliError("E_DAEMON_PROTOCOL", `daemon ${kind}를 JSON으로 만들 수 없습니다.`);
+  const frame = Buffer.from(`${json}\n`, "utf8");
+  if (frame.length - 1 > maxBytes) {
+    const code = kind === "request" ? "E_DAEMON_REQUEST_TOO_LARGE" : "E_DAEMON_RESPONSE_TOO_LARGE";
+    throw cliError(code, `daemon ${kind}가 허용 크기를 초과했습니다.`);
+  }
+  return frame;
+}
+
+function parseFrame(buffer, kind = "message") {
+  let source;
+  try { source = utf8Decoder.decode(buffer); }
+  catch (error) { throw cliError("E_DAEMON_PROTOCOL", `daemon ${kind}가 UTF-8이 아닙니다.`, null, error); }
+  if (source.endsWith("\r")) source = source.slice(0, -1);
+  if (!source) throw cliError("E_DAEMON_PROTOCOL", `비어 있는 daemon ${kind}입니다.`);
+  try { return JSON.parse(source); }
+  catch (error) { throw cliError("E_DAEMON_PROTOCOL", `daemon ${kind} JSON이 올바르지 않습니다.`, null, error); }
+}
+
+module.exports = Object.freeze({
+  PROTOCOL,
+  DEFAULT_MAX_REQUEST_BYTES,
+  DEFAULT_MAX_RESPONSE_BYTES,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  MIN_MESSAGE_BYTES,
+  MAX_MESSAGE_BYTES,
+  MIN_TIMEOUT_MS,
+  MAX_TIMEOUT_MS,
+  byteLimit,
+  timeoutLimit,
+  requestTimeoutError,
+  isRecord,
+  assertRequestId,
+  assertMethod,
+  createRequest,
+  validateRequest,
+  successResponse,
+  errorResponse,
+  validateResponse,
+  encodeFrame,
+  parseFrame
+});

package/tools/writer-cli/src/daemon-runner.cjs

@@ -0,0 +1,97 @@
+"use strict";
+
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { setTimeout: delay } = require("node:timers/promises");
+const { createDaemonClient } = require("./daemon-client.cjs");
+const { resolveAgentPaths } = require("./agent-paths.cjs");
+const { cliError } = require("./errors.cjs");
+const { INDEX_SCHEMA_VERSION } = require("./local-index.cjs");
+const { computeSourceFingerprint } = require("./source-fingerprint.cjs");
+const { version: TOOL_VERSION } = require("../package.json");
+
+const DAEMON_BIN = path.resolve(__dirname, "../bin/ssobig-writer-daemon.cjs");
+const CACHE_ENV = "SSOBIG_WRITER_AGENT_CACHE_DIR";
+
+function effectiveCacheDir(options = {}, environment = process.env) {
+  return options.cacheDir || environment[CACHE_ENV] || undefined;
+}
+
+function daemonClient(options = {}) {
+  const paths = resolveAgentPaths({ cacheDir: effectiveCacheDir(options) });
+  return createDaemonClient({ cacheDir: paths.daemonDir, socketPath: paths.socketPath, timeoutMs: options.timeoutMs });
+}
+
+async function probeDaemon(options = {}) {
+  const expectedSourceFingerprint = String(options.sourceFingerprint || computeSourceFingerprint());
+  const client = daemonClient({ ...options, timeoutMs: options.timeoutMs || 1_000 });
+  try {
+    const result = await client.request("daemon.ping", {}, { timeoutMs: options.timeoutMs || 1_000 });
+    if (result?.toolVersion !== TOOL_VERSION
+      || result?.indexSchemaVersion !== INDEX_SCHEMA_VERSION
+      || result?.sourceFingerprint !== expectedSourceFingerprint) {
+      throw cliError("E_DAEMON_VERSION_MISMATCH", "실행 중인 Writer daemon과 현재 CLI source 계약이 다릅니다.", {
+        expectedToolVersion: TOOL_VERSION,
+        actualToolVersion: result?.toolVersion || null,
+        expectedIndexSchemaVersion: INDEX_SCHEMA_VERSION,
+        actualIndexSchemaVersion: result?.indexSchemaVersion || null,
+        expectedSourceFingerprint,
+        actualSourceFingerprint: result?.sourceFingerprint || null
+      });
+    }
+    return result;
+  }
+  finally { await client.close(); }
+}
+
+async function startDaemon(options = {}) {
+  try { return { alreadyRunning: true, ...(await probeDaemon({ ...options, timeoutMs: 250 })) }; }
+  catch (error) {
+    if (error.code === "E_DAEMON_VERSION_MISMATCH") await stopDaemon({ ...options, timeoutMs: 120_000 });
+    else
+    if (!["E_DAEMON_UNAVAILABLE", "E_DAEMON_CONNECT_TIMEOUT"].includes(error.code)) throw error;
+  }
+  const child = (options.spawn || spawn)(process.execPath, [DAEMON_BIN, "--foreground"], {
+    detached: true,
+    shell: false,
+    stdio: "ignore",
+    env: { ...process.env, ...(effectiveCacheDir(options) ? { [CACHE_ENV]: path.resolve(String(effectiveCacheDir(options))) } : {}) }
+  });
+  child.unref?.();
+  const deadline = Date.now() + Math.max(500, Number(options.startTimeoutMs || 5_000));
+  let lastError = null;
+  while (Date.now() < deadline) {
+    await delay(50);
+    try { return { alreadyRunning: false, ...(await probeDaemon({ ...options, timeoutMs: 250 })) }; }
+    catch (error) { lastError = error; }
+  }
+  throw cliError("E_DAEMON_START", "Writer daemon이 시간 안에 시작되지 않았습니다.", null, lastError);
+}
+
+async function requestDaemon(method, params = {}, options = {}) {
+  if (options.autoStart !== false) await startDaemon(options);
+  const client = daemonClient(options);
+  try { return await client.request(method, params, { timeoutMs: options.timeoutMs }); }
+  catch (error) {
+    if (method === "writer.apply" && error.code === "E_DAEMON_REQUEST_TIMEOUT") {
+      throw cliError("E_AMBIGUOUS_SAVE", "daemon apply 결과를 시간 안에 확인하지 못했습니다. 같은 plan을 재적용하지 말고 receipt와 서버 원본을 확인해 주세요.", {
+        ...(error.details || {}),
+        readBackRequired: true,
+        doNotRetry: true
+      }, error);
+    }
+    throw error;
+  }
+  finally { await client.close(); }
+}
+
+async function stopDaemon(options = {}) {
+  const client = daemonClient({ ...options, timeoutMs: options.timeoutMs || 5_000 });
+  try { return await client.request("daemon.shutdown", {}, { timeoutMs: options.timeoutMs || 5_000 }); }
+  catch (error) {
+    if (error.code === "E_DAEMON_UNAVAILABLE") return { running: false };
+    throw error;
+  } finally { await client.close(); }
+}
+
+module.exports = Object.freeze({ DAEMON_BIN, CACHE_ENV, effectiveCacheDir, daemonClient, probeDaemon, startDaemon, requestDaemon, stopDaemon });