@cleocode/core 2026.4.9 → 2026.4.12

package/dist/otel/index.js

@@ -0,0 +1,163 @@
+/**
+ * OpenTelemetry token metrics core module.
+ * @task T4535
+ * @epic T4454
+ */
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+function getProjectRoot() {
+    let dir = process.cwd();
+    while (dir !== '/') {
+        if (existsSync(join(dir, '.cleo', 'config.json')))
+            return dir;
+        dir = join(dir, '..');
+    }
+    return process.cwd();
+}
+function getTokenFilePath() {
+    return join(getProjectRoot(), '.cleo', 'metrics', 'TOKEN_USAGE.jsonl');
+}
+function readJsonlFile(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const content = readFileSync(filePath, 'utf-8').trim();
+    if (!content)
+        return [];
+    return content.split('\n').map((line) => JSON.parse(line));
+}
+/** Get token tracking status. */
+export async function getOtelStatus() {
+    const tokenFile = getTokenFilePath();
+    const entries = readJsonlFile(tokenFile);
+    const totalTokens = entries.reduce((sum, e) => sum + (e.estimated_tokens ?? 0), 0);
+    const manifestTokens = entries
+        .filter((e) => e.event_type === 'manifest_read' || e.event_type === 'manifest_query')
+        .reduce((sum, e) => sum + (e.estimated_tokens ?? 0), 0);
+    const fullFileTokens = entries
+        .filter((e) => e.event_type === 'full_file_read')
+        .reduce((sum, e) => sum + (e.estimated_tokens ?? 0), 0);
+    return {
+        file: tokenFile,
+        events: entries.length,
+        totalTokens,
+        breakdown: {
+            manifestReads: manifestTokens,
+            fullFileReads: fullFileTokens,
+            other: totalTokens - manifestTokens - fullFileTokens,
+        },
+    };
+}
+/** Get combined token usage summary. */
+export async function getOtelSummary() {
+    const tokenFile = getTokenFilePath();
+    const entries = readJsonlFile(tokenFile);
+    if (entries.length === 0) {
+        return { message: 'No token tracking data yet', events: 0 };
+    }
+    const totalTokens = entries.reduce((sum, e) => sum + (e.estimated_tokens ?? 0), 0);
+    const sessions = entries.filter((e) => e.event_type === 'session_start');
+    const spawns = entries.filter((e) => e.event_type !== 'session_start');
+    const byType = {};
+    for (const e of entries) {
+        const type = e.event_type ?? 'unknown';
+        if (!byType[type])
+            byType[type] = { count: 0, tokens: 0 };
+        byType[type].count++;
+        byType[type].tokens += e.estimated_tokens ?? 0;
+    }
+    return {
+        totalEvents: entries.length,
+        totalTokens,
+        sessions: {
+            count: sessions.length,
+            tokens: sessions.reduce((s, e) => s + (e.estimated_tokens ?? 0), 0),
+        },
+        spawns: {
+            count: spawns.length,
+            tokens: spawns.reduce((s, e) => s + (e.estimated_tokens ?? 0), 0),
+        },
+        byType: Object.entries(byType).map(([type, stats]) => ({ type, ...stats })),
+        file: tokenFile,
+    };
+}
+/** Get session-level token data. */
+export async function getOtelSessions(opts) {
+    const entries = readJsonlFile(getTokenFilePath());
+    let sessions = entries.filter((e) => e.event_type === 'session_start');
+    if (opts.session) {
+        sessions = sessions.filter((e) => {
+            const ctx = (e.context ?? {});
+            return ctx.session_id === opts.session;
+        });
+    }
+    if (opts.task) {
+        sessions = sessions.filter((e) => e.task_id === opts.task);
+    }
+    return { sessions, count: sessions.length };
+}
+/** Get spawn-level token data. */
+export async function getOtelSpawns(opts) {
+    const entries = readJsonlFile(getTokenFilePath());
+    let spawns = entries.filter((e) => e.event_type !== 'session_start');
+    if (opts.task) {
+        spawns = spawns.filter((e) => e.task_id === opts.task);
+    }
+    return { spawns, count: spawns.length };
+}
+/** Get real token usage from Claude Code API. */
+export async function getRealTokenUsage(opts) {
+    const otelEnabled = process.env.CLAUDE_CODE_ENABLE_TELEMETRY === '1';
+    // Read JSONL token data and filter by opts
+    const entries = readJsonlFile(getTokenFilePath());
+    if (entries.length === 0) {
+        return {
+            message: otelEnabled
+                ? 'OTel enabled but no token data recorded yet'
+                : 'Real token usage requires OpenTelemetry configuration',
+            otelEnabled,
+            totalEvents: 0,
+        };
+    }
+    let filtered = entries;
+    // Filter by session if provided
+    if (opts.session) {
+        filtered = filtered.filter((e) => {
+            const ctx = (e.context ?? {});
+            return ctx.session_id === opts.session || e.session_id === opts.session;
+        });
+    }
+    // Filter by since timestamp if provided
+    if (opts.since) {
+        const sinceDate = new Date(opts.since).getTime();
+        filtered = filtered.filter((e) => {
+            const ts = (e.timestamp ?? e.recorded_at);
+            return ts ? new Date(ts).getTime() >= sinceDate : true;
+        });
+    }
+    const totalTokens = filtered.reduce((sum, e) => sum + (e.estimated_tokens ?? 0), 0);
+    const inputTokens = filtered.reduce((sum, e) => sum + (e.input_tokens ?? 0), 0);
+    const outputTokens = filtered.reduce((sum, e) => sum + (e.output_tokens ?? 0), 0);
+    return {
+        otelEnabled,
+        totalEvents: filtered.length,
+        totalTokens,
+        inputTokens,
+        outputTokens,
+        filters: {
+            session: opts.session ?? null,
+            since: opts.since ?? null,
+        },
+    };
+}
+/** Clear token tracking data with backup. */
+export async function clearOtelData() {
+    const tokenFile = getTokenFilePath();
+    if (existsSync(tokenFile)) {
+        const backup = `${tokenFile}.backup-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        copyFileSync(tokenFile, backup);
+        writeFileSync(tokenFile, '');
+        return { message: 'Token tracking cleared', backup };
+    }
+    return { message: 'No token file to clear' };
+}
+//# sourceMappingURL=index.js.map

package/dist/otel/index.js.map

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

package/dist/output.d.ts

@@ -4,18 +4,24 @@
  * 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.
+ * All envelopes use the canonical CLI envelope shape:
+ *   { success, data?, error?, meta, page? }
+ *
+ * This replaces the three legacy shapes:
+ *   {ok, r, _m}            (minimal MVI — removed)
+ *   {$schema, _meta, success, result}  (full LAFS — now uses meta/data)
+ *   {success, result}      (observe command — now uses data)
  *
  * Types are re-exported from the canonical source in src/types/lafs.ts.
  *
  * @epic T4663
  * @task T4672
+ * @task T338 (ADR-039 envelope unification)
  */
 import type { LafsEnvelope, LafsError, LafsSuccess } from '@cleocode/contracts';
-import type { LAFSPage, Warning } from '@cleocode/lafs';
+import type { CliEnvelope, CliEnvelopeError, CliMeta, LAFSPage, Warning } from '@cleocode/lafs';
 import { CleoError } from './errors.js';
-export type { LafsEnvelope, LafsError, LafsSuccess };
+export type { CliEnvelope, CliEnvelopeError, CliMeta, LafsEnvelope, LafsError, LafsSuccess };
 /**
  * Push a deprecation or informational warning into the current envelope.
  * Warnings are drained (consumed) by the next formatSuccess/formatError call.
@@ -39,25 +45,40 @@ export interface FormatOptions {
     mvi?: import('@cleocode/lafs').MVILevel;
 }
 /**
- * Format a successful result as a full LAFS-conformant envelope.
+ * Format a successful result as a canonical CLI envelope.
+ *
+ * Produces the unified `CliEnvelope<T>` shape: `{success, data, meta, page?}`.
+ * This replaces all three legacy shapes (minimal `{ok,r,_m}`, full `{$schema,_meta,result}`,
+ * and observe `{success,result}`) with a single canonical format (ADR-039).
  *
- * Always produces the full LAFSEnvelope with $schema and _meta.
- * When operation is omitted, defaults to 'cli.output'.
- * Supports optional page (T4668) and _extensions (T4670).
+ * The `mvi` option in `FormatOptions` is accepted for backward compatibility but
+ * no longer affects the envelope shape — the canonical shape is always emitted.
+ *
+ * @param data - The operation result payload.
+ * @param message - Optional success message (attached to `meta.message`).
+ * @param operationOrOpts - Operation name string or `FormatOptions` object.
+ * @returns JSON-serialized `CliEnvelope<T>`.
  *
  * @task T4672
  * @task T4668
  * @task T4670
+ * @task T338
  * @epic T4663
  */
 export declare function formatSuccess<T>(data: T, message?: string, operationOrOpts?: string | FormatOptions): string;
 /**
- * Format an error as a full LAFS-conformant envelope.
+ * Format an error as a canonical CLI error envelope.
+ *
+ * Produces `{success: false, error: CliEnvelopeError, meta: CliMeta}`.
+ * Every error envelope now always includes `meta` (ADR-039).
+ * When operation is omitted, defaults to `'cli.output'`.
  *
- * Always produces the full LAFSEnvelope with $schema and _meta.
- * When operation is omitted, defaults to 'cli.output'.
+ * @param error - The `CleoError` to format.
+ * @param operation - Optional dot-delimited operation identifier.
+ * @returns JSON-serialized error `CliEnvelope`.
  *
  * @task T4672
+ * @task T338
  * @epic T4663
  */
 export declare function formatError(error: CleoError, operation?: string): string;

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,EAAY,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAWrD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAeD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oFAAoF;IACpF,GAAG,CAAC,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CACzC;AAkCD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,GAAG,aAAa,GACvC,MAAM,CAmDR;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CASxE;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,MAAM,CAK7D"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAW7F;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAeD;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,oFAAoF;IACpF,GAAG,CAAC,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAC;CACzC;AAmCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,GAAG,aAAa,GACvC,MAAM,CAcR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAsBxE;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,GAAG,MAAM,CAK7D"}

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 use the canonical CLI envelope shape:
+ *   { success, data?, error?, meta, page? }
+ *
+ * This replaces the three legacy shapes:
+ *   {ok, r, _m}            (minimal MVI — removed)
+ *   {$schema, _meta, success, result}  (full LAFS — now uses meta/data)
+ *   {success, result}      (observe command — now uses data)
+ *
+ * Types are re-exported from the canonical source in src/types/lafs.ts.
+ *
+ * @epic T4663
+ * @task T4672
+ * @task T338 (ADR-039 envelope unification)
+ */
+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 canonical `CliMeta` object for CLI envelopes.
+ *
+ * Includes sessionId (T4702) and warnings (T4669) when present.
+ * Drains the pending warnings queue so they are included in the current envelope.
+ *
+ * @param operation - Dot-delimited operation identifier (e.g. `"tasks.show"`).
+ * @param duration_ms - Wall-clock duration in milliseconds. Defaults to 0.
+ * @returns A fully populated {@link CliMeta} object.
+ *
+ * @task T4700
+ * @task T4702
+ * @task T338
+ * @epic T4663
+ */
+function createCliMeta(operation, duration_ms = 0) {
+    const warnings = drainWarnings();
+    const meta = {
+        operation,
+        requestId: randomUUID(),
+        duration_ms,
+        timestamp: new Date().toISOString(),
+    };
+    const sessionId = getCurrentSessionId();
+    if (sessionId) {
+        meta['sessionId'] = sessionId;
+    }
+    if (warnings && warnings.length > 0) {
+        meta['warnings'] = warnings;
+    }
+    return meta;
+}
+/**
+ * Format a successful result as a canonical CLI envelope.
+ *
+ * Produces the unified `CliEnvelope<T>` shape: `{success, data, meta, page?}`.
+ * This replaces all three legacy shapes (minimal `{ok,r,_m}`, full `{$schema,_meta,result}`,
+ * and observe `{success,result}`) with a single canonical format (ADR-039).
+ *
+ * The `mvi` option in `FormatOptions` is accepted for backward compatibility but
+ * no longer affects the envelope shape — the canonical shape is always emitted.
+ *
+ * @param data - The operation result payload.
+ * @param message - Optional success message (attached to `meta.message`).
+ * @param operationOrOpts - Operation name string or `FormatOptions` object.
+ * @returns JSON-serialized `CliEnvelope<T>`.
+ *
+ * @task T4672
+ * @task T4668
+ * @task T4670
+ * @task T338
+ * @epic T4663
+ */
+export function formatSuccess(data, message, operationOrOpts) {
+    const opts = typeof operationOrOpts === 'string' ? { operation: operationOrOpts } : (operationOrOpts ?? {});
+    const meta = createCliMeta(opts.operation ?? 'cli.output');
+    const envelope = {
+        success: true,
+        data,
+        meta: message ? { ...meta, message } : meta,
+        ...(opts.page && { page: opts.page }),
+    };
+    return JSON.stringify(envelope);
+}
+/**
+ * Format an error as a canonical CLI error envelope.
+ *
+ * Produces `{success: false, error: CliEnvelopeError, meta: CliMeta}`.
+ * Every error envelope now always includes `meta` (ADR-039).
+ * When operation is omitted, defaults to `'cli.output'`.
+ *
+ * @param error - The `CleoError` to format.
+ * @param operation - Optional dot-delimited operation identifier.
+ * @returns JSON-serialized error `CliEnvelope`.
+ *
+ * @task T4672
+ * @task T338
+ * @epic T4663
+ */
+export function formatError(error, operation) {
+    const lafsError = error.toLAFSError();
+    const errorObj = {
+        code: lafsError.code,
+        message: lafsError.message,
+        details: lafsError.details,
+    };
+    if ('category' in lafsError && lafsError.category) {
+        errorObj['category'] = lafsError.category;
+    }
+    if ('retryable' in lafsError) {
+        errorObj['retryable'] = lafsError.retryable;
+    }
+    if ('agentAction' in lafsError && lafsError.agentAction) {
+        errorObj['agentAction'] = lafsError.agentAction;
+    }
+    const envelope = {
+        success: false,
+        error: errorObj,
+        meta: createCliMeta(operation ?? 'cli.output'),
+    };
+    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.d.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
@@ -124,20 +130,44 @@ export declare function getCleoDir(cwd?: string): string;
  */
 export declare 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 declare function getProjectRoot(cwd?: string): string;

package/dist/paths.d.ts.map

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