ai-dev-maintenance 0.1.0

package/dist/cli.js

@@ -0,0 +1,1115 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+
+// src/doctor.ts
+import path5 from "path";
+
+// src/commands.ts
+import { spawn } from "child_process";
+import { chmod, lstat, mkdtemp, rm } from "fs/promises";
+import os from "os";
+import path from "path";
+var ALLOWED_COMMANDS = {
+  sqlite3: "/usr/bin/sqlite3",
+  lsof: "/usr/sbin/lsof",
+  ps: "/bin/ps"
+};
+function isTrustedSystemCommand(stat) {
+  const allowed = new Set(Object.values(ALLOWED_COMMANDS));
+  const groupOrOtherWritable = (stat.mode & 18) !== 0;
+  return allowed.has(stat.path) && stat.uid === 0 && !stat.isSymbolicLink && !groupOrOtherWritable;
+}
+async function trustedCommandPath(name) {
+  const commandPath = ALLOWED_COMMANDS[name];
+  const info = await lstat(commandPath);
+  const trusted = isTrustedSystemCommand({
+    path: commandPath,
+    uid: info.uid,
+    mode: info.mode,
+    isSymbolicLink: info.isSymbolicLink()
+  });
+  if (!trusted) {
+    throw new Error(`untrusted system command: ${name}`);
+  }
+  return commandPath;
+}
+async function runCommand(command, args, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  const maxStdoutBytes = options.maxStdoutBytes ?? 256e3;
+  const maxStderrBytes = options.maxStderrBytes ?? 64e3;
+  const childHome = await mkdtemp(path.join(os.tmpdir(), "ai-dev-maintenance-home-"));
+  await chmod(childHome, 448);
+  return await new Promise((resolve) => {
+    const child = spawn(command, args, {
+      shell: false,
+      env: {
+        PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+        HOME: childHome
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = Buffer.alloc(0);
+    let stderr = Buffer.alloc(0);
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let settled = false;
+    let timedOut = false;
+    let timeoutSignal;
+    let killTimer;
+    const finish = (result) => {
+      rm(childHome, { recursive: true, force: true }).catch(() => void 0).finally(
+        () => resolve({
+          ...result,
+          stdoutTruncated,
+          stderrTruncated
+        })
+      );
+    };
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      timeoutSignal = "SIGTERM";
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        timeoutSignal = "SIGKILL";
+        child.kill("SIGKILL");
+      }, 1e3);
+      killTimer.unref();
+    }, timeoutMs);
+    timeout.unref();
+    child.stdout?.on("data", (chunk) => {
+      if (stdout.length >= maxStdoutBytes) {
+        stdoutTruncated = true;
+        return;
+      }
+      const next = Buffer.concat([stdout, chunk]);
+      if (next.length > maxStdoutBytes) stdoutTruncated = true;
+      stdout = next.subarray(0, maxStdoutBytes);
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderr.length >= maxStderrBytes) {
+        stderrTruncated = true;
+        return;
+      }
+      const next = Buffer.concat([stderr, chunk]);
+      if (next.length > maxStderrBytes) stderrTruncated = true;
+      stderr = next.subarray(0, maxStderrBytes);
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (killTimer) clearTimeout(killTimer);
+      finish({ code: null, stdout: "", stderr: error.message });
+    });
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (killTimer) clearTimeout(killTimer);
+      finish({
+        code,
+        signal: signal ?? timeoutSignal,
+        stdout: stdout.toString("utf8"),
+        stderr: stderr.toString("utf8"),
+        timedOut
+      });
+    });
+  });
+}
+
+// src/fs-safety.ts
+import { constants } from "fs";
+import { access, lstat as lstat2, mkdir, realpath } from "fs/promises";
+import path2 from "path";
+async function collectFileIdentity(filePath, pathCategory) {
+  try {
+    const lst = await lstat2(filePath);
+    const isLink = lst.isSymbolicLink();
+    const resolved = isLink ? void 0 : await realpath(filePath).catch(() => void 0);
+    return {
+      pathCategory,
+      realpath: resolved,
+      dev: lst.dev,
+      ino: lst.ino,
+      mode: lst.mode,
+      uid: lst.uid,
+      gid: lst.gid,
+      size: lst.size,
+      mtimeMs: lst.mtimeMs,
+      nlink: lst.nlink,
+      exists: true,
+      regularFile: lst.isFile(),
+      symbolicLink: isLink
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return {
+        pathCategory,
+        exists: false,
+        regularFile: false,
+        symbolicLink: false
+      };
+    }
+    throw error;
+  }
+}
+async function detectTargetState(mainPath) {
+  const main = await collectFileIdentity(mainPath, "codex-log-db-main");
+  const wal = await collectFileIdentity(`${mainPath}-wal`, "codex-log-db-wal");
+  const shm = await collectFileIdentity(`${mainPath}-shm`, "codex-log-db-shm");
+  const blockers = [];
+  const uid = process.getuid?.();
+  if (!main.exists) blockers.push("main database is missing");
+  blockers.push(...fileBlockers(main, "main database", uid));
+  for (const sidecar of [wal, shm]) {
+    if (!sidecar.exists) continue;
+    blockers.push(...fileBlockers(sidecar, sidecar.pathCategory, uid));
+  }
+  return {
+    mainPath,
+    exists: main.exists,
+    fixable: blockers.length === 0,
+    blockers,
+    main,
+    wal,
+    shm
+  };
+}
+function fileBlockers(file, label, uid) {
+  if (!file.exists) return [];
+  const blockers = [];
+  if (file.symbolicLink) blockers.push(`${label} is a symlink`);
+  if (!file.regularFile) blockers.push(`${label} is not a regular file`);
+  if (file.nlink !== void 0 && file.nlink > 1) blockers.push(`${label} has hard links`);
+  if (uid !== void 0 && file.uid !== uid) blockers.push(`${label} is not owned by current user`);
+  if (file.mode !== void 0 && (file.mode & 18) !== 0) {
+    blockers.push(`${label} is group/other writable`);
+  }
+  return blockers;
+}
+async function assertDirectoryChainSafe(startDir, stopDir) {
+  const blockers = [];
+  let current = path2.resolve(startDir);
+  const stop = path2.resolve(stopDir);
+  const uid = process.getuid?.();
+  while (current === stop || current.startsWith(`${stop}${path2.sep}`)) {
+    const info = await lstat2(current);
+    if (info.isSymbolicLink()) blockers.push(`${current} is a symlink`);
+    if (uid !== void 0 && info.uid !== uid) blockers.push(`${current} is not owned by current user`);
+    if ((info.mode & 18) !== 0) blockers.push(`${current} is group/other writable`);
+    if (current === stop) break;
+    const next = path2.dirname(current);
+    if (next === current) break;
+    current = next;
+  }
+  return blockers;
+}
+async function assertPrivateAppDirSafe(dir) {
+  return await checkPrivateAppDirSafe(dir, { createMissing: true });
+}
+async function assertExistingPrivateDirSafe(dir) {
+  return await checkPrivateAppDirSafe(dir, { createMissing: false });
+}
+async function checkPrivateAppDirSafe(dir, options) {
+  const blockers = [];
+  const resolved = path2.resolve(dir);
+  const uid = process.getuid?.();
+  const root = path2.parse(resolved).root;
+  const parts = resolved.slice(root.length).split(path2.sep).filter(Boolean);
+  const markerIndex = parts.indexOf(".ai-dev-maintenance");
+  const startIndex = markerIndex >= 0 ? markerIndex : parts.length - 1;
+  let current = path2.join(root, ...parts.slice(0, startIndex));
+  for (const [offset, part] of parts.slice(startIndex).entries()) {
+    current = path2.join(current, part);
+    let info = await lstat2(current).catch(async (error) => {
+      if (error.code !== "ENOENT") throw error;
+      if (!options.createMissing) {
+        blockers.push(`${offset === 0 ? "<app-data>" : `<app-data-component:${offset}>`} is missing`);
+        return void 0;
+      }
+      await mkdir(current, { mode: 448 });
+      return await lstat2(current);
+    });
+    const label = offset === 0 ? "<app-data>" : `<app-data-component:${offset}>`;
+    if (!info) return blockers;
+    if (info.isSymbolicLink()) {
+      blockers.push(`${label} is a symlink`);
+      return blockers;
+    }
+    if (!info.isDirectory()) {
+      blockers.push(`${label} is not a directory`);
+      return blockers;
+    }
+    if (uid !== void 0 && info.uid !== uid) blockers.push(`${label} is not owned by current user`);
+    if ((info.mode & 18) !== 0) blockers.push(`${label} is group/other writable`);
+    else if ((info.mode & 63) !== 0) blockers.push(`${label} exposes group/other permissions`);
+    if (blockers.length > 0) return blockers;
+  }
+  return blockers;
+}
+async function assertSafeReadablePrivateFile(filePath, label) {
+  const blockers = [];
+  const uid = process.getuid?.();
+  let info;
+  try {
+    info = await lstat2(filePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return [`${label} is missing`];
+    throw error;
+  }
+  if (info.isSymbolicLink()) blockers.push(`${label} is a symlink`);
+  if (!info.isFile()) blockers.push(`${label} is not a regular file`);
+  if (info.nlink > 1) blockers.push(`${label} has hard links`);
+  if (uid !== void 0 && info.uid !== uid) blockers.push(`${label} is not owned by current user`);
+  if ((info.mode & 18) !== 0) blockers.push(`${label} is group/other writable`);
+  return blockers;
+}
+function compareTargetIdentities(before, after, options) {
+  const blockers = [];
+  compareFileIdentity("main database", before.main, after.main, Boolean(options.allowMainSizeMtimeChange), blockers);
+  compareFileIdentity("codex-log-db-wal", before.wal, after.wal, options.allowSidecarSizeMtimeChange, blockers);
+  compareFileIdentity("codex-log-db-shm", before.shm, after.shm, options.allowSidecarSizeMtimeChange, blockers);
+  return blockers;
+}
+function compareFileIdentity(label, before, after, allowSizeMtimeChange, blockers) {
+  if (!before?.exists && !after?.exists) return;
+  const stableKeys = [
+    "exists",
+    "regularFile",
+    "symbolicLink",
+    "dev",
+    "ino",
+    "nlink",
+    "mode",
+    "uid",
+    "gid"
+  ];
+  for (const key of stableKeys) {
+    if (before?.[key] !== after?.[key]) {
+      blockers.push(`${label} identity changed`);
+      return;
+    }
+  }
+  if (!allowSizeMtimeChange && (before?.size !== after?.size || before?.mtimeMs !== after?.mtimeMs)) {
+    blockers.push(`${label} identity changed`);
+  }
+}
+function safeTargetStateForReport(state) {
+  return {
+    exists: state.exists,
+    fixable: state.fixable,
+    blockers: state.blockers,
+    main: safeIdentityForReport(state.main),
+    wal: safeIdentityForReport(state.wal),
+    shm: safeIdentityForReport(state.shm)
+  };
+}
+function safeIdentityForReport(file) {
+  if (!file) return void 0;
+  return {
+    pathCategory: file.pathCategory,
+    exists: file.exists,
+    regularFile: file.regularFile,
+    symbolicLink: file.symbolicLink,
+    size: file.size
+  };
+}
+
+// src/paths.ts
+import { pathToFileURL } from "url";
+import os2 from "os";
+import path3 from "path";
+var macHomePathPattern = /\/Users\/[^/]+/g;
+var nonHomeAbsolutePathStart = /\/(?:private|Volumes|tmp|var)\//g;
+function createSqliteUri(absolutePath, mode) {
+  if (!path3.isAbsolute(absolutePath)) {
+    throw new Error("SQLite paths must be absolute");
+  }
+  const url = pathToFileURL(absolutePath);
+  url.searchParams.set("mode", mode);
+  return url.href;
+}
+function redactPath(value) {
+  const home = os2.homedir();
+  let redacted = value;
+  if (home) {
+    redacted = redacted.replaceAll(home, "<home>");
+  }
+  redacted = redacted.replace(macHomePathPattern, "<home>");
+  return redactNonHomeAbsolutePaths(redacted);
+}
+function redactNonHomeAbsolutePaths(value) {
+  let result = "";
+  let cursor = 0;
+  for (const match of value.matchAll(nonHomeAbsolutePathStart)) {
+    const start = match.index ?? 0;
+    if (start < cursor) continue;
+    const end = findAbsolutePathEnd(value, start);
+    result += value.slice(cursor, start);
+    result += "<absolute-path>";
+    cursor = end;
+  }
+  return result + value.slice(cursor);
+}
+function findAbsolutePathEnd(value, start) {
+  let end = start;
+  while (end < value.length && !['"', "'", ",", ";", ":", ")", "\n", "\r"].includes(value[end] ?? "")) {
+    end++;
+  }
+  const segment = value.slice(start, end);
+  const extensionBeforeSpace = /\.[A-Za-z0-9_-]+(?=\s)/.exec(segment);
+  if (extensionBeforeSpace) return start + extensionBeforeSpace.index + extensionBeforeSpace[0].length;
+  return end;
+}
+function defaultCodexHome(env = process.env) {
+  const defaultHome = path3.join(os2.homedir(), ".codex");
+  const candidate = env.CODEX_HOME;
+  if (candidate && path3.resolve(candidate) !== defaultHome) {
+    return { codexHome: path3.resolve(candidate), custom: true };
+  }
+  return { codexHome: defaultHome, custom: false };
+}
+function targetTriple(mainPath) {
+  return [mainPath, `${mainPath}-wal`, `${mainPath}-shm`];
+}
+function appDataHome() {
+  return path3.join(os2.homedir(), ".ai-dev-maintenance");
+}
+
+// src/reports.ts
+import { readFile, readdir, writeFile } from "fs/promises";
+import path4 from "path";
+async function ensurePrivateDir(dir) {
+  const blockers = await assertPrivateAppDirSafe(dir);
+  if (blockers.length > 0) {
+    throw new Error(`unsafe private directory: ${blockers.join("; ")}`);
+  }
+}
+async function writeReport(report) {
+  const dir = path4.join(appDataHome(), "reports");
+  await ensurePrivateDir(dir);
+  const stamp = report.generatedAt.replace(/[:.]/g, "-");
+  const file = path4.join(dir, `report-${stamp}.json`);
+  await writeFile(file, `${JSON.stringify(report, null, 2)}
+`, { mode: 384, flag: "wx" });
+  return file;
+}
+async function latestReport() {
+  const dir = path4.join(appDataHome(), "reports");
+  await ensurePrivateDir(dir);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return null;
+  }
+  const reports = entries.filter((entry) => /^report-.*\.json$/.test(entry)).sort();
+  const latest = reports.at(-1);
+  if (!latest) return null;
+  const file = path4.join(dir, latest);
+  const fileBlockers2 = await assertSafeReadablePrivateFile(file, "report file");
+  if (fileBlockers2.length > 0) {
+    throw new Error(`unsafe report file: ${fileBlockers2.join("; ")}`);
+  }
+  return {
+    path: file,
+    report: sanitizeReportForOutput(JSON.parse(await readFile(file, "utf8")))
+  };
+}
+function sanitizeReportForOutput(report) {
+  return {
+    schemaVersion: 1,
+    toolVersion: sanitizeString(report.toolVersion),
+    generatedAt: sanitizeString(report.generatedAt),
+    command: sanitizeString(report.command),
+    status: report.status,
+    redacted: true,
+    target: {
+      kind: report.target?.kind === "default-codex-log-db" ? "default-codex-log-db" : "unknown",
+      pathCategory: sanitizeString(report.target?.pathCategory ?? "unknown")
+    },
+    findings: sanitizeRecord(report.findings),
+    metrics: sanitizeRecord(report.metrics),
+    blockedReasons: Array.isArray(report.blockedReasons) ? report.blockedReasons.map((reason) => sanitizeString(String(reason))) : [],
+    nextSafeAction: report.nextSafeAction ? sanitizeString(report.nextSafeAction) : void 0
+  };
+}
+function sanitizeRecord(value) {
+  const sanitized = sanitizeJsonValue(value);
+  return isPlainObject(sanitized) ? sanitized : {};
+}
+function sanitizeJsonValue(value, key = "") {
+  if (isForbiddenReportKey(key)) return void 0;
+  if (typeof value === "string") return sanitizeString(value);
+  if (typeof value === "number" || typeof value === "boolean" || value === null) return value;
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeJsonValue(item)).filter((item) => item !== void 0);
+  }
+  if (!isPlainObject(value)) return void 0;
+  const result = {};
+  for (const [childKey, childValue] of Object.entries(value)) {
+    const sanitized = sanitizeJsonValue(childValue, childKey);
+    if (sanitized !== void 0) result[sanitizeReportKey(childKey)] = sanitized;
+  }
+  return result;
+}
+function sanitizeString(value) {
+  return redactPath(value);
+}
+function sanitizeReportKey(key) {
+  return redactPath(key);
+}
+function isForbiddenReportKey(key) {
+  return (/* @__PURE__ */ new Set([
+    "dev",
+    "ino",
+    "uid",
+    "gid",
+    "mode",
+    "mtimeMs",
+    "realpath",
+    "rawStderr",
+    "stderr",
+    "stdout"
+  ])).has(key);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+// src/safety.ts
+function classifyLsofResult(result) {
+  if ("timedOut" in result && result.timedOut) {
+    return { usable: false, openHandles: false, reason: "timeout" };
+  }
+  if ("stdoutTruncated" in result && result.stdoutTruncated) {
+    return { usable: false, openHandles: false, reason: "lsof_output_truncated" };
+  }
+  if ("stderrTruncated" in result && result.stderrTruncated) {
+    return { usable: false, openHandles: false, reason: "lsof_error_truncated" };
+  }
+  const stdout = result.stdout.trim();
+  const stderr = result.stderr.trim();
+  if (stderr.length > 0) {
+    const lower = stderr.toLowerCase();
+    if (lower.includes("permission denied") || lower.includes("operation not permitted")) {
+      return { usable: false, openHandles: false, reason: "permission_denied" };
+    }
+    return { usable: false, openHandles: false, reason: "nonzero_stderr" };
+  }
+  if (result.code === 0) {
+    return {
+      usable: true,
+      openHandles: stdout.length > 0,
+      reason: stdout.length > 0 ? "open handles reported" : "no open handles reported"
+    };
+  }
+  if (result.code === 1 && stdout.length === 0 && stderr.length === 0) {
+    return { usable: true, openHandles: false, reason: "no open handles reported" };
+  }
+  return { usable: false, openHandles: false, reason: "nonzero_exit" };
+}
+function planFixSafety(input) {
+  const reasons = [];
+  if (input.knownCodexProcessExists) reasons.push("known Codex process is running");
+  if (input.anyOpenHandleOnTarget) reasons.push("target database is open by a process");
+  if (!input.lsofUsable) reasons.push("open-handle check is unavailable");
+  if (input.processListTruncated) reasons.push("process list check was truncated");
+  return { allowed: reasons.length === 0, reasons };
+}
+function parseKnownCodexProcess(psOutput, currentPid = process.pid) {
+  return psOutput.split("\n").map((line) => line.trim()).filter(Boolean).some((line) => {
+    const pid = Number(line.split(/\s+/, 1)[0]);
+    if (pid === currentPid) return false;
+    return /\b(Codex|codex|codex-cli|Codex Helper|OpenAI Codex|com\.openai\.codex)\b/.test(line);
+  });
+}
+
+// src/sqlite.ts
+async function checkSqliteJsonSupport() {
+  try {
+    const sqlite = await trustedCommandPath("sqlite3");
+    const result = await runCommand(sqlite, ["-json", "-init", "/dev/null", ":memory:", "select 1 as ok"], {
+      timeoutMs: 5e3
+    });
+    if (result.code !== 0) return { ok: false, reason: result.stderr.trim() || "sqlite3 failed" };
+    const parsed = JSON.parse(result.stdout);
+    return { ok: parsed?.[0]?.ok === 1, reason: parsed?.[0]?.ok === 1 ? void 0 : "unexpected sqlite3 json output" };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function inspectSqliteSnapshot(mainPath) {
+  try {
+    const quickCheck = await sqliteJson(mainPath, "ro", "PRAGMA quick_check;");
+    const table = await sqliteJson(
+      mainPath,
+      "ro",
+      "SELECT name FROM sqlite_schema WHERE type='table' AND name='logs';"
+    );
+    const columns = await sqliteJson(mainPath, "ro", "PRAGMA table_info(logs);");
+    const pageSize = await sqliteJson(mainPath, "ro", "PRAGMA page_size;");
+    const pageCount = await sqliteJson(mainPath, "ro", "PRAGMA page_count;");
+    const freelistCount = await sqliteJson(mainPath, "ro", "PRAGMA freelist_count;");
+    const autoVacuum = await sqliteJson(mainPath, "ro", "PRAGMA auto_vacuum;");
+    const columnNames = Array.isArray(columns) ? columns.map((row) => String(row.name)) : [];
+    return {
+      quickCheck: String(quickCheck?.[0]?.quick_check ?? ""),
+      hasLogsTable: Boolean(table?.[0]?.name === "logs"),
+      columns: columnNames,
+      recognizedSchema: quickCheck?.[0]?.quick_check === "ok" && table?.[0]?.name === "logs" && columnNames.includes("id") && columnNames.includes("level"),
+      pageSize: Number(pageSize?.[0]?.page_size ?? 0),
+      pageCount: Number(pageCount?.[0]?.page_count ?? 0),
+      freelistCount: Number(freelistCount?.[0]?.freelist_count ?? 0),
+      autoVacuum: Number(autoVacuum?.[0]?.auto_vacuum ?? 0)
+    };
+  } catch (error) {
+    return {
+      recognizedSchema: false,
+      error: sanitizeSqliteError(error)
+    };
+  }
+}
+async function sqliteJson(dbPath, mode, sql) {
+  const sqlite = await trustedCommandPath("sqlite3");
+  const result = await runCommand(sqlite, ["-json", "-init", "/dev/null", createSqliteUri(dbPath, mode), sql], {
+    timeoutMs: 15e3
+  });
+  if (result.code !== 0) {
+    throw new Error(classifySqliteCommandFailure(result.stderr, result.code));
+  }
+  return JSON.parse(result.stdout || "[]");
+}
+function classifySqliteCommandFailure(stderr, code) {
+  const lower = stderr.toLowerCase();
+  if (lower.includes("permission denied") || lower.includes("operation not permitted")) {
+    return "sqlite3 permission_denied";
+  }
+  if (lower.includes("database is locked") || lower.includes("busy")) {
+    return "sqlite3 database_busy";
+  }
+  if (lower.includes("file is not a database") || lower.includes("malformed")) {
+    return "sqlite3 invalid_database";
+  }
+  return code === null ? "sqlite3 failed" : `sqlite3 exited with ${code}`;
+}
+function sanitizeSqliteError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return redactPath(message);
+}
+
+// src/version.ts
+var TOOL_VERSION = "0.1.0";
+var REPORT_SCHEMA_VERSION = 1;
+
+// src/doctor.ts
+async function runDoctor(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (platform !== "darwin") {
+    const report2 = baseReport("doctor", generatedAt, "unsupported");
+    report2.blockedReasons.push("platform is unsupported");
+    report2.nextSafeAction = "Run this tool on macOS.";
+    return { report: report2 };
+  }
+  const { codexHome, custom } = defaultCodexHome(options.env);
+  const mainPath = path5.join(codexHome, "logs_2.sqlite");
+  const state = await detectTargetState(mainPath);
+  const report = baseReport("doctor", generatedAt, state.fixable ? "ok" : "partial");
+  report.target.pathCategory = custom ? "custom-codex-home" : "<home>/.codex/logs_2.sqlite";
+  report.findings.targetState = redactState(state);
+  report.blockedReasons.push(...state.blockers);
+  if (custom) report.blockedReasons.push("custom CODEX_HOME is read-only in doctor and rejected by fix");
+  const sqliteSupport = await checkSqliteJsonSupport();
+  report.findings.sqliteJson = sqliteSupport;
+  const lsof = await checkOpenHandles(targetTriple(mainPath));
+  report.findings.openHandles = lsof;
+  const knownProcess = await knownCodexProcessExists();
+  report.findings.knownCodexProcessExists = knownProcess;
+  report.findings.sqlite = {
+    available: false,
+    reason: "source database inspection is skipped in v1 to avoid copying private log bytes"
+  };
+  const reportPath = await writeReport(report);
+  if (options.showPaths) report.findings.reportPath = redactPath(reportPath);
+  return { report, reportPath };
+}
+async function checkOpenHandles(paths) {
+  try {
+    const lsof = await trustedCommandPath("lsof");
+    const result = await runCommand(lsof, ["-F", "pcn", ...paths], { timeoutMs: 5e3 });
+    return classifyLsofResult(result);
+  } catch (error) {
+    return {
+      usable: false,
+      openHandles: false,
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function knownCodexProcessExists() {
+  try {
+    const ps = await trustedCommandPath("ps");
+    const result = await runCommand(ps, ["-axo", "pid=,comm=,command="], { timeoutMs: 5e3 });
+    if (result.stdoutTruncated || result.stderrTruncated) return "unknown";
+    if (result.code !== 0) return "unknown";
+    return parseKnownCodexProcess(result.stdout);
+  } catch {
+    return "unknown";
+  }
+}
+function baseReport(command, generatedAt, status) {
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    toolVersion: TOOL_VERSION,
+    generatedAt,
+    command,
+    status,
+    redacted: true,
+    target: {
+      kind: "default-codex-log-db",
+      pathCategory: "<home>/.codex/logs_2.sqlite"
+    },
+    findings: {},
+    metrics: {},
+    blockedReasons: []
+  };
+}
+function redactState(state) {
+  return safeTargetStateForReport(state);
+}
+
+// src/fix.ts
+import { chmod as chmod2, mkdtemp as mkdtemp2, rename, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import path6 from "path";
+async function runFixSafe(options = {}) {
+  const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const report = baseFixReport(generatedAt);
+  if ((options.platform ?? process.platform) !== "darwin") {
+    report.status = "unsupported";
+    report.blockedReasons.push("platform is unsupported");
+    return { report };
+  }
+  const { codexHome, custom } = defaultCodexHome(options.env);
+  if (custom) {
+    report.status = "blocked";
+    report.target.pathCategory = "custom-codex-home";
+    report.blockedReasons.push("custom CODEX_HOME is rejected by fix");
+    report.nextSafeAction = "Run doctor for diagnostics only, or unset CODEX_HOME before fix --safe.";
+    return { report, reportPath: await writeReport(report) };
+  }
+  const mainPath = path6.join(codexHome, "logs_2.sqlite");
+  report.blockedReasons.push(...await targetDirectoryBlockers(mainPath));
+  const preflightResult = await runPreflight(mainPath);
+  report.findings.preflight = redactPreflightFindings(preflightResult.findings);
+  report.blockedReasons.push(...preflightResult.blockers);
+  if (report.blockedReasons.length > 0) {
+    report.status = "blocked";
+    report.nextSafeAction = "Close AI coding tools, verify the target path, then run doctor again.";
+    return { report, reportPath: await writeReport(report) };
+  }
+  const beforeBackup = await runPreflight(mainPath);
+  report.blockedReasons.push(...await targetDirectoryBlockers(mainPath));
+  report.blockedReasons.push(
+    ...compareTargetIdentities(preflightResult.findings.targetState, beforeBackup.findings.targetState, {
+      allowSidecarSizeMtimeChange: false
+    })
+  );
+  if (report.blockedReasons.length > 0) {
+    report.status = "blocked";
+    return { report, reportPath: await writeReport(report) };
+  }
+  if (beforeBackup.blockers.length > 0) {
+    report.status = "blocked";
+    report.blockedReasons.push(...beforeBackup.blockers.map((reason) => `before backup: ${reason}`));
+    return { report, reportPath: await writeReport(report) };
+  }
+  const backup = await createBackup(mainPath);
+  report.metrics.backupCreated = true;
+  report.findings.backup = { path: redactPath(backup.path), manifest: redactPath(backup.manifestPath) };
+  const beforeMutation = await runPreflight(mainPath);
+  report.blockedReasons.push(...await targetDirectoryBlockers(mainPath));
+  report.blockedReasons.push(
+    ...compareTargetIdentities(preflightResult.findings.targetState, beforeMutation.findings.targetState, {
+      allowSidecarSizeMtimeChange: false
+    })
+  );
+  if (report.blockedReasons.length > 0) {
+    report.status = "blocked";
+    return { report, reportPath: await writeReport(report) };
+  }
+  if (beforeMutation.blockers.length > 0) {
+    report.status = "blocked";
+    report.blockedReasons.push(...beforeMutation.blockers.map((reason) => `before mutation: ${reason}`));
+    return { report, reportPath: await writeReport(report) };
+  }
+  const beforeWalBytes = preflightResult.findings.targetState?.wal?.size ?? 0;
+  const sqlite = await trustedCommandPath("sqlite3");
+  const dbUri = createSqliteUri(mainPath, "rw");
+  try {
+    report.metrics.checkpointAttempted = true;
+    await runCheckpoint(sqlite, dbUri);
+    await runCheckpoint(sqlite, dbUri);
+  } catch (error) {
+    report.status = "blocked";
+    report.blockedReasons.push(error instanceof Error ? error.message : String(error));
+    return { report, reportPath: await writeReport(report) };
+  }
+  const postMutation = await runPreflight(mainPath);
+  report.blockedReasons.push(
+    ...compareTargetIdentities(beforeMutation.findings.targetState, postMutation.findings.targetState, {
+      allowMainSizeMtimeChange: true,
+      allowSidecarSizeMtimeChange: true
+    })
+  );
+  if (report.blockedReasons.length > 0) {
+    report.status = "blocked";
+    return { report, reportPath: await writeReport(report) };
+  }
+  if (postMutation.blockers.length > 0) {
+    report.status = "blocked";
+    report.blockedReasons.push(...postMutation.blockers.map((reason) => `after mutation: ${reason}`));
+    return { report, reportPath: await writeReport(report) };
+  }
+  const postflight = await runPreflight(mainPath);
+  if (postflight.blockers.length > 0) {
+    report.status = "blocked";
+    report.blockedReasons.push(...postflight.blockers);
+  } else {
+    report.status = "ok";
+  }
+  const afterWalBytes = postflight.findings.targetState?.wal?.size ?? 0;
+  if (afterWalBytes > 0) {
+    report.status = "blocked";
+    report.blockedReasons.push("WAL was not truncated");
+  }
+  report.metrics.beforeWalBytes = beforeWalBytes;
+  report.metrics.afterWalBytes = afterWalBytes;
+  report.metrics.reclaimedBytes = Math.max(0, Number(beforeWalBytes) - Number(afterWalBytes));
+  report.metrics.mainDbForcedShrink = false;
+  report.nextSafeAction = "Review the before/after metrics in the saved report.";
+  return { report, reportPath: await writeReport(report) };
+}
+async function runPreflight(mainPath) {
+  const blockers = [];
+  const targetState = await detectTargetState(mainPath);
+  blockers.push(...targetState.blockers);
+  const sqliteSupport = await checkSqliteJsonSupport();
+  if (!sqliteSupport.ok) blockers.push("sqlite3 JSON mode is unavailable");
+  const lsof = await checkOpenHandles(targetTriple(mainPath));
+  const knownProcess = await knownCodexProcessExists();
+  const safety = planFixSafety({
+    knownCodexProcessExists: knownProcess === true || knownProcess === "unknown",
+    anyOpenHandleOnTarget: lsof.openHandles,
+    lsofUsable: lsof.usable
+  });
+  blockers.push(...safety.reasons);
+  return {
+    blockers,
+    findings: {
+      targetState,
+      sqliteJson: sqliteSupport,
+      openHandles: lsof,
+      knownCodexProcessExists: knownProcess,
+      sqlite: {
+        available: false,
+        reason: "source database inspection is skipped in v1 to avoid copying private log bytes"
+      }
+    }
+  };
+}
+function redactPreflightFindings(findings) {
+  return {
+    ...findings,
+    targetState: safeTargetStateForReport(findings.targetState)
+  };
+}
+async function createBackup(mainPath) {
+  const backupDir = path6.join(appDataHome(), "backups");
+  await ensurePrivateDir(backupDir);
+  const workDir = await mkdtemp2(path6.join(backupDir, "backup-"));
+  await chmod2(workDir, 448);
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const backupPath = path6.join(workDir, `logs_2.sqlite.${stamp}.sqlite`);
+  const tmpPath = `${backupPath}.tmp`;
+  try {
+    const sqlite = await trustedCommandPath("sqlite3");
+    const vacuum = await runCommand(sqlite, ["-init", "/dev/null", createSqliteUri(mainPath, "ro"), `VACUUM INTO '${tmpPath.replaceAll("'", "''")}';`], {
+      timeoutMs: 6e4
+    });
+    if (vacuum.code !== 0) throw new Error("backup failed");
+    await chmod2(tmpPath, 384);
+    const inspection = await inspectSqliteSnapshot(tmpPath);
+    if (inspection.quickCheck !== "ok") throw new Error("backup quick_check failed");
+    if (!inspection.recognizedSchema) throw new Error("backup schema is unsupported");
+    await rename(tmpPath, backupPath);
+    const manifestPath = `${backupPath}.manifest.json`;
+    await writeFile2(
+      manifestPath,
+      `${JSON.stringify(
+        {
+          toolVersion: TOOL_VERSION,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          sourcePath: redactPath(mainPath),
+          backupPath: redactPath(backupPath),
+          inspection
+        },
+        null,
+        2
+      )}
+`,
+      { mode: 384, flag: "wx" }
+    );
+    await chmod2(manifestPath, 384);
+    return { path: backupPath, manifestPath };
+  } catch (error) {
+    await rm2(workDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function targetDirectoryBlockers(mainPath) {
+  const startDir = path6.dirname(mainPath);
+  const stopDir = path6.dirname(startDir);
+  const blockers = await assertDirectoryChainSafe(startDir, stopDir).catch((error) => [
+    error instanceof Error ? error.message : String(error)
+  ]);
+  return blockers.map(redactPath);
+}
+async function runCheckpoint(sqlite, dbUri) {
+  const checkpoint = await runCommand(sqlite, [
+    "-json",
+    "-init",
+    "/dev/null",
+    dbUri,
+    "PRAGMA busy_timeout=0; PRAGMA wal_checkpoint(TRUNCATE);"
+  ]);
+  if (checkpoint.code !== 0 || checkpoint.stdoutTruncated || checkpoint.stderrTruncated) {
+    throw new Error("checkpoint failed");
+  }
+  const rows = JSON.parse(checkpoint.stdout || "[]");
+  if (!checkpointRowsAreComplete(rows)) {
+    throw new Error("checkpoint busy");
+  }
+}
+function checkpointRowsAreComplete(rows) {
+  return rows.length === 1 && typeof rows[0]?.busy === "number" && typeof rows[0]?.log === "number" && typeof rows[0]?.checkpointed === "number" && Number.isFinite(rows[0].busy) && Number.isFinite(rows[0].log) && Number.isFinite(rows[0].checkpointed) && rows[0].busy === 0 && rows[0].log === rows[0].checkpointed;
+}
+function baseFixReport(generatedAt) {
+  return {
+    schemaVersion: REPORT_SCHEMA_VERSION,
+    toolVersion: TOOL_VERSION,
+    generatedAt,
+    command: "fix --safe",
+    status: "partial",
+    redacted: true,
+    target: {
+      kind: "default-codex-log-db",
+      pathCategory: "<home>/.codex/logs_2.sqlite"
+    },
+    findings: {},
+    metrics: {},
+    blockedReasons: []
+  };
+}
+
+// src/restore.ts
+import path7 from "path";
+import { realpath as realpath2 } from "fs/promises";
+async function validateRestoreBackup(backupPath) {
+  const backupRoot = path7.join(appDataHome(), "backups");
+  const rootBlockers = await assertExistingPrivateDirSafe(backupRoot);
+  if (rootBlockers.length > 0) return invalidRestoreResult(rootBlockers.join("; "));
+  const [backupRootReal, backupReal] = await Promise.all([
+    realpath2(backupRoot),
+    realpath2(backupPath)
+  ]).catch(() => [void 0, void 0]);
+  if (!backupRootReal || !backupReal || !isInsideDirectory(backupReal, backupRootReal)) {
+    return invalidRestoreResult("backup is outside the tool backup directory");
+  }
+  const beforeBlockers = await assertSafeReadablePrivateFile(backupPath, "backup file");
+  if (beforeBlockers.length > 0) return invalidRestoreResult(beforeBlockers.join("; "));
+  const beforeIdentity = await collectFileIdentity(backupPath, "backup file");
+  const inspection = await inspectSqliteSnapshot(backupPath);
+  const afterBlockers = await assertSafeReadablePrivateFile(backupPath, "backup file");
+  if (afterBlockers.length > 0) return invalidRestoreResult("backup file changed during validation");
+  const afterIdentity = await collectFileIdentity(backupPath, "backup file");
+  if (!sameBackupIdentity(beforeIdentity, afterIdentity)) return invalidRestoreResult("backup file changed during validation");
+  return {
+    valid: inspection.quickCheck === "ok" && inspection.recognizedSchema,
+    inspection,
+    warnings: [
+      "Validation only. This command does not restore anything.",
+      "Do not move, copy, or replace database files unless following a recovery guide.",
+      "Ask for help before manual restore if you are not comfortable with SQLite files."
+    ]
+  };
+}
+function invalidRestoreResult(reason) {
+  return {
+    valid: false,
+    reason,
+    warnings: [
+      "Validation only. This command does not restore anything.",
+      "Do not move, copy, or replace database files unless following a recovery guide.",
+      "Ask for help before manual restore if you are not comfortable with SQLite files."
+    ]
+  };
+}
+function isInsideDirectory(candidate, root) {
+  return candidate === root || candidate.startsWith(`${root}${path7.sep}`);
+}
+function sameBackupIdentity(before, after) {
+  return before.exists === after.exists && before.regularFile === after.regularFile && before.symbolicLink === after.symbolicLink && before.dev === after.dev && before.ino === after.ino && before.nlink === after.nlink && before.mode === after.mode && before.uid === after.uid && before.gid === after.gid && before.size === after.size && before.mtimeMs === after.mtimeMs;
+}
+
+// src/cli.ts
+async function runCli(argv = process.argv.slice(2)) {
+  const [command = "doctor", ...args] = argv;
+  const json = args.includes("--json");
+  const showPaths = args.includes("--show-paths");
+  if (command === "doctor") {
+    const flagError = unknownFlagError(args, /* @__PURE__ */ new Set(["--json", "--show-paths"]), "doctor");
+    if (flagError) return { exitCode: 2, output: flagError };
+    const { report, reportPath } = await runDoctor({ json, showPaths });
+    const outputReport = sanitizeReportForOutput(report);
+    return {
+      exitCode: report.status === "unsupported" ? 2 : 0,
+      output: json ? `${JSON.stringify(outputReport, null, 2)}
+` : renderReport(outputReport, reportPath, showPaths)
+    };
+  }
+  if (command === "fix" && args.includes("--safe")) {
+    const confirmationError = fixSafeConfirmationError(args);
+    if (confirmationError) return { exitCode: 2, output: confirmationError };
+    const { report, reportPath } = await runFixSafe();
+    const outputReport = sanitizeReportForOutput(report);
+    const exitCode = report.status === "ok" ? 0 : 3;
+    return { exitCode, output: renderReport(outputReport, reportPath, showPaths) };
+  }
+  if (command === "report" && args.includes("--latest")) {
+    const flagError = unknownFlagError(args, /* @__PURE__ */ new Set(["--latest", "--show-paths", "--unredacted"]), "report");
+    if (flagError) return { exitCode: 2, output: flagError };
+    if (args.includes("--unredacted")) {
+      return { exitCode: 2, output: "--unredacted is not supported in v1.\n" };
+    }
+    const latest = await latestReport();
+    if (!latest) return { exitCode: 1, output: "No report found.\n" };
+    const includePath = args.includes("--show-paths");
+    const payload = latest.report;
+    const pathLine = includePath ? `Report: ${redactPath(latest.path)}
+` : "";
+    return { exitCode: 0, output: includePath ? `${pathLine}${JSON.stringify(payload, null, 2)}
+` : renderReport(latest.report, latest.path) };
+  }
+  if (command === "restore" && args[0] === "validate") {
+    const flagError = unknownFlagError(args.slice(1), /* @__PURE__ */ new Set(["--backup"]), "restore validate");
+    if (flagError) return { exitCode: 2, output: flagError };
+    const backup = args[args.indexOf("--backup") + 1];
+    if (!backup || backup === args[0]) return { exitCode: 2, output: "Missing --backup <path>.\n" };
+    const result = await validateRestoreBackup(backup);
+    return { exitCode: result.valid ? 0 : 3, output: `${JSON.stringify(result, null, 2)}
+` };
+  }
+  return {
+    exitCode: 2,
+    output: usageText()
+  };
+}
+function renderReport(report, reportPath, showPaths = false) {
+  const lines = [
+    `Status: ${report.status}`,
+    `Safe to run fix --safe --yes: ${safeToRunFix(report) ? "yes" : "no"}`,
+    `What changed: ${whatChanged(report)}`,
+    `Target: ${report.target.pathCategory}`,
+    `Blocked reasons: ${report.blockedReasons.length === 0 ? "none" : report.blockedReasons.join("; ")}`
+  ];
+  if (report.metrics.reclaimedBytes !== void 0) {
+    lines.push(`Reclaimed bytes: ${report.metrics.reclaimedBytes}`);
+  }
+  if (report.nextSafeAction) lines.push(`Next safe action: ${report.nextSafeAction}`);
+  if (reportPath) {
+    const reportLocation = showPaths ? redactPath(reportPath) : redactPath(reportPath);
+    lines.push(`Report saved: ${reportLocation}`);
+    lines.push(`Review with: npm exec --ignore-scripts ai-dev-maintenance@${TOOL_VERSION} -- report --latest`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function fixSafeConfirmationError(args) {
+  const allowed = /* @__PURE__ */ new Set(["--safe", "--yes"]);
+  const unknown = args.filter((arg) => arg.startsWith("-") && !allowed.has(arg));
+  if (unknown.length > 0) return `Unknown fix flag: ${unknown.join(", ")}
+${usageText()}`;
+  if (args.includes("--yes")) return void 0;
+  return [
+    "Missing required confirmation: --yes",
+    "This creates a private local backup that may contain Codex log data, then cleans SQLite WAL storage.",
+    "It will not upload data, print log contents, delete logs, or rewrite session history.",
+    "Run again only after reviewing doctor output:",
+    `npm exec --ignore-scripts ai-dev-maintenance@${TOOL_VERSION} -- fix --safe --yes`
+  ].join("\n") + "\n";
+}
+function unknownFlagError(args, allowed, command) {
+  const unknown = args.filter((arg) => arg.startsWith("-") && !allowed.has(arg));
+  return unknown.length > 0 ? `Unknown ${command} flag: ${unknown.join(", ")}
+${usageText()}` : void 0;
+}
+function usageText() {
+  return [
+    "Usage:",
+    "  ai-dev-maintenance doctor [--json] [--show-paths]",
+    "  ai-dev-maintenance fix --safe --yes",
+    "  ai-dev-maintenance report --latest [--show-paths]",
+    "  ai-dev-maintenance restore validate --backup <path>"
+  ].join("\n") + "\n";
+}
+function safeToRunFix(report) {
+  if (report.command !== "doctor") return false;
+  if (report.status !== "ok" || report.blockedReasons.length > 0) return false;
+  const findings = report.findings;
+  const openHandles = findings.openHandles;
+  if (openHandles && (!openHandles.usable || openHandles.openHandles)) return false;
+  if (findings.knownCodexProcessExists !== false) return false;
+  return true;
+}
+function whatChanged(report) {
+  if (report.command === "doctor") return "redacted report only";
+  if (report.command === "fix --safe" && report.status === "ok") return "private backup + WAL cleanup";
+  if (report.command === "fix --safe" && report.metrics.backupCreated && report.metrics.checkpointAttempted) {
+    return "private backup created + checkpoint attempted; review report";
+  }
+  if (report.command === "fix --safe" && report.metrics.backupCreated) return "private backup created; fix was blocked";
+  if (report.command === "fix --safe") return "nothing; fix was blocked";
+  return "nothing";
+}
+function isDirectCliInvocation(moduleUrl, argv1) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argv1);
+  } catch {
+    return false;
+  }
+}
+if (isDirectCliInvocation(import.meta.url, process.argv[1])) {
+  runCli().then((result) => {
+    process.stdout.write(result.output);
+    process.exitCode = result.exitCode;
+  }).catch((error) => {
+    process.stderr.write(formatCliError(error));
+    process.exitCode = 1;
+  });
+}
+function formatCliError(error) {
+  return `${redactPath(error instanceof Error ? error.message : String(error))}
+`;
+}
+export {
+  fixSafeConfirmationError,
+  formatCliError,
+  isDirectCliInvocation,
+  renderReport,
+  runCli
+};