feat(studio): run nitro scans in the background with cancel-re-attach and nightly auto-clean

src/lib/services/nitro-cleanup.test.ts

@@ -88,10 +88,20 @@ vi.mock("node:fs", async (orig) => {
 import {
 	autoCleanFakeNitros,
 	deleteNitroCleanupFiles,
+	getPersistedCleanupResult,
 	type NitroRepairProgress,
+	refreshScanCacheAfterMutation,
 	repairBrokenNitros,
 	scanFakeBrokenNitros,
 } from "@/lib/services/nitro-cleanup";
+import {
+	cancelActiveScan,
+	cancelScanSession,
+	NitroScanConflictError,
+	readScanSession,
+	runScanInBackground,
+	writeScanSession,
+} from "@/lib/services/nitro-scan-session";
 
 beforeEach(() => {
 	vi.clearAllMocks();
@@ -128,6 +138,49 @@ beforeEach(() => {
 	statFn.mockImplementation(async () => ({ size: 512, mtimeMs: 0 }));
 });
 
+/**
+ * File-backed state for the mocked `node:fs` promises: cache/session/history
+ * writes land in the map and subsequent reads/exists checks consult it, while
+ * binary reads (nitro bundles) fall back to placeholder bytes.
+ */
+function installFileState(
+	initial: Record<string, string> = {},
+): Map<string, string> {
+	const files = new Map<string, string>(Object.entries(initial));
+	readFileFn.mockImplementation(async (filePath: string) => {
+		const stored = files.get(filePath);
+		if (stored !== undefined) return stored;
+		return Buffer.from("nitro-data");
+	});
+	writeFileFn.mockImplementation(async (filePath: string, data: unknown) => {
+		files.set(
+			filePath,
+			Buffer.isBuffer(data) ? data.toString("utf-8") : String(data),
+		);
+	});
+	existsFn.mockImplementation((filePath: string) => files.has(filePath));
+	return files;
+}
+
+async function waitForSessionState(
+	expected: string,
+	timeoutMs = 2000,
+): Promise<Awaited<ReturnType<typeof readScanSession>>> {
+	const deadline = Date.now() + timeoutMs;
+	let session = await readScanSession();
+	while ((session?.state ?? null) !== expected && Date.now() < deadline) {
+		await new Promise((resolve) => setTimeout(resolve, 5));
+		session = await readScanSession();
+	}
+	return session;
+}
+
+/** Let a detached scan from the previous test settle before the next one. */
+async function settleDetachedScans(): Promise<void> {
+	cancelActiveScan();
+	await new Promise((resolve) => setTimeout(resolve, 20));
+}
+
 function mockReaddir(byDir: Record<string, string[]>): void {
 	readdirFn.mockImplementation(async (dir: string) => byDir[dir] ?? []);
 }
@@ -429,6 +482,166 @@ describe("autoCleanFakeNitros", () => {
 	});
 });
 
+describe("refreshScanCacheAfterMutation", () => {
+	it("drops removed files and recomputes digests so the cache stays valid", async () => {
+		const dirs = {
+			"nitro\u0000/assets/nitro": dirSignature(["chair.nitro", "ghost.nitro"]),
+			"swf\u0000/assets/swf": dirSignature([]),
+			"icon\u0000/assets/icons": dirSignature([]),
+		};
+		const files = installFileState({
+			"/var/www/atom-nexst/storage/nitro-cleanup/scan-cache.json":
+				JSON.stringify({
+					dirs,
+					result: {
+						fake: [
+							{
+								fileName: "ghost.nitro",
+								base: "ghost",
+								size: 500,
+								dirs: ["/assets/nitro"],
+								lastModified: 0,
+							},
+						],
+						broken: [],
+						orphanedSwf: [],
+						orphanedIcon: [],
+						total: 2,
+					},
+				}),
+		});
+		// The directory changed after the cached scan (ghost.nitro deleted).
+		readdirFn.mockImplementation(async (dir: string) =>
+			dir.endsWith("/nitro") ? ["chair.nitro"] : [],
+		);
+
+		await refreshScanCacheAfterMutation("nitro", ["ghost.nitro"], 1);
+
+		const written = JSON.parse(
+			files.get(
+				"/var/www/atom-nexst/storage/nitro-cleanup/scan-cache.json",
+			) as string,
+		) as {
+			dirs: Record<string, string>;
+			result: {
+				fake: Array<{ fileName: string }>;
+				broken: unknown[];
+				orphanedSwf: unknown[];
+				orphanedIcon: unknown[];
+				total: number;
+			};
+		};
+		expect(written.dirs["nitro\u0000/assets/nitro"]).toBe(
+			dirSignature(["chair.nitro"]),
+		);
+		expect(written.result.fake).toEqual([]);
+		expect(written.result.total).toBe(1);
+		// The persisted result is now the refreshed one.
+		await expect(getPersistedCleanupResult()).resolves.toMatchObject({
+			fake: [],
+			total: 1,
+		});
+	});
+
+	it("is a no-op when the file names list is empty or no cache exists", async () => {
+		installFileState({});
+		await refreshScanCacheAfterMutation("nitro", [], 0);
+		installFileState({});
+		await refreshScanCacheAfterMutation("nitro", ["ghost.nitro"], 1);
+		expect(writeFileFn).not.toHaveBeenCalled();
+	});
+});
+
+describe("scan aborting", () => {
+	it("throws an AbortError and skips the scan cache write when aborted", async () => {
+		const controller = new AbortController();
+		controller.abort();
+
+		await expect(
+			scanFakeBrokenNitros({ signal: controller.signal }),
+		).rejects.toMatchObject({ name: "AbortError" });
+		expect(writeFileFn).not.toHaveBeenCalled();
+		expect(readFileFn).not.toHaveBeenCalled();
+	});
+});
+
+describe("nitro-scan-session", () => {
+	it("runs a scan in the background and persists the done session", async () => {
+		await settleDetachedScans();
+		installFileState({});
+		readdirFn.mockImplementation(async (dir: string) =>
+			dir.endsWith("/nitro") ? ["chair.nitro"] : [],
+		);
+		parseNitroBundle.mockReturnValue({});
+		statFn.mockImplementation(async () => ({ size: 512, mtimeMs: 0 }));
+
+		const session = await runScanInBackground({ force: true });
+
+		expect(session.id).toBeTruthy();
+		const done = await waitForSessionState("done");
+		expect(done?.id).toBe(session.id);
+		expect(done?.total).toBe(1);
+		expect(done?.cached).toBe(false);
+	});
+
+	it("rejects a second scan while a fresh one is running (single-flight)", async () => {
+		await settleDetachedScans();
+		installFileState({});
+		readdirFn.mockImplementation(async (dir: string) =>
+			dir.endsWith("/nitro") ? ["chair.nitro"] : [],
+		);
+		parseNitroBundle.mockReturnValue({});
+
+		await runScanInBackground({ force: false });
+		await expect(runScanInBackground({ force: false })).rejects.toBeInstanceOf(
+			NitroScanConflictError,
+		);
+
+		await settleDetachedScans();
+	});
+
+	it("lets a stale running session be taken over (crashed process recovery)", async () => {
+		await settleDetachedScans();
+		installFileState({});
+		readdirFn.mockImplementation(async (dir: string) =>
+			dir.endsWith("/nitro") ? ["chair.nitro"] : [],
+		);
+		parseNitroBundle.mockReturnValue({});
+		const staleHourAgo = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+		await writeScanSession({
+			id: "stale-session",
+			state: "running",
+			startedAt: staleHourAgo,
+			updatedAt: staleHourAgo,
+			force: false,
+		});
+
+		const session = await runScanInBackground({ force: false });
+
+		expect(session.id).not.toBe("stale-session");
+		await expect(waitForSessionState("done")).resolves.toMatchObject({
+			id: session.id,
+		});
+	});
+
+	it("marks the session cancelled when the scan is aborted", async () => {
+		await settleDetachedScans();
+		installFileState({});
+		readdirFn.mockImplementation(async (dir: string) =>
+			dir.endsWith("/nitro") ? ["chair.nitro"] : [],
+		);
+		parseNitroBundle.mockReturnValue({});
+
+		const session = await runScanInBackground({ force: false });
+		const cancelled = await cancelScanSession();
+
+		expect(cancelled?.state).toBe("cancelled");
+		await expect(waitForSessionState("cancelled")).resolves.toMatchObject({
+			id: session.id,
+		});
+	});
+});
+
 describe("repairBrokenNitros", () => {
 	it("re-downloads valid bundles and writes them to every nitro dir", async () => {
 		getTargetsFn.mockResolvedValue({