@cleocode/contracts 2.0.0

package/src/index.ts

@@ -0,0 +1,298 @@
+/**
+ * @cleocode/contracts — Domain types, interfaces, and contracts for the CLEO ecosystem.
+ *
+ * This is the LEAF package in the dependency graph — ZERO runtime dependencies.
+ * All domain types (Task, Session, DataAccessor, etc.) are defined here.
+ * Implementation packages (@cleocode/core, @cleocode/cleo) import from here.
+ */
+
+// === Status Registry (MUST be first — everything depends on this) ===
+export {
+  // Constants
+  TASK_STATUSES,
+  SESSION_STATUSES,
+  LIFECYCLE_PIPELINE_STATUSES,
+  LIFECYCLE_STAGE_STATUSES,
+  ADR_STATUSES,
+  GATE_STATUSES,
+  MANIFEST_STATUSES,
+  // Derived types
+  type TaskStatus,
+  type SessionStatus,
+  type PipelineStatus,
+  type StageStatus,
+  type AdrStatus,
+  type GateStatus,
+  type ManifestStatus,
+  // Terminal state sets
+  TERMINAL_TASK_STATUSES,
+  TERMINAL_PIPELINE_STATUSES,
+  TERMINAL_STAGE_STATUSES,
+  // Registry
+  type EntityType,
+  STATUS_REGISTRY,
+  isValidStatus,
+  // Display icons
+  PIPELINE_STATUS_ICONS,
+  STAGE_STATUS_ICONS,
+  TASK_STATUS_SYMBOLS_UNICODE,
+  TASK_STATUS_SYMBOLS_ASCII,
+} from './status-registry.js';
+
+// === Task Types ===
+export type {
+  TaskPriority,
+  TaskType,
+  TaskSize,
+  EpicLifecycle,
+  TaskOrigin,
+  VerificationAgent,
+  VerificationGate,
+  VerificationFailure,
+  TaskVerification,
+  TaskProvenance,
+  TaskRelation,
+  Task,
+  TaskCreate,
+  CompletedTask,
+  CancelledTask,
+  PhaseStatus,
+  Phase,
+  PhaseTransition,
+  ReleaseStatus,
+  Release,
+  ProjectMeta,
+  FileMeta,
+  SessionNote,
+  TaskWorkState,
+  TaskFile,
+} from './task.js';
+
+// === Session Types ===
+export { SessionView } from './session.js';
+export type {
+  SessionScope,
+  SessionStats,
+  SessionTaskWork,
+  Session,
+} from './session.js';
+
+// === Exit Codes ===
+export {
+  ExitCode,
+  isErrorCode,
+  isSuccessCode,
+  isNoChangeCode,
+  isRecoverableCode,
+  getExitCodeName,
+} from './exit-codes.js';
+
+// === Configuration Types ===
+export type {
+  OutputFormat,
+  DateFormat,
+  OutputConfig,
+  BackupConfig,
+  EnforcementProfile,
+  HierarchyConfig,
+  SessionConfig,
+  LogLevel,
+  LoggingConfig,
+  LifecycleEnforcementMode,
+  LifecycleConfig,
+  SharingMode,
+  SharingConfig,
+  SignalDockMode,
+  SignalDockConfig,
+  CleoConfig,
+  ConfigSource,
+  ResolvedValue,
+} from './config.js';
+
+// === LAFS Envelope Types ===
+export {
+  isLafsSuccess,
+  isLafsError,
+  isGatewayEnvelope,
+} from './lafs.js';
+export type {
+  LAFSErrorCategory,
+  LAFSError,
+  Warning,
+  LAFSTransport,
+  MVILevel,
+  LAFSPageNone,
+  LAFSPageOffset,
+  LAFSPage,
+  LAFSMeta,
+  LAFSEnvelope,
+  FlagInput,
+  ConformanceReport,
+  LafsAlternative,
+  LafsErrorDetail,
+  LafsSuccess,
+  LafsError,
+  LafsEnvelope,
+  GatewayMeta,
+  GatewaySuccess,
+  GatewayError,
+  GatewayEnvelope,
+  CleoResponse,
+} from './lafs.js';
+
+// === DataAccessor Interface ===
+export type {
+  ArchiveFields,
+  ArchiveFile,
+  TaskQueryFilters,
+  QueryTasksResult,
+  TaskFieldUpdates,
+  TransactionAccessor,
+  DataAccessor,
+} from './data-accessor.js';
+
+// === Provider Adapter Contracts ===
+export type { CLEOProviderAdapter, AdapterHealthStatus } from './adapter.js';
+export type { AdapterCapabilities } from './capabilities.js';
+export type { AdapterManifest, DetectionPattern } from './discovery.js';
+export type { AdapterHookProvider } from './hooks.js';
+export type { AdapterInstallProvider, InstallOptions, InstallResult } from './install.js';
+export type {
+  MemoryBridgeConfig,
+  MemoryBridgeContent,
+  SessionSummary,
+  BridgeLearning,
+  BridgePattern,
+  BridgeDecision,
+  BridgeObservation,
+} from './memory.js';
+export type { AdapterSpawnProvider, SpawnContext, SpawnResult } from './spawn.js';
+export type { AdapterPathProvider } from './provider-paths.js';
+export type { AdapterContextMonitorProvider } from './context-monitor.js';
+export type { AdapterTransportProvider } from './transport.js';
+
+// === CLEO Spawn Types (distinct from adapter spawn) ===
+export type {
+  Provider,
+  CAAMPSpawnOptions,
+  CAAMPSpawnResult,
+  CLEOSpawnContext,
+  CLEOSpawnResult,
+  CLEOSpawnAdapter,
+  TokenResolution,
+  SpawnStatus,
+} from './spawn-types.js';
+
+// === WarpChain Types ===
+export type {
+  ProtocolType,
+  GateName,
+  WarpStage,
+  WarpLink,
+  ChainShape,
+  GateCheck,
+  GateContract,
+  WarpChain,
+  ChainValidation,
+  WarpChainInstance,
+  GateResult,
+  WarpChainExecution,
+} from './warp-chain.js';
+
+// === Tessera Types ===
+export type {
+  TesseraVariable,
+  TesseraTemplate,
+  TesseraInstantiationInput,
+} from './tessera.js';
+
+// === Archive Types ===
+export type {
+  ArchiveMetadata,
+  ArchivedTask,
+  ArchiveReportType,
+  ArchiveSummaryReport,
+  ArchivePhaseEntry,
+  ArchiveLabelEntry,
+  ArchivePriorityEntry,
+  CycleTimeDistribution,
+  CycleTimePercentiles,
+  ArchiveCycleTimesReport,
+  ArchiveDailyTrend,
+  ArchiveMonthlyTrend,
+  ArchiveTrendsReport,
+  ArchiveStatsEnvelope,
+} from './archive.js';
+
+// === TodoWrite Types (deprecated — use task-sync types) ===
+export type {
+  TodoWriteItemStatus,
+  TodoWriteItem,
+  TodoWriteState,
+  TodoWriteSyncSessionState,
+  TodoWriteChangeSet,
+  TodoWriteChangeAction,
+  TodoWriteChange,
+  TodoWriteMergeResult,
+} from './todowrite.js';
+
+// === Task Sync Types (provider-agnostic reconciliation) ===
+export type {
+  ExternalTaskStatus,
+  ExternalTask,
+  SyncSessionState,
+  ConflictPolicy,
+  ReconcileOptions,
+  ReconcileActionType,
+  ReconcileAction,
+  ReconcileResult,
+  AdapterTaskSyncProvider,
+} from './task-sync.js';
+
+// === Result Types (Dashboard, Stats, Log, Context, Sequence, Analysis, Deps) ===
+export type {
+  TaskSummary,
+  LabelCount,
+  DashboardResult,
+  StatsCurrentState,
+  StatsCompletionMetrics,
+  StatsActivityMetrics,
+  StatsAllTime,
+  StatsCycleTimes,
+  StatsResult,
+  LogQueryResult,
+  ContextResult,
+  SequenceResult,
+  TaskRef,
+  TaskRefPriority,
+  LeveragedTask,
+  BottleneckTask,
+  TaskAnalysisResult,
+  TaskDepsResult,
+  CompleteTaskUnblocked,
+} from './results.js';
+
+// === Brain/Memory Types ===
+export type {
+  BrainEntryRef,
+  BrainEntrySummary,
+  ContradictionDetail,
+  SupersededEntry,
+} from './brain.js';
+
+// === TaskRecord Types (string-widened for dispatch/LAFS) ===
+export type {
+  TaskRecordRelation,
+  ValidationHistoryEntry,
+  TaskRecord,
+  MinimalTaskRecord,
+} from './task-record.js';
+
+// === Session Start Result ===
+export type { SessionStartResult } from './session.js';
+
+// === Operations Types (API wire format, namespaced to avoid collision with domain types) ===
+export * as ops from './operations/index.js';
+
+// Commonly used ops types re-exported at top level for convenience
+export type { BrainState } from './operations/orchestrate.js';

package/src/install.ts

@@ -0,0 +1,28 @@
+/**
+ * Install provider interface for CLEO provider adapters.
+ * Handles registration with the provider and instruction file references.
+ *
+ * @task T5240
+ */
+
+export interface AdapterInstallProvider {
+  install(options: InstallOptions): Promise<InstallResult>;
+  uninstall(): Promise<void>;
+  isInstalled(): Promise<boolean>;
+  /** Ensure the provider's instruction file references CLEO (e.g. @AGENTS.md in CLAUDE.md). */
+  ensureInstructionReferences(projectDir: string): Promise<void>;
+}
+
+export interface InstallOptions {
+  projectDir: string;
+  global?: boolean;
+  mcpServerPath?: string;
+}
+
+export interface InstallResult {
+  success: boolean;
+  installedAt: string;
+  instructionFileUpdated: boolean;
+  mcpRegistered: boolean;
+  details?: Record<string, unknown>;
+}

package/src/lafs.ts

@@ -0,0 +1,194 @@
+/**
+ * LAFS (LLM-Agent-First Schema) unified envelope types.
+ *
+ * Defines canonical LAFS types inline (contracts has ZERO external dependencies).
+ * In the main CLEO codebase these are re-exported from @cleocode/lafs-protocol;
+ * here they are defined as plain interfaces for maximum portability.
+ *
+ * @epic T4654
+ * @task T4655
+ */
+
+// ---------------------------------------------------------------------------
+// Canonical LAFS types (inlined from @cleocode/lafs-protocol)
+// ---------------------------------------------------------------------------
+
+/** LAFS error category. */
+export type LAFSErrorCategory =
+  | 'validation'
+  | 'not_found'
+  | 'conflict'
+  | 'authorization'
+  | 'internal'
+  | 'rate_limit'
+  | 'timeout'
+  | 'dependency';
+
+/** LAFS error object. */
+export interface LAFSError {
+  code: number | string;
+  category: LAFSErrorCategory;
+  message: string;
+  fix?: string;
+  details?: Record<string, unknown>;
+}
+
+/** LAFS warning. */
+export interface Warning {
+  code: string;
+  message: string;
+}
+
+/** LAFS transport metadata. */
+export type LAFSTransport = 'mcp' | 'cli' | 'http' | 'sdk';
+
+/** MVI (Minimal Viable Information) level. */
+export type MVILevel = 'minimal' | 'standard' | 'full';
+
+/** LAFS page — no pagination. */
+export interface LAFSPageNone {
+  strategy: 'none';
+}
+
+/** LAFS page — offset-based pagination. */
+export interface LAFSPageOffset {
+  strategy: 'offset';
+  offset: number;
+  limit: number;
+  total: number;
+  hasMore: boolean;
+}
+
+/** LAFS page union. */
+export type LAFSPage = LAFSPageNone | LAFSPageOffset;
+
+/** LAFS metadata block. */
+export interface LAFSMeta {
+  transport: LAFSTransport;
+  mvi: MVILevel;
+  page?: LAFSPage;
+  warnings?: Warning[];
+  durationMs?: number;
+}
+
+/** LAFS envelope (canonical protocol type). */
+export interface LAFSEnvelope<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: LAFSError;
+  _meta?: LAFSMeta;
+}
+
+/** Flag input for conformance checks. */
+export interface FlagInput {
+  flag: string;
+  value: unknown;
+}
+
+/** Conformance report. */
+export interface ConformanceReport {
+  valid: boolean;
+  violations: string[];
+  warnings: string[];
+}
+
+// ---------------------------------------------------------------------------
+// CLEO-specific error detail (backward compatible)
+// ---------------------------------------------------------------------------
+
+/** Actionable alternative the caller can try. */
+export interface LafsAlternative {
+  action: string;
+  command: string;
+}
+
+/** LAFS error detail shared between CLI and MCP. */
+export interface LafsErrorDetail {
+  code: number | string;
+  name?: string;
+  message: string;
+  fix?: string;
+  alternatives?: LafsAlternative[];
+  details?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// CLI envelope (base) - backward compatible
+// ---------------------------------------------------------------------------
+
+/** LAFS success envelope (CLI). */
+export interface LafsSuccess<T = unknown> {
+  success: true;
+  data: T;
+  message?: string;
+  noChange?: boolean;
+}
+
+/** LAFS error envelope (CLI). */
+export interface LafsError {
+  success: false;
+  error: LafsErrorDetail;
+}
+
+/** CLI envelope union type. */
+export type LafsEnvelope<T = unknown> = LafsSuccess<T> | LafsError;
+
+// ---------------------------------------------------------------------------
+// MCP / gateway envelope extension (extends LAFSMeta)
+// ---------------------------------------------------------------------------
+
+/**
+ * Metadata attached to every MCP gateway response.
+ * Extends the canonical LAFSMeta with CLEO gateway-specific fields.
+ *
+ * @task T4655
+ */
+export interface GatewayMeta extends LAFSMeta {
+  gateway: string;
+  domain: string;
+  duration_ms: number;
+}
+
+/** MCP success envelope (extends CLI base with _meta). */
+export interface GatewaySuccess<T = unknown> extends LafsSuccess<T> {
+  _meta: GatewayMeta;
+}
+
+/** MCP error envelope (extends CLI base with _meta). */
+export interface GatewayError extends LafsError {
+  _meta: GatewayMeta;
+}
+
+/** MCP envelope union type. */
+export type GatewayEnvelope<T = unknown> = GatewaySuccess<T> | GatewayError;
+
+// ---------------------------------------------------------------------------
+// Unified envelope (covers both CLI and MCP)
+// ---------------------------------------------------------------------------
+
+/**
+ * Unified CLEO response envelope.
+ *
+ * Every CLEO response (CLI or MCP) is a CleoResponse. MCP responses include
+ * the _meta field; CLI responses do not.
+ */
+export type CleoResponse<T = unknown> = LafsEnvelope<T> | GatewayEnvelope<T>;
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Type guard for success responses. */
+export function isLafsSuccess<T>(envelope: LafsEnvelope<T>): envelope is LafsSuccess<T> {
+  return envelope.success === true;
+}
+
+/** Type guard for error responses. */
+export function isLafsError<T>(envelope: LafsEnvelope<T>): envelope is LafsError {
+  return envelope.success === false;
+}
+
+/** Type guard for MCP gateway responses (has _meta). */
+export function isGatewayEnvelope<T>(envelope: CleoResponse<T>): envelope is GatewayEnvelope<T> {
+  return '_meta' in envelope && envelope._meta !== undefined;
+}

package/src/memory.ts

@@ -0,0 +1,57 @@
+/**
+ * Memory bridge types for CLEO provider adapters.
+ * Defines the shape of .cleo/memory-bridge.md content for cross-provider memory sharing.
+ *
+ * @task T5240
+ */
+
+export interface MemoryBridgeConfig {
+  maxObservations: number;
+  maxLearnings: number;
+  maxPatterns: number;
+  maxDecisions: number;
+  includeHandoff: boolean;
+  includeAntiPatterns: boolean;
+}
+
+export interface MemoryBridgeContent {
+  generatedAt: string;
+  lastSession?: SessionSummary;
+  learnings: BridgeLearning[];
+  patterns: BridgePattern[];
+  antiPatterns: BridgePattern[];
+  decisions: BridgeDecision[];
+  recentObservations: BridgeObservation[];
+}
+
+export interface SessionSummary {
+  sessionId: string;
+  date: string;
+  tasksCompleted: string[];
+  decisions: string[];
+  nextSuggested: string[];
+}
+
+export interface BridgeLearning {
+  id: string;
+  text: string;
+  confidence: number;
+}
+
+export interface BridgePattern {
+  id: string;
+  text: string;
+  type: 'follow' | 'avoid';
+}
+
+export interface BridgeDecision {
+  id: string;
+  title: string;
+  date: string;
+}
+
+export interface BridgeObservation {
+  id: string;
+  date: string;
+  summary: string;
+}

package/src/operations/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Operations types barrel — API wire format types for all CLEO domains.
+ *
+ * These are re-exported under `ops` namespace from the package root
+ * to avoid name collisions with canonical domain types.
+ */
+
+export * from './issues.js';
+export * from './lifecycle.js';
+export * from './orchestrate.js';
+export * from './release.js';
+export * from './research.js';
+export * from './session.js';
+export * from './skills.js';
+export * from './system.js';
+export * from './tasks.js';
+export * from './validate.js';

package/src/operations/issues.ts

@@ -0,0 +1,86 @@
+/**
+ * Issues Domain Operations (4 operations)
+ *
+ * Query operations: 1 (diagnostics)
+ * Mutate operations: 3 (add.bug, add.feature, add.help)
+ *
+ * @task T4494
+ */
+
+/**
+ * Common issue types
+ */
+export type IssueSeverity = 'low' | 'medium' | 'high' | 'critical';
+export type IssueArea = 'cli' | 'mcp' | 'docs' | 'tests' | 'other';
+export type IssueType = 'bug' | 'feature' | 'help';
+
+export interface Diagnostics {
+  cleoVersion: string;
+  bashVersion: string;
+  jqVersion: string;
+  os: string;
+  shell: string;
+  cleoHome: string;
+  ghVersion: string;
+  installLocation: string;
+}
+
+/**
+ * Query Operations
+ */
+
+// issues.diagnostics
+export type IssuesDiagnosticsParams = Record<string, never>;
+export interface IssuesDiagnosticsResult {
+  diagnostics: Diagnostics;
+}
+
+/**
+ * Mutate Operations
+ */
+
+// issues.add.bug (alias: create.bug)
+export interface IssuesCreateBugParams {
+  title: string;
+  body: string;
+  severity?: IssueSeverity;
+  area?: IssueArea;
+  dryRun?: boolean;
+}
+export interface IssuesCreateBugResult {
+  type: 'bug';
+  url: string;
+  number: number;
+  title: string;
+  labels: string[];
+}
+
+// issues.add.feature (alias: create.feature)
+export interface IssuesCreateFeatureParams {
+  title: string;
+  body: string;
+  area?: IssueArea;
+  dryRun?: boolean;
+}
+export interface IssuesCreateFeatureResult {
+  type: 'feature';
+  url: string;
+  number: number;
+  title: string;
+  labels: string[];
+}
+
+// issues.add.help (alias: create.help)
+export interface IssuesCreateHelpParams {
+  title: string;
+  body: string;
+  area?: IssueArea;
+  dryRun?: boolean;
+}
+export interface IssuesCreateHelpResult {
+  type: 'help';
+  url: string;
+  number: number;
+  title: string;
+  labels: string[];
+}