@cleocode/core 2026.4.0 → 2026.4.3

package/src/metrics/token-service.ts

@@ -1,14 +1,14 @@
 /**
  * Provider-aware token measurement and persistence.
  *
- * Central SSoT for CLI/MCP/tooling token estimation with a three-layer chain:
+ * Central SSoT for CLI/tooling token estimation with a three-layer chain:
  * 1) OTel/provider telemetry when available
  * 2) Exact tokenizer for supported models
  * 3) Heuristic fallback calibrated for JSON vs text payloads
  *
  * @task T5618
  * @why CLEO needs a provider-aware in-house token service instead of relying on a single external runtime.
- * @what Adds central token measurement, persistence, CRUD, and summary helpers for CLI, MCP, tests, and telemetry tooling.
+ * @what Adds central token measurement, persistence, CRUD, and summary helpers for CLI, tests, and telemetry tooling.
  */
 
 import { createHash, randomUUID } from 'node:crypto';
@@ -21,7 +21,7 @@ import { detectRuntimeProviderContext } from './provider-detection.js';
 
 export type TokenMethod = 'otel' | 'provider_api' | 'tokenizer' | 'heuristic';
 export type TokenConfidence = 'real' | 'high' | 'estimated' | 'coarse';
-export type TokenTransport = 'cli' | 'mcp' | 'api' | 'agent' | 'unknown';
+export type TokenTransport = 'cli' | 'api' | 'agent' | 'unknown';
 
 export interface TokenExchangeInput {
   requestPayload?: unknown;
@@ -554,7 +554,7 @@ export async function autoRecordDispatchTokenUsage(input: TokenExchangeInput): P
   try {
     await recordTokenExchange(input);
   } catch {
-    // Token telemetry must never break core CLI/MCP flows.
+    // Token telemetry must never break core CLI flows.
   }
 }
 

package/src/migration/index.ts

@@ -34,7 +34,7 @@ export {
   readMigrationLog,
 } from './logger.js';
 export type { PreflightResult } from './preflight.js';
-// Re-export pre-flight check for CLI/MCP consumers (@task T4699)
+// Re-export pre-flight check for CLI consumers (@task T4699)
 export { checkStorageMigration } from './preflight.js';
 export type {
   MigrationPhase,

package/src/paths.ts

@@ -17,6 +17,20 @@ import { getPlatformPaths } from './system/platform-paths.js';
 /**
  * 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?: string): boolean {
   const root = projectRoot ?? getProjectRoot();
@@ -29,6 +43,17 @@ export function isProjectInitialized(projectRoot?: string): boolean {
  * 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(): string {
   return getPlatformPaths().data;
@@ -36,6 +61,17 @@ export function getCleoHome(): string {
 
 /**
  * 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(): string {
   return join(getCleoHome(), 'templates');
@@ -43,6 +79,17 @@ export function getCleoTemplatesDir(): string {
 
 /**
  * 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(): string {
   return join(getCleoHome(), 'schemas');
@@ -50,6 +97,16 @@ export function getCleoSchemasDir(): string {
 
 /**
  * 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(): string {
   return join(getCleoHome(), 'docs');
@@ -58,6 +115,19 @@ export function getCleoDocsDir(): string {
 /**
  * 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?: string): string {
   if (cwd) {
@@ -68,6 +138,18 @@ export function getCleoDir(cwd?: string): string {
 
 /**
  * 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?: string): string {
   const cleoDir = getCleoDir();
@@ -81,6 +163,18 @@ 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.
+ *
+ * @param cwd - Optional working directory hint
+ * @returns Absolute path to the project root
+ *
+ * @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.
+ *
+ * @example
+ * ```typescript
+ * const root = getProjectRoot(); // "/home/user/projects/myapp"
+ * ```
  */
 export function getProjectRoot(cwd?: string): string {
   if (!cwd && process.env['CLEO_ROOT']) {
@@ -95,13 +189,28 @@ export function getProjectRoot(cwd?: string): string {
 
 /**
  * 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: string, cwd?: string): string {
   if (isAbsolutePath(relativePath)) {
     return relativePath;
   }
-  // Expand leading tilde
-  if (relativePath.startsWith('~/') || 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);
@@ -119,6 +228,17 @@ export function resolveProjectPath(relativePath: string, cwd?: string): string {
  *     // 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?: string): string {
   return join(getCleoDirAbsolute(cwd), 'tasks.db');
@@ -126,6 +246,17 @@ export function getTaskPath(cwd?: string): string {
 
 /**
  * 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?: string): string {
   return join(getCleoDirAbsolute(cwd), 'config.json');
@@ -133,6 +264,17 @@ export function getConfigPath(cwd?: string): string {
 
 /**
  * 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?: string): string {
   return join(getCleoDirAbsolute(cwd), 'sessions.json');
@@ -140,6 +282,17 @@ export function getSessionsPath(cwd?: string): string {
 
 /**
  * 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?: string): string {
   return join(getCleoDirAbsolute(cwd), 'tasks-archive.json');
@@ -148,6 +301,18 @@ export function getArchivePath(cwd?: string): string {
 /**
  * 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?: string): string {
@@ -156,6 +321,17 @@ export function getLogPath(cwd?: string): string {
 
 /**
  * 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?: string): string {
   return join(getCleoDirAbsolute(cwd), 'backups', 'operational');
@@ -163,6 +339,16 @@ export function getBackupDir(cwd?: string): string {
 
 /**
  * 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(): string {
   return join(getCleoHome(), 'config.json');
@@ -183,6 +369,18 @@ const DEFAULT_AGENT_OUTPUTS_DIR = '.cleo/agent-outputs';
  *   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?: string): string {
@@ -221,6 +419,19 @@ export function getAgentOutputsDir(cwd?: string): string {
 
 /**
  * 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?: string): string {
@@ -237,6 +448,18 @@ export function getAgentOutputsAbsolute(cwd?: string): string {
  * 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?: string): string {
@@ -262,6 +485,18 @@ export function getManifestPath(cwd?: string): string {
 
 /**
  * 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?: string): string {
@@ -276,6 +511,20 @@ export function getManifestArchivePath(cwd?: string): string {
 
 /**
  * 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: string): boolean {
   // POSIX absolute
@@ -294,6 +543,16 @@ export function isAbsolutePath(path: string): boolean {
 /**
  * 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(): string {
   return getPlatformPaths().log;
@@ -302,6 +561,16 @@ export function getCleoLogDir(): string {
 /**
  * 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(): string {
   return getPlatformPaths().cache;
@@ -309,6 +578,16 @@ export function getCleoCacheDir(): string {
 
 /**
  * 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(): string {
   return getPlatformPaths().temp;
@@ -317,6 +596,16 @@ export function getCleoTempDir(): string {
 /**
  * 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(): string {
   return getPlatformPaths().config;
@@ -331,12 +620,27 @@ export function getCleoConfigDir(): string {
  * 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(): string {
   const absPath = getCleoTemplatesDir();
   const home = homedir();
   if (absPath.startsWith(home)) {
-    return `~${absPath.slice(home.length)}`;
+    // Always use forward slash after tilde for cross-platform @-reference resolution
+    const relative = absPath.slice(home.length).replace(/\\/g, '/');
+    return `~${relative}`;
   }
   return absPath;
 }
@@ -348,6 +652,16 @@ export function getCleoTemplatesTildePath(): string {
 /**
  * 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(): string {
   return process.env['AGENTS_HOME'] ?? join(homedir(), '.agents');
@@ -355,6 +669,17 @@ export function getAgentsHome(): string {
 
 /**
  * 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(): string {
@@ -364,9 +689,19 @@ export function getClaudeAgentsDir(): string {
 
 /**
  * Get the claude-mem SQLite database path.
- * @deprecated Use AdapterPathProvider.getMemoryDbPath() from the active adapter instead.
- * Respects CLAUDE_MEM_DB env var, defaults to ~/.claude-mem/claude-mem.db.
+ *
+ * @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(): string {
   return process.env['CLAUDE_MEM_DB'] ?? join(homedir(), '.claude-mem', 'claude-mem.db');