speexor 0.1.0 → 0.2.0

package/docs/adr/0005-data-directory-layout.md

@@ -0,0 +1,69 @@
+# ADR-0005: User-Home Data Directory Layout (~/.speexor/)
+
+## Status
+
+Accepted
+
+## Context
+
+Speexor persists several kinds of local state: session data, task graphs, checkpoints, the decision log, extension caches, and secret references. Earlier drafts left the storage location implicit. A formal decision is needed on:
+
+1. **Location:** Should data live in the project directory (`.speexor/`) or the user home directory (`~/.speexor/`)?
+2. **Structure:** How should different data types (SQLite, JSON, binary checkpoints, vault references) be organized?
+3. **Isolation:** How do we prevent state leakage between different projects managed by Speexor?
+
+## Decision
+
+### Location: ~/.speexor/ (User Home)
+
+All persistent state lives under `~/.speexor/` in the user's home directory, not project-local. Each managed project gets a subdirectory keyed by a content-hash of the repository URL combined with a short project ID:
+
+```
+~/.speexor/
+  ├── 1a2b3c4d-my-project/       # Per-project directory (hash-projectId)
+  │   ├── task-graph.sqlite       # Task graph DAG store (SQLite)
+  │   ├── decision-log.sqlite     # Decision Log (SQLite, read-only history)
+  │   ├── checkpoints/            # Session checkpoint snapshots (JSON)
+  │   │   ├── checkpoint-abc.json
+  │   │   └── checkpoint-def.json
+  │   ├── extensions/             # Downloaded/cached extension manifests
+  │   └── vault-refs.json         # References into OS keychain (never secrets)
+  ├── registry-cache/             # Marketplace registry index cache
+  ├── logs/                       # Global orchestrator logs
+  └── lock                        # Process lock file (prevents concurrent instances)
+```
+
+Rationale for `~/.speexor/` over project-local:
+
+- Data survives project directory deletion (user can delete a clone without losing the decision log).
+- Multiple clones of the same repo share a single project directory (hash-based dedup).
+- Cleaner user experience — no hidden directories scattered across the file system.
+- Consistent with established patterns (`.aws/`, `.config/`, `.npm/`, etc.).
+
+### Storage Formats
+
+| Data Type        | Format  | Rationale                                      |
+|------------------|---------|------------------------------------------------|
+| Task graph       | SQLite  | Relational queries on DAG nodes/edges          |
+| Decision log     | SQLite  | Searchable, filterable history                 |
+| Checkpoints      | JSON    | Human-readable, debuggable snapshots           |
+| Extension cache  | JSON    | Simple manifest storage, no query pattern      |
+| Vault refs       | JSON    | Lightweight reference store (values in keychain)|
+| Session state    | JSON    | Synchronous read/write for simplicity          |
+
+### Secrets Management
+
+The `vault-refs.json` file contains only **references** (key names/paths) into the OS keychain. Actual secret values (API tokens, encryption keys) are stored via the OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret) and never written to disk in plaintext. The `secretsBackend` config option controls which backend is used.
+
+### Process Lock
+
+A `lock` file at `~/.speexor/lock` prevents multiple Speexor processes from operating on the same data directory simultaneously. The lock is advisory — it contains the PID and is cleaned up on graceful shutdown. Stale locks from crashes are automatically detected and cleared on startup.
+
+## Consequences
+
+- **Positive:** Data persists across project directory deletions; clean separation between projects.
+- **Positive:** Hash-based project IDs prevent collisions and enable deduplication.
+- **Positive:** SQLite for graph and decision log enables efficient queries vs. JSON scanning.
+- **Negative:** User-home directory may not be writable in some locked-down enterprise environments (mitigation: `SPEEXOR_DATA_DIR` env var override).
+- **Negative:** OS keychain dependency adds a setup step for headless/server environments.
+- **Neutral:** Consistent with `speexor migrate-from-konduktor` migration path (FR-84).

package/examples/basic.yaml

@@ -1,61 +1,61 @@
-# Speexor Configuration — Basic Example
-# Agent Orchestrator for multi-AI coding agent orchestration
-#
-# Usage:
-#   1. Save this file as speexor.config.yaml in your project root
-#   2. Run `speexor start` to initialize and open the dashboard
-#   3. Run `speexor agent spawn --task <issue-id>` to spawn an agent
-
-version: "1"
-
-projects:
-  # --- Single project, single agent ---
-  - name: brainclash
-    repository: https://github.com/superdevids/brainclash
-    provider:
-      primary: opencode
-      fallback:
-        - claude-code
-        - aider
-      concurrentLimit: 3
-
-    # Automated reactions to CI and PR events
-    reactions:
-      ci-failed:
-        auto: true
-        action: fix
-        retries: 3
-        escalateAfter: 30
-      changes-requested:
-        auto: true
-        action: fix
-        retries: 2
-        escalateAfter: 60
-      approved-and-green:
-        auto: false
-        action: notify
-        retries: 0
-        escalateAfter: 0
-
-  # --- Second project with different provider ---
-  - name: kata-netizen
-    repository: https://github.com/superdevids/kata-netizen
-    provider:
-      primary: claude-code
-      concurrentLimit: 2
-    reactions:
-      ci-failed:
-        auto: true
-        action: fix
-        retries: 3
-        escalateAfter: 30
-      changes-requested:
-        auto: true
-        action: fix
-        retries: 2
-        escalateAfter: 45
-      approved-and-green:
-        auto: false
-        action: notify
-        retries: 0
-        escalateAfter: 0
+# Speexor Configuration — Basic Example
+# Agent Orchestrator for multi-AI coding agent orchestration
+#
+# Usage:
+#   1. Save this file as speexor.config.yaml in your project root
+#   2. Run `speexor start` to initialize and open the dashboard
+#   3. Run `speexor agent spawn --task <issue-id>` to spawn an agent
+
+version: "1"
+
+projects:
+  # --- Single project, single agent ---
+  - name: brainclash
+    repository: https://github.com/superdevids/brainclash
+    provider:
+      primary: opencode
+      fallback:
+        - claude-code
+        - aider
+      concurrentLimit: 3
+
+    # Automated reactions to CI and PR events
+    reactions:
+      ci-failed:
+        auto: true
+        action: fix
+        retries: 3
+        escalateAfter: 30
+      changes-requested:
+        auto: true
+        action: fix
+        retries: 2
+        escalateAfter: 60
+      approved-and-green:
+        auto: false
+        action: notify
+        retries: 0
+        escalateAfter: 0
+
+  # --- Second project with different provider ---
+  - name: kata-netizen
+    repository: https://github.com/superdevids/kata-netizen
+    provider:
+      primary: claude-code
+      concurrentLimit: 2
+    reactions:
+      ci-failed:
+        auto: true
+        action: fix
+        retries: 3
+        escalateAfter: 30
+      changes-requested:
+        auto: true
+        action: fix
+        retries: 2
+        escalateAfter: 45
+      approved-and-green:
+        auto: false
+        action: notify
+        retries: 0
+        escalateAfter: 0

package/package.json

@@ -1,102 +1,103 @@
-{
-  "name": "speexor",
-  "version": "0.1.0",
-  "description": "Speexor — Agent Orchestrator for multi-AI coding agent orchestration across repositories",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "speexor": "dist/cli/index.js"
-  },
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./core": {
-      "import": "./dist/core/index.js",
-      "types": "./dist/core/index.d.ts"
-    },
-    "./cli": {
-      "import": "./dist/cli/index.js",
-      "types": "./dist/cli/index.d.ts"
-    },
-    "./plugins": {
-      "import": "./dist/plugins/index.js",
-      "types": "./dist/plugins/index.d.ts"
-    }
-  },
-  "files": [
-    "dist",
-    "schema",
-    "docs",
-    "*.md",
-    "examples",
-    "speexor.config.yaml.example"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
-  },
-  "dependencies": {
-    "commander": "^12.0.0",
-    "chalk": "^5.3.0",
-    "conf": "^12.0.0",
-    "dayjs": "^1.11.0",
-    "debug": "^4.3.0",
-    "eventemitter3": "^5.0.0",
-    "execa": "^9.0.0",
-    "globby": "^14.0.0",
-    "node-emoji": "^2.1.0",
-    "ora": "^8.0.0",
-    "yaml": "^2.5.0",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.1",
-    "@types/debug": "^4.1.0",
-    "@types/node": "^26.0.1",
-    "@vitest/coverage-v8": "^2.1.9",
-    "tsup": "^8.3.0",
-    "typescript": "^5.7.0",
-    "vite": "^8.1.0",
-    "vitest": "^2.1.0"
-  },
-  "keywords": [
-    "orchestrator",
-    "ai-agent",
-    "agent-orchestration",
-    "coding-agent",
-    "claude-code",
-    "opencode",
-    "aider",
-    "codex",
-    "multi-agent",
-    "speexor"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "preferGlobal": true,
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/superdevids/speexjs.git",
-    "directory": "packages/speexor"
-  },
-  "bugs": {
-    "url": "https://github.com/superdevids/speexjs/issues"
-  },
-  "homepage": "https://github.com/superdevids/speexjs/tree/main/packages/speexor#readme",
-  "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
+{
+  "name": "speexor",
+  "version": "0.2.0",
+  "description": "Speexor — Agent Orchestrator for multi-AI coding agent orchestration across repositories",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "speexor": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./core": {
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli/index.js",
+      "types": "./dist/cli/index.d.ts"
+    },
+    "./plugins": {
+      "import": "./dist/plugins/index.js",
+      "types": "./dist/plugins/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "schema",
+    "docs",
+    "*.md",
+    "examples",
+    "speexor.config.yaml.example"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.10.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "conf": "^12.0.0",
+    "dayjs": "^1.11.0",
+    "debug": "^4.3.0",
+    "eventemitter3": "^5.0.0",
+    "execa": "^9.0.0",
+    "globby": "^14.0.0",
+    "node-emoji": "^2.1.0",
+    "ora": "^8.0.0",
+    "yaml": "^2.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/debug": "^4.1.0",
+    "@types/node": "^26.0.1",
+    "@vitest/coverage-v8": "^2.1.9",
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vite": "^8.1.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "orchestrator",
+    "ai-agent",
+    "agent-orchestration",
+    "coding-agent",
+    "claude-code",
+    "opencode",
+    "aider",
+    "codex",
+    "multi-agent",
+    "speexor"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "preferGlobal": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superdevids/speexor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/superdevids/speexor/issues"
+  },
+  "homepage": "https://github.com/superdevids/speexor#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/schema/config.schema.json

@@ -1,119 +1,119 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://speexjs.dev/schemas/speexor-config.json",
-  "title": "Speexor Configuration",
-  "description": "Configuration schema for Speexor — Agent Orchestrator",
-  "type": "object",
-  "required": ["version", "projects"],
-  "properties": {
-    "version": {
-      "type": "string",
-      "enum": ["1"],
-      "description": "Config schema version"
-    },
-    "projects": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "required": ["name", "repository", "provider"],
-        "properties": {
-          "name": {
-            "type": "string",
-            "description": "Project display name"
-          },
-          "repository": {
-            "type": "string",
-            "description": "Git repository URL or local path"
-          },
-          "path": {
-            "type": "string",
-            "description": "Local path override for repository"
-          },
-          "branch": {
-            "type": "string",
-            "description": "Default base branch",
-            "default": "main"
-          },
-          "provider": {
-            "type": "object",
-            "required": ["primary"],
-            "properties": {
-              "primary": {
-                "type": "string",
-                "enum": ["opencode", "claude-code", "aider", "codex"],
-                "description": "Primary AI coding agent"
-              },
-              "fallback": {
-                "type": "array",
-                "items": {
-                  "type": "string",
-                  "enum": ["opencode", "claude-code", "aider", "codex"]
-                },
-                "description": "Fallback agents in priority order"
-              },
-              "concurrentLimit": {
-                "type": "integer",
-                "minimum": 1,
-                "maximum": 20,
-                "description": "Maximum parallel agents for this project"
-              },
-              "costLimit": {
-                "type": "integer",
-                "minimum": 0,
-                "description": "Cost limit in cents per session"
-              }
-            }
-          },
-          "reactions": {
-            "type": "object",
-            "properties": {
-              "ci-failed": { "$ref": "#/definitions/reactionRule" },
-              "changes-requested": { "$ref": "#/definitions/reactionRule" },
-              "approved-and-green": { "$ref": "#/definitions/reactionRule" }
-            },
-            "description": "Reaction rules for CI/PR events"
-          },
-          "plugins": {
-            "type": "object",
-            "properties": {
-              "tracker": { "type": "string" },
-              "scm": { "type": "string" },
-              "runtime": { "type": "string" },
-              "notifier": { "type": "string" }
-            }
-          }
-        }
-      }
-    }
-  },
-  "definitions": {
-    "reactionRule": {
-      "type": "object",
-      "required": ["auto", "action"],
-      "properties": {
-        "auto": {
-          "type": "boolean",
-          "description": "Auto-trigger reaction when event occurs"
-        },
-        "action": {
-          "type": "string",
-          "enum": ["fix", "notify", "escalate", "skip"],
-          "description": "Action to take when reaction triggers"
-        },
-        "retries": {
-          "type": "integer",
-          "minimum": 0,
-          "maximum": 10,
-          "description": "Number of retry attempts"
-        },
-        "escalateAfter": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 1440,
-          "description": "Minutes before escalating to human"
-        }
-      }
-    }
-  }
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://speexjs.dev/schemas/speexor-config.json",
+  "title": "Speexor Configuration",
+  "description": "Configuration schema for Speexor — Agent Orchestrator",
+  "type": "object",
+  "required": ["version", "projects"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "enum": ["1"],
+      "description": "Config schema version"
+    },
+    "projects": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "repository", "provider"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Project display name"
+          },
+          "repository": {
+            "type": "string",
+            "description": "Git repository URL or local path"
+          },
+          "path": {
+            "type": "string",
+            "description": "Local path override for repository"
+          },
+          "branch": {
+            "type": "string",
+            "description": "Default base branch",
+            "default": "main"
+          },
+          "provider": {
+            "type": "object",
+            "required": ["primary"],
+            "properties": {
+              "primary": {
+                "type": "string",
+                "enum": ["opencode", "claude-code", "aider", "codex"],
+                "description": "Primary AI coding agent"
+              },
+              "fallback": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "enum": ["opencode", "claude-code", "aider", "codex"]
+                },
+                "description": "Fallback agents in priority order"
+              },
+              "concurrentLimit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 20,
+                "description": "Maximum parallel agents for this project"
+              },
+              "costLimit": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Cost limit in cents per session"
+              }
+            }
+          },
+          "reactions": {
+            "type": "object",
+            "properties": {
+              "ci-failed": { "$ref": "#/definitions/reactionRule" },
+              "changes-requested": { "$ref": "#/definitions/reactionRule" },
+              "approved-and-green": { "$ref": "#/definitions/reactionRule" }
+            },
+            "description": "Reaction rules for CI/PR events"
+          },
+          "plugins": {
+            "type": "object",
+            "properties": {
+              "tracker": { "type": "string" },
+              "scm": { "type": "string" },
+              "runtime": { "type": "string" },
+              "notifier": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "reactionRule": {
+      "type": "object",
+      "required": ["auto", "action"],
+      "properties": {
+        "auto": {
+          "type": "boolean",
+          "description": "Auto-trigger reaction when event occurs"
+        },
+        "action": {
+          "type": "string",
+          "enum": ["fix", "notify", "escalate", "skip"],
+          "description": "Action to take when reaction triggers"
+        },
+        "retries": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "description": "Number of retry attempts"
+        },
+        "escalateAfter": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1440,
+          "description": "Minutes before escalating to human"
+        }
+      }
+    }
+  }
+}