@ssobig/writer-cli 0.2.0

package/README.md

@@ -0,0 +1,35 @@
+# @ssobig/writer-cli
+
+SSOBIG WRITER의 공식 Agent CLI다. Google 계정으로 로그인한 뒤 본인이 소유하거나 공유받은 Writer 작품을 서버 권한 범위 안에서 읽고, 검토된 plan만 적용한다.
+
+현재 지원 환경은 macOS 또는 Windows 10/11과 Node.js 22.13.0 이상이다. CLI는 일반 Writer 회원의 소유자·공동 편집자·뷰어 권한을 그대로 사용하며, server RLS와 focused RPC를 우회하지 않는다.
+
+## 설치
+
+```bash
+npm install --global @ssobig/writer-cli@latest
+ssobig-writer doctor
+ssobig-writer skills install --target <내-workspace>
+ssobig-writer auth login
+ssobig-writer auth whoami
+ssobig-writer project list
+```
+
+CLI는 stdout에 JSON 문서 하나를 출력한다. 원고 변경은 `plan -> 사람 검토 -> apply -> authoritative read-back` 절차만 사용하며, 범용 SQL이나 직접 table update를 제공하지 않는다.
+
+## 업데이트와 제거
+
+```bash
+ssobig-writer version --check
+npm install --global @ssobig/writer-cli@latest
+
+ssobig-writer auth logout
+ssobig-writer agent purge
+npm uninstall --global @ssobig/writer-cli
+```
+
+0.2.0부터 npm `latest`보다 낮은 CLI의 서버 접속 명령은 실행 전에 `E_CLI_UPDATE_REQUIRED`로 중단된다. help, targeted `command-schema`, `version --check`, `doctor`, `skills *`, logout과 daemon 정리 명령은 업데이트 전에도 사용할 수 있다. 0.1.0 사용자는 위 npm 설치 명령을 다시 실행해 0.2.0 이상으로 전환해야 한다. registry가 일시적으로 응답하지 않으면 새 작업을 차단하지 않지만, 로컬 cache가 이미 더 높은 버전을 확인했다면 계속 업데이트를 요구한다.
+
+`doctor`는 설치·최신 버전·credential session 존재·Auth health·실행 backend 버전을 읽기 전용으로 진단하고 token, 이메일, 원고 값을 출력하지 않는다. macOS 세션은 Keychain에 저장되고 private Unix daemon을 사용한다. Windows 세션은 현재 Windows 사용자만 해독할 수 있도록 DPAPI CurrentUser로 보호되며 CLI는 background daemon 대신 in-process backend를 자동 사용한다. 따라서 Windows에서는 `agent start`와 `agent stop`이 지원되지 않는다.
+
+상세 설치, 업데이트, 삭제 방법은 [SSOBIG WRITER 운영 가이드](https://writer.ssobig.com/)에서 확인한다.

package/asset-repository.js

@@ -0,0 +1,278 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === "object" && module.exports) module.exports = api;
+  root.SomiAssetRepository = api;
+})(typeof globalThis !== "undefined" ? globalThis : window, function () {
+  function cloneManifest(manifest) {
+    return { ...(manifest || {}), assets: { ...(manifest?.assets || {}) } };
+  }
+
+  function normalizeSnapshot(snapshot) {
+    if (snapshot && typeof snapshot === "object" && Object.prototype.hasOwnProperty.call(snapshot, "manifest")) {
+      return { manifest: cloneManifest(snapshot.manifest), revision: snapshot.revision, instanceId: snapshot.instanceId };
+    }
+    return { manifest: cloneManifest(snapshot), revision: undefined, instanceId: undefined };
+  }
+
+  function manifestReferencesPath(manifest, path) {
+    return Boolean(path && Object.values(manifest?.assets || {}).some(asset => !asset?.deleted && asset?.path === path));
+  }
+
+  function buildAssetRestorePlan(manifest) {
+    return Object.entries(manifest?.assets || {})
+      .filter(([, asset]) => Boolean(asset?.path && !asset.deleted))
+      .map(([assetId, asset]) => ({ localAssetId: assetId, manifestAssetId: assetId, asset }));
+  }
+
+  async function restoreAssetStore(manifest, options = {}) {
+    if (typeof options.deleteLocalAssetIds !== "function") throw new TypeError("에셋 복원에는 deleteLocalAssetIds 함수가 필요합니다.");
+    if (typeof options.downloadAsset !== "function") throw new TypeError("에셋 복원에는 downloadAsset 함수가 필요합니다.");
+    if (typeof options.putLocalAsset !== "function") throw new TypeError("에셋 복원에는 putLocalAsset 함수가 필요합니다.");
+    const queue = buildAssetRestorePlan(manifest);
+    const restoredLocalAssetIds = [];
+    const concurrency = Math.max(1, Number(options.concurrency || 6));
+    const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length) {
+        const entry = queue.shift();
+        const blob = await options.downloadAsset(entry);
+        if (!blob) continue;
+        await options.putLocalAsset(entry.localAssetId, blob);
+        restoredLocalAssetIds.push(entry.localAssetId);
+      }
+    });
+    await Promise.all(workers);
+    return { clearLocalAssetIds: [], restoredLocalAssetIds };
+  }
+
+  async function defaultContentHash(blob) {
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    if (globalThis.crypto?.subtle) {
+      const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+      return Array.from(new Uint8Array(digest), value => value.toString(16).padStart(2, "0")).join("");
+    }
+    let hash = 2166136261;
+    bytes.forEach(value => {
+      hash ^= value;
+      hash = Math.imul(hash, 16777619);
+    });
+    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, "0")}`;
+  }
+
+  function defaultOperationId() {
+    const random = globalThis.crypto?.randomUUID?.() || Math.random().toString(36).slice(2);
+    return `${Date.now()}-${random}`;
+  }
+
+  class AssetRepository {
+    constructor(options = {}) {
+      for (const name of ["readManifest", "saveManifest", "uploadBlob", "removeBlobs", "buildImmutablePath"]) {
+        if (typeof options[name] !== "function") throw new TypeError(`AssetRepository에는 ${name} 함수가 필요합니다.`);
+      }
+      this.readManifest = options.readManifest;
+      this.saveManifest = options.saveManifest;
+      this.uploadBlob = options.uploadBlob;
+      this.removeBlobs = options.removeBlobs;
+      this.buildImmutablePath = options.buildImmutablePath;
+      this.contentHash = options.contentHash || defaultContentHash;
+      this.operationId = options.operationId || defaultOperationId;
+      this.onManifest = typeof options.onManifest === "function" ? options.onManifest : () => {};
+      this.onOrphan = typeof options.onOrphan === "function" ? options.onOrphan : () => {};
+      this.onRecoveredCommit = typeof options.onRecoveredCommit === "function" ? options.onRecoveredCommit : () => {};
+      this.now = options.now || Date.now;
+      this.chain = Promise.resolve();
+      this.orphans = [];
+      this.failures = new Map();
+      this.pendingCount = 0;
+      this.cancelledError = null;
+    }
+
+    enqueue(assetId, operation) {
+      if (this.cancelledError) return Promise.reject(this.cancelledError);
+      this.pendingCount += 1;
+      const result = this.chain.catch(() => {}).then(() => {
+        if (this.cancelledError) throw this.cancelledError;
+        return operation();
+      }).then(value => {
+        this.failures.delete(assetId);
+        return value;
+      }).catch(error => {
+        this.failures.set(assetId, error);
+        throw error;
+      }).finally(() => {
+        this.pendingCount -= 1;
+      });
+      this.chain = result;
+      return result;
+    }
+
+    cancelAll(error) {
+      if (!this.cancelledError) {
+        this.cancelledError = error instanceof Error ? error : new Error(String(error || "에셋 저장이 취소되었습니다."));
+      }
+      return this.cancelledError;
+    }
+
+    upload(assetId, blob, options = {}) {
+      const key = String(assetId);
+      return this.enqueue(key, () => this.performUpload(key, blob, options));
+    }
+
+    remove(assetId, options = {}) {
+      const key = String(assetId);
+      return this.enqueue(key, () => this.performRemove(key, options));
+    }
+
+    async drain() {
+      while (true) {
+        const activeChain = this.chain;
+        let result;
+        try { result = await activeChain; } catch (error) {}
+        if (activeChain !== this.chain) continue;
+        if (this.failures.size) {
+          const error = new AggregateError([...this.failures.values()], "일부 에셋을 저장하지 못했습니다.");
+          error.code = "SOMI_ASSET_DRAIN_FAILED";
+          error.assetIds = [...this.failures.keys()];
+          throw error;
+        }
+        return result;
+      }
+    }
+
+    hasPending() {
+      return this.pendingCount > 0;
+    }
+
+    hasFailures() {
+      return this.failures.size > 0;
+    }
+
+    orphan(path, reason, error = null) {
+      const record = { path, reason, error, recordedAt: this.now() };
+      this.orphans.push(record);
+      try { this.onOrphan(record); } catch (callbackError) { console.error(callbackError); }
+      return record;
+    }
+
+    getOrphans() {
+      return this.orphans.map(orphan => ({ ...orphan }));
+    }
+
+    async removePaths(paths, reason) {
+      const uniquePaths = [...new Set((paths || []).filter(Boolean))];
+      if (!uniquePaths.length) return true;
+      try {
+        await this.removeBlobs(uniquePaths);
+        return true;
+      } catch (error) {
+        uniquePaths.forEach(path => this.orphan(path, reason, error));
+        return false;
+      }
+    }
+
+    // 매니페스트에 한 번이라도 커밋된 경로는 물리 삭제하지 않는다.
+    // 복사본이 원본의 자산 경로를 그대로 참조하므로, 원본에서 지운 자산을
+    // 스토리지에서 없애면 복사본의 참조가 함께 깨진다.
+    // 매니페스트에서 빠진 자산은 해당 작품에서만 보이지 않게 되고 파일은 남는다.
+
+    async performUpload(assetId, blob, options) {
+      if (!blob || typeof blob.arrayBuffer !== "function") throw new TypeError("업로드할 에셋은 Blob이어야 합니다.");
+      const contentHash = await this.contentHash(blob);
+      const operationId = String(this.operationId());
+      const currentSnapshot = normalizeSnapshot(await this.readManifest());
+      const currentManifest = currentSnapshot.manifest;
+      const previous = currentManifest.assets[assetId];
+      if (options.dedupe !== false && previous?.path && !previous.deleted && previous.contentHash === contentHash) {
+        return { unchanged: true, path: previous.path, manifest: currentManifest, entry: previous };
+      }
+
+      const path = this.buildImmutablePath({ assetId, blob, contentHash, operationId, options, previous });
+      if (!path || previous?.path === path) throw new Error("에셋 저장 경로는 기존 경로와 다른 immutable 경로여야 합니다.");
+      try {
+        await this.uploadBlob(path, blob, { upsert: false, contentType: blob.type || undefined });
+      } catch (uploadError) {
+        await this.removePaths([path], "failed-blob-upload");
+        throw uploadError;
+      }
+
+      const entry = {
+        ...(options.metadata || {}),
+        path,
+        name: String(options.name || blob.name || assetId),
+        type: String(options.type || blob.type || "application/octet-stream"),
+        contentHash,
+        operationId,
+        updatedAt: this.now()
+      };
+      const nextManifest = cloneManifest(currentManifest);
+      nextManifest.assets[assetId] = entry;
+
+      try {
+        await this.saveManifest(nextManifest, currentSnapshot);
+      } catch (saveError) {
+        let authoritativeManifest = null;
+        try { authoritativeManifest = normalizeSnapshot(await this.readManifest()).manifest; }
+        catch (readError) { this.orphan(path, "manifest-state-unknown", readError); }
+        if (authoritativeManifest) this.onManifest(authoritativeManifest);
+        if (authoritativeManifest?.assets?.[assetId]?.path === path) {
+          this.onRecoveredCommit({ assetId, path, manifest: authoritativeManifest, entry: authoritativeManifest.assets[assetId] });
+          return { path, manifest: authoritativeManifest, entry: authoritativeManifest.assets[assetId], recoveredCommit: true };
+        }
+        if (authoritativeManifest && !manifestReferencesPath(authoritativeManifest, path)) {
+          await this.removePaths([path], "failed-pointer-upload");
+        }
+        throw saveError;
+      }
+
+      this.onManifest(nextManifest);
+      // 교체된 이전 파일은 남겨 둔다. 다른 작품(복사본)이 그 경로를 참조할 수 있다.
+      return { path, manifest: nextManifest, entry };
+    }
+
+    async performRemove(assetId, options) {
+      const currentSnapshot = normalizeSnapshot(await this.readManifest());
+      const currentManifest = currentSnapshot.manifest;
+      const previous = currentManifest.assets[assetId];
+      if (!previous?.path && !options.tombstone) return { unchanged: true, manifest: currentManifest };
+      if (options.tombstone && previous?.deleted === true) return { unchanged: true, manifest: currentManifest };
+
+      const nextManifest = cloneManifest(currentManifest);
+      if (options.tombstone) {
+        nextManifest.assets[assetId] = {
+          deleted: true,
+          operationId: String(this.operationId()),
+          updatedAt: this.now()
+        };
+      } else {
+        delete nextManifest.assets[assetId];
+      }
+      try {
+        await this.saveManifest(nextManifest, currentSnapshot);
+      } catch (saveError) {
+        let authoritativeManifest = null;
+        try { authoritativeManifest = normalizeSnapshot(await this.readManifest()).manifest; }
+        catch (readError) { void readError; }
+        const authoritativeEntry = authoritativeManifest?.assets?.[assetId];
+        const expectedOperationId = nextManifest.assets?.[assetId]?.operationId;
+        const committed = options.tombstone
+          && authoritativeEntry?.deleted === true
+          && authoritativeEntry.operationId === expectedOperationId;
+        if (!authoritativeManifest || !committed) throw saveError;
+        this.onManifest(authoritativeManifest);
+        this.onRecoveredCommit({ assetId, manifest: authoritativeManifest, entry: authoritativeEntry || null, deletion: true });
+        return { deleted: true, manifest: authoritativeManifest, previousPath: previous?.path, recoveredCommit: true };
+      }
+      this.onManifest(nextManifest);
+
+      // 매니페스트에서만 제거한다. 파일은 남겨 복사본의 참조를 지킨다.
+      return { deleted: true, manifest: nextManifest, previousPath: previous?.path };
+    }
+  }
+
+  return {
+    AssetRepository,
+    defaultContentHash,
+    manifestReferencesPath,
+    buildAssetRestorePlan,
+    restoreAssetStore
+  };
+});

package/config.js

@@ -0,0 +1,14 @@
+(function (globalScope, factory) {
+  const config = factory();
+  if (typeof module === "object" && module.exports) module.exports = config;
+  if (globalScope) globalScope.SOMI_CONFIG = config;
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  "use strict";
+
+  return Object.freeze({
+    supabaseUrl: "https://tlyioijsopxeegzfjlqe.supabase.co",
+    supabaseKey: "sb_publishable_AdEHgXPGJ2gKGVAjb7RYSg_YzUuT6jB",
+    assetBucket: "ssobig-writer-assets",
+    staffDomain: "ssobig.com"
+  });
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ssobig/writer-cli",
+  "version": "0.2.0",
+  "description": "Official agent CLI for SSOBIG WRITER",
+  "type": "commonjs",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neofrigate/writer-ssobig.git"
+  },
+  "homepage": "https://writer.ssobig.com/",
+  "bugs": {
+    "url": "https://github.com/neofrigate/writer-ssobig/issues"
+  },
+  "bin": {
+    "ssobig-writer": "tools/writer-cli/bin/ssobig-writer.cjs",
+    "ssobig-writer-daemon": "tools/writer-cli/bin/ssobig-writer-daemon.cjs"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "2.110.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project-runtime.js

@@ -0,0 +1,102 @@
+(function (globalScope, factory) {
+  const runtime = factory();
+  if (typeof module === "object" && module.exports) module.exports = runtime;
+  if (globalScope) globalScope.SomiProjectRuntime = runtime;
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  "use strict";
+
+  const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+  const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  const PROJECT_STORAGE_NAMESPACE_PATTERN = /^project-[0-9a-f]{32}-$/;
+
+  const ENGINES = Object.freeze({
+    "mystery-v1": Object.freeze({
+      id: "mystery-v1",
+      frameTarget: "./templates/mystery-v1.html",
+      passesSlug: true
+    })
+  });
+
+
+  function normalizeSlug(value) {
+    return String(value || "").trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  }
+
+  function projectStorageNamespace(projectId) {
+    const compactId = String(projectId || "").trim().toLowerCase().replace(/-/g, "");
+    if (!/^[0-9a-f]{32}$/.test(compactId)) throw new Error("유효한 작품 UUID가 필요합니다.");
+    return `project-${compactId}-`;
+  }
+
+  function projectRecordError(message, field = "") {
+    const error = new Error(message);
+    error.code = "SOMI_INVALID_PROJECT_RECORD";
+    error.field = field;
+    return error;
+  }
+
+  function resolveStrictProject(project = {}) {
+    const id = String(project.id || "").trim().toLowerCase();
+    const rawSlug = String(project.slug || "").trim();
+    const slug = normalizeSlug(rawSlug);
+    const engine = String(project.engine_key || project.engineKey || "").trim();
+    const rawStorageNamespace = String(project.storage_namespace || project.storageNamespace || "").trim();
+    const storageNamespace = rawStorageNamespace.toLowerCase();
+
+    if (!UUID_PATTERN.test(id)) throw projectRecordError("신규 작품 레코드에 유효한 id UUID가 필요합니다.", "id");
+    if (!SLUG_PATTERN.test(rawSlug) || rawSlug !== slug) throw projectRecordError("작품 slug 형식이 올바르지 않습니다.", "slug");
+    if (engine !== "mystery-v1") throw projectRecordError(`지원하지 않는 Component Writer engine입니다: ${engine || "(빈 값)"}`, "engine_key");
+    if (rawStorageNamespace !== storageNamespace || !PROJECT_STORAGE_NAMESPACE_PATTERN.test(storageNamespace)) {
+      throw projectRecordError("신규 작품의 storage_namespace는 UUID 기반 형식이어야 합니다.", "storage_namespace");
+    }
+    if (storageNamespace !== projectStorageNamespace(id)) {
+      throw projectRecordError("작품 id와 storage_namespace가 일치하지 않습니다.", "storage_namespace");
+    }
+
+    const engineDefinition = ENGINES[engine];
+    return Object.freeze({
+      slug,
+      storageNamespace,
+      engine,
+      route: `/${slug}`,
+      frameTarget: engineDefinition.frameTarget,
+      passesSlug: engineDefinition.passesSlug
+    });
+  }
+
+  function parseProjectRecord(project = {}, options = {}) {
+    if (!project || typeof project !== "object" || Array.isArray(project)) {
+      throw projectRecordError("작품 레코드는 객체여야 합니다.");
+    }
+    const mode = String(options.mode || "strict");
+    if (!["auto", "strict"].includes(mode)) throw projectRecordError("작품 해석은 strict mode만 지원합니다.");
+    return resolveStrictProject(project);
+  }
+
+  function resolveProject(project = {}) {
+    return parseProjectRecord(project, { mode: "strict" });
+  }
+
+  function browserRoute(runtime = {}, locationLike = {}) {
+    const route = String(runtime.route || "");
+    const slug = String(runtime.slug || "");
+    const hostname = String(locationLike.hostname || "").trim().toLowerCase();
+    const isLoopback = ["127.0.0.1", "localhost", "::1", "[::1]"].includes(hostname);
+    if (isLoopback && SLUG_PATTERN.test(slug)) {
+      return `/workbench.html?slug=${encodeURIComponent(slug)}`;
+    }
+    return route;
+  }
+
+  return Object.freeze({
+    ENGINES,
+    SLUG_PATTERN,
+    UUID_PATTERN,
+    PROJECT_STORAGE_NAMESPACE_PATTERN,
+    normalizeSlug,
+    projectStorageNamespace,
+    parseProjectRecord,
+    resolveProject,
+    browserRoute
+  });
+});

package/storage-path.js

@@ -0,0 +1,110 @@
+(function (globalScope, factory) {
+  const storagePath = factory();
+  if (typeof module === "object" && module.exports) module.exports = storagePath;
+  if (globalScope) globalScope.SomiStoragePath = storagePath;
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  "use strict";
+
+  function safePathSegment(value, fallback = "asset") {
+    const normalized = String(value || "")
+      .normalize("NFKD")
+      .toLowerCase()
+      .replace(/[^a-z0-9.@_-]+/g, "-")
+      .replace(/-{2,}/g, "-")
+      .replace(/^[.-]+|[.-]+$/g, "");
+    const safeFallback = String(fallback || "asset").replace(/[^a-zA-Z0-9@_-]+/g, "-") || "asset";
+    return normalized && normalized !== "." && normalized !== ".." ? normalized : safeFallback;
+  }
+
+  function safeFileName(value, fallback = "asset.bin") {
+    const candidate = String(value || "").split(/[\\/]/).pop() || "";
+    const dotIndex = candidate.lastIndexOf(".");
+    const hasExtension = dotIndex > 0 && dotIndex < candidate.length - 1;
+    const stem = safePathSegment(hasExtension ? candidate.slice(0, dotIndex) : candidate, "asset");
+    const extension = hasExtension ? safePathSegment(candidate.slice(dotIndex + 1), "") : "";
+    const result = extension ? `${stem}.${extension}` : stem;
+    return result || safePathSegment(fallback, "asset.bin");
+  }
+
+  function assertStorageObjectPath(path) {
+    const candidate = String(path || "").trim().replace(/^\/+|\/+$/g, "");
+    if (!candidate) throw new Error("Storage 경로가 비어 있습니다.");
+    const segments = candidate.split("/");
+    if (segments.some(segment => !segment || segment === "." || segment === ".." || /[\\\u0000-\u001f]/.test(segment))) {
+      throw new Error("Storage 경로에 안전하지 않은 segment가 있습니다.");
+    }
+    return segments.join("/");
+  }
+
+  function joinStoragePath(...segments) {
+    return assertStorageObjectPath(segments.map(segment => String(segment || "").replace(/^\/+|\/+$/g, "")).join("/"));
+  }
+
+  function encodedStoragePath(path) {
+    return assertStorageObjectPath(path).split("/").map(segment => encodeURIComponent(segment)).join("/");
+  }
+
+  function publicObjectMarker(bucketName) {
+    return `/storage/v1/object/public/${encodeURIComponent(String(bucketName || ""))}/`;
+  }
+
+  function assetSource(value, bucketName) {
+    let rawCandidate = value;
+    if (value && typeof value === "object") {
+      rawCandidate = [value.path, value.publicUrl, value.url]
+        .find(candidate => typeof candidate === "string" && candidate.trim()) || "";
+    }
+    if (typeof rawCandidate !== "string") return null;
+    const candidate = rawCandidate.trim();
+    if (!candidate) return null;
+    if (!/^https?:\/\//i.test(candidate)) {
+      try {
+        const path = assertStorageObjectPath(candidate);
+        return Object.freeze({ key: `path:${path}`, path, url: "", original: candidate });
+      } catch (error) {
+        return null;
+      }
+    }
+    try {
+      const url = new URL(candidate);
+      const marker = publicObjectMarker(bucketName);
+      if (url.pathname.startsWith(marker)) {
+        const path = assertStorageObjectPath(decodeURIComponent(url.pathname.slice(marker.length)));
+        return Object.freeze({ key: `path:${path}`, path, url: "", original: candidate });
+      }
+    } catch (error) {
+      return null;
+    }
+    return Object.freeze({ key: `url:${candidate}`, path: "", url: candidate, original: candidate });
+  }
+
+  function copiedAssetPath(source, sourceRoot, targetRoot, assetId, metadata = {}) {
+    const safeSourceRoot = assertStorageObjectPath(sourceRoot);
+    const safeTargetRoot = assertStorageObjectPath(targetRoot);
+    const sourcePath = String(source?.path || "");
+    if (sourcePath.startsWith(`${safeSourceRoot}/`)) {
+      return joinStoragePath(safeTargetRoot, sourcePath.slice(safeSourceRoot.length + 1));
+    }
+    const pathname = sourcePath || (() => {
+      try { return decodeURIComponent(new URL(source?.url || "").pathname); }
+      catch (error) { return ""; }
+    })();
+    const folderMatch = pathname.match(/\/(image|json)\/(.+)$/i);
+    if (folderMatch) return joinStoragePath(safeTargetRoot, folderMatch[1].toLowerCase(), assertStorageObjectPath(folderMatch[2]));
+    const rawFileName = pathname.split("/").pop() || String(metadata.name || `${safePathSegment(assetId)}.bin`);
+    const fileName = safeFileName(rawFileName, `${safePathSegment(assetId)}.bin`);
+    const isJson = metadata.type === "application/json" || /\.json$/i.test(fileName);
+    return joinStoragePath(safeTargetRoot, isJson ? "json" : "image", `${safePathSegment(assetId)}-${fileName}`);
+  }
+
+  return Object.freeze({
+    safePathSegment,
+    safeFileName,
+    assertStorageObjectPath,
+    joinStoragePath,
+    encodedStoragePath,
+    publicObjectMarker,
+    assetSource,
+    copiedAssetPath
+  });
+});

package/templates/mystery-v1/authoring-view-preference.js

@@ -0,0 +1,34 @@
+(function (root, factory) {
+  const api = factory(root);
+  if (typeof module === "object" && module.exports) module.exports = api;
+  if (root) root.WriterWorkbenchAuthoringViewPreference = api;
+})(typeof globalThis !== "undefined" ? globalThis : this, function (root) {
+  "use strict";
+
+  const STORAGE_KEY = "somi-workbench-authoring-view";
+  const DEFAULT_VIEW = "preview";
+  const VIEWS = Object.freeze(["input", "preview"]);
+
+  function normalize(value) {
+    return VIEWS.includes(value) ? value : DEFAULT_VIEW;
+  }
+
+  function deviceStorage() {
+    try { return root?.localStorage || null; }
+    catch (_) { return null; }
+  }
+
+  function read(storage = deviceStorage()) {
+    try { return normalize(storage?.getItem(STORAGE_KEY)); }
+    catch (_) { return DEFAULT_VIEW; }
+  }
+
+  function write(view, storage = deviceStorage()) {
+    const normalized = normalize(view);
+    try { storage?.setItem(STORAGE_KEY, normalized); }
+    catch (_) { /* 기기 저장소를 사용할 수 없어도 현재 화면 전환은 유지한다. */ }
+    return normalized;
+  }
+
+  return Object.freeze({ STORAGE_KEY, DEFAULT_VIEW, VIEWS, normalize, read, write });
+});

package/templates/mystery-v1/character-perspective-preview.js

@@ -0,0 +1,61 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === "object" && module.exports) module.exports = api;
+  if (root) root.WriterWorkbenchCharacterPerspectivePreview = api;
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  "use strict";
+
+  const CARD_ORDER = Object.freeze([
+    Object.freeze({ key: "progress", label: "진행", templateId: "ssobig.progress" }),
+    Object.freeze({ key: "common", label: "공통정보", templateId: "ssobig.common" }),
+    Object.freeze({ key: "character", label: "캐릭터", templateId: "ssobig.character" })
+  ]);
+
+  function characters(instance, data) {
+    const records = data?.characters && typeof data.characters === "object" ? data.characters : {};
+    const names = data?.names && typeof data.names === "object" ? data.names : {};
+    const deleted = new Set(Array.isArray(data?.deletedColumns) ? data.deletedColumns : []);
+    const order = Array.isArray(data?.order) ? data.order : Object.keys(records);
+    return order
+      .filter(id => !deleted.has(id) && Object.hasOwn(records, id) && records[id]?.isPlayable === true)
+      .map(id => Object.freeze({ id, name: String(names[id] || id), value: records[id] }));
+  }
+
+  function selectCharacter(instance, data, requestedId) {
+    const entries = characters(instance, data);
+    return entries.find(entry => entry.id === requestedId) || entries[0] || null;
+  }
+
+  function characterData(data, characterId) {
+    const source = data && typeof data === "object" ? data : {};
+    const value = source.characters?.[characterId];
+    if (!value) return null;
+    return {
+      ...source,
+      characters: { [characterId]: value },
+      names: { [characterId]: source.names?.[characterId] || characterId },
+      order: [characterId],
+      deletedColumns: []
+    };
+  }
+
+  function build(components, dataFor, requestedCharacterId) {
+    const active = Array.isArray(components) ? components : [];
+    const byTemplate = new Map(active.map(instance => [instance.templateId, instance]));
+    const characterInstance = byTemplate.get("ssobig.character") || null;
+    const sourceCharacterData = characterInstance ? dataFor(characterInstance) : null;
+    const availableCharacters = characters(characterInstance, sourceCharacterData);
+    const selectedCharacter = selectCharacter(characterInstance, sourceCharacterData, requestedCharacterId);
+    const cards = CARD_ORDER.flatMap(definition => {
+      const instance = byTemplate.get(definition.templateId);
+      if (!instance) return [];
+      const data = definition.key === "character"
+        ? characterData(sourceCharacterData, selectedCharacter?.id)
+        : dataFor(instance);
+      return data ? [{ ...definition, instance, data }] : [];
+    });
+    return Object.freeze({ characters: availableCharacters, selectedCharacter, cards });
+  }
+
+  return Object.freeze({ CARD_ORDER, characters, selectCharacter, characterData, build });
+});