ai-project-maintainer 0.3.0

package/ai-project-maintainer/references/tool-router.md

@@ -0,0 +1,53 @@
+# Tool Router
+
+Use this reference to choose checks dynamically. Run only tools that match the repository and the user's scope.
+
+## Selection Order
+
+1. Inspect the project with `scripts/probe-project.mjs`.
+2. Use installed Codex skills for security review when available.
+3. Use local CLI tools that are already installed.
+4. Use package-manager or containerized tools only when the repo already uses them or the user approves.
+5. Fall back to manual review with explicit coverage gaps.
+
+## Core Routing Table
+
+| Surface | Signals | Primary tools | Notes |
+| --- | --- | --- | --- |
+| Code security | Auth, API routes, serializers, file upload, HTTP clients, SQL construction, crypto | `codex-security`, Semgrep, CodeQL, Open Code Review | Prioritize changed files and dataflow into sinks. |
+| Secrets | `.env`, private keys, token-like config, CI variables, committed credentials | Gitleaks, Trivy secret scan | Do not print secret values. Report only location and type. |
+| Dependencies | Lockfiles, Docker images, SBOM, package manifests | Trivy, OSV-Scanner, native package audit | Separate reachable production risk from dev-only noise. |
+| Database migrations | `migrations/`, `db/migrate`, Prisma, Drizzle, Alembic, Flyway, Liquibase, raw SQL | Squawk, Atlas, Bytebase, pgroll, strong_migrations, gh-ost, pt-online-schema-change | Review lock behavior and rollback before correctness polish. |
+| IaC and cloud | Terraform, CloudFormation, Pulumi, Helm, Kubernetes YAML, Docker Compose | Checkov, Trivy config, Conftest/OPA, Kubescape | Focus on public exposure, IAM, network policy, privileged runtime, and secret mounts. |
+| Containers | Dockerfile, compose, image references, deploy manifests | Trivy image/config, Hadolint, Docker build checks | Check root user, privileged mode, writable filesystem, and unpinned base images. |
+| Kubernetes runtime | K8s manifests, `kubectl` context, incident request | k8sgpt, HolmesGPT, Kubescape, Falco, Cilium/Tetragon | Default to read-only commands. |
+| Web/API DAST | Staging URL explicitly provided by user | OWASP ZAP, Nuclei | Require explicit scope for active scans. Never infer internet targets. |
+| Incident response | Alerts, logs, metrics, traces, rollout history, deploys, migrations | HolmesGPT, OpenSRE, k8sgpt, kubectl, observability CLIs/APIs | Build a timeline before proposing fixes. |
+
+## Command Patterns
+
+Use these as patterns, adapting paths and package managers to the repo.
+
+```bash
+semgrep scan --config auto
+trivy fs --scanners vuln,secret,misconfig .
+gitleaks detect --source . --redact
+checkov -d .
+squawk path/to/migration.sql
+atlas migrate lint --dir "file://migrations"
+kubescape scan
+k8sgpt analyze
+```
+
+Use CodeQL when a CodeQL database or GitHub code scanning setup already exists, or when the user asks for deeper security analysis.
+
+## Missing Tool Handling
+
+When a useful tool is unavailable, write a short gap:
+
+```text
+Unavailable: squawk. Coverage gap: Postgres migration lock-risk linting was not run.
+Smallest next guardrail: add squawk to CI for changed `.sql` migration files.
+```
+
+Do not turn the review into an installation project unless the user asks for setup.

package/ai-project-maintainer/scripts/audit-plan.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { detectProject } from "./lib/project-detect.mjs";
+import { hasConfiguredEvidence, loadIntake } from "./lib/intake.mjs";
+
+function item(id, title, status, summary, recommendation = "") {
+  return { id, title, status, summary, recommendation };
+}
+
+function realBusinessFlows(intake) {
+  return (intake.businessFlows.business_flows || []).filter((flow) => flow && !flow.template && flow.id);
+}
+
+function flowTests(flows) {
+  return flows.flatMap((flow) => (Array.isArray(flow.tests) ? flow.tests : []));
+}
+
+export function buildAuditPlan(project, intake = loadIntake(project.root, project)) {
+  const profile = {
+    projectType: intake.profile.derived.projectType,
+    hasDatabase: intake.profile.derived.hasDatabase,
+    hasCi: intake.profile.derived.hasCi,
+    hasElectron: intake.profile.derived.hasElectron,
+    hasDeployment: intake.profile.derived.hasDeployment,
+    handlesAuth: Boolean(intake.profile.risk?.handles_auth),
+    handlesSensitiveData: Boolean(intake.profile.risk?.handles_sensitive_data),
+    handlesFinancialData: Boolean(intake.profile.risk?.handles_financial_data),
+  };
+  const evidence = intake.evidence.evidence || {};
+  const deployment = evidence.deployment || {};
+  const observability = evidence.observability || {};
+  const database = evidence.database || {};
+  const flows = realBusinessFlows(intake);
+  const tests = flowTests(flows);
+  const plan = [];
+
+  plan.push(
+    intake.initialized
+      ? item("intake-config", "Production audit intake", "PASS", "Project profile and evidence source templates are present.")
+      : item("intake-config", "Production audit intake", "GAP", "Production audit intake has not been initialized.", "Run init-audit and fill the generated templates."),
+  );
+
+  plan.push(
+    flows.length
+      ? item("business-critical-flows", "Critical business flows", "PASS", `${flows.length} critical flow(s) declared.`)
+      : item("business-critical-flows", "Critical business flows", "USER_DECISION", "The maintainer must declare the business flows that must not break.", "Fill .ai-maintainer/business-flows.yml with real flows."),
+  );
+
+  plan.push(
+    flows.length && tests.length === 0
+      ? item("business-flow-tests", "Business flow tests", "GAP", "Critical flows are declared without linked automated tests.", "Add tests for each critical flow and list them in business-flows.yml.")
+      : item("business-flow-tests", "Business flow tests", flows.length ? "PASS" : "USER_DECISION", flows.length ? `${tests.length} test reference(s) declared.` : "Declare flows before test coverage can be judged."),
+  );
+
+  plan.push(
+    profile.hasElectron
+      ? item("electron-security", "Electron security review", "PASS", "Electron surface detected; IPC, preload, file permission, and update trust checks are enabled.")
+      : item("electron-security", "Electron security review", "N/A", "No Electron surface detected."),
+  );
+
+  plan.push(
+    profile.hasCi
+      ? item("ci-security", "CI security review", "PASS", "CI workflow evidence detected; actionlint and zizmor checks are applicable.")
+      : item("ci-security", "CI security review", "GAP", "No GitHub Actions workflow evidence detected.", "Add CI or document another release gate in evidence-sources.yml."),
+  );
+
+  plan.push(
+    profile.hasDeployment || deployment.has_production
+      ? item("release-approval", "Production release approval", deployment.production_requires_approval ? "PASS" : "GAP", deployment.production_requires_approval ? "Production approval evidence declared." : "Production deployment exists without approval evidence.", "Use GitHub Environments or document the approval gate.")
+      : item("release-approval", "Production release approval", "GAP", "No production deployment evidence declared.", "Declare deployment provider and approval status in evidence-sources.yml."),
+  );
+
+  for (const [id, title, key] of [
+    ["observability-errors", "Error monitoring", "errors"],
+    ["observability-logs", "Production logs", "logs"],
+    ["observability-metrics", "Production metrics", "metrics"],
+    ["observability-alerts", "Production alerts", "alerts"],
+  ]) {
+    plan.push(
+      hasConfiguredEvidence(observability[key])
+        ? item(id, title, "PASS", `${title} evidence declared.`)
+        : item(id, title, "GAP", `${title} evidence is missing.`, `Declare ${key} evidence in evidence-sources.yml.`),
+    );
+  }
+
+  if (profile.hasDatabase) {
+    plan.push(item("database-migrations", "Database migration review", hasConfiguredEvidence(database.review_tool) ? "PASS" : "GAP", hasConfiguredEvidence(database.review_tool) ? "Database review tool evidence declared." : "Database surface detected without migration review tool evidence.", "Use Atlas, Bytebase, Squawk, or document manual migration review."));
+    plan.push(item("database-backup", "Database backup evidence", hasConfiguredEvidence(database.backup_policy) ? "PASS" : "GAP", hasConfiguredEvidence(database.backup_policy) ? "Backup policy evidence declared." : "Database backup evidence is missing.", "Document backup policy before production migration."));
+    plan.push(item("database-rollback", "Database rollback or forward-fix plan", hasConfiguredEvidence(database.rollback_plan) ? "PASS" : "GAP", hasConfiguredEvidence(database.rollback_plan) ? "Rollback or forward-fix evidence declared." : "Database rollback or forward-fix evidence is missing.", "Document rollback or forward-fix strategy."));
+  } else {
+    plan.push(item("database-migrations", "Database migration review", "N/A", "No database surface detected or declared."));
+    plan.push(item("database-backup", "Database backup evidence", "N/A", "No database surface detected or declared."));
+    plan.push(item("database-rollback", "Database rollback or forward-fix plan", "N/A", "No database surface detected or declared."));
+  }
+
+  if (intake.parseErrors.length) {
+    for (const error of intake.parseErrors) {
+      plan.push(item(`intake-parse-${error.path}`, "Intake YAML parse error", "GAP", `${error.path}: ${error.reason}`, "Fix malformed YAML so the audit can use maintainer-supplied evidence."));
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    root: project.root,
+    profile,
+    plan,
+    evidence: plan.filter((entry) => entry.status === "PASS"),
+    coverageGaps: plan.filter((entry) => entry.status === "GAP"),
+    userDecisions: plan.filter((entry) => entry.status === "USER_DECISION"),
+  };
+}
+
+function resolveOutputPath(root, outputPath) {
+  if (!outputPath) return null;
+  return path.isAbsolute(outputPath) ? outputPath : path.resolve(root, outputPath);
+}
+
+export function runAuditPlan(projectRoot, options = {}) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const project = detectProject(root);
+  const audit = buildAuditPlan(project, loadIntake(root, project));
+  const outputPath = resolveOutputPath(root, options.outputPath);
+  if (outputPath) {
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, JSON.stringify(audit, null, 2));
+  }
+  return audit;
+}
+
+function parseArgs(args) {
+  const positional = [];
+  let outputPath = null;
+  let jsonOnly = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--output") outputPath = args[++i];
+    else if (arg.startsWith("--output=")) outputPath = arg.slice("--output=".length);
+    else if (arg === "--json") jsonOnly = true;
+    else if (!arg.startsWith("--")) positional.push(arg);
+  }
+  return { projectRoot: positional[0] || process.cwd(), outputPath, jsonOnly };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const audit = runAuditPlan(args.projectRoot, { outputPath: args.outputPath });
+  console.log(JSON.stringify(audit, null, 2));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/ai-project-maintainer/scripts/bootstrap-local-tools.ps1

@@ -0,0 +1,109 @@
+param(
+  [string[]]$Tools = @("gitleaks", "trivy", "squawk"),
+  [string]$InstallDir = "$env:USERPROFILE\.codex\security-tools",
+  [switch]$AddToPath
+)
+
+$ErrorActionPreference = "Stop"
+$binDir = Join-Path $InstallDir "bin"
+New-Item -ItemType Directory -Force -Path $binDir | Out-Null
+$requestedTools = @()
+foreach ($item in $Tools) {
+  $requestedTools += ($item -split ',' | ForEach-Object { $_.Trim() } | Where-Object { $_ })
+}
+
+function Write-Step($Message) {
+  Write-Host "==> $Message"
+}
+
+function Test-Command($Name) {
+  $null -ne (Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Get-Asset($Repo, [string[]]$Patterns) {
+  $release = Invoke-RestMethod -Headers @{ "User-Agent" = "ai-project-maintainer" } -Uri "https://api.github.com/repos/$Repo/releases/latest"
+  foreach ($pattern in $Patterns) {
+    $asset = $release.assets | Where-Object { $_.name -match $pattern -and $_.name -match '\.zip$' } | Select-Object -First 1
+    if ($asset) { return $asset }
+  }
+  throw "No Windows zip asset matched $($Patterns -join ', ') for $Repo"
+}
+
+function Install-FromGitHubZip($Name, $Repo, [string[]]$Patterns, $ExeName) {
+  if (Test-Command $ExeName) {
+    Write-Step "$Name already available on PATH"
+    return
+  }
+
+  $asset = Get-Asset -Repo $Repo -Patterns $Patterns
+  $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("$Name-" + [guid]::NewGuid())
+  $zip = Join-Path $tmp $asset.name
+  New-Item -ItemType Directory -Force -Path $tmp | Out-Null
+
+  Write-Step "Downloading $Name from $Repo ($($asset.name))"
+  Invoke-WebRequest -Headers @{ "User-Agent" = "ai-project-maintainer" } -Uri $asset.browser_download_url -OutFile $zip
+  Expand-Archive -LiteralPath $zip -DestinationPath $tmp -Force
+
+  $exe = Get-ChildItem -Path $tmp -Recurse -File -Filter "$ExeName.exe" | Select-Object -First 1
+  if (-not $exe) { throw "Downloaded $Name but could not find $ExeName.exe in archive" }
+
+  Copy-Item -LiteralPath $exe.FullName -Destination (Join-Path $binDir "$ExeName.exe") -Force
+  Write-Step "Installed $Name to $binDir"
+}
+
+function Install-WithUvTool($Name, $Package, $ExeName) {
+  if (Test-Command $ExeName) {
+    Write-Step "$Name already available on PATH"
+    return
+  }
+  if (-not (Test-Command "uv")) {
+    Write-Warning "uv is not installed; cannot install $Name locally. Install uv, Python, or Docker and rerun."
+    return
+  }
+  Write-Step "Installing $Name with uv tool install $Package"
+  & uv tool install $Package
+  if ($LASTEXITCODE -ne 0) {
+    throw "uv tool install $Package failed with exit code $LASTEXITCODE"
+  }
+}
+
+foreach ($tool in $requestedTools) {
+  try {
+    switch ($tool.ToLowerInvariant()) {
+      "gitleaks" {
+        Install-FromGitHubZip -Name "gitleaks" -Repo "gitleaks/gitleaks" -Patterns @("windows.*x64", "windows.*64") -ExeName "gitleaks"
+      }
+      "trivy" {
+        Install-FromGitHubZip -Name "trivy" -Repo "aquasecurity/trivy" -Patterns @("windows-64bit", "windows.*64") -ExeName "trivy"
+      }
+      "squawk" {
+        Install-FromGitHubZip -Name "squawk" -Repo "sbdchd/squawk" -Patterns @("windows.*x86_64", "windows.*amd64", "windows.*64") -ExeName "squawk"
+      }
+      "semgrep" {
+        Install-WithUvTool -Name "semgrep" -Package "semgrep" -ExeName "semgrep"
+      }
+      "checkov" {
+        Install-WithUvTool -Name "checkov" -Package "checkov" -ExeName "checkov"
+      }
+      default {
+        Write-Warning "Unknown local bootstrap tool '$tool'. Supported: gitleaks, trivy, squawk, semgrep, checkov."
+      }
+    }
+  } catch {
+    Write-Warning "Could not install ${tool}: $($_.Exception.Message)"
+  }
+}
+
+if ($AddToPath) {
+  $current = [Environment]::GetEnvironmentVariable("Path", "User")
+  $parts = $current -split ';' | Where-Object { $_ }
+  if ($parts -notcontains $binDir) {
+    [Environment]::SetEnvironmentVariable("Path", ($parts + $binDir -join ';'), "User")
+    Write-Step "Added $binDir to the user PATH. Restart terminals/Codex to pick it up."
+  } else {
+    Write-Step "$binDir is already in the user PATH"
+  }
+}
+
+Write-Step "Installed tools:"
+Get-ChildItem -File -LiteralPath $binDir | Select-Object Name,Length,LastWriteTime

package/ai-project-maintainer/scripts/check-syntax.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const targetDirs = [
+  path.join(repoRoot, "ai-project-maintainer", "scripts"),
+  path.join(repoRoot, "test"),
+];
+
+function collectMjsFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectMjsFiles(full, out);
+    else if (entry.isFile() && entry.name.endsWith(".mjs")) out.push(full);
+  }
+  return out;
+}
+
+const files = targetDirs.flatMap((dir) => collectMjsFiles(dir));
+let failed = false;
+
+for (const file of files) {
+  const result = spawnSync(process.execPath, ["--check", file], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+  if (result.status !== 0) {
+    failed = true;
+    process.stderr.write(result.stderr || result.stdout);
+  }
+}
+
+if (!failed) {
+  console.log(`Syntax check passed for ${files.length} files.`);
+}
+
+process.exit(failed ? 1 : 0);

package/ai-project-maintainer/scripts/ci-smoke-gate.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { runLocalGate } from "./run-local-gate.mjs";
+
+const projectRoot = path.resolve(process.argv[2] || process.cwd());
+const outputPath = process.argv[3] || "reports/security-report.json";
+
+const report = runLocalGate(projectRoot, {
+  noTests: true,
+  outputPath,
+  writeReports: true,
+  runnerOptions: {
+    envPath: "",
+  },
+});
+
+const summary = {
+  status: report.passed ? "PASS" : "FAIL",
+  blockers: report.summary?.blockers ?? 0,
+  warnings: report.summary?.warnings ?? 0,
+  coverageGaps: report.summary?.coverageGaps ?? 0,
+  outputPath,
+};
+
+console.log(JSON.stringify(summary, null, 2));
+process.exit(report.passed ? 0 : 1);

package/ai-project-maintainer/scripts/cli.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { runAuditPlan } from "./audit-plan.mjs";
+import { runDoctor } from "./doctor.mjs";
+import { initAudit } from "./init-audit.mjs";
+import { initProject } from "./init-project.mjs";
+import { runLocalGate } from "./run-local-gate.mjs";
+import { summarizeReport } from "./report-summary.mjs";
+import { toMarkdown } from "./lib/report.mjs";
+
+function readOption(args, name, fallback = null) {
+  const index = args.indexOf(name);
+  if (index === -1) {
+    const inline = args.find((arg) => arg.startsWith(`${name}=`));
+    return inline ? inline.slice(name.length + 1) : fallback;
+  }
+  return args[index + 1] || fallback;
+}
+
+export function parseCliArgs(argv) {
+  const [command = "help", ...rest] = argv;
+
+  if (command === "doctor") {
+    return {
+      command,
+      args: {
+        jsonOnly: rest.includes("--json"),
+        checkTrivyDb: !rest.includes("--no-trivy-db"),
+      },
+    };
+  }
+
+  if (command === "init") {
+    return {
+      command,
+      args: {
+        projectRoot: rest.find((arg) => !arg.startsWith("--")) || process.cwd(),
+        profile: readOption(rest, "--profile", "oss"),
+        ci: readOption(rest, "--ci", "github"),
+        preCommit: rest.includes("--pre-commit"),
+      },
+    };
+  }
+
+  if (command === "gate") {
+    return {
+      command,
+      args: {
+        projectRoot: rest.find((arg) => !arg.startsWith("--")) || process.cwd(),
+        strict: rest.includes("--strict"),
+        release: rest.includes("--release"),
+        noTests: rest.includes("--no-tests"),
+        jsonOnly: rest.includes("--json"),
+        production: rest.includes("--production"),
+        outputPath: readOption(rest, "--output", null),
+      },
+    };
+  }
+
+  if (command === "init-audit") {
+    return {
+      command,
+      args: {
+        projectRoot: rest.find((arg) => !arg.startsWith("--")) || process.cwd(),
+      },
+    };
+  }
+
+  if (command === "audit-plan") {
+    return {
+      command,
+      args: {
+        projectRoot: rest.find((arg) => !arg.startsWith("--")) || process.cwd(),
+        outputPath: readOption(rest, "--output", null),
+        jsonOnly: rest.includes("--json"),
+      },
+    };
+  }
+
+  if (command === "summary") {
+    return {
+      command,
+      args: {
+        reportPath: rest.find((arg) => !arg.startsWith("--")),
+      },
+    };
+  }
+
+  return { command: "help", args: {} };
+}
+
+function doctorToMarkdown(report) {
+  const lines = [];
+  lines.push(`# AI Project Maintainer Doctor: ${report.passed ? "PASS" : "WARN"}`);
+  lines.push("");
+  lines.push(`- node: ${report.node.version}`);
+  lines.push("");
+  lines.push("## Required Scanners");
+  for (const tool of report.required) lines.push(`- ${tool.name}: ${tool.status}${tool.version ? ` (${tool.version})` : ""}`);
+  lines.push("");
+  lines.push("## Optional Scanners");
+  for (const tool of report.optional) lines.push(`- ${tool.name}: ${tool.status}${tool.version ? ` (${tool.version})` : ""}`);
+  lines.push("");
+  lines.push("## Trivy DB");
+  lines.push(`- ${report.trivyDb.status}: ${report.trivyDb.summary}`);
+  return lines.join("\n");
+}
+
+export function runCli(argv = process.argv.slice(2), io = { stdout: process.stdout, stderr: process.stderr }) {
+  const parsed = parseCliArgs(argv);
+
+  if (parsed.command === "doctor") {
+    const report = runDoctor({ checkTrivyDb: parsed.args.checkTrivyDb });
+    io.stdout.write(`${parsed.args.jsonOnly ? JSON.stringify(report, null, 2) : doctorToMarkdown(report)}\n`);
+    return report.passed ? 0 : 1;
+  }
+
+  if (parsed.command === "init") {
+    const result = initProject(parsed.args.projectRoot, {
+      profile: parsed.args.profile,
+      ci: parsed.args.ci,
+      preCommit: parsed.args.preCommit,
+    });
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  }
+
+  if (parsed.command === "gate") {
+    const report = runLocalGate(parsed.args.projectRoot, {
+      strict: parsed.args.strict,
+      release: parsed.args.release,
+      noTests: parsed.args.noTests,
+      production: parsed.args.production,
+      outputPath: parsed.args.outputPath,
+      writeReports: true,
+    });
+    io.stdout.write(`${parsed.args.jsonOnly ? JSON.stringify(report, null, 2) : toMarkdown(report)}\n`);
+    return report.passed ? 0 : 1;
+  }
+
+  if (parsed.command === "init-audit") {
+    const result = initAudit(parsed.args.projectRoot);
+    io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  }
+
+  if (parsed.command === "audit-plan") {
+    const audit = runAuditPlan(parsed.args.projectRoot, { outputPath: parsed.args.outputPath });
+    io.stdout.write(`${JSON.stringify(audit, null, 2)}\n`);
+    return 0;
+  }
+
+  if (parsed.command === "summary" && parsed.args.reportPath) {
+    io.stdout.write(`${summarizeReport(parsed.args.reportPath)}\n`);
+    return 0;
+  }
+
+  io.stderr.write("Usage: ai-project-maintainer <doctor|init|init-audit|audit-plan|gate|summary> [options]\n");
+  return 2;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(runCli());
+}

package/ai-project-maintainer/scripts/doctor.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { commandPath, runCommand } from "./lib/command-runner.mjs";
+
+const coreTools = ["git", "npm", "pnpm", "yarn", "bun"];
+const requiredScanners = ["gitleaks", "trivy", "semgrep"];
+const optionalScanners = ["osv-scanner", "actionlint", "zizmor", "syft", "grype", "checkov", "squawk", "scorecard", "pre-commit", "mega-linter-runner"];
+
+function inspectTool(name, options) {
+  const resolved = commandPath(name, options.runnerOptions || {});
+  if (!resolved) return { name, status: "missing", path: null, version: null };
+  const result = runCommand(name, ["--version"], { ...(options.runnerOptions || {}), timeoutMs: 30 * 1000 });
+  return {
+    name,
+    status: result.status === "pass" ? "available" : "error",
+    path: resolved,
+    version: `${result.stdout}\n${result.stderr}`.trim().split(/\r?\n/).find(Boolean) || `exit ${result.code}`,
+  };
+}
+
+export function runDoctor(options = {}) {
+  const required = requiredScanners.map((tool) => inspectTool(tool, options));
+  const optional = optionalScanners.map((tool) => inspectTool(tool, options));
+  const core = coreTools.map((tool) => inspectTool(tool, options));
+  const trivyAvailable = required.find((tool) => tool.name === "trivy")?.status === "available";
+  let trivyDb = { status: "skipped", summary: trivyAvailable ? "Trivy DB check disabled by option." : "trivy is not available" };
+
+  if (trivyAvailable && options.checkTrivyDb !== false) {
+    const result = runCommand("trivy", ["image", "--download-db-only", "--timeout", "30s"], {
+      ...(options.runnerOptions || {}),
+      timeoutMs: 60 * 1000,
+    });
+    trivyDb = {
+      status: result.status === "pass" ? "available" : "error",
+      summary: result.status === "pass" ? "Trivy vulnerability DB can be downloaded." : `${result.stderr}\n${result.stdout}`.trim(),
+    };
+  }
+
+  return {
+    node: { status: "available", version: process.version },
+    core,
+    required,
+    optional,
+    trivyDb,
+    passed: required.every((tool) => tool.status === "available") && (trivyDb.status === "available" || trivyDb.status === "skipped"),
+  };
+}
+
+function toMarkdown(report) {
+  const lines = [];
+  lines.push(`# AI Project Maintainer Doctor: ${report.passed ? "PASS" : "WARN"}`);
+  lines.push("");
+  lines.push(`- node: ${report.node.version}`);
+  lines.push("");
+  lines.push("## Core");
+  for (const tool of report.core) lines.push(`- ${tool.name}: ${tool.status}${tool.version ? ` (${tool.version})` : ""}`);
+  lines.push("");
+  lines.push("## Required Scanners");
+  for (const tool of report.required) lines.push(`- ${tool.name}: ${tool.status}${tool.version ? ` (${tool.version})` : ""}`);
+  lines.push("");
+  lines.push("## Optional Scanners");
+  for (const tool of report.optional) lines.push(`- ${tool.name}: ${tool.status}${tool.version ? ` (${tool.version})` : ""}`);
+  lines.push("");
+  lines.push("## Trivy DB");
+  lines.push(`- ${report.trivyDb.status}: ${report.trivyDb.summary}`);
+  return lines.join("\n");
+}
+
+function main() {
+  const jsonOnly = process.argv.includes("--json");
+  const noTrivyDb = process.argv.includes("--no-trivy-db");
+  const report = runDoctor({ checkTrivyDb: !noTrivyDb });
+  console.log(jsonOnly ? JSON.stringify(report, null, 2) : toMarkdown(report));
+  process.exit(report.passed ? 0 : 1);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}