@cleocode/core 2026.3.76 → 2026.4.0

package/dist/output.js

@@ -0,0 +1,164 @@
+/**
+ * LAFS-compliant output formatter for CLEO V2.
+ *
+ * LAFS (LLM-Agent-First Schema) ensures all CLI output is
+ * machine-parseable JSON by default, with optional human-readable modes.
+ *
+ * All envelopes are now full LAFS-compliant with $schema and _meta.
+ * The backward-compatible shape (success + data, no _meta) has been removed.
+ *
+ * Types are re-exported from the canonical source in src/types/lafs.ts.
+ *
+ * @epic T4663
+ * @task T4672
+ */
+import { randomUUID } from 'node:crypto';
+import { CleoError } from './errors.js';
+import { getCurrentSessionId } from './sessions/context-alert.js';
+/**
+ * Accumulated warnings for the current request.
+ * Reset on each formatSuccess/formatError call via drainWarnings().
+ *
+ * @task T4669
+ * @epic T4663
+ */
+const pendingWarnings = [];
+/**
+ * Push a deprecation or informational warning into the current envelope.
+ * Warnings are drained (consumed) by the next formatSuccess/formatError call.
+ *
+ * @task T4669
+ * @epic T4663
+ */
+export function pushWarning(warning) {
+    pendingWarnings.push(warning);
+}
+/**
+ * Drain all pending warnings (returns and clears the queue).
+ *
+ * @task T4669
+ * @epic T4663
+ */
+function drainWarnings() {
+    if (pendingWarnings.length === 0)
+        return undefined;
+    const drained = [...pendingWarnings];
+    pendingWarnings.length = 0;
+    return drained;
+}
+/**
+ * Create a LAFS-conformant _meta object for CLI envelopes.
+ * Includes sessionId (T4702) and warnings (T4669) when present.
+ *
+ * @task T4700
+ * @task T4702
+ * @epic T4663
+ */
+function createCliMeta(operation, mvi = 'minimal') {
+    const warnings = drainWarnings();
+    const meta = {
+        specVersion: '1.2.3',
+        schemaVersion: '2026.2.1',
+        timestamp: new Date().toISOString(),
+        operation,
+        requestId: randomUUID(),
+        transport: 'cli',
+        strict: true,
+        mvi,
+        contextVersion: 1,
+        ...(warnings && { warnings }),
+    };
+    const sessionId = getCurrentSessionId();
+    if (sessionId) {
+        meta.sessionId = sessionId;
+    }
+    return meta;
+}
+/**
+ * Format a successful result as a full LAFS-conformant envelope.
+ *
+ * Always produces the full LAFSEnvelope with $schema and _meta.
+ * When operation is omitted, defaults to 'cli.output'.
+ * Supports optional page (T4668) and _extensions (T4670).
+ *
+ * @task T4672
+ * @task T4668
+ * @task T4670
+ * @epic T4663
+ */
+export function formatSuccess(data, message, operationOrOpts) {
+    const opts = typeof operationOrOpts === 'string' ? { operation: operationOrOpts } : (operationOrOpts ?? {});
+    // Determine MVI level: default is 'minimal' (agent-optimized).
+    // Only --human flag or explicit mvi='full'/'standard' overrides.
+    const mviLevel = opts.mvi ?? 'minimal';
+    const meta = createCliMeta(opts.operation ?? 'cli.output', mviLevel);
+    const fullEnvelope = {
+        $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+        _meta: meta,
+        success: true,
+        result: data,
+        ...(message && { message }),
+        ...(opts.page && { page: opts.page }),
+        ...(opts.extensions &&
+            Object.keys(opts.extensions).length > 0 && { _extensions: opts.extensions }),
+    };
+    // For 'full' level, skip projection — return the complete envelope as-is.
+    // This is the backward-compatible path used by --human and conformance tests.
+    if (mviLevel === 'full') {
+        return JSON.stringify(fullEnvelope);
+    }
+    // Apply MVI projection — strips envelope to the declared level.
+    // 'minimal': { success, result, _meta: { requestId, contextVersion } }
+    // 'standard': + $schema, timestamp, operation, mvi
+    if (mviLevel === 'minimal') {
+        // Inline minimal projection — avoids dynamic import overhead.
+        // Matches projectMetaMinimal() from @cleocode/lafs/mviProjection.ts
+        const minimalMeta = {
+            op: meta.operation,
+            rid: meta.requestId,
+        };
+        if (meta.sessionId)
+            minimalMeta.sid = meta.sessionId;
+        if (meta.warnings?.length)
+            minimalMeta.w = meta.warnings;
+        const minimal = {
+            ok: true,
+            r: data,
+            _m: minimalMeta,
+        };
+        if (message)
+            minimal.msg = message;
+        if (opts.page)
+            minimal.p = opts.page;
+        return JSON.stringify(minimal);
+    }
+    // 'standard' level — use the full envelope structure (current behavior)
+    return JSON.stringify(fullEnvelope);
+}
+/**
+ * Format an error as a full LAFS-conformant envelope.
+ *
+ * Always produces the full LAFSEnvelope with $schema and _meta.
+ * When operation is omitted, defaults to 'cli.output'.
+ *
+ * @task T4672
+ * @epic T4663
+ */
+export function formatError(error, operation) {
+    const envelope = {
+        $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+        _meta: createCliMeta(operation ?? 'cli.output'),
+        success: false,
+        result: null,
+        error: error.toLAFSError(),
+    };
+    return JSON.stringify(envelope);
+}
+/** Format any result (success or error) as LAFS JSON. */
+export function formatOutput(result) {
+    if (result instanceof CleoError) {
+        return formatError(result);
+    }
+    return formatSuccess(result);
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"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"}

package/dist/pagination.js

@@ -0,0 +1,64 @@
+/**
+ * LAFS-compliant pagination utility for list commands.
+ *
+ * Wraps result arrays in LAFSPage offset pagination objects.
+ * Supports both offset-based and cursor-based pagination modes.
+ *
+ * @task T4668
+ * @epic T4663
+ */
+/**
+ * Default page size when limit is not specified.
+ *
+ * @task T4668
+ */
+const DEFAULT_LIMIT = 50;
+/**
+ * Create an LAFSPage object from pagination parameters.
+ *
+ * Returns mode:"none" when no pagination is requested (no limit/offset).
+ * Returns mode:"offset" with hasMore/total when pagination is active.
+ *
+ * @task T4668
+ * @epic T4663
+ */
+export function createPage(input) {
+    const { total, limit, offset } = input;
+    // No pagination requested
+    if (limit === undefined && offset === undefined) {
+        return { mode: 'none' };
+    }
+    const effectiveLimit = limit ?? DEFAULT_LIMIT;
+    const effectiveOffset = offset ?? 0;
+    const hasMore = effectiveOffset + effectiveLimit < total;
+    return {
+        mode: 'offset',
+        limit: effectiveLimit,
+        offset: effectiveOffset,
+        hasMore,
+        total,
+    };
+}
+/**
+ * Apply pagination to an array of items and return the sliced result with page metadata.
+ *
+ * @task T4668
+ * @epic T4663
+ */
+export function paginate(items, limit, offset) {
+    if (!items || items.length === 0) {
+        return { items: [], page: { mode: 'none' } };
+    }
+    const total = items.length;
+    if (limit === undefined && offset === undefined) {
+        return { items, page: { mode: 'none' } };
+    }
+    const effectiveOffset = offset ?? 0;
+    const effectiveLimit = limit ?? DEFAULT_LIMIT;
+    const sliced = items.slice(effectiveOffset, effectiveOffset + effectiveLimit);
+    return {
+        items: sliced,
+        page: createPage({ total, limit: effectiveLimit, offset: effectiveOffset }),
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmBH;;;;GAIG;AACH,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IAEvC,0BAA0B;IAC1B,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAkB,CAAC;IAC1C,CAAC;IAED,MAAM,cAAc,GAAG,KAAK,IAAI,aAAa,CAAC;IAC9C,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,eAAe,GAAG,cAAc,GAAG,KAAK,CAAC;IAEzD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,cAAc;QACrB,MAAM,EAAE,eAAe;QACvB,OAAO;QACP,KAAK;KACY,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,KAA6B,EAC7B,KAAc,EACd,MAAe;IAEf,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAkB,EAAE,CAAC;IAC/D,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAE3B,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAkB,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,CAAC;IACpC,MAAM,cAAc,GAAG,KAAK,IAAI,aAAa,CAAC;IAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,eAAe,EAAE,eAAe,GAAG,cAAc,CAAC,CAAC;IAE9E,OAAO;QACL,KAAK,EAAE,MAAM;QACb,IAAI,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;KAC5E,CAAC;AACJ,CAAC"}

package/dist/paths.js

@@ -0,0 +1,337 @@
+/**
+ * XDG-compliant path resolution for CLEO V2.
+ *
+ * Environment variables:
+ *   CLEO_HOME   - Global installation directory (default: ~/.cleo)
+ *   CLEO_DIR    - Project data directory (default: .cleo)
+ *
+ * @epic T4454
+ * @task T4458
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { getPlatformPaths } from './system/platform-paths.js';
+/**
+ * Check if a CLEO project is initialized at the given root.
+ * Checks for tasks.db.
+ */
+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).
+ */
+export function getCleoHome() {
+    return getPlatformPaths().data;
+}
+/**
+ * Get the global CLEO templates directory.
+ */
+export function getCleoTemplatesDir() {
+    return join(getCleoHome(), 'templates');
+}
+/**
+ * Get the global CLEO schemas directory.
+ */
+export function getCleoSchemasDir() {
+    return join(getCleoHome(), 'schemas');
+}
+/**
+ * Get the global CLEO docs directory.
+ */
+export function getCleoDocsDir() {
+    return join(getCleoHome(), 'docs');
+}
+/**
+ * Get the project CLEO data directory (relative).
+ * Respects CLEO_DIR env var, defaults to ".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.
+ */
+export function getCleoDirAbsolute(cwd) {
+    const cleoDir = getCleoDir();
+    if (isAbsolutePath(cleoDir)) {
+        return cleoDir;
+    }
+    return resolve(cwd ?? process.cwd(), cleoDir);
+}
+/**
+ * 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.
+ */
+export function getProjectRoot(cwd) {
+    if (!cwd && process.env['CLEO_ROOT']) {
+        return process.env['CLEO_ROOT'];
+    }
+    const cleoDirAbs = getCleoDirAbsolute(cwd);
+    if (cleoDirAbs.endsWith('/.cleo') || cleoDirAbs.endsWith('\\.cleo')) {
+        return dirname(cleoDirAbs);
+    }
+    return cwd ?? process.cwd();
+}
+/**
+ * Resolve a project-relative path to an absolute path.
+ */
+export function resolveProjectPath(relativePath, cwd) {
+    if (isAbsolutePath(relativePath)) {
+        return relativePath;
+    }
+    // Expand leading tilde
+    if (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({});
+ */
+export function getTaskPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'tasks.db');
+}
+/**
+ * Get the path to the project's config.json file.
+ */
+export function getConfigPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'config.json');
+}
+/**
+ * Get the path to the project's sessions.json file.
+ */
+export function getSessionsPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'sessions.json');
+}
+/**
+ * Get the path to the project's archive file.
+ */
+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).
+ * @task T4644
+ */
+export function getLogPath(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'logs', 'cleo.log');
+}
+/**
+ * Get the backup directory for operational backups.
+ */
+export function getBackupDir(cwd) {
+    return join(getCleoDirAbsolute(cwd), 'backups', 'operational');
+}
+/**
+ * Get the global config file path.
+ */
+export function getGlobalConfigPath() {
+    return join(getCleoHome(), 'config.json');
+}
+// ============================================================================
+// 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'
+ *
+ * @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.
+ * @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'.
+ *
+ * @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.
+ * @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).
+ */
+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
+ */
+export function getCleoLogDir() {
+    return getPlatformPaths().log;
+}
+/**
+ * Get the OS cache directory for CLEO.
+ * Linux: ~/.cache/cleo | macOS: ~/Library/Caches/cleo | Windows: %LOCALAPPDATA%\cleo\Cache
+ */
+export function getCleoCacheDir() {
+    return getPlatformPaths().cache;
+}
+/**
+ * Get the OS temp directory for CLEO ephemeral files.
+ */
+export function getCleoTempDir() {
+    return getPlatformPaths().temp;
+}
+/**
+ * Get the OS config directory for CLEO.
+ * Linux: ~/.config/cleo | macOS: ~/Library/Preferences/cleo | Windows: %APPDATA%\cleo\Config
+ */
+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)
+ */
+export function getCleoTemplatesTildePath() {
+    const absPath = getCleoTemplatesDir();
+    const home = homedir();
+    if (absPath.startsWith(home)) {
+        return `~${absPath.slice(home.length)}`;
+    }
+    return absPath;
+}
+// ============================================================================
+// Third-Party Tool Paths (OS-aware)
+// ============================================================================
+/**
+ * Get the global agents hub directory.
+ * Respects AGENTS_HOME env var, defaults to ~/.agents.
+ */
+export function getAgentsHome() {
+    return process.env['AGENTS_HOME'] ?? join(homedir(), '.agents');
+}
+/**
+ * Get the Claude Code agents directory (~/.claude/agents by default).
+ * @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.
+ * @deprecated Use AdapterPathProvider.getMemoryDbPath() from the active adapter instead.
+ * 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).
+ */
+export function getClaudeMemDbPath() {
+    return process.env['CLAUDE_MEM_DB'] ?? join(homedir(), '.claude-mem', 'claude-mem.db');
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}