@cleocode/core 2026.4.9 → 2026.4.11

package/src/paths.ts

@@ -1,8 +1,14 @@
 /**
  * XDG-compliant path resolution for CLEO V2.
  *
+ * Global data directory is resolved via env-paths (XDG on Linux, platform
+ * conventions on macOS and Windows):
+ *   Linux:   ~/.local/share/cleo
+ *   macOS:   ~/Library/Application Support/cleo
+ *   Windows: %LOCALAPPDATA%\cleo
+ *
  * Environment variables:
- *   CLEO_HOME   - Global installation directory (default: ~/.cleo)
+ *   CLEO_HOME   - Override global installation directory
  *   CLEO_DIR    - Project data directory (default: .cleo)
  *
  * @epic T4454
@@ -12,6 +18,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from './errors.js';
 import { getPlatformPaths } from './system/platform-paths.js';
 
 /**
@@ -160,31 +168,100 @@ export function getCleoDirAbsolute(cwd?: string): string {
 }
 
 /**
- * Get the project root from the CLEO directory.
- * Respects CLEO_ROOT env var, then derives from CLEO_DIR.
- * If CLEO_DIR is ".cleo", the project root is its parent.
+ * Get the project root by walking ancestor directories for `.cleo/` or `.git/`.
+ *
+ * Stops at the **first** ancestor directory that contains either sentinel
+ * directory and never drifts past it — even when multiple nested projects
+ * exist above the starting directory.
+ *
+ * Resolution order:
+ *   1. `CLEO_ROOT` env var — bypasses walk entirely (CI / test override)
+ *   2. `CLEO_DIR` env var (absolute path only) — derives project root from dirname
+ *   3. Walk ancestors from `cwd` (or `process.cwd()`) toward filesystem root:
+ *      - `.cleo/` found → return that directory (project root)
+ *      - `.git/` found (without `.cleo/` sibling) → throw `E_NOT_INITIALIZED`
+ *   4. Filesystem root reached without either → throw `E_NO_PROJECT`
  *
- * @param cwd - Optional working directory hint
- * @returns Absolute path to the project root
+ * @param cwd - Optional starting directory; defaults to `process.cwd()`
+ * @returns Absolute path to the project root directory (parent of `.cleo/`)
+ * @throws {CleoError} `ExitCode.CONFIG_ERROR` (`E_NOT_INITIALIZED`) when a
+ *   `.git/` is found but no `.cleo/` is present at that level.
+ * @throws {CleoError} `ExitCode.NOT_FOUND` (`E_NO_PROJECT`) when neither
+ *   sentinel is found in any ancestor.
  *
  * @remarks
- * Resolution order: CLEO_ROOT env var (if no cwd), parent of the resolved
- * .cleo directory (if it ends with /.cleo), or the cwd/process.cwd() fallback.
+ * `CLEO_ROOT` is an absolute-path escape hatch for environments where the
+ * working directory is unrelated to the project (CI tmpdirs, monorepo scripts,
+ * test harnesses). When set it is returned as-is without scanning ancestors.
+ *
+ * `CLEO_DIR` set to an absolute path (e.g. `/project/.cleo`) also bypasses
+ * the walk: the project root is derived as its `dirname`. This preserves
+ * backward compatibility for test harnesses that use `CLEO_DIR` to pin the
+ * project root.
+ *
+ * NEVER auto-creates `.cleo/`. Project initialisation is an explicit opt-in
+ * via `cleo init`.
  *
  * @example
  * ```typescript
- * const root = getProjectRoot(); // "/home/user/projects/myapp"
+ * // Running from packages/core inside the monorepo:
+ * const root = getProjectRoot(); // "/mnt/projects/cleocode"
  * ```
  */
 export function getProjectRoot(cwd?: string): string {
-  if (!cwd && process.env['CLEO_ROOT']) {
+  // 1. Honour CLEO_ROOT env var — bypass walk entirely
+  if (process.env['CLEO_ROOT']) {
     return process.env['CLEO_ROOT'];
   }
-  const cleoDirAbs = getCleoDirAbsolute(cwd);
-  if (cleoDirAbs.endsWith('/.cleo') || cleoDirAbs.endsWith('\\.cleo')) {
-    return dirname(cleoDirAbs);
+
+  // 2. If CLEO_DIR is an absolute path, derive the project root from it.
+  //    This preserves backward compatibility for test harnesses that set
+  //    CLEO_DIR=/some/absolute/path/.cleo to pin the project root.
+  const cleoDirEnv = process.env['CLEO_DIR'];
+  if (cleoDirEnv && isAbsolutePath(cleoDirEnv)) {
+    if (cleoDirEnv.endsWith('/.cleo') || cleoDirEnv.endsWith('\\.cleo')) {
+      return dirname(cleoDirEnv);
+    }
+    return cleoDirEnv;
   }
-  return cwd ?? process.cwd();
+
+  const start = resolve(cwd ?? process.cwd());
+  let current = start;
+
+  // 2. Walk ancestors toward filesystem root
+  while (true) {
+    const cleoDir = join(current, '.cleo');
+    const gitDir = join(current, '.git');
+
+    if (existsSync(cleoDir)) {
+      // .cleo/ found — this is the project root
+      return current;
+    }
+
+    if (existsSync(gitDir)) {
+      // .git/ found but no .cleo/ sibling — not initialised
+      throw new CleoError(ExitCode.CONFIG_ERROR, `Run cleo init at ${current}`, {
+        fix: `cd ${current} && cleo init`,
+      });
+    }
+
+    // Move up one level
+    const parent = dirname(current);
+    if (parent === current) {
+      // Reached filesystem root without finding either sentinel
+      break;
+    }
+    current = parent;
+  }
+
+  // 3. No sentinel found in any ancestor
+  throw new CleoError(
+    ExitCode.NOT_FOUND,
+    'Not inside a CLEO project. Run cleo init or cd to an existing project',
+    {
+      fix: 'cleo init',
+    },
+  );
 }
 
 /**

package/src/scaffold.ts

@@ -77,18 +77,35 @@ export const REQUIRED_CLEO_SUBDIRS = [
   'adrs',
 ] as const;
 
-/** Embedded fallback for .cleo/.gitignore content (deny-by-default). */
+/**
+ * Embedded fallback for .cleo/.gitignore content (deny-by-default).
+ *
+ * Must stay in sync with `packages/core/templates/cleo-gitignore`. The
+ * template file is the source of truth; this constant is only used when
+ * the template file cannot be located at runtime (bundled binary edge
+ * cases, air-gapped installs, etc.).
+ *
+ * ADR-013 §9 (2026-04-07, T5158): config.json / project-info.json are
+ * NOT re-included here. Runtime state files (tasks.db, brain.db,
+ * config.json, project-info.json) are protected by explicit deny rules
+ * so that nested-.gitignore allow rules cannot unignore them at the
+ * project repository level.
+ */
 export const CLEO_GITIGNORE_FALLBACK = `# .cleo/.gitignore — Deny-by-default for CLEO project data
 # Ignore everything, then explicitly allow only tracked files.
+#
+# ADR-013 §9 (2026-04-07, T5158): config.json + project-info.json are
+# runtime snapshots regenerated by \`cleo init\`, not tracked in git.
+# Recovery for all four runtime files (tasks.db, brain.db, config.json,
+# project-info.json) is provided by \`cleo backup add\` snapshots under
+# .cleo/backups/. See .cleo/adrs/ADR-013 for the full recovery story.
 
 # Step 1: Ignore everything
 *
 
 # Allow list
 !.gitignore
-!config.json
 !project-context.json
-!project-info.json
 !setup-otel.sh
 !DATA-SAFETY-IMPLEMENTATION-SUMMARY.md
 !adrs/
@@ -103,6 +120,8 @@ export const CLEO_GITIGNORE_FALLBACK = `# .cleo/.gitignore — Deny-by-default f
 *.db-shm
 *.db-wal
 *.db-journal
+config.json
+project-info.json
 log.json
 bypass-log.json
 qa-log.json

package/src/store/__tests__/cleanup-legacy.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Unit tests for detectAndRemoveLegacyGlobalFiles() and
+ * detectAndRemoveStrayProjectNexus().
+ *
+ * All filesystem interactions occur inside a fresh tmp directory per test.
+ * The `cleoHomeOverride` / `projectRoot` parameters are used instead of
+ * mocking `getCleoHome()` to keep tests hermetic and avoid global module
+ * state side-effects.
+ *
+ * @task T304
+ * @task T307
+ * @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,
+  detectAndRemoveStrayProjectNexus,
+} 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);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// detectAndRemoveStrayProjectNexus (T307)
+// ---------------------------------------------------------------------------
+
+describe('detectAndRemoveStrayProjectNexus', () => {
+  let tmpProjectRoot: string;
+
+  beforeEach(() => {
+    // Create a fake project root with a .cleo sub-directory
+    tmpProjectRoot = mkdtempSync(join(tmpdir(), 'cleo-stray-nexus-test-'));
+    mkdirSync(join(tmpProjectRoot, '.cleo'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpProjectRoot, { recursive: true, force: true });
+  });
+
+  it('removes the stray nexus.db when it is present', () => {
+    const strayPath = join(tmpProjectRoot, '.cleo', 'nexus.db');
+    writeFileSync(strayPath, ''); // zero-byte stray (mirrors the real incident)
+
+    expect(existsSync(strayPath)).toBe(true);
+
+    const result = detectAndRemoveStrayProjectNexus(tmpProjectRoot);
+
+    expect(result.removed).toBe(true);
+    expect(result.path).toBe(strayPath);
+    expect(existsSync(strayPath)).toBe(false);
+  });
+
+  it('is a no-op when no stray nexus.db is present', () => {
+    const strayPath = join(tmpProjectRoot, '.cleo', 'nexus.db');
+
+    // Sanity: file does not exist
+    expect(existsSync(strayPath)).toBe(false);
+
+    const result = detectAndRemoveStrayProjectNexus(tmpProjectRoot);
+
+    expect(result.removed).toBe(false);
+    expect(result.path).toBe(strayPath);
+    // Still does not exist
+    expect(existsSync(strayPath)).toBe(false);
+  });
+
+  it('is idempotent: second call is a no-op after first removed the file', () => {
+    const strayPath = join(tmpProjectRoot, '.cleo', 'nexus.db');
+    writeFileSync(strayPath, '');
+
+    const first = detectAndRemoveStrayProjectNexus(tmpProjectRoot);
+    expect(first.removed).toBe(true);
+
+    const second = detectAndRemoveStrayProjectNexus(tmpProjectRoot);
+    expect(second.removed).toBe(false);
+    expect(second.path).toBe(strayPath);
+  });
+
+  it('does not remove other .cleo files when removing the stray', () => {
+    const strayPath = join(tmpProjectRoot, '.cleo', 'nexus.db');
+    const tasksPath = join(tmpProjectRoot, '.cleo', 'tasks.db');
+    const configPath = join(tmpProjectRoot, '.cleo', 'config.json');
+
+    writeFileSync(strayPath, '');
+    writeFileSync(tasksPath, 'placeholder');
+    writeFileSync(configPath, '{}');
+
+    detectAndRemoveStrayProjectNexus(tmpProjectRoot);
+
+    expect(existsSync(strayPath)).toBe(false);
+    // Sibling live files must be untouched
+    expect(existsSync(tasksPath)).toBe(true);
+    expect(existsSync(configPath)).toBe(true);
+  });
+
+  it('returns removed: false when the stray exists as a directory (non-fatal)', () => {
+    // Create a directory named nexus.db to simulate an unlinkSync EISDIR failure
+    const strayPath = join(tmpProjectRoot, '.cleo', 'nexus.db');
+    mkdirSync(strayPath);
+
+    const result = detectAndRemoveStrayProjectNexus(tmpProjectRoot);
+
+    // Cannot unlink a directory — should return removed: false without throwing
+    expect(result.removed).toBe(false);
+    expect(result.path).toBe(strayPath);
+    // The directory is still there (we didn't rmdir)
+    expect(existsSync(strayPath)).toBe(true);
+  });
+});