UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

359 lines (335 loc) • 13.7 kB
import { rmSync } from "node:fs"; import { join } from "node:path"; import { resolveCodexHomeDir } from "../../codex/home"; import { discoverRuntimeDbPaths, probeStateDbWritable } from "./db"; import { createExclusiveStageDir, normalizeArchivedRolloutPath, writePrivateFile } from "./paths"; import { collectRestorePendingAcceptedDestRels } from "./pending"; import { candidateOverlapsPendingRestore, clampPercent, computeExactPreviewDigest, computePreviewDigest, listArchivedCandidates, previewArchivedCleanup, previewExactArchivedCleanup, resolveExactArchivedCandidates, selectOldestPercent } from "./preview"; import { loadThreadsForCleanup, reconcileDeletedThreads } from "./reconcile"; import type { ThreadSnapshot } from "./reconcile"; import { purgeStaged, removeEmptyTrashRoot, removeStageIfEmpty, rollbackStaged, stageCandidates, trashRelPath } from "./staging"; import type { ArchivedCandidate, CleanupErrorCode, CleanupManifestEntry, CleanupMode, CleanupPreview, CleanupResult } from "./types"; export interface ExecuteCleanupOptions { percent: number; mode: CleanupMode; /** Required digest from preview; rejects when the candidate set drifted. */ digest: string; /** * Optional exact candidate set (logical relPaths). When set, selection bypasses * percent rounding and the digest must match `computeExactPreviewDigest`. */ candidateRelPaths?: string[]; codexHome?: string; /** Test-only: shrink busy_timeout so lock tests fail fast. */ busyTimeoutMs?: number; now?: number; /** Test-only failure injection for atomicity regressions. */ _test?: { failManifestWrite?: boolean; /** Observe the complete temp and prior destination before publication. Never serialized. */ beforeManifestReplace?: ( temporaryPath: string, targetPath: string, phase: "staging" | "pre-commit" | "purge-incomplete", ) => void; failPurgeBasenames?: string[]; failRollbackBasenames?: string[]; blockStageDestBasenames?: string[]; failAfterLogsMutation?: boolean; failAfterMemoriesMutation?: boolean; failAfterGoalsMutation?: boolean; failBeforeStateCommit?: boolean; failSatelliteRestore?: boolean; failSatelliteBackupWrite?: boolean; failSatelliteBackupReplace?: boolean; afterSatelliteMutations?: () => void; beforeReconcileLock?: () => void; }; } /** Serializable cleanup test hooks allowed on the management API wire. */ export type CleanupWireTestHooks = Omit< NonNullable<ExecuteCleanupOptions["_test"]>, "afterSatelliteMutations" | "beforeReconcileLock" | "beforeManifestReplace" >; function isStringArray(v: unknown): v is string[] { return Array.isArray(v) && v.every(e => typeof e === "string"); } /** Pick only allowlisted serializable hooks; drops all function hooks and unknown keys. */ export function pickWireCleanupTestHooks(raw: unknown): CleanupWireTestHooks | undefined { if (!raw || typeof raw !== "object") return undefined; const o = raw as Record<string, unknown>; const out: CleanupWireTestHooks = {}; if (typeof o.failManifestWrite === "boolean") out.failManifestWrite = o.failManifestWrite; if (isStringArray(o.failPurgeBasenames)) out.failPurgeBasenames = o.failPurgeBasenames; if (isStringArray(o.failRollbackBasenames)) out.failRollbackBasenames = o.failRollbackBasenames; if (isStringArray(o.blockStageDestBasenames)) out.blockStageDestBasenames = o.blockStageDestBasenames; if (typeof o.failAfterLogsMutation === "boolean") out.failAfterLogsMutation = o.failAfterLogsMutation; if (typeof o.failAfterMemoriesMutation === "boolean") out.failAfterMemoriesMutation = o.failAfterMemoriesMutation; if (typeof o.failAfterGoalsMutation === "boolean") out.failAfterGoalsMutation = o.failAfterGoalsMutation; if (typeof o.failBeforeStateCommit === "boolean") out.failBeforeStateCommit = o.failBeforeStateCommit; if (typeof o.failSatelliteRestore === "boolean") out.failSatelliteRestore = o.failSatelliteRestore; if (typeof o.failSatelliteBackupWrite === "boolean") out.failSatelliteBackupWrite = o.failSatelliteBackupWrite; if (typeof o.failSatelliteBackupReplace === "boolean") out.failSatelliteBackupReplace = o.failSatelliteBackupReplace; return Object.keys(out).length > 0 ? out : undefined; } function fail( mode: CleanupMode, percent: number, error: CleanupErrorCode, extra?: { trashDir?: string }, ): CleanupResult { return { ok: false, mode, percent, count: 0, bytes: 0, removedPaths: [], error, ...(extra?.trashDir ? { trashDir: extra.trashDir } : {}), }; } /** * Execute archived cleanup bound to a preview digest. * Stages every physical file, writes the recovery manifest, then commits DB deletes. * Rollback never deletes a stage directory that still holds unrestored files. */ export function executeArchivedCleanup(options: ExecuteCleanupOptions): CleanupResult { const codexHome = options.codexHome ?? resolveCodexHomeDir(); const mode = options.mode; const percent = clampPercent(options.percent); const busyTimeoutMs = options.busyTimeoutMs ?? 100; const failRollback = new Set(options._test?.failRollbackBasenames ?? []); const failPurge = new Set(options._test?.failPurgeBasenames ?? []); const blockStageDest = new Set(options._test?.blockStageDestBasenames ?? []); if (mode !== "quarantine" && mode !== "permanent") { return fail(mode, percent, "invalid_mode"); } if (typeof options.digest !== "string" || !/^[a-f0-9]{64}$/i.test(options.digest)) { return fail(mode, percent, "invalid_digest"); } let preview: CleanupPreview; let unfilteredSelected: ArchivedCandidate[]; if (options.candidateRelPaths !== undefined) { const selected = resolveExactArchivedCandidates(options.candidateRelPaths, codexHome); if (selected === null) { return fail(mode, percent, "stale_preview"); } unfilteredSelected = selected; preview = previewExactArchivedCleanup(selected, codexHome); } else { const all = listArchivedCandidates(codexHome); unfilteredSelected = selectOldestPercent(all, percent); preview = previewArchivedCleanup(percent, codexHome); } if (preview.digest.toLowerCase() !== options.digest.toLowerCase()) { const pendingDestRels = collectRestorePendingAcceptedDestRels(codexHome); const blocked = unfilteredSelected.filter(c => candidateOverlapsPendingRestore(c, pendingDestRels)); const unfilteredDigest = options.candidateRelPaths !== undefined ? computeExactPreviewDigest(unfilteredSelected) : computePreviewDigest(unfilteredSelected, percent); if ( unfilteredDigest.toLowerCase() === options.digest.toLowerCase() && blocked.length > 0 ) { return fail(mode, percent, "restore_pending_overlap"); } return fail(mode, percent, "stale_preview"); } const pendingDestRels = collectRestorePendingAcceptedDestRels(codexHome); if (preview.candidates.some(c => candidateOverlapsPendingRestore(c, pendingDestRels))) { return fail(mode, percent, "restore_pending_overlap"); } if (preview.candidates.length === 0) { return { ok: true, mode, percent, count: 0, bytes: 0, removedPaths: [], }; } const paths = discoverRuntimeDbPaths(codexHome); const probe = probeStateDbWritable(codexHome, busyTimeoutMs); if (!probe.ok) { return fail(mode, percent, probe.error); } // Preflight referenced-history / matching while DB is free, before any rename. const loaded = loadThreadsForCleanup(paths.state ?? "", preview.candidates, codexHome, busyTimeoutMs); if (!loaded.ok) { return fail(mode, percent, loaded.error); } const epoch = options.now ?? Date.now(); let stageDir: string; try { stageDir = createExclusiveStageDir(codexHome, epoch); } catch { return fail(mode, percent, "fs_failed"); } const trashDir = trashRelPath(codexHome, stageDir); const threadByRelPath = new Map<string, ThreadSnapshot>(); for (const thread of loaded.threads) { const normalized = normalizeArchivedRolloutPath(thread.rollout_path, codexHome); if (normalized) threadByRelPath.set(normalized, thread); } const skippedReferencedPaths = loaded.skipped .map(thread => normalizeArchivedRolloutPath(thread.rollout_path, codexHome)) .filter((path): path is string => path !== null); const matchedPaths = new Set([ ...threadByRelPath.keys(), ...skippedReferencedPaths, ]); const candidates = preview.candidates.filter(candidate => { return !matchedPaths.has(candidate.relPath) || threadByRelPath.has(candidate.relPath); }); if (candidates.length === 0) { removeStageIfEmpty(stageDir, []); removeEmptyTrashRoot(codexHome); return { ok: true, mode, percent, count: 0, bytes: 0, removedPaths: [], ...(skippedReferencedPaths.length ? { skippedReferencedPaths } : {}), }; } const manifestEntries: CleanupManifestEntry[] = candidates.map(candidate => { const thread = threadByRelPath.get(candidate.relPath); return { relPath: candidate.relPath, bytes: candidate.bytes, mtimeMs: candidate.mtimeMs, physicalRelPaths: candidate.physicalRelPaths, ...(thread ? { threadId: thread.id, rolloutPath: thread.rollout_path, archived: thread.archived } : {}), }; }); const writeManifest = (extra: Record<string, unknown> = {}) => { writePrivateFile( join(stageDir, "manifest.json"), JSON.stringify({ quarantinedAt: epoch, mode, percent, digest: preview.digest, entries: manifestEntries, ...extra, }, null, 2), (temporaryPath, targetPath) => options._test?.beforeManifestReplace?.( temporaryPath, targetPath, extra.staging ? "staging" : "pre-commit", ), ); }; // Journal staged paths before the first rename so a crash mid-stage is recoverable. try { if (options._test?.failManifestWrite) { throw new Error("test_fail_manifest_write"); } writeManifest({ staging: true }); } catch { removeStageIfEmpty(stageDir, []); return fail(mode, percent, "fs_failed"); } const stageResult = stageCandidates(codexHome, candidates, stageDir, { blockDestBasenames: blockStageDest.size > 0 ? blockStageDest : undefined, }); if (!stageResult.ok) { const rolled = rollbackStaged(stageResult.staged, { failBasenames: failRollback }); removeStageIfEmpty(stageDir, rolled.remaining); return fail(mode, percent, "fs_failed", rolled.restored ? undefined : { trashDir }); } // Final manifest before DB deletion so a mid-flight crash still has recovery metadata. try { writeManifest(); } catch { const rolled = rollbackStaged(stageResult.staged, { failBasenames: failRollback }); removeStageIfEmpty(stageDir, rolled.remaining); return fail(mode, percent, "fs_failed", rolled.restored ? undefined : { trashDir }); } const deleted = reconcileDeletedThreads( paths, candidates, codexHome, busyTimeoutMs, stageDir, options._test, ); if (!deleted.ok) { const rolled = rollbackStaged(stageResult.staged, { failBasenames: failRollback }); // Keep the stage (and recovery manifest) when files or satellite DB rows remain unrestored. const keepTrash = Boolean(deleted.satelliteRestoreFailed) || !rolled.restored; if (!keepTrash) { removeStageIfEmpty(stageDir, rolled.remaining); removeEmptyTrashRoot(codexHome); } return fail(mode, percent, deleted.error, keepTrash ? { trashDir } : undefined); } const removedPaths = candidates.map(c => c.relPath); const bytes = candidates.reduce((sum, c) => sum + c.bytes, 0); if (mode === "quarantine") { return { ok: true, mode, percent, count: removedPaths.length, bytes, trashDir, removedPaths, ...(skippedReferencedPaths.length ? { skippedReferencedPaths } : {}), }; } // Permanent: purge staged files only after a successful DB commit. const purge = purgeStaged(stageResult.staged, { failBasenames: failPurge }); if (purge.remaining.length > 0) { // Overwrite the pre-commit manifest so recovery reflects what actually survived. const survivingRelPaths = new Set(purge.remaining.map(item => item.relPath)); try { writePrivateFile( join(stageDir, "manifest.json"), JSON.stringify({ quarantinedAt: epoch, mode: "permanent", percent, digest: preview.digest, purgeIncomplete: true, purgedRelPaths: purge.purged.map(item => item.relPath), entries: manifestEntries .map(entry => ({ ...entry, physicalRelPaths: entry.physicalRelPaths.filter(rel => survivingRelPaths.has(rel)), })) .filter(entry => entry.physicalRelPaths.length > 0), }, null, 2), (temporaryPath, targetPath) => options._test?.beforeManifestReplace?.( temporaryPath, targetPath, "purge-incomplete", ), ); } catch { /* best-effort: the pre-commit manifest is still on disk */ } return { ok: false, mode, percent, count: 0, bytes: 0, trashDir, removedPaths: [], error: "fs_failed", }; } try { rmSync(stageDir, { recursive: true, force: true }); } catch { /* empty dir */ } // Drop an empty `.trash` root so permanent cleanup leaves no quarantine tree behind. removeEmptyTrashRoot(codexHome); return { ok: true, mode, percent, count: removedPaths.length, bytes, removedPaths, ...(skippedReferencedPaths.length ? { skippedReferencedPaths } : {}), }; }