mindforge-cc 1.0.0

package/sdk/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mindforge/sdk",
+  "version": "1.0.0",
+  "description": "MindForge SDK \u2014 Programmatic API for embedding MindForge in tools",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "node tests/sdk.test.js",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "mindforge",
+    "agentic-framework",
+    "claude",
+    "sdk"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.0.0"
+  }
+}

package/sdk/src/client.ts

@@ -0,0 +1,133 @@
+/**
+ * MindForge SDK — Main Client
+ */
+
+import { EventEmitter } from 'events';
+import * as fs from 'fs';
+import * as path from 'path';
+import type {
+  MindForgeConfig, HealthReport, AuditLogEntry
+} from './types';
+
+export class MindForgeClient extends EventEmitter {
+  private config: Required<MindForgeConfig>;
+  private projectRoot: string;
+
+  constructor(config: MindForgeConfig = {}) {
+    super();
+    this.projectRoot = config.projectRoot ?? process.cwd();
+    this.config = {
+      projectRoot:    this.projectRoot,
+      apiKey:         config.apiKey ?? process.env.ANTHROPIC_API_KEY ?? '',
+      ciMode:         config.ciMode ?? (process.env.CI === 'true'),
+      outputFormat:   config.outputFormat ?? 'json',
+      taskTimeoutMs:  config.taskTimeoutMs ?? 600_000,
+    };
+  }
+  // ── Project state ──────────────────────────────────────────────────────────
+  isInitialised(): boolean {
+    return fs.existsSync(path.join(this.projectRoot, '.planning', 'PROJECT.md'));
+  }
+
+  readState(): Record<string, unknown> | null {
+    const statePath = path.join(this.projectRoot, '.planning', 'STATE.md');
+    if (!fs.existsSync(statePath)) return null;
+    return { raw: fs.readFileSync(statePath, 'utf8') };
+  }
+
+  readHandoff(): Record<string, unknown> | null {
+    const handoffPath = path.join(this.projectRoot, '.planning', 'HANDOFF.json');
+    if (!fs.existsSync(handoffPath)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  // ── Health check ───────────────────────────────────────────────────────────
+  async health(): Promise<HealthReport> {
+    const errors:   Array<{ category: string; message: string; autoRepairable: boolean }> = [];
+    const warnings: Array<{ category: string; message: string; autoRepairable: boolean }> = [];
+    const info:     Array<{ category: string; message: string; autoRepairable: boolean }> = [];
+
+    const requiredFiles = [
+      '.planning/STATE.md',
+      '.planning/HANDOFF.json',
+      '.planning/AUDIT.jsonl',
+      '.mindforge/org/CONVENTIONS.md',
+    ];
+
+    for (const file of requiredFiles) {
+      const fullPath = path.join(this.projectRoot, file);
+      if (!fs.existsSync(fullPath)) {
+        warnings.push({ category: 'installation', message: `Missing: ${file}`, autoRepairable: false });
+      }
+    }
+
+    // Check HANDOFF.json validity
+    const handoff = this.readHandoff();
+    if (handoff && !handoff.schema_version) {
+      errors.push({ category: 'state', message: 'HANDOFF.json missing schema_version field', autoRepairable: false });
+    }
+
+    // Check AUDIT.jsonl
+    const auditPath = path.join(this.projectRoot, '.planning', 'AUDIT.jsonl');
+    if (fs.existsSync(auditPath)) {
+      const lineCount = fs.readFileSync(auditPath, 'utf8').split('\n').filter(Boolean).length;
+      if (lineCount > 9000) {
+        warnings.push({ category: 'audit', message: `AUDIT.jsonl has ${lineCount} lines — archive soon`, autoRepairable: true });
+      }
+      info.push({ category: 'audit', message: `AUDIT.jsonl: ${lineCount} entries`, autoRepairable: false });
+    }
+
+    return {
+      overallStatus: errors.length > 0 ? 'error' : warnings.length > 0 ? 'warning' : 'healthy',
+      errors,
+      warnings,
+      informational: info,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  // ── Audit log reading ──────────────────────────────────────────────────────
+  readAuditLog(filter?: { event?: string; phase?: number; since?: Date }): AuditLogEntry[] {
+    const auditPath = path.join(this.projectRoot, '.planning', 'AUDIT.jsonl');
+    if (!fs.existsSync(auditPath)) return [];
+
+    return fs.readFileSync(auditPath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((line: string) => { try { return JSON.parse(line) as AuditLogEntry; } catch { return null; } })
+      .filter((entry: AuditLogEntry | null): entry is AuditLogEntry => !!entry)
+      .filter(entry => {
+        if (filter?.event && entry.event !== filter.event) return false;
+        if (filter?.phase !== undefined && entry.phase !== filter.phase) return false;
+        if (filter?.since && new Date(entry.timestamp) < filter.since) return false;
+        return true;
+      });
+  }
+
+  // ── Metrics reading ────────────────────────────────────────────────────────
+  readSessionMetrics(limit = 10): unknown[] {
+    const metricsPath = path.join(this.projectRoot, '.mindforge', 'metrics', 'session-quality.jsonl');
+    if (!fs.existsSync(metricsPath)) return [];
+
+    return fs.readFileSync(metricsPath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .slice(-limit)
+      .map((line: string) => { try { return JSON.parse(line); } catch { return null; } })
+      .filter(Boolean);
+  }
+
+  // ── Config validation ──────────────────────────────────────────────────────
+  validateConfig(): { valid: boolean; errors: string[]; warnings: string[] } {
+    const configPath = path.join(this.projectRoot, 'MINDFORGE.md');
+    if (!fs.existsSync(configPath)) {
+      return { valid: true, errors: [], warnings: ['MINDFORGE.md not found — using defaults'] };
+    }
+    // Full validation via bin/validate-config.js
+    return { valid: true, errors: [], warnings: [] };
+  }
+}

package/sdk/src/commands.ts

@@ -0,0 +1,63 @@
+/**
+ * MindForge SDK — Command Builders
+ * Builds the command strings that can be sent to Claude Code / Antigravity
+ * via their programmatic APIs.
+ */
+
+export interface CommandOptions {
+  flags?: string[];
+  args?: string[];
+}
+
+export const commands = {
+  /**
+   * Build a /mindforge:health command string
+   */
+  health(opts: CommandOptions = {}): string {
+    const flags = opts.flags?.join(' ') ?? '';
+    return `/mindforge:health ${flags}`.trim();
+  },
+
+  /**
+   * Build a /mindforge:plan-phase command string
+   */
+  planPhase(phase: number, opts: CommandOptions = {}): string {
+    const flags = opts.flags?.join(' ') ?? '';
+    return `/mindforge:plan-phase ${phase} ${flags}`.trim();
+  },
+
+  /**
+   * Build a /mindforge:execute-phase command string
+   */
+  executePhase(phase: number, opts: CommandOptions = {}): string {
+    const flags = opts.flags?.join(' ') ?? '';
+    return `/mindforge:execute-phase ${phase} ${flags}`.trim();
+  },
+
+  /**
+   * Build a /mindforge:security-scan command string
+   */
+  securityScan(path?: string, opts: CommandOptions = {}): string {
+    const flags = opts.flags?.join(' ') ?? '';
+    return `/mindforge:security-scan ${path ?? ''} ${flags}`.trim();
+  },
+
+  /**
+   * Build a /mindforge:audit command string with filters
+   */
+  audit(filter: { phase?: number; event?: string; since?: string } = {}): string {
+    const parts = ['/mindforge:audit'];
+    if (filter.phase)  parts.push(`--phase ${filter.phase}`);
+    if (filter.event)  parts.push(`--event ${filter.event}`);
+    if (filter.since)  parts.push(`--since ${filter.since}`);
+    return parts.join(' ');
+  },
+
+  /**
+   * Build a /mindforge:pr-review command string
+   */
+  prReview(opts: CommandOptions = {}): string {
+    const flags = opts.flags?.join(' ') ?? '';
+    return `/mindforge:pr-review ${flags}`.trim();
+  },
+};

package/sdk/src/events.ts

@@ -0,0 +1,166 @@
+/**
+ * MindForge SDK — Server-Sent Events (SSE) stream for real-time progress
+ * Enables external tools to subscribe to MindForge execution progress.
+ */
+
+import * as http from 'http';
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface SSEClient {
+  id: string;
+  response: http.ServerResponse;
+}
+
+export class MindForgeEventStream {
+  private clients: SSEClient[] = [];
+  private server: http.Server | null = null;
+  private auditWatcher: fs.FSWatcher | null = null;
+  private lastAuditLine = 0;
+
+  /**
+   * Start the SSE server on the given port
+   */
+  start(port = 7337): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server = http.createServer((req, res) => {
+        if (req.url !== '/events') {
+          res.writeHead(404);
+          res.end();
+          return;
+        }
+
+        // SECURITY: Only allow connections from localhost
+        const clientIp = req.socket.remoteAddress;
+        const isLocalhost = clientIp === '127.0.0.1' ||
+                            clientIp === '::1' ||
+                            clientIp === '::ffff:127.0.0.1';
+        if (!isLocalhost) {
+          res.writeHead(403);
+          res.end('Forbidden: MindForge event stream is localhost-only');
+          return;
+        }
+
+        // CORS: Only allow localhost origins (exact match, not wildcard)
+        const origin = req.headers.origin;
+        const allowedOriginPattern = /^https?:\/\/localhost(:\d+)?$/;
+        const corsOrigin = origin && allowedOriginPattern.test(origin)
+          ? origin
+          : 'http://localhost';
+
+        res.writeHead(200, {
+          'Content-Type':  'text/event-stream',
+          'Cache-Control': 'no-cache',
+          'Connection':    'keep-alive',
+          'Access-Control-Allow-Origin': corsOrigin,
+          'X-Content-Type-Options': 'nosniff',
+        });
+
+        const clientId = Date.now().toString();
+        this.clients.push({ id: clientId, response: res });
+
+        // Send initial connection event
+        this.sendEvent(res, 'connected', { clientId, timestamp: new Date().toISOString() });
+
+        // Clean up on disconnect
+        req.on('close', () => {
+          this.clients = this.clients.filter(c => c.id !== clientId);
+        });
+      });
+
+      // SECURITY: Bind to localhost ONLY — not all interfaces
+      this.server.listen(port, '127.0.0.1', () => {
+        console.log(`MindForge event stream: http://localhost:${port}/events (localhost only)`);
+        resolve();
+      });
+
+      this.server.on('error', (err: NodeJS.ErrnoException) => {
+        if (err.code === 'EADDRINUSE') {
+          reject(new Error(
+            `Port ${port} is already in use. Use: new MindForgeEventStream().start(${port + 1})`
+          ));
+        } else {
+          reject(err);
+        }
+      });
+    });
+  }
+
+  /**
+   * Watch AUDIT.jsonl for new entries and broadcast as SSE events
+   */
+  watchAuditLog(projectRoot: string): void {
+    const auditPath = path.join(projectRoot, '.planning', 'AUDIT.jsonl');
+
+    if (!fs.existsSync(auditPath)) {
+      // Create the file if it doesn't exist yet
+      fs.writeFileSync(auditPath, '');
+    }
+
+    // Set initial line count
+    const content = fs.readFileSync(auditPath, 'utf8');
+    this.lastAuditLine = content.split('\n').filter(Boolean).length;
+
+    try {
+      this.auditWatcher = fs.watch(auditPath, () => {
+        const lines = fs.readFileSync(auditPath, 'utf8')
+          .split('\n')
+          .filter(Boolean);
+
+        // Broadcast new lines
+        for (let i = this.lastAuditLine; i < lines.length; i++) {
+          try {
+            const entry = JSON.parse(lines[i]);
+            this.broadcast('audit_entry', entry);
+          } catch {
+            // Ignore parse errors for incomplete lines
+          }
+        }
+
+        this.lastAuditLine = lines.length;
+      });
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOSPC') {
+        // Linux inotify limit reached — fall back to polling
+        console.warn('MindForge: inotify limit reached, falling back to 2s polling');
+        setInterval(() => {
+          const lines = fs.readFileSync(auditPath, 'utf8').split('\n').filter(Boolean);
+          for (let i = this.lastAuditLine; i < lines.length; i++) {
+            try { this.broadcast('audit_entry', JSON.parse(lines[i])); } catch { /* ignore */ }
+          }
+          this.lastAuditLine = lines.length;
+        }, 2000);
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Broadcast an event to all connected clients
+   */
+  broadcast(eventType: string, data: unknown): void {
+    this.clients.forEach(client => {
+      this.sendEvent(client.response, eventType, data);
+    });
+  }
+
+  private sendEvent(res: http.ServerResponse, type: string, data: unknown): void {
+    try {
+      res.write(`event: ${type}\n`);
+      res.write(`data: ${JSON.stringify(data)}\n\n`);
+    } catch {
+      // Client disconnected
+    }
+  }
+
+  /**
+   * Stop the event stream server
+   */
+  stop(): void {
+    this.auditWatcher?.close();
+    this.server?.close();
+    this.clients.forEach(c => c.response.end());
+    this.clients = [];
+  }
+}

package/sdk/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * MindForge SDK — Public API
+ * @module @mindforge/sdk
+ */
+
+export { MindForgeClient } from './client';
+export { MindForgeEventStream } from './events';
+export { commands } from './commands';
+export type { CommandOptions } from './commands';
+export type {
+  MindForgeConfig,
+  PhaseResult,
+  TaskResult,
+  SecurityFinding,
+  GateResult,
+  HealthReport,
+  HealthIssue,
+  MindForgeEvent,
+  AuditLogEntry,
+} from './types';
+
+export const VERSION = '1.0.0';

package/sdk/src/types.ts

@@ -0,0 +1,87 @@
+/**
+ * MindForge SDK — Type Definitions
+ */
+
+export interface MindForgeConfig {
+  /** Path to the project root (default: cwd) */
+  projectRoot?: string;
+  /** Claude API key (default: ANTHROPIC_API_KEY env var) */
+  apiKey?: string;
+  /** CI mode — disables interactive features */
+  ciMode?: boolean;
+  /** Output format for events */
+  outputFormat?: 'json' | 'text' | 'github-annotations';
+  /** Timeout per task in milliseconds (default: 600000 — 10 minutes) */
+  taskTimeoutMs?: number;
+}
+
+export interface PhaseResult {
+  phase: number;
+  status: 'success' | 'failure' | 'warning' | 'skipped';
+  tasksCompleted: number;
+  tasksTotal: number;
+  commits: string[];
+  securityFindings: SecurityFinding[];
+  qualityGateResults: GateResult[];
+  durationMs: number;
+  errorMessage?: string;
+}
+
+export interface TaskResult {
+  planId: string;
+  taskName: string;
+  status: 'completed' | 'failed' | 'skipped';
+  commitSha?: string;
+  verifyOutput?: string;
+  durationMs: number;
+  errorMessage?: string;
+}
+
+export interface SecurityFinding {
+  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+  owaspCategory: string;
+  file: string;
+  line: number;
+  description: string;
+  remediation: string;
+  remediated: boolean;
+}
+
+export interface GateResult {
+  gate: string;
+  status: 'passed' | 'failed' | 'warning' | 'skipped';
+  detail?: string;
+}
+
+export interface HealthReport {
+  overallStatus: 'healthy' | 'warning' | 'error';
+  errors: HealthIssue[];
+  warnings: HealthIssue[];
+  informational: HealthIssue[];
+  timestamp: string;
+}
+
+export interface HealthIssue {
+  category: string;
+  message: string;
+  autoRepairable: boolean;
+  fixCommand?: string;
+}
+
+export type MindForgeEvent =
+  | { type: 'task_started';   phase: number; plan: string; taskName: string }
+  | { type: 'task_completed'; phase: number; plan: string; commitSha: string }
+  | { type: 'task_failed';    phase: number; plan: string; error: string }
+  | { type: 'wave_started';   phase: number; wave: number; taskCount: number }
+  | { type: 'wave_completed'; phase: number; wave: number }
+  | { type: 'phase_completed'; phase: number; result: PhaseResult }
+  | { type: 'security_finding'; finding: SecurityFinding }
+  | { type: 'gate_result';    gate: GateResult }
+  | { type: 'log';            level: 'info' | 'warn' | 'error'; message: string };
+
+export interface AuditLogEntry {
+  timestamp: string;
+  event: string;
+  phase?: number;
+  [key: string]: unknown;
+}

package/sdk/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}