sinapse-ai 9.3.0 → 9.5.0

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,

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

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * SINAPSE Telemetry — STUB (opt-in, disabled by default)
+ * @story C.1 — Exit Codes, Auto-Doctor & Opt-in Telemetry
+ *
+ * IMPORTANT (contributors):
+ *   This is a STUB implementation. It does NOT make real network requests.
+ *   Calling `send(event)` when telemetry is enabled logs the payload at debug
+ *   level and stops there.
+ *
+ *   TODO(follow-up-story): wire a real HTTPS endpoint once the privacy policy
+ *   at docs/TELEMETRY.md has been reviewed by legal and the endpoint URL is
+ *   confirmed. Until then, NO real data leaves the user's machine.
+ *
+ * Contract (see Story C.1 ACs):
+ *   AC 4 — Exported methods: enable(), disable(), isEnabled(), send(event).
+ *   AC 5 — Disabled by default. `send()` is a no-op when disabled.
+ *   AC 6 — `enable()` persists a flag to ~/.sinapse/config.json. CLI wrapper
+ *          shows the confirmation message to the user.
+ *   AC 7 — `SINAPSE_TELEMETRY=1` env var overrides the config file.
+ *   AC 8 — Payload is anonymized: only { category, platform, version, timestamp }.
+ *          NO user paths, NO usernames, NO file names, NO PII.
+ *   AC 9 — send() logs at debug level only. No HTTP.
+ *
+ * Zero external deps (pure Node stdlib). Safe to require() anywhere.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// ─── Config file location ────────────────────────────────────────────────────
+// Stored under ~/.sinapse/config.json so it is per-user (not per-project) and
+// does not pollute the project directory.
+
+function sinapseHome() {
+  return path.join(os.homedir(), '.sinapse');
+}
+
+function configPath() {
+  return path.join(sinapseHome(), 'config.json');
+}
+
+// ─── Predefined failure categories (AC 8) ────────────────────────────────────
+// Adding a new category? Add it here AND in docs/TELEMETRY.md so the privacy
+// policy stays in sync with the code.
+
+const FAILURE_CATEGORIES = Object.freeze([
+  'doctor-fail',
+  'sync-ide-fail',
+  'permission-error',
+  'runtime-dir-fail',
+  'unknown',
+]);
+
+// ─── Allowed platforms (AC 8) ────────────────────────────────────────────────
+
+const ALLOWED_PLATFORMS = Object.freeze(['win32', 'darwin', 'linux']);
+
+/**
+ * Normalize process.platform to one of the allowed values. Any exotic platform
+ * (aix, freebsd, openbsd, sunos, ...) is coerced to 'linux' to avoid leaking a
+ * fingerprint. NEVER returns the raw platform string.
+ * @returns {'win32'|'darwin'|'linux'}
+ */
+function normalizePlatform() {
+  const p = process.platform;
+  if (p === 'win32' || p === 'darwin' || p === 'linux') return p;
+  return 'linux';
+}
+
+// ─── Version reading ─────────────────────────────────────────────────────────
+
+let _cachedVersion = null;
+function readVersion() {
+  if (_cachedVersion) return _cachedVersion;
+  try {
+    const pkg = require(path.resolve(__dirname, '..', '..', '..', 'package.json'));
+    _cachedVersion = pkg && pkg.version ? String(pkg.version) : 'unknown';
+  } catch {
+    _cachedVersion = 'unknown';
+  }
+  return _cachedVersion;
+}
+
+// ─── Config file read / write ────────────────────────────────────────────────
+// All filesystem calls are fail-safe: a corrupt or missing config.json MUST
+// NEVER crash the caller. Telemetry is best-effort.
+
+function readConfig() {
+  try {
+    const p = configPath();
+    if (!fs.existsSync(p)) return {};
+    const raw = fs.readFileSync(p, 'utf8');
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(cfg) {
+  try {
+    const home = sinapseHome();
+    if (!fs.existsSync(home)) {
+      fs.mkdirSync(home, { recursive: true });
+    }
+    fs.writeFileSync(configPath(), `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * AC 5 + AC 7 — Is telemetry currently enabled?
+ *
+ * Resolution order (highest priority first):
+ *   1. SINAPSE_TELEMETRY=1 env var → TRUE (overrides config file)
+ *   2. SINAPSE_TELEMETRY=0 env var → FALSE (explicit opt-out wins too)
+ *   3. ~/.sinapse/config.json { "telemetry": true|false }
+ *   4. Default → FALSE
+ *
+ * @returns {boolean}
+ */
+function isEnabled() {
+  const envVar = process.env.SINAPSE_TELEMETRY;
+  if (envVar === '1' || envVar === 'true') return true;
+  if (envVar === '0' || envVar === 'false') return false;
+  const cfg = readConfig();
+  return cfg.telemetry === true;
+}
+
+/**
+ * AC 6 — Persist opt-in to config file. Returns true on success.
+ * Does NOT print any message (CLI layer owns the user-facing copy).
+ * @returns {boolean}
+ */
+function enable() {
+  const cfg = readConfig();
+  cfg.telemetry = true;
+  return writeConfig(cfg);
+}
+
+/**
+ * Persist opt-out to config file. Returns true on success.
+ * @returns {boolean}
+ */
+function disable() {
+  const cfg = readConfig();
+  cfg.telemetry = false;
+  return writeConfig(cfg);
+}
+
+/**
+ * AC 8 — Build an anonymized payload from a category.
+ * Only { category, platform, version, timestamp } is included.
+ * Unknown categories are coerced to 'unknown' to prevent category-sprawl and
+ * to keep the schema predictable for the (future) real endpoint.
+ *
+ * @param {string} category
+ * @returns {{category:string,platform:'win32'|'darwin'|'linux',version:string,timestamp:string}}
+ */
+function buildPayload(category) {
+  const safeCategory = FAILURE_CATEGORIES.includes(category) ? category : 'unknown';
+  return {
+    category: safeCategory,
+    platform: normalizePlatform(),
+    version: readVersion(),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/**
+ * AC 5 + AC 9 — Send a telemetry event.
+ *
+ * When disabled → no-op (no network call, no log).
+ * When enabled  → build anonymized payload, log at debug level, and return it.
+ *
+ * NOTE: This stub does NOT make any HTTP request. A follow-up story will add
+ * the real endpoint after legal review of docs/TELEMETRY.md.
+ *
+ * @param {{category?: string}} event
+ * @param {{logger?: object}} [opts] — inject a logger for tests; defaults to
+ *   the shared SINAPSE logger if available, otherwise console.
+ * @returns {null|object} the payload that would have been sent, or null if disabled
+ */
+function send(event = {}, opts = {}) {
+  if (!isEnabled()) return null;
+  const payload = buildPayload(event && event.category);
+  const logger = opts.logger || _getDefaultLogger();
+  try {
+    if (logger && typeof logger.debug === 'function') {
+      logger.debug('[telemetry stub]', JSON.stringify(payload));
+    }
+  } catch {
+    /* never throw from telemetry */
+  }
+  // TODO(follow-up-story): POST payload to real endpoint here.
+  return payload;
+}
+
+// ─── Default logger resolution ──────────────────────────────────────────────
+// Try the shared SINAPSE logger first (so telemetry respects --debug/--quiet),
+// but fall back to a console shim if it's unavailable (e.g. during very early
+// bootstrap or in isolated tests).
+
+let _defaultLogger = null;
+function _getDefaultLogger() {
+  if (_defaultLogger) return _defaultLogger;
+  try {
+    const { getLogger } = require('../logger');
+    _defaultLogger = getLogger();
+  } catch {
+    _defaultLogger = {
+      debug: (...args) => { try { console.debug(...args); } catch { /* ignore */ } },
+    };
+  }
+  return _defaultLogger;
+}
+
+// Test helper — reset internal caches between tests. Not part of the public
+// contract; do not use in production code.
+function _reset() {
+  _cachedVersion = null;
+  _defaultLogger = null;
+}
+
+module.exports = {
+  // Public API (AC 4)
+  enable,
+  disable,
+  isEnabled,
+  send,
+  // Helpers exposed for tests + CLI command
+  buildPayload,
+  normalizePlatform,
+  readVersion,
+  configPath,
+  sinapseHome,
+  FAILURE_CATEGORIES,
+  ALLOWED_PLATFORMS,
+  _reset,
+};