supipowers 1.2.6 → 1.5.0

package/src/review/default-agents/security.md

@@ -0,0 +1,67 @@
+---
+name: security
+description: Security-focused code reviewer aligned with OWASP Top 10 and CWE Top 25
+focus: Access control, injection, authentication, cryptography, secrets management, supply chain, error handling
+---
+
+You are a security-focused code reviewer. Analyze the provided code diff for security vulnerabilities, referencing OWASP Top 10 and CWE Top 25 categories where applicable.
+
+## What to Check
+
+### Broken Access Control
+- Missing or incorrect authorization checks on endpoints and data access
+- Insecure direct object references (IDOR) — user-controlled IDs used without ownership validation
+- Privilege escalation paths — role checks that can be bypassed or are missing entirely
+- Server-side request forgery (SSRF) — user-controlled URLs passed to server-side fetchers
+
+### Injection
+- SQL/NoSQL injection — string concatenation or template literals in queries instead of parameterized statements
+- Cross-site scripting (XSS) — `innerHTML`, `document.write`, `dangerouslySetInnerHTML`, or unescaped user input in templates
+- OS command injection — user input passed to `exec()`, `spawn()`, or shell commands without sanitization
+- Template injection — user input interpolated into server-side templates
+
+### Authentication Failures
+- Weak session handling — predictable session IDs, missing expiration, no rotation after privilege change
+- Insecure token storage — JWTs or session tokens in localStorage, missing HttpOnly/Secure flags on cookies
+- Credential stuffing exposure — missing rate limiting or account lockout on authentication endpoints
+
+### Cryptographic Failures
+- Deprecated algorithms — MD5, SHA-1, DES, RC4, or ECB mode used for security purposes
+- Hardcoded cryptographic keys or initialization vectors
+- Weak randomness — `Math.random()` or other non-CSPRNG sources used for security-sensitive values
+- Missing or misconfigured TLS — allowing downgrade, self-signed certs in production
+
+### Secrets Management
+- Hardcoded credentials, API keys, tokens, or connection strings in source code
+- Secrets written to logs, error messages, or HTTP responses
+- Missing rotation patterns for long-lived credentials
+
+### Supply Chain Risks
+- Untrusted or unvetted dependencies introduced without justification
+- Missing integrity checks (lockfile changes without corresponding package.json changes)
+- Unsafe dynamic imports — `import()` or `require()` with user-controlled paths
+
+### Insecure Error Handling
+- Stack traces, internal paths, or debug information leaked to end users
+- Fail-open patterns — exceptions that grant access or skip validation instead of denying
+- Sensitive data (credentials, tokens, PII) included in error messages or responses
+
+### Security Logging Gaps
+- Missing audit trails for authentication events, authorization failures, or sensitive operations
+- PII or secrets written to application logs
+- Insufficient context in security-relevant log entries (missing user ID, IP, or action)
+
+## Severity Guide
+
+- **error**: Exploitable vulnerability that can lead to unauthorized access, data exposure, or code execution (e.g., injection, auth bypass, exposed secrets)
+- **warning**: Context-dependent risk that may be exploitable depending on deployment, configuration, or input source (e.g., missing validation on internal input, weak-but-not-broken crypto config)
+- **info**: Hardening opportunity or defense-in-depth suggestion that improves security posture without addressing an active vulnerability (e.g., missing security header, logging improvement)
+
+## Out of Scope
+
+- Correctness or logic bugs (handled by correctness agent)
+- Code style or formatting (handled by linter)
+- Maintainability concerns (handled by maintainability agent)
+- Performance optimizations
+
+{output_instructions}

package/src/review/fixer.ts

@@ -0,0 +1,219 @@
+import fixFindingsPrompt from "./prompts/fix-findings.md" with { type: "text" };
+import fixOutputSchemaPrompt from "./prompts/fix-output-schema.md" with { type: "text" };
+import type {
+  GateExecutionContext,
+  ReviewFinding,
+  ReviewFixOutput,
+  ReviewFixRecord,
+  ReviewOutput,
+  ReviewScope,
+} from "../types.js";
+import { parseStructuredOutput, runWithOutputValidation } from "./output.js";
+import { ReviewFixOutputSchema } from "./types.js";
+import { renderReviewTemplate } from "./template.js";
+
+export interface ReviewFixInput {
+  cwd: string;
+  scope: ReviewScope;
+  findings: ReviewFinding[];
+  createAgentSession: GateExecutionContext["createAgentSession"];
+  model?: string;
+  thinkingLevel?: string | null;
+  timeoutMs?: number;
+}
+
+export interface ReviewFixRunResult {
+  output: ReviewFixOutput;
+  attempts: number;
+  rawOutputs: string[];
+}
+
+export interface ReviewOutputDelta {
+  resolved: ReviewFinding[];
+  remaining: ReviewFinding[];
+  newFindings: ReviewFinding[];
+}
+
+function fingerprintFinding(finding: ReviewFinding): string {
+  return [
+    finding.file ?? "(unknown)",
+    finding.lineStart ?? "?",
+    finding.lineEnd ?? finding.lineStart ?? "?",
+    finding.title.toLowerCase().replace(/\s+/g, " ").trim(),
+  ].join("|");
+}
+
+function selectFixableFindings(findings: ReviewFinding[]): ReviewFinding[] {
+  return findings.filter((finding) => finding.file !== null);
+}
+
+function createSkippedRecord(finding: ReviewFinding, summary: string): ReviewFixRecord {
+  return {
+    findingIds: [finding.id],
+    file: finding.file,
+    status: "skipped",
+    summary,
+  };
+}
+
+function summarizeFixRecords(records: ReviewFixRecord[]): string {
+  const counts = records.reduce(
+    (summary, record) => {
+      summary[record.status] += 1;
+      return summary;
+    },
+    { applied: 0, skipped: 0, failed: 0 },
+  );
+
+  return `Fix pass: ${counts.applied} applied, ${counts.skipped} skipped, ${counts.failed} failed.`;
+}
+
+function deriveFixStatus(records: ReviewFixRecord[], requestedCount: number): ReviewFixOutput["status"] {
+  if (requestedCount === 0) {
+    return "skipped";
+  }
+
+  const applied = records.filter((record) => record.status === "applied").length;
+  const skipped = records.filter((record) => record.status === "skipped").length;
+  const failed = records.filter((record) => record.status === "failed").length;
+
+  if (applied === 0 && failed === 0 && skipped > 0) {
+    return "skipped";
+  }
+  if (applied > 0 && skipped === 0 && failed === 0) {
+    return "applied";
+  }
+  if (applied === 0 && failed > 0 && skipped === 0) {
+    return "blocked";
+  }
+  return "partial";
+}
+
+function normalizeFixOutput(
+  requestedFindings: ReviewFinding[],
+  reported: ReviewFixOutput,
+  carriedSkips: ReviewFixRecord[],
+): ReviewFixOutput {
+  const knownIds = new Set(requestedFindings.map((finding) => finding.id));
+  const handledIds = new Set<string>();
+  const fixes: ReviewFixRecord[] = [];
+
+  for (const record of reported.fixes) {
+    const findingIds = [...new Set(record.findingIds.filter((id) => knownIds.has(id) && !handledIds.has(id)))];
+    if (findingIds.length === 0) {
+      continue;
+    }
+    findingIds.forEach((id) => handledIds.add(id));
+    fixes.push({
+      ...record,
+      findingIds,
+    });
+  }
+
+  for (const finding of requestedFindings) {
+    if (!handledIds.has(finding.id)) {
+      fixes.push(createSkippedRecord(finding, "Fixer did not report handling this finding."));
+    }
+  }
+
+  fixes.push(...carriedSkips);
+  return {
+    fixes,
+    summary: reported.summary || summarizeFixRecords(fixes),
+    status: reported.status === "blocked"
+      ? "blocked"
+      : deriveFixStatus(fixes, requestedFindings.length + carriedSkips.length),
+  };
+}
+
+export function buildFixPrompt(scope: ReviewScope, findings: ReviewFinding[]): string {
+  return renderReviewTemplate(fixFindingsPrompt, {
+    scope,
+    findingsJson: JSON.stringify(findings, null, 2),
+    fixOutputSchema: fixOutputSchemaPrompt.trim(),
+  });
+}
+
+export async function runAutoFix(input: ReviewFixInput): Promise<ReviewFixRunResult> {
+  const skippedFindings = input.findings.filter((finding) => finding.file === null);
+  const carriedSkips = skippedFindings.map((finding) =>
+    createSkippedRecord(finding, "Skipped because the finding does not identify a concrete file to edit."),
+  );
+  const fixableFindings = selectFixableFindings(input.findings);
+
+  if (fixableFindings.length === 0) {
+    return {
+      output: {
+        fixes: carriedSkips,
+        summary: carriedSkips.length > 0
+          ? summarizeFixRecords(carriedSkips)
+          : "No findings were eligible for automatic fixing.",
+        status: "skipped",
+      },
+      attempts: 0,
+      rawOutputs: [],
+    };
+  }
+
+  const result = await runWithOutputValidation(input.createAgentSession, {
+    cwd: input.cwd,
+    prompt: buildFixPrompt(input.scope, fixableFindings),
+    schema: fixOutputSchemaPrompt.trim(),
+    parse(raw) {
+      return parseStructuredOutput<ReviewFixOutput>(raw, ReviewFixOutputSchema);
+    },
+    model: input.model,
+    thinkingLevel: input.thinkingLevel ?? null,
+    timeoutMs: input.timeoutMs ?? 180_000,
+  });
+
+  if (result.status === "blocked") {
+    return {
+      output: {
+        fixes: [
+          ...fixableFindings.map((finding) => createSkippedRecord(finding, result.error)),
+          ...carriedSkips,
+        ],
+        summary: result.error,
+        status: "blocked",
+      },
+      attempts: result.attempts,
+      rawOutputs: result.rawOutputs,
+    };
+  }
+
+  return {
+    output: normalizeFixOutput(fixableFindings, result.output, carriedSkips),
+    attempts: result.attempts,
+    rawOutputs: [result.rawOutput],
+  };
+}
+
+export function compareReviewOutputs(previous: ReviewOutput, next: ReviewOutput): ReviewOutputDelta {
+  const previousMap = new Map(previous.findings.map((finding) => [fingerprintFinding(finding), finding]));
+  const nextMap = new Map(next.findings.map((finding) => [fingerprintFinding(finding), finding]));
+
+  const resolved: ReviewFinding[] = [];
+  const remaining: ReviewFinding[] = [];
+  const newFindings: ReviewFinding[] = [];
+
+  for (const [fingerprint, finding] of previousMap) {
+    if (nextMap.has(fingerprint)) {
+      remaining.push(nextMap.get(fingerprint)!);
+    } else {
+      resolved.push(finding);
+    }
+  }
+
+  for (const [fingerprint, finding] of nextMap) {
+    if (!previousMap.has(fingerprint)) {
+      newFindings.push(finding);
+    }
+  }
+
+  return {
+    resolved,
+    remaining,
+    newFindings,
+  };
+}

package/src/review/multi-agent-runner.ts

@@ -0,0 +1,135 @@
+import agentReviewWrapperPrompt from "./prompts/agent-review-wrapper.md" with { type: "text" };
+import outputInstructionsPrompt from "./prompts/output-instructions.md" with { type: "text" };
+import reviewOutputSchema from "./prompts/review-output-schema.md" with { type: "text" };
+import type { ConfiguredReviewAgent, GateExecutionContext, ReviewOutput, ReviewScope } from "../types.js";
+import { explainReviewOutputFailure, parseReviewOutput, runWithOutputValidation } from "./output.js";
+import { renderReviewTemplate } from "./template.js";
+
+export interface MultiAgentReviewInput {
+  cwd: string;
+  scope: ReviewScope;
+  agents: ConfiguredReviewAgent[];
+  createAgentSession: GateExecutionContext["createAgentSession"];
+  model?: string;
+  thinkingLevel?: string | null;
+  timeoutMs?: number;
+  onAgentStart?: (agent: ConfiguredReviewAgent) => void;
+  onAgentComplete?: (result: MultiAgentAgentResult) => void;
+}
+
+export interface MultiAgentAgentResult {
+  agent: ConfiguredReviewAgent;
+  output: ReviewOutput;
+  attempts: number;
+  rawOutputs: string[];
+}
+
+export interface MultiAgentReviewResult {
+  agents: MultiAgentAgentResult[];
+  output: ReviewOutput;
+}
+
+function renderOutputInstructions(): string {
+  return renderReviewTemplate(outputInstructionsPrompt, {
+    outputSchema: reviewOutputSchema.trim(),
+  });
+}
+
+export function buildConfiguredAgentPrompt(agent: ConfiguredReviewAgent, scope: ReviewScope): string {
+  if (!agent.prompt.includes("{output_instructions}")) {
+    throw new Error(`Review agent ${agent.name} is missing the {output_instructions} placeholder.`);
+  }
+
+  const outputInstructions = renderOutputInstructions();
+  const agentPrompt = renderReviewTemplate(
+    agent.prompt.replaceAll("{output_instructions}", "{{outputInstructions}}"),
+    { outputInstructions },
+  );
+
+  return renderReviewTemplate(agentReviewWrapperPrompt, {
+    agent,
+    agentPrompt,
+    scope,
+  });
+}
+
+function aggregateAgentOutputs(results: MultiAgentAgentResult[]): ReviewOutput {
+  const findings = results.flatMap((result) =>
+    result.output.findings.map((finding) => ({
+      ...finding,
+      agent: finding.agent ?? result.agent.name,
+    })),
+  );
+  const blockedAgents = results.filter((result) => result.output.status === "blocked").length;
+  const summary = `Ran ${results.length} review agents: ${findings.length} findings, ${blockedAgents} blocked.`;
+
+  return {
+    findings,
+    summary,
+    status: blockedAgents > 0 ? "blocked" : findings.length > 0 ? "failed" : "passed",
+  };
+}
+
+async function runConfiguredAgent(
+  input: Omit<MultiAgentReviewInput, "agents">,
+  agent: ConfiguredReviewAgent,
+): Promise<MultiAgentAgentResult> {
+  input.onAgentStart?.(agent);
+
+  const result = await runWithOutputValidation(input.createAgentSession, {
+    cwd: input.cwd,
+    prompt: buildConfiguredAgentPrompt(agent, input.scope),
+    schema: reviewOutputSchema.trim(),
+    parse(raw) {
+      const output = parseReviewOutput(raw);
+      return {
+        output,
+        error: output ? null : explainReviewOutputFailure(raw),
+      };
+    },
+    model: agent.model ?? input.model,
+    thinkingLevel: input.thinkingLevel ?? null,
+    timeoutMs: input.timeoutMs ?? 120_000,
+  });
+
+  if (result.status === "blocked") {
+    const blockedResult = {
+      agent,
+      output: {
+        findings: [],
+        summary: result.error,
+        status: "blocked",
+      },
+      attempts: result.attempts,
+      rawOutputs: result.rawOutputs,
+    } satisfies MultiAgentAgentResult;
+    input.onAgentComplete?.(blockedResult);
+    return blockedResult;
+  }
+
+  const completedResult = {
+    agent,
+    output: {
+      ...result.output,
+      findings: result.output.findings.map((finding) => ({
+        ...finding,
+        agent: finding.agent ?? agent.name,
+      })),
+    },
+    attempts: result.attempts,
+    rawOutputs: [result.rawOutput],
+  } satisfies MultiAgentAgentResult;
+  input.onAgentComplete?.(completedResult);
+  return completedResult;
+}
+
+export async function runMultiAgentReview(input: MultiAgentReviewInput): Promise<MultiAgentReviewResult> {
+  const results = await Promise.all(
+    input.agents.map((agent) => runConfiguredAgent(input, agent)),
+  );
+
+  return {
+    agents: results,
+    output: aggregateAgentOutputs(results),
+  };
+}

package/src/review/output.ts

@@ -0,0 +1,147 @@
+import type { TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import invalidOutputRetryPrompt from "./prompts/invalid-output-retry.md" with { type: "text" };
+import { runStructuredAgentSession } from "../quality/ai-session.js";
+import { stripMarkdownCodeFence } from "../text.js";
+import type { GateExecutionContext, ReviewOutput } from "../types.js";
+import {
+  ReviewOutputSchema,
+  collectReviewValidationErrors,
+  formatReviewValidationErrors,
+} from "./types.js";
+import { renderReviewTemplate } from "./template.js";
+
+export interface StructuredParseResult<T> {
+  output: T | null;
+  error: string | null;
+}
+
+export interface OutputValidationRunOptions<T> {
+  cwd: string;
+  prompt: string;
+  schema: string;
+  parse: (raw: string) => StructuredParseResult<T>;
+  model?: string;
+  thinkingLevel?: string | null;
+  timeoutMs?: number;
+  maxAttempts?: number;
+}
+
+export type OutputValidationRunResult<T> =
+  | {
+      status: "ok";
+      output: T;
+      rawOutput: string;
+      attempts: number;
+    }
+  | {
+      status: "blocked";
+      error: string;
+      rawOutputs: string[];
+      attempts: number;
+    };
+
+function truncateForPrompt(text: string, maxLength = 1200): string {
+  const normalized = text.trim();
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, maxLength - 1)}…`;
+}
+
+export function parseStructuredOutput<T>(raw: string, schema: TSchema): StructuredParseResult<T> {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(stripMarkdownCodeFence(raw));
+  } catch (error) {
+    return {
+      output: null,
+      error: error instanceof Error ? `Invalid JSON: ${error.message}` : "Invalid JSON.",
+    };
+  }
+
+  if (!Value.Check(schema, parsed)) {
+    const errors = formatReviewValidationErrors(collectReviewValidationErrors(schema, parsed));
+    return {
+      output: null,
+      error: errors.length > 0 ? errors.join("; ") : "Output does not match the required schema.",
+    };
+  }
+
+  return {
+    output: parsed as T,
+    error: null,
+  };
+}
+
+export function parseReviewOutput(raw: string): ReviewOutput | null {
+  return parseStructuredOutput<ReviewOutput>(raw, ReviewOutputSchema).output;
+}
+
+export function explainReviewOutputFailure(raw: string): string | null {
+  return parseStructuredOutput<ReviewOutput>(raw, ReviewOutputSchema).error;
+}
+
+export async function runWithOutputValidation<T>(
+  createAgentSession: GateExecutionContext["createAgentSession"],
+  options: OutputValidationRunOptions<T>,
+): Promise<OutputValidationRunResult<T>> {
+  const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+  const rawOutputs: string[] = [];
+  let prompt = options.prompt;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const result = await runStructuredAgentSession(createAgentSession, {
+      cwd: options.cwd,
+      prompt,
+      model: options.model,
+      thinkingLevel: options.thinkingLevel ?? null,
+      timeoutMs: options.timeoutMs,
+    });
+
+    if (result.status !== "ok") {
+      return {
+        status: "blocked",
+        error: result.error,
+        rawOutputs,
+        attempts: attempt,
+      };
+    }
+
+    rawOutputs.push(result.finalText);
+    const parsed = options.parse(result.finalText);
+    if (parsed.output) {
+      return {
+        status: "ok",
+        output: parsed.output,
+        rawOutput: result.finalText,
+        attempts: attempt,
+      };
+    }
+
+    if (attempt === maxAttempts) {
+      return {
+        status: "blocked",
+        error: parsed.error ?? "Agent output was invalid.",
+        rawOutputs,
+        attempts: attempt,
+      };
+    }
+
+    prompt = renderReviewTemplate(invalidOutputRetryPrompt, {
+      prompt: options.prompt,
+      error: parsed.error ?? "Agent output was invalid.",
+      previousOutput: truncateForPrompt(result.finalText),
+      schema: options.schema,
+    });
+  }
+
+  return {
+    status: "blocked",
+    error: "Output validation exhausted without producing a valid result.",
+    rawOutputs,
+    attempts: maxAttempts,
+  };
+}

package/src/review/prompts/agent-review-wrapper.md

@@ -0,0 +1,36 @@
+You are part of a structured multi-agent code review pipeline.
+
+Agent name: {{agent.name}}
+Agent description: {{agent.description}}
+{{#if agent.focus}}
+Agent focus: {{agent.focus}}
+{{/if}}
+
+Agent-specific instructions:
+{{agentPrompt}}
+
+Review scope: {{scope.description}}
+Reviewable files: {{scope.stats.filesChanged}}
+Excluded files: {{scope.stats.excludedFiles}}
+Additions: {{scope.stats.additions}}
+Deletions: {{scope.stats.deletions}}
+{{#if scope.baseBranch}}
+Base branch: {{scope.baseBranch}}
+{{/if}}
+{{#if scope.commit}}
+Commit: {{scope.commit}}
+{{/if}}
+{{#if scope.customInstructions}}
+Custom review focus:
+{{scope.customInstructions}}
+{{/if}}
+
+Files in scope:
+{{#each scope.files}}
+- {{path}} (+{{additions}} -{{deletions}})
+{{/each}}
+
+Unified diff:
+```diff
+{{scope.diff}}
+```

package/src/review/prompts/fix-findings.md

@@ -0,0 +1,32 @@
+You are applying safe automatic fixes for reviewed findings.
+
+Use tools to inspect and edit the actual files.
+Fix only findings you can resolve confidently and safely.
+Do not change unrelated code.
+
+Review scope: {{scope.description}}
+Reviewable files: {{scope.stats.filesChanged}}
+Additions: {{scope.stats.additions}}
+Deletions: {{scope.stats.deletions}}
+
+Findings selected for automatic fixing:
+```json
+{{findingsJson}}
+```
+
+Return JSON only matching this schema:
+```json
+{{fixOutputSchema}}
+```
+
+Rules:
+- Group related edits by file when possible.
+- Each entry in `fixes` must reference one or more handled `findingIds`.
+- Use `applied` when you changed code to address the finding.
+- Use `skipped` when no safe automatic fix exists.
+- Use `failed` when you attempted a fix but could not complete it.
+- If every handled finding was skipped, set overall `status` to `skipped`.
+- If some fixes applied and others were skipped or failed, set overall `status` to `partial`.
+- If all safe fixes applied, set overall `status` to `applied`.
+- Use `blocked` only if you cannot complete a truthful fixing pass.
+- After editing, return JSON only. Do not wrap it in markdown fences.

package/src/review/prompts/fix-output-schema.md

@@ -0,0 +1,18 @@
+{
+  "fixes": [
+    {
+      "findingIds": ["F001"],
+      "file": "src/auth.ts",
+      "status": "applied",
+      "summary": "Added a null guard before dereferencing the user object."
+    },
+    {
+      "findingIds": ["F002"],
+      "file": null,
+      "status": "skipped",
+      "summary": "Skipped because the finding does not identify a concrete file to edit."
+    }
+  ],
+  "summary": "Applied 1 fix and skipped 1 finding.",
+  "status": "partial"
+}

package/src/review/prompts/invalid-output-retry.md

@@ -0,0 +1,22 @@
+{{prompt}}
+
+---
+
+Your previous output was invalid.
+
+Validation error:
+{{error}}
+
+{{#if previousOutput}}
+Previous output (truncated):
+```text
+{{previousOutput}}
+```
+
+{{/if}}
+Return valid JSON only matching this schema:
+```json
+{{schema}}
+```
+
+Do not wrap the JSON in markdown fences.

package/src/review/prompts/output-instructions.md

@@ -0,0 +1,14 @@
+Return JSON only matching this schema:
+```json
+{{outputSchema}}
+```
+
+Rules:
+- Tell the truth. If file, line, or suggestion is unknown, use `null` instead of guessing.
+- Every finding must be actionable and grounded in the provided scope.
+- `confidence` must be between 0 and 1.
+- Use priority `P0`..`P3`, where `P0` is critical and `P3` is low urgency.
+- Use `status: "failed"` when you found actionable issues.
+- Use `status: "passed"` only when no actionable issues remain.
+- Use `status: "blocked"` only if you cannot complete a truthful review.
+- Do not wrap the JSON in markdown fences.