sinapse-ai 1.6.1 → 1.8.0

package/.sinapse-ai/product/templates/engine/renderer.js

@@ -205,6 +205,23 @@ class TemplateRenderer {
     this.customHelpers = new Map();
     registerDefaultHelpers(this.handlebars);
 
+    // HTML-escape policy for compiled templates.
+    //
+    // Default is `noEscape: true` (HTML escaping OFF) BY DESIGN. This renderer
+    // produces Markdown / plain-text documents (ADR, PRD, story, epic, task —
+    // see SUPPORTED_TYPES in index.js, all saved as `.md` under docs/). Markdown
+    // legitimately contains raw `<`, `>`, `&`, quotes (headings, tables,
+    // comparison operators, code blocks, HTML-in-markdown). Turning escaping ON
+    // would corrupt that output (`&` -> `&amp;`, `<` -> `&lt;`), so it stays OFF.
+    //
+    // SECURITY CONTRACT: this renderer must ONLY receive TRUSTED context
+    // (framework-elicited template variables) and its output is consumed as
+    // Markdown/CLI/docs — NEVER served as HTML to a browser. If you ever reuse
+    // this engine to emit HTML for a web response, construct it with
+    // `{ noEscape: false }` so Handlebars escapes interpolated values and
+    // mitigates XSS. Do not feed untrusted user input through the trusted path.
+    this.noEscape = options.noEscape !== false;
+
     // Register any custom helpers from options
     if (options.helpers) {
       for (const [name, fn] of Object.entries(options.helpers)) {
@@ -242,9 +259,11 @@ class TemplateRenderer {
     const templateBody = typeof template === 'string' ? template : template.body;
 
     try {
+      // noEscape default = true (Markdown/docs output, trusted context). See the
+      // SECURITY CONTRACT note in the constructor before changing this.
       const compiledTemplate = this.handlebars.compile(templateBody, {
         strict: false,
-        noEscape: true,
+        noEscape: this.noEscape,
       });
 
       // Add metadata to context if available

package/.sinapse-ai/scripts/pm.sh

@@ -381,24 +381,36 @@ spawn_terminal() {
   # Add agent activation
   agent_cmd="${agent_cmd} --print-only"  # Just for testing, real impl would use actual claude flags
 
+  # SECURITY (SHELL-INJECTION-PM-SH): AGENT/TASK/PARAMS/CONTEXT_FILE come from
+  # CLI args and are interpolated into a command string run by a shell in the
+  # spawned terminal. Escape every interpolated value with `printf %q` so shell
+  # metacharacters (`;`, `$()`, backticks, quotes) cannot break out and execute.
+  local q_agent q_task q_params q_context q_output q_lock
+  printf -v q_agent '%q' "$AGENT"
+  printf -v q_task '%q' "$TASK"
+  printf -v q_params '%q' "$PARAMS"
+  printf -v q_context '%q' "$CONTEXT_FILE"
+  printf -v q_output '%q' "$OUTPUT_FILE"
+  printf -v q_lock '%q' "$LOCK_FILE"
+
   # For now, we'll create a simpler command that demonstrates the concept
   # The actual claude CLI integration will depend on how claude accepts agent/task args
   local full_cmd="echo '=== SINAPSE Agent Session ===' && "
-  full_cmd+="echo 'Agent: ${AGENT}' && "
-  full_cmd+="echo 'Task: ${TASK}' && "
-  [[ -n "$PARAMS" ]] && full_cmd+="echo 'Params: ${PARAMS}' && "
-  [[ -n "$CONTEXT_FILE" ]] && full_cmd+="echo 'Context: ${CONTEXT_FILE}' && "
+  full_cmd+="echo Agent: ${q_agent} && "
+  full_cmd+="echo Task: ${q_task} && "
+  [[ -n "$PARAMS" ]] && full_cmd+="echo Params: ${q_params} && "
+  [[ -n "$CONTEXT_FILE" ]] && full_cmd+="echo Context: ${q_context} && "
   full_cmd+="echo '' && "
 
   # Actual execution would be something like:
   # full_cmd+="${CLAUDE_CMD} @${AGENT} *${TASK} ${PARAMS}"
   # For now, simulate the output
-  full_cmd+="echo 'Executing: @${AGENT} *${TASK} ${PARAMS}' && "
+  full_cmd+="echo Executing: @${q_agent} '*'${q_task} ${q_params} && "
   full_cmd+="echo 'Agent execution would happen here...' && "
   full_cmd+="echo '=== Session Complete ===' "
 
   # Redirect output to file and remove lock when done
-  full_cmd+=" > '${OUTPUT_FILE}' 2>&1; rm -f '${LOCK_FILE}'"
+  full_cmd+=" > ${q_output} 2>&1; rm -f ${q_lock}"
 
   # Spawn based on OS
   case "$os" in

package/bin/cli.js

@@ -26,6 +26,8 @@ const KNOWN_COMMANDS = [
   'list',
   'status',
   'doctor',
+  'ideate',
+  'agents',
   'chrome-brain',
   'help',
 ];
@@ -134,6 +136,21 @@ function runRouter() {
     // eslint-disable-next-line no-fallthrough -- process.exit above terminates; Story 10.45 piggyback fix.
     case 'list':     cmdList(); break;
     case 'status':   cmdStatus(); break;
+    case 'ideate': {
+      // Wires the IdeationEngine (self-improvement analyzers) into the CLI.
+      const { cmdIdeate } = require('./commands/ideate');
+      cmdIdeate({ argv: args.slice(1) })
+        .then((code) => { if (code) process.exitCode = code; })
+        .catch((e) => { logger.error(`${RED}Erro no ideate:${NC} ${e.message}`); process.exit(1); });
+      break;
+    }
+    case 'agents': {
+      // Lists the full agent roster with uniform derived metadata (SCHEMA-001).
+      const { cmdAgents } = require('./commands/agents');
+      try { process.exitCode = cmdAgents({ argv: args.slice(1) }) || 0; }
+      catch (e) { logger.error(`${RED}Erro no agents:${NC} ${e.message}`); process.exit(1); }
+      break;
+    }
     case 'doctor': {
       // Story 10.21 — wires the modular doctor into the canonical CLI
       const doctorArgs = args.slice(1);

package/bin/commands/agents.js

@@ -0,0 +1,96 @@
+// bin/commands/agents.js — `sinapse agents` command.
+//
+// Lists the full agent roster with uniform, derived metadata (id, name, squad,
+// type) via SquadAgentResolver.list(). This is the consumer that makes the
+// unified agent schema (SCHEMA-001) useful: one place to discover every agent
+// regardless of how its source file is structured.
+
+'use strict';
+
+const { getLogger } = require('../../.sinapse-ai/core/logger');
+const { CYAN, GREEN, YELLOW, BOLD, DIM, RED, NC } = require('../lib/constants');
+
+/**
+ * Parse `agents` CLI args.
+ * @param {string[]} argv
+ * @returns {{help:boolean, json:boolean, squad:string|undefined, type:string|undefined}}
+ */
+function parseAgentsArgs(argv = []) {
+  const o = { help: false, json: false, squad: undefined, type: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--json') o.json = true;
+    else if (a === '--squad') { o.squad = argv[++i]; }
+    else if (a.startsWith('--squad=')) o.squad = a.slice('--squad='.length);
+    else if (a === '--type') { o.type = argv[++i]; }
+    else if (a.startsWith('--type=')) o.type = a.slice('--type='.length);
+  }
+  return o;
+}
+
+function printHelp(logger) {
+  logger.always(`${BOLD}sinapse agents${NC} — lista os agentes do framework\n`);
+  logger.always(`${BOLD}Uso:${NC}`);
+  logger.always(`  ${CYAN}sinapse agents${NC}                    todos os agentes, agrupados por squad`);
+  logger.always(`  ${CYAN}sinapse agents --squad squad-copy${NC} só de um squad`);
+  logger.always(`  ${CYAN}sinapse agents --type orchestrator${NC} só orquestradores`);
+  logger.always(`  ${CYAN}sinapse agents --json${NC}             saída JSON (pra tooling)`);
+}
+
+/**
+ * Run the agents listing.
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv]
+ * @returns {number} exit code
+ */
+function cmdAgents(opts = {}) {
+  const logger = getLogger();
+  const parsed = parseAgentsArgs(opts.argv || []);
+  if (parsed.help) {
+    printHelp(logger);
+    return 0;
+  }
+
+  let SquadAgentResolver;
+  try {
+    SquadAgentResolver = require('../../.sinapse-ai/core/registry/squad-agent-resolver');
+  } catch (e) {
+    logger.error(`${RED}Resolver de agentes indisponível:${NC} ${e.message}`);
+    return 1;
+  }
+
+  const resolver = new SquadAgentResolver(process.cwd());
+  let agents = resolver.list();
+
+  if (parsed.squad) agents = agents.filter((a) => a.squad === parsed.squad);
+  if (parsed.type) agents = agents.filter((a) => a.type === parsed.type);
+
+  if (parsed.json) {
+    logger.always(JSON.stringify(agents, null, 2));
+    return 0;
+  }
+
+  if (agents.length === 0) {
+    logger.always(`${YELLOW}Nenhum agente encontrado com esse filtro.${NC}`);
+    return 0;
+  }
+
+  // Group by squad for a scannable view.
+  const bySquad = {};
+  for (const a of agents) (bySquad[a.squad] ||= []).push(a);
+  const squads = Object.keys(bySquad).sort();
+
+  logger.always(`${BOLD}${agents.length} agentes${NC} em ${squads.length} grupos\n`);
+  for (const squad of squads) {
+    logger.always(`${CYAN}${squad}${NC} ${DIM}(${bySquad[squad].length})${NC}`);
+    for (const a of bySquad[squad].sort((x, y) => x.id.localeCompare(y.id))) {
+      const tag = a.type === 'orchestrator' ? `${GREEN}◆${NC}` : `${DIM}·${NC}`;
+      logger.always(`  ${tag} ${a.id} ${DIM}— ${a.name}${NC}`);
+    }
+    logger.always('');
+  }
+  return 0;
+}
+
+module.exports = { cmdAgents, parseAgentsArgs };

package/bin/commands/doctor.js

@@ -48,6 +48,21 @@ Exit codes (Story A.3):
     logger.always(result.formatted);
   }
 
+  // --deep also surfaces the SYNAPSE context-engine diagnostics, which until now
+  // were only reachable via the diagnose-synapse skill (not the public CLI).
+  // Defensive: the collectors already degrade gracefully, but guard the require
+  // so a missing module never breaks `doctor`.
+  if (opts.deep) {
+    try {
+      const {
+        runDiagnostics,
+      } = require('../../.sinapse-ai/core/synapse/diagnostics/synapse-diagnostics');
+      logger.always('\n' + runDiagnostics(process.cwd()));
+    } catch (err) {
+      logger.always(`\n(SYNAPSE diagnostics unavailable: ${err.message})`);
+    }
+  }
+
   // Story A.3 — precise exit code mapping:
   //   0 PASS | 1 WARN only | 2 FAIL | 3 internal runner error
   // Fall back to resolveExitCode when available (module may be mocked in tests

package/bin/commands/ideate.js

@@ -0,0 +1,129 @@
+// bin/commands/ideate.js — `sinapse ideate` command.
+//
+// Wires the IdeationEngine (.sinapse-ai/core/ideation) into the CLI so the
+// framework's self-improvement analyzers (performance, security, code quality,
+// UX, architecture) are actually reachable. Before this, the engine had zero
+// consumers (VAPORWARE-1, audit 2026-06-11). Per "potentiate, don't cut", the
+// fix is a real entry point, not deletion.
+
+'use strict';
+
+const path = require('path');
+const { getLogger } = require('../../.sinapse-ai/core/logger');
+const { CYAN, GREEN, YELLOW, RED, BOLD, NC } = require('../lib/constants');
+
+const VALID_AREAS = ['performance', 'security', 'codeQuality', 'ux', 'architecture'];
+
+/**
+ * Parse `ideate` CLI args into options.
+ * @param {string[]} argv - args after the `ideate` token
+ * @returns {{ help: boolean, json: boolean, save: boolean, focus: string[]|undefined }}
+ */
+function parseIdeateArgs(argv = []) {
+  const opts = { help: false, json: false, save: true, focus: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--no-save') opts.save = false;
+    else if (a === '--focus' || a === '-f') {
+      const val = argv[i + 1];
+      if (val && !val.startsWith('-')) {
+        opts.focus = val.split(',').map((s) => s.trim()).filter(Boolean);
+        i++;
+      }
+    } else if (a.startsWith('--focus=')) {
+      opts.focus = a.slice('--focus='.length).split(',').map((s) => s.trim()).filter(Boolean);
+    }
+  }
+  return opts;
+}
+
+/** Print usage. */
+function printHelp(logger) {
+  logger.always(`${BOLD}sinapse ideate${NC} — análise de melhorias do projeto\n`);
+  logger.always('Analisa o código e sugere melhorias priorizadas (quick wins primeiro)');
+  logger.always('nas áreas: performance, security, codeQuality, ux, architecture.\n');
+  logger.always(`${BOLD}Uso:${NC}`);
+  logger.always(`  ${CYAN}sinapse ideate${NC}                      analisa todas as áreas`);
+  logger.always(`  ${CYAN}sinapse ideate --focus security${NC}     só uma área (ou lista: perf,security)`);
+  logger.always(`  ${CYAN}sinapse ideate --no-save${NC}            não grava o relatório em disco`);
+  logger.always(`  ${CYAN}sinapse ideate --json${NC}               saída JSON (pra pipelines)\n`);
+  logger.always(`Relatório salvo em ${CYAN}.sinapse/ideation/${NC} (suggestions.json + .md).`);
+}
+
+/**
+ * Run the ideation analysis and present results.
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv] - raw args after `ideate`
+ * @returns {Promise<number>} exit code
+ */
+async function cmdIdeate(opts = {}) {
+  const logger = getLogger();
+  const parsed = parseIdeateArgs(opts.argv || []);
+
+  if (parsed.help) {
+    printHelp(logger);
+    return 0;
+  }
+
+  // Validate focus areas early with a friendly message.
+  if (parsed.focus) {
+    const invalid = parsed.focus.filter((a) => !VALID_AREAS.includes(a));
+    if (invalid.length) {
+      logger.error(`${RED}Área inválida:${NC} ${invalid.join(', ')}`);
+      logger.error(`Áreas válidas: ${VALID_AREAS.join(', ')}`);
+      return 1;
+    }
+  }
+
+  let IdeationEngine;
+  try {
+    IdeationEngine = require('../../.sinapse-ai/core/ideation/ideation-engine');
+  } catch (e) {
+    logger.error(`${RED}Motor de ideação indisponível:${NC} ${e.message}`);
+    return 1;
+  }
+
+  const engine = new IdeationEngine({ rootPath: process.cwd() });
+
+  if (!parsed.json) {
+    logger.always(`${CYAN}›${NC} Analisando o projeto${parsed.focus ? ` (${parsed.focus.join(', ')})` : ''}...`);
+  }
+
+  let result;
+  try {
+    result = await engine.ideate({ focus: parsed.focus, save: parsed.save });
+  } catch (e) {
+    logger.error(`${RED}Falha na análise:${NC} ${e.message}`);
+    return 1;
+  }
+
+  if (parsed.json) {
+    logger.always(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  const { summary } = result;
+  logger.always('');
+  logger.always(`${BOLD}${summary.totalSuggestions} sugestões${NC} · ${GREEN}${summary.quickWins} quick wins${NC} · ${YELLOW}${summary.highImpact} alto impacto${NC}`);
+
+  const top = result.allSuggestions.slice(0, 8);
+  if (top.length) {
+    logger.always('');
+    for (const s of top) {
+      const tag = s.category === 'quick-win' ? `${GREEN}[quick win]${NC}` : `${YELLOW}[${s.area}]${NC}`;
+      logger.always(`  ${tag} ${s.title || s.description}`);
+    }
+  } else {
+    logger.always(`\n${GREEN}Nenhuma sugestão pendente — o código está limpo nas áreas analisadas.${NC}`);
+  }
+
+  if (parsed.save) {
+    const out = path.join('.sinapse', 'ideation');
+    logger.always(`\nRelatório completo salvo em ${CYAN}${out}/${NC} (suggestions.md)`);
+  }
+  return 0;
+}
+
+module.exports = { cmdIdeate, parseIdeateArgs, VALID_AREAS };

package/bin/commands/uninstall.js

@@ -18,6 +18,35 @@ const {
 const { header } = require('../lib/header');
 const { rmDirSync } = require('../lib/fs-utils');
 const { confirmUninstall } = require('../lib/prompts');
+const { runSafe } = require('../../.sinapse-ai/core/utils/spawn-safe');
+
+// The installer sets git `core.hooksPath` to this managed dir. On uninstall we
+// must unset it — otherwise git keeps pointing at removed hooks and every future
+// commit fails with "cannot run hook" (UNINSTALL-GIT-HOOKS, audit 2026-06-11).
+const MANAGED_HOOKS_MARKER = path.join('.sinapse-ai', 'git-hooks');
+
+/**
+ * Unset git core.hooksPath IF it points at the SINAPSE-managed hooks dir.
+ * Only touches our own config — a user's custom hooksPath is left untouched.
+ * @param {string} projectDir - Git project directory (default cwd)
+ * @returns {Promise<{unset: boolean, value: string|null}>}
+ */
+async function removeGitHooksConfig(projectDir = process.cwd()) {
+  try {
+    const get = await runSafe('git', ['-C', projectDir, 'config', '--get', 'core.hooksPath']);
+    const value = (get.stdout || '').trim();
+    if (!get.success || !value) return { unset: false, value: null };
+    // Normalize separators so the marker matches on Windows and POSIX.
+    const normalized = value.replace(/\\/g, '/');
+    if (!normalized.includes(MANAGED_HOOKS_MARKER.replace(/\\/g, '/'))) {
+      return { unset: false, value }; // not ours — leave it alone
+    }
+    const unset = await runSafe('git', ['-C', projectDir, 'config', '--unset', 'core.hooksPath']);
+    return { unset: unset.success, value };
+  } catch {
+    return { unset: false, value: null };
+  }
+}
 
 // Story 10.40 — Remove SINAPSE-authored orqx agents from a global agents dir.
 // Returns { removed: N } for reporting. Only touches files matching *-orqx.md
@@ -205,6 +234,16 @@ async function cmdUninstall(opts = {}) {
     logger.always(`  ${YELLOW}-${NC} ~/.claude/settings.json (no SINAPSE keys found)`);
   }
 
+  // UNINSTALL-GIT-HOOKS — reset git hooks config so commits keep working.
+  const hooksResult = await removeGitHooksConfig(process.cwd());
+  if (hooksResult.unset) {
+    logger.always(`  ${GREEN}✓${NC} Reset git core.hooksPath (was SINAPSE-managed)`);
+  } else if (hooksResult.value) {
+    logger.always(`  ${YELLOW}-${NC} git core.hooksPath kept (custom, not SINAPSE-managed)`);
+  } else {
+    logger.always(`  ${YELLOW}-${NC} git core.hooksPath (not set)`);
+  }
+
   logger.always(`\n${GREEN}Sinapse uninstalled.${NC}`);
   logger.always(`${YELLOW}Note:${NC} PATH entry in shell RC files was not removed. Clean up manually if desired.\n`);
 }
@@ -216,5 +255,6 @@ module.exports = {
   removeInstalledAgentsFrom,
   removeOrqxAgentsFrom,
   cleanClaudeSettingsJson,
+  removeGitHooksConfig,
   INSTALLED_AGENTS_MANIFEST,
 };

package/bin/postinstall.js

@@ -1,11 +1,16 @@
 #!/usr/bin/env node
 
 /**
- * SINAPSE Postinstall Orchestrator
- * @story A.1 - Postinstall Script & Runtime Dirs
+ * SINAPSE Setup Orchestrator (formerly the npm `postinstall` lifecycle hook)
+ * @story A.1 - Setup Script & Runtime Dirs
  * @story B.1 - Minimalist Install Output Design
+ * @security 2026-06 - NO LONGER wired as an npm `postinstall` hook. Auto-running
+ *   code on `npm install` is a supply-chain surface: a compromised publish would
+ *   execute on every consumer's machine without any explicit action. Setup is now
+ *   EXPLICIT — it runs only via `npm run setup` or as part of `npx sinapse-ai install`,
+ *   never automatically. The module's behavior is otherwise unchanged.
  *
- * Runs automatically after `npm install` (global or local) unless:
+ * When invoked, it still skips itself when:
  *   - SINAPSE_SKIP_POSTINSTALL=1 is set (explicit opt-out)
  *   - A known CI env var is present (GITHUB_ACTIONS, CI=true, etc.)
  *   - npm was invoked with --ignore-scripts (native npm behavior, nothing to do here)
@@ -350,6 +355,43 @@ function stepCreateRuntimeDirs() {
   return { ok: softFailures === 0, critical: false };
 }
 
+/**
+ * Step: generate the SYNAPSE context-engine runtime (.synapse/ domain files).
+ * Compiles the L0 constitution domain from .sinapse-ai/constitution.md so the
+ * UserPromptSubmit context engine actually injects rules. Without this, the
+ * engine is inert (the hook silently emits no context). Tolerant + non-critical:
+ * the wrapper always exits 0 and the engine degrades gracefully if absent.
+ */
+function stepGenerateSynapse() {
+  if (isGlobalInstall()) {
+    return { ok: true, critical: false, skipped: true };
+  }
+  verboseLog(`${c.cyan}›${c.reset} Gerando runtime do motor de contexto (.synapse/)...`);
+  const script = path.join(PROJECT_ROOT, 'scripts', 'generate-synapse-runtime.js');
+  if (!fs.existsSync(script)) {
+    return { ok: true, critical: false, skipped: true };
+  }
+  // Run in-process (not a subprocess) — faster, and keeps the shared run()
+  // sequence (sync:ide → doctor) intact for callers/tests. The wrapper's
+  // generate() is tolerant and never throws; preserve our own exit code since
+  // the underlying generator sets process.exitCode=1 on a miss.
+  const savedExit = process.exitCode;
+  let ok = false;
+  try {
+    const { generate } = require(script);
+    ok = generate();
+  } catch (err) {
+    warn(`Geração do .synapse/ falhou: ${err.message} — não-crítico (motor degrada).`);
+  } finally {
+    process.exitCode = savedExit;
+  }
+  if (ok) {
+    verboseLog(`${c.green}✓${c.reset} Runtime do motor de contexto pronto (.synapse/constitution)`);
+  }
+  // Always non-critical: the engine degrades gracefully without domains.
+  return { ok: true, critical: false };
+}
+
 /**
  * Step 4: sinapse doctor --quiet.
  * Exit code semantics (per Story A.1 Dev Notes + Story A.3):
@@ -541,6 +583,9 @@ function main(argvOverride) {
     return 2;
   }
 
+  // Compile the SYNAPSE context-engine runtime (.synapse/). Non-critical.
+  const synapseGen = stepGenerateSynapse();
+
   const doctor = stepDoctor();
   if (doctor.critical) {
     renderPartialInstallMessage();
@@ -565,7 +610,7 @@ function main(argvOverride) {
   // so `npm install` does not report `command failed`. Critical failures have
   // already returned 2 above. The `--json` output still carries `status: warn`
   // for pipelines that want to act on it. [Story 10.39]
-  if (!syncIde.ok || !runtimeDirs.ok || !doctor.ok) {
+  if (!syncIde.ok || !runtimeDirs.ok || !synapseGen.ok || !doctor.ok) {
     renderPartialInstallMessage();
     if (FLAGS.json) {
       if (jsonState.status === 'success') jsonState.status = 'warn';
@@ -587,6 +632,7 @@ module.exports = {
   isValidInstallRoot,
   stepSyncIde,
   stepCreateRuntimeDirs,
+  stepGenerateSynapse,
   stepDoctor,
   renderFinalSummary,
   renderPartialInstallMessage,