mindforge-sdk 11.8.0 → 11.9.5

package/README.md

@@ -1,17 +1,17 @@
-# @mindforge/sdk
+# mindforge-sdk
 
 TypeScript SDK for embedding MindForge in tools, dashboards, and CI pipelines.
 
 ## Installation
 
 ```bash
-npm install @mindforge/sdk
+npm install mindforge-sdk
 ```
 
 ## Quick start
 
 ```typescript
-import { MindForgeClient } from '@mindforge/sdk';
+import { MindForgeClient } from 'mindforge-sdk';
 
 const client = new MindForgeClient({
   projectRoot: '/path/to/project',
@@ -33,8 +33,29 @@ console.log(metrics);
 
 ## Real-time event streaming
 
+`MindForgeEventStream` is the supported path and it is self-contained: it starts its own SSE server,
+tails `.planning/AUDIT.jsonl`, and broadcasts each new entry as an `audit_entry` event. Verified end to
+end — `GET /events` returns `text/event-stream`, and appending to the audit log produces a broadcast.
+Note the `watchAuditLog()` call below is required: `start()` serves the stream but does not begin
+tailing on its own.
+
+`WebSocketEventStream` is also exported, and it comes with two constraints worth knowing before you
+reach for it:
+
+- **It needs a global `WebSocket` that this package does not provide.** `engines.node` is `>=18.0.0`
+  and `dependencies` is empty, so on Node 18 or 20 you must install `ws` yourself and assign it to
+  `globalThis.WebSocket`. On Node 22+ the global exists. Calling `connect()` without one throws an
+  error saying so, rather than a bare `ReferenceError`.
+- **MindForge ships no WebSocket server.** The default URL is `ws://127.0.0.1:7337/ws`, but the
+  dashboard exposes no `/ws` upgrade path — so this client is for connecting to a server *you* run,
+  not to MindForge itself. Use `MindForgeEventStream` if you want events from MindForge.
+
+Reconnection is automatic (5 attempts, linear backoff). A reconnect that fails is delivered to an
+`'error'` listener registered with `on('error', handler)`; once the attempts are exhausted a `'close'`
+event fires with the reason, so a dead stream is observable rather than silent.
+
 ```typescript
-import { MindForgeEventStream } from '@mindforge/sdk';
+import { MindForgeEventStream } from 'mindforge-sdk';
 
 const stream = new MindForgeEventStream();
 await stream.start(7337);
@@ -64,7 +85,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 v11.8.0
+## New in v11.9.5
 
 ### Additional exports
 
@@ -73,7 +94,7 @@ import {
   MindForgeClient,
   MindForgeEventStream,
   WebSocketEventStream,
-  VERSION,              // '11.8.0'
+  VERSION,              // '11.9.5'
 } from 'mindforge-sdk';
 
 import type {
@@ -89,7 +110,7 @@ import type {
 ### Streaming execution
 
 ```typescript
-import { MindForgeClient, WebSocketEventStream } from 'mindforge-sdk';
+import { MindForgeClient } from 'mindforge-sdk';
 
 const client = new MindForgeClient({ projectRoot: '.' });
 const { stream } = await client.streamExecution(1);

package/dist/events.d.ts

@@ -33,6 +33,14 @@ export declare class WebSocketEventStream {
     private maxReconnectAttempts;
     private listeners;
     constructor(url?: string);
+    /**
+     * Dispatch to registered listeners. One dispatch path for messages, reconnect failures and
+     * stream death, so those three cannot drift apart in how they treat a throwing listener.
+     *
+     * A missing 'error' listener does NOT mean silence: a reconnect that fails invisibly leaves the
+     * consumer believing the stream is live, which is the failure mode this class was already in.
+     */
+    private emit;
     connect(): Promise<void>;
     on(eventType: string, handler: EventHandler): void;
     off(eventType: string, handler: EventHandler): void;

package/dist/events.js

@@ -192,7 +192,37 @@ class WebSocketEventStream {
         this.maxReconnectAttempts = 5;
         this.listeners = new Map();
     }
+    /**
+     * Dispatch to registered listeners. One dispatch path for messages, reconnect failures and
+     * stream death, so those three cannot drift apart in how they treat a throwing listener.
+     *
+     * A missing 'error' listener does NOT mean silence: a reconnect that fails invisibly leaves the
+     * consumer believing the stream is live, which is the failure mode this class was already in.
+     */
+    emit(eventType, data) {
+        const handlers = this.listeners.get(eventType);
+        if (!handlers || handlers.size === 0) {
+            if (eventType === 'error' && typeof process !== 'undefined' && process.stderr) {
+                const message = data instanceof Error ? data.message : String(data);
+                process.stderr.write(`[MindForge SDK] event stream error: ${message}\n`);
+            }
+            return;
+        }
+        // A listener that throws must not take the stream — or the process — with it.
+        handlers.forEach((handler) => { try {
+            handler(data);
+        }
+        catch { /* listener fault */ } });
+    }
     async connect() {
+        // Fail fast and legibly. `WebSocket` is declared, not imported, and sdk/package.json has NO
+        // dependencies while engines.node is >=18.0.0 — so on Node 18 or 20 the constructor below is a
+        // bare `ReferenceError: WebSocket is not defined`, which tells the caller nothing about why.
+        if (typeof WebSocket === 'undefined') {
+            throw new Error('WebSocketEventStream requires a global WebSocket: Node 22+, a browser, or the optional '
+                + '\'ws\' package installed and assigned to globalThis.WebSocket. This SDK declares no '
+                + 'runtime dependencies, so it does not install one for you.');
+        }
         return new Promise((resolve, reject) => {
             this.ws = new WebSocket(this.url);
             this.ws.onopen = () => {
@@ -203,15 +233,33 @@ class WebSocketEventStream {
             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));
+                    this.emit(parsed.type, parsed.data);
                 }
                 catch { /* malformed message */ }
             };
             this.ws.onclose = () => {
                 if (this.reconnectAttempts < this.maxReconnectAttempts) {
                     this.reconnectAttempts++;
-                    setTimeout(() => this.connect(), 1000 * this.reconnectAttempts);
+                    setTimeout(() => {
+                        // A scheduled reconnect is fire-and-forget, so nothing awaits the promise it returns.
+                        // Without this .catch(), `connect()` rejecting via onerror is an UNHANDLED REJECTION —
+                        // and under Node's default mode that is fatal: it TERMINATES THE CALLER'S PROCESS.
+                        // Reproduced against the compiled module with a stub socket whose reconnect calls
+                        // onerror: exit code 1, and the line after the wait never ran.
+                        this.connect().catch((err) => this.emit('error', err));
+                    }, 1000 * this.reconnectAttempts);
+                }
+                else if (this.maxReconnectAttempts > 0) {
+                    // Attempts exhausted. This branch did not exist: the stream simply went quiet, leaving
+                    // the consumer with no way to learn it was dead.
+                    //
+                    // Guarded on maxReconnectAttempts > 0 because disconnect() sets it to 0 (:276). Without
+                    // the guard, a DELIBERATE disconnect would emit 'close' with reason "reconnect attempts
+                    // exhausted" — telling the caller their stream died when they closed it themselves.
+                    this.emit('close', {
+                        reason: 'reconnect attempts exhausted',
+                        attempts: this.reconnectAttempts,
+                    });
                 }
             };
         });

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * MindForge SDK — Public API
- * @module @mindforge/sdk
+ * @module mindforge-sdk
  */
 export { MindForgeClient } from './client';
 export { MindForgeEventStream, WebSocketEventStream } from './events';
@@ -8,4 +8,4 @@ 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, StreamChunk, StreamingExecutionResult, BatchExecutionRequest, BatchExecutionResult, } from './types';
-export declare const VERSION = "11.8.0";
+export declare const VERSION = "11.9.5";

package/dist/index.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * MindForge SDK — Public API
- * @module @mindforge/sdk
+ * @module mindforge-sdk
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = exports.MindForgeMemory = exports.batch = exports.commands = exports.WebSocketEventStream = exports.MindForgeEventStream = exports.MindForgeClient = void 0;
@@ -15,4 +15,4 @@ Object.defineProperty(exports, "commands", { enumerable: true, get: function ()
 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 = '11.8.0';
+exports.VERSION = '11.9.5';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mindforge-sdk",
-  "version": "11.8.0",
-  "description": "MindForge SDK \u2014 Programmatic API for embedding MindForge in tools",
+  "version": "11.9.5",
+  "description": "MindForge SDK — Programmatic API for embedding MindForge in tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -32,6 +32,11 @@
     "sdk"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sairam0424/MindForge.git",
+    "directory": "sdk"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -40,7 +45,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.9.1",
     "eslint": "^9.0.0",
     "globals": "^15.0.0",
     "typescript": "^5.4.0",