@ssobig/writer-cli 0.2.0

package/tools/writer-cli/src/daemon-server.cjs

@@ -0,0 +1,378 @@
+"use strict";
+
+const fs = require("node:fs");
+const net = require("node:net");
+const os = require("node:os");
+const path = require("node:path");
+const { cliError } = require("./errors.cjs");
+const {
+  PROTOCOL,
+  DEFAULT_MAX_REQUEST_BYTES,
+  DEFAULT_MAX_RESPONSE_BYTES,
+  DEFAULT_REQUEST_TIMEOUT_MS,
+  byteLimit,
+  timeoutLimit,
+  requestTimeoutError,
+  validateRequest,
+  successResponse,
+  errorResponse,
+  encodeFrame,
+  parseFrame
+} = require("./daemon-protocol.cjs");
+
+const DEFAULT_CACHE_DIRECTORY = path.join("Library", "Caches", "com.ssobig.writer-agent", "v1");
+const DEFAULT_SOCKET_NAME = "daemon.sock";
+const MAX_SOCKET_PATH_BYTES = 100;
+
+function rejectTcpOptions(options) {
+  if (Object.hasOwn(options, "host") || Object.hasOwn(options, "port")) {
+    throw cliError("E_DAEMON_TCP_FORBIDDEN", "Writer daemon은 Unix domain socket만 사용할 수 있습니다.");
+  }
+}
+
+function resolveDaemonPaths(options = {}) {
+  rejectTcpOptions(options);
+  const homeDirectory = path.resolve(String(options.homeDirectory || os.homedir()));
+  const requestedSocketPath = options.socketPath ? path.resolve(String(options.socketPath)) : null;
+  const cacheDir = path.resolve(String(options.cacheDir || (requestedSocketPath ? path.dirname(requestedSocketPath) : path.join(homeDirectory, DEFAULT_CACHE_DIRECTORY))));
+  const socketName = String(options.socketName || DEFAULT_SOCKET_NAME);
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(socketName)) throw cliError("E_DAEMON_CONFIG", "daemon socket 이름이 올바르지 않습니다.");
+  const socketPath = requestedSocketPath || path.join(cacheDir, socketName);
+  if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(path.basename(socketPath))) throw cliError("E_DAEMON_CONFIG", "daemon socket 경로의 파일 이름이 올바르지 않습니다.");
+  if (path.dirname(socketPath) !== cacheDir) throw cliError("E_DAEMON_CONFIG", "daemon socket은 전용 cache directory 바로 아래에 있어야 합니다.");
+  if (Buffer.byteLength(socketPath, "utf8") > MAX_SOCKET_PATH_BYTES) {
+    throw cliError("E_DAEMON_CONFIG", `daemon socket 경로가 너무 깁니다: ${Buffer.byteLength(socketPath, "utf8")} bytes`);
+  }
+  return Object.freeze({ cacheDir, socketPath });
+}
+
+function prepareCacheDirectory(cacheDir, options = {}) {
+  const fsApi = options.fs || fs;
+  try { fsApi.mkdirSync(cacheDir, { recursive: true, mode: 0o700 }); }
+  catch (error) { throw cliError("E_DAEMON_CACHE", "Writer daemon cache directory를 만들 수 없습니다.", null, error); }
+  let stat;
+  try { stat = fsApi.lstatSync(cacheDir); }
+  catch (error) { throw cliError("E_DAEMON_CACHE", "Writer daemon cache directory를 확인할 수 없습니다.", null, error); }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw cliError("E_DAEMON_CACHE_UNSAFE", "Writer daemon cache 경로는 symlink가 아닌 directory여야 합니다.");
+  const uid = typeof options.uid === "number" ? options.uid : process.getuid?.();
+  if (Number.isInteger(uid) && Number.isInteger(stat.uid) && stat.uid !== uid) {
+    throw cliError("E_DAEMON_CACHE_UNSAFE", "Writer daemon cache directory의 소유자가 현재 사용자와 다릅니다.");
+  }
+  try { fsApi.chmodSync(cacheDir, 0o700); }
+  catch (error) { throw cliError("E_DAEMON_CACHE_UNSAFE", "Writer daemon cache directory 권한을 0700으로 제한할 수 없습니다.", null, error); }
+  const verified = fsApi.lstatSync(cacheDir);
+  if ((verified.mode & 0o777) !== 0o700) throw cliError("E_DAEMON_CACHE_UNSAFE", "Writer daemon cache directory 권한은 0700이어야 합니다.");
+  return verified;
+}
+
+function verifyDaemonEndpoint(paths, options = {}) {
+  const fsApi = options.fs || fs;
+  const uid = typeof options.uid === "number" ? options.uid : process.getuid?.();
+  let directory;
+  let socket;
+  try {
+    directory = fsApi.lstatSync(paths.cacheDir);
+    socket = fsApi.lstatSync(paths.socketPath);
+  } catch (error) {
+    if (error.code === "ENOENT") throw cliError("E_DAEMON_UNAVAILABLE", "Writer daemon socket이 없습니다.", null, error);
+    throw cliError("E_DAEMON_SOCKET", "Writer daemon socket을 확인할 수 없습니다.", null, error);
+  }
+  if (directory.isSymbolicLink() || !directory.isDirectory() || (directory.mode & 0o777) !== 0o700) {
+    throw cliError("E_DAEMON_CACHE_UNSAFE", "Writer daemon cache directory가 안전한 0700 directory가 아닙니다.");
+  }
+  if (socket.isSymbolicLink() || !socket.isSocket() || (socket.mode & 0o777) !== 0o600) {
+    throw cliError("E_DAEMON_SOCKET_UNSAFE", "Writer daemon endpoint가 안전한 0600 Unix socket이 아닙니다.");
+  }
+  if (Number.isInteger(uid) && ((Number.isInteger(directory.uid) && directory.uid !== uid) || (Number.isInteger(socket.uid) && socket.uid !== uid))) {
+    throw cliError("E_DAEMON_SOCKET_UNSAFE", "Writer daemon endpoint의 소유자가 현재 사용자와 다릅니다.");
+  }
+  return Object.freeze({ directory, socket });
+}
+
+function probeSocket(socketPath, options = {}) {
+  const netApi = options.net || net;
+  const timeoutMs = Number(options.timeoutMs || 500);
+  return new Promise(resolve => {
+    let settled = false;
+    const socket = netApi.createConnection({ path: socketPath });
+    function finish(result) {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    }
+    socket.once("connect", () => finish({ status: "active" }));
+    socket.once("error", error => {
+      if (error.code === "ENOENT") finish({ status: "missing" });
+      else if (error.code === "ECONNREFUSED") finish({ status: "stale" });
+      else finish({ status: "unknown", code: error.code || "" });
+    });
+    socket.setTimeout(timeoutMs, () => finish({ status: "unknown", code: "ETIMEDOUT" }));
+  });
+}
+
+function sameFile(left, right) {
+  return left && right && left.dev === right.dev && left.ino === right.ino;
+}
+
+async function prepareSocketPath(socketPath, options = {}) {
+  const fsApi = options.fs || fs;
+  let initial;
+  try { initial = fsApi.lstatSync(socketPath); }
+  catch (error) {
+    if (error.code === "ENOENT") return;
+    throw cliError("E_DAEMON_SOCKET", "기존 Writer daemon socket을 확인할 수 없습니다.", null, error);
+  }
+  if (initial.isSymbolicLink() || !initial.isSocket()) {
+    throw cliError("E_DAEMON_SOCKET_UNSAFE", "기존 daemon socket 경로가 symlink 또는 socket이 아닌 파일입니다. 자동 삭제하지 않습니다.");
+  }
+  const probe = await (options.probe || probeSocket)(socketPath, options);
+  if (probe.status === "active") throw cliError("E_DAEMON_ALREADY_RUNNING", "Writer daemon이 이미 실행 중입니다.");
+  if (probe.status !== "stale") {
+    throw cliError("E_DAEMON_SOCKET_BUSY", "기존 daemon socket의 안전한 stale 여부를 확인할 수 없어 삭제하지 않습니다.");
+  }
+  let current;
+  try { current = fsApi.lstatSync(socketPath); }
+  catch (error) {
+    if (error.code === "ENOENT") return;
+    throw cliError("E_DAEMON_SOCKET", "기존 Writer daemon socket을 다시 확인할 수 없습니다.", null, error);
+  }
+  if (!sameFile(initial, current) || current.isSymbolicLink() || !current.isSocket()) {
+    throw cliError("E_DAEMON_SOCKET_BUSY", "확인 중 daemon socket이 교체되어 자동 삭제하지 않습니다.");
+  }
+  try { fsApi.unlinkSync(socketPath); }
+  catch (error) { if (error.code !== "ENOENT") throw cliError("E_DAEMON_SOCKET", "stale daemon socket을 제거할 수 없습니다.", null, error); }
+}
+
+function createDaemonServer(options = {}) {
+  rejectTcpOptions(options);
+  if (typeof options.handler !== "function") throw cliError("E_DAEMON_CONFIG", "Writer daemon request handler가 필요합니다.");
+  const fsApi = options.fs || fs;
+  const netApi = options.net || net;
+  const paths = resolveDaemonPaths(options);
+  const maxRequestBytes = byteLimit(options.maxRequestBytes, DEFAULT_MAX_REQUEST_BYTES, "maxRequestBytes");
+  const maxResponseBytes = byteLimit(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, "maxResponseBytes");
+  const requestTimeoutMs = timeoutLimit(options.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+  const closeTimeoutMs = timeoutLimit(options.closeTimeoutMs, 5_000);
+  const connections = new Set();
+  let server = null;
+  let state = "idle";
+  let socketIdentity = null;
+  const serialLanes = new Map();
+  let closePromise = null;
+
+  function writeResponse(socket, response) {
+    let frame;
+    try { frame = encodeFrame(response, maxResponseBytes, "response"); }
+    catch (error) {
+      const fallback = errorResponse(response?.id || null, error);
+      try { frame = encodeFrame(fallback, maxResponseBytes, "response"); }
+      catch (fallbackError) {
+        socket.destroy();
+        return false;
+      }
+    }
+    if (!socket.destroyed && socket.writable) socket.write(frame);
+    return true;
+  }
+
+  function protocolFailure(socket, error, id = null, close = false) {
+    writeResponse(socket, errorResponse(id, error));
+    if (close) socket.end();
+  }
+
+  function queueRequest(socket, connection, request) {
+    connection.pending += 1;
+    const deadlineAt = Date.now() + Math.min(requestTimeoutMs, request.timeoutMs);
+    const lane = String(typeof options.requestLane === "function" ? options.requestLane(request) : "default");
+    const previous = (serialLanes.get(lane) || Promise.resolve()).catch(() => {});
+    let completeWork;
+    const handlerWork = previous.then(async () => {
+      const controller = new AbortController();
+      let shutdownAfterResponse = false;
+      let timeout;
+      const configuredTimeout = deadlineAt - Date.now();
+      if (configuredTimeout <= 0) {
+        writeResponse(socket, errorResponse(request.id, requestTimeoutError(request.id)));
+        connection.pending -= 1;
+        if ((state === "closing" || connection.closeAfterPending) && connection.pending === 0) socket.end();
+        return;
+      }
+      const handlerPromise = Promise.resolve().then(() => options.handler(request, Object.freeze({
+        signal: controller.signal,
+        protocol: PROTOCOL,
+        socketPath: paths.socketPath,
+        requestShutdown() { shutdownAfterResponse = true; }
+      })));
+      handlerPromise.catch(() => {});
+      const timeoutPromise = new Promise((resolve, reject) => {
+        timeout = setTimeout(() => {
+          controller.abort();
+          reject(requestTimeoutError(request.id));
+        }, configuredTimeout);
+        timeout.unref?.();
+      });
+      try {
+        const result = await Promise.race([handlerPromise, timeoutPromise]);
+        clearTimeout(timeout);
+        writeResponse(socket, successResponse(request.id, result));
+      } catch (error) {
+        clearTimeout(timeout);
+        writeResponse(socket, errorResponse(request.id, error));
+      } finally {
+        completeWork = handlerPromise.catch(() => {});
+        await completeWork;
+        connection.pending -= 1;
+        if ((state === "closing" || connection.closeAfterPending) && connection.pending === 0) socket.end();
+        if (shutdownAfterResponse && state === "running") setImmediate(() => close().catch(() => {}));
+      }
+    });
+    const laneWork = handlerWork.catch(() => {});
+    serialLanes.set(lane, laneWork);
+    laneWork.finally(() => {
+      if (serialLanes.get(lane) === laneWork) serialLanes.delete(lane);
+    });
+  }
+
+  function acceptConnection(socket) {
+    socket.setNoDelay?.(true);
+    const connection = { buffer: Buffer.alloc(0), pending: 0, closeAfterPending: false };
+    Object.defineProperty(socket, "__writerDaemonConnection", { value: connection, configurable: true });
+    connections.add(socket);
+    socket.on("data", chunk => {
+      if (state !== "running" || !Buffer.isBuffer(chunk)) return;
+      connection.buffer = Buffer.concat([connection.buffer, chunk]);
+      while (true) {
+        const newline = connection.buffer.indexOf(0x0a);
+        if (newline === -1) {
+          if (connection.buffer.length > maxRequestBytes) {
+            connection.buffer = Buffer.alloc(0);
+            protocolFailure(socket, cliError("E_DAEMON_REQUEST_TOO_LARGE", "daemon request가 허용 크기를 초과했습니다."), null, true);
+          }
+          return;
+        }
+        if (newline > maxRequestBytes) {
+          connection.buffer = connection.buffer.subarray(newline + 1);
+          protocolFailure(socket, cliError("E_DAEMON_REQUEST_TOO_LARGE", "daemon request가 허용 크기를 초과했습니다."), null, true);
+          return;
+        }
+        const frame = connection.buffer.subarray(0, newline);
+        connection.buffer = connection.buffer.subarray(newline + 1);
+        let request;
+        try { request = validateRequest(parseFrame(frame, "request")); }
+        catch (error) {
+          protocolFailure(socket, error);
+          continue;
+        }
+        queueRequest(socket, connection, request);
+      }
+    });
+    socket.once("error", () => {});
+    socket.once("close", () => connections.delete(socket));
+    if (state !== "running") socket.end();
+  }
+
+  async function start() {
+    if (state === "running") return api;
+    if (state !== "idle") throw cliError("E_DAEMON_STATE", `Writer daemon을 ${state} 상태에서 시작할 수 없습니다.`);
+    state = "starting";
+    try {
+      prepareCacheDirectory(paths.cacheDir, { fs: fsApi, uid: options.uid });
+      await prepareSocketPath(paths.socketPath, { fs: fsApi, net: netApi, probe: options.probeSocket, timeoutMs: options.probeTimeoutMs });
+      server = netApi.createServer(acceptConnection);
+      server.on("error", () => {});
+      await new Promise((resolve, reject) => {
+        const onError = error => { server.off("listening", onListening); reject(error); };
+        const onListening = () => { server.off("error", onError); resolve(); };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(paths.socketPath);
+      });
+      fsApi.chmodSync(paths.socketPath, 0o600);
+      const stat = fsApi.lstatSync(paths.socketPath);
+      if (!stat.isSocket() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o600) {
+        throw cliError("E_DAEMON_SOCKET_UNSAFE", "daemon socket 권한 또는 파일 형식이 안전하지 않습니다.");
+      }
+      const uid = typeof options.uid === "number" ? options.uid : process.getuid?.();
+      if (Number.isInteger(uid) && Number.isInteger(stat.uid) && stat.uid !== uid) {
+        throw cliError("E_DAEMON_SOCKET_UNSAFE", "daemon socket의 소유자가 현재 사용자와 다릅니다.");
+      }
+      socketIdentity = { dev: stat.dev, ino: stat.ino };
+      state = "running";
+      return api;
+    } catch (error) {
+      state = "idle";
+      if (server) {
+        try { server.close(); } catch (closeError) { void closeError; }
+        server = null;
+      }
+      throw error.code?.startsWith?.("E_") ? error : cliError("E_DAEMON_START", "Writer daemon을 시작할 수 없습니다.", null, error);
+    }
+  }
+
+  function unlinkOwnedSocket() {
+    if (!socketIdentity) return;
+    try {
+      const current = fsApi.lstatSync(paths.socketPath);
+      if (sameFile(socketIdentity, current) && current.isSocket()) fsApi.unlinkSync(paths.socketPath);
+    } catch (error) { if (error.code !== "ENOENT") throw error; }
+    socketIdentity = null;
+  }
+
+  async function close() {
+    if (closePromise) return closePromise;
+    if (state === "idle" || state === "closed") return;
+    state = "closing";
+    closePromise = (async () => {
+      for (const socket of connections) {
+        const connection = socket.__writerDaemonConnection;
+        if (!connection || connection.pending === 0) socket.end();
+        else connection.closeAfterPending = true;
+      }
+      const closed = new Promise(resolve => {
+        if (!server) { resolve(); return; }
+        try { server.close(() => resolve()); }
+        catch (error) { resolve(); }
+      });
+      let forceTimer;
+      await Promise.race([
+        closed,
+        new Promise(resolve => {
+          forceTimer = setTimeout(() => {
+            for (const socket of connections) socket.destroy();
+            resolve();
+          }, closeTimeoutMs);
+          forceTimer.unref?.();
+        })
+      ]);
+      if (forceTimer) clearTimeout(forceTimer);
+      for (const socket of connections) socket.destroy();
+      try { unlinkOwnedSocket(); } catch (error) { void error; }
+      server = null;
+      state = "closed";
+    })();
+    return closePromise;
+  }
+
+  const api = Object.freeze({
+    protocol: PROTOCOL,
+    cacheDir: paths.cacheDir,
+    socketPath: paths.socketPath,
+    start,
+    close,
+    get state() { return state; }
+  });
+  return api;
+}
+
+module.exports = Object.freeze({
+  DEFAULT_CACHE_DIRECTORY,
+  DEFAULT_SOCKET_NAME,
+  MAX_SOCKET_PATH_BYTES,
+  resolveDaemonPaths,
+  prepareCacheDirectory,
+  verifyDaemonEndpoint,
+  probeSocket,
+  prepareSocketPath,
+  createDaemonServer
+});

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

@@ -0,0 +1,235 @@
+"use strict";
+
+const fs = require("node:fs");
+const config = require("../../../config.js");
+const packageManifest = require("../package.json");
+const { createCredentialStorage, createWindowsDpapiStorage, inspectStoredSession } = require("./auth.cjs");
+const { probeDaemon } = require("./daemon-runner.cjs");
+const { computeSourceFingerprint } = require("./source-fingerprint.cjs");
+
+const REGISTRY_URL = "https://registry.npmjs.org/@ssobig%2Fwriter-cli/latest";
+
+function parseSemver(value) {
+  const match = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(String(value || ""));
+  if (!match) return null;
+  return Object.freeze({ major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]), prerelease: match[4] ? match[4].split(".") : [] });
+}
+
+function compareIdentifiers(left, right) {
+  const leftNumeric = /^\d+$/.test(left);
+  const rightNumeric = /^\d+$/.test(right);
+  if (leftNumeric && rightNumeric) return Number(left) - Number(right);
+  if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1;
+  return left.localeCompare(right, "en");
+}
+
+function compareSemver(leftValue, rightValue) {
+  const left = parseSemver(leftValue);
+  const right = parseSemver(rightValue);
+  if (!left || !right) return null;
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) return left[key] > right[key] ? 1 : -1;
+  }
+  if (!left.prerelease.length || !right.prerelease.length) {
+    if (left.prerelease.length === right.prerelease.length) return 0;
+    return left.prerelease.length ? -1 : 1;
+  }
+  const length = Math.max(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left.prerelease[index] === undefined) return -1;
+    if (right.prerelease[index] === undefined) return 1;
+    const compared = compareIdentifiers(left.prerelease[index], right.prerelease[index]);
+    if (compared !== 0) return compared > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+function minimumVersion(requirement) {
+  const match = /^>=(\d+\.\d+\.\d+)$/.exec(String(requirement || ""));
+  return match ? match[1] : null;
+}
+
+function nodeSupport(version = process.versions.node, requirement = packageManifest.engines.node) {
+  const minimum = minimumVersion(requirement);
+  const comparison = minimum ? compareSemver(version, minimum) : null;
+  return Object.freeze({ version: String(version), required: String(requirement), supported: comparison !== null && comparison >= 0 });
+}
+
+async function fetchLatestVersion(options = {}) {
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new Error("npm registry를 확인할 fetch 구현이 없습니다.");
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), Math.max(250, Number(options.timeoutMs || 5_000)));
+  timeout.unref?.();
+  try {
+    const response = await fetchImpl(REGISTRY_URL, { headers: { Accept: "application/json" }, redirect: "error", signal: controller.signal });
+    if (!response.ok) throw new Error(`npm registry HTTP ${response.status}`);
+    const payload = await response.json();
+    if (!parseSemver(payload?.version)) throw new Error("npm registry version이 올바르지 않습니다.");
+    return String(payload.version);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function versionReport(options = {}) {
+  const currentVersion = String(options.version || packageManifest.version);
+  const report = {
+    package: String(packageManifest.name),
+    version: currentVersion,
+    node: nodeSupport(options.nodeVersion || process.versions.node, packageManifest.engines.node),
+    platform: String(options.platform || process.platform),
+    arch: String(options.arch || process.arch),
+    sourceFingerprint: String((options.computeFingerprint || computeSourceFingerprint)())
+  };
+  if (options.checkLatest === true) {
+    try {
+      const latestVersion = await (options.fetchLatest || fetchLatestVersion)({ fetch: options.fetch, timeoutMs: options.timeoutMs });
+      const comparison = compareSemver(latestVersion, currentVersion);
+      report.registry = { status: comparison !== null && comparison > 0 ? "update-available" : "current", latestVersion, updateAvailable: comparison !== null && comparison > 0, error: null };
+    } catch (error) {
+      report.registry = { status: "unavailable", latestVersion: null, updateAvailable: null, error: "npm registry에서 최신 버전을 확인하지 못했습니다." };
+    }
+  }
+  return Object.freeze(report);
+}
+
+function check(id, status, message, code = null, remediation = null) {
+  return Object.freeze({ id, status, code, message, remediation });
+}
+
+function overallStatus(checks) {
+  if (checks.some(item => item.status === "error")) return "error";
+  if (checks.some(item => item.status === "warning")) return "warning";
+  return "ok";
+}
+
+function defaultKeychainCheck(options = {}) {
+  (options.fs || fs).accessSync("/usr/bin/security", fs.constants.X_OK);
+  return true;
+}
+
+async function defaultSessionStatus(options = {}) {
+  const storage = createCredentialStorage({ ...(options.credentialOptions || {}), platform: options.platform });
+  return inspectStoredSession(storage, { now: options.now });
+}
+
+async function defaultCredentialStoreCheck(options = {}) {
+  const platform = String(options.platform || process.platform);
+  if (platform === "darwin") return defaultKeychainCheck(options);
+  if (platform === "win32") {
+    const storage = createWindowsDpapiStorage({ ...(options.credentialOptions || {}), platform });
+    return storage.probe();
+  }
+  return false;
+}
+
+async function defaultHealthCheck(options = {}) {
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new Error("Supabase health를 확인할 fetch 구현이 없습니다.");
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), Math.max(250, Number(options.timeoutMs || 5_000)));
+  timeout.unref?.();
+  try {
+    const response = await fetchImpl(`${config.supabaseUrl}/auth/v1/health`, { headers: { apikey: config.supabaseKey, Accept: "application/json" }, redirect: "error", signal: controller.signal });
+    if (!response.ok) throw new Error(`Supabase Auth health HTTP ${response.status}`);
+    return true;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function doctorReport(options = {}) {
+  const checks = [];
+  const platform = String(options.platform || process.platform);
+  const node = nodeSupport(options.nodeVersion || process.versions.node, packageManifest.engines.node);
+  checks.push(node.supported
+    ? check("node", "ok", `Node.js ${node.version}이 지원 범위입니다.`)
+    : check("node", "error", `Node.js ${node.required}가 필요합니다.`, "E_NODE_UNSUPPORTED", `Node.js ${node.required}로 업데이트해 주세요.`));
+  const supportedPlatform = ["darwin", "win32"].includes(platform);
+  checks.push(supportedPlatform
+    ? check("platform", "ok", `지원 플랫폼 ${platform === "darwin" ? "macOS" : "Windows"}를 확인했습니다.`)
+    : check("platform", "error", `현재 플랫폼 ${platform}은 공개 CLI 인증을 지원하지 않습니다.`, "E_PLATFORM_UNSUPPORTED", "macOS 또는 Windows에서 Writer CLI를 실행해 주세요."));
+
+  try {
+    const fingerprint = String((options.computeFingerprint || computeSourceFingerprint)());
+    checks.push(check("package", "ok", `공개 package runtime 무결성을 확인했습니다: ${fingerprint}`));
+  } catch (error) {
+    checks.push(check("package", "error", "공개 package runtime 파일이 누락되었거나 손상됐습니다.", "E_PACKAGE_INTEGRITY", "Writer CLI를 최신 버전으로 다시 설치해 주세요."));
+  }
+
+  if (options.checkLatestVersion === true) {
+    try {
+      const currentVersion = String(options.currentVersion || packageManifest.version);
+      const latestVersion = await (options.fetchLatest || fetchLatestVersion)({ fetch: options.fetch, timeoutMs: options.timeoutMs });
+      if (compareSemver(latestVersion, currentVersion) > 0) checks.push(check("cli-update", "error", `Writer CLI ${currentVersion}보다 최신 필수 버전 ${latestVersion}이 있습니다.`, "E_CLI_UPDATE_REQUIRED", "npm install --global @ssobig/writer-cli@latest"));
+      else checks.push(check("cli-update", "ok", `Writer CLI ${currentVersion}이 npm latest 기준 최신입니다.`));
+    } catch (error) {
+      checks.push(check("cli-update", "warning", "npm registry에서 최신 Writer CLI 버전을 확인하지 못했습니다.", "W_CLI_UPDATE_CHECK_UNAVAILABLE", "네트워크 연결 후 ssobig-writer version --check를 다시 실행해 주세요."));
+    }
+  }
+
+  let credentialStoreReady = false;
+  if (supportedPlatform) {
+    try {
+      const credentialCheck = options.credentialStoreCheck
+        || (platform === "darwin" && options.keychainCheck)
+        || defaultCredentialStoreCheck;
+      credentialStoreReady = await credentialCheck({
+        platform,
+        fs: options.fs,
+        credentialOptions: options.credentialOptions
+      });
+      if (credentialStoreReady !== true) throw new Error("Credential store check did not confirm availability.");
+      checks.push(platform === "darwin"
+        ? check("keychain", "ok", "macOS Keychain 명령을 사용할 수 있습니다.")
+        : check("credential-store", "ok", "Windows DPAPI CurrentUser credential store를 사용할 수 있습니다."));
+    } catch (error) {
+      checks.push(platform === "darwin"
+        ? check("keychain", "error", "macOS Keychain을 사용할 수 없습니다.", "E_KEYCHAIN_UNAVAILABLE", "Keychain 접근 권한과 /usr/bin/security를 확인해 주세요.")
+        : check("credential-store", "error", "Windows DPAPI credential store를 사용할 수 없습니다.", "E_CREDENTIAL_STORE_UNAVAILABLE", "현재 Windows 사용자 프로필과 PowerShell 실행 환경을 확인해 주세요."));
+    }
+  } else {
+    checks.push(check("keychain", "error", "현재 플랫폼에는 지원되는 Writer CLI credential store가 없습니다.", "E_KEYCHAIN_UNAVAILABLE", "macOS에서 Writer CLI를 실행해 주세요."));
+  }
+
+  if (credentialStoreReady) {
+    try {
+      const session = await (options.sessionStatus || defaultSessionStatus)({ platform, now: options.now, credentialOptions: options.credentialOptions });
+      if (session.status === "active") checks.push(check("auth-session", "ok", "로컬 Writer CLI 로그인 세션이 있습니다."));
+      else if (session.status === "expired") checks.push(check("auth-session", "warning", "로컬 Writer CLI 로그인 세션이 만료됐습니다.", "E_AUTH_EXPIRED", "ssobig-writer auth login을 실행해 주세요."));
+      else if (session.status === "malformed") checks.push(check("auth-session", "error", "로컬 Writer CLI 로그인 세션 형식이 올바르지 않습니다.", "E_AUTH_SESSION_INVALID", "ssobig-writer auth logout 후 다시 로그인해 주세요."));
+      else checks.push(check("auth-session", "warning", "로컬 Writer CLI 로그인 세션이 없습니다.", "E_AUTH_REQUIRED", "ssobig-writer auth login을 실행해 주세요."));
+    } catch (error) {
+      checks.push(check("auth-session", "error", "credential store에서 Writer CLI 로그인 세션을 확인할 수 없습니다.", "E_CREDENTIAL_STORE_UNAVAILABLE", "credential store 접근 권한을 확인해 주세요."));
+    }
+  } else {
+    checks.push(check("auth-session", "warning", "credential store를 사용할 수 없어 로그인 세션 검사를 건너뛰었습니다.", "E_AUTH_SESSION_SKIPPED", null));
+  }
+
+  try {
+    await (options.healthCheck || defaultHealthCheck)({ fetch: options.fetch, timeoutMs: options.timeoutMs });
+    checks.push(check("supabase", "ok", "SSOBIG WRITER Auth 서비스에 연결할 수 있습니다."));
+  } catch (error) {
+    checks.push(check("supabase", "error", "SSOBIG WRITER Auth 서비스에 연결할 수 없습니다.", "E_SERVICE_UNAVAILABLE", "네트워크 연결을 확인한 뒤 다시 시도해 주세요."));
+  }
+
+  if (platform === "win32") {
+    checks.push(check("daemon", "ok", "Windows에서는 background daemon 없이 안전한 in-process backend를 사용합니다."));
+  } else {
+    try {
+      await (options.probeDaemon || probeDaemon)({ timeoutMs: 500 });
+      checks.push(check("daemon", "ok", "Writer daemon이 현재 CLI와 같은 계약으로 실행 중입니다."));
+    } catch (error) {
+      if (["E_DAEMON_UNAVAILABLE", "E_DAEMON_CONNECT_TIMEOUT"].includes(String(error?.code || ""))) {
+        checks.push(check("daemon", "warning", "Writer daemon이 실행 중이 아닙니다.", "E_DAEMON_UNAVAILABLE", "필요할 때 ssobig-writer agent start를 실행해 주세요."));
+      } else {
+        checks.push(check("daemon", "error", "Writer daemon 상태가 현재 CLI 계약과 맞지 않습니다.", String(error?.code || "E_DAEMON_STATUS"), "ssobig-writer agent stop 후 다시 시작해 주세요."));
+      }
+    }
+  }
+
+  return Object.freeze({ overall: overallStatus(checks), checks: Object.freeze(checks) });
+}
+
+module.exports = Object.freeze({ REGISTRY_URL, parseSemver, compareSemver, nodeSupport, fetchLatestVersion, versionReport, defaultKeychainCheck, defaultCredentialStoreCheck, defaultSessionStatus, defaultHealthCheck, doctorReport, overallStatus });