@ssobig/writer-cli 0.2.0

package/tools/writer-cli/src/agent-service.cjs

@@ -0,0 +1,496 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const config = require("../../../config.js");
+const { createAuthManager } = require("./auth.cjs");
+const { createSupabaseGateway } = require("./gateway.cjs");
+const { buildValidatedSnapshot } = require("./corpus.cjs");
+const {
+  createComponentPlan,
+  findInstance,
+  verifyPlan,
+  validateLoadedVersion
+} = require("./domain.cjs");
+const { applyProjectCreationPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan } = require("./mutations.cjs");
+const { pointerSegments } = require("./json-patch.cjs");
+const { equalJson, sha256 } = require("./json.cjs");
+const { cliError, normalizeError } = require("./errors.cjs");
+const { readJson, reservePrivateJson, writePrivateJson } = require("./commands.cjs");
+const { resolveAgentPaths, ensurePrivateDirectory, purgeAllAgentIndexes } = require("./agent-paths.cjs");
+
+function pointerValue(document, pointer) {
+  let value = document;
+  for (const segment of pointerSegments(pointer)) {
+    if (Array.isArray(value)) {
+      if (!/^(0|[1-9][0-9]*)$/.test(segment) || Number(segment) >= value.length) {
+        throw cliError("E_INVALID_PATCH", `JSON Pointer 대상이 없습니다: ${pointer}`);
+      }
+      value = value[Number(segment)];
+    } else if (value && typeof value === "object" && Object.hasOwn(value, segment)) {
+      value = value[segment];
+    } else {
+      throw cliError("E_INVALID_PATCH", `JSON Pointer 대상이 없습니다: ${pointer}`);
+    }
+  }
+  return value;
+}
+
+function replaceOccurrence(source, oldText, newText, occurrenceIndex) {
+  if (typeof source !== "string") throw cliError("E_REPLACE_TYPE", "텍스트 부분 교체 대상은 문자열 필드여야 합니다.");
+  if (typeof oldText !== "string" || oldText.length === 0) throw cliError("E_USAGE", "oldText에는 비어 있지 않은 문자열이 필요합니다.");
+  if (typeof newText !== "string") throw cliError("E_USAGE", "newText에는 문자열이 필요합니다.");
+  const offsets = [];
+  let cursor = 0;
+  while (cursor <= source.length - oldText.length) {
+    const found = source.indexOf(oldText, cursor);
+    if (found < 0) break;
+    offsets.push(found);
+    cursor = found + Math.max(1, oldText.length);
+  }
+  if (!offsets.length) throw cliError("E_CONFLICT", "서버 원본에서 교체할 기존 텍스트를 찾을 수 없습니다. 다시 검색해 주세요.");
+  let selected = occurrenceIndex;
+  if (selected === undefined || selected === null) {
+    if (offsets.length !== 1) throw cliError("E_AMBIGUOUS_MATCH", "같은 필드에 기존 텍스트가 여러 번 있습니다. occurrenceIndex를 명시해 주세요.", { occurrences: offsets.length });
+    selected = 0;
+  }
+  selected = Number(selected);
+  if (!Number.isSafeInteger(selected) || selected < 0 || selected >= offsets.length) {
+    throw cliError("E_USAGE", `occurrenceIndex는 0부터 ${offsets.length - 1} 사이여야 합니다.`);
+  }
+  const offset = offsets[selected];
+  return source.slice(0, offset) + newText + source.slice(offset + oldText.length);
+}
+
+function dataShape(value) {
+  if (Array.isArray(value)) return { type: "array", items: value.length };
+  if (value && typeof value === "object") {
+    const fields = Object.keys(value);
+    return { type: "object", fieldCount: fields.length, fields };
+  }
+  return { type: value === null ? "null" : typeof value };
+}
+
+function selectedValue(value, maximumCharacters = 2_000) {
+  if (typeof value !== "string") return { value, valueIncluded: true };
+  const characters = [...value];
+  if (characters.length <= maximumCharacters) return { value, valueIncluded: true, characters: characters.length };
+  return {
+    preview: `${characters.slice(0, maximumCharacters).join("")}…`,
+    valueIncluded: false,
+    truncated: true,
+    characters: characters.length
+  };
+}
+
+function createAgentService(options = {}) {
+  const platform = String(options.platform || process.platform);
+  const auth = options.auth || createAuthManager(config, { ...(options.authOptions || {}), platform, persistent: true });
+  const gatewayFactory = options.gatewayFactory || (client => createSupabaseGateway(client, { bucketName: config.assetBucket }));
+  const indexFactory = options.indexFactory || (indexOptions => require("./local-index.cjs").createLocalIndex(indexOptions));
+  const cacheDir = resolveAgentPaths({
+    cacheDir: options.cacheDir,
+    platform,
+    environment: options.environment,
+    homeDirectory: options.homeDirectory
+  }).cacheDir;
+  const now = options.now || (() => new Date());
+  const retentionMs = Math.max(86_400_000, Number(options.retentionMs || 7 * 86_400_000));
+  let localIndex = null;
+  let indexActorId = "";
+  let realtimeClient = null;
+  let realtimeChannel = null;
+  let realtimeState = "disabled";
+  let realtimeSubscribedOnce = false;
+  let invalidatedAt = null;
+  let invalidationReason = null;
+  let invalidationGeneration = 0;
+  let syncPromise = null;
+  let lastSyncError = null;
+
+  function isoNow() {
+    const value = now();
+    return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+  }
+
+  async function ensureIndex(user) {
+    if (localIndex && indexActorId === String(user.id)) return localIndex;
+    if (localIndex) await localIndex.close();
+    const paths = resolveAgentPaths({ cacheDir, userId: user.id, platform });
+    ensurePrivateDirectory(paths.userCacheDir, options.fs, { platform });
+    let opened = await indexFactory({ cacheDir: paths.userCacheDir, filePath: paths.indexPath });
+    const openedStatus = await opened.status({ maxAgeMs: retentionMs, now: isoNow() });
+    if (openedStatus?.ready && Number(openedStatus.freshness?.ageMs) > retentionMs) {
+      await opened.purge();
+      opened = await indexFactory({ cacheDir: paths.userCacheDir, filePath: paths.indexPath });
+    }
+    localIndex = opened;
+    indexActorId = String(user.id);
+    return localIndex;
+  }
+
+  function invalidate(reason) {
+    invalidationGeneration += 1;
+    invalidatedAt = isoNow();
+    invalidationReason = String(reason || "change-hint");
+  }
+
+  function startRealtime(client) {
+    if (options.realtime === false || realtimeChannel || typeof client?.channel !== "function") return;
+    realtimeClient = client;
+    realtimeState = "connecting";
+    let channel = client.channel("ssobig-writer-agent-index-invalidation");
+    for (const table of ["somi_projects", "somi_project_component_sets", "somi_project_component_instances"]) {
+      channel = channel.on("postgres_changes", { event: "*", schema: "public", table }, () => invalidate(`realtime:${table}`));
+    }
+    realtimeChannel = channel.subscribe(status => {
+      realtimeState = String(status || "unknown").toLowerCase();
+      if (status === "SUBSCRIBED") {
+        if (realtimeSubscribedOnce) invalidate("realtime-reconnect");
+        realtimeSubscribedOnce = true;
+      }
+    });
+  }
+
+  async function performSync(context, params = {}, startedGeneration = invalidationGeneration) {
+    const gateway = gatewayFactory(context.client);
+    startRealtime(context.client);
+    let corpus;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try { corpus = await gateway.loadCorpus("active"); break; }
+      catch (error) {
+        if (error.code !== "E_CORPUS_CHANGED" || attempt === 1) throw error;
+      }
+    }
+    const built = buildValidatedSnapshot(corpus, context.user, { now });
+    const index = await ensureIndex(context.user);
+    const indexStatus = await index.replaceSnapshot(built.snapshot);
+    if (invalidationGeneration === startedGeneration) {
+      invalidatedAt = null;
+      invalidationReason = null;
+    }
+    lastSyncError = null;
+    return {
+      authoritativeSource: "supabase",
+      cacheAuthoritative: false,
+      reason: String(params.reason || "manual"),
+      syncedAt: built.snapshot.syncedAt,
+      revisionVectorHash: built.snapshot.revisionVectorHash,
+      indexedVersions: built.snapshot.versions.length,
+      rejected: built.rejected,
+      index: indexStatus
+    };
+  }
+
+  async function sync(params = {}) {
+    if (syncPromise) return syncPromise;
+    const startedGeneration = invalidationGeneration;
+    syncPromise = auth.withSession(context => performSync(context, params, startedGeneration))
+      .catch(error => {
+        lastSyncError = normalizeError(error);
+        throw error;
+      })
+      .finally(() => { syncPromise = null; });
+    return syncPromise;
+  }
+
+  async function withLocalIndex(callback) {
+    return auth.withSession(async context => {
+      startRealtime(context.client);
+      return callback(await ensureIndex(context.user), context);
+    });
+  }
+
+  async function ensureReadableIndex(params = {}, reason = "read") {
+    if (params.fresh === true) {
+      await sync({ reason: `${reason}-fresh` });
+      return;
+    }
+    const status = await withLocalIndex(index => index.status());
+    if (!status.ready && status.available !== true) {
+      await sync({ reason: `${reason}-initial` });
+      return;
+    }
+    if (params.requireFresh === true && (invalidatedAt || status.freshness?.status !== "fresh")) {
+      await sync({ reason: `${reason}-fresh` });
+    }
+  }
+
+  async function search(params = {}) {
+    await ensureReadableIndex(params, "search");
+    return withLocalIndex(async index => {
+      const result = await index.search(params);
+      return {
+        ...result,
+        invalidatedAt,
+        invalidationReason,
+        realtimeState,
+        cacheAuthoritative: false,
+        requiresServerReadBeforeWrite: true
+      };
+    });
+  }
+
+  async function read(params = {}) {
+    if (params.component !== undefined && params.project === undefined) {
+      throw cliError("E_USAGE", "component를 읽으려면 project가 필요합니다.");
+    }
+    if (params.pointer !== undefined && params.component === undefined) {
+      throw cliError("E_USAGE", "JSON pointer를 읽으려면 component가 필요합니다.");
+    }
+    await ensureReadableIndex(params, "read");
+    return withLocalIndex(async index => {
+      const local = await index.getComponent({
+        ...(params.project !== undefined ? { project: params.project } : {}),
+        ...(params.version !== undefined ? { version: params.version } : {}),
+        ...(params.component !== undefined ? { component: params.component } : {}),
+        includeAssets: params.includeAssets === true || params.component !== undefined
+      });
+      const base = {
+        authoritative: false,
+        source: local.source,
+        requiresServerReadBeforeWrite: true,
+        freshness: local.freshness,
+        invalidatedAt,
+        invalidationReason
+      };
+      if (params.project === undefined) {
+        const grouped = new Map();
+        for (const component of local.components) {
+          const key = `${component.project.id}:${component.versionNumber}`;
+          if (!grouped.has(key)) grouped.set(key, {
+            project: component.project,
+            versionNumber: component.versionNumber,
+            componentCount: 0,
+            title: null
+          });
+          const summary = grouped.get(key);
+          summary.componentCount += 1;
+          if (component.templateId === "ssobig.basic" && typeof component.data?.title === "string") summary.title = component.data.title;
+        }
+        return { ...base, projects: [...grouped.values()] };
+      }
+      if (params.component === undefined) {
+        if (!local.components.length) throw cliError("E_PROJECT_NOT_FOUND", "로컬 인덱스에서 작품을 찾을 수 없습니다. 필요하면 fresh read를 실행해 주세요.");
+        return {
+          ...base,
+          project: local.components[0]?.project || { id: null, slug: String(params.project) },
+          versionNumber: local.components[0]?.versionNumber || params.version || null,
+          components: local.components.map(component => ({
+            instanceId: component.instanceId,
+            templateId: component.templateId,
+            revision: component.revision,
+            dataHash: component.dataHash,
+            shape: dataShape(component.data)
+          }))
+        };
+      }
+      if (!local.components.length) throw cliError("E_COMPONENT_NOT_FOUND", "로컬 인덱스에서 Component를 찾을 수 없습니다. 필요하면 fresh read를 실행해 주세요.");
+      if (local.components.length > 1) throw cliError("E_AMBIGUOUS_COMPONENT", "Component selector가 여러 Instance와 일치합니다. instance id를 사용해 주세요.");
+      const component = local.components[0];
+      const identity = {
+        instanceId: component.instanceId,
+        templateId: component.templateId,
+        revision: component.revision,
+        dataHash: component.dataHash
+      };
+      if (params.pointer !== undefined) {
+        const value = pointerValue(component.data, String(params.pointer));
+        return { ...base, project: component.project, versionNumber: component.versionNumber, component: identity, pointer: String(params.pointer), value };
+      }
+      return { ...base, project: component.project, versionNumber: component.versionNumber, component: identity, data: component.data };
+    });
+  }
+
+  async function resolveMatch(params, callback) {
+    const matchId = String(params?.matchId || "");
+    if (!matchId) throw cliError("E_USAGE", "matchId가 필요합니다.");
+    return auth.withSession(async context => {
+      const index = await ensureIndex(context.user);
+      const local = await index.getMatch(matchId);
+      const rawMatch = local?.match || local;
+      const match = rawMatch ? {
+        ...rawMatch,
+        projectId: rawMatch.projectId || rawMatch.project?.id,
+        projectSlug: rawMatch.projectSlug || rawMatch.project?.slug,
+        instanceId: rawMatch.instanceId || rawMatch.component?.instanceId,
+        templateId: rawMatch.templateId || rawMatch.component?.templateId,
+        instanceRevision: rawMatch.instanceRevision ?? rawMatch.component?.revision,
+        dataHash: rawMatch.dataHash || rawMatch.component?.dataHash,
+        componentSetRevision: rawMatch.componentSetRevision ?? rawMatch.componentSet?.revision,
+        componentChecksum: rawMatch.componentChecksum || rawMatch.componentSet?.checksum
+      } : null;
+      if (!match) throw cliError("E_MATCH_NOT_FOUND", "로컬 검색 결과를 찾을 수 없습니다. 다시 검색해 주세요.");
+      if (!match.projectId || !match.instanceId || typeof match.pointer !== "string") {
+        throw cliError("E_INDEX_CORRUPT", "로컬 검색 결과 identity가 완전하지 않습니다. writer_sync를 다시 실행해 주세요.");
+      }
+      const gateway = gatewayFactory(context.client);
+      const validated = validateLoadedVersion(await gateway.loadVersion(match.projectId, Number(match.versionNumber)));
+      const instance = findInstance(validated, match.instanceId);
+      const value = pointerValue(instance.data, match.pointer);
+      const staleMatch = Number(match.instanceRevision) !== Number(instance.revision)
+        || String(match.dataHash || "") !== sha256(instance.data)
+        || Number(match.componentSetRevision) !== Number(validated.componentSet.revision)
+        || String(match.componentChecksum || "") !== String(validated.componentSet.component_checksum || "");
+      return callback({ context, gateway, validated, instance, match, value, staleMatch });
+    });
+  }
+
+  async function get(params = {}) {
+    const maximumCharacters = Number(params.maximumCharacters ?? 2_000);
+    if (!Number.isSafeInteger(maximumCharacters) || maximumCharacters < 100 || maximumCharacters > 20_000) {
+      throw cliError("E_USAGE", "maximumCharacters는 100~20000 사이의 정수여야 합니다.");
+    }
+    return resolveMatch(params, async ({ validated, instance, match, value, staleMatch }) => ({
+      authoritative: true,
+      source: "supabase-authoritative-read",
+      project: { id: validated.project.id, slug: validated.project.slug },
+      versionNumber: validated.versionNumber,
+      component: {
+        instanceId: instance.instanceId,
+        templateId: instance.templateId,
+        revision: instance.revision,
+        dataHash: sha256(instance.data)
+      },
+      selected: {
+        matchId: match.matchId || String(params.matchId),
+        pointer: match.pointer,
+        staleMatch,
+        ...selectedValue(value, maximumCharacters)
+      }
+    }));
+  }
+
+  async function planReplace(params = {}) {
+    const outputPath = String(params.out || params.planPath || "");
+    if (!outputPath) throw cliError("E_USAGE", "검토할 plan 파일 경로(out)가 필요합니다.");
+    return resolveMatch(params, async ({ context, validated, instance, match, value, staleMatch }) => {
+      if (staleMatch) throw cliError("E_MATCH_STALE", "검색 결과 이후 Component revision 또는 hash가 변경되었습니다. writer_sync 후 다시 검색해 주세요.");
+      let replacement;
+      if (Object.hasOwn(params, "oldText") || Object.hasOwn(params, "newText")) {
+        replacement = replaceOccurrence(value, params.oldText, params.newText, params.occurrenceIndex);
+      } else {
+        if (!Object.hasOwn(params, "expectedValue") || !Object.hasOwn(params, "replacementValue")) {
+          throw cliError("E_USAGE", "oldText/newText 또는 expectedValue/replacementValue가 필요합니다.");
+        }
+        if (!equalJson(value, params.expectedValue)) throw cliError("E_CONFLICT", "서버 원본 값이 expectedValue와 다릅니다. 다시 검색해 주세요.");
+        replacement = params.replacementValue;
+      }
+      const patch = [
+        { op: "test", path: match.pointer, value },
+        { op: "replace", path: match.pointer, value: replacement }
+      ];
+      const plan = createComponentPlan(validated, instance.instanceId, patch, context.user.email, {
+        planId: crypto.randomUUID(),
+        createdAt: isoNow(),
+        ...(params.checkpointMessage !== undefined ? { checkpointMessage: String(params.checkpointMessage) } : {})
+      });
+      const planFile = writePrivateJson(outputPath, plan);
+      return {
+        planFile,
+        planId: plan.planId,
+        digest: plan.digest,
+        digestPurpose: "accidental-corruption-detection-not-approval-signature",
+        operation: plan.operation,
+        checkpointMessage: plan.checkpointMessage,
+        project: plan.project,
+        versionNumber: plan.versionNumber,
+        target: plan.target,
+        pointer: match.pointer,
+        beforeHash: plan.beforeHash,
+        afterHash: plan.afterHash,
+        reviewRequired: true,
+        applyRequiresExplicitCall: true
+      };
+    });
+  }
+
+  async function apply(params = {}) {
+    const planPath = String(params.planPath || params.plan || "");
+    const receiptPath = String(params.receiptPath || params.receipt || "");
+    if (!planPath || !receiptPath) throw cliError("E_USAGE", "planPath와 새 receiptPath가 필요합니다.");
+    return auth.withSession(async context => {
+      const planRead = readJson(planPath, "plan");
+      const plan = verifyPlan(planRead.value);
+      const reservation = reservePrivateJson(receiptPath);
+      const gateway = gatewayFactory(context.client);
+      let receipt;
+      try {
+        if (plan.operation === "project.create") receipt = await applyProjectCreationPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
+        else if (plan.operation === "project.catalog-demo") receipt = await applyCatalogDemoPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
+        else if (plan.operation.startsWith("project.")) receipt = await applyProjectStatusPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
+        else if (plan.operation === "component.patch") receipt = await applyComponentPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
+        else if (plan.operation.startsWith("checkpoint.")) receipt = await applyCheckpointPlan(gateway, plan, context.user.email, { appliedAt: isoNow() });
+        else receipt = await applyAssetPlan(gateway, plan, context.user.email, { appliedAt: isoNow(), now: Date.now });
+      } catch (error) {
+        reservation.discard();
+        throw error;
+      }
+      let receiptFile;
+      try { receiptFile = reservation.commit(receipt); }
+      catch (error) {
+        try { reservation.discard(); } catch (discardError) { void discardError; }
+        throw cliError("E_AMBIGUOUS_RECEIPT", "서버 쓰기는 완료됐지만 receipt 파일을 확정할 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+      }
+      invalidate("apply-readback-complete");
+      return { planFile: planRead.path, receiptFile, receipt, indexRefresh: "required" };
+    });
+  }
+
+  async function status() {
+    return {
+      running: true,
+      cacheDir,
+      cacheAuthoritative: false,
+      index: localIndex ? await localIndex.status() : { available: false, reason: "not-opened" },
+      invalidatedAt,
+      invalidationReason,
+      realtimeState,
+      syncing: Boolean(syncPromise),
+      lastSyncError: lastSyncError ? { code: lastSyncError.code, message: lastSyncError.message } : null
+    };
+  }
+
+  async function purge() {
+    const index = localIndex;
+    localIndex = null;
+    indexActorId = "";
+    const openedResult = index ? await index.purge() : null;
+    const remainingResult = purgeAllAgentIndexes({ cacheDir, platform, fs: options.fs });
+    invalidatedAt = null;
+    invalidationReason = null;
+    return { purged: true, removedIndexFiles: Number(openedResult?.removedFiles || 0) + remainingResult.removedFiles, cacheAuthoritative: false };
+  }
+
+  async function logout() {
+    const purgeResult = await purge();
+    const result = await auth.logout();
+    return { ...result, localIndexPurged: true, removedIndexFiles: purgeResult.removedIndexFiles };
+  }
+
+  async function close() {
+    if (realtimeClient && realtimeChannel) {
+      try { await realtimeClient.removeChannel(realtimeChannel); } catch (error) { void error; }
+    }
+    realtimeChannel = null;
+    if (localIndex) await localIndex.close();
+    localIndex = null;
+    await auth.dispose?.();
+  }
+
+  async function handle(method, params = {}) {
+    if (method === "status") return status();
+    if (method === "sync") return sync(params);
+    if (method === "search") return search(params);
+    if (method === "read") return read(params);
+    if (method === "get") return get(params);
+    if (method === "planReplace") return planReplace(params);
+    if (method === "apply") return apply(params);
+    if (method === "purge") return purge();
+    if (method === "logout") return logout();
+    throw cliError("E_DAEMON_METHOD", `지원하지 않는 Writer agent method입니다: ${String(method || "")}`);
+  }
+
+  return Object.freeze({ handle, sync, search, read, get, planReplace, apply, status, purge, logout, close });
+}
+
+module.exports = Object.freeze({ createAgentService, pointerValue, replaceOccurrence });

package/tools/writer-cli/src/asset-policy.cjs

@@ -0,0 +1,113 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { sha256 } = require("./json.cjs");
+const { cliError } = require("./errors.cjs");
+
+const MAX_BYTES = 15 * 1024 * 1024;
+const TYPES_BY_EXTENSION = Object.freeze({
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".json": "application/json"
+});
+const EXTENSION_BY_TYPE = Object.freeze({
+  "image/jpeg": "jpg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "application/json": "json"
+});
+
+function isImageAssetId(assetId) {
+  return ["poster", "logo", "workspace-background"].includes(assetId)
+    || assetId.startsWith("character-")
+    || assetId.startsWith("clue-image-");
+}
+
+function assertAssetId(assetId) {
+  const value = String(assetId || "");
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value)) throw cliError("E_VALIDATION", `에셋 ID 형식이 올바르지 않습니다: ${value || "(비어 있음)"}`);
+  return value;
+}
+
+function hasMagic(bytes, expected) {
+  return expected.every((value, index) => bytes[index] === value);
+}
+
+function assertFileContent(buffer, type) {
+  if (type === "image/jpeg" && !hasMagic(buffer, [0xff, 0xd8, 0xff])) throw cliError("E_VALIDATION", "JPEG 파일 signature가 올바르지 않습니다.");
+  if (type === "image/png" && !hasMagic(buffer, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) throw cliError("E_VALIDATION", "PNG 파일 signature가 올바르지 않습니다.");
+  if (type === "image/gif" && !["GIF87a", "GIF89a"].includes(buffer.subarray(0, 6).toString("ascii"))) throw cliError("E_VALIDATION", "GIF 파일 signature가 올바르지 않습니다.");
+  if (type === "image/webp" && !(buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP")) throw cliError("E_VALIDATION", "WebP 파일 signature가 올바르지 않습니다.");
+  if (type === "application/json") {
+    try { JSON.parse(buffer.toString("utf8")); }
+    catch (error) { throw cliError("E_VALIDATION", "JSON 파일 내용을 파싱할 수 없습니다.", null, error); }
+  }
+}
+
+function readAssetFile(filePath, assetId, options = {}) {
+  const fsApi = options.fs || fs;
+  const absolutePath = path.resolve(String(filePath || ""));
+  const type = TYPES_BY_EXTENSION[path.extname(absolutePath).toLowerCase()];
+  if (!type) throw cliError("E_VALIDATION", "JPEG, PNG, WebP, GIF 이미지와 JSON 파일만 업로드할 수 있습니다.");
+  const normalizedAssetId = assertAssetId(assetId);
+  if (isImageAssetId(normalizedAssetId) && type === "application/json") throw cliError("E_VALIDATION", "포스터, 로고, 배경, 캐릭터와 단서 에셋에는 이미지만 연결할 수 있습니다.");
+  let handle = null;
+  let stat;
+  try {
+    const pathStat = fsApi.lstatSync(absolutePath);
+    if (!pathStat.isFile()) throw cliError("E_VALIDATION", `업로드 대상은 symlink가 아닌 일반 파일이어야 합니다: ${absolutePath}`);
+    const noFollow = Number(fsApi.constants?.O_NOFOLLOW ?? fs.constants.O_NOFOLLOW ?? 0);
+    handle = fsApi.openSync(absolutePath, fs.constants.O_RDONLY | noFollow);
+    stat = fsApi.fstatSync(handle);
+  }
+  catch (error) {
+    if (error.code?.startsWith?.("E_")) throw error;
+    throw cliError("E_FILE_NOT_FOUND", `업로드 파일을 읽을 수 없습니다: ${absolutePath}`, null, error);
+  }
+  if (!stat.isFile()) {
+    try { fsApi.closeSync(handle); } catch (error) { void error; }
+    throw cliError("E_VALIDATION", `업로드 대상이 일반 파일이 아닙니다: ${absolutePath}`);
+  }
+  if (stat.size > MAX_BYTES) {
+    try { fsApi.closeSync(handle); } catch (error) { void error; }
+    throw cliError("E_VALIDATION", "파일 크기는 15MB 이하여야 합니다.");
+  }
+  const buffer = Buffer.allocUnsafe(stat.size);
+  let offset = 0;
+  try {
+    while (offset < stat.size) {
+      const count = fsApi.readSync(handle, buffer, offset, stat.size - offset, offset);
+      if (count === 0) break;
+      offset += count;
+    }
+    const afterStat = fsApi.fstatSync(handle);
+    if (offset !== stat.size || afterStat.size !== stat.size) throw cliError("E_CONFLICT", "파일을 읽는 동안 크기가 변경되었습니다. 새 plan을 만들어 주세요.");
+  } catch (error) {
+    if (error.code?.startsWith?.("E_")) throw error;
+    throw cliError("E_FILE_NOT_FOUND", `업로드 파일을 읽을 수 없습니다: ${absolutePath}`, null, error);
+  } finally {
+    try { fsApi.closeSync(handle); } catch (error) { void error; }
+  }
+  assertFileContent(buffer, type);
+  const metadata = Object.freeze({
+    path: absolutePath,
+    name: path.basename(absolutePath),
+    type,
+    extension: EXTENSION_BY_TYPE[type],
+    size: stat.size,
+    mtimeMs: Math.trunc(stat.mtimeMs),
+    contentHash: sha256(buffer)
+  });
+  return Object.freeze({ metadata, buffer });
+}
+
+function inspectAssetFile(filePath, assetId, options = {}) {
+  return readAssetFile(filePath, assetId, options).metadata;
+}
+
+module.exports = Object.freeze({ MAX_BYTES, TYPES_BY_EXTENSION, EXTENSION_BY_TYPE, isImageAssetId, assertAssetId, readAssetFile, inspectAssetFile });