feat(core): legacy global file cleanup mechanism (T304)

kryptobaseddev · claude · kryptobaseddev · commit bc0cfe50538a · 2026-04-07T20:56:10.000-07:00
T304 — Wave 1 of T299 v2026.4.11 epic. Implements ADR-036's
"legacy global file cleanup" section.

New cleanup-legacy.ts with detectAndRemoveLegacyGlobalFiles() — idempotent
one-shot cleanup of workspace.db + workspace.db.bak-pre-rename +
workspace.db-shm + workspace.db-shm-wal + nexus-pre-cleo.db.bak at
$XDG_DATA_HOME/cleo/.

- 6 unit tests covering all-present, no-op, partial, no-spurious-deletions,
  idempotent, error-capture
- Wired into packages/cleo/src/cli/index.ts global init (non-blocking)
- Exported via packages/core/src/internal.ts

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/cleo/src/cli/index.ts b/packages/cleo/src/cli/index.ts
@@ -9,6 +9,7 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { detectAndRemoveLegacyGlobalFiles } from '@cleocode/core/internal';
 import { type CommandDef, defineCommand, runMain, showUsage } from 'citty';
 import { ShimCommand } from './commander-shim.js';
 import { resolveFieldContext, setFieldContext } from './field-context.js';
@@ -375,6 +376,15 @@ for (const shim of rootShim._subcommands) {
   }
   setFieldContext(fieldResolution);
 
+  // One-shot idempotent cleanup of legacy global-tier files (T304 / ADR-036).
+  // Runs non-blocking on every invocation; errors are swallowed so that stale
+  // files never prevent normal command execution.
+  try {
+    detectAndRemoveLegacyGlobalFiles();
+  } catch {
+    // Non-fatal: legacy cleanup must never break the CLI startup path.
+  }
+
   // Handle -V as alias for --version (citty handles --version but not -V)
   // Must come after format context is set so output respects --json/--human
   if (argv[0] === '-V') {
diff --git a/packages/core/src/internal.ts b/packages/core/src/internal.ts
@@ -411,6 +411,8 @@ export type { CreateStickyParams, ListStickiesParams, StickyNote } from './stick
 // Store
 export { createBackup, listBackups, restoreFromBackup } from './store/backup.js';
 export { getBrainDb, getBrainNativeDb } from './store/brain-sqlite.js';
+export type { LegacyCleanupResult } from './store/cleanup-legacy.js';
+export { detectAndRemoveLegacyGlobalFiles } from './store/cleanup-legacy.js';
 export {
   gitCheckpoint,
   gitCheckpointStatus,
diff --git a/packages/core/src/store/__tests__/cleanup-legacy.test.ts b/packages/core/src/store/__tests__/cleanup-legacy.test.ts
@@ -0,0 +1,174 @@
+/**
+ * Unit tests for detectAndRemoveLegacyGlobalFiles().
+ *
+ * All filesystem interactions occur inside a fresh tmp directory per test.
+ * The `cleoHomeOverride` parameter is used instead of mocking `getCleoHome()`
+ * to keep tests hermetic and avoid global module state side-effects.
+ *
+ * @task T304
+ * @epic T299
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { detectAndRemoveLegacyGlobalFiles } from '../cleanup-legacy.js';
+
+// ---------------------------------------------------------------------------
+// Logger mock — prevents pino from trying to open real log files during tests
+// ---------------------------------------------------------------------------
+
+vi.mock('../../logger.js', () => ({
+  getLogger: () => ({
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  }),
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const LEGACY_NAMES = [
+  'workspace.db',
+  'workspace.db.bak-pre-rename',
+  'workspace.db-shm',
+  'workspace.db-shm-wal',
+  'nexus-pre-cleo.db.bak',
+] as const;
+
+const LIVE_NAMES = ['nexus.db', 'signaldock.db', 'machine-key', 'config.json'] as const;
+
+function createTmpHome(): string {
+  return mkdtempSync(join(tmpdir(), 'cleo-cleanup-test-'));
+}
+
+function touchFile(dir: string, name: string): string {
+  const fullPath = join(dir, name);
+  writeFileSync(fullPath, 'placeholder');
+  return fullPath;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('detectAndRemoveLegacyGlobalFiles', () => {
+  let tmpHome: string;
+
+  beforeEach(() => {
+    tmpHome = createTmpHome();
+  });
+
+  afterEach(() => {
+    rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  it('deletes all legacy files when all are present', () => {
+    // Create every legacy file
+    for (const name of LEGACY_NAMES) {
+      touchFile(tmpHome, name);
+    }
+
+    const result = detectAndRemoveLegacyGlobalFiles(tmpHome);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.removed).toHaveLength(LEGACY_NAMES.length);
+
+    for (const name of LEGACY_NAMES) {
+      expect(result.removed).toContain(name);
+      expect(existsSync(join(tmpHome, name))).toBe(false);
+    }
+  });
+
+  it('is a no-op when no legacy files are present', () => {
+    // Empty directory — no legacy files
+    const result = detectAndRemoveLegacyGlobalFiles(tmpHome);
+
+    expect(result.removed).toHaveLength(0);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('deletes only the files that exist when a partial set is present', () => {
+    const presentFiles = ['workspace.db', 'nexus-pre-cleo.db.bak'] as const;
+    const absentFiles = LEGACY_NAMES.filter(
+      (n) => !(presentFiles as readonly string[]).includes(n),
+    );
+
+    for (const name of presentFiles) {
+      touchFile(tmpHome, name);
+    }
+
+    const result = detectAndRemoveLegacyGlobalFiles(tmpHome);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.removed).toHaveLength(presentFiles.length);
+
+    for (const name of presentFiles) {
+      expect(result.removed).toContain(name);
+      expect(existsSync(join(tmpHome, name))).toBe(false);
+    }
+
+    for (const name of absentFiles) {
+      expect(result.removed).not.toContain(name);
+    }
+  });
+
+  it('does not touch live DB files or other non-legacy files', () => {
+    // Create all legacy files AND all live files
+    for (const name of LEGACY_NAMES) {
+      touchFile(tmpHome, name);
+    }
+    for (const name of LIVE_NAMES) {
+      touchFile(tmpHome, name);
+    }
+    // Create an extra unrelated file
+    touchFile(tmpHome, 'some-other.txt');
+
+    detectAndRemoveLegacyGlobalFiles(tmpHome);
+
+    // Live files must still exist
+    for (const name of LIVE_NAMES) {
+      expect(existsSync(join(tmpHome, name))).toBe(true);
+    }
+    // Extra file must still exist
+    expect(existsSync(join(tmpHome, 'some-other.txt'))).toBe(true);
+  });
+
+  it('is idempotent: second call returns empty removed array', () => {
+    for (const name of LEGACY_NAMES) {
+      touchFile(tmpHome, name);
+    }
+
+    const first = detectAndRemoveLegacyGlobalFiles(tmpHome);
+    expect(first.removed).toHaveLength(LEGACY_NAMES.length);
+    expect(first.errors).toHaveLength(0);
+
+    // Second call — files are already gone
+    const second = detectAndRemoveLegacyGlobalFiles(tmpHome);
+    expect(second.removed).toHaveLength(0);
+    expect(second.errors).toHaveLength(0);
+  });
+
+  it('captures errors for files that cannot be deleted and continues', () => {
+    // Create a directory with the legacy name to simulate an undeletable entry
+    // (fs.unlinkSync on a directory throws EISDIR)
+    const problemName = 'workspace.db';
+    mkdirSync(join(tmpHome, problemName));
+    // Also create a normal deletable legacy file
+    touchFile(tmpHome, 'nexus-pre-cleo.db.bak');
+
+    const result = detectAndRemoveLegacyGlobalFiles(tmpHome);
+
+    // The directory-disguised file should appear in errors
+    const errorFiles = result.errors.map((e) => e.file);
+    expect(errorFiles).toContain(problemName);
+
+    // The normal file should still be removed
+    expect(result.removed).toContain('nexus-pre-cleo.db.bak');
+    expect(existsSync(join(tmpHome, 'nexus-pre-cleo.db.bak'))).toBe(false);
+  });
+});
diff --git a/packages/core/src/store/cleanup-legacy.ts b/packages/core/src/store/cleanup-legacy.ts
@@ -0,0 +1,120 @@
+/**
+ * Idempotent one-shot cleanup of legacy global-tier files.
+ *
+ * Detects and removes stale files left at the global CLEO home directory
+ * (`getCleoHome()`) by pre-v2026.4.11 naming migrations. Safe to call on
+ * repeat invocations — existence-checks guard every deletion.
+ *
+ * Files targeted (see ADR-036 §Decision/Global-Tier table):
+ *   - workspace.db              (pre-nexus naming relic)
+ *   - workspace.db.bak-pre-rename  (safety copy from a long-landed rename)
+ *   - workspace.db-shm          (SQLite shared-memory sidecar of workspace.db)
+ *   - workspace.db-shm-wal      (SQLite WAL sidecar of workspace.db)
+ *   - nexus-pre-cleo.db.bak     (pre-CLEO backup of nexus — migration complete)
+ *
+ * Live files (nexus.db, signaldock.db, machine-key, config.json, etc.) are
+ * NEVER touched. The function only acts on the explicit LEGACY_FILES list.
+ *
+ * @task T304
+ * @epic T299
+ * @adr ADR-036
+ * @why v2026.4.10 left workspace.db and pre-cleo backups at global tier;
+ *   ADR-036 mandates their deletion to eliminate diagnostic confusion and
+ *   false impressions of active legacy databases.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLogger } from '../logger.js';
+import { getCleoHome } from '../paths.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Exhaustive list of legacy filenames that MUST be removed from the global
+ * CLEO home directory. No other files are touched.
+ *
+ * @task T304
+ */
+const LEGACY_FILES: readonly string[] = [
+  'workspace.db',
+  'workspace.db.bak-pre-rename',
+  'workspace.db-shm',
+  'workspace.db-shm-wal',
+  'nexus-pre-cleo.db.bak',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result returned by {@link detectAndRemoveLegacyGlobalFiles}. */
+export interface LegacyCleanupResult {
+  /** Filenames (basename only) that were successfully deleted. */
+  removed: string[];
+  /** Files that could not be deleted, with error messages. */
+  errors: Array<{ file: string; error: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect and remove legacy global-tier files from the CLEO home directory.
+ *
+ * Idempotent: safe to call when some or all files are already absent. Each
+ * file is individually existence-checked before attempting deletion. Failures
+ * on individual files are captured in `errors` rather than thrown, so the
+ * caller receives a complete picture of what was (and was not) cleaned up.
+ *
+ * Logs each successful deletion at `info` level and each failure at `warn`
+ * level via the shared pino logger.
+ *
+ * @param cleoHomeOverride - Optional directory override for tests. When
+ *   omitted the canonical `getCleoHome()` path is used. Prefer passing this
+ *   parameter in test harnesses rather than mutating `CLEO_HOME` environment
+ *   variables, as it avoids global state contamination between test runs.
+ * @returns A {@link LegacyCleanupResult} describing what was removed and any
+ *   errors encountered.
+ *
+ * @example
+ * ```typescript
+ * // Production usage (runs against real global home)
+ * const result = detectAndRemoveLegacyGlobalFiles();
+ * if (result.removed.length > 0) {
+ *   // Legacy files were cleaned up
+ * }
+ *
+ * // Test usage (runs against tmp directory)
+ * const result = detectAndRemoveLegacyGlobalFiles('/tmp/fake-cleo-home');
+ * ```
+ *
+ * @task T304
+ * @epic T299
+ */
+export function detectAndRemoveLegacyGlobalFiles(cleoHomeOverride?: string): LegacyCleanupResult {
+  const log = getLogger('cleanup-legacy');
+  const cleoHome = cleoHomeOverride ?? getCleoHome();
+  const removed: string[] = [];
+  const errors: Array<{ file: string; error: string }> = [];
+
+  for (const fileName of LEGACY_FILES) {
+    const fullPath = path.join(cleoHome, fileName);
+    try {
+      if (fs.existsSync(fullPath)) {
+        fs.unlinkSync(fullPath);
+        removed.push(fileName);
+        log.info({ file: fullPath }, 'Removed legacy global file');
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ file: fileName, error: message });
+      log.warn({ file: fullPath, error: message }, 'Failed to remove legacy global file');
+    }
+  }
+
+  return { removed, errors };
+}
