sinapse-ai 1.6.0 → 1.7.0

package/.sinapse-ai/core/errors/utils.js

@@ -0,0 +1,187 @@
+/**
+ * core/errors/utils.js — pure helpers for the SINAPSE error module.
+ *
+ * Pure helpers with no external branding, so the logic stays portable. These
+ * helpers are shared by the
+ * registry, the SinapseError class, and the serializer — keep them dependency
+ * free so every other error file can require them safely.
+ */
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function cloneMetadataValue(value, seen = new WeakSet()) {
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      return '[Circular]';
+    }
+
+    seen.add(value);
+    try {
+      return value.map((entry) => cloneMetadataValue(entry, seen));
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  if (isPlainObject(value)) {
+    if (seen.has(value)) {
+      return '[Circular]';
+    }
+
+    seen.add(value);
+    try {
+      return Object.keys(value).reduce((clone, key) => {
+        clone[key] = cloneMetadataValue(value[key], seen);
+        return clone;
+      }, {});
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  return value;
+}
+
+function deepMerge(...sources) {
+  return sources.reduce((merged, source) => {
+    if (!isPlainObject(source)) {
+      return merged;
+    }
+
+    const sourceSeen = new WeakSet();
+    sourceSeen.add(source);
+
+    for (const key of Object.keys(source)) {
+      const current = merged[key];
+      const next = source[key];
+
+      if (isPlainObject(current) && isPlainObject(next)) {
+        merged[key] = deepMerge(current, next);
+      } else {
+        merged[key] = cloneMetadataValue(next, sourceSeen);
+      }
+    }
+
+    return merged;
+  }, {});
+}
+
+function normalizeErrorCode(code) {
+  if (typeof code !== 'string') {
+    return null;
+  }
+
+  const normalized = code.trim().toUpperCase();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizeRecovery(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+/**
+ * sanitizeValue — turn an arbitrary value into something JSON-safe.
+ *
+ * Handles: bigint (→ string), function/symbol (→ String()), Date (→ ISO),
+ * RegExp (→ string), Map/Set (→ arrays), circular references (via WeakSet,
+ * → '[Circular]'), and nested plain objects/arrays. Never throws on a cycle.
+ *
+ * Note on Error values: when `serializeErrorFn` is supplied (the serializer
+ * injects its own `serializeError`), Error instances are delegated to it so
+ * the full typed envelope is produced. When called standalone (no injection),
+ * Error instances fall through to plain-object enumeration — still cycle-safe.
+ */
+function sanitizeValue(value, seen = new WeakSet(), options = {}, serializeErrorFn = null) {
+  if (value === undefined || value === null) {
+    return value;
+  }
+
+  const valueType = typeof value;
+
+  if (valueType === 'bigint') {
+    return value.toString();
+  }
+
+  if (valueType === 'function' || valueType === 'symbol') {
+    return String(value);
+  }
+
+  if (valueType !== 'object') {
+    return value;
+  }
+
+  if (seen.has(value)) {
+    return '[Circular]';
+  }
+
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? value.toString() : value.toISOString();
+  }
+
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+
+  if (value instanceof Error && typeof serializeErrorFn === 'function') {
+    return serializeErrorFn(value, options, seen);
+  }
+
+  seen.add(value);
+
+  try {
+    if (value instanceof Map) {
+      return Array.from(value.entries()).map(([key, entryValue]) => [
+        sanitizeValue(key, seen, options, serializeErrorFn),
+        sanitizeValue(entryValue, seen, options, serializeErrorFn),
+      ]);
+    }
+
+    if (value instanceof Set) {
+      return Array.from(value.values()).map((entryValue) =>
+        sanitizeValue(entryValue, seen, options, serializeErrorFn),
+      );
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((entryValue) => sanitizeValue(entryValue, seen, options, serializeErrorFn));
+    }
+
+    return Object.keys(value).reduce((safeValue, key) => {
+      try {
+        safeValue[key] = sanitizeValue(value[key], seen, options, serializeErrorFn);
+      } catch (error) {
+        safeValue[key] = `[Unserializable: ${error.message}]`;
+      }
+      return safeValue;
+    }, {});
+  } catch (error) {
+    return `[Unserializable: ${error.message}]`;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+module.exports = {
+  isPlainObject,
+  cloneMetadataValue,
+  deepMerge,
+  normalizeErrorCode,
+  normalizeRecovery,
+  hasOwn,
+  sanitizeValue,
+};

package/.sinapse-ai/core/execution/build-orchestrator.js

@@ -22,8 +22,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawn, execSync } = require('child_process');
+const { execSync } = require('child_process');
 const { EventEmitter } = require('events');
+const { runSafe } = require('../utils/spawn-safe');
 
 // Import components
 const { AutonomousBuildLoop, BuildEvent } = require('./autonomous-build-loop');
@@ -501,61 +502,55 @@ The subtask is complete only when verification passes.
   }
 
   /**
-   * Run Claude CLI with prompt
+   * Run Claude CLI with the prompt delivered through stdin.
+   *
+   * Hardened: the prompt goes through stdin (never the command line) and the
+   * process is spawned by argv via cross-spawn — so the prompt can contain
+   * quotes, pipes, `;`, `$()` or any shell metacharacter without ever being
+   * interpreted as a command (shell-injection is structurally impossible).
+   * `--model` is pushed onto the argv (not interpolated into a string).
+   * cross-spawn resolves `claude.cmd` on Windows (native spawn → ENOENT).
+   *
+   * @param {string} prompt - Prompt to execute
+   * @param {string} workDir - Working directory for the CLI
+   * @param {Object} [config={}] - { claudeModel, subtaskTimeout, verbose }
+   * @returns {Promise<{stdout:string, stderr:string, code:number|null}>}
    */
-  async runClaudeCLI(prompt, workDir, config) {
-    return new Promise((resolve, reject) => {
-      const args = [
-        '--print', // Non-interactive mode
-        '--dangerously-skip-permissions', // Allow file writes
-      ];
-
-      if (config.claudeModel) {
-        args.push('--model', config.claudeModel);
-      }
-
-      // Escape prompt for shell
-      const escapedPrompt = prompt.replace(/'/g, "'\\''");
-
-      const fullCommand = `echo '${escapedPrompt}' | claude ${args.join(' ')}`;
+  async runClaudeCLI(prompt, workDir, config = {}) {
+    if (!prompt || typeof prompt !== 'string') {
+      throw new Error('runClaudeCLI requires a non-empty string prompt');
+    }
 
-      this.log(`Running Claude CLI in ${workDir}`, 'debug');
+    const args = [
+      '--print', // Non-interactive mode
+      '--dangerously-skip-permissions', // Allow file writes
+    ];
 
-      const child = spawn('sh', ['-c', fullCommand], {
-        cwd: workDir,
-        env: { ...process.env },
-        timeout: config.subtaskTimeout,
-      });
+    // Model goes onto the argv, never interpolated into a shell string.
+    if (config.claudeModel) {
+      args.push('--model', config.claudeModel);
+    }
 
-      let stdout = '';
-      let stderr = '';
+    this.log(`Running Claude CLI in ${workDir}`, 'debug');
 
-      child.stdout.on('data', (data) => {
-        stdout += data.toString();
-        if (config.verbose) {
-          process.stdout.write(data);
-        }
-      });
+    const result = await runSafe('claude', args, {
+      cwd: workDir,
+      env: { ...process.env },
+      timeout: config.subtaskTimeout,
+      input: prompt,
+      onStdout: config.verbose ? (chunk) => process.stdout.write(chunk) : undefined,
+      onStderr: config.verbose ? (chunk) => process.stderr.write(chunk) : undefined,
+    });
 
-      child.stderr.on('data', (data) => {
-        stderr += data.toString();
-        if (config.verbose) {
-          process.stderr.write(data);
-        }
-      });
+    if (result.success) {
+      return { stdout: result.stdout, stderr: result.stderr, code: result.code };
+    }
 
-      child.on('close', (code) => {
-        if (code === 0) {
-          resolve({ stdout, stderr, code });
-        } else {
-          reject(new Error(`Claude CLI exited with code ${code}: ${stderr}`));
-        }
-      });
+    if (result.signal) {
+      throw new Error(`Claude CLI killed by signal ${result.signal}: ${result.stderr}`);
+    }
 
-      child.on('error', (error) => {
-        reject(error);
-      });
-    });
+    throw new Error(`Claude CLI exited with code ${result.code}: ${result.stderr}`);
   }
 
   /**

package/.sinapse-ai/core/execution/build-state-manager.js

@@ -23,6 +23,11 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const {
+  normalizeError,
+  sanitizeValue: sanitizeErrorValue,
+  serializeError,
+} = require('../errors');
 
 // Optional dependencies with graceful fallback
 let chalk;
@@ -87,6 +92,66 @@ const NotificationType = {
   ABANDONED: 'abandoned',
 };
 
+/**
+ * Converts arbitrary values into stable, JSON-safe log data.
+ *
+ * @param {*} value - Value to sanitize.
+ * @param {WeakSet<object>} [seen=new WeakSet()] - Objects in the current path.
+ * @returns {*} Data-only representation that JSON.stringify can serialize.
+ */
+function sanitizeLogValue(value, seen = new WeakSet()) {
+  return sanitizeErrorValue(value, seen, {
+    includeStack: shouldExposeLogErrorStack(),
+  });
+}
+
+/**
+ * Checks whether persisted attempt logs may include raw error stack traces.
+ *
+ * @returns {boolean} True when stack trace logging is explicitly enabled.
+ */
+function shouldExposeLogErrorStack() {
+  const stackFlag = process.env.DEBUG_ERROR_STACKS || process.env.DEBUG_STACKS || '';
+  return ['1', 'true', 'yes', 'on'].includes(String(stackFlag).toLowerCase());
+}
+
+/**
+ * Stringifies attempt log details without allowing log formatting to throw.
+ *
+ * @param {*} value - Value to stringify.
+ * @returns {string} JSON string or a fallback marker.
+ */
+function stringifyLogDetails(value) {
+  try {
+    return JSON.stringify(sanitizeLogValue(value));
+  } catch (error) {
+    return JSON.stringify(`[Unserializable: ${error.message}]`);
+  }
+}
+
+/**
+ * Normalize a failed build attempt into legacy message plus canonical details.
+ *
+ * @param {*} error - Raw failure error/value.
+ * @param {object} context - Build/subtask context for metadata.
+ * @returns {{ message: string, details: object }} Normalized failure payload.
+ */
+function normalizeFailureError(error, context = {}) {
+  const normalized = normalizeError(error || 'Unknown error', {
+    code: 'SNPS_EXECUTION_FAILED',
+    metadata: {
+      buildState: context,
+    },
+  });
+
+  return {
+    message: normalized.message,
+    details: serializeError(normalized, {
+      includeStack: shouldExposeLogErrorStack(),
+    }),
+  };
+}
+
 // ═══════════════════════════════════════════════════════════════════════════════════
 //                              SCHEMA VALIDATION
 // ═══════════════════════════════════════════════════════════════════════════════════
@@ -185,6 +250,8 @@ class BuildStateManager {
     // Internal state
     this._state = null;
     this._logBuffer = [];
+    this._persistenceAvailable = true;
+    this._persistenceError = null;
   }
 
   // ─────────────────────────────────────────────────────────────────────────────────
@@ -244,14 +311,24 @@ class BuildStateManager {
    * @returns {Object|null} Loaded state or null if not exists
    */
   loadState() {
+    if (!this._persistenceAvailable) {
+      return this._state;
+    }
+
     if (!fs.existsSync(this.stateFilePath)) {
       return null;
     }
 
+    let content;
     try {
-      const content = fs.readFileSync(this.stateFilePath, 'utf-8');
-      const state = JSON.parse(content);
+      content = fs.readFileSync(this.stateFilePath, 'utf-8');
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+      return this._state;
+    }
 
+    try {
+      const state = JSON.parse(content);
       // Validate
       const validation = validateBuildState(state);
       if (!validation.valid) {
@@ -277,11 +354,6 @@ class BuildStateManager {
       throw new Error('No state to save. Call createState() or loadState() first.');
     }
 
-    // Ensure directory exists
-    if (!fs.existsSync(this.planDir)) {
-      fs.mkdirSync(this.planDir, { recursive: true });
-    }
-
     // Only update timestamp if explicitly requested (via saveCheckpoint)
     if (options.updateCheckpoint) {
       this._state.lastCheckpoint = new Date().toISOString();
@@ -293,11 +365,24 @@ class BuildStateManager {
       throw new Error(`Invalid state: ${validation.errors.join(', ')}`);
     }
 
-    // Write state file
-    fs.writeFileSync(this.stateFilePath, JSON.stringify(this._state, null, 2), 'utf-8');
+    if (!this._persistenceAvailable) {
+      return this._state;
+    }
+
+    try {
+      // Ensure directory exists
+      if (!fs.existsSync(this.planDir)) {
+        fs.mkdirSync(this.planDir, { recursive: true });
+      }
+
+      // Write state file
+      fs.writeFileSync(this.stateFilePath, JSON.stringify(this._state, null, 2), 'utf-8');
 
-    // Flush log buffer
-    this._flushLogBuffer();
+      // Flush log buffer
+      this._flushLogBuffer();
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+    }
 
     return this._state;
   }
@@ -341,11 +426,6 @@ class BuildStateManager {
       throw new Error('No state loaded');
     }
 
-    // Ensure checkpoint directory exists
-    if (!fs.existsSync(this.checkpointDir)) {
-      fs.mkdirSync(this.checkpointDir, { recursive: true });
-    }
-
     const checkpointId = this._generateCheckpointId();
     const now = new Date().toISOString();
 
@@ -376,8 +456,19 @@ class BuildStateManager {
     this._updateMetrics(checkpoint);
 
     // Save checkpoint file
-    const checkpointPath = path.join(this.checkpointDir, `${checkpointId}.json`);
-    fs.writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+    if (this._persistenceAvailable) {
+      try {
+        // Ensure checkpoint directory exists
+        if (!fs.existsSync(this.checkpointDir)) {
+          fs.mkdirSync(this.checkpointDir, { recursive: true });
+        }
+
+        const checkpointPath = path.join(this.checkpointDir, `${checkpointId}.json`);
+        fs.writeFileSync(checkpointPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+      } catch (error) {
+        this._markPersistenceUnavailable(error);
+      }
+    }
 
     // Save main state with checkpoint timestamp update
     this.saveState({ updateCheckpoint: true });
@@ -781,12 +872,21 @@ class BuildStateManager {
       throw new Error('No state loaded');
     }
 
+    const attempt =
+      options.attempt ||
+      this._state.failedAttempts.filter((f) => f.subtaskId === subtaskId).length + 1;
+
+    const normalizedFailure = normalizeFailureError(options.error, {
+      storyId: this.storyId,
+      subtaskId,
+      attempt,
+    });
+
     const failure = {
       subtaskId,
-      attempt:
-        options.attempt ||
-        this._state.failedAttempts.filter((f) => f.subtaskId === subtaskId).length + 1,
-      error: options.error || 'Unknown error',
+      attempt,
+      error: normalizedFailure.message,
+      errorDetails: normalizedFailure.details,
       timestamp: new Date().toISOString(),
       approach: options.approach || null,
       duration: options.duration || null,
@@ -808,6 +908,7 @@ class BuildStateManager {
     this._logAttempt(subtaskId, 'failure', {
       attempt: failure.attempt,
       error: failure.error,
+      errorDetails: failure.errorDetails,
       isStuck: isStuck.stuck,
     });
 
@@ -918,6 +1019,8 @@ class BuildStateManager {
    * @private
    */
   _logAttempt(subtaskId, action, details = {}) {
+    if (!this._persistenceAvailable) return;
+
     const entry = {
       timestamp: new Date().toISOString(),
       storyId: this.storyId,
@@ -927,7 +1030,7 @@ class BuildStateManager {
     };
 
     // Format log line
-    const logLine = `[${entry.timestamp}] [${this.storyId}] [${subtaskId}] ${action}: ${JSON.stringify(details)}\n`;
+    const logLine = `[${entry.timestamp}] [${this.storyId}] [${subtaskId}] ${action}: ${stringifyLogDetails(details)}\n`;
 
     this._logBuffer.push(logLine);
 
@@ -943,15 +1046,20 @@ class BuildStateManager {
    */
   _flushLogBuffer() {
     if (this._logBuffer.length === 0) return;
+    if (!this._persistenceAvailable) return;
 
-    // Ensure directory exists
-    if (!fs.existsSync(this.planDir)) {
-      fs.mkdirSync(this.planDir, { recursive: true });
-    }
+    try {
+      // Ensure directory exists
+      if (!fs.existsSync(this.planDir)) {
+        fs.mkdirSync(this.planDir, { recursive: true });
+      }
 
-    // Append to log file
-    fs.appendFileSync(this.logFilePath, this._logBuffer.join(''), 'utf-8');
-    this._logBuffer = [];
+      // Append to log file
+      fs.appendFileSync(this.logFilePath, this._logBuffer.join(''), 'utf-8');
+      this._logBuffer = [];
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+    }
   }
 
   /**
@@ -961,11 +1069,22 @@ class BuildStateManager {
    * @returns {string[]} Log lines
    */
   getAttemptLog(options = {}) {
+    if (!this._persistenceAvailable) {
+      return [];
+    }
+
     if (!fs.existsSync(this.logFilePath)) {
       return [];
     }
 
-    const content = fs.readFileSync(this.logFilePath, 'utf-8');
+    let content;
+    try {
+      content = fs.readFileSync(this.logFilePath, 'utf-8');
+    } catch (error) {
+      this._markPersistenceUnavailable(error);
+      return [];
+    }
+
     let lines = content.split('\n').filter((l) => l.trim());
 
     // Filter by subtask if specified
@@ -1143,6 +1262,39 @@ class BuildStateManager {
     // Silent by default - can be overridden
   }
 
+  /**
+   * Check if file-backed persistence is still available.
+   *
+   * @returns {boolean} True when state/checkpoint/log writes are available.
+   */
+  isPersistenceAvailable() {
+    return this._persistenceAvailable;
+  }
+
+  /**
+   * Get the first persistence error that disabled file-backed writes.
+   *
+   * @returns {Error|null} Persistence error or null when persistence is available.
+   */
+  getPersistenceError() {
+    return this._persistenceError;
+  }
+
+  /**
+   * Disable file-backed persistence after an I/O failure.
+   *
+   * @param {Error} error - Underlying persistence error.
+   * @private
+   */
+  _markPersistenceUnavailable(error) {
+    if (!this._persistenceAvailable) return;
+
+    this._persistenceAvailable = false;
+    this._persistenceError = error instanceof Error ? error : new Error(String(error));
+    this._logBuffer = [];
+    this._log(`Persistence unavailable: ${this._persistenceError.message}`);
+  }
+
   // ─────────────────────────────────────────────────────────────────────────────────
   //                              CLI FORMATTING
   // ─────────────────────────────────────────────────────────────────────────────────