sentinelayer-cli 0.8.0 → 0.8.1

package/src/agents/backend/tools/base.js

@@ -0,0 +1,189 @@
+// Shared helpers for Maya's (backend) domain tools (#A14).
+// Mirrors src/agents/security/tools/base.js but with persona defaulting to
+// "backend". Intentional per-persona copy — a later refactor (#A25+) can
+// hoist this to src/agents/shared-tools/ once the 12 persona modules are
+// shipped and the common surface is stable.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import ignore from "ignore";
+
+const DEFAULT_IGNORED_DIRS = new Set([
+  ".git",
+  "node_modules",
+  ".venv",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".sentinelayer",
+  ".sentinel",
+  ".turbo",
+  ".idea",
+  ".vscode",
+  "__pycache__",
+  ".cache",
+]);
+const MAX_FILE_SIZE_BYTES = 1024 * 1024;
+const SEVERITIES = Object.freeze(["P0", "P1", "P2", "P3"]);
+
+export function toPosix(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+export function normalizeSeverity(value) {
+  const normalized = String(value || "").trim().toUpperCase();
+  if (SEVERITIES.includes(normalized)) {
+    return normalized;
+  }
+  return "P2";
+}
+
+export function createFinding({
+  severity,
+  kind,
+  file,
+  line = 0,
+  evidence = "",
+  rootCause = "",
+  recommendedFix = "",
+  confidence = null,
+  tool = "",
+  persona = "backend",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "backend",
+    severity: normalizeSeverity(severity),
+    file: toPosix(file || ""),
+    line: Number.isFinite(Number(line)) ? Math.max(0, Math.floor(Number(line))) : 0,
+    evidence: String(evidence || "").trim().slice(0, 400),
+    rootCause: String(rootCause || "").trim(),
+    recommendedFix: String(recommendedFix || "").trim(),
+    confidence:
+      confidence === null || confidence === undefined
+        ? null
+        : Math.max(0, Math.min(1, Number(confidence) || 0)),
+  };
+}
+
+async function readIgnorePatterns(filePath) {
+  try {
+    const raw = await fsp.readFile(filePath, "utf-8");
+    return String(raw || "")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+async function createIgnoreMatcher(rootPath) {
+  const matcher = ignore();
+  const gitignore = await readIgnorePatterns(path.join(rootPath, ".gitignore"));
+  const sentinel = await readIgnorePatterns(
+    path.join(rootPath, ".sentinelayerignore")
+  );
+  matcher.add([...gitignore, ...sentinel]);
+  return (relativePath, isDirectory) => {
+    const normalized = toPosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    const candidate = isDirectory ? `${normalized}/` : normalized;
+    return matcher.ignores(candidate);
+  };
+}
+
+export async function* walkRepoFiles({
+  rootPath = process.cwd(),
+  extensions = new Set(),
+  maxFileSize = MAX_FILE_SIZE_BYTES,
+} = {}) {
+  const resolvedRoot = path.resolve(rootPath);
+  const ignoreMatcher = await createIgnoreMatcher(resolvedRoot);
+  const wantedExtensions =
+    extensions instanceof Set
+      ? extensions
+      : new Set(Array.isArray(extensions) ? extensions : []);
+  const stack = [resolvedRoot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let entries = [];
+    try {
+      entries = await fsp.readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      const relativePath = toPosix(path.relative(resolvedRoot, fullPath));
+      if (entry.isDirectory()) {
+        if (!relativePath || DEFAULT_IGNORED_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (ignoreMatcher(relativePath, true)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (ignoreMatcher(relativePath, false)) {
+        continue;
+      }
+      const ext = path.extname(entry.name).toLowerCase();
+      if (wantedExtensions.size > 0 && !wantedExtensions.has(ext) && !wantedExtensions.has("")) {
+        continue;
+      }
+      let stat = null;
+      try {
+        stat = await fsp.stat(fullPath);
+      } catch {
+        stat = null;
+      }
+      if (!stat || stat.size > maxFileSize) {
+        continue;
+      }
+      yield { fullPath, relativePath };
+    }
+  }
+}
+
+export function findLineMatches(content, pattern) {
+  const text = String(content || "");
+  if (!pattern) {
+    return [];
+  }
+  const global = new RegExp(
+    pattern.source,
+    pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`
+  );
+  const matches = [];
+  let match;
+  while ((match = global.exec(text)) !== null) {
+    const lineIndex = text.slice(0, match.index).split(/\r?\n/).length;
+    matches.push({
+      index: match.index,
+      line: lineIndex,
+      match: match[0],
+    });
+  }
+  return matches;
+}
+
+export function getLineContent(content, line) {
+  const lines = String(content || "").split(/\r?\n/);
+  return (lines[Math.max(0, (Number(line) || 1) - 1)] || "").trim();
+}
+
+export { DEFAULT_IGNORED_DIRS, MAX_FILE_SIZE_BYTES, SEVERITIES };

package/src/agents/backend/tools/circuit-breaker-check.js

@@ -0,0 +1,123 @@
+// circuit-breaker-check — flag outbound calls lacking a circuit breaker (#A14).
+//
+// A "circuit breaker" in backend-runtime reviews is any guard that bounds
+// failure propagation — opossum, cockatiel, Polly (in .NET interop),
+// resilience4j, hystrix-style patterns, or hand-rolled "open/half-open"
+// state machines. The heuristic: look for outbound primitive calls (fetch,
+// axios, got, http.request, node-fetch, requests, urllib, aiohttp) and
+// verify there's a breaker mention in the same file or a common wrapper
+// file. Absence → P1 finding for human review.
+//
+// We stay conservative: one finding per file per outbound surface (not per
+// call site) so a file with 40 fetches doesn't produce 40 identical
+// findings.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const JS_TS_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+const PY_EXTENSIONS = new Set([".py"]);
+const CODE_EXTENSIONS = new Set([...JS_TS_EXTENSIONS, ...PY_EXTENSIONS]);
+
+const OUTBOUND_PATTERNS_JS = [
+  /\bfetch\s*\(/,
+  /\baxios(?:\.[a-z]+)?\s*\(/,
+  /\bgot(?:\.[a-z]+)?\s*\(/,
+  /\bhttp\.(?:request|get|post)\s*\(/,
+  /\bhttps\.(?:request|get|post)\s*\(/,
+  /\bsuperagent(?:\.[a-z]+)?\s*\(/,
+];
+
+const OUTBOUND_PATTERNS_PY = [
+  /\brequests\.(?:get|post|put|patch|delete|request)\s*\(/,
+  /\burllib\.request\.urlopen\s*\(/,
+  /\baiohttp\.ClientSession\s*\(/,
+  /\bhttpx\.(?:get|post|put|patch|delete|request)\s*\(/,
+];
+
+const BREAKER_SIGNALS = [
+  /circuitBreaker|circuit_breaker|CircuitBreaker/,
+  /opossum|cockatiel|resilience4j|hystrix|Polly/i,
+  /\bbreaker\.(?:fire|exec|execute)\s*\(/,
+];
+
+export async function runCircuitBreakerCheck({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions: CODE_EXTENSIONS });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const ext = path.extname(fullPath).toLowerCase();
+    const outboundPatterns = PY_EXTENSIONS.has(ext)
+      ? OUTBOUND_PATTERNS_PY
+      : OUTBOUND_PATTERNS_JS;
+
+    const hasBreaker = BREAKER_SIGNALS.some((pattern) => pattern.test(content));
+    if (hasBreaker) {
+      continue;
+    }
+
+    const seenPatterns = new Set();
+    for (const pattern of outboundPatterns) {
+      if (!pattern.test(content)) {
+        continue;
+      }
+      if (seenPatterns.has(pattern.source)) {
+        continue;
+      }
+      seenPatterns.add(pattern.source);
+      const match = pattern.exec(content);
+      const lineIndex = content.slice(0, match?.index || 0).split(/\r?\n/).length;
+      findings.push(
+        createFinding({
+          tool: "circuit-breaker-check",
+          kind: "backend.no-circuit-breaker",
+          severity: "P1",
+          file: toPosix(relativePath),
+          line: lineIndex,
+          evidence: `${pattern.source} called without a circuit breaker in this file`,
+          rootCause:
+            "Outbound primitive call has no circuit breaker in scope — a slow or failing dependency cascades into the caller's runtime.",
+          recommendedFix:
+            "Wrap the dependency in a circuit breaker (opossum on Node, pybreaker / hyx in Python) with OPEN / HALF_OPEN / CLOSED transitions and fail-closed defaults.",
+          confidence: 0.55,
+        })
+      );
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) {
+      continue;
+    }
+    const fullPath = path.isAbsolute(trimmed)
+      ? trimmed
+      : path.join(resolvedRoot, trimmed);
+    const relativePath = path
+      .relative(resolvedRoot, fullPath)
+      .replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}

package/src/agents/backend/tools/idempotency-audit.js

@@ -0,0 +1,105 @@
+// idempotency-audit — flag mutation endpoints without idempotency plumbing (#A14).
+//
+// Backend-runtime review: every POST / PUT / PATCH that can be retried by a
+// client (or a queue / webhook) should carry an idempotency key, and the
+// server should dedupe on it. We scan for handler declarations and look for
+// signals that idempotency is being honored — presence of
+// `idempotency_key`, `Idempotency-Key`, or a deduplication table lookup —
+// anywhere in the file.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const JS_TS_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+const PY_EXTENSIONS = new Set([".py"]);
+
+const MUTATION_PATTERNS = [
+  // JS / TS routers: Express, Fastify, Koa, Hono
+  /\b(?:app|router|server|route)\.(post|put|patch)\s*\(/,
+  /\bfastify\.(post|put|patch)\s*\(/,
+  /\bhono\.(post|put|patch)\s*\(/,
+  // Next.js app-router handlers
+  /^export\s+async\s+function\s+(POST|PUT|PATCH)\s*\(/m,
+  // Python: FastAPI / Flask
+  /@(?:app|router|blueprint)\.(post|put|patch)\s*\(/,
+];
+
+const IDEMPOTENCY_SIGNALS = [
+  /idempotency[_-]?key/i,
+  /Idempotency-Key/,
+  /dedupe|deduplicat|already_processed/i,
+];
+
+export async function runIdempotencyAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const extensions = new Set([...JS_TS_EXTENSIONS, ...PY_EXTENSIONS]);
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const hasSignal = IDEMPOTENCY_SIGNALS.some((pattern) => pattern.test(content));
+    if (hasSignal) {
+      continue;
+    }
+
+    const allMatches = [];
+    for (const pattern of MUTATION_PATTERNS) {
+      allMatches.push(...findLineMatches(content, pattern));
+    }
+    if (allMatches.length === 0) {
+      continue;
+    }
+    allMatches.sort((a, b) => a.line - b.line);
+    const first = allMatches[0];
+    findings.push(
+      createFinding({
+        tool: "idempotency-audit",
+        kind: "backend.no-idempotency",
+        severity: "P2",
+        file: toPosix(relativePath),
+        line: first.line,
+        evidence: getLineContent(content, first.line),
+        rootCause:
+          "Mutation-style route handler(s) declared in a file with no idempotency / dedupe plumbing. Retries from clients, queues, or webhooks risk double-charge / double-send.",
+        recommendedFix:
+          "Accept an Idempotency-Key header, persist (key, response) for a reasonable window (e.g. 24h), and return the cached response on replay.",
+        confidence: 0.5,
+      })
+    );
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) {
+      continue;
+    }
+    const fullPath = path.isAbsolute(trimmed)
+      ? trimmed
+      : path.join(resolvedRoot, trimmed);
+    const relativePath = path
+      .relative(resolvedRoot, fullPath)
+      .replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}

package/src/agents/backend/tools/index.js

@@ -0,0 +1,87 @@
+// Maya (backend persona) domain-tool registry (#A14).
+
+import { runCircuitBreakerCheck } from "./circuit-breaker-check.js";
+import { runIdempotencyAudit } from "./idempotency-audit.js";
+import { runRetryAudit } from "./retry-audit.js";
+import { runTimeoutAudit } from "./timeout-audit.js";
+
+export const BACKEND_TOOLS = Object.freeze({
+  "circuit-breaker-check": {
+    id: "circuit-breaker-check",
+    description:
+      "Flag files that make outbound HTTP calls (fetch / axios / got / http(s) / requests / httpx / urllib / aiohttp) without any circuit-breaker signal in scope.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runCircuitBreakerCheck,
+  },
+  "retry-audit": {
+    id: "retry-audit",
+    description:
+      "Flag hand-rolled retry loops using constant delays (classic thundering-herd risk). Does not fire when p-retry / async-retry / tenacity / Polly is already in use.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runRetryAudit,
+  },
+  "timeout-audit": {
+    id: "timeout-audit",
+    description:
+      "Flag outbound HTTP calls declared without an explicit timeout / AbortSignal — default timeouts in major clients are effectively infinite.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runTimeoutAudit,
+  },
+  "idempotency-audit": {
+    id: "idempotency-audit",
+    description:
+      "Flag files that declare POST/PUT/PATCH handlers without any idempotency-key or dedupe plumbing. Catches double-charge / double-send risk.",
+    schema: {
+      type: "object",
+      properties: {
+        rootPath: { type: "string" },
+        files: { type: "array", items: { type: "string" } },
+      },
+    },
+    handler: runIdempotencyAudit,
+  },
+});
+
+export const BACKEND_TOOL_IDS = Object.freeze(Object.keys(BACKEND_TOOLS));
+
+export async function dispatchBackendTool(toolId, args = {}) {
+  const tool = BACKEND_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown backend tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllBackendTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of BACKEND_TOOL_IDS) {
+    const out = await dispatchBackendTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export {
+  runCircuitBreakerCheck,
+  runIdempotencyAudit,
+  runRetryAudit,
+  runTimeoutAudit,
+};

package/src/agents/backend/tools/retry-audit.js

@@ -0,0 +1,132 @@
+// retry-audit — flag retry loops without exponential backoff + jitter (#A14).
+//
+// Retries are a footgun: a linear / fixed-interval retry against a failing
+// downstream is a synchronized flood, which is exactly when you want jitter
+// and exponential backoff. We look for loops that include `setTimeout(...)`
+// or `sleep(...)` with constant delays as a heuristic — the LLM review
+// layer confirms.
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, toPosix, walkRepoFiles } from "./base.js";
+
+const JS_TS_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+]);
+const PY_EXTENSIONS = new Set([".py"]);
+
+// "for-loop with constant sleep" pattern — a classic bad-retry shape.
+const BAD_RETRY_PATTERNS = [
+  // for (let i = 0; i < 5; i++) { ...; await sleep(1000); } — constant 1000 ms
+  {
+    pattern: /for\s*\([^)]*;[^)]*<[^)]*\)\s*\{[\s\S]{0,500}?(?:setTimeout|sleep|delay|wait)\s*\([^)]*\b\d{2,}\b[^)]*\)/,
+    kind: "backend.retry-constant-delay",
+    severity: "P2",
+    rootCause:
+      "A for-loop retry with a constant delay creates synchronized load on the downstream when it recovers.",
+    recommendedFix:
+      "Replace with exponential backoff + jitter. Libraries: p-retry / async-retry on Node, tenacity on Python.",
+    confidence: 0.6,
+  },
+  {
+    pattern: /while\s*\([^)]*(?:retry|attempt)[^)]*\)\s*\{[\s\S]{0,500}?(?:setTimeout|sleep|delay|wait)\s*\([^)]*\b\d{2,}\b[^)]*\)/,
+    kind: "backend.retry-constant-delay",
+    severity: "P2",
+    rootCause:
+      "A while-retry loop with a constant delay thunders herd once the downstream recovers.",
+    recommendedFix:
+      "Add exponential backoff and jitter. A simple formula: delay = Math.min(maxDelay, baseDelay * 2**attempt * (0.5 + Math.random())).",
+    confidence: 0.55,
+  },
+  {
+    pattern: /for\s+\w+\s+in\s+range\s*\([^)]*\)\s*:\s*\n[\s\S]{0,400}?time\.sleep\s*\(\s*\d+\s*\)/,
+    kind: "backend.retry-constant-delay",
+    severity: "P2",
+    rootCause:
+      "Python retry loop uses time.sleep with a constant — synchronized retry storm risk.",
+    recommendedFix:
+      "Switch to tenacity.retry with stop_after_attempt + wait_exponential_jitter.",
+    confidence: 0.55,
+  },
+];
+
+// "no jitter" signal: we look for files that DO have retry logic (mentioned
+// keywords) but don't mention jitter / random.
+function hasJitter(content) {
+  return /jitter|Math\.random|random\.(?:random|uniform)|secrets\.randbelow/.test(
+    content
+  );
+}
+
+function hasRetryLibraryHint(content) {
+  return /p-retry|async-retry|retry\.operation|tenacity\.retry|@retry|retry_strategy|Polly/.test(
+    content
+  );
+}
+
+export async function runRetryAudit({ rootPath, files = null } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  const extensions = new Set([...JS_TS_EXTENSIONS, ...PY_EXTENSIONS]);
+  const iterator =
+    Array.isArray(files) && files.length > 0
+      ? iterateExplicitFiles(resolvedRoot, files)
+      : walkRepoFiles({ rootPath: resolvedRoot, extensions });
+
+  const findings = [];
+  for await (const { fullPath, relativePath } of iterator) {
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    if (hasRetryLibraryHint(content)) {
+      // Retry library is in use — assume it handles backoff correctly.
+      continue;
+    }
+
+    for (const rule of BAD_RETRY_PATTERNS) {
+      const matches = findLineMatches(content, rule.pattern);
+      if (matches.length === 0) {
+        continue;
+      }
+      findings.push(
+        createFinding({
+          tool: "retry-audit",
+          kind: rule.kind,
+          severity: rule.severity,
+          file: toPosix(relativePath),
+          line: matches[0].line,
+          evidence: (content.split(/\r?\n/)[matches[0].line - 1] || "").trim(),
+          rootCause: rule.rootCause,
+          recommendedFix: rule.recommendedFix,
+          confidence: hasJitter(content) ? Math.max(0.3, rule.confidence - 0.2) : rule.confidence,
+        })
+      );
+    }
+  }
+  return findings;
+}
+
+async function* iterateExplicitFiles(resolvedRoot, files) {
+  for (const file of files) {
+    const trimmed = String(file || "").trim();
+    if (!trimmed) {
+      continue;
+    }
+    const fullPath = path.isAbsolute(trimmed)
+      ? trimmed
+      : path.join(resolvedRoot, trimmed);
+    const relativePath = path
+      .relative(resolvedRoot, fullPath)
+      .replace(/\\/g, "/");
+    yield { fullPath, relativePath };
+  }
+}