@cleocode/contracts 2.0.0

package/src/operations/session.ts

@@ -0,0 +1,119 @@
+/**
+ * Session Domain Operations (9 operations)
+ *
+ * Query operations: 4
+ * Mutate operations: 5
+ *
+ * SYNC: Canonical type definitions live in the CLI package at:
+ *   src/types/session.ts (Session, SessionScope, etc.)
+ * These MCP operation types are the API contract (wire format).
+ */
+
+/**
+ * Common session types
+ */
+export interface SessionOp {
+  id: string;
+  name: string;
+  scope: string;
+  started: string;
+  ended?: string;
+  startedTask?: string;
+  status: 'active' | 'suspended' | 'ended';
+  notes?: string[];
+}
+
+/**
+ * Query Operations
+ */
+
+// session.status
+export type SessionStatusParams = Record<string, never>;
+export interface SessionStatusResult {
+  current: SessionOp | null;
+  hasStartedTask: boolean;
+  startedTask?: string;
+}
+
+// session.list
+export interface SessionListParams {
+  active?: boolean;
+  status?: string;
+  limit?: number;
+  offset?: number;
+}
+export interface SessionListResult {
+  sessions: SessionOp[];
+  total: number;
+  filtered: number;
+}
+
+// session.show
+export interface SessionShowParams {
+  sessionId: string;
+}
+export type SessionShowResult = SessionOp;
+
+// session.history
+export interface SessionHistoryParams {
+  limit?: number;
+}
+export interface SessionHistoryEntry {
+  sessionId: string;
+  name: string;
+  started: string;
+  ended: string;
+  tasksCompleted: number;
+  duration: string;
+}
+export type SessionHistoryResult = SessionHistoryEntry[];
+
+/**
+ * Mutate Operations
+ */
+
+// session.start
+export interface SessionStartParams {
+  scope: string;
+  name?: string;
+  autoStart?: boolean;
+  startTask?: string;
+}
+export type SessionStartResult = SessionOp;
+
+// session.end
+export interface SessionEndParams {
+  notes?: string;
+}
+export interface SessionEndResult {
+  session: SessionOp;
+  summary: {
+    duration: string;
+    tasksCompleted: number;
+    tasksCreated: number;
+  };
+}
+
+// session.resume
+export interface SessionResumeParams {
+  sessionId: string;
+}
+export type SessionResumeResult = SessionOp;
+
+// session.suspend
+export interface SessionSuspendParams {
+  notes?: string;
+}
+export interface SessionSuspendResult {
+  sessionId: string;
+  suspended: string;
+}
+
+// session.gc
+export interface SessionGcParams {
+  olderThan?: string;
+}
+export interface SessionGcResult {
+  cleaned: number;
+  sessionIds: string[];
+}

package/src/operations/skills.ts

@@ -0,0 +1,210 @@
+/**
+ * Skills Domain Operations (12 operations)
+ *
+ * Query operations: 6 (list, show, find, dispatch, verify, dependencies)
+ * Mutate operations: 6 (install, uninstall, enable, disable, configure, refresh)
+ *
+ * @task T4387
+ */
+
+/**
+ * Common skill types
+ */
+export type SkillCategory = 'core' | 'recommended' | 'specialist' | 'composition' | 'meta';
+export type SkillStatus = 'active' | 'disabled' | 'deprecated' | 'missing';
+export type DispatchStrategy = 'label' | 'type' | 'keyword' | 'fallback';
+
+export interface SkillSummary {
+  name: string;
+  version: string;
+  description: string;
+  category: SkillCategory;
+  core: boolean;
+  tier: number;
+  status: SkillStatus;
+  protocol: string | null;
+}
+
+export interface SkillDetail extends SkillSummary {
+  path: string;
+  references: string[];
+  dependencies: string[];
+  sharedResources: string[];
+  compatibility: string[];
+  license: string;
+  metadata: Record<string, unknown>;
+  capabilities?: {
+    inputs: string[];
+    outputs: string[];
+    dispatch_triggers: string[];
+    compatible_subagent_types: string[];
+    chains_to: string[];
+    dispatch_keywords: {
+      primary: string[];
+      secondary: string[];
+    };
+  };
+  constraints?: {
+    max_context_tokens: number;
+    requires_session: boolean;
+    requires_epic: boolean;
+  };
+}
+
+export interface DispatchCandidate {
+  skill: string;
+  score: number;
+  strategy: DispatchStrategy;
+  reason: string;
+}
+
+export interface DependencyNode {
+  name: string;
+  version: string;
+  direct: boolean;
+  depth: number;
+}
+
+export interface ValidationIssue {
+  level: 'error' | 'warn';
+  field: string;
+  message: string;
+}
+
+/**
+ * Query Operations
+ */
+
+// skills.list
+export interface SkillsListParams {
+  category?: SkillCategory;
+  core?: boolean;
+  filter?: string;
+}
+export type SkillsListResult = SkillSummary[];
+
+// skills.show
+export interface SkillsShowParams {
+  name: string;
+}
+export type SkillsShowResult = SkillDetail;
+
+// skills.find
+export interface SkillsFindParams {
+  query: string;
+  limit?: number;
+}
+export interface SkillsFindResult {
+  query: string;
+  results: Array<SkillSummary & { score: number; matchReason: string }>;
+}
+
+// skills.dispatch
+export interface SkillsDispatchParams {
+  taskId?: string;
+  taskType?: string;
+  labels?: string[];
+  title?: string;
+  description?: string;
+}
+export interface SkillsDispatchResult {
+  selectedSkill: string;
+  reason: string;
+  strategy: DispatchStrategy;
+  candidates: DispatchCandidate[];
+}
+
+// skills.verify
+export interface SkillsVerifyParams {
+  name?: string;
+}
+export interface SkillsVerifyResult {
+  valid: boolean;
+  total: number;
+  passed: number;
+  failed: number;
+  results: Array<{
+    name: string;
+    valid: boolean;
+    issues: ValidationIssue[];
+  }>;
+}
+
+// skills.dependencies
+export interface SkillsDependenciesParams {
+  name: string;
+  transitive?: boolean;
+}
+export interface SkillsDependenciesResult {
+  name: string;
+  dependencies: DependencyNode[];
+  resolved: string[];
+}
+
+/**
+ * Mutate Operations
+ */
+
+// skills.install
+export interface SkillsInstallParams {
+  name: string;
+  source?: string;
+}
+export interface SkillsInstallResult {
+  name: string;
+  installed: boolean;
+  version: string;
+  path: string;
+}
+
+// skills.uninstall
+export interface SkillsUninstallParams {
+  name: string;
+  force?: boolean;
+}
+export interface SkillsUninstallResult {
+  name: string;
+  uninstalled: boolean;
+}
+
+// skills.enable
+export interface SkillsEnableParams {
+  name: string;
+}
+export interface SkillsEnableResult {
+  name: string;
+  enabled: boolean;
+  status: SkillStatus;
+}
+
+// skills.disable
+export interface SkillsDisableParams {
+  name: string;
+  reason?: string;
+}
+export interface SkillsDisableResult {
+  name: string;
+  disabled: boolean;
+  status: SkillStatus;
+}
+
+// skills.configure
+export interface SkillsConfigureParams {
+  name: string;
+  config: Record<string, unknown>;
+}
+export interface SkillsConfigureResult {
+  name: string;
+  configured: boolean;
+  config: Record<string, unknown>;
+}
+
+// skills.refresh
+export interface SkillsRefreshParams {
+  force?: boolean;
+}
+export interface SkillsRefreshResult {
+  refreshed: boolean;
+  skillCount: number;
+  timestamp: string;
+}

package/src/operations/system.ts

@@ -0,0 +1,174 @@
+/**
+ * System Domain Operations (12 operations)
+ *
+ * Query operations: 5
+ * Mutate operations: 7
+ */
+
+/**
+ * Common system types
+ */
+export interface HealthCheck {
+  component: string;
+  healthy: boolean;
+  message?: string;
+}
+
+export interface ProjectStats {
+  tasks: {
+    total: number;
+    pending: number;
+    active: number;
+    blocked: number;
+    done: number;
+  };
+  sessions: {
+    total: number;
+    active: number;
+  };
+  research: {
+    total: number;
+    complete: number;
+  };
+}
+
+/**
+ * Query Operations
+ */
+
+// system.version
+export type SystemVersionParams = Record<string, never>;
+export interface SystemVersionResult {
+  version: string;
+  schemaVersion: string;
+  buildDate: string;
+}
+
+// system.doctor
+export type SystemDoctorParams = Record<string, never>;
+export interface SystemDoctorResult {
+  healthy: boolean;
+  checks: HealthCheck[];
+  warnings: string[];
+  errors: string[];
+}
+
+// system.config.get
+export interface SystemConfigGetParams {
+  key: string;
+}
+export interface SystemConfigGetResult {
+  key: string;
+  value: unknown;
+  type: string;
+}
+
+// system.stats
+export type SystemStatsParams = Record<string, never>;
+export type SystemStatsResult = ProjectStats;
+
+// system.context
+export type SystemContextParams = Record<string, never>;
+export interface SystemContextResult {
+  currentTokens: number;
+  maxTokens: number;
+  percentUsed: number;
+  level: 'safe' | 'medium' | 'high' | 'critical';
+  estimatedFiles: number;
+  largestFile: {
+    path: string;
+    tokens: number;
+  };
+}
+
+/**
+ * Mutate Operations
+ */
+
+// system.init
+export interface SystemInitParams {
+  projectType?: 'nodejs' | 'python' | 'bash' | 'typescript' | 'rust' | 'go';
+  detect?: boolean;
+}
+export interface SystemInitResult {
+  initialized: boolean;
+  projectType?: string;
+  filesCreated: string[];
+  detectedFeatures?: Record<string, boolean>;
+}
+
+// system.config.set
+export interface SystemConfigSetParams {
+  key: string;
+  value: unknown;
+}
+export interface SystemConfigSetResult {
+  key: string;
+  value: unknown;
+  previousValue?: unknown;
+}
+
+// system.backup
+export interface SystemBackupParams {
+  type?: 'snapshot' | 'safety' | 'archive' | 'migration';
+  note?: string;
+}
+export interface SystemBackupResult {
+  backupId: string;
+  type: string;
+  timestamp: string;
+  files: string[];
+  size: number;
+}
+
+// system.restore
+export interface SystemRestoreParams {
+  backupId: string;
+}
+export interface SystemRestoreResult {
+  backupId: string;
+  restored: string;
+  filesRestored: string[];
+}
+
+// system.migrate
+export interface SystemMigrateParams {
+  version?: string;
+  dryRun?: boolean;
+}
+export interface SystemMigrateResult {
+  fromVersion: string;
+  toVersion: string;
+  migrations: Array<{
+    name: string;
+    applied: boolean;
+    error?: string;
+  }>;
+  dryRun: boolean;
+}
+
+// system.sync
+export interface SystemSyncParams {
+  direction?: 'push' | 'pull' | 'bidirectional';
+}
+export interface SystemSyncResult {
+  direction: string;
+  synced: string;
+  tasksSynced: number;
+  conflicts: Array<{
+    taskId: string;
+    resolution: string;
+  }>;
+}
+
+// system.cleanup
+export interface SystemCleanupParams {
+  type: 'backups' | 'logs' | 'archive' | 'sessions';
+  olderThan?: string;
+}
+export interface SystemCleanupResult {
+  type: string;
+  cleaned: number;
+  freed: number;
+  items: string[];
+}