@ssobig/writer-cli 0.2.0

package/tools/writer-cli/src/skill-manager.cjs

@@ -0,0 +1,255 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const packageManifest = require("../package.json");
+const { cliError } = require("./errors.cjs");
+
+const SKILL_NAME = "ssobig-writer-cli";
+const SKILL_VERSION = "0.2.0";
+const MANIFEST_NAME = ".ssobig-writer-skill-manifest.json";
+const PAYLOAD_ROOT = path.resolve(__dirname, "../skills", SKILL_NAME);
+const PLATFORM_PATHS = Object.freeze({ codex: [".agents", "skills"], claude: [".claude", "skills"] });
+
+function sha256Buffer(value) { return crypto.createHash("sha256").update(value).digest("hex"); }
+
+function safeRelative(value) {
+  const normalized = String(value || "").replace(/\\/g, "/").split(path.sep).join("/");
+  if (!normalized || normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized) || normalized.includes("\0") || normalized.split("/").some(part => !part || part === "." || part === "..")) {
+    throw cliError("E_SKILL_PATH", `안전하지 않은 skill 상대 경로입니다: ${normalized || "(empty)"}`);
+  }
+  return normalized;
+}
+
+function walkRegularFiles(root, fsApi = fs, directory = root) {
+  const entries = fsApi.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name, "en"));
+  const files = [];
+  for (const entry of entries) {
+    const absolute = path.join(directory, entry.name);
+    const stat = fsApi.lstatSync(absolute);
+    if (stat.isSymbolicLink()) throw cliError("E_SKILL_PATH", `skill payload에는 symbolic link를 포함할 수 없습니다: ${absolute}`);
+    if (stat.isDirectory()) files.push(...walkRegularFiles(root, fsApi, absolute));
+    else if (stat.isFile()) files.push(safeRelative(path.relative(root, absolute)));
+    else throw cliError("E_SKILL_PATH", `skill payload에는 일반 파일만 포함할 수 있습니다: ${absolute}`);
+  }
+  return files;
+}
+
+function payload(fsApi = fs, payloadRoot = PAYLOAD_ROOT) {
+  const root = path.resolve(payloadRoot);
+  const files = walkRegularFiles(root, fsApi).map(relativePath => {
+    const content = fsApi.readFileSync(path.join(root, relativePath));
+    return Object.freeze({ path: relativePath, content, sha256: sha256Buffer(content) });
+  });
+  return Object.freeze({ root, files: Object.freeze(files) });
+}
+
+function selectedPlatforms(options = {}) {
+  if (options.codex === true && options.claude === true) throw cliError("E_USAGE", "--codex와 --claude는 함께 지정할 수 없습니다. 둘 다 설치하려면 platform option을 생략하세요.");
+  if (options.codex === true) return ["codex"];
+  if (options.claude === true) return ["claude"];
+  return ["codex", "claude"];
+}
+
+function assertWorkspace(target, fsApi = fs) {
+  const workspace = path.resolve(String(target || ""));
+  if (!target) throw cliError("E_USAGE", "--target workspace 경로가 필요합니다.");
+  let stat;
+  try { stat = fsApi.lstatSync(workspace); }
+  catch (error) { throw cliError("E_SKILL_PATH", `skill target workspace를 찾을 수 없습니다: ${workspace}`, null, error); }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw cliError("E_SKILL_PATH", `skill target은 symbolic link가 아닌 directory여야 합니다: ${workspace}`);
+  return workspace;
+}
+
+function destination(workspace, platform) {
+  const root = path.resolve(workspace);
+  const resolved = path.resolve(root, ...PLATFORM_PATHS[platform], SKILL_NAME);
+  if (resolved === root || !resolved.startsWith(`${root}${path.sep}`)) throw cliError("E_SKILL_PATH", "skill destination이 target workspace를 벗어났습니다.");
+  return resolved;
+}
+
+function assertExistingParentsSafe(workspace, targetPath, fsApi = fs) {
+  let current = path.resolve(workspace);
+  const relative = path.relative(current, targetPath);
+  for (const segment of relative.split(path.sep).slice(0, -1)) {
+    current = path.join(current, segment);
+    try {
+      const stat = fsApi.lstatSync(current);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw cliError("E_SKILL_PATH", `skill 경로에 안전하지 않은 parent가 있습니다: ${current}`);
+    } catch (error) { if (error.code === "ENOENT") break; throw error; }
+  }
+}
+
+function readManifest(skillDirectory, fsApi = fs) {
+  const manifestPath = path.join(skillDirectory, MANIFEST_NAME);
+  let stat;
+  try { stat = fsApi.lstatSync(manifestPath); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (stat.isSymbolicLink() || !stat.isFile()) throw cliError("E_SKILL_CONFLICT", `관리 manifest가 일반 파일이 아닙니다: ${manifestPath}`);
+  let parsed;
+  try { parsed = JSON.parse(fsApi.readFileSync(manifestPath, "utf8")); }
+  catch (error) { throw cliError("E_SKILL_CONFLICT", `관리 manifest가 손상되었습니다: ${manifestPath}`, null, error); }
+  if (parsed?.manifestVersion !== 1 || parsed?.skillName !== SKILL_NAME || !Array.isArray(parsed.files)) {
+    throw cliError("E_SKILL_CONFLICT", `관리 manifest 형식이 올바르지 않습니다: ${manifestPath}`);
+  }
+  return parsed;
+}
+
+function inspectManaged(skillDirectory, fsApi = fs) {
+  let stat;
+  try { stat = fsApi.lstatSync(skillDirectory); }
+  catch (error) { if (error.code === "ENOENT") return Object.freeze({ state: "missing", manifest: null }); throw error; }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw cliError("E_SKILL_CONFLICT", `skill destination이 안전한 directory가 아닙니다: ${skillDirectory}`);
+  const manifest = readManifest(skillDirectory, fsApi);
+  if (!manifest) throw cliError("E_SKILL_CONFLICT", `기존 skill directory는 Writer CLI가 관리하지 않습니다: ${skillDirectory}`);
+  const declared = new Map();
+  for (const item of manifest.files) {
+    const relativePath = safeRelative(item?.path);
+    if (!/^[a-f0-9]{64}$/.test(String(item?.sha256 || "")) || declared.has(relativePath)) throw cliError("E_SKILL_CONFLICT", `관리 manifest file 목록이 올바르지 않습니다: ${skillDirectory}`);
+    declared.set(relativePath, String(item.sha256));
+  }
+  const actual = walkRegularFiles(skillDirectory, fsApi).filter(relativePath => relativePath !== MANIFEST_NAME);
+  const extra = actual.find(relativePath => !declared.has(relativePath));
+  if (extra) throw cliError("E_SKILL_CONFLICT", `관리되지 않는 skill 파일을 보존하기 위해 중단했습니다: ${path.join(skillDirectory, extra)}`);
+  for (const [relativePath, expected] of declared) {
+    const filePath = path.resolve(skillDirectory, relativePath);
+    if (!filePath.startsWith(`${path.resolve(skillDirectory)}${path.sep}`)) throw cliError("E_SKILL_PATH", "관리 manifest 경로가 skill directory를 벗어났습니다.");
+    let fileStat;
+    try { fileStat = fsApi.lstatSync(filePath); }
+    catch (error) { throw cliError("E_SKILL_CONFLICT", `관리 skill 파일이 누락되었습니다: ${filePath}`, null, error); }
+    if (fileStat.isSymbolicLink() || !fileStat.isFile() || sha256Buffer(fsApi.readFileSync(filePath)) !== expected) {
+      throw cliError("E_SKILL_CONFLICT", `사용자가 수정한 관리 skill 파일을 덮어쓰지 않습니다: ${filePath}`);
+    }
+  }
+  return Object.freeze({ state: "managed", manifest });
+}
+
+function desiredManifest(payloadValue) {
+  return Object.freeze({
+    manifestVersion: 1,
+    skillName: SKILL_NAME,
+    skillVersion: SKILL_VERSION,
+    cliVersion: packageManifest.version,
+    files: payloadValue.files.map(item => ({ path: item.path, sha256: item.sha256 }))
+  });
+}
+
+function sameDesired(manifest, desired) {
+  return JSON.stringify({ skillVersion: manifest.skillVersion, cliVersion: manifest.cliVersion, files: manifest.files })
+    === JSON.stringify({ skillVersion: desired.skillVersion, cliVersion: desired.cliVersion, files: desired.files });
+}
+
+function writeStage(stagePath, payloadValue, manifest, fsApi = fs) {
+  fsApi.mkdirSync(stagePath, { recursive: false, mode: 0o700 });
+  for (const item of payloadValue.files) {
+    const destinationPath = path.join(stagePath, item.path);
+    fsApi.mkdirSync(path.dirname(destinationPath), { recursive: true, mode: 0o700 });
+    fsApi.writeFileSync(destinationPath, item.content, { mode: 0o600, flag: "wx" });
+  }
+  fsApi.writeFileSync(path.join(stagePath, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+}
+
+function installOrUpdate(options = {}) {
+  const fsApi = options.fs || fs;
+  const workspace = assertWorkspace(options.target, fsApi);
+  const payloadValue = payload(fsApi, options.payloadRoot || PAYLOAD_ROOT);
+  const manifest = desiredManifest(payloadValue);
+  const targets = selectedPlatforms(options).map(platform => {
+    const skillDirectory = destination(workspace, platform);
+    assertExistingParentsSafe(workspace, skillDirectory, fsApi);
+    const current = inspectManaged(skillDirectory, fsApi);
+    return { platform, skillDirectory, current, action: current.state === "missing" ? "install" : (sameDesired(current.manifest, manifest) ? "unchanged" : "update") };
+  });
+  if (options.dryRun === true || targets.every(target => target.action === "unchanged")) {
+    return Object.freeze({ dryRun: options.dryRun === true, workspace, skillName: SKILL_NAME, skillVersion: SKILL_VERSION, targets: targets.map(({ platform, skillDirectory, action }) => ({ platform, path: skillDirectory, action })) });
+  }
+
+  const prepared = [];
+  const swapped = [];
+  try {
+    for (const target of targets.filter(item => item.action !== "unchanged")) {
+      const parent = path.dirname(target.skillDirectory);
+      fsApi.mkdirSync(parent, { recursive: true, mode: 0o700 });
+      assertExistingParentsSafe(workspace, target.skillDirectory, fsApi);
+      const stagePath = path.join(parent, `.${SKILL_NAME}.${process.pid}.${crypto.randomUUID()}.stage`);
+      writeStage(stagePath, payloadValue, manifest, fsApi);
+      prepared.push({ ...target, stagePath, backupPath: `${stagePath}.backup` });
+    }
+    for (const item of prepared) {
+      if (item.current.state === "managed") fsApi.renameSync(item.skillDirectory, item.backupPath);
+      try { fsApi.renameSync(item.stagePath, item.skillDirectory); }
+      catch (error) {
+        if (item.current.state === "managed") fsApi.renameSync(item.backupPath, item.skillDirectory);
+        throw error;
+      }
+      swapped.push(item);
+    }
+  } catch (error) {
+    for (const item of [...swapped].reverse()) {
+      try {
+        fsApi.rmSync(item.skillDirectory, { recursive: true, force: true });
+        if (item.current.state === "managed" && fsApi.existsSync(item.backupPath)) fsApi.renameSync(item.backupPath, item.skillDirectory);
+      } catch (rollbackError) { void rollbackError; }
+    }
+    for (const item of prepared) {
+      try { if (fsApi.existsSync(item.stagePath)) fsApi.rmSync(item.stagePath, { recursive: true, force: true }); } catch (cleanupError) { void cleanupError; }
+    }
+    throw cliError("E_SKILL_WRITE", "skill 설치를 atomic하게 반영하지 못했습니다. 기존 관리 파일은 보존했습니다.", null, error);
+  }
+  for (const item of swapped) {
+    if (item.current.state !== "managed") continue;
+    try { fsApi.rmSync(item.backupPath, { recursive: true, force: false }); }
+    catch (error) { void error; }
+  }
+  return Object.freeze({ dryRun: false, workspace, skillName: SKILL_NAME, skillVersion: SKILL_VERSION, targets: targets.map(({ platform, skillDirectory, action }) => ({ platform, path: skillDirectory, action })) });
+}
+
+function skillStatus(options = {}) {
+  const fsApi = options.fs || fs;
+  const workspace = assertWorkspace(options.target, fsApi);
+  const desired = desiredManifest(payload(fsApi, options.payloadRoot || PAYLOAD_ROOT));
+  const targets = Object.keys(PLATFORM_PATHS).map(platform => {
+    const skillDirectory = destination(workspace, platform);
+    assertExistingParentsSafe(workspace, skillDirectory, fsApi);
+    try {
+      const current = inspectManaged(skillDirectory, fsApi);
+      if (current.state === "missing") return { platform, path: skillDirectory, status: "missing" };
+      return { platform, path: skillDirectory, status: sameDesired(current.manifest, desired) ? "current" : "update-available", installedSkillVersion: current.manifest.skillVersion, installedCliVersion: current.manifest.cliVersion };
+    } catch (error) {
+      if (error.code === "E_SKILL_CONFLICT") return { platform, path: skillDirectory, status: "conflict", error: error.message };
+      throw error;
+    }
+  });
+  return Object.freeze({ workspace, skillName: SKILL_NAME, skillVersion: SKILL_VERSION, targets });
+}
+
+function removeManaged(options = {}) {
+  if (options.managedOnly !== true) throw cliError("E_USAGE", "skills remove에는 --managed-only가 필요합니다.");
+  const fsApi = options.fs || fs;
+  const workspace = assertWorkspace(options.target, fsApi);
+  const targets = selectedPlatforms(options).map(platform => {
+    const skillDirectory = destination(workspace, platform);
+    assertExistingParentsSafe(workspace, skillDirectory, fsApi);
+    const current = inspectManaged(skillDirectory, fsApi);
+    return { platform, skillDirectory, current, action: current.state === "missing" ? "unchanged" : "remove" };
+  });
+  if (options.dryRun !== true) {
+    for (const target of targets.filter(item => item.action === "remove")) {
+      for (const item of target.current.manifest.files) fsApi.unlinkSync(path.join(target.skillDirectory, safeRelative(item.path)));
+      fsApi.unlinkSync(path.join(target.skillDirectory, MANIFEST_NAME));
+      const directories = [];
+      const collect = directory => {
+        for (const entry of fsApi.readdirSync(directory, { withFileTypes: true })) if (entry.isDirectory() && !entry.isSymbolicLink()) collect(path.join(directory, entry.name));
+        directories.push(directory);
+      };
+      collect(target.skillDirectory);
+      for (const directory of directories) {
+        try { fsApi.rmdirSync(directory); } catch (error) { if (!error || !["ENOTEMPTY", "ENOENT"].includes(error.code)) throw error; }
+      }
+    }
+  }
+  return Object.freeze({ dryRun: options.dryRun === true, workspace, skillName: SKILL_NAME, targets: targets.map(({ platform, skillDirectory, action }) => ({ platform, path: skillDirectory, action })) });
+}
+
+module.exports = Object.freeze({ SKILL_NAME, SKILL_VERSION, MANIFEST_NAME, PAYLOAD_ROOT, PLATFORM_PATHS, safeRelative, payload, selectedPlatforms, destination, inspectManaged, installOrUpdate, skillStatus, removeManaged });

package/tools/writer-cli/src/source-fingerprint.cjs

@@ -0,0 +1,90 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const SOURCE_FINGERPRINT_VERSION = "ssobig-writer-source-v2";
+const REPOSITORY_ROOT = path.resolve(__dirname, "../../..");
+const REQUIRED_SHARED_FILES = Object.freeze([
+  "config.js",
+  "project-runtime.js",
+  "asset-repository.js",
+  "storage-path.js"
+]);
+
+function normalizedRelative(root, absolutePath) {
+  const relative = path.relative(root, absolutePath).split(path.sep).join("/");
+  if (!relative || relative.startsWith("../") || path.isAbsolute(relative)) {
+    throw new Error(`Writer source fingerprint 경로가 저장소 밖에 있습니다: ${absolutePath}`);
+  }
+  return relative;
+}
+
+function filesWithExtension(directory, extension, fsApi) {
+  let entries;
+  try { entries = fsApi.readdirSync(directory, { withFileTypes: true }); }
+  catch (error) { throw new Error(`Writer source fingerprint 디렉터리를 읽을 수 없습니다: ${directory}`, { cause: error }); }
+  return entries
+    .filter(entry => entry.isFile() && entry.name.endsWith(extension))
+    .map(entry => path.join(directory, entry.name));
+}
+
+function filesRecursive(directory, fsApi) {
+  return fsApi.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const absolute = path.join(directory, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`Writer source fingerprint에는 symbolic link를 포함할 수 없습니다: ${absolute}`);
+    if (entry.isDirectory()) return filesRecursive(absolute, fsApi);
+    if (entry.isFile()) return [absolute];
+    throw new Error(`Writer source fingerprint에는 일반 파일만 포함할 수 있습니다: ${absolute}`);
+  });
+}
+
+function runtimeSourceFiles(options = {}) {
+  const fsApi = options.fs || fs;
+  const repositoryRoot = path.resolve(options.repositoryRoot || REPOSITORY_ROOT);
+  const files = [
+    ...filesWithExtension(path.join(repositoryRoot, "tools/writer-cli/src"), ".cjs", fsApi),
+    ...filesWithExtension(path.join(repositoryRoot, "tools/writer-cli/bin"), ".cjs", fsApi),
+    ...filesRecursive(path.join(repositoryRoot, "tools/writer-cli/skills"), fsApi),
+    ...filesWithExtension(path.join(repositoryRoot, "templates/mystery-v1"), ".js", fsApi),
+    path.join(repositoryRoot, "tools/writer-cli/package.json"),
+    path.join(repositoryRoot, "tools/writer-cli/package-lock.json"),
+    ...REQUIRED_SHARED_FILES.map(fileName => path.join(repositoryRoot, fileName))
+  ];
+  const relativeFiles = files.map(filePath => normalizedRelative(repositoryRoot, filePath));
+  if (new Set(relativeFiles).size !== relativeFiles.length) throw new Error("Writer source fingerprint 대상이 중복되었습니다.");
+  return relativeFiles.sort();
+}
+
+function computeSourceFingerprint(options = {}) {
+  const fsApi = options.fs || fs;
+  const repositoryRoot = path.resolve(options.repositoryRoot || REPOSITORY_ROOT);
+  const files = options.files ? [...options.files].map(String).sort() : runtimeSourceFiles({ repositoryRoot, fs: fsApi });
+  const hash = crypto.createHash("sha256");
+  hash.update(`${SOURCE_FINGERPRINT_VERSION}\0`);
+  for (const relativePath of files) {
+    const absolutePath = path.resolve(repositoryRoot, relativePath);
+    if (normalizedRelative(repositoryRoot, absolutePath) !== relativePath.split(path.sep).join("/")) {
+      throw new Error(`Writer source fingerprint 상대 경로가 올바르지 않습니다: ${relativePath}`);
+    }
+    let content;
+    try { content = fsApi.readFileSync(absolutePath); }
+    catch (error) { throw new Error(`Writer source fingerprint 파일을 읽을 수 없습니다: ${relativePath}`, { cause: error }); }
+    hash.update(relativePath);
+    hash.update("\0");
+    hash.update(String(content.length));
+    hash.update("\0");
+    hash.update(content);
+    hash.update("\0");
+  }
+  return `${SOURCE_FINGERPRINT_VERSION}:sha256:${hash.digest("hex")}`;
+}
+
+module.exports = Object.freeze({
+  SOURCE_FINGERPRINT_VERSION,
+  REPOSITORY_ROOT,
+  REQUIRED_SHARED_FILES,
+  runtimeSourceFiles,
+  computeSourceFingerprint
+});

package/tools/writer-cli/src/update-gate.cjs

@@ -0,0 +1,102 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+const packageManifest = require("../package.json");
+const { resolveAgentPaths, ensurePrivateDirectory } = require("./agent-paths.cjs");
+const { compareSemver, fetchLatestVersion, parseSemver } = require("./diagnostics.cjs");
+const { cliError } = require("./errors.cjs");
+
+const CACHE_FILE = "cli-version-check.json";
+const CACHE_VERSION = 1;
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const INSTALL_COMMAND = "npm install --global @ssobig/writer-cli@latest";
+const DOWNLOAD_URL = "https://writer.ssobig.com/cli-download";
+
+function clock(options = {}) {
+  const value = typeof options.now === "function" ? options.now() : Date.now();
+  return value instanceof Date ? value.getTime() : Number(value);
+}
+
+function cacheLocation(options = {}) {
+  const cacheDir = resolveAgentPaths({
+    cacheDir: options.cacheDir,
+    platform: options.platform,
+    environment: options.environment,
+    homeDirectory: options.homeDirectory
+  }).cacheDir;
+  return Object.freeze({ cacheDir, filePath: path.join(cacheDir, CACHE_FILE) });
+}
+
+function readCache(filePath, fsApi = fs) {
+  try {
+    const stat = fsApi.lstatSync(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) return null;
+    const parsed = JSON.parse(fsApi.readFileSync(filePath, "utf8"));
+    const status = parsed?.status === "unavailable" ? "unavailable" : "current";
+    if (parsed?.cacheVersion !== CACHE_VERSION || !Number.isFinite(Number(parsed?.checkedAt))) return null;
+    if (status === "current" && !parseSemver(parsed?.latestVersion)) return null;
+    return Object.freeze({ cacheVersion: CACHE_VERSION, status, latestVersion: status === "current" ? String(parsed.latestVersion) : null, checkedAt: Number(parsed.checkedAt) });
+  } catch (error) { return null; }
+}
+
+function writeCache(location, value, options = {}) {
+  const fsApi = options.fs || fs;
+  ensurePrivateDirectory(location.cacheDir, fsApi, { platform: options.platform });
+  const temporary = path.join(location.cacheDir, `.${CACHE_FILE}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    fsApi.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: "wx" });
+    fsApi.renameSync(temporary, location.filePath);
+    if (String(options.platform || process.platform) !== "win32") fsApi.chmodSync(location.filePath, 0o600);
+  } finally {
+    try { fsApi.unlinkSync(temporary); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+}
+
+function updateRequired(currentVersion, latestVersion, source) {
+  throw cliError("E_CLI_UPDATE_REQUIRED", `Writer CLI ${currentVersion}은 최신 필수 버전 ${latestVersion}보다 낮아 서버 작업을 실행하지 않았습니다.`, {
+    currentVersion,
+    latestVersion,
+    installCommand: INSTALL_COMMAND,
+    downloadUrl: DOWNLOAD_URL,
+    source
+  });
+}
+
+async function checkRequiredUpdate(options = {}) {
+  const currentVersion = String(options.currentVersion || packageManifest.version);
+  if (!parseSemver(currentVersion)) throw cliError("E_CLI_VERSION", `현재 Writer CLI 버전이 올바르지 않습니다: ${currentVersion}`);
+  const fsApi = options.fs || fs;
+  const location = cacheLocation(options);
+  const now = clock(options);
+  const ttlMs = Math.max(0, Number(options.ttlMs ?? DEFAULT_TTL_MS));
+  const cached = readCache(location.filePath, fsApi);
+  if (cached && now - cached.checkedAt >= 0 && now - cached.checkedAt < ttlMs) {
+    if (cached.latestVersion && compareSemver(cached.latestVersion, currentVersion) > 0) updateRequired(currentVersion, cached.latestVersion, "cache");
+    if (cached.status === "unavailable") return Object.freeze({ status: "unavailable", currentVersion, latestVersion: null, source: "cache", warning: "npm registry에서 최신 Writer CLI 버전을 확인하지 못해 이번 작업은 차단하지 않습니다." });
+    return Object.freeze({ status: "current", currentVersion, latestVersion: cached.latestVersion, source: "cache", warning: null });
+  }
+  try {
+    const latestVersion = await (options.fetchLatest || fetchLatestVersion)({ fetch: options.fetch, timeoutMs: options.timeoutMs });
+    let cacheWriteFailed = false;
+    try { writeCache(location, { cacheVersion: CACHE_VERSION, status: "current", latestVersion, checkedAt: now }, { fs: fsApi, platform: options.platform }); }
+    catch (error) { cacheWriteFailed = true; }
+    if (compareSemver(latestVersion, currentVersion) > 0) updateRequired(currentVersion, latestVersion, "registry");
+    return Object.freeze({ status: "current", currentVersion, latestVersion, source: "registry", warning: cacheWriteFailed ? "최신 Writer CLI 버전 cache를 안전하게 기록하지 못했지만 registry 확인 결과는 최신입니다." : null });
+  } catch (error) {
+    if (error?.code === "E_CLI_UPDATE_REQUIRED") throw error;
+    if (cached?.latestVersion && compareSemver(cached.latestVersion, currentVersion) > 0) updateRequired(currentVersion, cached.latestVersion, "stale-cache");
+    try { writeCache(location, { cacheVersion: CACHE_VERSION, status: "unavailable", latestVersion: null, checkedAt: now }, { fs: fsApi, platform: options.platform }); }
+    catch (cacheError) { void cacheError; }
+    return Object.freeze({
+      status: "unavailable",
+      currentVersion,
+      latestVersion: cached?.latestVersion || null,
+      source: cached ? "stale-cache" : "registry",
+      warning: "npm registry에서 최신 Writer CLI 버전을 확인하지 못해 이번 작업은 차단하지 않습니다."
+    });
+  }
+}
+
+module.exports = Object.freeze({ CACHE_FILE, CACHE_VERSION, DEFAULT_TTL_MS, INSTALL_COMMAND, DOWNLOAD_URL, cacheLocation, readCache, writeCache, checkRequiredUpdate });