@cleocode/contracts 2.0.0

package/src/config.ts

@@ -0,0 +1,135 @@
+/**
+ * Configuration type definitions for CLEO.
+ *
+ * Covers project and global config with cascade resolution.
+ * These are stable types shared across core, dispatch, and CLI.
+ *
+ * @epic T4454
+ * @task T4456
+ * @task T5710
+ */
+
+/** Output format options. */
+export type OutputFormat = 'json' | 'text' | 'jsonl' | 'markdown' | 'table';
+
+/** Date format options. */
+export type DateFormat = 'relative' | 'iso' | 'short' | 'long';
+
+/** Output configuration. */
+export interface OutputConfig {
+  defaultFormat: OutputFormat;
+  showColor: boolean;
+  showUnicode: boolean;
+  showProgressBars: boolean;
+  dateFormat: DateFormat;
+}
+
+/** Backup configuration. */
+export interface BackupConfig {
+  maxOperationalBackups: number;
+  maxSafetyBackups: number;
+  compressionEnabled: boolean;
+}
+
+/** Hierarchy enforcement profile preset. */
+export type EnforcementProfile = 'llm-agent-first' | 'human-cognitive' | 'custom';
+
+/** Hierarchy configuration. */
+export interface HierarchyConfig {
+  maxDepth: number;
+  maxSiblings: number;
+  cascadeDelete: boolean;
+  /** Maximum number of active (non-done) siblings. 0 = disabled. */
+  maxActiveSiblings: number;
+  /** Whether done tasks count toward the sibling limit. */
+  countDoneInLimit: boolean;
+  /** Enforcement profile preset. Explicit fields override preset values. */
+  enforcementProfile: EnforcementProfile;
+}
+
+/** Session configuration. */
+export interface SessionConfig {
+  autoStart: boolean;
+  requireNotes: boolean;
+  multiSession: boolean;
+}
+
+/** Pino log levels. */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+
+/** Logging configuration. */
+export interface LoggingConfig {
+  /** Minimum log level to record (default: 'info') */
+  level: LogLevel;
+  /** Log file path relative to .cleo/ (default: 'logs/cleo.log') */
+  filePath: string;
+  /** Max log file size in bytes before rotation (default: 10MB) */
+  maxFileSize: number;
+  /** Number of rotated log files to retain (default: 5) */
+  maxFiles: number;
+  /** Days to retain audit_log rows before pruning (default: 90) */
+  auditRetentionDays: number;
+  /** Whether to archive pruned rows to compressed JSONL before deletion (default: true) */
+  archiveBeforePrune: boolean;
+}
+
+/** Lifecycle enforcement mode. */
+export type LifecycleEnforcementMode = 'strict' | 'advisory' | 'off';
+
+/** Lifecycle enforcement configuration. */
+export interface LifecycleConfig {
+  mode: LifecycleEnforcementMode;
+}
+
+/** Sharing mode: whether .cleo/ files are committed to the project git repo. */
+export type SharingMode = 'none' | 'project';
+
+/** Sharing configuration for multi-contributor .cleo/ state management. */
+export interface SharingConfig {
+  /** Sharing mode (default: 'none'). */
+  mode: SharingMode;
+  /** Files/patterns in .cleo/ to commit to project git (relative to .cleo/). */
+  commitAllowlist: string[];
+  /** Files/patterns to always exclude, even if in commitAllowlist. */
+  denylist: string[];
+}
+
+/** SignalDock transport mode. */
+export type SignalDockMode = 'http' | 'native';
+
+/** SignalDock integration configuration. */
+export interface SignalDockConfig {
+  /** Whether SignalDock transport is enabled (default: false). */
+  enabled: boolean;
+  /** Transport mode: 'http' for REST API client, 'native' for napi-rs bindings (default: 'http'). */
+  mode: SignalDockMode;
+  /** SignalDock API server endpoint (default: 'http://localhost:4000'). */
+  endpoint: string;
+  /** Prefix for CLEO agent names in SignalDock registry (default: 'cleo-'). */
+  agentPrefix: string;
+  /** Default privacy tier for registered agents (default: 'private'). */
+  privacyTier: 'public' | 'discoverable' | 'private';
+}
+
+/** CLEO project configuration (config.json). */
+export interface CleoConfig {
+  version: string;
+  output: OutputConfig;
+  backup: BackupConfig;
+  hierarchy: HierarchyConfig;
+  session: SessionConfig;
+  lifecycle: LifecycleConfig;
+  logging: LoggingConfig;
+  sharing: SharingConfig;
+  /** SignalDock inter-agent transport (optional, disabled by default). */
+  signaldock?: SignalDockConfig;
+}
+
+/** Configuration resolution priority. */
+export type ConfigSource = 'cli' | 'env' | 'project' | 'global' | 'default';
+
+/** A resolved config value with its source. */
+export interface ResolvedValue<T> {
+  value: T;
+  source: ConfigSource;
+}

package/src/context-monitor.ts

@@ -0,0 +1,16 @@
+/**
+ * Context monitor provider interface for CLEO provider adapters.
+ * Allows providers to implement context window tracking and statusline integration.
+ * @task T5240
+ */
+
+export interface AdapterContextMonitorProvider {
+  /** Process context window input and return a status string */
+  processContextInput(input: unknown, cwd?: string): Promise<string>;
+  /** Check if statusline integration is configured */
+  checkStatuslineIntegration(): 'configured' | 'not_configured' | 'custom_no_cleo' | 'no_settings';
+  /** Get the statusline configuration object */
+  getStatuslineConfig(): Record<string, unknown>;
+  /** Get human-readable setup instructions */
+  getSetupInstructions(): string;
+}

package/src/data-accessor.ts

@@ -0,0 +1,239 @@
+/**
+ * DataAccessor: File-level storage abstraction for core modules.
+ *
+ * Core modules operate on whole-file data structures (ArchiveFile, SessionsFile).
+ * The DataAccessor abstracts WHERE that data is stored (SQLite via Drizzle ORM)
+ * while preserving the read-modify-write pattern that core business logic relies on.
+ *
+ * This is the DRY/SOLID injection point: core modules accept a DataAccessor parameter
+ * instead of calling readJson/saveJson directly.
+ *
+ * Implementation: SqliteDataAccessor (materializes/dematerializes from SQLite tables)
+ *
+ * @epic T4454
+ */
+
+import type { ArchivedTask } from './archive.js';
+import type { Session } from './session.js';
+import type {
+  Task,
+  TaskPriority,
+  TaskSize,
+  TaskStatus,
+  TaskType,
+} from './task.js';
+
+/** Archive-specific fields for task upsert. */
+export interface ArchiveFields {
+  archivedAt?: string;
+  archiveReason?: string;
+  cycleTimeDays?: number | null;
+}
+
+/** Archive file structure. */
+export interface ArchiveFile {
+  archivedTasks: ArchivedTask[];
+  version?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Targeted query/mutation types (Phase 2 modernization)
+// ---------------------------------------------------------------------------
+
+/** Filter bag for queryTasks(). Covers ~90% of task query patterns. */
+export interface TaskQueryFilters {
+  status?: TaskStatus | TaskStatus[];
+  priority?: TaskPriority;
+  type?: TaskType;
+  parentId?: string | null; // null = root tasks only
+  phase?: string;
+  label?: string;
+  search?: string; // SQL LIKE on title+description
+  excludeStatus?: TaskStatus | TaskStatus[];
+  limit?: number;
+  offset?: number;
+  orderBy?: 'position' | 'createdAt' | 'updatedAt' | 'priority';
+}
+
+/** Result from queryTasks() with pagination support. */
+export interface QueryTasksResult {
+  tasks: Task[];
+  total: number;
+}
+
+/** Partial task row fields for updateTaskFields(). */
+export interface TaskFieldUpdates {
+  title?: string;
+  description?: string | null;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  type?: TaskType | null;
+  parentId?: string | null;
+  phase?: string | null;
+  size?: TaskSize | null;
+  position?: number | null;
+  positionVersion?: number;
+  labelsJson?: string;
+  notesJson?: string;
+  acceptanceJson?: string;
+  filesJson?: string;
+  origin?: string | null;
+  blockedBy?: string | null;
+  epicLifecycle?: string | null;
+  noAutoComplete?: boolean | null;
+  completedAt?: string | null;
+  cancelledAt?: string | null;
+  cancellationReason?: string | null;
+  verificationJson?: string | null;
+  createdBy?: string | null;
+  modifiedBy?: string | null;
+  sessionId?: string | null;
+  updatedAt?: string | null;
+}
+
+/**
+ * Subset of DataAccessor methods available inside a transaction callback.
+ * Write-only — reads use the outer accessor (snapshot isolation).
+ */
+export interface TransactionAccessor {
+  upsertSingleTask(task: Task): Promise<void>;
+  archiveSingleTask(taskId: string, fields: ArchiveFields): Promise<void>;
+  removeSingleTask(taskId: string): Promise<void>;
+  setMetaValue(key: string, value: unknown): Promise<void>;
+  updateTaskFields(taskId: string, fields: TaskFieldUpdates): Promise<void>;
+  appendLog(entry: Record<string, unknown>): Promise<void>;
+}
+
+/**
+ * DataAccessor interface.
+ *
+ * Core modules call these methods instead of readJson/saveJson.
+ * Each method maps directly to the file-level operations that
+ * core modules already perform.
+ */
+export interface DataAccessor {
+  /** The storage engine backing this accessor. */
+  readonly engine: 'sqlite';
+
+  // ---- Archive data ----
+
+  /** Load the archive file. Returns null if archive doesn't exist. */
+  loadArchive(): Promise<ArchiveFile | null>;
+
+  /** Save the archive file atomically. Creates backup before write. */
+  saveArchive(data: ArchiveFile): Promise<void>;
+
+  // ---- Session data ----
+
+  /** Load all sessions from the store. Returns empty array if none exist. */
+  loadSessions(): Promise<Session[]>;
+
+  /** Save all sessions to the store atomically. */
+  saveSessions(sessions: Session[]): Promise<void>;
+
+  // ---- Audit log ----
+
+  /** Append an entry to the audit log. */
+  appendLog(entry: Record<string, unknown>): Promise<void>;
+
+  // ---- Lifecycle ----
+
+  /** Release any resources (close DB connections, etc.). */
+  close(): Promise<void>;
+
+  // ---- Fine-grained task operations (T5034) ----
+
+  /** Upsert a single task (targeted write, no full-file reload). */
+  upsertSingleTask(task: Task): Promise<void>;
+
+  /** Archive a single task by ID (sets status='archived' + archive metadata). */
+  archiveSingleTask(taskId: string, fields: ArchiveFields): Promise<void>;
+
+  /** Delete a single task permanently from the tasks table. */
+  removeSingleTask(taskId: string): Promise<void>;
+
+  /** Load a single task by ID with its dependencies and relations. Returns null if not found. */
+  loadSingleTask(taskId: string): Promise<Task | null>;
+
+  /** Insert a row into the task_relations table (T5168). */
+  addRelation(
+    taskId: string,
+    relatedTo: string,
+    relationType: string,
+    reason?: string,
+  ): Promise<void>;
+
+  // ---- Metadata (schema_meta KV store) ----
+
+  /** Read a typed value from the metadata store. Returns null if not found. */
+  getMetaValue<T>(key: string): Promise<T | null>;
+
+  /** Write a typed value to the metadata store. */
+  setMetaValue(key: string, value: unknown): Promise<void>;
+
+  /** Read the schema version from metadata. Convenience for getMetaValue('schema_version'). */
+  getSchemaVersion(): Promise<string | null>;
+
+  // ---- Targeted query methods (Phase 2 modernization) ----
+
+  /** Query tasks with filters, pagination, and ordering. Returns matching tasks + total count. */
+  queryTasks(filters: TaskQueryFilters): Promise<QueryTasksResult>;
+
+  /** Count tasks matching optional filters. Excludes archived by default. */
+  countTasks(filters?: { status?: TaskStatus | TaskStatus[]; parentId?: string }): Promise<number>;
+
+  /** Get direct children of a parent task. */
+  getChildren(parentId: string): Promise<Task[]>;
+
+  /** Count direct children of a parent task (all statuses except archived). */
+  countChildren(parentId: string): Promise<number>;
+
+  /** Count active (non-terminal) children of a parent task. */
+  countActiveChildren(parentId: string): Promise<number>;
+
+  /** Get ancestor chain from task to root via WITH RECURSIVE CTE. Ordered root-first. */
+  getAncestorChain(taskId: string): Promise<Task[]>;
+
+  /** Get full subtree rooted at taskId via WITH RECURSIVE CTE. Includes root. */
+  getSubtree(rootId: string): Promise<Task[]>;
+
+  /** Get tasks that depend on (are blocked by) the given task. Reverse dep lookup. */
+  getDependents(taskId: string): Promise<Task[]>;
+
+  /** Get transitive dependency chain via WITH RECURSIVE CTE. Returns task IDs. */
+  getDependencyChain(taskId: string): Promise<string[]>;
+
+  /** Check if a task exists (any status including archived). */
+  taskExists(taskId: string): Promise<boolean>;
+
+  /** Load multiple tasks by ID in a single batch query. */
+  loadTasks(taskIds: string[]): Promise<Task[]>;
+
+  // ---- Targeted write methods (Phase 2 modernization) ----
+
+  /** Update specific fields on a task without full load/save cycle. */
+  updateTaskFields(taskId: string, fields: TaskFieldUpdates): Promise<void>;
+
+  /** Get next available position for a task within a parent scope (SQL-level, race-safe). */
+  getNextPosition(parentId: string | null): Promise<number>;
+
+  /** Shift positions of siblings >= fromPosition by delta (bulk SQL update). */
+  shiftPositions(parentId: string | null, fromPosition: number, delta: number): Promise<void>;
+
+  /** Execute a function inside a SQLite transaction (BEGIN IMMEDIATE / COMMIT / ROLLBACK). */
+  transaction<T>(fn: (tx: TransactionAccessor) => Promise<T>): Promise<T>;
+
+  // ---- Fine-grained session operations ----
+
+  /** Get the currently active session (status='active', most recent). */
+  getActiveSession(): Promise<Session | null>;
+
+  /** Upsert a single session (targeted write). */
+  upsertSingleSession(session: Session): Promise<void>;
+
+  /** Remove a single session by ID. */
+  removeSingleSession(sessionId: string): Promise<void>;
+}
+
+// Factory functions (createDataAccessor, getAccessor) live in @cleocode/core,
+// not here. Contracts is types-only.

package/src/discovery.ts

@@ -0,0 +1,31 @@
+/**
+ * Adapter manifest and discovery contracts for CLEO provider adapters.
+ *
+ * @task T5240
+ */
+
+import type { AdapterCapabilities } from './capabilities.js';
+
+export interface AdapterManifest {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  /** Provider identifier, e.g. "claude-code", "opencode", "cursor" */
+  provider: string;
+  /** Relative path to the main adapter module */
+  entryPoint: string;
+  /**
+   * Resolved absolute path to the adapter package root.
+   * Populated at discovery time by discoverAdapterManifests().
+   */
+  packagePath: string;
+  capabilities: AdapterCapabilities;
+  detectionPatterns: DetectionPattern[];
+}
+
+export interface DetectionPattern {
+  type: 'env' | 'file' | 'process' | 'cli';
+  pattern: string;
+  description: string;
+}

package/src/exit-codes.ts

@@ -0,0 +1,175 @@
+/**
+ * CLEO exit codes — canonical definitions shared across all layers.
+ *
+ * Ranges: 0 = success, 1-99 = errors, 100+ = special (non-error) states.
+ *
+ * @epic T4454
+ * @task T4456
+ * @task T5710
+ */
+
+export enum ExitCode {
+  // === SUCCESS (0) ===
+  SUCCESS = 0,
+
+  // === GENERAL ERRORS (1-9) ===
+  GENERAL_ERROR = 1,
+  INVALID_INPUT = 2,
+  FILE_ERROR = 3,
+  NOT_FOUND = 4,
+  DEPENDENCY_ERROR = 5,
+  VALIDATION_ERROR = 6,
+  LOCK_TIMEOUT = 7,
+  CONFIG_ERROR = 8,
+
+  // === HIERARCHY ERRORS (10-19) ===
+  PARENT_NOT_FOUND = 10,
+  DEPTH_EXCEEDED = 11,
+  SIBLING_LIMIT = 12,
+  INVALID_PARENT_TYPE = 13,
+  CIRCULAR_REFERENCE = 14,
+  ORPHAN_DETECTED = 15,
+  HAS_CHILDREN = 16,
+  TASK_COMPLETED = 17,
+  CASCADE_FAILED = 18,
+  HAS_DEPENDENTS = 19,
+
+  // === CONCURRENCY ERRORS (20-29) ===
+  CHECKSUM_MISMATCH = 20,
+  CONCURRENT_MODIFICATION = 21,
+  ID_COLLISION = 22,
+
+  // === SESSION ERRORS (30-39) ===
+  SESSION_EXISTS = 30,
+  SESSION_NOT_FOUND = 31,
+  SCOPE_CONFLICT = 32,
+  SCOPE_INVALID = 33,
+  TASK_NOT_IN_SCOPE = 34,
+  TASK_CLAIMED = 35,
+  SESSION_REQUIRED = 36,
+  SESSION_CLOSE_BLOCKED = 37,
+  ACTIVE_TASK_REQUIRED = 38,
+  NOTES_REQUIRED = 39,
+
+  // === VERIFICATION ERRORS (40-47) ===
+  VERIFICATION_INIT_FAILED = 40,
+  GATE_UPDATE_FAILED = 41,
+  INVALID_GATE = 42,
+  INVALID_AGENT = 43,
+  MAX_ROUNDS_EXCEEDED = 44,
+  GATE_DEPENDENCY = 45,
+  VERIFICATION_LOCKED = 46,
+  ROUND_MISMATCH = 47,
+
+  // === CONTEXT SAFEGUARD (50-54) ===
+  CONTEXT_WARNING = 50,
+  CONTEXT_CAUTION = 51,
+  CONTEXT_CRITICAL = 52,
+  CONTEXT_EMERGENCY = 53,
+  CONTEXT_STALE = 54,
+
+  // === ORCHESTRATOR ERRORS (60-67) ===
+  PROTOCOL_MISSING = 60,
+  INVALID_RETURN_MESSAGE = 61,
+  MANIFEST_ENTRY_MISSING = 62,
+  SPAWN_VALIDATION_FAILED = 63,
+  AUTONOMOUS_BOUNDARY = 64,
+  HANDOFF_REQUIRED = 65,
+  RESUME_FAILED = 66,
+  CONCURRENT_SESSION = 67,
+
+  // === NEXUS ERRORS (70-79) ===
+  NEXUS_NOT_INITIALIZED = 70,
+  NEXUS_PROJECT_NOT_FOUND = 71,
+  NEXUS_PERMISSION_DENIED = 72,
+  NEXUS_INVALID_SYNTAX = 73,
+  NEXUS_SYNC_FAILED = 74,
+  NEXUS_REGISTRY_CORRUPT = 75,
+  NEXUS_PROJECT_EXISTS = 76,
+  NEXUS_QUERY_FAILED = 77,
+  NEXUS_GRAPH_ERROR = 78,
+  NEXUS_RESERVED = 79,
+
+  // === LIFECYCLE ENFORCEMENT (80-84) ===
+  LIFECYCLE_GATE_FAILED = 80,
+  AUDIT_MISSING = 81,
+  CIRCULAR_VALIDATION = 82,
+  LIFECYCLE_TRANSITION_INVALID = 83,
+  PROVENANCE_REQUIRED = 84,
+
+  // === ARTIFACT PUBLISH (85-89) ===
+  ARTIFACT_TYPE_UNKNOWN = 85,
+  ARTIFACT_VALIDATION_FAILED = 86,
+  ARTIFACT_BUILD_FAILED = 87,
+  ARTIFACT_PUBLISH_FAILED = 88,
+  ARTIFACT_ROLLBACK_FAILED = 89,
+
+  // === PROVENANCE (90-94) ===
+  PROVENANCE_CONFIG_INVALID = 90,
+  SIGNING_KEY_MISSING = 91,
+  SIGNATURE_INVALID = 92,
+  DIGEST_MISMATCH = 93,
+  ATTESTATION_INVALID = 94,
+
+  // === ADAPTER ERRORS (95-99) ===
+  ADAPTER_NOT_FOUND = 95,
+  ADAPTER_INIT_FAILED = 96,
+  ADAPTER_HOOK_FAILED = 97,
+  ADAPTER_SPAWN_FAILED = 98,
+  ADAPTER_INSTALL_FAILED = 99,
+
+  // === SPECIAL CODES (100+) - NOT errors ===
+  NO_DATA = 100,
+  ALREADY_EXISTS = 101,
+  NO_CHANGE = 102,
+  TESTS_SKIPPED = 103,
+}
+
+/** Check if an exit code represents an error (1-99). */
+export function isErrorCode(code: ExitCode): boolean {
+  return code >= 1 && code < 100;
+}
+
+/** Check if an exit code represents success (0 or 100+). */
+export function isSuccessCode(code: ExitCode): boolean {
+  return code === 0 || code >= 100;
+}
+
+/** Check if an exit code indicates no change (idempotent operation). */
+export function isNoChangeCode(code: ExitCode): boolean {
+  return code === ExitCode.NO_CHANGE;
+}
+
+/** Check if an exit code is recoverable (retry may succeed). */
+export function isRecoverableCode(code: ExitCode): boolean {
+  const nonRecoverable = new Set<ExitCode>([
+    ExitCode.FILE_ERROR,
+    ExitCode.DEPENDENCY_ERROR,
+    ExitCode.CIRCULAR_REFERENCE,
+    ExitCode.CASCADE_FAILED,
+    ExitCode.SESSION_CLOSE_BLOCKED,
+    ExitCode.VERIFICATION_LOCKED,
+    ExitCode.CONTEXT_WARNING,
+    ExitCode.CONTEXT_CAUTION,
+    ExitCode.CONTEXT_CRITICAL,
+    ExitCode.CONTEXT_EMERGENCY,
+    ExitCode.CONTEXT_STALE,
+    ExitCode.AUTONOMOUS_BOUNDARY,
+    ExitCode.HANDOFF_REQUIRED,
+    ExitCode.NEXUS_PERMISSION_DENIED,
+    ExitCode.NEXUS_REGISTRY_CORRUPT,
+    ExitCode.CIRCULAR_VALIDATION,
+    ExitCode.LIFECYCLE_TRANSITION_INVALID,
+    ExitCode.ARTIFACT_TYPE_UNKNOWN,
+    ExitCode.ARTIFACT_ROLLBACK_FAILED,
+    ExitCode.DIGEST_MISMATCH,
+  ]);
+
+  if (!isErrorCode(code)) return false;
+  return !nonRecoverable.has(code);
+}
+
+/** Human-readable name for an exit code. */
+export function getExitCodeName(code: ExitCode): string {
+  return ExitCode[code] ?? 'UNKNOWN';
+}

package/src/hooks.ts

@@ -0,0 +1,17 @@
+/**
+ * Hook provider interface for CLEO provider adapters.
+ * Maps provider-specific events to CAAMP hook events.
+ *
+ * @task T5240
+ */
+
+export interface AdapterHookProvider {
+  /** Map a provider-specific event name to a CAAMP hook event name, or null if unmapped. */
+  mapProviderEvent(providerEvent: string): string | null;
+  /** Register the provider's native hook mechanism for a project. */
+  registerNativeHooks(projectDir: string): Promise<void>;
+  /** Unregister all native hooks previously registered. */
+  unregisterNativeHooks(): Promise<void>;
+  /** Return the full event mapping for introspection. */
+  getEventMap?(): Readonly<Record<string, string>>;
+}