mindforge-cc 1.0.0 → 1.0.2

package/sdk/package.json

@@ -1,30 +0,0 @@
-{
-  "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

@@ -1,133 +0,0 @@
-/**
- * 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

@@ -1,63 +0,0 @@
-/**
- * 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

@@ -1,166 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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

@@ -1,87 +0,0 @@
-/**
- * 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

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