speexor 0.1.0

package/API-REFERENCE.md

@@ -0,0 +1,201 @@
+# API Reference
+
+> Plugin interfaces, configuration schema, and core API documentation for Speexor.
+
+## Plugin Interfaces
+
+### PluginModule (Base Interface)
+All plugins must implement this interface:
+
+```typescript
+interface PluginModule {
+  name: string
+  version: string
+  type: PluginSlot  // 'agent' | 'runtime' | 'workspace' | 'tracker' | 'scm' | 'notifier' | 'terminal'
+  initialize(context: PluginContext): Promise<void>
+  destroy(): Promise<void>
+}
+
+interface PluginContext {
+  config: SpeexorConfig
+  eventBus: EventBus
+  logger: (msg: string) => void
+}
+```
+
+### AgentPlugin
+
+```typescript
+interface AgentPlugin extends PluginModule {
+  type: 'agent'
+  spawn(task: AgentTask, runtime: RuntimeSession): Promise<AgentSession>
+  sendInput(sessionId: string, input: string): Promise<void>
+  getStatus(sessionId: string): Promise<AgentStatus>
+  kill(sessionId: string): Promise<void>
+}
+```
+
+### RuntimePlugin
+
+```typescript
+interface RuntimePlugin extends PluginModule {
+  type: 'runtime'
+  createSession(worktreePath: string): Promise<RuntimeSession>
+  destroySession(sessionId: string): Promise<void>
+  sendInput(sessionId: string, input: string): Promise<void>
+  getOutput(sessionId: string): Promise<string>
+  getLiveStream(sessionId: string): AsyncIterable<string>
+  getStatus(sessionId: string): Promise<'running' | 'stopped' | 'error'>
+}
+```
+
+### WorkspacePlugin
+
+```typescript
+interface WorkspacePlugin extends PluginModule {
+  type: 'workspace'
+  createWorktree(task: AgentTask): Promise<WorktreeSession>
+  removeWorktree(sessionId: string): Promise<void>
+  getWorktreePath(sessionId: string): string
+  listActive(): Promise<WorktreeSession[]>
+  cleanupStale(): Promise<string[]>
+}
+```
+
+### TrackerPlugin
+
+```typescript
+interface TrackerPlugin extends PluginModule {
+  type: 'tracker'
+  fetchIssues(filter?: TrackerFilter): Promise<TrackerIssue[]>
+  getIssue(id: string): Promise<TrackerIssue | null>
+  onEvent(handler: (event: TrackerEvent) => void): void
+}
+```
+
+### SCMPlugin
+
+```typescript
+interface SCMPlugin extends PluginModule {
+  type: 'scm'
+  createBranch(baseBranch: string, newBranch: string): Promise<void>
+  commitAndPush(branch: string, message: string): Promise<string>
+  createPullRequest(title: string, description: string, head: string, base: string): Promise<PRInfo>
+  getPRStatus(prId: string): Promise<PRStatus>
+  getPRComments(prId: string): Promise<PRComment[]>
+  getCIRuns(prId: string): Promise<CIRun[]>
+  mergePR(prId: string, method?: 'merge' | 'squash' | 'rebase'): Promise<void>
+  onEvent(handler: (event: TrackerEvent) => void): void
+}
+```
+
+### NotifierPlugin
+
+```typescript
+interface NotifierPlugin extends PluginModule {
+  type: 'notifier'
+  notify(level: 'info' | 'warn' | 'error' | 'success', title: string, message: string): Promise<void>
+}
+```
+
+### TerminalPlugin
+
+```typescript
+interface TerminalPlugin extends PluginModule {
+  type: 'terminal'
+  attach(sessionId: string): Promise<void>
+  detach(sessionId: string): Promise<void>
+  write(sessionId: string, data: string): Promise<void>
+  onData(sessionId: string, handler: (data: string) => void): void
+}
+```
+
+## Core API
+
+### SpeexorLifecycle
+
+```typescript
+class SpeexorLifecycle {
+  constructor(config: SpeexorConfig)
+  initialize(): Promise<void>
+  registerPlugin(plugin: PluginModule): void
+  getPlugins<T>(slot: PluginSlot): T[]
+  getFirstPlugin<T>(slot: PluginSlot): T | undefined
+  spawnAgent(task: AgentTask): Promise<AgentSession>
+  stopSession(sessionId: string): Promise<void>
+  getSession(sessionId: string): AgentSession | undefined
+  listSessions(): AgentSession[]
+  destroy(): Promise<void>
+  getConfig(): SpeexorConfig
+  getStatus(): SessionStatus
+  eventBus: EventBus
+}
+```
+
+### Config Functions
+
+```typescript
+function loadConfig(cwd?: string): SpeexorConfig
+function validateConfig(raw: unknown): SpeexorConfig
+function generateDefaultConfig(repoUrl: string, projectName?: string): SpeexorConfig
+```
+
+### Plugin Loading
+
+```typescript
+function loadAllPlugins(): PluginModule[]
+function loadPluginByType(type: string): PluginModule | undefined
+```
+
+### Event Bus
+
+```typescript
+function createEventBus(): EventBus
+// EventBus: { emit(event, data), on(event, handler), off(event, handler), once(event, handler) }
+```
+
+## Configuration Schema
+
+```yaml
+version: "1"
+projects:
+  - name: <string>
+    repository: <string>
+    path?: <string>
+    branch?: <string>
+    provider:
+      primary: opencode | claude-code | aider | codex
+      fallback?: (opencode | claude-code | aider | codex)[]
+      concurrentLimit?: <1-20>
+      costLimit?: <number>
+    reactions?:
+      ci-failed?: { auto, action, retries, escalateAfter }
+      changes-requested?: { auto, action, retries, escalateAfter }
+      approved-and-green?: { auto, action, retries, escalateAfter }
+    plugins?:
+      tracker?: string
+      scm?: string
+      runtime?: string
+      notifier?: string
+```
+
+## Dashboard API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/status` | Lifecycle status, project/agent counts, uptime |
+| GET | `/api/projects` | Project configurations |
+| GET | `/api/sessions` | Active sessions, worktrees, runtimes |
+| GET | `/api/health` | Health check with memory stats |
+| GET | `/` or `/dashboard` | HTML dashboard UI |
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `speexor start [repo]` | Init project + start dashboard |
+| `speexor agent spawn -t <id>` | Spawn agent for task |
+| `speexor list` | List projects and agents |
+| `speexor stop <session-id>` | Stop agent session |
+| `speexor logs <session-id>` | Tail session logs |
+| `speexor config-help` | Print config schema |