sentinelayer-cli 0.8.0 → 0.8.2

package/src/agents/observability/tools/alert-audit.js

@@ -0,0 +1,39 @@
+// alert-audit — check that alert definitions exist (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const ALERT_SIGNATURES = [
+  /(^|\/)alerts?\/[^/]+\.(ya?ml|json|tf)$/i,
+  /(^|\/)prometheus\/rules?\//i,
+  /(^|\/)alertmanager\//i,
+  /(^|\/)monitors?\/[^/]+\.(ya?ml|json|tf)$/i,
+];
+
+export async function runAlertAudit({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  let found = false;
+  for await (const { relativePath } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (ALERT_SIGNATURES.some((p) => p.test(rel))) {
+      found = true;
+      break;
+    }
+  }
+  if (found) return [];
+  return [
+    createFinding({
+      tool: "alert-audit",
+      kind: "observability.no-alerts",
+      severity: "P2",
+      file: "",
+      line: 0,
+      evidence: "No alert definitions found under alerts/, monitors/, prometheus/rules/, or alertmanager/",
+      rootCause: "Without declarative alert definitions we can't tell what production failures the team is actually notified of.",
+      recommendedFix: "Define alerts in code (Prometheus rules, Datadog Terraform monitors, SLO burn-rate alerts). Require every critical endpoint to have an error-rate + latency alert.",
+      confidence: 0.6,
+    }),
+  ];
+}

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

@@ -0,0 +1,181 @@
+// Shared helpers for Sofia's (observability) domain tools (#A20).
+
+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 = "observability",
+} = {}) {
+  return {
+    persona,
+    tool: String(tool || "").trim(),
+    kind: String(kind || "").trim() || "observability",
+    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/observability/tools/dashboard-gap.js

@@ -0,0 +1,42 @@
+// dashboard-gap — check that a dashboard config exists somewhere (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, toPosix, walkRepoFiles } from "./base.js";
+
+const MANIFEST_SIGNATURES = [
+  /(^|\/)dashboards?\//,
+  /(^|\/)grafana\//,
+  /(^|\/)datadog\//,
+  /(^|\/)observability\//,
+];
+const DASHBOARD_FILES = /\.json$|\.yaml$|\.yml$/i;
+
+export async function runDashboardGap({ rootPath } = {}) {
+  const resolvedRoot = path.resolve(String(rootPath || "."));
+  let found = false;
+  for await (const { relativePath } of walkRepoFiles({ rootPath: resolvedRoot })) {
+    const rel = toPosix(relativePath);
+    if (MANIFEST_SIGNATURES.some((p) => p.test(rel)) && DASHBOARD_FILES.test(rel)) {
+      found = true;
+      break;
+    }
+  }
+  if (found) {
+    return [];
+  }
+  return [
+    createFinding({
+      tool: "dashboard-gap",
+      kind: "observability.no-dashboard",
+      severity: "P3",
+      file: "",
+      line: 0,
+      evidence: "No dashboards/, grafana/, datadog/, or observability/ directory with JSON / YAML configs",
+      rootCause: "No dashboard config checked into the repo. Ad-hoc dashboards created in the UI are invisible to code review and drift over time.",
+      recommendedFix: "Check a machine-readable dashboard source (Grafana JSON, Datadog Terraform, OpenMetrics) into the repo. Generate the deployed dashboard from source to keep them in sync.",
+      confidence: 0.55,
+    }),
+  ];
+}

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

@@ -0,0 +1,54 @@
+// Sofia (observability persona) domain-tool registry (#A20).
+
+import { runAlertAudit } from "./alert-audit.js";
+import { runDashboardGap } from "./dashboard-gap.js";
+import { runLogSchemaCheck } from "./log-schema-check.js";
+import { runSpanCoverage } from "./span-coverage.js";
+
+export const OBSERVABILITY_TOOLS = Object.freeze({
+  "span-coverage": {
+    id: "span-coverage",
+    description: "Flag route handlers that have no OpenTelemetry / Sentry / Datadog tracing span in scope.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runSpanCoverage,
+  },
+  "dashboard-gap": {
+    id: "dashboard-gap",
+    description: "Report if no dashboard configuration (Grafana JSON, Datadog TF, observability dir) is checked into the repo.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runDashboardGap,
+  },
+  "alert-audit": {
+    id: "alert-audit",
+    description: "Report if no declarative alert definitions (Prometheus rules, Datadog monitors, alertmanager) are checked in.",
+    schema: { type: "object", properties: { rootPath: { type: "string" } } },
+    handler: runAlertAudit,
+  },
+  "log-schema-check": {
+    id: "log-schema-check",
+    description: "Flag production source files (not tests / scripts / docs) that use console.log / print() instead of a structured logger.",
+    schema: { type: "object", properties: { rootPath: { type: "string" }, files: { type: "array", items: { type: "string" } } } },
+    handler: runLogSchemaCheck,
+  },
+});
+
+export const OBSERVABILITY_TOOL_IDS = Object.freeze(Object.keys(OBSERVABILITY_TOOLS));
+
+export async function dispatchObservabilityTool(toolId, args = {}) {
+  const tool = OBSERVABILITY_TOOLS[toolId];
+  if (!tool) {
+    throw new Error(`Unknown observability tool: ${toolId}`);
+  }
+  return tool.handler(args);
+}
+
+export async function runAllObservabilityTools({ rootPath, files = null } = {}) {
+  const findings = [];
+  for (const toolId of OBSERVABILITY_TOOL_IDS) {
+    const out = await dispatchObservabilityTool(toolId, { rootPath, files });
+    findings.push(...out);
+  }
+  return findings;
+}
+
+export { runAlertAudit, runDashboardGap, runLogSchemaCheck, runSpanCoverage };

package/src/agents/observability/tools/log-schema-check.js

@@ -0,0 +1,74 @@
+// log-schema-check — flag console.log in production code paths (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".py"]);
+
+function isProductionSource(relPath) {
+  const p = toPosix(relPath);
+  if (/(^|\/)(tests?|__tests__|specs?)\//.test(p)) return false;
+  if (/\.(test|spec)\.(js|jsx|ts|tsx|mjs|cjs|py)$/.test(p)) return false;
+  if (/(^|\/)scripts\//.test(p)) return false;
+  if (/(^|\/)bin\//.test(p)) return false;
+  if (/(^|\/)docs?\//.test(p)) return false;
+  return true;
+}
+
+const UNSTRUCTURED_LOG_PATTERNS_JS = /\bconsole\.(log|info|warn|error|debug)\s*\(/;
+const UNSTRUCTURED_LOG_PATTERNS_PY = /\bprint\s*\(/;
+
+export async function runLogSchemaCheck({ 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 = [];
+  const reported = new Set();
+  for await (const { fullPath, relativePath } of iterator) {
+    if (!isProductionSource(relativePath)) continue;
+    let content;
+    try {
+      content = await fsp.readFile(fullPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const ext = path.extname(fullPath).toLowerCase();
+    const pattern = ext === ".py" ? UNSTRUCTURED_LOG_PATTERNS_PY : UNSTRUCTURED_LOG_PATTERNS_JS;
+    const matches = findLineMatches(content, pattern);
+    if (matches.length === 0) continue;
+    const rel = toPosix(relativePath);
+    if (reported.has(rel)) continue;
+    reported.add(rel);
+    findings.push(
+      createFinding({
+        tool: "log-schema-check",
+        kind: "observability.unstructured-log",
+        severity: "P3",
+        file: rel,
+        line: matches[0].line,
+        evidence: getLineContent(content, matches[0].line),
+        rootCause: "Production code uses console.log / print() — unindexed output that can't be queried, correlated, or redacted at collection time.",
+        recommendedFix: "Route through a structured logger (pino, winston, structlog) with a shared schema. Configure PII fields to be automatically redacted.",
+        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 };
+  }
+}
+
+export { isProductionSource };

package/src/agents/observability/tools/span-coverage.js

@@ -0,0 +1,74 @@
+// span-coverage — flag route handlers without a tracing span (#A20).
+
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { createFinding, findLineMatches, getLineContent, toPosix, walkRepoFiles } from "./base.js";
+
+const CODE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".py", ".go"]);
+
+const HANDLER_PATTERNS = [
+  /\b(?:app|router|server|fastify|hono)\.(get|post|put|patch|delete)\s*\(/,
+  /^export\s+async\s+function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(/m,
+  /@(?:app|router|api_router)\.(?:get|post|put|patch|delete)\s*\(/,
+];
+
+const SPAN_SIGNALS = [
+  /tracer\.startSpan|tracer\.startActiveSpan|otel\.|opentelemetry|@tracing|withSpan|withActiveSpan/i,
+  /sentry\.(?:startTransaction|startSpan)/i,
+  /datadog|dd-trace|ddtrace/i,
+  /Sentry\.startTransaction/,
+];
+
+export async function runSpanCoverage({ 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 hasHandler = HANDLER_PATTERNS.some((p) => p.test(content));
+    if (!hasHandler) {
+      continue;
+    }
+    const hasSpan = SPAN_SIGNALS.some((p) => p.test(content));
+    if (hasSpan) {
+      continue;
+    }
+    const match = findLineMatches(content, HANDLER_PATTERNS[0])[0] ||
+      findLineMatches(content, HANDLER_PATTERNS[1])[0] ||
+      findLineMatches(content, HANDLER_PATTERNS[2])[0];
+    findings.push(
+      createFinding({
+        tool: "span-coverage",
+        kind: "observability.no-span",
+        severity: "P2",
+        file: toPosix(relativePath),
+        line: match?.line || 1,
+        evidence: getLineContent(content, match?.line || 1),
+        rootCause: "Route handler declared without any tracing-span signal (OpenTelemetry, Sentry, Datadog). Request latency / error breakdowns will be opaque.",
+        recommendedFix: "Wrap the handler body in tracer.startActiveSpan('<name>', …) or use framework middleware that auto-instruments handlers.",
+        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/persona-visuals.js

@@ -25,6 +25,44 @@ export const PERSONA_VISUALS = Object.freeze({
   "ai-governance": { color: "violet",  avatar: "\u{1F916}",       shortName: "Amina",  fullName: "Amina Chen",       domain: "ai_pipeline",           specialty: "Prompt injection, tool abuse, eval regressions, unsafe model routing, guardrail bypass, policy drift in agentic flows", bias: "AI autonomy requires proportional governance" },
 });
 
+/**
+ * Visual identity for the orchestrator tier (Dr. Kai Chen / Senti).
+ *
+ * Kept SEPARATE from PERSONA_VISUALS so the dispatch-invariant test
+ * (FULL_DEPTH_PERSONAS ⊆ PERSONA_VISUALS keys) isn't polluted by
+ * non-review entries. Consumers that need the orchestrator visual
+ * import ORCHESTRATOR_VISUALS or call resolveOrchestratorVisual().
+ */
+export const ORCHESTRATOR_VISUALS = Object.freeze({
+  "kai-chen": {
+    color: "gold",
+    avatar: "\u{1F3AD}",
+    shortName: "Kai",
+    fullName: "Dr. Kai Chen",
+    domain: "orchestration",
+    specialty: "Global orchestrator — picks personas, deduplicates across domains, ranks by severity × confidence × blast radius, demands reproduction steps",
+    bias: "performance budgets; operational simplicity; correctness over cleverness",
+    role: "Global Orchestrator / Senti",
+  },
+});
+
+export function resolveOrchestratorVisual(idOrName) {
+  if (!idOrName) return null;
+  const lower = String(idOrName).toLowerCase();
+  if (ORCHESTRATOR_VISUALS[lower]) {
+    return { id: lower, ...ORCHESTRATOR_VISUALS[lower] };
+  }
+  for (const [id, visual] of Object.entries(ORCHESTRATOR_VISUALS)) {
+    if (
+      visual.shortName.toLowerCase() === lower
+      || visual.fullName.toLowerCase() === lower
+    ) {
+      return { id, ...visual };
+    }
+  }
+  return null;
+}
+
 /**
  * Resolve persona visual identity by agent ID or persona name.
  */

package/src/agents/release/index.js

@@ -0,0 +1,12 @@
+// Omar (release persona) — barrel export (#A19).
+
+export {
+  RELEASE_TOOLS,
+  RELEASE_TOOL_IDS,
+  dispatchReleaseTool,
+  runAllReleaseTools,
+  runChangelogDiff,
+  runFeatureFlagAudit,
+  runRollbackVerify,
+  runSemverCheck,
+} from "./tools/index.js";