mindforge-cc 8.1.1 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/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/.mindforge/mirrors/mirror-sre-776a1cf9/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/.mindforge/mirrors/mirror-sre-776a1cf9/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/.mindforge/mirrors/mirror-sre-776a1cf9/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/.mindforge/mirrors/mirror-sre-776a1cf9/sdk/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * MindForge SDK — Public API
+ * @module @mindforge/sdk
+ */
+
+export { MindForgeClient } from './client';
+export { MindForgeEventStream } from './events';
+export { commands } from './commands';
+export { MindForgeMemory } from './memory';
+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/.mindforge/mirrors/mirror-sre-776a1cf9/sdk/src/memory.ts

@@ -0,0 +1,257 @@
+/**
+ * MindForge v2.4.0 SDK — Memory API (RAG 2.0)
+ * TypeScript interface to the MindForge Knowledge Graph.
+ */
+
+import * as path from 'path';
+import * as os   from 'os';
+
+// Import JS implementations
+// @ts-expect-error - JS modules lack declaration files
+import * as Store  from '../../bin/memory/knowledge-store';
+// @ts-expect-error - JS modules lack declaration files
+import * as Loader from '../../bin/memory/session-memory-loader';
+// @ts-expect-error - JS modules lack declaration files
+import * as Graph  from '../../bin/memory/knowledge-graph';
+// @ts-expect-error - JS modules lack declaration files
+import * as Shadow from '../../bin/memory/auto-shadow';
+// @ts-expect-error - JS modules lack declaration files
+import * as Embedder from '../../bin/memory/embedding-engine';
+
+export type KnowledgeType =
+  | 'architectural_decision'
+  | 'code_pattern'
+  | 'bug_pattern'
+  | 'team_preference'
+  | 'domain_knowledge';
+
+export interface KnowledgeEntry {
+  id:               string;
+  timestamp:        string;
+  type:             KnowledgeType;
+  topic:            string;
+  content:          string;
+  source:           string;
+  project:          string;
+  confidence:       number;
+  tags:             string[];
+  linked_adrs:      string[];
+  times_referenced: number;
+  last_referenced:  string | null;
+  deprecated:       boolean;
+  deprecated_by:    string | null;
+  // Type-specific optional fields
+  decision?:        string;
+  rationale?:       string;
+  root_cause?:      string;
+  fix?:             string;
+  preference?:      string;
+  strength?:        'strong' | 'moderate' | 'weak';
+  bug_category?:    string;
+  domain?:          string;
+  tech_stack?:      string[];
+  global?:          boolean;
+  promoted_at?:     string;
+}
+
+export interface QueryParams {
+  tags?:           string[];
+  topic?:          string;
+  type?:           KnowledgeType;
+  minConfidence?:  number;
+  limit?:          number;
+  includeGlobal?:  boolean;
+  includeDeprecated?: boolean;
+  project?:        string;
+}
+
+export interface MemoryStats {
+  total_entries:      number;
+  active_entries:     number;
+  deprecated_entries: number;
+  by_type:            Record<string, number>;
+  avg_confidence:     number;
+}
+
+export interface SessionContext {
+  preferences:  KnowledgeEntry[];
+  decisions:    KnowledgeEntry[];
+  bugPatterns:  KnowledgeEntry[];
+  codePatterns: KnowledgeEntry[];
+  domain:       KnowledgeEntry[];
+  count:        number;
+  formatted:    string;
+}
+
+export type EdgeType =
+  | 'RELATED_TO'
+  | 'CAUSED_BY'
+  | 'SUPERSEDES'
+  | 'DEPENDS_ON'
+  | 'INFORMS'
+  | 'CONTRADICTS';
+
+export interface GraphEdge {
+  id:              string;
+  sourceId:        string;
+  targetId:        string;
+  type:            EdgeType;
+  weight:          number;
+  reason:          string;
+  metadata:        Record<string, unknown>;
+  created_at:      string;
+  last_traversed:  string | null;
+  traversal_count: number;
+  deprecated:      boolean;
+  checksum:        string;
+}
+
+export interface ShadowContext {
+  formatted:  string;
+  items:      ShadowItem[];
+  count:      number;
+  budgetUsed: number;
+}
+
+export interface ShadowItem {
+  id:         string;
+  type:       KnowledgeType;
+  topic:      string;
+  content:    string;
+  confidence: number;
+  score:      number;
+  source:     string;
+  tags:       string[];
+  edges?:     string;
+}
+
+export interface GraphStats {
+  total_nodes:     number;
+  total_edges:     number;
+  edges_by_type:   Record<string, number>;
+  orphan_nodes:    number;
+  avg_weight:      number;
+  connected_ratio: number;
+}
+
+export interface TraversalResult {
+  id:    string;
+  depth: number;
+  path:  string[];
+}
+
+/**
+ * MindForge Knowledge Graph client (RAG 2.0).
+ */
+export class MindForgeMemory {
+  private readonly memoryDir: string;
+  private readonly kbPath:    string;
+  private readonly globalPath: string;
+
+  constructor(private readonly projectRoot: string = process.cwd()) {
+    this.memoryDir  = path.join(projectRoot, '.mindforge', 'memory');
+    this.kbPath     = path.join(this.memoryDir, 'knowledge-base.jsonl');
+    this.globalPath = path.join(os.homedir(), '.mindforge', 'global-knowledge-base.jsonl');
+  }
+
+  // ── Knowledge Store Operations ───────────────────────────────────────────
+
+  /** Add a new knowledge entry. */
+  public async remember(entry: Partial<KnowledgeEntry>): Promise<string> {
+    return Store.add(entry);
+  }
+
+  /** Query the knowledge base. */
+  public async query(params: QueryParams = {}): Promise<KnowledgeEntry[]> {
+    return Store.query(params);
+  }
+
+  /** Reinforce an entry (increase confidence). */
+  public async reinforce(id: string): Promise<void> {
+    Store.reinforce(id);
+  }
+
+  /** Deprecate an entry. */
+  public async deprecate(id: string, reason: string, supersededBy?: string): Promise<void> {
+    Store.deprecate(id, reason, supersededBy);
+  }
+
+  /** Get memory statistics. */
+  public async getStats(): Promise<MemoryStats> {
+    return Store.stats();
+  }
+
+  /** Load context for a session. */
+  public async loadContext(opts: { techStack?: string[], phase?: string, topic?: string }): Promise<SessionContext> {
+    const result = Loader.loadForSession(opts);
+    return result;
+  }
+
+  // ── Knowledge Graph Operations (RAG 2.0) ──────────────────────────────
+
+  /** Add a typed edge between two knowledge nodes. */
+  public async addEdge(edge: {
+    sourceId: string;
+    targetId: string;
+    type: EdgeType;
+    weight?: number;
+    reason?: string;
+  }): Promise<string> {
+    return Graph.addEdge(edge);
+  }
+
+  /** Get all edges for a specific node. */
+  public async getEdges(nodeId: string, opts?: {
+    direction?: 'outgoing' | 'incoming' | 'both';
+    edgeTypes?: EdgeType[];
+  }): Promise<GraphEdge[]> {
+    return Graph.getNodeEdges(nodeId, opts);
+  }
+
+  /** BFS traversal from a starting node. */
+  public async traverse(startId: string, maxDepth?: number, opts?: {
+    edgeTypes?: EdgeType[];
+    minWeight?: number;
+  }): Promise<TraversalResult[]> {
+    return Graph.traverse(startId, maxDepth, opts);
+  }
+
+  /** Find related knowledge via hybrid embedding + graph query. */
+  public async findRelated(queryText: string, opts?: {
+    maxHops?: number;
+    topK?: number;
+  }): Promise<Array<{ id: string; score: number; source: string }>> {
+    const allEntries = Store.readAll(true);
+    const { vectors, df, N } = Embedder.buildEmbeddings(allEntries);
+    return Graph.findRelated(queryText, vectors, df, N, opts);
+  }
+
+  /** Generate auto-shadow context for a task. */
+  public async autoShadow(opts: {
+    taskDescription: string;
+    excludeIds?: string[];
+    techStack?: string[];
+  }): Promise<ShadowContext> {
+    return Shadow.generateShadowContext(opts);
+  }
+
+  /** Get graph statistics. */
+  public async getGraphStats(): Promise<GraphStats> {
+    return Graph.graphStats();
+  }
+
+  /** Apply weight decay to stale edges. */
+  public async decayEdges(): Promise<{ decayed: number; pruned: number }> {
+    return Graph.applyDecay();
+  }
+
+  /** Detect cycles in directed edge types. */
+  public async detectCycles(): Promise<string[][]> {
+    return Graph.detectCycles();
+  }
+
+  /** Verify SHA-256 integrity of all edges. */
+  public async verifyIntegrity(): Promise<{ valid: number; corrupted: string[] }> {
+    return Graph.verifyEdgeIntegrity();
+  }
+}