sinapse-ai 9.4.0 → 9.5.0

package/.sinapse-ai/core/doctor/checks/rules-files.js

@@ -58,5 +58,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run, EXPECTED_RULES };
+// Story A.3: rules files ship with the framework; exceptions indicate real damage.
+const onError = 'fail';
+
+module.exports = { name, run, EXPECTED_RULES, onError };
 

package/.sinapse-ai/core/doctor/checks/settings-json.js

@@ -118,5 +118,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: .claude/settings.json is a hard requirement. Exceptions are FAIL.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/checks/skills-count.js

@@ -69,5 +69,8 @@ async function run(context) {
   };
 }
 
-module.exports = { name, run };
+// Story A.3: skills dir ships with the framework.
+const onError = 'fail';
+
+module.exports = { name, run, onError };
 

package/.sinapse-ai/core/doctor/index.js

@@ -1,12 +1,23 @@
 /**
  * SINAPSE Doctor — Environment Health Check Orchestrator
  *
- * Runs 12 modular checks against the SINAPSE environment and returns
+ * Runs modular checks against the SINAPSE environment and returns
  * structured results with optional --fix, --json, and --dry-run support.
  *
+ * Exception Classification (Story A.3):
+ * Each check module may export an `onError` field with one of:
+ *   - 'fail' (default) — thrown exceptions map to a FAIL verdict
+ *   - 'warn'           — thrown exceptions map to a WARN verdict
+ *   - 'skip'           — thrown exceptions cause the check to be excluded
+ *                        from results entirely
+ *
+ * This replaces the previous behavior where the generic catch block
+ * marked every exception as FAIL, producing false alarms on fresh
+ * installs (no git repo, empty registry, missing agent memory dirs).
+ *
  * @module sinapse-ai/doctor
- * @version 2.0.0
- * @story INS-4.1
+ * @version 2.1.0
+ * @story INS-4.1, A.3
  */
 
 const path = require('path');
@@ -15,7 +26,46 @@ const { formatText } = require('./formatters/text');
 const { formatJson } = require('./formatters/json');
 const { applyFixes } = require('./fix-handler');
 
-const DOCTOR_VERSION = '2.0.0';
+const DOCTOR_VERSION = '2.1.0';
+
+const VALID_ON_ERROR = new Set(['fail', 'warn', 'skip']);
+
+/**
+ * Map a check module's `onError` field to the verdict produced when
+ * the check itself throws. Falls back to 'fail' for safety.
+ *
+ * @param {Object} checkModule
+ * @returns {'fail' | 'warn' | 'skip'}
+ */
+function resolveOnError(checkModule) {
+  const declared = checkModule && checkModule.onError;
+  if (declared && VALID_ON_ERROR.has(declared)) {
+    return declared;
+  }
+  return 'fail';
+}
+
+/**
+ * Build a structured result entry for a thrown exception, based on
+ * the check's declared error policy. Returns null if the policy is
+ * 'skip' (excluded from results).
+ *
+ * @param {Object} checkModule
+ * @param {Error} error
+ * @returns {Object|null}
+ */
+function buildErrorResult(checkModule, error) {
+  const policy = resolveOnError(checkModule);
+  if (policy === 'skip') {
+    return null;
+  }
+  return {
+    check: checkModule.name || 'unknown',
+    status: policy === 'warn' ? 'WARN' : 'FAIL',
+    message: `Check threw error: ${error.message}`,
+    fixCommand: null,
+  };
+}
 
 /**
  * Run all doctor checks
@@ -26,7 +76,7 @@ const DOCTOR_VERSION = '2.0.0';
  * @param {boolean} [options.dryRun=false] - Show what --fix would do
  * @param {boolean} [options.quiet=false] - Minimal output
  * @param {string} [options.projectRoot] - Project root (defaults to cwd)
- * @returns {Promise<Object>} Doctor results
+ * @returns {Promise<Object>} Doctor results (includes `internalError` when the runner itself crashes)
  */
 async function runDoctorChecks(options = {}) {
   const {
@@ -38,58 +88,115 @@ async function runDoctorChecks(options = {}) {
     projectRoot = process.cwd(),
   } = options;
 
-  const context = {
-    projectRoot,
-    frameworkRoot: path.resolve(__dirname, '..', '..', '..'),
-    options: { fix, json, dryRun, quiet, deep },
-  };
+  try {
+    const context = {
+      projectRoot,
+      frameworkRoot: path.resolve(__dirname, '..', '..', '..'),
+      options: { fix, json, dryRun, quiet, deep },
+    };
+
+    // Load and run all checks (deep checks only with --deep flag)
+    const checks = loadChecks({ deep });
+    const results = [];
 
-  // Load and run all checks (deep checks only with --deep flag)
-  const checks = loadChecks({ deep });
-  const results = [];
-
-  for (const checkModule of checks) {
-    try {
-      const result = await checkModule.run(context);
-      results.push(result);
-    } catch (error) {
-      results.push({
-        check: checkModule.name || 'unknown',
-        status: 'FAIL',
-        message: `Check threw error: ${error.message}`,
-        fixCommand: null,
-      });
+    for (const checkModule of checks) {
+      try {
+        const result = await checkModule.run(context);
+        results.push(result);
+      } catch (error) {
+        const errorResult = buildErrorResult(checkModule, error);
+        if (errorResult !== null) {
+          results.push(errorResult);
+        }
+        // policy === 'skip' → silently exclude
+      }
     }
-  }
 
-  // Apply fixes if requested
-  let fixResults = null;
-  if (fix || dryRun) {
-    fixResults = await applyFixes(results, context);
-  }
+    // Apply fixes if requested
+    let fixResults = null;
+    if (fix || dryRun) {
+      fixResults = await applyFixes(results, context);
+    }
 
-  // Build summary
-  const summary = {
-    pass: results.filter((r) => r.status === 'PASS').length,
-    warn: results.filter((r) => r.status === 'WARN').length,
-    fail: results.filter((r) => r.status === 'FAIL').length,
-    info: results.filter((r) => r.status === 'INFO').length,
-  };
+    // Build summary
+    const summary = {
+      pass: results.filter((r) => r.status === 'PASS').length,
+      warn: results.filter((r) => r.status === 'WARN').length,
+      fail: results.filter((r) => r.status === 'FAIL').length,
+      info: results.filter((r) => r.status === 'INFO').length,
+    };
 
-  const output = {
-    version: DOCTOR_VERSION,
-    timestamp: new Date().toISOString(),
-    summary,
-    checks: results,
-    fixResults,
-  };
+    const output = {
+      version: DOCTOR_VERSION,
+      timestamp: new Date().toISOString(),
+      summary,
+      checks: results,
+      fixResults,
+      internalError: null,
+    };
+
+    // Format output
+    if (json) {
+      return { formatted: formatJson(output), data: output };
+    }
+
+    return { formatted: formatText(output, { quiet }), data: output };
+  } catch (runnerError) {
+    // Runner itself crashed (not a check throwing). Surface as exit code 3.
+    const summary = { pass: 0, warn: 0, fail: 0, info: 0 };
+    const errorPayload = {
+      message: runnerError.message,
+      stack: runnerError.stack,
+    };
+    const output = {
+      version: DOCTOR_VERSION,
+      timestamp: new Date().toISOString(),
+      summary,
+      checks: [],
+      fixResults: null,
+      internalError: errorPayload,
+    };
+
+    const formatted = json
+      ? formatJson(output)
+      : `SINAPSE Doctor v${DOCTOR_VERSION} — internal error: ${runnerError.message}`;
 
-  // Format output
-  if (json) {
-    return { formatted: formatJson(output), data: output };
+    return { formatted, data: output };
   }
+}
 
-  return { formatted: formatText(output, { quiet }), data: output };
+/**
+ * Resolve a doctor result object into a canonical exit code.
+ *
+ * Story A.3 exit code mapping:
+ *   0 — PASS (no FAILs, no WARNs)
+ *   1 — WARN only (no FAILs)
+ *   2 — at least one FAIL
+ *   3 — internal runner error (runDoctorChecks itself crashed)
+ *
+ * @param {Object} result - Return value from runDoctorChecks()
+ * @returns {0 | 1 | 2 | 3}
+ */
+function resolveExitCode(result) {
+  if (!result || !result.data) {
+    return 3;
+  }
+  if (result.data.internalError) {
+    return 3;
+  }
+  const summary = result.data.summary || {};
+  if ((summary.fail || 0) > 0) {
+    return 2;
+  }
+  if ((summary.warn || 0) > 0) {
+    return 1;
+  }
+  return 0;
 }
 
-module.exports = { runDoctorChecks, DOCTOR_VERSION };
+module.exports = {
+  runDoctorChecks,
+  resolveExitCode,
+  resolveOnError,
+  DOCTOR_VERSION,
+};

package/.sinapse-ai/core/ids/registry-updater.js

@@ -483,10 +483,15 @@ class RegistryUpdater {
   }
 
   _writeRegistry(registryData) {
+    // Story 10.24 — sortKeys: true makes the YAML output deterministic.
+    // Without it, key order follows JS object insertion order, which means
+    // semantically-identical writes can produce textually-different files
+    // and cause endless `M entity-registry.yaml` churn in `git status`.
+    // The registry is machine-managed so alphabetical key order is fine.
     const yamlStr = yaml.dump(registryData, {
       lineWidth: 120,
       noRefs: true,
-      sortKeys: false,
+      sortKeys: true,
     });
 
     const dir = path.dirname(this._registryPath);

package/.sinapse-ai/core/logger/index.js

@@ -0,0 +1,319 @@
+'use strict';
+
+/**
+ * SINAPSE Logger — unified logging abstraction
+ * @story A.2 - Logger & Verbose Flag Refactor
+ *
+ * Levels:
+ *   error = 0  (always shown, except nothing is shown in --json mode until flush)
+ *   warn  = 1  (default floor — shown unless --quiet)
+ *   info  = 2  (shown on --verbose)
+ *   debug = 3  (shown on --debug)
+ *
+ * Flag resolution priority (highest wins):
+ *   --quiet > --debug > --verbose > default(warn)
+ *
+ * Extra modes:
+ *   --json  Structured output: all human text is suppressed; logger accumulates a
+ *           JSON summary which is flushed at process exit (flush() also callable).
+ *
+ * First-run detection:
+ *   ASCII art header is gated by level (info+) OR the absence of
+ *   ~/.sinapse/.first-run-done. The first run creates this flag file.
+ *
+ * Design constraints (from story Dev Notes):
+ *   - Zero external deps (pure Node stdlib).
+ *   - Safe on repeated require() from bin/cli.js and bin/sinapse.js in same process.
+ *   - Tests can call createLogger({ level, json }) to build isolated instances.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const LEVELS = Object.freeze({
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+});
+
+const LEVEL_NAMES = Object.freeze(['error', 'warn', 'info', 'debug']);
+
+const DEFAULT_LEVEL = 'warn';
+
+const SINAPSE_HOME = path.join(os.homedir(), '.sinapse');
+const FIRST_RUN_FLAG = path.join(SINAPSE_HOME, '.first-run-done');
+
+/**
+ * Resolve level from parsed flags. Higher verbosity wins unless --quiet is set.
+ * --quiet beats everything else (error only).
+ * @param {{ quiet?: boolean, debug?: boolean, verbose?: boolean }} flags
+ * @returns {'error'|'warn'|'info'|'debug'}
+ */
+function resolveLevel(flags = {}) {
+  if (flags.quiet) return 'error';
+  if (flags.debug) return 'debug';
+  if (flags.verbose) return 'info';
+  return DEFAULT_LEVEL;
+}
+
+/**
+ * Parse verbosity/output flags from an argv-like array (process.argv.slice(2)).
+ * Non-destructive — returns a plain object, does not mutate the input.
+ * @param {string[]} argv
+ */
+function parseFlags(argv) {
+  const a = Array.isArray(argv) ? argv : [];
+  const has = (name) => a.includes(name);
+  return {
+    quiet: has('--quiet') || has('-q'),
+    verbose: has('--verbose') || has('-v'),
+    debug: has('--debug'),
+    json: has('--json'),
+  };
+}
+
+/**
+ * Detect whether this is a first run. True when the flag file does NOT exist.
+ * Any filesystem error is treated as "not first run" to avoid breaking headless
+ * environments (safer default: stay quiet).
+ */
+function isFirstRun() {
+  try {
+    return !fs.existsSync(FIRST_RUN_FLAG);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark first run as done by touching the flag file. Idempotent and failure-tolerant.
+ */
+function markFirstRunDone() {
+  try {
+    if (!fs.existsSync(SINAPSE_HOME)) {
+      fs.mkdirSync(SINAPSE_HOME, { recursive: true });
+    }
+    if (!fs.existsSync(FIRST_RUN_FLAG)) {
+      fs.writeFileSync(FIRST_RUN_FLAG, `${new Date().toISOString()}\n`, 'utf8');
+    }
+  } catch {
+    /* non-fatal — first-run detection will just keep asking */
+  }
+}
+
+/**
+ * Build a logger instance.
+ * @param {object} [opts]
+ * @param {'error'|'warn'|'info'|'debug'} [opts.level]  explicit level (overrides flags)
+ * @param {boolean} [opts.json]                         json mode
+ * @param {NodeJS.WritableStream} [opts.stdout]         stdout sink (testable)
+ * @param {NodeJS.WritableStream} [opts.stderr]         stderr sink (testable)
+ */
+function createLogger(opts = {}) {
+  const level = opts.level && LEVELS[opts.level] !== undefined ? opts.level : DEFAULT_LEVEL;
+  const threshold = LEVELS[level];
+  const json = Boolean(opts.json);
+  const stdout = opts.stdout || process.stdout;
+  const stderr = opts.stderr || process.stderr;
+
+  // JSON-mode accumulator. Flushed as a single JSON object on flush() or process exit.
+  const jsonState = {
+    status: 'ok',
+    version: null,
+    agents: [],
+    warnings: [],
+    errors: [],
+    messages: [],
+  };
+
+  function emit(channel, lvl, args) {
+    if (json) {
+      const text = args
+        .map((a) => (a instanceof Error ? a.stack || a.message : typeof a === 'object' ? safeStringify(a) : String(a)))
+        .join(' ');
+      if (lvl === 'error') jsonState.errors.push(text);
+      else if (lvl === 'warn') jsonState.warnings.push(text);
+      else jsonState.messages.push({ level: lvl, text });
+      if (lvl === 'error') jsonState.status = 'error';
+      else if (lvl === 'warn' && jsonState.status === 'ok') jsonState.status = 'warn';
+      return;
+    }
+    const stream = channel === 'stderr' ? stderr : stdout;
+    try {
+      stream.write(`${formatArgs(args)}\n`);
+    } catch {
+      /* broken pipe / closed stream — swallow */
+    }
+  }
+
+  function formatArgs(args) {
+    return args
+      .map((a) => {
+        if (a instanceof Error) return a.stack || a.message;
+        if (typeof a === 'object' && a !== null) return safeStringify(a);
+        return String(a);
+      })
+      .join(' ');
+  }
+
+  const api = {
+    level,
+    threshold,
+    json,
+
+    isEnabled(lvl) {
+      return LEVELS[lvl] !== undefined && LEVELS[lvl] <= threshold;
+    },
+
+    error(...args) {
+      // error is always captured (level 0)
+      emit('stderr', 'error', args);
+    },
+
+    warn(...args) {
+      if (threshold >= LEVELS.warn) emit('stderr', 'warn', args);
+    },
+
+    info(...args) {
+      if (threshold >= LEVELS.info) emit('stdout', 'info', args);
+    },
+
+    debug(...args) {
+      if (threshold >= LEVELS.debug) emit('stdout', 'debug', args);
+    },
+
+    /**
+     * Write raw text to stdout at info-or-higher. Used by commands that need
+     * to render tables / long output that should NOT appear on default runs.
+     */
+    print(...args) {
+      if (json) {
+        jsonState.messages.push({ level: 'info', text: formatArgs(args) });
+        return;
+      }
+      if (threshold >= LEVELS.info) {
+        try {
+          stdout.write(`${formatArgs(args)}\n`);
+        } catch { /* ignore */ }
+      }
+    },
+
+    /**
+     * Always-on stdout write. For output that MUST appear at default level
+     * (e.g. one-line status: "SINAPSE ready."). Respects --json and --quiet.
+     * --quiet: suppressed unless this is a direct error.
+     */
+    always(...args) {
+      if (json) {
+        jsonState.messages.push({ level: 'always', text: formatArgs(args) });
+        return;
+      }
+      if (threshold === LEVELS.error) return; // --quiet
+      try {
+        stdout.write(`${formatArgs(args)}\n`);
+      } catch { /* ignore */ }
+    },
+
+    /**
+     * Set the package version on the JSON state. Harmless in non-json mode.
+     */
+    setVersion(version) {
+      jsonState.version = version;
+    },
+
+    /**
+     * Push an agent entry into the JSON state. Harmless in non-json mode.
+     */
+    addAgent(name, meta = {}) {
+      jsonState.agents.push({ name, ...meta });
+    },
+
+    /**
+     * Flush the JSON state to stdout as a single structured object.
+     * Safe to call multiple times — no-op after the first call.
+     */
+    flush() {
+      if (!json || api._flushed) return;
+      api._flushed = true;
+      try {
+        stdout.write(`${JSON.stringify(jsonState)}\n`);
+      } catch { /* ignore */ }
+    },
+
+    _jsonState: jsonState,
+    _flushed: false,
+  };
+
+  return api;
+}
+
+/**
+ * Build the process-wide logger from process.argv. Cached: repeated calls return
+ * the same instance so `bin/cli.js` and `bin/sinapse.js` share state in a single run.
+ */
+let _singleton = null;
+
+function getLogger(argvOverride) {
+  if (_singleton) return _singleton;
+  const argv = argvOverride || process.argv.slice(2);
+  const flags = parseFlags(argv);
+  _singleton = createLogger({
+    level: resolveLevel(flags),
+    json: flags.json,
+  });
+  _singleton._flags = flags;
+
+  // Ensure JSON state is flushed on process exit so --json is reliable.
+  if (flags.json) {
+    const flush = () => { try { _singleton.flush(); } catch { /* noop */ } };
+    process.on('exit', flush);
+    process.on('beforeExit', flush);
+  }
+  return _singleton;
+}
+
+/** Reset the singleton (tests only). */
+function _resetLogger() {
+  _singleton = null;
+}
+
+/**
+ * Decide whether the ASCII art header should be shown.
+ *
+ *   show if: level >= info  (i.e. --verbose or --debug)
+ *   OR       first run (no flag file)
+ *
+ *   never show in --json mode or --quiet mode.
+ */
+function shouldShowHeader(logger) {
+  if (!logger) return false;
+  if (logger.json) return false;
+  if (logger.threshold === LEVELS.error) return false; // --quiet
+  if (logger.threshold >= LEVELS.info) return true;    // --verbose / --debug
+  return isFirstRun();
+}
+
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '[unserializable]';
+  }
+}
+
+module.exports = {
+  LEVELS,
+  LEVEL_NAMES,
+  DEFAULT_LEVEL,
+  FIRST_RUN_FLAG,
+  createLogger,
+  getLogger,
+  parseFlags,
+  resolveLevel,
+  isFirstRun,
+  markFirstRunDone,
+  shouldShowHeader,
+  _resetLogger,
+};

package/.sinapse-ai/core/orchestration/terminal-spawner.js

@@ -12,7 +12,7 @@
 
 'use strict';
 
-const { spawn, execSync } = require('child_process');
+const { spawn, execSync, execFileSync } = require('child_process');
 const fs = require('fs').promises;
 const fsSync = require('fs');
 const path = require('path');
@@ -554,7 +554,7 @@ async function spawnAgent(agent, task, options = {}) {
         SINAPSE_OUTPUT_DIR: opts.outputDir,
       };
 
-      const result = execSync(`bash "${scriptPath}" ${args.join(' ')}`, {
+      const result = execFileSync('bash', [scriptPath, ...args], {
         encoding: 'utf8',
         timeout: opts.timeout,
         env,