@smartergpt/lexrunner 1.0.0 → 1.3.0

package/docs/cluster-gates-rollback.md

@@ -1,222 +0,0 @@
-# Cluster Gate Execution & Rollback
-
-This document describes the cluster-aware gate execution and rollback mechanism for the merge-weave workflow.
-
-## Overview
-
-After each cluster is resolved (merged), gates (lint, build, tests) are executed. If any gate fails:
-
-1. The cluster patch is reverted (rollback)
-2. A `.weave/merge-patch.diff` is captured
-3. A failure bundle is stored in `.weave/`
-4. A draft PR is opened with artifacts (optional)
-
-## Architecture
-
-### Core Components
-
-- **`clusterGates.ts`**: Cluster-aware gate execution with rollback
-- **`draftPR.ts`**: Draft PR creation for failed clusters
-- **`git/operations.ts`**: Git operations including rollback support
-
-### Flow
-
-```
-1. Resolve Cluster (merge PRs)
-   ↓
-2. Execute Gates
-   ↓
-3. Gates Pass? → Continue to next cluster
-   |
-   └─ Gates Fail? → Rollback + Store Artifacts + Draft PR
-```
-
-## Usage
-
-### Basic Example
-
-```typescript
-import { executeClusterWithGates, ClusterContext } from "./weave/clusterGates.js";
-import { ExecutionState } from "./executionState.js";
-import { GitOperations } from "./git/operations.js";
-
-// Define cluster context
-const cluster: ClusterContext = {
-  clusterIndex: 0,
-  items: plan.items,
-  baseBranch: "main",
-  integrationBranch: "weave/integration-2024",
-  weaveDir: ".weave",
-};
-
-// Execute cluster with gates
-const result = await executeClusterWithGates(cluster, plan, executionState, gitOps, {
-  skipGates: false,
-  timeoutMs: 30000,
-});
-
-if (!result.success) {
-  console.error(`Cluster ${cluster.clusterIndex} failed`);
-  console.log(`Rollback performed: ${result.rollbackPerformed}`);
-  console.log(`Artifacts: ${result.artifactPaths.join(", ")}`);
-}
-```
-
-## Artifacts
-
-When a cluster fails gates, the following artifacts are stored in `.weave/`:
-
-### 1. Merge Patch Diff
-
-- **Path**: `.weave/cluster-{N}-merge-patch.diff`
-- **Content**: Git diff showing what was merged before rollback
-- **Purpose**: Review what changes caused the failure
-
-### 2. Failure Bundle
-
-- **Path**: `.weave/cluster-{N}-failure-bundle.json`
-- **Content**: JSON with failed gates, timestamps, rollback info
-- **Schema**:
-  ```json
-  {
-    "clusterIndex": 0,
-    "timestamp": "2024-12-17T07:00:00.000Z",
-    "baseBranch": "main",
-    "integrationBranch": "weave/integration-xyz",
-    "items": ["PR-123", "PR-456"],
-    "failedGates": [
-      {
-        "item": "PR-123",
-        "gate": "test",
-        "status": "fail",
-        "exitCode": 1,
-        "stderr": "Test failed..."
-      }
-    ],
-    "mergePatchDiff": "diff --git ...",
-    "rollbackSha": "abc123...",
-    "artifactPaths": [...]
-  }
-  ```
-
-### 3. Gate Artifacts
-
-- **Path**: `.weave/cluster-{N}/gates/{item}/{gate}/`
-- **Content**: Gate-specific outputs (junit.xml, coverage, etc.)
-
-## Draft PR Creation
-
-When gates fail, a draft PR is automatically created (if GitHub API is available):
-
-- **Title**: `[DRAFT] Cluster {N} gate failures - {items}`
-- **Body**: Includes:
-  - Failure summary table
-  - Links to artifacts
-  - Merge patch diff preview
-  - Rollback instructions
-  - Next steps
-
-The draft PR helps with:
-
-- Team visibility of failures
-- Artifact sharing
-- Collaboration on fixes
-- Audit trail
-
-## Rollback Mechanism
-
-### How Rollback Works
-
-1. **Before cluster execution**: Capture current HEAD SHA
-2. **Execute gates**: Run all gates for cluster items
-3. **On failure**:
-   - Capture `git diff {base}..HEAD` as merge-patch.diff
-   - Execute `git reset --hard {baseSha}`
-   - Store artifacts
-   - Create failure branch and draft PR
-
-### Git Operations
-
-The rollback uses:
-
-- `getCurrentHead()`: Get SHA before cluster execution
-- `getDiff(base, head)`: Capture merge-patch.diff
-- `resetHard(sha)`: Perform rollback
-
-### Safety
-
-- Rollback is **deterministic** - always returns to exact pre-cluster state
-- All artifacts are stored **before** rollback
-- Rollback SHA is stored in failure bundle for manual recovery if needed
-
-## Testing
-
-Integration tests verify:
-
-- ✅ Gates execute successfully for passing clusters
-- ✅ Rollback occurs on gate failure
-- ✅ Artifacts are stored in `.weave/`
-- ✅ Merge-patch.diff is captured
-- ✅ Failure bundle is created
-- ✅ Git state is restored to pre-cluster SHA
-
-Run tests:
-
-```bash
-npm test tests/cluster-gates-rollback.spec.ts
-```
-
-## Configuration
-
-### Gate Timeout
-
-Default: 30 seconds per gate
-Configure via options:
-
-```typescript
-const result = await executeClusterWithGates(cluster, plan, state, git, {
-  timeoutMs: 60000, // 60 seconds
-});
-```
-
-### Skip Gates (Dev Mode)
-
-```typescript
-const result = await executeClusterWithGates(cluster, plan, state, git, {
-  skipGates: true, // Skip all gates (not recommended)
-});
-```
-
-## Error Handling
-
-### Transient Errors
-
-- Retryable gates (e.g., flaky tests) use policy retry configuration
-- See `plan.policy.retries` for retry settings
-
-### Permanent Errors
-
-- Immediate failure without retry
-- Rollback triggered
-- Artifacts stored
-
-### Partial Failures
-
-- If any gate in cluster fails, entire cluster rolls back
-- No partial rollback - all or nothing per cluster
-
-## Best Practices
-
-1. **Keep clusters small**: Easier to debug failures
-2. **Review failure bundles**: Check `.weave/` artifacts
-3. **Fix and retry**: Address issues in original PRs, re-run workflow
-4. **Use draft PRs**: Enable team collaboration on failures
-5. **Monitor timeouts**: Adjust `timeoutMs` for slow gates
-
-## Future Enhancements
-
-- [ ] Automatic retry with exponential backoff
-- [ ] Cluster-level conflict prediction before merge
-- [ ] Parallel gate execution within cluster
-- [ ] Smart rollback (partial rollback for independent failures)
-- [ ] Integration with GitHub Checks API

package/docs/command-creation-guide.md

@@ -1,485 +0,0 @@
-# Command Creation Guide
-
-This guide shows how to create new commands in the modular lexrunner CLI architecture.
-
-## Overview
-
-The lexrunner CLI uses a **modular command architecture** where:
-
-- Each command lives in its own module under `src/commands/`
-- Commands are registered in `src/cli.ts` using a standard pattern
-- Shared utilities are in `src/cli/` (output, flags, exit handling)
-- Business logic stays in `src/core/`
-
-## Quick Start
-
-### 1. Create Command Module
-
-Create a new file in `src/commands/` following the naming convention:
-
-```bash
-# For single-word commands
-src/commands/mycommand.ts
-
-# For hyphenated commands (use camelCase for filename)
-src/commands/myCommand.ts  # for "my-command"
-```
-
-### 2. Command Template
-
-Use this template as your starting point:
-
-```typescript
-// src/commands/myCommand.ts
-import { Command } from "commander";
-import { writeJsonOutput } from "../cli/output.js";
-import { throwExit } from "../cli/exitHandler.js";
-
-/**
- * Register the my-command command
- */
-export function registerMyCommandCommand(program: Command): void {
-  program
-    .command("my-command")
-    .description("Brief description of what this command does")
-    .argument("<required-arg>", "Description of required argument")
-    .option("-o, --option <value>", "Description of optional flag")
-    .option("--json", "Output as JSON")
-    .action(async (requiredArg, options) => {
-      try {
-        const result = await executeMyCommand(requiredArg, options);
-
-        if (options.json) {
-          writeJsonOutput(result);
-        } else {
-          console.log(formatMyCommandOutput(result));
-        }
-      } catch (error) {
-        throwExit(error, 1);
-      }
-    });
-}
-
-/**
- * Pure, testable business logic
- */
-async function executeMyCommand(
-  arg: string,
-  options: { option?: string }
-): Promise<MyCommandResult> {
-  // Your implementation here
-  return {
-    success: true,
-    data: `Processed ${arg} with option ${options.option}`,
-  };
-}
-
-/**
- * Format output for human consumption
- */
-function formatMyCommandOutput(result: MyCommandResult): string {
-  return `✅ ${result.data}`;
-}
-
-interface MyCommandResult {
-  success: boolean;
-  data: string;
-}
-```
-
-### 3. Register in CLI
-
-Add your command to `src/cli.ts`:
-
-```typescript
-// src/cli.ts
-import { registerMyCommandCommand } from "./commands/myCommand.js";
-
-// ... existing imports ...
-
-function registerCommands(program: Command): void {
-  // ... existing registrations ...
-  registerMyCommandCommand(program);
-}
-```
-
-### 4. Add Tests
-
-Create a test file in `tests/commands/`:
-
-```typescript
-// tests/commands/myCommand.spec.ts
-import { describe, it, expect } from "vitest";
-import { registerMyCommandCommand } from "../../src/commands/myCommand.js";
-import { Command } from "commander";
-
-describe("myCommand", () => {
-  it("should register command with correct name", () => {
-    const program = new Command();
-    registerMyCommandCommand(program);
-
-    const command = program.commands.find((cmd) => cmd.name() === "my-command");
-    expect(command).toBeDefined();
-  });
-
-  it("should execute successfully", async () => {
-    // Test your command logic
-  });
-});
-```
-
-## Best Practices
-
-### Separation of Concerns
-
-✅ **DO:**
-
-```typescript
-// Command handler (thin wrapper)
-.action(async (args, options) => {
-  const result = await executeMyCommand(args, options);
-  handleOutput(result, options);
-});
-
-// Pure business logic (easily testable)
-async function executeMyCommand(args, options) {
-  // All logic here
-}
-```
-
-❌ **DON'T:**
-
-```typescript
-// Business logic mixed with CLI handling
-.action(async (args, options) => {
-  // Complex logic inline - hard to test!
-  const data = processData(args);
-  if (options.json) {
-    console.log(JSON.stringify(data));
-  } else {
-    console.log(formatData(data));
-  }
-});
-```
-
-### Output Handling
-
-Always support both human and JSON output:
-
-```typescript
-if (options.json) {
-  writeJsonOutput(result); // Use helper from cli/output.js
-} else {
-  console.log(formatForHuman(result));
-}
-```
-
-### Error Handling
-
-Use `throwExit` for consistent error handling:
-
-```typescript
-import { throwExit } from "../cli/exitHandler.js";
-
-try {
-  const result = await riskyOperation();
-} catch (error) {
-  throwExit(error, 1); // Exit with code 1
-}
-```
-
-### Type Safety
-
-Define interfaces for your results:
-
-```typescript
-interface MyCommandResult {
-  success: boolean;
-  items: string[];
-  metadata?: Record<string, unknown>;
-}
-```
-
-## Command Categories
-
-### Simple Commands
-
-**Characteristics:**
-
-- No complex dependencies
-- Minimal business logic
-- Quick to execute
-
-**Examples:** `completion`, `merge-order`, `status`
-
-**Location:** `src/commands/simpleCommand.ts`
-
-### Complex Commands
-
-**Characteristics:**
-
-- Orchestrate multiple operations
-- May spawn subprocesses
-- Require extensive error handling
-
-**Examples:** `execute`, `merge`, `autopilot`
-
-**Location:** `src/commands/complexCommand.ts`
-
-### Command Groups
-
-For related commands, use subdirectories:
-
-```
-src/commands/
-├── orchestrate/
-│   ├── fanout.ts
-│   ├── merge.ts
-│   └── status.ts
-└── audit/
-    ├── validate.ts
-    └── export.ts
-```
-
-Register command groups:
-
-```typescript
-// src/commands/orchestrate/index.ts
-import { Command } from "commander";
-import { registerFanoutCommand } from "./fanout.js";
-import { registerMergeCommand } from "./merge.js";
-
-export function registerOrchestrateCommands(program: Command): void {
-  const orchestrate = program.command("orchestrate").description("Orchestration commands");
-
-  registerFanoutCommand(orchestrate);
-  registerMergeCommand(orchestrate);
-}
-```
-
-## Testing Patterns
-
-### Unit Tests
-
-Test your business logic functions directly:
-
-```typescript
-describe("executeMyCommand", () => {
-  it("should process valid input", async () => {
-    const result = await executeMyCommand("test", { option: "value" });
-    expect(result.success).toBe(true);
-  });
-
-  it("should handle errors gracefully", async () => {
-    await expect(executeMyCommand("", {})).rejects.toThrow();
-  });
-});
-```
-
-### Integration Tests
-
-Test the full command flow:
-
-```typescript
-import { executeCommand } from "../helpers/cli-test-utils.js";
-
-describe("my-command integration", () => {
-  it("should execute via CLI", async () => {
-    const output = await executeCommand("my-command arg --option value");
-    expect(output).toContain("✅");
-  });
-
-  it("should support JSON output", async () => {
-    const output = await executeCommand("my-command arg --json");
-    const result = JSON.parse(output);
-    expect(result.success).toBe(true);
-  });
-});
-```
-
-## Common Utilities
-
-### Output (`src/cli/output.js`)
-
-```typescript
-import { writeJsonOutput } from "../cli/output.js";
-
-// Write JSON to stdout
-writeJsonOutput({ success: true, data: [] });
-```
-
-### Exit Handling (`src/cli/exitHandler.js`)
-
-```typescript
-import { throwExit, CLIExitSignal } from "../cli/exitHandler.js";
-
-// Graceful exit with error message
-throwExit(new Error("Operation failed"), 1);
-
-// Exit with signal
-throw new CLIExitSignal(0, "Success message");
-```
-
-### Global Flags (`src/cli/flags.js`)
-
-```typescript
-import { parseGlobalFlags } from "../cli/flags.js";
-
-// Parse global flags if needed in your command
-const globalOpts = parseGlobalFlags(process.argv);
-```
-
-## Documentation Requirements
-
-When adding a new command:
-
-1. **Update `docs/cli.md`** - Add command reference
-2. **Add JSDoc comments** - Document exported functions
-3. **Update CHANGELOG.md** - Note the new command
-4. **Add examples** - Include in `docs/tutorials/` if complex
-
-Example JSDoc:
-
-````typescript
-/**
- * Register the my-command command
- *
- * @param program - Commander program instance
- *
- * @example
- * ```typescript
- * import { Command } from 'commander';
- * import { registerMyCommandCommand } from './commands/myCommand.js';
- *
- * const program = new Command();
- * registerMyCommandCommand(program);
- * ```
- */
-export function registerMyCommandCommand(program: Command): void {
-  // ...
-}
-````
-
-## Checklist
-
-Before submitting a PR with a new command:
-
-- [ ] Created command module in `src/commands/`
-- [ ] Registered command in `src/cli.ts`
-- [ ] Added unit tests in `tests/commands/`
-- [ ] Added integration test (if applicable)
-- [ ] Updated `docs/cli.md` with command reference
-- [ ] Added JSDoc comments to exported functions
-- [ ] Tested with `--json` flag
-- [ ] Tested error handling (invalid inputs, missing files, etc.)
-- [ ] Verified all gates pass (`npm run lint`, `npm run typecheck`, `npm test`)
-- [ ] Updated CHANGELOG.md
-
-## Examples
-
-See these existing commands for reference:
-
-### Simple Command Example
-
-**File:** `src/commands/completion.ts`
-
-- Minimal dependencies
-- Pure output generation
-- ~50 lines of code
-
-### Medium Command Example
-
-**File:** `src/commands/discover.ts`
-
-- GitHub API integration
-- Option parsing
-- JSON/human output
-- ~150 lines of code
-
-### Complex Command Example
-
-**File:** `src/commands/execute.ts`
-
-- Multi-stage orchestration
-- Subprocess management
-- Progress reporting
-- Error recovery
-- ~300+ lines of code
-
-## Common Pitfalls
-
-### ❌ Avoid Inline Business Logic
-
-```typescript
-// BAD: Logic in action handler
-.action(async (args, options) => {
-  const data = await fetchData();
-  const filtered = data.filter(x => x.active);
-  const sorted = filtered.sort((a, b) => a.name.localeCompare(b.name));
-  console.log(sorted);
-});
-```
-
-```typescript
-// GOOD: Separate business logic
-.action(async (args, options) => {
-  const result = await executeMyCommand(args, options);
-  handleOutput(result, options);
-});
-
-async function executeMyCommand(args, options) {
-  const data = await fetchData();
-  return processData(data);
-}
-```
-
-### ❌ Avoid Console.log for Errors
-
-```typescript
-// BAD
-catch (error) {
-  console.log('Error:', error.message);
-  process.exit(1);
-}
-```
-
-```typescript
-// GOOD
-catch (error) {
-  throwExit(error, 1);
-}
-```
-
-### ❌ Don't Mix Output Formats
-
-```typescript
-// BAD: JSON polluted with human messages
-if (options.json) {
-  console.log("Processing..."); // ❌ Non-JSON output
-  writeJsonOutput(result);
-}
-```
-
-```typescript
-// GOOD: Clean JSON output
-if (options.json) {
-  writeJsonOutput(result);
-} else {
-  console.log("Processing...");
-  console.log(formatResult(result));
-}
-```
-
-## Need Help?
-
-- Check existing commands in `src/commands/` for patterns
-- Review tests in `tests/commands/` for examples
-- Ask in GitHub Discussions
-- Read the [CLI Architecture](../docs/architecture.md) doc
-
-## Related Documentation
-
-- [CLI Reference](../docs/cli.md) - Full command documentation
-- [Architecture](../docs/architecture.md) - Overall system design
-- [Testing Guide](../docs/testing.md) - Testing patterns and tools
-- [CONTRIBUTING.md](../CONTRIBUTING.md) - General contribution guidelines