@wundam/orchex 1.0.0-rc.1 → 1.0.0-rc.2

package/README.md

@@ -11,19 +11,16 @@ Your AI assistant does tasks one at a time. Orchex makes it do 10 at once — sa
 - **Parallel Execution** — Multiple streams run simultaneously in dependency-aware waves. 5-10x faster than serial prompting.
 - **Ownership Enforcement** — Each stream can only modify files in its `owns` array. No two agents touch the same file. Zero conflicts.
 - **`orchex learn`** — The magic command. Paste a markdown plan, get executable parallel streams with dependency inference and anti-pattern detection. No other tool does this.
-- **Self-Healing** — 10 error categories with targeted fix streams. Not blind retry — categorized analysis with augmented instructions.
-- **Multi-LLM** — OpenAI, Gemini, Claude, DeepSeek, Ollama. Route different orchestrations to different providers — use DeepSeek ($0.001/1K) for docs, Claude ($0.015/1K) for core logic.
+- **Self-Healing** — Categorized error analysis with targeted fix streams. Not blind retry.
+- **Multi-LLM** — OpenAI, Gemini, Claude, DeepSeek, Ollama. Route different orchestrations to different providers.
 - **BYOK** — Bring your own API key from any supported provider. You control costs.
-- **Context Budget Intelligence** — Provider-aware limits with soft/hard enforcement and adaptive learning per stream category.
-- **Team Collaboration** — Organization members see each other's orchestration runs. Shared dashboard with org switcher and access controls.
-- **Observability** — Real-time stats: speedup multiplier, success rate, self-heal recoveries, time saved. Per-user dashboard with 30-day rolling metrics.
 
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) >= 18
 - LLM API key (one of the following):
   - `ANTHROPIC_API_KEY` for Anthropic Claude
-  - `OPENAI_API_KEY` for OpenAI (GPT-4, GPT-4.1)
+  - `OPENAI_API_KEY` for OpenAI (GPT-4.1, GPT-4.5)
   - `GEMINI_API_KEY` for Google Gemini
   - `DEEPSEEK_API_KEY` for DeepSeek (V3, Coder, Reasoner)
   - Or configure Ollama for local models
@@ -40,6 +37,24 @@ Or use directly:
 npx @wundam/orchex
 ```
 
+## Cloud Setup (Optional)
+
+Connect to orchex cloud for managed execution:
+
+```bash
+orchex login
+```
+
+Your browser opens — log in or create a free account, click **Allow**. Token saved automatically.
+
+```bash
+orchex status          # Check tier and trial runs
+orchex logout          # Clear credentials
+orchex --help          # All commands
+```
+
+See the [cloud setup guide](docs/user-guide/cloud-setup.md) for full details.
+
 ## MCP Configuration
 
 Add to your MCP config (e.g. project `.mcp.json`):
@@ -94,13 +109,7 @@ orchex.init({
 orchex.execute({ mode: "auto" })
 ```
 
-Calculates waves from dependencies (topological sort), then for each wave:
-1. Runs **setup** commands for each stream
-2. Builds a **4-layer context prompt** (project, stream files, dependency artifacts, instructions)
-3. Calls the **LLM API** in parallel (one call per stream in the wave)
-4. Parses and **validates artifacts** from responses
-5. **Applies** file operations to the codebase
-6. Runs **verify** commands
+Calculates waves from dependencies (topological sort), then executes each wave in parallel — running setup commands, calling the LLM API, applying file operations with ownership enforcement, and running verification commands.
 
 Wave plan for the example above:
 - **Wave 1:** `types` (no deps)
@@ -138,28 +147,6 @@ orchex.complete({ archive: true })
 | `recover` | Detect and recover stuck streams from mid-execution failures |
 | `reload` | Restart the MCP server process (picks up config/code changes) |
 
-## Architecture
-
-```
-orchex.execute()
-  │
-  For each wave (parallel streams within wave):
-  │
-  ├── 1. Resolve   — load manifest, calculate waves, find target
-  ├── 2. Setup     — run pre-execution commands
-  ├── 3. Context   — build 4-layer prompt
-  │     ├── Project context (file tree, deps, config)
-  │     ├── Stream context (owned + read-only file contents)
-  │     ├── Dependency context (completed artifact summaries)
-  │     └── Instructions (artifact format, ownership rules)
-  ├── 4. Execute   — call LLM API in parallel (Claude/OpenAI/Gemini/DeepSeek/Ollama)
-  ├── 5. Validate  — parse orchex-artifact from response
-  ├── 6. Apply     — write files to codebase (with ownership enforcement)
-  └── 7. Verify    — run post-execution commands
-```
-
-Streams can only modify files listed in their `owns` array. A file-based lock prevents concurrent `execute` calls.
-
 ## Stream Definition
 
 | Field | Type | Description |
@@ -177,120 +164,12 @@ Streams can only modify files listed in their `owns` array. A file-based lock pr
 
 **One stream = one atomic deliverable.** If your stream description uses "and" between distinct concepts, split it.
 
-| Pattern | Success | Why |
-|---------|---------|-----|
-| `docs-installation` (one installation guide) | ✅ | Single focused topic |
-| `integration-claude-code` (one integration guide) | ✅ | Predictable structure |
-| `unified-layout` (implementation + tests) | ✅ | Code + tests are one unit |
-| `docs-structure` (5 different docs) | ❌ | Multiple distinct outputs |
-| `tutorials-first` (setup + walkthrough + summary) | ❌ | Multiple conceptual sections |
-
 **Slicing heuristics:**
-- **`owns` > 4 distinct files** → Split (each file requiring different content should be separate)
-- **`reads` > 4 files** → Split (high synthesis complexity = timeout risk)
+- **`owns` > 4 distinct files** → Split
+- **`reads` > 4 files** → Split (high synthesis complexity)
 - **Expected output > 6,000 tokens** → Split
+- **Code implementation + its tests** → Keep together
 - **Tutorials** → Section into intro/walkthrough/conclusion streams
-- **Code implementation + its tests** → Keep together (they must match)
-- **Templated repetition** → Can bundle (structurally identical outputs)
-
-## Context Budget Intelligence
-
-Orchex Learn tracks context budget usage and adapts thresholds based on execution history.
-
-### Provider-Aware Limits
-
-| Provider | Context Limit | Default Soft | Default Hard |
-|----------|---------------|--------------|--------------|
-| Anthropic | 200,000 | 140,000 | 180,000 |
-| OpenAI | 128,000 | 89,600 | 115,200 |
-| Gemini | 1,000,000 | 700,000 | 900,000 |
-| DeepSeek | 128,000 | 89,600 | 115,200 |
-| Ollama | 128,000 | 89,600 | 115,200 |
-
-### Budget Warnings
-
-When a stream's estimated context exceeds limits, warnings appear in execution output:
-
-```json
-{
-  "event": "budget_warning",
-  "streamId": "large-docs",
-  "violationType": "soft",
-  "estimatedTokens": 156000,
-  "budgetLimit": 140000
-}
-```
-
-### Adaptive Learning
-
-Thresholds improve as execution history accumulates:
-- **Per-category limits** — Code streams vs. documentation vs. tutorials
-- **Confidence levels** — Low (0-49 samples) → Medium (50-99) → High (100+)
-- **Persisted learning** — Saved in `.orchex/learn/thresholds.json`
-
-### Stream Category Recommendations
-
-| Category | Max Owns | Max Reads | Notes |
-|----------|----------|-----------|-------|
-| code | 4 | 4 | Implementation files |
-| docs | 6 | 3 | Documentation pages |
-| tutorial | 3 | 4 | Sectioned tutorials |
-| test | 4 | 5 | Test files with fixtures |
-| migration | 3 | 4 | Schema migrations |
-
-## Stream Validation
-
-Orchex validates stream definitions during `init` and `add_stream`, detecting anti-patterns and suggesting improvements.
-
-### Quality Analysis
-
-```json
-{
-  "qualityAnalysis": {
-    "overallScore": 85,
-    "issues": { "errors": 0, "warnings": 2, "info": 1 },
-    "problematicStreams": ["large-docs"],
-    "splitSuggestions": [{
-      "streamId": "large-docs",
-      "templateName": "Documentation Set",
-      "suggestedStreams": ["docs-overview", "docs-installation", "docs-quickstart"]
-    }]
-  }
-}
-```
-
-### Anti-Patterns Detected
-
-| Pattern | Severity | Description |
-|---------|----------|-------------|
-| High owns count | warning | Stream owns >4 files across multiple directories |
-| High reads count | warning | Stream reads >4 files (synthesis complexity) |
-| Compound plan | warning | Plan contains multiple "and" conjunctions |
-| Empty plan | error | Stream has no plan description |
-| No verification | info | Stream has no verify commands |
-
-### Template-Based Split Suggestions
-
-When anti-patterns are detected, Orchex suggests splits based on known templates:
-- **Documentation Set** — Split into overview, installation, quickstart, etc.
-- **Code Feature** — Split into types, core, tests, docs
-- **Migration** — Split into new implementation, migrate components, deprecate old
-- **Tutorial** — Split into intro, steps, conclusion
-- **API Reference** — Split by module
-
-### Automatic Splitting in `learn`
-
-When `orchex learn` parses a markdown plan, it automatically splits deliverables with mixed concerns into focused sub-streams following `types → migrations → core → tests → docs` ordering. Each sub-stream gets relevant plan content and files for its concern. Dependencies chain sequentially: the first sub-stream inherits the parent's deps, and each subsequent sub-stream depends on the previous one. Cross-deliverable dependencies resolve to the `-core` sibling (the implementation stream) rather than scaffolding streams like `-types` or `-migrations`. Plan authors can use `- Read:` / `- Import:` markers alongside `- Create:` / `- Modify:` to declare read-only file dependencies.
-
-### Learn Pipeline Intelligence
-
-The `learn` pipeline includes several quality improvements:
-
-- **Import-based reads inference** — Parses `import`/`require()` from code blocks in plan documents and auto-adds referenced files to `reads`. Resolves relative imports when filename context is available.
-- **Path validation** — Validates `owns`/`reads` paths against the filesystem when `projectDir` is available. Auto-corrects unambiguous mismatches (e.g., `tools.ts` → `src/tools.ts`) with visible warnings.
-- **Cycle auto-resolution** — When two streams mutually read each other's owned files (context reads, not sequencing requirements), the false dependency cycle is automatically resolved. N-node file-ownership-only cycles are broken by removing the weakest edge. Cycles involving explicit or content-pattern dependencies are preserved and reported as errors.
-- **Structured description extraction** — Complex sections (>3000 chars, >=3 children) get numbered task lists instead of truncated prose, ensuring all sub-sections are visible to the LLM.
-- **Complexity warnings** — Flags deliverables with many sub-sections, suggesting YAML definitions or `deliverable_level: 3` for manual decomposition.
 
 ## Development
 
@@ -317,15 +196,7 @@ For local development, point `.mcp.json` to your local build:
 
 ## Pricing
 
-| Tier | Price | What you get |
-|---|---|---|
-| **Local** | Free | Core MCP tools: 5 streams, 2 waves, single provider, BYOK. |
-| **Cloud Trial** | $0 ($5 credit) | Full cloud features. 30-day credit, no credit card required. |
-| **Pro** | $19/mo | 100 cloud runs/mo, 15 agents, 10 waves, 2 providers, `orchex learn`, full self-healing. |
-| **Team** | $49/user/mo | 500 cloud runs/mo, 25 agents, 25 waves, 3 providers, shared orchestrations, team management. |
-| **Enterprise** | Custom | Unlimited runs + waves, 50+ agents, all providers, self-hosted, SLA + dedicated support. |
-
-1 run = 1 orchestration. BYOK on all plans — you pay your own LLM API costs.
+See [orchex.dev/pricing](https://orchex.dev/pricing) for current plans and limits. Free local tier included.
 
 ## License
 

package/dist/artifacts.d.ts

@@ -68,6 +68,24 @@ export declare function checkOwnership(operations: FileOperation[], owns: string
  * Returns violations, warnings, and allowed files separately.
  */
 export declare function checkOwnershipDetailed(operations: FileOperation[], owns: string[], options?: OwnershipCheckOptions): OwnershipCheckResult;
+/**
+ * Validate syntax of files modified by artifact operations.
+ *
+ * Strategy:
+ * - JSON: in-process JSON.parse (fast, no child process)
+ * - JS/MJS/CJS: node --check (per-file syntax check)
+ * - TS/TSX inside tsconfig include: project-wide `tsc --noEmit --project tsconfig.json`,
+ *   filtered to only report errors from stream-owned files. This respects skipLibCheck,
+ *   global type augmentations (declare global), and include/exclude paths.
+ * - TS/TSX outside tsconfig include (e.g. tests/): per-file `tsc --noEmit
+ *   --isolatedModules --skipLibCheck`, filtered to exclude node_modules errors.
+ *
+ * Returns valid:true if all files pass or have unsupported extensions.
+ */
+export declare function validateSyntax(projectDir: string, operations: FileOperation[]): Promise<{
+    valid: boolean;
+    errors: string[];
+}>;
 /**
  * Apply a stream's artifact to the project codebase.
  * Creates a backup before applying. Rolls back on error.
@@ -109,6 +127,50 @@ export interface StreamBackup {
  * Public API — used by orchestrator for verify isolation.
  */
 export declare function createStreamBackup(projectDir: string, streamId: string, operations: FileOperation[]): Promise<StreamBackup>;
+/**
+ * Persist a stream backup to disk as JSON.
+ * Stored in .orchex/active/backups/<streamId>.json
+ */
+export declare function writeBackup(projectDir: string, backup: StreamBackup): Promise<void>;
+/**
+ * Read a single backup from disk. Returns null if not found.
+ */
+export declare function readBackup(projectDir: string, streamId: string): Promise<StreamBackup | null>;
+/**
+ * Read all persisted backups from disk.
+ */
+export declare function readAllBackups(projectDir: string): Promise<StreamBackup[]>;
+/**
+ * Delete a single backup file.
+ */
+export declare function deleteBackup(projectDir: string, streamId: string): Promise<void>;
+interface IsolationState {
+    streamId: string;
+    phase: 'reverting' | 'testing' | 'restoring';
+    timestamp: string;
+}
+/**
+ * Write isolation state to disk before each dangerous phase.
+ * If the process crashes, recovery can read this to know which
+ * stream was being tested and restore from its disk backup.
+ */
+export declare function writeIsolationState(projectDir: string, streamId: string, phase: IsolationState['phase']): Promise<void>;
+/**
+ * Read isolation state. Returns null if no state file exists.
+ */
+export declare function readIsolationState(projectDir: string): Promise<IsolationState | null>;
+/**
+ * Clear isolation state after successful completion or recovery.
+ */
+export declare function clearIsolationState(projectDir: string): Promise<void>;
+/**
+ * Recover from a crash that happened during verify isolation.
+ * Reads .isolation-state to determine which stream was being tested,
+ * then restores it from its disk backup.
+ *
+ * Returns true if recovery was performed, false if no recovery needed.
+ */
+export declare function recoverFromIsolationCrash(projectDir: string): Promise<boolean>;
 /**
  * Revert a stream's changes using its backup.
  * Restores modified files and removes created files.
@@ -119,14 +181,33 @@ export declare function revertStreamBackup(projectDir: string, backup: StreamBac
  * Used to re-apply changes after a temporary revert during verify isolation.
  */
 export declare function restoreStreamBackup(projectDir: string, backup: StreamBackup): Promise<void>;
+/**
+ * Execute a function with only the specified stream's changes on disk.
+ * Temporarily reverts all other streams' backups, runs fn, then restores them.
+ * Uses crash-recovery state machine (.isolation-state) for safety.
+ *
+ * If otherBackups is empty, fn is called directly without isolation.
+ */
+export declare function withStreamIsolation<T>(projectDir: string, streamId: string, otherBackups: StreamBackup[], fn: () => Promise<T>): Promise<T>;
+export interface IsolationOptions {
+    /** Total timeout for the entire isolation process in ms. Default: 120_000 (2 min). */
+    timeoutMs?: number;
+}
+export interface FileOverlap {
+    path: string;
+    streams: string[];
+}
+export interface IsolationResult {
+    verdicts: Map<string, 'guilty' | 'innocent' | 'unknown'>;
+    fileOverlaps: FileOverlap[];
+}
 /**
  * Isolate which stream(s) caused a verify failure by temporarily
  * reverting each stream's changes and re-running its verify commands.
  *
- * Returns a map of streamId → verdict:
- * - 'guilty': reverting this stream made verify pass
- * - 'innocent': reverting this stream didn't fix verify
- * - 'unknown': couldn't determine (interaction between streams)
+ * Returns an IsolationResult with:
+ * - verdicts: streamId → 'guilty' | 'innocent' | 'unknown'
+ * - fileOverlaps: files modified by multiple streams (diagnostic hint)
  */
-export declare function isolateVerifyFailure(projectDir: string, backups: StreamBackup[], failedVerifyMap: Map<string, string[]>): Promise<Map<string, 'guilty' | 'innocent' | 'unknown'>>;
+export declare function isolateVerifyFailure(projectDir: string, backups: StreamBackup[], failedVerifyMap: Map<string, string[]>, options?: IsolationOptions): Promise<IsolationResult>;
 export {};