@cleocode/core 2.0.0

package/src/otel/index.ts

@@ -0,0 +1,149 @@
+/**
+ * OpenTelemetry token metrics core module.
+ * @task T4535
+ * @epic T4454
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function getProjectRoot(): string {
+  let dir = process.cwd();
+  while (dir !== '/') {
+    if (existsSync(join(dir, '.cleo', 'config.json'))) return dir;
+    dir = join(dir, '..');
+  }
+  return process.cwd();
+}
+
+function getTokenFilePath(): string {
+  return join(getProjectRoot(), '.cleo', 'metrics', 'TOKEN_USAGE.jsonl');
+}
+
+function readJsonlFile(filePath: string): Record<string, unknown>[] {
+  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(): Promise<Record<string, unknown>> {
+  const tokenFile = getTokenFilePath();
+  const entries = readJsonlFile(tokenFile);
+  const totalTokens = entries.reduce((sum, e) => sum + ((e.estimated_tokens as number) ?? 0), 0);
+  const manifestTokens = entries
+    .filter((e) => e.event_type === 'manifest_read' || e.event_type === 'manifest_query')
+    .reduce((sum, e) => sum + ((e.estimated_tokens as number) ?? 0), 0);
+  const fullFileTokens = entries
+    .filter((e) => e.event_type === 'full_file_read')
+    .reduce((sum, e) => sum + ((e.estimated_tokens as number) ?? 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(): Promise<Record<string, unknown>> {
+  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 as number) ?? 0), 0);
+  const sessions = entries.filter((e) => e.event_type === 'session_start');
+  const spawns = entries.filter((e) => e.event_type !== 'session_start');
+
+  const byType: Record<string, { count: number; tokens: number }> = {};
+  for (const e of entries) {
+    const type = (e.event_type as string) ?? 'unknown';
+    if (!byType[type]) byType[type] = { count: 0, tokens: 0 };
+    byType[type]!.count++;
+    byType[type]!.tokens += (e.estimated_tokens as number) ?? 0;
+  }
+
+  return {
+    totalEvents: entries.length,
+    totalTokens,
+    sessions: {
+      count: sessions.length,
+      tokens: sessions.reduce((s, e) => s + ((e.estimated_tokens as number) ?? 0), 0),
+    },
+    spawns: {
+      count: spawns.length,
+      tokens: spawns.reduce((s, e) => s + ((e.estimated_tokens as number) ?? 0), 0),
+    },
+    byType: Object.entries(byType).map(([type, stats]) => ({ type, ...stats })),
+    file: tokenFile,
+  };
+}
+
+/** Get session-level token data. */
+export async function getOtelSessions(opts: {
+  session?: string;
+  task?: string;
+}): Promise<Record<string, unknown>> {
+  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 ?? {}) as Record<string, unknown>;
+      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: {
+  task?: string;
+  epic?: string;
+}): Promise<Record<string, unknown>> {
+  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: {
+  session?: string;
+  since?: string;
+}): Promise<Record<string, unknown>> {
+  // Real token usage requires OTel integration - return placeholder
+  return {
+    message: 'Real token usage requires OpenTelemetry configuration',
+    otelEnabled: process.env.CLAUDE_CODE_ENABLE_TELEMETRY === '1',
+  };
+}
+
+/** Clear token tracking data with backup. */
+export async function clearOtelData(): Promise<Record<string, unknown>> {
+  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' };
+}

package/src/output.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 type { LAFSMeta, LAFSPage, Warning } from '@cleocode/lafs-protocol';
+import type { LafsEnvelope, LafsError, LafsSuccess } from '@cleocode/contracts';
+import { CleoError } from './errors.js';
+import { getCurrentSessionId } from './sessions/context-alert.js';
+
+export type { LafsSuccess, LafsError, LafsEnvelope };
+
+/**
+ * Accumulated warnings for the current request.
+ * Reset on each formatSuccess/formatError call via drainWarnings().
+ *
+ * @task T4669
+ * @epic T4663
+ */
+const pendingWarnings: Warning[] = [];
+
+/**
+ * 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: Warning): void {
+  pendingWarnings.push(warning);
+}
+
+/**
+ * Drain all pending warnings (returns and clears the queue).
+ *
+ * @task T4669
+ * @epic T4663
+ */
+function drainWarnings(): Warning[] | undefined {
+  if (pendingWarnings.length === 0) return undefined;
+  const drained = [...pendingWarnings];
+  pendingWarnings.length = 0;
+  return drained;
+}
+
+/**
+ * Options for envelope formatting.
+ *
+ * @task T4668
+ * @task T4670
+ * @epic T4663
+ */
+export interface FormatOptions {
+  operation?: string;
+  page?: LAFSPage;
+  extensions?: Record<string, unknown>;
+  /** MVI level to embed in the envelope _meta. Defaults to 'standard'. @task T4957 */
+  mvi?: import('@cleocode/lafs-protocol').MVILevel;
+}
+
+/**
+ * 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: string,
+  mvi: import('@cleocode/lafs-protocol').MVILevel = 'standard',
+): LAFSMeta {
+  const warnings = drainWarnings();
+  const meta: LAFSMeta = {
+    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<T>(
+  data: T,
+  message?: string,
+  operationOrOpts?: string | FormatOptions,
+): string {
+  const opts: FormatOptions =
+    typeof operationOrOpts === 'string' ? { operation: operationOrOpts } : (operationOrOpts ?? {});
+
+  const envelope: Record<string, unknown> = {
+    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+    _meta: createCliMeta(opts.operation ?? 'cli.output', opts.mvi),
+    success: true as const,
+    result: data as Record<string, unknown> | Record<string, unknown>[] | null,
+    ...(message && { message }),
+  };
+  if (opts.page) {
+    envelope['page'] = opts.page;
+  }
+  if (opts.extensions && Object.keys(opts.extensions).length > 0) {
+    envelope['_extensions'] = opts.extensions;
+  }
+  return JSON.stringify(envelope);
+}
+
+/**
+ * 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: CleoError, operation?: string): string {
+  const envelope = {
+    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
+    _meta: createCliMeta(operation ?? 'cli.output'),
+    success: false as const,
+    result: null,
+    error: error.toLAFSError(),
+  };
+  return JSON.stringify(envelope);
+}
+
+/** Format any result (success or error) as LAFS JSON. */
+export function formatOutput<T>(result: T | CleoError): string {
+  if (result instanceof CleoError) {
+    return formatError(result);
+  }
+  return formatSuccess(result);
+}

package/src/pagination.ts

@@ -0,0 +1,90 @@
+/**
+ * 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
+ */
+
+import type { LAFSPage, LAFSPageNone, LAFSPageOffset } from '@cleocode/lafs-protocol';
+
+/**
+ * Input parameters for paginating a result set.
+ *
+ * @task T4668
+ * @epic T4663
+ */
+export interface PaginateInput {
+  /** Total number of items before pagination. */
+  total: number;
+  /** Number of items to return per page. */
+  limit?: number;
+  /** Number of items to skip. */
+  offset?: number;
+}
+
+/**
+ * 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: PaginateInput): LAFSPage {
+  const { total, limit, offset } = input;
+
+  // No pagination requested
+  if (limit === undefined && offset === undefined) {
+    return { mode: 'none' } as LAFSPageNone;
+  }
+
+  const effectiveLimit = limit ?? DEFAULT_LIMIT;
+  const effectiveOffset = offset ?? 0;
+  const hasMore = effectiveOffset + effectiveLimit < total;
+
+  return {
+    mode: 'offset',
+    limit: effectiveLimit,
+    offset: effectiveOffset,
+    hasMore,
+    total,
+  } as LAFSPageOffset;
+}
+
+/**
+ * Apply pagination to an array of items and return the sliced result with page metadata.
+ *
+ * @task T4668
+ * @epic T4663
+ */
+export function paginate<T>(
+  items: T[],
+  limit?: number,
+  offset?: number,
+): { items: T[]; page: LAFSPage } {
+  const total = items.length;
+
+  if (limit === undefined && offset === undefined) {
+    return { items, page: { mode: 'none' } as LAFSPageNone };
+  }
+
+  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 }),
+  };
+}