@cleocode/core 2026.4.31 → 2026.4.35

package/dist/paths.js

@@ -0,0 +1,882 @@
+/**
+ * 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   - Override global installation directory
+ *   CLEO_DIR    - Project data directory (default: .cleo)
+ *
+ * @epic T4454
+ * @task T4458
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+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';
+/**
+ * AsyncLocalStorage instance that carries the active {@link WorktreeScope}
+ * for the current async execution context.
+ *
+ * @remarks
+ * Set by the spawn adapter (or any caller that wants to redirect CLEO path
+ * resolution to a worktree directory) before invoking subagent logic.
+ * `getProjectRoot()` checks this store BEFORE the `CLEO_ROOT` env-var and
+ * ancestor-walk, so scoped callers transparently receive the worktree root.
+ *
+ * Callers outside a worktree context receive `undefined` from
+ * `worktreeScope.getStore()` and fall through to the existing resolution
+ * order unchanged.
+ *
+ * @example
+ * ```ts
+ * import { worktreeScope } from '@cleocode/core/paths';
+ *
+ * worktreeScope.run(
+ *   { worktreeRoot: '/path/to/worktree', projectHash: 'abc123' },
+ *   async () => {
+ *     const root = getProjectRoot(); // returns '/path/to/worktree'
+ *   }
+ * );
+ * ```
+ *
+ * @task T380
+ * @public
+ */
+export const worktreeScope = new AsyncLocalStorage();
+/**
+ * Check if a CLEO project is initialized at the given root.
+ * Checks for tasks.db.
+ *
+ * @param projectRoot - Absolute path to check; defaults to the resolved project root
+ * @returns True if .cleo/ and tasks.db exist at the given root
+ *
+ * @remarks
+ * A project is considered initialized when both the .cleo/ directory and
+ * the tasks.db SQLite database file are present.
+ *
+ * @example
+ * ```typescript
+ * if (isProjectInitialized('/my/project')) {
+ *   console.log('CLEO project found');
+ * }
+ * ```
+ */
+export function isProjectInitialized(projectRoot) {
+    const root = projectRoot ?? getProjectRoot();
+    const cleoDir = join(root, '.cleo');
+    return existsSync(cleoDir) && existsSync(join(cleoDir, 'tasks.db'));
+}
+/**
+ * Get the global CLEO home directory.
+ * Respects CLEO_HOME env var; otherwise uses the OS-appropriate data path
+ * via env-paths (XDG_DATA_HOME on Linux, Library/Application Support on macOS,
+ * %LOCALAPPDATA% on Windows).
+ *
+ * @returns Absolute path to the global CLEO data directory
+ *
+ * @remarks
+ * Delegates to `getPlatformPaths().data` which uses the `env-paths` package
+ * for XDG-compliant path resolution across operating systems.
+ *
+ * @example
+ * ```typescript
+ * const home = getCleoHome(); // e.g. "/home/user/.local/share/cleo"
+ * ```
+ */
+export function getCleoHome() {
+    return getPlatformPaths().data;
+}
+/**
+ * Get the global CLEO templates directory.
+ *
+ * @returns Absolute path to the templates directory under CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/templates` where CLEO-INJECTION.md and other global
+ * templates are stored.
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoTemplatesDir(); // e.g. "/home/user/.local/share/cleo/templates"
+ * ```
+ */
+export function getCleoTemplatesDir() {
+    return join(getCleoHome(), 'templates');
+}
+/**
+ * Get the global CLEO schemas directory.
+ *
+ * @returns Absolute path to the schemas directory under CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/schemas`. Note that schemas are typically read at
+ * runtime from the npm package root, not this global directory.
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoSchemasDir();
+ * ```
+ */
+export function getCleoSchemasDir() {
+    return join(getCleoHome(), 'schemas');
+}
+/**
+ * Get the global CLEO docs directory.
+ *
+ * @returns Absolute path to the docs directory under CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/docs` for global documentation storage.
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoDocsDir();
+ * ```
+ */
+export function getCleoDocsDir() {
+    return join(getCleoHome(), 'docs');
+}
+/**
+ * Get the project CLEO data directory (relative).
+ * Respects CLEO_DIR env var, defaults to ".cleo".
+ *
+ * @param cwd - Optional working directory; when provided, returns absolute path
+ * @returns Relative or absolute path to the project's .cleo directory
+ *
+ * @remarks
+ * If `cwd` is provided, delegates to `getCleoDirAbsolute`. Otherwise returns
+ * the `CLEO_DIR` env var or the default ".cleo" relative path.
+ *
+ * @example
+ * ```typescript
+ * const rel = getCleoDir();           // ".cleo"
+ * const abs = getCleoDir('/project'); // "/project/.cleo"
+ * ```
+ */
+export function getCleoDir(cwd) {
+    if (cwd) {
+        return getCleoDirAbsolute(cwd);
+    }
+    return process.env['CLEO_DIR'] ?? '.cleo';
+}
+/**
+ * Get the absolute path to the project CLEO directory.
+ *
+ * @param cwd - Optional working directory to resolve against; defaults to process.cwd()
+ * @returns Absolute path to the project's .cleo directory
+ *
+ * @remarks
+ * If CLEO_DIR is already absolute, returns it directly. Otherwise resolves
+ * it relative to the provided cwd or process.cwd().
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoDirAbsolute('/my/project'); // "/my/project/.cleo"
+ * ```
+ */
+export function getCleoDirAbsolute(cwd) {
+    const cleoDir = getCleoDir();
+    if (isAbsolutePath(cleoDir)) {
+        return cleoDir;
+    }
+    return resolve(cwd ?? process.cwd(), cleoDir);
+}
+/**
+ * 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 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
+ * `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
+ * // Running from packages/core inside the monorepo:
+ * const root = getProjectRoot(); // "/mnt/projects/cleocode"
+ * ```
+ */
+export function getProjectRoot(cwd) {
+    // 0. AsyncLocalStorage worktree scope (T380/ADR-041 §D3) — checked FIRST.
+    //    When a spawn adapter wraps execution in worktreeScope.run(...), the
+    //    scoped root wins over all env-var and walk-based resolution.
+    const scope = worktreeScope.getStore();
+    if (scope !== undefined) {
+        return scope.worktreeRoot;
+    }
+    // 1. Honour CLEO_ROOT / CLEO_PROJECT_ROOT env var — bypass walk entirely.
+    //    CLEO_PROJECT_ROOT is the agent-friendly alias (T090).
+    const envRoot = process.env['CLEO_ROOT'] ?? process.env['CLEO_PROJECT_ROOT'];
+    if (envRoot) {
+        return envRoot;
+    }
+    // 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;
+    }
+    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',
+    });
+}
+/**
+ * Resolve a project-relative path to an absolute path.
+ *
+ * @param relativePath - Path to resolve (relative, absolute, or tilde-prefixed)
+ * @param cwd - Optional working directory for project root resolution
+ * @returns Absolute resolved path
+ *
+ * @remarks
+ * Returns absolute paths unchanged. Expands leading tilde (`~/`) to the user's
+ * home directory. Resolves other relative paths against the project root.
+ *
+ * @example
+ * ```typescript
+ * resolveProjectPath('src/index.ts');     // "/project/src/index.ts"
+ * resolveProjectPath('~/notes.md');       // "/home/user/notes.md"
+ * resolveProjectPath('/absolute/path');   // "/absolute/path"
+ * ```
+ */
+export function resolveProjectPath(relativePath, cwd) {
+    if (isAbsolutePath(relativePath)) {
+        return relativePath;
+    }
+    // Expand leading tilde (handles both ~/ on Unix and ~\ on Windows)
+    if (relativePath.startsWith('~/') || relativePath.startsWith('~\\') || relativePath === '~') {
+        return resolve(homedir(), relativePath.slice(2));
+    }
+    return resolve(getProjectRoot(cwd), relativePath);
+}
+/**
+ * Get the path to the project's tasks.db file (SQLite database).
+ * @deprecated Use getAccessor() from './store/data-accessor.js' instead. This function
+ *   returns the database file path for legacy compatibility, but all task data access
+ *   should go through the DataAccessor interface to ensure proper SQLite interaction.
+ *   Example:
+ *     // OLD (deprecated):
+ *     const taskPath = getTaskPath(cwd);
+ *     const data = await readJsonFile<TaskFile>(taskPath);
+ *     // NEW (correct):
+ *     const accessor = await getAccessor(cwd);
+ *     const data = await accessor.queryTasks({});
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the tasks.db file
+ *
+ * @remarks
+ * Returns `{cleoDir}/tasks.db`. Prefer `getAccessor()` for actual data access.
+ *
+ * @example
+ * ```typescript
+ * const dbPath = getTaskPath('/project');
+ * ```
+ */
+export function getTaskPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'tasks.db');
+}
+/**
+ * Get the path to the project's config.json file.
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the project config.json
+ *
+ * @remarks
+ * Returns `{cleoDir}/config.json`.
+ *
+ * @example
+ * ```typescript
+ * const configPath = getConfigPath('/project');
+ * ```
+ */
+export function getConfigPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'config.json');
+}
+/**
+ * Get the path to the project's sessions.json file.
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the sessions.json file
+ *
+ * @remarks
+ * Returns `{cleoDir}/sessions.json`.
+ *
+ * @example
+ * ```typescript
+ * const sessionsPath = getSessionsPath('/project');
+ * ```
+ */
+export function getSessionsPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'sessions.json');
+}
+/**
+ * Get the path to the project's archive file.
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the tasks-archive.json file
+ *
+ * @remarks
+ * Returns `{cleoDir}/tasks-archive.json` where archived tasks are stored.
+ *
+ * @example
+ * ```typescript
+ * const archivePath = getArchivePath('/project');
+ * ```
+ */
+export function getArchivePath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'tasks-archive.json');
+}
+/**
+ * Get the path to the project's log file.
+ * Canonical structured runtime log path (pino).
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the cleo.log file
+ *
+ * @remarks
+ * Returns `{cleoDir}/logs/cleo.log`. Used by pino for structured JSON logging.
+ *
+ * @example
+ * ```typescript
+ * const logPath = getLogPath('/project');
+ * ```
+ *
+ * @task T4644
+ */
+export function getLogPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'logs', 'cleo.log');
+}
+/**
+ * Get the backup directory for operational backups.
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the operational backups directory
+ *
+ * @remarks
+ * Returns `{cleoDir}/backups/operational`.
+ *
+ * @example
+ * ```typescript
+ * const backupDir = getBackupDir('/project');
+ * ```
+ */
+export function getBackupDir(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'backups', 'operational');
+}
+/**
+ * Get the global config file path.
+ *
+ * @returns Absolute path to the global config.json in CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/config.json` for global CLEO configuration.
+ *
+ * @example
+ * ```typescript
+ * const globalConfig = getGlobalConfigPath();
+ * ```
+ */
+export function getGlobalConfigPath() {
+    return join(getCleoHome(), 'config.json');
+}
+// ============================================================================
+// CleoOS Hub Paths (Phase 1)
+// ============================================================================
+/**
+ * Get the Global Justfile Hub directory.
+ *
+ * The hub stores cross-project recipe libraries agents can run in ANY project
+ * (cleo-bootstrap, rcasd-init, schema-validate, lint-standard). Both humans
+ * (via editor) and the meta Cleo Chef Agent write recipes here.
+ *
+ * @returns Absolute path to the global-recipes directory under CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/global-recipes`. Created by `ensureGlobalHome()`.
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoGlobalRecipesDir();
+ * // Linux: "/home/user/.local/share/cleo/global-recipes"
+ * ```
+ */
+export function getCleoGlobalRecipesDir() {
+    return join(getCleoHome(), 'global-recipes');
+}
+/**
+ * Get the absolute path to the primary global justfile.
+ *
+ * @returns Absolute path to `{cleoHome}/global-recipes/justfile`
+ *
+ * @remarks
+ * This is the single-file entry point for the Justfile Hub. Additional
+ * domain-specific justfiles live alongside it in the same directory.
+ *
+ * @example
+ * ```typescript
+ * const path = getCleoGlobalJustfilePath();
+ * ```
+ */
+export function getCleoGlobalJustfilePath() {
+    return join(getCleoGlobalRecipesDir(), 'justfile');
+}
+/**
+ * Get the Global Pi Extensions Hub directory.
+ *
+ * Houses the Pi extensions that drive the CleoOS UI and tools:
+ * orchestrator.ts (Conductor Loop), project-manager.ts (TUI dashboard),
+ * tilldone.ts (work visualization), cant-bridge.ts (CANT runtime),
+ * stage-guide.ts (before_agent_start hook).
+ *
+ * @returns Absolute path to the pi-extensions directory under CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/pi-extensions`. Pi is configured to load extensions
+ * from this directory via settings.json or the PI extension path setting.
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoPiExtensionsDir();
+ * // Linux: "/home/user/.local/share/cleo/pi-extensions"
+ * ```
+ */
+export function getCleoPiExtensionsDir() {
+    return join(getCleoHome(), 'pi-extensions');
+}
+/**
+ * Get the Global CANT Workflows Hub directory.
+ *
+ * Stores compiled and parsed `.cant` workflows that agents can invoke
+ * globally across projects. Project-local agents still live in `.cleo/agents/`.
+ *
+ * @returns Absolute path to the cant-workflows directory under CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/cant-workflows`. Used by the CANT runtime bridge
+ * to resolve globally-available workflow definitions.
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoCantWorkflowsDir();
+ * ```
+ */
+export function getCleoCantWorkflowsDir() {
+    return join(getCleoHome(), 'cant-workflows');
+}
+/**
+ * Get the Global CLEO Agents directory.
+ *
+ * Holds globally-available CANT agent definitions (`.cant` files).
+ * Project-local agents still live in `{projectRoot}/.cleo/agents/`.
+ *
+ * @returns Absolute path to the agents directory under CLEO home
+ *
+ * @remarks
+ * Returns `{cleoHome}/agents`. Loaded when `cleo agent start <id>` resolves
+ * agent IDs that aren't found in the project-local registry.
+ *
+ * @example
+ * ```typescript
+ * const dir = getCleoGlobalAgentsDir();
+ * ```
+ */
+export function getCleoGlobalAgentsDir() {
+    return join(getCleoHome(), 'agents');
+}
+// ============================================================================
+// Agent Outputs
+// ============================================================================
+const DEFAULT_AGENT_OUTPUTS_DIR = '.cleo/agent-outputs';
+/**
+ * Get the agent outputs directory (relative path) from config or default.
+ *
+ * Config lookup priority:
+ *   1. config.agentOutputs.directory
+ *   2. config.research.outputDir (deprecated)
+ *   3. config.directories.agentOutputs (deprecated)
+ *   4. Default: '.cleo/agent-outputs'
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Relative or absolute path to the agent outputs directory
+ *
+ * @remarks
+ * Checks config fields in priority order: `agentOutputs.directory`, `research.outputDir`,
+ * `directories.agentOutputs`. Falls back to `.cleo/agent-outputs`.
+ *
+ * @example
+ * ```typescript
+ * const dir = getAgentOutputsDir('/project');
+ * ```
+ *
+ * @task T4700
+ */
+export function getAgentOutputsDir(cwd) {
+    const projectRoot = getProjectRoot(cwd);
+    const configPath = join(projectRoot, '.cleo', 'config.json');
+    if (existsSync(configPath)) {
+        try {
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            // Priority 1: agentOutputs.directory (canonical)
+            if (typeof config.agentOutputs === 'object' && config.agentOutputs?.directory) {
+                return config.agentOutputs.directory;
+            }
+            // Also support agentOutputs as a plain string
+            if (typeof config.agentOutputs === 'string' && config.agentOutputs) {
+                return config.agentOutputs;
+            }
+            // Priority 2: research.outputDir (deprecated)
+            if (config.research?.outputDir) {
+                return config.research.outputDir;
+            }
+            // Priority 3: directories.agentOutputs (deprecated)
+            if (config.directories?.agentOutputs) {
+                return config.directories.agentOutputs;
+            }
+        }
+        catch {
+            // fallback to default
+        }
+    }
+    return DEFAULT_AGENT_OUTPUTS_DIR;
+}
+/**
+ * Get the absolute path to the agent outputs directory.
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the agent outputs directory
+ *
+ * @remarks
+ * Resolves the output of `getAgentOutputsDir()` against the project root
+ * if it is not already absolute.
+ *
+ * @example
+ * ```typescript
+ * const absDir = getAgentOutputsAbsolute('/project');
+ * ```
+ *
+ * @task T4700
+ */
+export function getAgentOutputsAbsolute(cwd) {
+    const dir = getAgentOutputsDir(cwd);
+    if (isAbsolutePath(dir)) {
+        return dir;
+    }
+    return resolve(getProjectRoot(cwd), dir);
+}
+/**
+ * Get the absolute path to the MANIFEST.jsonl file.
+ *
+ * Checks config.agentOutputs.manifestFile for custom filename,
+ * defaults to 'MANIFEST.jsonl'.
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the MANIFEST.jsonl file
+ *
+ * @remarks
+ * Checks `config.agentOutputs.manifestFile` for a custom filename,
+ * defaults to `MANIFEST.jsonl` in the agent outputs directory.
+ *
+ * @example
+ * ```typescript
+ * const manifestPath = getManifestPath('/project');
+ * ```
+ *
+ * @task T4700
+ */
+export function getManifestPath(cwd) {
+    const outputDir = getAgentOutputsDir(cwd);
+    const projectRoot = getProjectRoot(cwd);
+    const configPath = join(projectRoot, '.cleo', 'config.json');
+    let manifestFile = 'MANIFEST.jsonl';
+    if (existsSync(configPath)) {
+        try {
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const customFile = config.agentOutputs?.manifestFile ?? config.research?.manifestFile;
+            if (customFile) {
+                manifestFile = customFile;
+            }
+        }
+        catch {
+            // fallback
+        }
+    }
+    return resolve(projectRoot, outputDir, manifestFile);
+}
+/**
+ * Get the absolute path to the MANIFEST.archive.jsonl file.
+ *
+ * @param cwd - Optional working directory for path resolution
+ * @returns Absolute path to the MANIFEST.archive.jsonl file
+ *
+ * @remarks
+ * Returns the archive manifest path in the agent outputs directory.
+ *
+ * @example
+ * ```typescript
+ * const archivePath = getManifestArchivePath('/project');
+ * ```
+ *
+ * @task T4700
+ */
+export function getManifestArchivePath(cwd) {
+    const outputDir = getAgentOutputsDir(cwd);
+    const projectRoot = getProjectRoot(cwd);
+    return resolve(projectRoot, outputDir, 'MANIFEST.archive.jsonl');
+}
+// ============================================================================
+// Path Utilities
+// ============================================================================
+/**
+ * Check if a path is absolute (POSIX or Windows).
+ *
+ * @param path - Filesystem path to check
+ * @returns True if the path is absolute on any supported OS
+ *
+ * @remarks
+ * Recognizes POSIX absolute paths (`/...`), Windows drive letters (`C:\...`),
+ * and UNC paths (`\\...`).
+ *
+ * @example
+ * ```typescript
+ * isAbsolutePath('/usr/bin');    // true
+ * isAbsolutePath('C:\\Users');   // true
+ * isAbsolutePath('./relative'); // false
+ * ```
+ */
+export function isAbsolutePath(path) {
+    // POSIX absolute
+    if (path.startsWith('/'))
+        return true;
+    // Windows drive letter (C:\, D:/)
+    if (/^[A-Za-z]:[\\/]/.test(path))
+        return true;
+    // UNC path
+    if (path.startsWith('\\\\'))
+        return true;
+    return false;
+}
+// ============================================================================
+// OS-Aware Global Paths (via env-paths)
+// ============================================================================
+/**
+ * Get the OS log directory for CLEO global logs.
+ * Linux: ~/.local/state/cleo | macOS: ~/Library/Logs/cleo | Windows: %LOCALAPPDATA%\cleo\Log
+ *
+ * @returns Absolute path to the OS-appropriate log directory
+ *
+ * @remarks
+ * Delegates to `getPlatformPaths().log` for XDG-compliant resolution.
+ *
+ * @example
+ * ```typescript
+ * const logDir = getCleoLogDir();
+ * ```
+ */
+export function getCleoLogDir() {
+    return getPlatformPaths().log;
+}
+/**
+ * Get the OS cache directory for CLEO.
+ * Linux: ~/.cache/cleo | macOS: ~/Library/Caches/cleo | Windows: %LOCALAPPDATA%\cleo\Cache
+ *
+ * @returns Absolute path to the OS-appropriate cache directory
+ *
+ * @remarks
+ * Delegates to `getPlatformPaths().cache` for XDG-compliant resolution.
+ *
+ * @example
+ * ```typescript
+ * const cacheDir = getCleoCacheDir();
+ * ```
+ */
+export function getCleoCacheDir() {
+    return getPlatformPaths().cache;
+}
+/**
+ * Get the OS temp directory for CLEO ephemeral files.
+ *
+ * @returns Absolute path to the OS-appropriate temp directory
+ *
+ * @remarks
+ * Delegates to `getPlatformPaths().temp` for platform-specific resolution.
+ *
+ * @example
+ * ```typescript
+ * const tempDir = getCleoTempDir();
+ * ```
+ */
+export function getCleoTempDir() {
+    return getPlatformPaths().temp;
+}
+/**
+ * Get the OS config directory for CLEO.
+ * Linux: ~/.config/cleo | macOS: ~/Library/Preferences/cleo | Windows: %APPDATA%\cleo\Config
+ *
+ * @returns Absolute path to the OS-appropriate config directory
+ *
+ * @remarks
+ * Delegates to `getPlatformPaths().config` for XDG-compliant resolution.
+ *
+ * @example
+ * ```typescript
+ * const configDir = getCleoConfigDir();
+ * ```
+ */
+export function getCleoConfigDir() {
+    return getPlatformPaths().config;
+}
+/**
+ * Get the CLEO templates directory as a tilde-prefixed path for use
+ * in `@` references (AGENTS.md, CLAUDE.md, etc.). Cross-platform:
+ * replaces the user's home directory with `~` so the reference works
+ * when loaded by LLM providers that resolve `~` at runtime.
+ *
+ * Linux:   ~/.local/share/cleo/templates
+ * macOS:   ~/Library/Application Support/cleo/templates
+ * Windows: ~/AppData/Local/cleo/Data/templates (approximate)
+ *
+ * @returns Tilde-prefixed path like "~/.local/share/cleo/templates"
+ *
+ * @remarks
+ * Returns the absolute path if the home directory is not a prefix
+ * (unlikely but handled). Always uses forward slashes after the tilde
+ * for cross-platform compatibility in `@`-reference resolution.
+ *
+ * @example
+ * ```typescript
+ * const tildePath = getCleoTemplatesTildePath();
+ * // "~/.local/share/cleo/templates"
+ * ```
+ */
+export function getCleoTemplatesTildePath() {
+    const absPath = getCleoTemplatesDir();
+    const home = homedir();
+    if (absPath.startsWith(home)) {
+        // Always use forward slash after tilde for cross-platform @-reference resolution
+        const relative = absPath.slice(home.length).replace(/\\/g, '/');
+        return `~${relative}`;
+    }
+    return absPath;
+}
+// ============================================================================
+// Third-Party Tool Paths (OS-aware)
+// ============================================================================
+/**
+ * Get the global agents hub directory.
+ * Respects AGENTS_HOME env var, defaults to ~/.agents.
+ *
+ * @returns Absolute path to the agents hub directory
+ *
+ * @remarks
+ * Returns `AGENTS_HOME` env var if set, otherwise `~/.agents`.
+ *
+ * @example
+ * ```typescript
+ * const agentsHome = getAgentsHome(); // "/home/user/.agents"
+ * ```
+ */
+export function getAgentsHome() {
+    return process.env['AGENTS_HOME'] ?? join(homedir(), '.agents');
+}
+/**
+ * Get the Claude Code agents directory (~/.claude/agents by default).
+ *
+ * @returns Absolute path to the Claude agents directory
+ *
+ * @remarks
+ * Respects `CLAUDE_HOME` env var for the parent directory.
+ *
+ * @example
+ * ```typescript
+ * const dir = getClaudeAgentsDir();
+ * ```
+ *
+ * @deprecated Use AdapterPathProvider.getAgentInstallDir() from the active adapter instead.
+ */
+export function getClaudeAgentsDir() {
+    const claudeDir = process.env['CLAUDE_HOME'] ?? join(homedir(), '.claude');
+    return join(claudeDir, 'agents');
+}
+/**
+ * Get the claude-mem SQLite database path.
+ *
+ * @returns Absolute path to the claude-mem.db file
+ *
+ * @remarks
+ * Respects `CLAUDE_MEM_DB` env var, defaults to `~/.claude-mem/claude-mem.db`.
+ * This is a third-party tool path; homedir() is correct here (no env-paths standard).
+ *
+ * @example
+ * ```typescript
+ * const dbPath = getClaudeMemDbPath();
+ * ```
+ *
+ * @deprecated Use AdapterPathProvider.getMemoryDbPath() from the active adapter instead.
+ */
+export function getClaudeMemDbPath() {
+    return process.env['CLAUDE_MEM_DB'] ?? join(homedir(), '.claude-mem', 'claude-mem.db');
+}
+//# sourceMappingURL=paths.js.map