@ssobig/writer-cli 0.2.0

package/tools/writer-cli/src/investigation-board-layout.cjs

@@ -0,0 +1,328 @@
+"use strict";
+
+const { sha256 } = require("./json.cjs");
+const { cliError } = require("./errors.cjs");
+
+const SPEC_SCHEMA_VERSION = "ssobig-investigation-board-layout-v1";
+const ALGORITHM_VERSION = "hub-clusters-v1";
+const VIEWPORT = Object.freeze({ width: 10000, height: 10000 });
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const BAND_ORDER = Object.freeze(["top", "left", "center", "right", "bottom"]);
+const BAND_RECTS = Object.freeze({
+  top: Object.freeze({ x: 3600, y: 3000, width: 2800, height: 800, columns: 4, capacity: 8 }),
+  left: Object.freeze({ x: 2800, y: 4100, width: 1600, height: 1600, columns: 2, capacity: 8 }),
+  center: Object.freeze({ x: 4400, y: 4000, width: 1200, height: 1800, columns: 2, capacity: 6 }),
+  right: Object.freeze({ x: 5600, y: 4100, width: 1600, height: 1600, columns: 2, capacity: 8 }),
+  bottom: Object.freeze({ x: 3600, y: 6000, width: 2800, height: 900, columns: 4, capacity: 8 })
+});
+const NODE_COLORS = Object.freeze({
+  character: "#d5e8ff",
+  evidence: "#e2ccff",
+  question: "#ffe58f",
+  allegation: "#ffcfb3",
+  fact: "#c9f7c2",
+  context: "#d9dde3"
+});
+const EDGE_COLORS = Object.freeze({
+  context: "#8a929d",
+  evidence: "#7b83a0",
+  claim: "#c56f46",
+  causal: "#8f6f2f",
+  primary: "#4f6475"
+});
+const EDGE_KIND_ORDER = Object.freeze(["context", "evidence", "claim", "causal", "primary"]);
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function fail(message, details = null) {
+  throw cliError("E_VALIDATION", message, details);
+}
+
+function assertKeys(value, allowed, label) {
+  if (!isObject(value)) fail(`${label}은 객체여야 합니다.`);
+  const unknown = Object.keys(value).find(key => !allowed.includes(key));
+  if (unknown) fail(`${label}.${unknown}은 지원되지 않는 필드입니다.`);
+}
+
+function requiredString(value, label, maximum) {
+  if (typeof value !== "string" || !value.trim() || value.length > maximum) fail(`${label}은 비어 있지 않은 ${maximum}자 이하 문자열이어야 합니다.`);
+  return value;
+}
+
+function requiredId(value, label) {
+  const id = requiredString(value, label, 128);
+  if (!ID_PATTERN.test(id)) fail(`${label} 형식이 올바르지 않습니다.`);
+  return id;
+}
+
+function requiredOrder(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > 999) fail(`${label}는 0~999 정수여야 합니다.`);
+  return value;
+}
+
+function countBy(values) {
+  const result = {};
+  for (const value of values) result[value] = (result[value] || 0) + 1;
+  return Object.fromEntries(Object.entries(result).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+function normalizeReferences(references) {
+  if (!Array.isArray(references)) fail("추리 보드 참조 목록이 필요합니다.");
+  const output = new Set();
+  for (const reference of references) {
+    if (!isObject(reference) || !["character", "clue"].includes(reference.type) || typeof reference.id !== "string" || !reference.id.trim()) {
+      fail("추리 보드 참조 목록에 올바르지 않은 항목이 있습니다.");
+    }
+    output.add(`${reference.type}:${reference.id}`);
+  }
+  return output;
+}
+
+function normalizeSpec(input, references) {
+  assertKeys(input, ["schemaVersion", "layout", "clusters", "nodes", "edges"], "layout spec");
+  if (input.schemaVersion !== SPEC_SCHEMA_VERSION) fail(`layout spec.schemaVersion은 ${SPEC_SCHEMA_VERSION}이어야 합니다.`);
+  if (input.layout !== "hub-clusters") fail("layout spec.layout은 hub-clusters여야 합니다.");
+  if (!Array.isArray(input.clusters) || input.clusters.length < 2 || input.clusters.length > BAND_ORDER.length) {
+    fail(`clusters는 2~${BAND_ORDER.length}개여야 합니다.`);
+  }
+  if (!Array.isArray(input.nodes) || input.nodes.length < 2 || input.nodes.length > 38) fail("nodes는 2~38개여야 합니다.");
+  if (!Array.isArray(input.edges) || input.edges.length < 1 || input.edges.length > 120) fail("edges는 1~120개여야 합니다.");
+
+  const clusterIds = new Set();
+  const bands = new Set();
+  const clusters = input.clusters.map((cluster, index) => {
+    assertKeys(cluster, ["id", "label", "band"], `clusters.${index}`);
+    const id = requiredId(cluster.id, `clusters.${index}.id`);
+    const label = requiredString(cluster.label, `clusters.${index}.label`, 60);
+    if (!BAND_ORDER.includes(cluster.band)) fail(`clusters.${index}.band가 올바르지 않습니다.`);
+    if (clusterIds.has(id)) fail(`중복된 cluster id입니다: ${id}`);
+    if (bands.has(cluster.band)) fail(`하나의 band에는 cluster를 하나만 둘 수 있습니다: ${cluster.band}`);
+    clusterIds.add(id);
+    bands.add(cluster.band);
+    return { id, label, band: cluster.band };
+  });
+  if (!bands.has("center")) fail("hub-clusters 배치에는 center cluster가 필요합니다.");
+
+  const referenceSet = normalizeReferences(references);
+  const nodeIds = new Set();
+  const clusterOrders = new Map();
+  const nodes = input.nodes.map((node, index) => {
+    if (!isObject(node)) fail(`nodes.${index}는 객체여야 합니다.`);
+    const common = ["id", "type", "clusterId", "order", "importance", "semantic"];
+    const fields = node.type === "reference"
+      ? [...common, "referenceType", "referenceId"]
+      : node.type === "sticky" ? [...common, "title", "text"] : common;
+    assertKeys(node, fields, `nodes.${index}`);
+    const id = requiredId(node.id, `nodes.${index}.id`);
+    if (nodeIds.has(id)) fail(`중복된 node id입니다: ${id}`);
+    nodeIds.add(id);
+    if (!clusterIds.has(node.clusterId)) fail(`nodes.${index}.clusterId가 존재하지 않습니다: ${node.clusterId}`);
+    const order = requiredOrder(node.order, `nodes.${index}.order`);
+    const orderKey = `${node.clusterId}:${order}`;
+    if (clusterOrders.has(orderKey)) fail(`cluster 안에서 node order가 중복됩니다: ${orderKey}`);
+    clusterOrders.set(orderKey, id);
+    if (!["primary", "secondary"].includes(node.importance)) fail(`nodes.${index}.importance는 primary 또는 secondary여야 합니다.`);
+    if (!Object.hasOwn(NODE_COLORS, node.semantic)) fail(`nodes.${index}.semantic이 올바르지 않습니다.`);
+    if (node.type === "reference") {
+      if (!["character", "clue"].includes(node.referenceType)) fail(`nodes.${index}.referenceType이 올바르지 않습니다.`);
+      const referenceId = requiredString(node.referenceId, `nodes.${index}.referenceId`, 200);
+      if (!referenceSet.has(`${node.referenceType}:${referenceId}`)) fail(`작품에서 찾을 수 없는 참조입니다: ${node.referenceType}:${referenceId}`);
+      if (node.referenceType === "character" && node.semantic !== "character") fail(`캐릭터 reference node의 semantic은 character여야 합니다: ${id}`);
+      if (node.referenceType === "clue" && node.semantic === "character") fail(`단서 reference node는 character semantic을 사용할 수 없습니다: ${id}`);
+      return { id, type: node.type, clusterId: node.clusterId, order, importance: node.importance, semantic: node.semantic, referenceType: node.referenceType, referenceId };
+    }
+    if (node.type !== "sticky") fail(`nodes.${index}.type은 reference 또는 sticky여야 합니다.`);
+    if (node.semantic === "character") fail(`포스트잇은 character semantic을 사용할 수 없습니다: ${id}`);
+    const title = typeof node.title === "string" && node.title.length <= 120 ? node.title : fail(`nodes.${index}.title은 120자 이하 문자열이어야 합니다.`);
+    const text = typeof node.text === "string" && node.text.length <= 5000 ? node.text : fail(`nodes.${index}.text는 5000자 이하 문자열이어야 합니다.`);
+    return { id, type: node.type, clusterId: node.clusterId, order, importance: node.importance, semantic: node.semantic, title, text };
+  });
+
+  for (const cluster of clusters) {
+    const count = nodes.filter(node => node.clusterId === cluster.id).length;
+    if (!count) fail(`비어 있는 cluster는 사용할 수 없습니다: ${cluster.id}`);
+    if (count > BAND_RECTS[cluster.band].capacity) fail(`${cluster.band} cluster는 node를 최대 ${BAND_RECTS[cluster.band].capacity}개까지 배치할 수 있습니다.`);
+  }
+
+  const edgeIds = new Set();
+  const edgeOrders = new Set();
+  const edges = input.edges.map((edge, index) => {
+    assertKeys(edge, ["id", "fromNodeId", "toNodeId", "order", "direction", "label", "kind"], `edges.${index}`);
+    const id = requiredId(edge.id, `edges.${index}.id`);
+    if (edgeIds.has(id)) fail(`중복된 edge id입니다: ${id}`);
+    edgeIds.add(id);
+    const order = requiredOrder(edge.order, `edges.${index}.order`);
+    if (edgeOrders.has(order)) fail(`edge order가 중복됩니다: ${order}`);
+    edgeOrders.add(order);
+    if (!nodeIds.has(edge.fromNodeId) || !nodeIds.has(edge.toNodeId) || edge.fromNodeId === edge.toNodeId) fail(`edges.${index}의 연결 node가 올바르지 않습니다.`);
+    if (!["none", "forward", "both"].includes(edge.direction)) fail(`edges.${index}.direction이 올바르지 않습니다.`);
+    const label = requiredString(edge.label, `edges.${index}.label`, 200);
+    if (!Object.hasOwn(EDGE_COLORS, edge.kind)) fail(`edges.${index}.kind가 올바르지 않습니다.`);
+    return { id, fromNodeId: edge.fromNodeId, toNodeId: edge.toNodeId, order, direction: edge.direction, label, kind: edge.kind };
+  });
+
+  return { schemaVersion: SPEC_SCHEMA_VERSION, layout: "hub-clusters", clusters, nodes, edges };
+}
+
+function nodeSize(node) {
+  if (node.type === "reference" && node.referenceType === "character") return node.importance === "primary" ? { width: 360, height: 280 } : { width: 320, height: 240 };
+  if (node.type === "reference") return node.importance === "primary" ? { width: 320, height: 200 } : { width: 300, height: 180 };
+  return node.importance === "primary" ? { width: 360, height: 220 } : { width: 320, height: 200 };
+}
+
+function positionCluster(cluster, sourceNodes) {
+  const rect = BAND_RECTS[cluster.band];
+  const nodes = sourceNodes.slice().sort((left, right) => left.order - right.order || left.id.localeCompare(right.id));
+  const sized = nodes.map(node => ({ ...node, ...nodeSize(node) }));
+  const columns = Math.min(rect.columns, sized.length);
+  const rows = Math.ceil(sized.length / columns);
+  const cellWidth = Math.max(...sized.map(node => node.width)) + 120;
+  const cellHeight = Math.max(...sized.map(node => node.height)) + 120;
+  const gridWidth = columns * cellWidth - 120;
+  const gridHeight = rows * cellHeight - 120;
+  const startX = Math.round(rect.x + (rect.width - gridWidth) / 2);
+  const startY = Math.round(rect.y + (rect.height - gridHeight) / 2);
+  return sized.map((node, index) => {
+    const column = index % columns;
+    const row = Math.floor(index / columns);
+    const x = Math.round(startX + column * cellWidth + (cellWidth - 120 - node.width) / 2);
+    const y = Math.round(startY + row * cellHeight + (cellHeight - 120 - node.height) / 2);
+    const common = { id: node.id, type: node.type, x, y, width: node.width, height: node.height, color: NODE_COLORS[node.semantic] };
+    return node.type === "reference"
+      ? { ...common, referenceType: node.referenceType, referenceId: node.referenceId }
+      : { ...common, title: node.title, text: node.text };
+  });
+}
+
+function center(node) {
+  return { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+}
+
+function orientation(a, b, c) {
+  return (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+}
+
+function segmentsCross(first, second) {
+  const a = first.from;
+  const b = first.to;
+  const c = second.from;
+  const d = second.to;
+  return orientation(a, b, c) * orientation(a, b, d) < 0 && orientation(c, d, a) * orientation(c, d, b) < 0;
+}
+
+function segmentIntersectsRect(segment, node, padding = 20) {
+  const left = node.x - padding;
+  const right = node.x + node.width + padding;
+  const top = node.y - padding;
+  const bottom = node.y + node.height + padding;
+  let minimum = 0;
+  let maximum = 1;
+  const dx = segment.to.x - segment.from.x;
+  const dy = segment.to.y - segment.from.y;
+  for (const [p, q] of [[-dx, segment.from.x - left], [dx, right - segment.from.x], [-dy, segment.from.y - top], [dy, bottom - segment.from.y]]) {
+    if (p === 0 && q < 0) return false;
+    if (p === 0) continue;
+    const ratio = q / p;
+    if (p < 0) minimum = Math.max(minimum, ratio);
+    else maximum = Math.min(maximum, ratio);
+    if (minimum > maximum) return false;
+  }
+  return true;
+}
+
+function layoutReview(spec, nodes, edges) {
+  const nodesById = new Map(nodes.map(node => [node.id, node]));
+  const segments = edges.map(edge => ({
+    edge,
+    from: center(nodesById.get(edge.fromNodeId)),
+    to: center(nodesById.get(edge.toNodeId))
+  }));
+  let crossingCount = 0;
+  for (let left = 0; left < segments.length; left += 1) {
+    for (let right = left + 1; right < segments.length; right += 1) {
+      const first = segments[left].edge;
+      const second = segments[right].edge;
+      if ([first.fromNodeId, first.toNodeId].some(id => id === second.fromNodeId || id === second.toNodeId)) continue;
+      if (segmentsCross(segments[left], segments[right])) crossingCount += 1;
+    }
+  }
+  let edgeNodeOverlapCount = 0;
+  for (const segment of segments) {
+    for (const node of nodes) {
+      if (node.id === segment.edge.fromNodeId || node.id === segment.edge.toNodeId) continue;
+      if (segmentIntersectsRect(segment, node)) edgeNodeOverlapCount += 1;
+    }
+  }
+  const degrees = new Map(nodes.map(node => [node.id, 0]));
+  for (const edge of edges) {
+    degrees.set(edge.fromNodeId, degrees.get(edge.fromNodeId) + 1);
+    degrees.set(edge.toNodeId, degrees.get(edge.toNodeId) + 1);
+  }
+  const orphanNodeIds = [...degrees].filter(([, degree]) => degree === 0).map(([id]) => id).sort();
+  const longEdgeCount = segments.filter(segment => Math.hypot(segment.to.x - segment.from.x, segment.to.y - segment.from.y) > 2200).length;
+  const primaryEdgeCount = spec.edges.filter(edge => edge.kind === "primary").length;
+  const warnings = [];
+  if (crossingCount) warnings.push(`관계선 교차 ${crossingCount}건: node order나 cluster band를 조정하세요.`);
+  if (edgeNodeOverlapCount) warnings.push(`다른 카드를 통과하는 관계선 ${edgeNodeOverlapCount}건: 관련 node를 같은 cluster에 가깝게 배치하세요.`);
+  if (longEdgeCount) warnings.push(`2,200px보다 긴 관계선 ${longEdgeCount}건: 보조 사건 node로 인과 흐름을 나누는 것을 검토하세요.`);
+  if (orphanNodeIds.length) warnings.push(`연결되지 않은 node ${orphanNodeIds.length}개: ${orphanNodeIds.join(", ")}`);
+  if (primaryEdgeCount > 7) warnings.push(`핵심 관계선이 ${primaryEdgeCount}개입니다. 전체 보기에는 7개 이하를 권장합니다.`);
+  if (nodes.length > 24) warnings.push(`node가 ${nodes.length}개입니다. 전체 보기와 상세 보드를 분리하는 것을 검토하세요.`);
+  const left = Math.min(...nodes.map(node => node.x));
+  const top = Math.min(...nodes.map(node => node.y));
+  const right = Math.max(...nodes.map(node => node.x + node.width));
+  const bottom = Math.max(...nodes.map(node => node.y + node.height));
+  const penalty = Math.min(35, crossingCount * 5)
+    + Math.min(30, edgeNodeOverlapCount * 5)
+    + Math.min(15, longEdgeCount * 2)
+    + Math.min(20, orphanNodeIds.length * 10)
+    + Math.max(0, primaryEdgeCount - 7) * 3;
+  return {
+    algorithmVersion: ALGORITHM_VERSION,
+    qualityScore: Math.max(0, 100 - penalty),
+    nodeCount: nodes.length,
+    nodeTypes: countBy(nodes.map(node => node.type === "sticky" ? "sticky" : node.referenceType)),
+    edgeCount: edges.length,
+    edgeKinds: countBy(spec.edges.map(edge => edge.kind)),
+    edgeDirections: countBy(edges.map(edge => edge.direction)),
+    clusters: spec.clusters
+      .slice().sort((leftCluster, rightCluster) => BAND_ORDER.indexOf(leftCluster.band) - BAND_ORDER.indexOf(rightCluster.band))
+      .map(cluster => ({ id: cluster.id, label: cluster.label, band: cluster.band, nodeIds: spec.nodes.filter(node => node.clusterId === cluster.id).sort((leftNode, rightNode) => leftNode.order - rightNode.order).map(node => node.id) })),
+    contentBounds: { x: left, y: top, width: right - left, height: bottom - top },
+    crossingCount,
+    edgeNodeOverlapCount,
+    longEdgeCount,
+    orphanNodeIds,
+    warnings
+  };
+}
+
+function layoutInvestigationBoard(input, references) {
+  const spec = normalizeSpec(input, references);
+  const clusterByBand = new Map(spec.clusters.map(cluster => [cluster.band, cluster]));
+  const nodes = BAND_ORDER.flatMap(band => {
+    const cluster = clusterByBand.get(band);
+    return cluster ? positionCluster(cluster, spec.nodes.filter(node => node.clusterId === cluster.id)) : [];
+  });
+  const edges = spec.edges
+    .slice()
+    .sort((left, right) => EDGE_KIND_ORDER.indexOf(left.kind) - EDGE_KIND_ORDER.indexOf(right.kind) || left.order - right.order || left.id.localeCompare(right.id))
+    .map(edge => ({ id: edge.id, fromNodeId: edge.fromNodeId, toNodeId: edge.toNodeId, direction: edge.direction, label: edge.label, color: EDGE_COLORS[edge.kind] }));
+  return Object.freeze({
+    spec,
+    specHash: sha256(spec),
+    data: { viewport: { ...VIEWPORT }, nodes, edges },
+    review: layoutReview(spec, nodes, edges)
+  });
+}
+
+module.exports = Object.freeze({
+  SPEC_SCHEMA_VERSION,
+  ALGORITHM_VERSION,
+  VIEWPORT,
+  NODE_COLORS,
+  EDGE_COLORS,
+  layoutInvestigationBoard
+});

package/tools/writer-cli/src/json-patch.cjs

@@ -0,0 +1,98 @@
+"use strict";
+
+const { clone, equalJson } = require("./json.cjs");
+const { cliError } = require("./errors.cjs");
+
+const FORBIDDEN_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+function pointerSegments(pointer) {
+  if (pointer === "") return [];
+  if (typeof pointer !== "string" || !pointer.startsWith("/")) {
+    throw cliError("E_INVALID_PATCH", `JSON Pointer가 올바르지 않습니다: ${String(pointer)}`);
+  }
+  return pointer.slice(1).split("/").map(segment => {
+    if (/~(?![01])/u.test(segment)) throw cliError("E_INVALID_PATCH", `JSON Pointer escape가 올바르지 않습니다: ${pointer}`);
+    const decoded = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (FORBIDDEN_SEGMENTS.has(decoded)) throw cliError("E_INVALID_PATCH", `안전하지 않은 JSON Pointer segment입니다: ${decoded}`);
+    return decoded;
+  });
+}
+
+function arrayIndex(segment, length, options = {}) {
+  if (options.append && segment === "-") return length;
+  if (!/^(0|[1-9][0-9]*)$/.test(segment)) throw cliError("E_INVALID_PATCH", `배열 index가 올바르지 않습니다: ${segment}`);
+  const index = Number(segment);
+  const upper = options.allowEnd ? length : length - 1;
+  if (!Number.isSafeInteger(index) || index < 0 || index > upper) throw cliError("E_INVALID_PATCH", `배열 index가 범위를 벗어났습니다: ${segment}`);
+  return index;
+}
+
+function locate(document, segments) {
+  let current = document;
+  for (const segment of segments) {
+    if (Array.isArray(current)) current = current[arrayIndex(segment, current.length)];
+    else if (current && typeof current === "object" && Object.hasOwn(current, segment)) current = current[segment];
+    else throw cliError("E_INVALID_PATCH", `JSON Pointer 대상이 없습니다: /${segments.join("/")}`);
+  }
+  return current;
+}
+
+function parentAt(document, segments) {
+  if (!segments.length) return { parent: null, key: null };
+  const parent = locate(document, segments.slice(0, -1));
+  if (!parent || typeof parent !== "object") throw cliError("E_INVALID_PATCH", "JSON Patch 대상의 부모가 객체 또는 배열이 아닙니다.");
+  return { parent, key: segments.at(-1) };
+}
+
+function applyOperation(document, operation) {
+  if (!operation || typeof operation !== "object" || Array.isArray(operation)) throw cliError("E_INVALID_PATCH", "각 JSON Patch 작업은 객체여야 합니다.");
+  const op = String(operation.op || "");
+  const segments = pointerSegments(operation.path);
+  if (!['add', 'replace', 'remove', 'test'].includes(op)) {
+    throw cliError("E_INVALID_PATCH", `지원하지 않는 JSON Patch 작업입니다: ${op || "(비어 있음)"}`);
+  }
+
+  if (op === "test") {
+    if (!Object.hasOwn(operation, "value")) throw cliError("E_INVALID_PATCH", "test 작업에는 value가 필요합니다.");
+    const actual = segments.length ? locate(document, segments) : document;
+    if (!equalJson(actual, operation.value)) throw cliError("E_PATCH_TEST_FAILED", `JSON Patch test가 실패했습니다: ${operation.path}`);
+    return document;
+  }
+
+  if (!segments.length) {
+    if (op === "remove") throw cliError("E_INVALID_PATCH", "Component data 루트는 삭제할 수 없습니다.");
+    if (!Object.hasOwn(operation, "value")) throw cliError("E_INVALID_PATCH", `${op} 작업에는 value가 필요합니다.`);
+    return clone(operation.value);
+  }
+
+  const { parent, key } = parentAt(document, segments);
+  if (op === "add") {
+    if (!Object.hasOwn(operation, "value")) throw cliError("E_INVALID_PATCH", "add 작업에는 value가 필요합니다.");
+    if (Array.isArray(parent)) parent.splice(arrayIndex(key, parent.length, { append: true, allowEnd: true }), 0, clone(operation.value));
+    else parent[key] = clone(operation.value);
+    return document;
+  }
+
+  if (Array.isArray(parent)) {
+    const index = arrayIndex(key, parent.length);
+    if (op === "replace") {
+      if (!Object.hasOwn(operation, "value")) throw cliError("E_INVALID_PATCH", "replace 작업에는 value가 필요합니다.");
+      parent[index] = clone(operation.value);
+    } else parent.splice(index, 1);
+    return document;
+  }
+
+  if (!Object.hasOwn(parent, key)) throw cliError("E_INVALID_PATCH", `JSON Pointer 대상이 없습니다: ${operation.path}`);
+  if (op === "replace") {
+    if (!Object.hasOwn(operation, "value")) throw cliError("E_INVALID_PATCH", "replace 작업에는 value가 필요합니다.");
+    parent[key] = clone(operation.value);
+  } else delete parent[key];
+  return document;
+}
+
+function applyPatch(value, patch) {
+  if (!Array.isArray(patch) || !patch.length) throw cliError("E_INVALID_PATCH", "비어 있지 않은 RFC 6902 JSON Patch 배열이 필요합니다.");
+  return patch.reduce(applyOperation, clone(value));
+}
+
+module.exports = Object.freeze({ pointerSegments, applyPatch });

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

@@ -0,0 +1,26 @@
+"use strict";
+
+const crypto = require("node:crypto");
+
+function clone(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  const source = Buffer.isBuffer(value) || typeof value === "string" ? value : canonicalJson(value);
+  return crypto.createHash("sha256").update(source).digest("hex");
+}
+
+function equalJson(left, right) {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+module.exports = Object.freeze({ clone, canonicalJson, sha256, equalJson });

package/tools/writer-cli/src/local-index-cache.cjs

@@ -0,0 +1,139 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const { cliError } = require("./errors.cjs");
+const { INDEX_SCHEMA_VERSION, SERVER_SNAPSHOT_SOURCE } = require("./local-index-snapshot.cjs");
+
+const DEFAULT_FILE_NAMES = Object.freeze({ sqlite: "index.sqlite3", json: "index.json" });
+
+function rejectSymlink(target, label) {
+  try {
+    if (fs.lstatSync(target).isSymbolicLink()) throw cliError("E_LOCAL_INDEX_PERMISSIONS", `${label} 경로는 symbolic link일 수 없습니다.`);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+function ensurePrivateDirectory(directory) {
+  if (!directory) throw cliError("E_LOCAL_INDEX_CONFIGURATION", "계정별 cacheDir 또는 filePath가 필요합니다.");
+  const resolved = path.resolve(directory);
+  rejectSymlink(resolved, "로컬 인덱스 디렉터리");
+  fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+  rejectSymlink(resolved, "로컬 인덱스 디렉터리");
+  const stat = fs.statSync(resolved);
+  if (!stat.isDirectory()) throw cliError("E_LOCAL_INDEX_PERMISSIONS", "로컬 인덱스 경로가 디렉터리가 아닙니다.");
+  if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+    throw cliError("E_LOCAL_INDEX_PERMISSIONS", "현재 사용자가 소유하지 않은 로컬 인덱스 디렉터리입니다.");
+  }
+  fs.chmodSync(resolved, 0o700);
+  return resolved;
+}
+
+function ensurePrivateFile(filePath) {
+  rejectSymlink(filePath, "로컬 인덱스 파일");
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile()) throw cliError("E_LOCAL_INDEX_PERMISSIONS", "로컬 인덱스 경로가 일반 파일이 아닙니다.");
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+      throw cliError("E_LOCAL_INDEX_PERMISSIONS", "현재 사용자가 소유하지 않은 로컬 인덱스 파일입니다.");
+    }
+    fs.chmodSync(filePath, 0o600);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+function resolveStoragePaths(options, backend) {
+  const explicitFile = options.filePath ? path.resolve(String(options.filePath)) : null;
+  const cacheDir = ensurePrivateDirectory(options.cacheDir || (explicitFile ? path.dirname(explicitFile) : null));
+  if (explicitFile && path.dirname(explicitFile) !== cacheDir) {
+    throw cliError("E_LOCAL_INDEX_CONFIGURATION", "filePath는 cacheDir 바로 아래에 있어야 합니다.");
+  }
+  const filePath = explicitFile || path.join(cacheDir, DEFAULT_FILE_NAMES[backend]);
+  ensurePrivateFile(filePath);
+  return { cacheDir, filePath };
+}
+
+function readJsonState(filePath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (value?.metadata?.schemaVersion !== INDEX_SCHEMA_VERSION || value?.metadata?.source !== SERVER_SNAPSHOT_SOURCE
+      || !Array.isArray(value.components) || !Array.isArray(value.nodes)) {
+      throw cliError("E_LOCAL_INDEX_SCHEMA", "지원하지 않는 로컬 인덱스 형식입니다. purge 후 다시 동기화해 주세요.");
+    }
+    return value;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function atomicWritePrivateJson(cacheDir, filePath, value) {
+  const temporary = path.join(cacheDir, `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  rejectSymlink(filePath, "로컬 인덱스 파일");
+  let descriptor = null;
+  try {
+    descriptor = fs.openSync(temporary, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+    fs.writeFileSync(descriptor, JSON.stringify(value));
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = null;
+    fs.renameSync(temporary, filePath);
+    fs.chmodSync(filePath, 0o600);
+    if (process.platform !== "win32") {
+      const directoryDescriptor = fs.openSync(cacheDir, fs.constants.O_RDONLY);
+      try { fs.fsyncSync(directoryDescriptor); } finally { fs.closeSync(directoryDescriptor); }
+    }
+  } finally {
+    if (descriptor !== null) try { fs.closeSync(descriptor); } catch (error) { void error; }
+    try { fs.unlinkSync(temporary); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+  }
+}
+
+function createJsonBackend(options) {
+  const storage = resolveStoragePaths(options, "json");
+  let closed = false;
+  function state() {
+    if (closed) throw cliError("E_LOCAL_INDEX_CLOSED", "닫힌 로컬 인덱스입니다.");
+    return readJsonState(storage.filePath);
+  }
+  function replaceState(next) {
+    atomicWritePrivateJson(storage.cacheDir, storage.filePath, next);
+  }
+  function metadata() {
+    return state()?.metadata || null;
+  }
+  function queryRows() {
+    return state()?.nodes || [];
+  }
+  function getMatch(matchId) {
+    return (state()?.nodes || []).find(node => node.matchId === String(matchId || "")) || null;
+  }
+  function getComponent() {
+    return state()?.components || [];
+  }
+  function counts() {
+    const current = state();
+    return { components: current?.components.length || 0, scalars: current?.nodes.length || 0 };
+  }
+  function close() { closed = true; }
+  return { kind: "json", searchEngine: "json-bounded-scan", ...storage, replaceState, metadata, queryRows, getMatch, getComponent, counts, close };
+}
+
+function unlinkIfPresent(target) {
+  try { fs.unlinkSync(target); return true; }
+  catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+}
+
+function purgeBackendFiles(backend) {
+  const targets = backend.kind === "sqlite"
+    ? [backend.filePath, `${backend.filePath}-journal`, `${backend.filePath}-wal`, `${backend.filePath}-shm`]
+    : [backend.filePath];
+  let removed = 0;
+  for (const target of targets) if (unlinkIfPresent(target)) removed += 1;
+  return removed;
+}
+
+module.exports = Object.freeze({ resolveStoragePaths, createJsonBackend, purgeBackendFiles });