@ssobig/writer-cli 0.2.0

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

@@ -0,0 +1,98 @@
+"use strict";
+
+const { cliError } = require("./errors.cjs");
+const { own } = require("./local-index-snapshot.cjs");
+
+const DEFAULT_FRESH_FOR_MS = 30_000;
+const PUBLIC_PREVIEW_CHARACTERS = 200;
+
+function rowToNode(row) {
+  if (!row) return null;
+  if (own(row, "matchId")) return row;
+  return {
+    matchId: row.match_id,
+    projectId: row.project_id,
+    projectSlug: row.project_slug,
+    versionNumber: Number(row.version_number),
+    componentSetRevision: Number(row.component_set_revision),
+    componentChecksum: row.component_checksum,
+    instanceId: row.instance_id,
+    templateId: row.template_id,
+    instanceRevision: Number(row.instance_revision),
+    dataHash: row.data_hash,
+    pointer: row.pointer,
+    field: row.field_name,
+    valueType: row.value_type,
+    valueJson: row.value_json,
+    valueText: row.value_text,
+    searchText: row.search_text,
+    foldedText: row.folded_text
+  };
+}
+
+function freshnessFor(metadata, options = {}, nowProvider = Date.now) {
+  if (!metadata) return Object.freeze({ status: "empty", syncedAt: null, ageMs: null, maxAgeMs: null });
+  const nowValue = options.now === undefined ? Number(nowProvider()) : new Date(options.now).getTime();
+  if (!Number.isFinite(nowValue)) throw cliError("E_LOCAL_INDEX_QUERY", "freshness now 값이 올바르지 않습니다.");
+  const maxAgeMs = options.maxAgeMs === undefined ? DEFAULT_FRESH_FOR_MS : Number(options.maxAgeMs);
+  if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0) throw cliError("E_LOCAL_INDEX_QUERY", "maxAgeMs는 0 이상의 숫자여야 합니다.");
+  const ageMs = Math.max(0, nowValue - new Date(metadata.syncedAt).getTime());
+  return Object.freeze({
+    status: options.online === false ? "offline" : (ageMs <= maxAgeMs ? "fresh" : "stale"),
+    syncedAt: metadata.syncedAt,
+    lastVerifiedAuthAt: metadata.lastVerifiedAuthAt,
+    ageMs,
+    maxAgeMs
+  });
+}
+
+function clippedText(value, maximum) {
+  const characters = [...String(value)];
+  return {
+    text: characters.length <= maximum ? characters.join("") : `${characters.slice(0, maximum).join("")}…`,
+    truncated: characters.length > maximum
+  };
+}
+
+function publicMatch(node) {
+  const parsedValue = JSON.parse(node.valueJson);
+  const preview = clippedText(node.valueText, PUBLIC_PREVIEW_CHARACTERS);
+  const valueIncluded = typeof parsedValue !== "string" || !preview.truncated;
+  return Object.freeze({
+    matchId: node.matchId,
+    project: Object.freeze({ id: node.projectId, slug: node.projectSlug }),
+    versionNumber: node.versionNumber,
+    component: Object.freeze({
+      instanceId: node.instanceId,
+      templateId: node.templateId,
+      revision: node.instanceRevision,
+      dataHash: node.dataHash
+    }),
+    isAsset: node.templateId === "ssobig.assets",
+    componentSet: Object.freeze({ revision: node.componentSetRevision, checksum: node.componentChecksum }),
+    pointer: node.pointer,
+    field: node.field,
+    valueType: node.valueType,
+    ...(valueIncluded ? { value: parsedValue } : {}),
+    valueIncluded,
+    ...(!valueIncluded ? { preview: preview.text, previewTruncated: true } : {})
+  });
+}
+
+function componentFromRow(row) {
+  if (own(row, "projectId")) return row;
+  return {
+    projectId: row.project_id,
+    projectSlug: row.project_slug,
+    versionNumber: Number(row.version_number),
+    componentSetRevision: Number(row.component_set_revision),
+    componentChecksum: row.component_checksum,
+    instanceId: row.instance_id,
+    templateId: row.template_id,
+    instanceRevision: Number(row.instance_revision),
+    dataHash: row.data_hash,
+    data: JSON.parse(row.data_json)
+  };
+}
+
+module.exports = Object.freeze({ rowToNode, freshnessFor, publicMatch, componentFromRow });

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

@@ -0,0 +1,304 @@
+"use strict";
+
+const { cliError } = require("./errors.cjs");
+const {
+  own,
+  isObject,
+  finiteInteger,
+  assertJsonValue,
+  cloneJson,
+  unescapeJsonPointerToken,
+  scalarType,
+  normalizedText,
+  foldedText,
+  trigramValues
+} = require("./local-index-snapshot.cjs");
+
+const DEFAULT_LIMIT = 20;
+const DEFAULT_MAX_LIMIT = 500;
+const DEFAULT_MAX_CANDIDATE_ROWS = 50_000;
+const DEFAULT_MAX_REGEX_SCAN_ROWS = 10_000;
+const DEFAULT_MAX_REGEX_PATTERN_LENGTH = 256;
+const DEFAULT_MAX_REGEX_VALUE_LENGTH = 64 * 1024;
+const DEFAULT_MAX_SUBSTRING_TRIGRAMS = 64;
+
+function createQueryLimits(options, useFts5) {
+  return Object.freeze({
+    maxLimit: finiteInteger(options.maxLimit ?? DEFAULT_MAX_LIMIT, "maxLimit", 1, "E_LOCAL_INDEX_CONFIGURATION"),
+    maxCandidateRows: finiteInteger(options.maxCandidateRows ?? DEFAULT_MAX_CANDIDATE_ROWS, "maxCandidateRows", 1, "E_LOCAL_INDEX_CONFIGURATION"),
+    maxRegexScanRows: finiteInteger(options.maxRegexScanRows ?? DEFAULT_MAX_REGEX_SCAN_ROWS, "maxRegexScanRows", 1, "E_LOCAL_INDEX_CONFIGURATION"),
+    maxRegexPatternLength: finiteInteger(options.maxRegexPatternLength ?? DEFAULT_MAX_REGEX_PATTERN_LENGTH, "maxRegexPatternLength", 1, "E_LOCAL_INDEX_CONFIGURATION"),
+    maxRegexValueLength: finiteInteger(options.maxRegexValueLength ?? DEFAULT_MAX_REGEX_VALUE_LENGTH, "maxRegexValueLength", 1, "E_LOCAL_INDEX_CONFIGURATION"),
+    maxSubstringTrigrams: finiteInteger(options.maxSubstringTrigrams ?? DEFAULT_MAX_SUBSTRING_TRIGRAMS, "maxSubstringTrigrams", 1, "E_LOCAL_INDEX_CONFIGURATION"),
+    useFts5: useFts5 === true
+  });
+}
+
+function asStringList(value, name) {
+  if (value === undefined || value === null) return [];
+  const list = Array.isArray(value) ? value : [value];
+  const normalized = list.map(item => String(item || "").trim());
+  if (normalized.some(item => !item)) throw cliError("E_LOCAL_INDEX_QUERY", `${name} filter에 빈 값이 있습니다.`);
+  if (normalized.length > 256) throw cliError("E_LOCAL_INDEX_QUERY", `${name} filter는 최대 256개까지 지원합니다.`);
+  return [...new Set(normalized)];
+}
+
+function asVersionList(value) {
+  if (value === undefined || value === null) return [];
+  return [...new Set((Array.isArray(value) ? value : [value]).map(item => finiteInteger(item, "version filter", 1, "E_LOCAL_INDEX_QUERY")))];
+}
+
+function normalizePathFilter(item, defaultOperation = "exact") {
+  const object = isObject(item) ? item : { op: defaultOperation, value: item };
+  const op = String(object.op || object.mode || defaultOperation);
+  if (!["exact", "prefix", "glob"].includes(op)) throw cliError("E_LOCAL_INDEX_QUERY", `지원하지 않는 path filter입니다: ${op}`);
+  const value = String(object.value ?? "");
+  if (value !== "" && !value.startsWith("/")) throw cliError("E_LOCAL_INDEX_QUERY", "JSON pointer는 빈 문자열 또는 /로 시작해야 합니다.");
+  if (op !== "glob") {
+    for (const token of value.split("/").slice(1)) unescapeJsonPointerToken(token);
+  }
+  return { op, value };
+}
+
+function normalizeFilters(request) {
+  const projectRefs = asStringList(request.projects ?? request.project, "project");
+  const componentRefs = asStringList(request.components ?? request.component, "component");
+  const pathFilters = [];
+  if (own(request, "path")) pathFilters.push(normalizePathFilter(request.path, "exact"));
+  if (own(request, "pathPrefix")) pathFilters.push(normalizePathFilter(request.pathPrefix, "prefix"));
+  if (own(request, "pathGlob")) pathFilters.push(normalizePathFilter(request.pathGlob, "glob"));
+  if (request.paths !== undefined) {
+    if (!Array.isArray(request.paths)) throw cliError("E_LOCAL_INDEX_QUERY", "paths는 배열이어야 합니다.");
+    pathFilters.push(...request.paths.map(item => normalizePathFilter(item, "exact")));
+  }
+  return {
+    projectRefs,
+    projectIds: asStringList(request.projectIds ?? request.projectId, "projectId"),
+    projectSlugs: asStringList(request.projectSlugs ?? request.projectSlug, "projectSlug"),
+    versions: asVersionList(request.versions ?? request.version),
+    componentRefs,
+    instanceIds: asStringList(request.instanceIds ?? request.instanceId, "instanceId"),
+    templateIds: asStringList(request.templateIds ?? request.templateId, "templateId"),
+    fields: asStringList(request.fields ?? request.field, "field"),
+    valueTypes: asStringList(request.valueTypes ?? request.valueType, "valueType"),
+    pathFilters,
+    includeAssets: request.includeAssets === true
+  };
+}
+
+function addInSql(where, parameters, column, values) {
+  if (!values.length) return;
+  where.push(`${column} IN (${values.map(() => "?").join(", ")})`);
+  parameters.push(...values);
+}
+
+function appendSqlIdentityFilters(where, parameters, filters, tableName = "scalar_nodes") {
+  const prefix = tableName ? `${tableName}.` : "";
+  if (filters.projectRefs.length) {
+    const placeholders = filters.projectRefs.map(() => "?").join(", ");
+    where.push(`(${prefix}project_id IN (${placeholders}) OR ${prefix}project_slug IN (${placeholders}))`);
+    parameters.push(...filters.projectRefs, ...filters.projectRefs);
+  }
+  addInSql(where, parameters, `${prefix}project_id`, filters.projectIds);
+  addInSql(where, parameters, `${prefix}project_slug`, filters.projectSlugs);
+  addInSql(where, parameters, `${prefix}version_number`, filters.versions);
+  if (filters.componentRefs.length) {
+    const placeholders = filters.componentRefs.map(() => "?").join(", ");
+    where.push(`(${prefix}instance_id IN (${placeholders}) OR ${prefix}template_id IN (${placeholders}))`);
+    parameters.push(...filters.componentRefs, ...filters.componentRefs);
+  }
+  addInSql(where, parameters, `${prefix}instance_id`, filters.instanceIds);
+  addInSql(where, parameters, `${prefix}template_id`, filters.templateIds);
+}
+
+function sqlLikeLiteral(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
+
+function appendSqlNodeFilters(where, parameters, filters) {
+  appendSqlIdentityFilters(where, parameters, filters);
+  if (!filters.includeAssets) where.push("scalar_nodes.template_id <> 'ssobig.assets'");
+  addInSql(where, parameters, "scalar_nodes.field_name", filters.fields);
+  addInSql(where, parameters, "scalar_nodes.value_type", filters.valueTypes);
+  if (filters.pathFilters.length && filters.pathFilters.every(item => item.op !== "glob")) {
+    const clauses = [];
+    for (const filter of filters.pathFilters) {
+      if (filter.op === "exact") {
+        clauses.push("scalar_nodes.pointer = ?");
+        parameters.push(filter.value);
+      } else {
+        clauses.push("(scalar_nodes.pointer = ? OR scalar_nodes.pointer LIKE ? ESCAPE '\\')");
+        parameters.push(filter.value, `${sqlLikeLiteral(filter.value).replace(/\/$/, "")}/%`);
+      }
+    }
+    where.push(`(${clauses.join(" OR ")})`);
+  }
+}
+
+function globRegex(glob) {
+  let source = "^";
+  for (let index = 0; index < glob.length; index += 1) {
+    const character = glob[index];
+    if (character === "*" && glob[index + 1] === "*") {
+      source += ".*";
+      index += 1;
+    } else if (character === "*") source += "[^/]*";
+    else if (character === "?") source += "[^/]";
+    else source += character.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+  }
+  return new RegExp(`${source}$`, "u");
+}
+
+function pathMatches(pointer, filters) {
+  if (!filters.length) return true;
+  return filters.some(filter => {
+    if (filter.op === "exact") return pointer === filter.value;
+    if (filter.op === "prefix") return pointer === filter.value || pointer.startsWith(`${filter.value.replace(/\/$/, "")}/`);
+    return globRegex(filter.value).test(pointer);
+  });
+}
+
+function identityMatches(node, filters) {
+  if (!filters.includeAssets && node.templateId === "ssobig.assets") return false;
+  if (filters.projectRefs.length && !filters.projectRefs.includes(node.projectId) && !filters.projectRefs.includes(node.projectSlug)) return false;
+  if (filters.projectIds.length && !filters.projectIds.includes(node.projectId)) return false;
+  if (filters.projectSlugs.length && !filters.projectSlugs.includes(node.projectSlug)) return false;
+  if (filters.versions.length && !filters.versions.includes(Number(node.versionNumber))) return false;
+  if (filters.componentRefs.length && !filters.componentRefs.includes(node.instanceId) && !filters.componentRefs.includes(node.templateId)) return false;
+  if (filters.instanceIds.length && !filters.instanceIds.includes(node.instanceId)) return false;
+  if (filters.templateIds.length && !filters.templateIds.includes(node.templateId)) return false;
+  if (filters.fields.length && !filters.fields.includes(node.field ?? node.field_name)) return false;
+  if (filters.valueTypes.length && !filters.valueTypes.includes(node.valueType ?? node.value_type)) return false;
+  return pathMatches(node.pointer, filters.pathFilters);
+}
+
+function assertSafeRegex(pattern, maxLength) {
+  if (pattern.length > maxLength) throw cliError("E_LOCAL_INDEX_REGEX_LIMIT", `regex는 최대 ${maxLength}자까지 지원합니다.`);
+  if (/\(\?[=!<]/u.test(pattern) || /\\(?:[1-9]|k<)/u.test(pattern)) {
+    throw cliError("E_LOCAL_INDEX_UNSAFE_REGEX", "lookaround와 backreference가 없는 제한된 regex만 지원합니다.");
+  }
+  if (/(?:\.\*){2,}|(?:\.\+){2,}/u.test(pattern.replace(/\s+/g, ""))) {
+    throw cliError("E_LOCAL_INDEX_UNSAFE_REGEX", "반복 wildcard가 중첩된 regex는 지원하지 않습니다.");
+  }
+  const stack = [];
+  let escaped = false;
+  let characterClass = false;
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (escaped) { escaped = false; continue; }
+    if (character === "\\") { escaped = true; continue; }
+    if (character === "[") { characterClass = true; continue; }
+    if (character === "]") { characterClass = false; continue; }
+    if (characterClass) continue;
+    if (character === "(") stack.push({ quantified: false, alternation: false });
+    else if (character === "|") { if (stack.length) stack.at(-1).alternation = true; }
+    else if (["*", "+", "?", "{"].includes(character)) {
+      if (stack.length) stack.at(-1).quantified = true;
+    } else if (character === ")") {
+      const group = stack.pop() || { quantified: false, alternation: false };
+      const tail = pattern.slice(index + 1);
+      if (/^(?:[*+?]|\{\d+(?:,\d*)?\})/u.test(tail) && (group.quantified || group.alternation)) {
+        throw cliError("E_LOCAL_INDEX_UNSAFE_REGEX", "중첩되거나 모호한 반복 group regex는 지원하지 않습니다.");
+      }
+    }
+  }
+}
+
+function compileRegex(request, limits) {
+  const pattern = String(request.query ?? request.pattern ?? "");
+  assertSafeRegex(pattern, limits.maxRegexPatternLength);
+  const requestedFlags = String(request.flags || "");
+  if (/[^imsu]/u.test(requestedFlags)) throw cliError("E_LOCAL_INDEX_QUERY", "regex flags는 i, m, s, u만 지원합니다.");
+  let flags = [...new Set([...requestedFlags, "u"])].join("");
+  if (request.caseSensitive !== true && !flags.includes("i")) flags += "i";
+  try { return new RegExp(pattern, flags); }
+  catch (error) { throw cliError("E_LOCAL_INDEX_QUERY", "올바르지 않은 regex입니다.", null, error); }
+}
+
+function normalizeSearch(request, limits) {
+  if (!isObject(request)) throw cliError("E_LOCAL_INDEX_QUERY", "검색 요청 객체가 필요합니다.");
+  const mode = String(request.mode || "substring");
+  if (!["exact", "substring", "regex", "all"].includes(mode)) throw cliError("E_LOCAL_INDEX_QUERY", `지원하지 않는 검색 mode입니다: ${mode}`);
+  const hasValue = own(request, "value");
+  if (mode !== "all" && !hasValue && !own(request, "query") && !own(request, "pattern")) {
+    throw cliError("E_LOCAL_INDEX_QUERY", "검색 query 또는 value가 필요합니다.");
+  }
+  if (hasValue) assertJsonValue(request.value);
+  if (hasValue && ![null, "string", "number", "boolean"].includes(request.value === null ? null : typeof request.value)) {
+    throw cliError("E_LOCAL_INDEX_QUERY", "exact value는 JSON scalar여야 합니다.");
+  }
+  if (hasValue && !["exact", "all"].includes(mode)) throw cliError("E_LOCAL_INDEX_QUERY", "typed value 검색은 exact mode에서만 지원합니다.");
+  const limit = finiteInteger(request.limit ?? Math.min(DEFAULT_LIMIT, limits.maxLimit), "limit", 1, "E_LOCAL_INDEX_QUERY");
+  if (limit > limits.maxLimit) throw cliError("E_LOCAL_INDEX_QUERY", `limit은 최대 ${limits.maxLimit}입니다.`);
+  const caseSensitive = request.caseSensitive === true;
+  const query = hasValue ? null : String(request.query ?? request.pattern ?? "");
+  const normalizedQuery = query === null ? null : normalizedText(query);
+  return {
+    request,
+    mode,
+    hasValue,
+    value: hasValue ? cloneJson(request.value) : undefined,
+    valueType: hasValue ? scalarType(request.value) : null,
+    valueJson: hasValue ? JSON.stringify(request.value) : null,
+    query: normalizedQuery,
+    foldedQuery: normalizedQuery === null ? null : foldedText(normalizedQuery),
+    caseSensitive,
+    limit,
+    filters: normalizeFilters(request),
+    regex: mode === "regex" ? compileRegex(request, limits) : null
+  };
+}
+
+function appendSqlSearch(where, parameters, search, limits) {
+  if (search.mode === "exact") {
+    if (search.hasValue) {
+      where.push("scalar_nodes.value_type = ? AND scalar_nodes.value_json = ?");
+      parameters.push(search.valueType, search.valueJson);
+    } else {
+      where.push(`scalar_nodes.${search.caseSensitive ? "search_text" : "folded_text"} = ?`);
+      parameters.push(search.caseSensitive ? search.query : search.foldedQuery);
+    }
+  } else if (search.mode === "substring") {
+    const needle = search.caseSensitive ? search.query : search.foldedQuery;
+    const trigrams = trigramValues(search.foldedQuery, limits.maxSubstringTrigrams);
+    if (trigrams.length) {
+      if (limits.useFts5) {
+        where.push("scalar_nodes.id IN (SELECT rowid FROM scalar_fts WHERE scalar_fts MATCH ?)");
+        parameters.push(`"${search.foldedQuery.replace(/"/g, "\"\"")}"`);
+      } else {
+        where.push(`scalar_nodes.id IN (
+          SELECT node_id FROM scalar_trigrams
+          WHERE trigram IN (${trigrams.map(() => "?").join(", ")})
+          GROUP BY node_id HAVING COUNT(*) = ?
+        )`);
+        parameters.push(...trigrams, trigrams.length);
+      }
+    }
+    where.push(`instr(scalar_nodes.${search.caseSensitive ? "search_text" : "folded_text"}, ?) > 0`);
+    parameters.push(needle);
+  }
+}
+
+function nodeMatchesSearch(node, search) {
+  if (!identityMatches(node, search.filters)) return false;
+  if (search.mode === "all") return true;
+  if (search.mode === "exact") {
+    if (search.hasValue) return node.valueType === search.valueType && node.valueJson === search.valueJson;
+    return search.caseSensitive ? node.searchText === search.query : node.foldedText === search.foldedQuery;
+  }
+  if (search.mode === "substring") {
+    return (search.caseSensitive ? node.searchText : node.foldedText).includes(search.caseSensitive ? search.query : search.foldedQuery);
+  }
+  return search.regex.test(node.valueText);
+}
+
+module.exports = Object.freeze({
+  createQueryLimits,
+  normalizeFilters,
+  appendSqlIdentityFilters,
+  appendSqlNodeFilters,
+  identityMatches,
+  normalizeSearch,
+  appendSqlSearch,
+  nodeMatchesSearch
+});

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

@@ -0,0 +1,235 @@
+"use strict";
+
+const { sha256 } = require("./json.cjs");
+const { cliError } = require("./errors.cjs");
+
+const INDEX_SCHEMA_VERSION = "ssobig-writer-local-read-index-v2";
+const SERVER_SNAPSHOT_SOURCE = "supabase-authoritative-read";
+
+function own(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function finiteInteger(value, name, minimum = 0, errorCode = "E_LOCAL_INDEX_SNAPSHOT") {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < minimum) {
+    throw cliError(errorCode, `${name} 값이 올바르지 않습니다.`);
+  }
+  return number;
+}
+
+function nonEmptyString(value, name) {
+  const text = String(value || "").trim();
+  if (!text) throw cliError("E_LOCAL_INDEX_SNAPSHOT", `${name} 값이 필요합니다.`);
+  return text;
+}
+
+function isoTimestamp(value, name) {
+  const text = String(value || "");
+  if (!text || Number.isNaN(new Date(text).getTime())) {
+    throw cliError("E_LOCAL_INDEX_SNAPSHOT", `${name} 값이 유효한 ISO 날짜가 아닙니다.`);
+  }
+  return new Date(text).toISOString();
+}
+
+function assertJsonValue(value, pointer = "") {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw cliError("E_LOCAL_INDEX_SNAPSHOT", `JSON에 유한하지 않은 숫자가 있습니다: ${pointer || "/"}`);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) assertJsonValue(value[index], `${pointer}/${index}`);
+    return;
+  }
+  if (isObject(value)) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw cliError("E_LOCAL_INDEX_SNAPSHOT", `plain JSON object가 아닌 값이 있습니다: ${pointer || "/"}`);
+    }
+    for (const key of Object.keys(value)) assertJsonValue(value[key], `${pointer}/${escapeJsonPointerToken(key)}`);
+    return;
+  }
+  throw cliError("E_LOCAL_INDEX_SNAPSHOT", `JSON으로 저장할 수 없는 값이 있습니다: ${pointer || "/"}`);
+}
+
+function cloneJson(value) {
+  assertJsonValue(value);
+  return JSON.parse(JSON.stringify(value));
+}
+
+function escapeJsonPointerToken(value) {
+  return String(value).replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+function unescapeJsonPointerToken(value) {
+  const text = String(value);
+  if (/~(?![01])/u.test(text)) throw cliError("E_LOCAL_INDEX_QUERY", `잘못된 RFC 6901 token입니다: ${text}`);
+  return text.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+function scalarType(value) {
+  if (value === null) return "null";
+  return typeof value;
+}
+
+function scalarText(value) {
+  if (typeof value === "string") return value;
+  if (value === null) return "null";
+  return String(value);
+}
+
+function normalizedText(value) {
+  return String(value).normalize("NFC");
+}
+
+function foldedText(value) {
+  return normalizedText(value).toLowerCase();
+}
+
+function flattenJsonScalars(value) {
+  assertJsonValue(value);
+  const rows = [];
+  function visit(current, pointer) {
+    if (current === null || ["string", "number", "boolean"].includes(typeof current)) {
+      const text = scalarText(current);
+      const encodedField = pointer === "" ? "" : pointer.slice(pointer.lastIndexOf("/") + 1);
+      rows.push(Object.freeze({
+        pointer,
+        field: pointer === "" ? "" : unescapeJsonPointerToken(encodedField),
+        value: current,
+        valueType: scalarType(current),
+        valueJson: JSON.stringify(current),
+        valueText: text,
+        searchText: normalizedText(text),
+        foldedText: foldedText(text)
+      }));
+      return;
+    }
+    if (Array.isArray(current)) {
+      current.forEach((item, index) => visit(item, `${pointer}/${index}`));
+      return;
+    }
+    for (const key of Object.keys(current)) visit(current[key], `${pointer}/${escapeJsonPointerToken(key)}`);
+  }
+  visit(value, "");
+  return rows;
+}
+
+function trigramValues(value, maxCount = Infinity) {
+  const characters = [...foldedText(value)];
+  if (characters.length < 3) return [];
+  const unique = new Set();
+  for (let index = 0; index <= characters.length - 3 && unique.size < maxCount; index += 1) {
+    unique.add(characters.slice(index, index + 3).join(""));
+  }
+  return [...unique];
+}
+
+function normalizeSnapshot(snapshot) {
+  const arrayInput = Array.isArray(snapshot);
+  const source = arrayInput ? SERVER_SNAPSHOT_SOURCE : String(snapshot?.source || "");
+  if (source !== SERVER_SNAPSHOT_SOURCE) {
+    throw cliError("E_LOCAL_INDEX_SNAPSHOT", `로컬 인덱스는 ${SERVER_SNAPSHOT_SOURCE} snapshot만 받습니다.`);
+  }
+  const syncedAt = isoTimestamp(arrayInput ? new Date().toISOString() : snapshot.syncedAt, "syncedAt");
+  const lastVerifiedAuthAt = arrayInput || !snapshot.lastVerifiedAuthAt
+    ? null
+    : isoTimestamp(snapshot.lastVerifiedAuthAt, "lastVerifiedAuthAt");
+  const actor = arrayInput || !snapshot.actor ? null : {
+    id: String(snapshot.actor.id || ""),
+    email: String(snapshot.actor.email || "").toLowerCase()
+  };
+  const entries = arrayInput ? snapshot : (snapshot.projects || snapshot.versions);
+  if (!Array.isArray(entries)) throw cliError("E_LOCAL_INDEX_SNAPSHOT", "snapshot.projects 배열이 필요합니다.");
+
+  const components = [];
+  const nodes = [];
+  const versionKeys = new Set();
+  const componentKeys = new Set();
+  for (const entry of entries) {
+    const project = entry?.project;
+    const projectId = nonEmptyString(project?.id, "project.id");
+    const projectSlug = nonEmptyString(project?.slug, "project.slug");
+    const versionNumber = finiteInteger(entry?.versionNumber ?? entry?.version?.version_number, "version_number", 1);
+    const componentSetRevision = finiteInteger(entry?.componentSet?.revision, "componentSet.revision", 0);
+    const componentChecksum = nonEmptyString(entry?.componentSet?.component_checksum ?? entry?.componentSet?.componentChecksum, "componentSet.component_checksum");
+    const versionKey = `${projectId}\u0000${versionNumber}`;
+    if (versionKeys.has(versionKey)) throw cliError("E_LOCAL_INDEX_SNAPSHOT", `중복 작품 버전입니다: ${projectSlug} v${versionNumber}`);
+    versionKeys.add(versionKey);
+    const rows = entry?.instances || entry?.componentRows;
+    if (!Array.isArray(rows)) throw cliError("E_LOCAL_INDEX_SNAPSHOT", `${projectSlug} v${versionNumber}의 Component 배열이 필요합니다.`);
+    for (const row of rows) {
+      const instanceId = nonEmptyString(row?.instanceId ?? row?.instance_id, "instance_id");
+      const templateId = nonEmptyString(row?.templateId ?? row?.template_id, "template_id");
+      const instanceRevision = finiteInteger(row?.revision, "instance.revision", 0);
+      assertJsonValue(row?.data);
+      const data = cloneJson(row.data);
+      const dataHash = sha256(data);
+      const componentKey = `${versionKey}\u0000${instanceId}`;
+      if (componentKeys.has(componentKey)) throw cliError("E_LOCAL_INDEX_SNAPSHOT", `중복 Component입니다: ${projectSlug} v${versionNumber} ${instanceId}`);
+      componentKeys.add(componentKey);
+      const component = {
+        projectId,
+        projectSlug,
+        versionNumber,
+        componentSetRevision,
+        componentChecksum,
+        instanceId,
+        templateId,
+        instanceRevision,
+        dataHash,
+        data
+      };
+      components.push(component);
+      for (const scalar of flattenJsonScalars(data)) {
+        const matchId = sha256({
+          projectId,
+          versionNumber,
+          instanceId,
+          instanceRevision,
+          dataHash,
+          pointer: scalar.pointer,
+          valueType: scalar.valueType,
+          valueJson: scalar.valueJson
+        });
+        nodes.push({ ...component, data: undefined, ...scalar, matchId });
+      }
+    }
+  }
+  const snapshotHash = sha256({ source, actor, syncedAt, lastVerifiedAuthAt, components });
+  const metadata = {
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    source,
+    actor,
+    syncedAt,
+    lastVerifiedAuthAt,
+    snapshotHash,
+    projectVersionCount: versionKeys.size,
+    componentCount: components.length,
+    scalarCount: nodes.length
+  };
+  return { metadata, components, nodes };
+}
+
+module.exports = Object.freeze({
+  INDEX_SCHEMA_VERSION,
+  SERVER_SNAPSHOT_SOURCE,
+  own,
+  isObject,
+  finiteInteger,
+  assertJsonValue,
+  cloneJson,
+  escapeJsonPointerToken,
+  unescapeJsonPointerToken,
+  scalarType,
+  normalizedText,
+  foldedText,
+  flattenJsonScalars,
+  trigramValues,
+  normalizeSnapshot
+});