@ssobig/writer-cli 0.2.0

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

@@ -0,0 +1,47 @@
+"use strict";
+
+class WriterCliError extends Error {
+  constructor(code, message, details = null, options = {}) {
+    super(String(message || code), options);
+    this.name = "WriterCliError";
+    this.code = String(code || "E_WRITER_CLI");
+    this.details = details && typeof details === "object" ? details : null;
+  }
+}
+
+function cliError(code, message, details = null, cause = null) {
+  return new WriterCliError(code, message, details, cause ? { cause } : {});
+}
+
+function redact(value) {
+  return String(value || "")
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, "[REDACTED_JWT]")
+    .replace(/((?:access|refresh)_token\s*[=:]\s*)[^\s,}\]]+/gi, "$1[REDACTED]");
+}
+
+function normalizeError(error) {
+  if (error instanceof WriterCliError) return error;
+  const sourceCode = String(error?.code || "");
+  const status = Number(error?.status || 0);
+  if (["40001", "PT409", "23505"].includes(sourceCode) || status === 409) {
+    return cliError("E_CONFLICT", "다른 화면 또는 작업이 먼저 저장했습니다. 새 plan을 만들어 다시 검토해 주세요.", null, error);
+  }
+  if (sourceCode === "42501") {
+    return cliError("E_AUTHORIZATION", "이 Writer 데이터에 접근할 권한이 없습니다.", null, error);
+  }
+  if (sourceCode === "P0001" && /SOMI_CHECKPOINT_NO_CHANGES/.test(String(error?.message || ""))) {
+    return cliError("E_NO_CHANGES", "Latest가 이미 해당 체크포인트 상태와 같습니다.", null, error);
+  }
+  if (sourceCode === "P0001" && /E_CODE_CHANGE_REQUIRED/.test(String(error?.message || ""))) {
+    return cliError("E_CODE_CHANGE_REQUIRED", "체크포인트의 Component 구성 또는 schema가 현재 Latest와 달라 CLI에서 복원할 수 없습니다.", null, error);
+  }
+  if (sourceCode === "22023") {
+    return cliError("E_VALIDATION", redact(error?.message || "Writer 입력값이 올바르지 않습니다."), null, error);
+  }
+  if (sourceCode === "SOMI_MIGRATION_REQUIRED") {
+    return cliError("E_MIGRATION_REQUIRED", redact(error.message), null, error);
+  }
+  return cliError(sourceCode && /^E_/.test(sourceCode) ? sourceCode : "E_WRITER_CLI", redact(error?.message || "Writer CLI 작업에 실패했습니다."), null, error);
+}
+
+module.exports = Object.freeze({ WriterCliError, cliError, normalizeError, redact });

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

@@ -0,0 +1,357 @@
+"use strict";
+
+const projectRuntime = require("../../../project-runtime.js");
+const {
+  PROJECT_COLUMNS,
+  VERSION_COLUMNS,
+  SET_COLUMNS,
+  INSTANCE_COLUMNS,
+  VIEW_COLUMNS,
+  BINDING_COLUMNS,
+  CHECKPOINT_COLUMNS,
+  CHECKPOINT_ENTRY_COLUMNS
+} = require("./domain.cjs");
+const { cliError } = require("./errors.cjs");
+
+function dataOrThrow(result) {
+  if (result?.error) throw result.error;
+  return result?.data;
+}
+
+const PAGE_SIZE = 1_000;
+const PROJECT_ID_CHUNK_SIZE = 100;
+
+function chunks(values, size = PROJECT_ID_CHUNK_SIZE) {
+  const output = [];
+  for (let index = 0; index < values.length; index += size) output.push(values.slice(index, index + size));
+  return output;
+}
+
+async function collectPages(buildQuery) {
+  const rows = [];
+  for (let offset = 0; ; offset += PAGE_SIZE) {
+    const query = buildQuery().range(offset, offset + PAGE_SIZE - 1);
+    const page = dataOrThrow(await query) || [];
+    rows.push(...page);
+    if (page.length < PAGE_SIZE) return rows;
+  }
+}
+
+function createSupabaseGateway(client, options = {}) {
+  if (!client?.from || !client?.rpc || !client?.storage?.from) throw cliError("E_CONFIGURATION", "Supabase client 설정이 완전하지 않습니다.");
+  const bucketName = String(options.bucketName || "");
+  if (!bucketName) throw cliError("E_CONFIGURATION", "Writer Storage 버킷 설정이 필요합니다.");
+
+  function projectStatus(value = "active") {
+    const status = String(value || "");
+    if (!["active", "archived"].includes(status)) throw cliError("E_USAGE", "--status는 active 또는 archived여야 합니다.");
+    return status;
+  }
+
+  async function listProjects(status = "active") {
+    const normalizedStatus = projectStatus(status);
+    return collectPages(() => client
+      .from("somi_projects")
+      .select(PROJECT_COLUMNS)
+      .eq("status", normalizedStatus)
+      .order("updated_at", { ascending: false })
+      .order("id", { ascending: true }));
+  }
+
+  async function getProject(projectRef, status = "active") {
+    const value = String(projectRef || "").trim();
+    if (!value) throw cliError("E_USAGE", "--project 값이 필요합니다.");
+    const normalizedStatus = projectStatus(status);
+    let query = client.from("somi_projects").select(PROJECT_COLUMNS).eq("status", normalizedStatus);
+    query = projectRuntime.UUID_PATTERN.test(value) ? query.eq("id", value.toLowerCase()) : query.eq("slug", value);
+    const row = dataOrThrow(await query.maybeSingle());
+    if (!row) throw cliError("E_PROJECT_NOT_FOUND", `${normalizedStatus} 작품을 찾을 수 없습니다: ${value}`);
+    return row;
+  }
+
+  async function findProjectBySlug(slug) {
+    const value = String(slug || "").trim();
+    if (!value) throw cliError("E_USAGE", "작품 slug가 필요합니다.");
+    return dataOrThrow(await client
+      .from("somi_projects")
+      .select(PROJECT_COLUMNS)
+      .eq("slug", value)
+      .maybeSingle()) || null;
+  }
+
+  async function listVersions(projectId) {
+    return dataOrThrow(await client
+      .from("somi_project_versions")
+      .select(VERSION_COLUMNS)
+      .eq("project_id", String(projectId))
+      .order("version_number", { ascending: false })) || [];
+  }
+
+  async function loadCorpus(status = "active") {
+    const projects = await listProjects(status);
+    if (!projects.length) {
+      return {
+        projects: [],
+        versionRows: [],
+        componentSetRows: [],
+        componentRows: [],
+        viewRows: [],
+        bindingRows: []
+      };
+    }
+    const projectIds = projects.map(project => String(project.id));
+    async function loadTable(table, columns, orders) {
+      const batches = await Promise.all(chunks(projectIds).map(projectIdBatch => collectPages(() => {
+        let query = client.from(table).select(columns).in("project_id", projectIdBatch);
+        for (const [column, ascending] of orders) query = query.order(column, { ascending });
+        return query;
+      })));
+      return batches.flat();
+    }
+    const [versionResult, setResult, componentResult, viewResult, bindingResult] = await Promise.all([
+      loadTable("somi_project_versions", VERSION_COLUMNS, [["project_id", true], ["version_number", false]]),
+      loadTable("somi_project_component_sets", SET_COLUMNS, [["project_id", true], ["version_number", false]]),
+      loadTable("somi_project_component_instances", INSTANCE_COLUMNS, [["project_id", true], ["version_number", true], ["sort_order", true], ["instance_id", true]]),
+      loadTable("somi_project_view_component_instances", `project_id,version_number,${VIEW_COLUMNS}`, [["project_id", true], ["version_number", true], ["sort_order", true], ["view_instance_id", true]]),
+      loadTable("somi_project_view_component_bindings", `project_id,version_number,${BINDING_COLUMNS}`, [["project_id", true], ["version_number", true], ["sort_order", true], ["view_instance_id", true], ["binding_key", true]])
+    ]);
+    const [verifiedSets, verifiedProjects] = await Promise.all([
+      loadTable("somi_project_component_sets", SET_COLUMNS, [["project_id", true], ["version_number", false]]),
+      listProjects(status)
+    ]);
+    const setVector = rows => rows.map(row => [String(row.project_id), Number(row.version_number), Number(row.revision), String(row.component_checksum)]);
+    const projectVector = rows => rows.map(row => [String(row.id), String(row.status), String(row.updated_at)]).sort((left, right) => left[0].localeCompare(right[0]));
+    if (JSON.stringify(setVector(setResult)) !== JSON.stringify(setVector(verifiedSets))
+      || JSON.stringify(projectVector(projects)) !== JSON.stringify(projectVector(verifiedProjects))) {
+      throw cliError("E_CORPUS_CHANGED", "동기화 중 Writer 원본 revision이 변경되었습니다. 전체 snapshot을 다시 읽어야 합니다.");
+    }
+    return {
+      projects,
+      versionRows: versionResult,
+      componentSetRows: setResult,
+      componentRows: componentResult,
+      viewRows: viewResult,
+      bindingRows: bindingResult
+    };
+  }
+
+  async function loadVersion(projectRef, versionNumber) {
+    const project = await getProject(projectRef);
+    const version = Number(versionNumber);
+    if (!Number.isSafeInteger(version) || version < 1) throw cliError("E_USAGE", "--version에는 1 이상의 정수가 필요합니다.");
+    const [versionResult, setResult, componentResult, viewResult, bindingResult] = await Promise.all([
+      client.from("somi_project_versions").select(VERSION_COLUMNS).eq("project_id", project.id).eq("version_number", version).maybeSingle(),
+      client.from("somi_project_component_sets").select(SET_COLUMNS).eq("project_id", project.id).eq("version_number", version).maybeSingle(),
+      client.from("somi_project_component_instances").select(INSTANCE_COLUMNS).eq("project_id", project.id).eq("version_number", version).order("sort_order", { ascending: true }),
+      client.from("somi_project_view_component_instances").select(VIEW_COLUMNS).eq("project_id", project.id).eq("version_number", version).order("sort_order", { ascending: true }),
+      client.from("somi_project_view_component_bindings").select(BINDING_COLUMNS).eq("project_id", project.id).eq("version_number", version).order("sort_order", { ascending: true })
+    ]);
+    const versionRow = dataOrThrow(versionResult);
+    if (!versionRow) throw cliError("E_VERSION_NOT_FOUND", `${project.slug}의 v${version}을 찾을 수 없습니다.`);
+    return {
+      project,
+      version: versionRow,
+      componentSet: dataOrThrow(setResult),
+      componentRows: dataOrThrow(componentResult) || [],
+      viewRows: dataOrThrow(viewResult) || [],
+      bindingRows: dataOrThrow(bindingResult) || []
+    };
+  }
+
+  async function loadLatestVersion(projectRef, versionNumber = null) {
+    if (versionNumber !== null && versionNumber !== undefined && versionNumber !== "") {
+      return loadVersion(projectRef, Number(versionNumber));
+    }
+    const project = await getProject(projectRef);
+    const activeSet = dataOrThrow(await client
+      .from("somi_project_component_sets")
+      .select(SET_COLUMNS)
+      .eq("project_id", project.id)
+      .eq("canonical_status", "active")
+      .maybeSingle());
+    if (!activeSet) throw cliError("E_MIGRATION_REQUIRED", `${project.slug}의 단일 Latest workspace를 찾을 수 없습니다.`);
+    return loadVersion(project.id, Number(activeSet.version_number));
+  }
+
+  async function listCheckpoints(input) {
+    return dataOrThrow(await client.rpc("list_somi_project_checkpoints", {
+      p_project_id: String(input.projectId),
+      p_version_number: Number(input.versionNumber),
+      p_before_checkpoint_number: input.beforeCheckpointNumber === null || input.beforeCheckpointNumber === undefined
+        ? null
+        : Number(input.beforeCheckpointNumber),
+      p_limit: Number(input.limit || 50)
+    })) || [];
+  }
+
+  async function getCheckpoint(projectId, versionNumber, selector) {
+    const value = String(selector || "").trim();
+    if (!value) throw cliError("E_USAGE", "체크포인트 ID 또는 번호가 필요합니다.");
+    let query = client.from("somi_project_checkpoints")
+      .select(CHECKPOINT_COLUMNS)
+      .eq("project_id", String(projectId))
+      .eq("version_number", Number(versionNumber));
+    if (/^[1-9][0-9]*$/.test(value)) query = query.eq("checkpoint_number", Number(value));
+    else {
+      if (!projectRuntime.UUID_PATTERN.test(value)) throw cliError("E_USAGE", "--checkpoint에는 1 이상의 번호 또는 UUID가 필요합니다.");
+      query = query.eq("checkpoint_id", value.toLowerCase());
+    }
+    const row = dataOrThrow(await query.maybeSingle());
+    if (!row) throw cliError("E_CHECKPOINT_NOT_FOUND", `체크포인트를 찾을 수 없습니다: ${value}`);
+    return row;
+  }
+
+  async function getCheckpointByOperation(projectId, versionNumber, operationId) {
+    return dataOrThrow(await client.from("somi_project_checkpoints")
+      .select(CHECKPOINT_COLUMNS)
+      .eq("project_id", String(projectId))
+      .eq("version_number", Number(versionNumber))
+      .eq("operation_id", String(operationId))
+      .maybeSingle()) || null;
+  }
+
+  async function getCheckpointSnapshot(projectId, versionNumber, selector, options = {}) {
+    const checkpoint = await getCheckpoint(projectId, versionNumber, selector);
+    const entries = await collectPages(() => client.from("somi_project_checkpoint_entries")
+      .select(CHECKPOINT_ENTRY_COLUMNS)
+      .eq("checkpoint_id", checkpoint.checkpoint_id)
+      .eq("project_id", String(projectId))
+      .eq("version_number", Number(versionNumber))
+      .order("sort_order", { ascending: true })
+      .order("instance_id", { ascending: true }));
+    if (options.includeData !== true || !entries.length) return { checkpoint, entries };
+    const hashes = [...new Set(entries.map(entry => String(entry.data_hash)))];
+    const blobBatches = await Promise.all(chunks(hashes).map(hashBatch => collectPages(() => client
+      .from("somi_project_checkpoint_blobs")
+      .select("project_id,content_hash,data")
+      .eq("project_id", String(projectId))
+      .in("content_hash", hashBatch)
+      .order("content_hash", { ascending: true }))));
+    const blobs = blobBatches.flat();
+    const dataByHash = new Map(blobs.map(blob => [String(blob.content_hash), blob.data]));
+    const missing = hashes.find(hash => !dataByHash.has(hash));
+    if (missing) throw cliError("E_MIGRATION_REQUIRED", `체크포인트 payload blob을 찾을 수 없습니다: ${missing}`);
+    return {
+      checkpoint,
+      entries: entries.map(entry => ({ ...entry, data: dataByHash.get(String(entry.data_hash)) }))
+    };
+  }
+
+  async function createCheckpoint(input) {
+    return dataOrThrow(await client.rpc("create_somi_project_checkpoint", {
+      p_project_id: String(input.projectId),
+      p_version_number: Number(input.versionNumber),
+      p_expected_set_revision: Number(input.expectedSetRevision),
+      p_expected_component_checksum: String(input.expectedComponentChecksum),
+      p_message: String(input.message),
+      p_operation_id: String(input.operationId),
+      p_updated_by_email: String(input.actorEmail || "")
+    }));
+  }
+
+  async function restoreCheckpoint(input) {
+    return dataOrThrow(await client.rpc("restore_somi_project_checkpoint", {
+      p_project_id: String(input.projectId),
+      p_version_number: Number(input.versionNumber),
+      p_checkpoint_id: String(input.checkpointId),
+      p_expected_set_revision: Number(input.expectedSetRevision),
+      p_expected_component_checksum: String(input.expectedComponentChecksum),
+      p_message: String(input.message),
+      p_operation_id: String(input.operationId),
+      p_updated_by_email: String(input.actorEmail || "")
+    }));
+  }
+
+  async function saveInstance(input) {
+    const args = {
+      p_project_id: String(input.projectId),
+      p_version_number: Number(input.versionNumber),
+      p_instance: input.payload,
+      p_expected_revision: Number(input.expectedRevision),
+      p_updated_by_email: String(input.actorEmail || "")
+    };
+    if (input.checkpointMessage !== undefined) {
+      args.p_checkpoint_message = String(input.checkpointMessage || "");
+      args.p_checkpoint_source = "cli";
+    }
+    const result = await client.rpc("save_somi_project_component_instance", args);
+    return dataOrThrow(result);
+  }
+
+  async function setProjectArchived(input) {
+    return dataOrThrow(await client.rpc("set_somi_project_archived", {
+      p_project_id: String(input.projectId || ""),
+      p_expected_status: String(input.expectedStatus || ""),
+      p_expected_updated_at: String(input.expectedUpdatedAt || ""),
+      p_archived: input.archived === true,
+      p_updated_by_email: String(input.actorEmail || "")
+    }));
+  }
+
+  async function setCatalogDemoProject(input) {
+    return dataOrThrow(await client.rpc("set_somi_catalog_demo_project", {
+      p_project_id: String(input.projectId || ""),
+      p_expected_is_catalog_demo: input.expectedIsCatalogDemo === true,
+      p_expected_updated_at: String(input.expectedUpdatedAt || ""),
+      p_enabled: input.enabled === true
+    }));
+  }
+
+  async function createScaffoldProject(input) {
+    return dataOrThrow(await client.rpc("create_somi_project_from_scaffold", {
+      p_slug: String(input.slug || ""),
+      p_title: String(input.title || ""),
+      p_author_name: String(input.authorName || "")
+    }));
+  }
+
+  async function createImportedProject(input) {
+    return dataOrThrow(await client.rpc("create_somi_project_from_import", {
+      p_slug: String(input.slug || ""),
+      p_title: String(input.title || ""),
+      p_author_name: String(input.authorName || ""),
+      p_components: input.components,
+      p_source: input.provenance
+    }));
+  }
+
+  async function uploadObject(objectPath, body, uploadOptions = {}) {
+    const result = await client.storage.from(bucketName).upload(objectPath, body, {
+      ...uploadOptions,
+      upsert: false
+    });
+    dataOrThrow(result);
+    return { path: objectPath };
+  }
+
+  async function removeObjects(paths) {
+    const result = await client.storage.from(bucketName).remove(paths);
+    dataOrThrow(result);
+    return { paths: [...paths] };
+  }
+
+  return Object.freeze({
+    listProjects,
+    getProject,
+    findProjectBySlug,
+    listVersions,
+    loadCorpus,
+    loadVersion,
+    loadLatestVersion,
+    listCheckpoints,
+    getCheckpoint,
+    getCheckpointByOperation,
+    getCheckpointSnapshot,
+    createCheckpoint,
+    restoreCheckpoint,
+    saveInstance,
+    setProjectArchived,
+    setCatalogDemoProject,
+    createScaffoldProject,
+    createImportedProject,
+    uploadObject,
+    removeObjects
+  });
+}
+
+module.exports = Object.freeze({ createSupabaseGateway, dataOrThrow });