mindforge-sdk 10.7.0 → 11.6.0

package/README.md

@@ -64,7 +64,7 @@ if (!valid) console.error(errors);
 - The SDK operates on local files and provides no network authentication. Do not expose SDK
   endpoints to the public internet.
 
-## New in v9.0.0
+## New in v11.6.0
 
 ### Additional exports
 
@@ -72,13 +72,71 @@ if (!valid) console.error(errors);
 import {
   MindForgeClient,
   MindForgeEventStream,
-  VERSION,              // '9.0.0'
-} from '@mindforge/sdk';
+  WebSocketEventStream,
+  VERSION,              // '11.6.0'
+} from 'mindforge-sdk';
 
 import type {
-  WaveExecutionResult,  // Result type returned by wave execution operations
-  MigrationResult,      // Result type returned by schema migration operations
-} from '@mindforge/sdk';
+  WaveExecutionResult,
+  MigrationResult,
+  StreamChunk,
+  StreamingExecutionResult,
+  BatchExecutionRequest,
+  BatchExecutionResult,
+} from 'mindforge-sdk';
+```
+
+### Streaming execution
+
+```typescript
+import { MindForgeClient, WebSocketEventStream } from 'mindforge-sdk';
+
+const client = new MindForgeClient({ projectRoot: '.' });
+const { stream } = await client.streamExecution(1);
+
+for await (const chunk of stream) {
+  if (chunk.type === 'content') process.stdout.write(chunk.content!);
+  if (chunk.type === 'done') break;
+}
+```
+
+### Batch execution
+
+Runs commands concurrently (semaphore-bounded by `maxConcurrency`, default 3). Each
+task's `command` is the executable and `options.args` is a **string array** — it is NOT a
+shell string. Commands run with `shell: false`, so arguments are passed directly to the
+process and are safe from shell injection.
+
+```typescript
+const batch = await client.batchExecute({
+  tasks: [
+    { id: 'task-a', command: 'node', options: { args: ['--version'] } },
+    { id: 'task-b', command: 'git',  options: { args: ['rev-parse', 'HEAD'] } },
+  ],
+  maxConcurrency: 4,
+});
+
+for (const entry of batch.results) {
+  if (entry.status === 'fulfilled') {
+    // entry.result is { stdout, stderr, exitCode }
+    const { stdout, stderr, exitCode } = entry.result as {
+      stdout: string; stderr: string; exitCode: number;
+    };
+    console.log(`${entry.taskId} exited ${exitCode}: ${stdout.trim()}`);
+  } else {
+    // entry.status === 'rejected'
+    console.error(`${entry.taskId} failed: ${entry.error}`);
+  }
+}
+
+console.log(`batch finished in ${batch.totalDurationMs}ms`);
+```
+
+### Runtime config validation
+
+```typescript
+const { valid, errors } = client.validateRuntimeConfig();
+if (!valid) console.error(errors);
 ```
 
 ### New `MindForgeClient` methods

package/dist/client.d.ts

@@ -2,7 +2,7 @@
  * MindForge SDK — Main Client
  */
 import { EventEmitter } from 'events';
-import type { MindForgeConfig, HealthReport, AuditLogEntry } from './types';
+import type { MindForgeConfig, HealthReport, AuditLogEntry, StreamingExecutionResult, BatchExecutionRequest, BatchExecutionResult } from './types';
 export declare class MindForgeClient extends EventEmitter {
     private config;
     private projectRoot;
@@ -25,4 +25,13 @@ export declare class MindForgeClient extends EventEmitter {
     readAutoState(): Record<string, unknown> | null;
     getDbPath(): string;
     isDatabaseInitialized(): boolean;
+    streamExecution(phase: number, options?: {
+        taskFilter?: string;
+    }): Promise<StreamingExecutionResult>;
+    batchExecute(request: BatchExecutionRequest): Promise<BatchExecutionResult>;
+    validateRuntimeConfig(): {
+        valid: boolean;
+        errors: string[];
+    };
+    private executeCommand;
 }

package/dist/client.js

@@ -38,8 +38,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MindForgeClient = void 0;
 const events_1 = require("events");
+const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const events_2 = require("./events");
 class MindForgeClient extends events_1.EventEmitter {
     constructor(config = {}) {
         super();
@@ -228,5 +230,121 @@ class MindForgeClient extends events_1.EventEmitter {
     isDatabaseInitialized() {
         return fs.existsSync(this.getDbPath());
     }
+    // ── v11 Phase 5B: Streaming execution ─────────────────────────────────────
+    async streamExecution(phase, options) {
+        const eventSource = new events_2.WebSocketEventStream();
+        await eventSource.connect();
+        const chunks = [];
+        let resolveNext = null;
+        eventSource.on('stream_chunk', (raw) => {
+            const data = raw; // socket payload is untyped JSON; narrow at the boundary
+            if (resolveNext) {
+                resolveNext({ value: data, done: data.type === 'done' });
+                resolveNext = null;
+            }
+            else {
+                chunks.push(data);
+            }
+        });
+        const stream = {
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        if (chunks.length > 0) {
+                            const chunk = chunks.shift();
+                            if (chunk.type === 'done')
+                                eventSource.disconnect();
+                            return Promise.resolve({ value: chunk, done: chunk.type === 'done' });
+                        }
+                        return new Promise(resolve => { resolveNext = resolve; });
+                    },
+                    return() {
+                        eventSource.disconnect();
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                };
+            }
+        };
+        return { phaseId: phase, taskId: options?.taskFilter || '*', stream };
+    }
+    // ── v11 Phase 5B: Batch execution with semaphore-based concurrency ────────
+    async batchExecute(request) {
+        const startTime = Date.now();
+        const maxConcurrency = request.maxConcurrency || 3;
+        const results = [];
+        let running = 0;
+        const queue = [...request.tasks];
+        await new Promise((resolve) => {
+            const processNext = () => {
+                if (queue.length === 0 && running === 0) {
+                    resolve();
+                    return;
+                }
+                while (running < maxConcurrency && queue.length > 0) {
+                    const task = queue.shift();
+                    running++;
+                    this.executeCommand(task.command, task.options)
+                        .then(result => {
+                        results.push({ taskId: task.id, status: 'fulfilled', result });
+                    })
+                        .catch(error => {
+                        results.push({ taskId: task.id, status: 'rejected', error: error.message });
+                    })
+                        .finally(() => {
+                        running--;
+                        processNext();
+                    });
+                }
+            };
+            processNext();
+        });
+        return { results, totalDurationMs: Date.now() - startTime };
+    }
+    // ── v11 Phase 5B: Runtime config validation ───────────────────────────────
+    validateRuntimeConfig() {
+        const errors = [];
+        if (!this.config.projectRoot)
+            errors.push('projectRoot is required');
+        if (this.config.taskTimeoutMs && this.config.taskTimeoutMs < 0)
+            errors.push('taskTimeoutMs must be positive');
+        return { valid: errors.length === 0, errors };
+    }
+    executeCommand(command, options) {
+        const args = Array.isArray(options?.args) ? options.args : [];
+        const cwd = options?.cwd ?? this.projectRoot;
+        const timeoutMs = this.config.taskTimeoutMs;
+        return new Promise((resolve, reject) => {
+            const child = (0, child_process_1.spawn)(command, args, { cwd, shell: false });
+            let stdout = '';
+            let stderr = '';
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                child.kill('SIGTERM');
+                setTimeout(() => { if (!child.killed)
+                    child.kill('SIGKILL'); }, 2000).unref();
+                settled = true;
+                reject(new Error(`Command timed out after ${timeoutMs}ms: ${command}`));
+            }, timeoutMs);
+            timer.unref();
+            child.stdout?.on('data', (d) => { stdout += d.toString(); });
+            child.stderr?.on('data', (d) => { stderr += d.toString(); });
+            child.on('error', (err) => {
+                if (settled)
+                    return;
+                clearTimeout(timer);
+                settled = true;
+                reject(err);
+            });
+            child.on('close', (code) => {
+                if (settled)
+                    return;
+                clearTimeout(timer);
+                settled = true;
+                resolve({ stdout, stderr, exitCode: code ?? -1 });
+            });
+        });
+    }
 }
 exports.MindForgeClient = MindForgeClient;

package/dist/commands.d.ts

@@ -37,3 +37,4 @@ export declare const commands: {
      */
     prReview(opts?: CommandOptions): string;
 };
+export declare function batch(commands: string[]): string;

package/dist/commands.js

@@ -6,6 +6,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commands = void 0;
+exports.batch = batch;
 exports.commands = {
     /**
      * Build a /mindforge:health command string
@@ -56,3 +57,6 @@ exports.commands = {
         return `/mindforge:pr-review ${flags}`.trim();
     },
 };
+function batch(commands) {
+    return commands.map(cmd => cmd.trim()).filter(Boolean).join(' && ');
+}

package/dist/events.d.ts

@@ -25,3 +25,17 @@ export declare class MindForgeEventStream {
      */
     stop(): void;
 }
+type EventHandler = (data: unknown) => void;
+export declare class WebSocketEventStream {
+    private url;
+    private ws;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private listeners;
+    constructor(url?: string);
+    connect(): Promise<void>;
+    on(eventType: string, handler: EventHandler): void;
+    off(eventType: string, handler: EventHandler): void;
+    disconnect(): void;
+}
+export {};

package/dist/events.js

@@ -37,7 +37,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MindForgeEventStream = void 0;
+exports.WebSocketEventStream = exports.MindForgeEventStream = void 0;
 const http = __importStar(require("http"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -184,3 +184,51 @@ class MindForgeEventStream {
     }
 }
 exports.MindForgeEventStream = MindForgeEventStream;
+class WebSocketEventStream {
+    constructor(url = 'ws://127.0.0.1:7337/ws') {
+        this.url = url;
+        this.ws = null;
+        this.reconnectAttempts = 0;
+        this.maxReconnectAttempts = 5;
+        this.listeners = new Map();
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(this.url);
+            this.ws.onopen = () => {
+                this.reconnectAttempts = 0;
+                resolve();
+            };
+            this.ws.onerror = (err) => reject(err);
+            this.ws.onmessage = (event) => {
+                try {
+                    const parsed = JSON.parse(String(event.data));
+                    const handlers = this.listeners.get(parsed.type) || new Set();
+                    handlers.forEach(handler => handler(parsed.data));
+                }
+                catch { /* malformed message */ }
+            };
+            this.ws.onclose = () => {
+                if (this.reconnectAttempts < this.maxReconnectAttempts) {
+                    this.reconnectAttempts++;
+                    setTimeout(() => this.connect(), 1000 * this.reconnectAttempts);
+                }
+            };
+        });
+    }
+    on(eventType, handler) {
+        if (!this.listeners.has(eventType)) {
+            this.listeners.set(eventType, new Set());
+        }
+        this.listeners.get(eventType).add(handler);
+    }
+    off(eventType, handler) {
+        this.listeners.get(eventType)?.delete(handler);
+    }
+    disconnect() {
+        this.maxReconnectAttempts = 0;
+        this.ws?.close();
+        this.ws = null;
+    }
+}
+exports.WebSocketEventStream = WebSocketEventStream;

package/dist/index.d.ts

@@ -3,9 +3,9 @@
  * @module @mindforge/sdk
  */
 export { MindForgeClient } from './client';
-export { MindForgeEventStream } from './events';
-export { commands } from './commands';
+export { MindForgeEventStream, WebSocketEventStream } from './events';
+export { commands, batch } from './commands';
 export { MindForgeMemory } from './memory';
 export type { CommandOptions } from './commands';
-export type { MindForgeConfig, PhaseResult, TaskResult, SecurityFinding, GateResult, HealthReport, HealthIssue, MindForgeEvent, AuditLogEntry, WaveExecutionResult, MigrationResult, } from './types';
-export declare const VERSION = "10.7.0";
+export type { MindForgeConfig, PhaseResult, TaskResult, SecurityFinding, GateResult, HealthReport, HealthIssue, MindForgeEvent, AuditLogEntry, WaveExecutionResult, MigrationResult, StreamChunk, StreamingExecutionResult, BatchExecutionRequest, BatchExecutionResult, } from './types';
+export declare const VERSION = "11.6.0";

package/dist/index.js

@@ -4,13 +4,15 @@
  * @module @mindforge/sdk
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.MindForgeMemory = exports.commands = exports.MindForgeEventStream = exports.MindForgeClient = void 0;
+exports.VERSION = exports.MindForgeMemory = exports.batch = exports.commands = exports.WebSocketEventStream = exports.MindForgeEventStream = exports.MindForgeClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "MindForgeClient", { enumerable: true, get: function () { return client_1.MindForgeClient; } });
 var events_1 = require("./events");
 Object.defineProperty(exports, "MindForgeEventStream", { enumerable: true, get: function () { return events_1.MindForgeEventStream; } });
+Object.defineProperty(exports, "WebSocketEventStream", { enumerable: true, get: function () { return events_1.WebSocketEventStream; } });
 var commands_1 = require("./commands");
 Object.defineProperty(exports, "commands", { enumerable: true, get: function () { return commands_1.commands; } });
+Object.defineProperty(exports, "batch", { enumerable: true, get: function () { return commands_1.batch; } });
 var memory_1 = require("./memory");
 Object.defineProperty(exports, "MindForgeMemory", { enumerable: true, get: function () { return memory_1.MindForgeMemory; } });
-exports.VERSION = '10.7.0';
+exports.VERSION = '11.6.0';

package/dist/types.d.ts

@@ -123,3 +123,36 @@ export interface MigrationResult {
     migrationsApplied?: string[];
     backupDir?: string;
 }
+/** v11 Phase 5B: Streaming execution chunk from WebSocket event stream */
+export interface StreamChunk {
+    type: 'content' | 'tool_use' | 'thinking' | 'done';
+    content?: string;
+    toolName?: string;
+    toolInput?: Record<string, unknown>;
+    finishReason?: 'end_turn' | 'max_tokens' | 'stop_sequence';
+}
+/** v11 Phase 5B: Result handle for a streaming execution */
+export interface StreamingExecutionResult {
+    phaseId: number;
+    taskId: string;
+    stream: AsyncIterable<StreamChunk>;
+}
+/** v11 Phase 5B: Request payload for batch execution */
+export interface BatchExecutionRequest {
+    tasks: Array<{
+        id: string;
+        command: string;
+        options?: Record<string, unknown>;
+    }>;
+    maxConcurrency?: number;
+}
+/** v11 Phase 5B: Aggregated result from batch execution */
+export interface BatchExecutionResult {
+    results: Array<{
+        taskId: string;
+        status: 'fulfilled' | 'rejected';
+        result?: unknown;
+        error?: string;
+    }>;
+    totalDurationMs: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindforge-sdk",
-  "version": "10.7.0",
+  "version": "11.6.0",
   "description": "MindForge SDK \u2014 Programmatic API for embedding MindForge in tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,9 +20,10 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "node tests/sdk.test.js",
+    "pretest": "npm run build",
+    "test": "node tests/sdk.test.js && node tests/execute-command.test.js",
     "lint": "eslint .",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm test"
   },
   "keywords": [
     "mindforge",