@cleocode/core 2026.4.98 → 2026.4.99

package/src/gc/__tests__/state.test.ts

@@ -0,0 +1,169 @@
+/**
+ * GC State Tests (T735)
+ *
+ * Covers:
+ * - readGCState: returns default state when file missing
+ * - readGCState: merges missing fields with defaults on schema version bump
+ * - writeGCState: writes atomically via tmp+rename
+ * - patchGCState: merges patch over current state
+ *
+ * Uses real temp directories (mkdtemp). No mocked filesystem.
+ *
+ * @task T735
+ * @epic T726
+ */
+
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  DEFAULT_GC_STATE,
+  GC_STATE_SCHEMA_VERSION,
+  patchGCState,
+  readGCState,
+  writeGCState,
+} from '../state.js';
+
+describe('readGCState', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-gc-state-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns default state when file does not exist', async () => {
+    const nonExistentPath = join(tmpDir, 'nonexistent', 'gc-state.json');
+    const state = await readGCState(nonExistentPath);
+    expect(state).toEqual(DEFAULT_GC_STATE);
+  });
+
+  it('returns default state when file contains invalid JSON', async () => {
+    const statePath = join(tmpDir, 'gc-state.json');
+    await mkdir(tmpDir, { recursive: true });
+    // Write invalid JSON
+    await import('node:fs/promises').then((fs) =>
+      fs.writeFile(statePath, 'not valid json {{{', 'utf-8'),
+    );
+
+    const state = await readGCState(statePath);
+    expect(state).toEqual(DEFAULT_GC_STATE);
+  });
+
+  it('merges partial state with defaults (forward compatibility)', async () => {
+    const statePath = join(tmpDir, 'gc-state.json');
+    // Write a state with only some fields (simulates old schema version)
+    const partial = { schemaVersion: '1.0', lastRunAt: '2026-04-10T03:00:00.000Z' };
+    await import('node:fs/promises').then((fs) =>
+      fs.writeFile(statePath, JSON.stringify(partial), 'utf-8'),
+    );
+
+    const state = await readGCState(statePath);
+
+    // Explicitly set fields are preserved
+    expect(state.lastRunAt).toBe('2026-04-10T03:00:00.000Z');
+    // Missing fields default to the DEFAULT_GC_STATE values
+    expect(state.consecutiveFailures).toBe(0);
+    expect(state.escalationNeeded).toBe(false);
+    expect(state.daemonPid).toBeNull();
+  });
+});
+
+describe('writeGCState', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-gc-write-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates parent directories if they do not exist', async () => {
+    const statePath = join(tmpDir, 'nested', 'deep', 'gc-state.json');
+    await writeGCState(statePath, { ...DEFAULT_GC_STATE });
+
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.schemaVersion).toBe(GC_STATE_SCHEMA_VERSION);
+  });
+
+  it('writes valid JSON with correct schema version', async () => {
+    const statePath = join(tmpDir, 'gc-state.json');
+    const state = { ...DEFAULT_GC_STATE, daemonPid: 12345, lastRunAt: '2026-04-15T03:00:00Z' };
+
+    await writeGCState(statePath, state);
+
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.schemaVersion).toBe('1.0');
+    expect(parsed.daemonPid).toBe(12345);
+    expect(parsed.lastRunAt).toBe('2026-04-15T03:00:00Z');
+  });
+
+  it('overwrites existing state file', async () => {
+    const statePath = join(tmpDir, 'gc-state.json');
+    const initial = { ...DEFAULT_GC_STATE, consecutiveFailures: 1 };
+    await writeGCState(statePath, initial);
+
+    const updated = { ...DEFAULT_GC_STATE, consecutiveFailures: 0, lastRunAt: 'now' };
+    await writeGCState(statePath, updated);
+
+    const raw = await readFile(statePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.consecutiveFailures).toBe(0);
+    expect(parsed.lastRunAt).toBe('now');
+  });
+});
+
+describe('patchGCState', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-gc-patch-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates file with patch merged over defaults when file does not exist', async () => {
+    const statePath = join(tmpDir, 'gc-state.json');
+    const patched = await patchGCState(statePath, { daemonPid: 9999 });
+
+    expect(patched.daemonPid).toBe(9999);
+    // Other fields default
+    expect(patched.consecutiveFailures).toBe(0);
+    expect(patched.escalationNeeded).toBe(false);
+  });
+
+  it('preserves existing fields not in the patch', async () => {
+    const statePath = join(tmpDir, 'gc-state.json');
+    await writeGCState(statePath, { ...DEFAULT_GC_STATE, consecutiveFailures: 3, daemonPid: 100 });
+
+    const patched = await patchGCState(statePath, { escalationNeeded: true });
+
+    // Patched field updated
+    expect(patched.escalationNeeded).toBe(true);
+    // Unpatched fields preserved
+    expect(patched.consecutiveFailures).toBe(3);
+    expect(patched.daemonPid).toBe(100);
+  });
+
+  it('allows null to clear a field', async () => {
+    const statePath = join(tmpDir, 'gc-state.json');
+    await writeGCState(statePath, {
+      ...DEFAULT_GC_STATE,
+      pendingPrune: ['path/a', 'path/b'],
+    });
+
+    const patched = await patchGCState(statePath, { pendingPrune: null });
+    expect(patched.pendingPrune).toBeNull();
+  });
+});

package/src/gc/__tests__/transcript.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Transcript Lifecycle Tests (T735)
+ *
+ * Covers memory-architecture-spec.md §12.1 acceptance criteria:
+ * - TL-F5: prune --dry-run makes zero filesystem mutations
+ * - TL-F6: Budget cap triggers early prune when total size > threshold
+ * - TL-F7: API key absent falls back to 30d-only deletion
+ *
+ * Additional unit tests:
+ * - classifyTranscriptTier: correct hot/warm/cold at all boundary values
+ * - scanTranscripts: correct hot/warm counts for a known directory layout
+ * - pruneTranscripts: correct deletion with confirm=true
+ * - parseDurationMs: correct parsing of all supported formats
+ *
+ * Uses real temp directories (mkdtemp). No mocked filesystem.
+ *
+ * @task T735
+ * @epic T726
+ */
+
+import { mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+  classifyTranscriptTier,
+  parseDurationMs,
+  pruneTranscripts,
+  scanTranscripts,
+} from '../transcript.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a fake session JSONL under `projectsDir/<slug>/`.
+ * Sets the mtime to `now - ageMs` so tier classification works correctly.
+ */
+async function createSession(
+  projectsDir: string,
+  slug: string,
+  sessionId: string,
+  ageMs: number,
+): Promise<string> {
+  const slugDir = join(projectsDir, slug);
+  await mkdir(slugDir, { recursive: true });
+
+  const jsonlPath = join(slugDir, `${sessionId}.jsonl`);
+  await writeFile(jsonlPath, `{"type":"user","text":"session ${sessionId}"}\n`, 'utf-8');
+
+  // Back-date the mtime to simulate age
+  const pastDate = new Date(Date.now() - ageMs);
+  await utimes(jsonlPath, pastDate, pastDate);
+
+  return jsonlPath;
+}
+
+// ---------------------------------------------------------------------------
+// classifyTranscriptTier
+// ---------------------------------------------------------------------------
+
+describe('classifyTranscriptTier', () => {
+  it('returns hot for age < 24h', () => {
+    expect(classifyTranscriptTier(0)).toBe('hot');
+    expect(classifyTranscriptTier(1 * 60 * 60 * 1000)).toBe('hot'); // 1h
+    expect(classifyTranscriptTier(23 * 60 * 60 * 1000)).toBe('hot'); // 23h
+  });
+
+  it('returns warm for age 24h–7d', () => {
+    const ONE_DAY = 24 * 60 * 60 * 1000;
+    const SEVEN_DAYS = 7 * ONE_DAY;
+    expect(classifyTranscriptTier(ONE_DAY)).toBe('warm');
+    expect(classifyTranscriptTier(ONE_DAY + 1000)).toBe('warm'); // just past 24h
+    expect(classifyTranscriptTier(3 * ONE_DAY)).toBe('warm'); // 3 days
+    expect(classifyTranscriptTier(SEVEN_DAYS - 1000)).toBe('warm'); // just under 7d
+  });
+
+  it('returns cold for age >= 7d', () => {
+    const SEVEN_DAYS = 7 * 24 * 60 * 60 * 1000;
+    expect(classifyTranscriptTier(SEVEN_DAYS)).toBe('cold');
+    expect(classifyTranscriptTier(SEVEN_DAYS + 1000)).toBe('cold');
+    expect(classifyTranscriptTier(30 * 24 * 60 * 60 * 1000)).toBe('cold'); // 30d
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseDurationMs
+// ---------------------------------------------------------------------------
+
+describe('parseDurationMs', () => {
+  it('parses days correctly', () => {
+    expect(parseDurationMs('7d')).toBe(7 * 24 * 60 * 60 * 1000);
+    expect(parseDurationMs('1d')).toBe(24 * 60 * 60 * 1000);
+    expect(parseDurationMs('30d')).toBe(30 * 24 * 60 * 60 * 1000);
+  });
+
+  it('parses hours correctly', () => {
+    expect(parseDurationMs('24h')).toBe(24 * 60 * 60 * 1000);
+    expect(parseDurationMs('1h')).toBe(60 * 60 * 1000);
+    expect(parseDurationMs('168h')).toBe(168 * 60 * 60 * 1000);
+  });
+
+  it('parses minutes correctly', () => {
+    expect(parseDurationMs('30m')).toBe(30 * 60 * 1000);
+    expect(parseDurationMs('1m')).toBe(60 * 1000);
+  });
+
+  it('parses seconds correctly', () => {
+    expect(parseDurationMs('60s')).toBe(60 * 1000);
+  });
+
+  it('throws on invalid format', () => {
+    expect(() => parseDurationMs('invalid')).toThrow();
+    expect(() => parseDurationMs('7')).toThrow();
+    expect(() => parseDurationMs('')).toThrow();
+    expect(() => parseDurationMs('7w')).toThrow(); // weeks not supported
+  });
+});
+
+// ---------------------------------------------------------------------------
+// scanTranscripts — correct hot/warm counts
+// ---------------------------------------------------------------------------
+
+describe('scanTranscripts', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-scan-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns empty result when projects dir does not exist', async () => {
+    const result = await scanTranscripts(join(tmpDir, 'nonexistent'));
+    expect(result.totalSessions).toBe(0);
+    expect(result.hot).toHaveLength(0);
+    expect(result.warm).toHaveLength(0);
+  });
+
+  it('correctly identifies hot sessions (< 24h)', async () => {
+    // 1 hour old → hot
+    await createSession(projectsDir, 'proj', 'hot-session', 1 * 60 * 60 * 1000);
+
+    const result = await scanTranscripts(projectsDir);
+
+    expect(result.hot).toHaveLength(1);
+    expect(result.warm).toHaveLength(0);
+    expect(result.hot[0]?.sessionId).toBe('hot-session');
+    expect(result.hot[0]?.tier).toBe('hot');
+  });
+
+  it('correctly identifies warm sessions (1–7d)', async () => {
+    // 3 days old → warm
+    await createSession(projectsDir, 'proj', 'warm-session', 3 * 24 * 60 * 60 * 1000);
+
+    const result = await scanTranscripts(projectsDir);
+
+    expect(result.warm).toHaveLength(1);
+    expect(result.hot).toHaveLength(0);
+    expect(result.warm[0]?.sessionId).toBe('warm-session');
+    expect(result.warm[0]?.tier).toBe('warm');
+  });
+
+  it('cold sessions (>7d, already deleted) do not appear in scan', async () => {
+    // Create a file but COLD sessions should have already been deleted from disk
+    // We verify cold sessions don't appear in warm/hot lists
+    const result = await scanTranscripts(projectsDir);
+    // No sessions created yet → all empty
+    expect(result.totalSessions).toBe(0);
+  });
+
+  it('counts sessions across multiple projects', async () => {
+    await createSession(projectsDir, 'proj-a', 'session-1', 1 * 60 * 60 * 1000); // hot
+    await createSession(projectsDir, 'proj-a', 'session-2', 2 * 24 * 60 * 60 * 1000); // warm
+    await createSession(projectsDir, 'proj-b', 'session-3', 5 * 24 * 60 * 60 * 1000); // warm
+
+    const result = await scanTranscripts(projectsDir);
+
+    expect(result.totalSessions).toBe(3);
+    expect(result.hot).toHaveLength(1);
+    expect(result.warm).toHaveLength(2);
+  });
+
+  it('totalBytes is the sum of all session file sizes', async () => {
+    await createSession(projectsDir, 'proj', 'size-session', 1 * 60 * 60 * 1000);
+
+    const result = await scanTranscripts(projectsDir);
+    expect(result.totalBytes).toBeGreaterThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TL-F5: prune --dry-run makes zero filesystem mutations
+// ---------------------------------------------------------------------------
+
+describe('pruneTranscripts dry-run (TL-F5)', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-prune-dr-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('dry-run (confirm=false) makes zero filesystem mutations', async () => {
+    // Use 35d to be beyond the 30d API-key-absent circuit breaker minimum
+    const OLD_SESSION_AGE = 35 * 24 * 60 * 60 * 1000; // 35 days
+    const jsonlPath = await createSession(projectsDir, 'proj', 'old-session', OLD_SESSION_AGE);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000, // 7d threshold
+      confirm: false, // dry-run
+      projectsDir,
+    });
+
+    // File must still exist after dry-run
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined();
+
+    expect(result.dryRun).toBe(true);
+    expect(result.pruned).toBeGreaterThan(0);
+    expect(result.deletedPaths).toContain(jsonlPath);
+  });
+
+  it('dry-run reports correct byte count', async () => {
+    const content = 'x'.repeat(1024); // 1 KB
+    const slugDir = join(projectsDir, 'proj');
+    await mkdir(slugDir, { recursive: true });
+    const jsonlPath = join(slugDir, 'big-session.jsonl');
+    await writeFile(jsonlPath, content, 'utf-8');
+    // Use 35d to exceed the 30d API-key-absent circuit breaker minimum
+    const past = new Date(Date.now() - 35 * 24 * 60 * 60 * 1000);
+    await utimes(jsonlPath, past, past);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: false,
+      projectsDir,
+    });
+
+    expect(result.bytesFreed).toBeGreaterThanOrEqual(1024);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// pruneTranscripts with confirm=true (actual deletion)
+// ---------------------------------------------------------------------------
+
+describe('pruneTranscripts confirm=true', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-prune-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('deletes sessions older than the threshold', async () => {
+    // Use 35d to be beyond the 30d API-key-absent circuit breaker minimum
+    const OLD_AGE = 35 * 24 * 60 * 60 * 1000; // 35 days
+    const jsonlPath = await createSession(projectsDir, 'proj', 'old-del', OLD_AGE);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: true,
+      projectsDir,
+    });
+
+    // File must be gone
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).rejects.toThrow();
+
+    expect(result.dryRun).toBe(false);
+    expect(result.pruned).toBeGreaterThan(0);
+  });
+
+  it('does NOT delete sessions younger than the threshold', async () => {
+    const RECENT_AGE = 1 * 24 * 60 * 60 * 1000; // 1 day
+    const jsonlPath = await createSession(projectsDir, 'proj', 'recent-keep', RECENT_AGE);
+
+    await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: true,
+      projectsDir,
+    });
+
+    // Recent file must still exist
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TL-F7: ANTHROPIC_API_KEY absent → 30d-only deletion (circuit breaker)
+// ---------------------------------------------------------------------------
+
+describe('pruneTranscripts API key circuit breaker (TL-F7)', () => {
+  let tmpDir: string;
+  let projectsDir: string;
+  let savedApiKey: string | undefined;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'cleo-transcript-apikey-'));
+    projectsDir = join(tmpDir, 'projects');
+    await mkdir(projectsDir, { recursive: true });
+    // Save and clear API key
+    savedApiKey = process.env['ANTHROPIC_API_KEY'];
+    delete process.env['ANTHROPIC_API_KEY'];
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    // Restore API key
+    if (savedApiKey !== undefined) {
+      process.env['ANTHROPIC_API_KEY'] = savedApiKey;
+    }
+  });
+
+  it('skips deletion of sessions < 30d when API key is absent', async () => {
+    // 10-day-old session; caller requests 7d threshold
+    const TEN_DAYS = 10 * 24 * 60 * 60 * 1000;
+    const jsonlPath = await createSession(projectsDir, 'proj', 'apikey-test', TEN_DAYS);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000, // 7d requested
+      confirm: true,
+      projectsDir,
+    });
+
+    // Circuit breaker: no API key → 30d minimum. 10-day session is NOT deleted.
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).resolves.toBeUndefined();
+
+    expect(result.pruned).toBe(0);
+  });
+
+  it('allows deletion of sessions > 30d even without API key', async () => {
+    // 35-day-old session — beyond the 30d circuit-breaker minimum
+    const THIRTY_FIVE_DAYS = 35 * 24 * 60 * 60 * 1000;
+    const jsonlPath = await createSession(projectsDir, 'proj', 'old-apikey', THIRTY_FIVE_DAYS);
+
+    const result = await pruneTranscripts({
+      olderThanMs: 7 * 24 * 60 * 60 * 1000,
+      confirm: true,
+      projectsDir,
+    });
+
+    // 35-day session IS deleted (beyond 30d fallback minimum)
+    const { access } = await import('node:fs/promises');
+    await expect(access(jsonlPath)).rejects.toThrow();
+
+    expect(result.pruned).toBeGreaterThan(0);
+  });
+});

package/src/gc/daemon-entry.ts

@@ -0,0 +1,26 @@
+/**
+ * GC Daemon Entry Point — Standalone script executed by `spawnGCDaemon()`.
+ *
+ * This script is spawned as a detached background process by `cleo daemon start`.
+ * It must NOT import from the main CLI shim (no citty, no commander). It only
+ * imports from the gc/ module subtree.
+ *
+ * The cleoDir is passed as argv[2] by `spawnGCDaemon()`.
+ *
+ * @see gc/daemon.ts for the spawn logic
+ * @task T731
+ * @epic T726
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { bootstrapDaemon } from './daemon.js';
+
+const cleoDir = process.argv[2] ?? join(homedir(), '.cleo');
+
+bootstrapDaemon(cleoDir).catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  // stderr is redirected to gc.err by the parent spawn call
+  process.stderr.write(`[CLEO GC] Fatal daemon error: ${message}\n`);
+  process.exit(1);
+});