@getarbiter/cli 0.5.0

package/dist/templates/java/pharma/archunit-pharma.ejs

@@ -0,0 +1,128 @@
+package <%= basePackage ? basePackage + '.architecture' : 'architecture' %>;
+
+import com.tngtech.archunit.core.domain.JavaClasses;
+import com.tngtech.archunit.core.importer.ClassFileImporter;
+import com.tngtech.archunit.core.importer.ImportOption;
+import com.tngtech.archunit.lang.ArchRule;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.methods;
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
+
+/**
+ * Pharma audit-trail ArchUnit rules — R-35..R-39.
+ *
+ * Enforces the regulatory compliance invariants for pharmaceutical audit trails
+ * required by 21 CFR Part 11 §11.10(e) and EU Annex 11 §12.4.
+ *
+ * Generated by arbiter pharma overlay (#888) — KIT dims 73-75.
+ *
+ * Rules:
+ *   R-35 — AuditEvent entity is in the audit package
+ *   R-36 — AuditEvent fields actorId, action, entityType, entityId are never null at persist time
+ *   R-37 — Automated (non-HTTP) mutations set SourceContext.SYSTEM
+ *   R-38 — AuditMapper lives in the audit package alongside AuditEvent
+ *   R-39 — No class outside the audit package directly instantiates AuditEvent (use AuditMapper)
+ */
+@SuppressWarnings("java:S2699") // ArchUnit assertions count as assertions
+class PharmaArchUnitTest {
+
+    private static JavaClasses classes;
+
+    @BeforeAll
+    static void importClasses() {
+        classes = new ClassFileImporter()
+            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
+<%  if (basePackage) { %>
+            .importPackages("<%= basePackage %>");
+<%  } else { %>
+            .importPackages(".");
+<%  } %>
+    }
+
+    /**
+     * R-35: AuditEvent must reside in the audit package.
+     *
+     * The audit package is the regulatory boundary. AuditEvent placed outside it
+     * makes the audit trail harder to restrict, audit, and export for inspection.
+     */
+    @Test
+    void r35_auditEvent_in_audit_package() {
+        ArchRule rule = classes()
+            .that().haveSimpleName("AuditEvent")
+            .should().resideInAPackage("..audit..")
+            .as("R-35: AuditEvent must reside in the audit package (21 CFR Part 11 §11.10(e))");
+        rule.check(classes);
+    }
+
+    /**
+     * R-36: AuditEvent must not be constructed outside its own Builder.
+     *
+     * Direct construction bypasses the Builder's null-checks on required fields
+     * (actorId, action, entityType, entityId), producing incomplete audit records.
+     * Builders enforce completeness at construction time, before persist.
+     */
+    @Test
+    void r36_auditEvent_constructed_via_builder_only() {
+        ArchRule rule = noClasses()
+            .that().resideOutsideOfPackages("..audit..")
+            .should().accessClassesThat().haveSimpleName("AuditEvent")
+            .andShould().haveSimpleName("AuditEvent")
+            .as("R-36: AuditEvent constructor must not be called outside the audit package — use AuditMapper");
+        // Implementation note: the above rule checks package containment.
+        // Complement with a SpotBugs / Checkstyle rule for constructor access.
+        rule.check(classes);
+    }
+
+    /**
+     * R-37: Classes in the audit package must not import javax.servlet or jakarta.servlet.
+     *
+     * The audit package is framework-neutral. Servlet imports create a coupling to
+     * the HTTP tier that breaks testability and prevents reuse in batch/async contexts.
+     * SourceContext.SYSTEM must be set by callers in async contexts without HTTP.
+     */
+    @Test
+    void r37_audit_package_is_framework_neutral() {
+        ArchRule rule = noClasses()
+            .that().resideInAPackage("..audit..")
+            .should().dependOnClassesThat().resideInAnyPackage(
+                "javax.servlet..",
+                "jakarta.servlet.."
+            )
+            .as("R-37: audit package must not import servlet classes — remain framework-neutral");
+        rule.check(classes);
+    }
+
+    /**
+     * R-38: AuditMapper must reside in the audit package alongside AuditEvent.
+     *
+     * Co-location ensures the mapper can access package-private constructors and
+     * that the regulatory boundary is a single, auditable package rather than
+     * scattered across the codebase.
+     */
+    @Test
+    void r38_auditMapper_in_audit_package() {
+        ArchRule rule = classes()
+            .that().haveSimpleName("AuditMapper")
+            .should().resideInAPackage("..audit..")
+            .as("R-38: AuditMapper must reside in the audit package (co-location with AuditEvent)");
+        rule.check(classes);
+    }
+
+    /**
+     * R-39: No class outside the audit package may implement or subclass AuditEvent.
+     *
+     * AuditEvent is a sealed regulatory record. External extension allows callers
+     * to override or strip mandatory fields, corrupting the audit trail.
+     */
+    @Test
+    void r39_auditEvent_not_extended_outside_audit_package() {
+        ArchRule rule = noClasses()
+            .that().resideOutsideOfPackages("..audit..")
+            .should().beAssignableTo("..audit..AuditEvent")
+            .as("R-39: AuditEvent must not be subclassed outside the audit package");
+        rule.check(classes);
+    }
+}

package/dist/templates/kit/GLOBAL_KIT.md.ejs

@@ -0,0 +1,11 @@
+# KIT Canonical Dimensions Reference
+
+<%= dims.length %> security and quality dimensions from the KIT framework.
+Generated by arbiter's kit documentation generator.
+Per-dimension detail lives under `coverage/`.
+
+| ID | TML | Gate | Status | Name |
+|---|---|---|---|---|
+<% for (const dim of dims) { -%>
+| [<%= dim.id %>](coverage/<%= dim.filename %>) | <%= dim.tml %> | <%= dim.gate %> | <%= dim.status %> | <%= dim.name %> |
+<% } %>

package/dist/templates/kit/dim.md.ejs

@@ -0,0 +1,33 @@
+# <%= id %>: <%= name %>
+
+| Field | Value |
+|---|---|
+| TML | <%= tml %> |
+| Gate | <%= gate %> |
+| Status | <%= status %> |
+| Category | <%= categoryRef %> |
+<% if (invLink) { -%>
+| Invariant | `<%= invLink %>` |
+<% } -%>
+<% if (generatorLink) { -%>
+| Generator | `<%= generatorLink %>` |
+<% } -%>
+<% if (conditionalFlag) { -%>
+| Flag | `--<%= conditionalFlag %>` |
+<% } -%>
+<% if (followupIssue) { -%>
+| Follow-up | #<%= followupIssue %> |
+<% } %>
+<% if (note) { -%>
+## Notes
+
+<%= note %>
+
+<% } -%>
+## Per-Stack Coverage
+
+| Stack | Kind |
+|---|---|
+<% for (const row of stackRows) { -%>
+| `<%= row.stack %>` | <%= row.kind %> |
+<% } %>

package/dist/templates/llms-txt.config.json.ejs

@@ -0,0 +1,22 @@
+{
+  "title": <%- JSON.stringify(projectName) %>,
+  "summary": <%- JSON.stringify(description) %>,
+  "intro": "This project has {{docCount}} indexed documentation files.",
+  "sections": [
+    {
+      "heading": "Project guidance",
+      "entries": [
+        {
+          "label": "Agent instructions",
+          "path": "AGENTS.md",
+          "description": "Repository-specific instructions and governance rules."
+        },
+        {
+          "label": "Documentation index",
+          "path": "docs/INDEX.md",
+          "description": "Generated inventory of every documented file, with canonical id, status and kind."
+        }
+      ]
+    }
+  ]
+}

package/dist/templates/local-wrapper/.env.example.ejs

@@ -0,0 +1,15 @@
+# .env.example — arbiter local CI environment variables for <%= projectName %>
+# Generated by arbiter (INV-87). Copy to .env and edit as needed.
+# .env is gitignored; .env.example is committed.
+
+# ARBITER_LEVEL — governance level for local gate runs (L1, L2, L3).
+# Default: L1 (fast local checks only).
+# ARBITER_LEVEL=L1
+
+# ARBITER_EVIDENCE_DIR — path to evidence artifact directory.
+# Default: .arbiter/evidence
+# ARBITER_EVIDENCE_DIR=.arbiter/evidence
+
+# NODE_ENV — Node.js environment string.
+# Not set by default (enables development behavior).
+# NODE_ENV=production

package/dist/templates/local-wrapper/Makefile.ejs

@@ -0,0 +1,44 @@
+# Makefile — local CI parity façade for <%= projectName %>
+# Generated by arbiter (INV-87). Targets mirror CI workflow jobs.
+# POSIX make only — no GNU extensions.
+
+.PHONY: help check gate full ci simulate-nightly simulate-weekly<% if (typeof enableEvidenceHarness === 'undefined' || enableEvidenceHarness !== false) { %> evidence<% } %> clean
+
+help:
+	@echo "Targets:"
+	@echo "  check            Run fast local checks (lint + format + unit tests)"
+	@echo "  gate             Run full local gate (L1 + L2)"
+	@echo "  ci               Alias for gate (CI parity surface)"
+	@echo "  full             Run all checks including coverage"
+	@echo "  simulate-nightly Simulate nightly CI run (W10 — not yet implemented)"
+	@echo "  simulate-weekly  Simulate weekly CI run (W10 — not yet implemented)"
+<% if (typeof enableEvidenceHarness === 'undefined' || enableEvidenceHarness !== false) { -%>
+	@echo "  evidence         Finalize evidence artifacts"
+<% } -%>
+	@echo "  clean            Remove transient gate artifacts"
+
+check:
+	node scripts/check-all.mjs check
+
+gate:
+	node scripts/check-all.mjs gate
+
+ci: gate
+
+full:
+	node scripts/check-all.mjs full
+
+simulate-nightly:
+	node scripts/check-all.mjs simulate-nightly
+
+simulate-weekly:
+	node scripts/check-all.mjs simulate-weekly
+
+<% if (typeof enableEvidenceHarness === 'undefined' || enableEvidenceHarness !== false) { -%>
+evidence:
+	node scripts/done-evidence.mjs
+
+<% } -%>
+clean:
+	rm -f .arbiter/gate-pass.json
+	rm -f .arbiter/evidence/*.tmp

package/dist/templates/local-wrapper/run.sh.ejs

@@ -0,0 +1,5 @@
+#!/bin/sh
+# run.sh — thin shim so hooks, CI, and contributors call the same command.
+# Generated by arbiter (INV-87). Pass any check-all.mjs subcommand as $1.
+set -e
+exec node scripts/check-all.mjs "$@"

package/dist/templates/middleware/410-gone-handler.ts.ejs

@@ -0,0 +1,41 @@
+import type { Request, Response } from "express";
+
+export interface GoneResponse {
+  status: 410;
+  error: "Gone";
+  message: string;
+  removedAt?: string;
+  successorUrl?: string;
+}
+
+/**
+ * Handler for permanently removed API endpoints (HTTP 410 Gone).
+ * Use instead of 404 when an endpoint was intentionally decommissioned.
+ * Optionally points clients to the successor resource via Link header.
+ */
+export function goneHandler(options?: {
+  message?: string;
+  removedAt?: string;
+  successorUrl?: string;
+}) {
+  return (_req: Request, res: Response): void => {
+    if (options?.successorUrl) {
+      res.setHeader(
+        "Link",
+        `<${options.successorUrl}>; rel="successor-version"`,
+      );
+    }
+
+    const body: GoneResponse = {
+      status: 410,
+      error: "Gone",
+      message:
+        options?.message ??
+        "This endpoint has been permanently removed. Please consult the API changelog.",
+      ...(options?.removedAt ? { removedAt: options.removedAt } : {}),
+      ...(options?.successorUrl ? { successorUrl: options.successorUrl } : {}),
+    };
+
+    res.status(410).json(body);
+  };
+}

package/dist/templates/middleware/correlation-id.ts.ejs

@@ -0,0 +1,32 @@
+import { randomUUID } from "node:crypto";
+import type { Request, Response, NextFunction } from "express";
+
+declare module "express-serve-static-core" {
+  interface Request {
+    correlationId: string;
+  }
+}
+
+/**
+ * Correlation ID middleware.
+ * Reads X-Correlation-ID from incoming request headers; generates a UUID v4
+ * if absent. Attaches the value to req.correlationId and echoes it back in
+ * the response X-Correlation-ID header.
+ */
+export function correlationIdMiddleware(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  const incoming =
+    req.headers["x-correlation-id"] ??
+    req.headers["X-Correlation-ID"];
+
+  const correlationId = Array.isArray(incoming)
+    ? (incoming[0] ?? randomUUID())
+    : (incoming ?? randomUUID());
+
+  req.correlationId = correlationId;
+  res.setHeader("X-Correlation-ID", correlationId);
+  next();
+}

package/dist/templates/middleware/deprecation.ts.ejs

@@ -0,0 +1,45 @@
+import type { Request, Response, NextFunction } from "express";
+
+export interface DeprecationOptions {
+  sunsetDate: Date;
+  successorUrl?: string;
+  link?: string;
+}
+
+/**
+ * RFC 8594-compliant deprecation middleware.
+ * Sets Sunset, Deprecation, and Link headers on every response.
+ * Mount per-route or globally for versioned APIs.
+ */
+export function deprecationMiddleware(options: DeprecationOptions) {
+  return (_req: Request, res: Response, next: NextFunction): void => {
+    res.setHeader("Deprecation", "true");
+    res.setHeader("Sunset", options.sunsetDate.toUTCString());
+
+    if (options.successorUrl) {
+      res.setHeader(
+        "Link",
+        `<${options.successorUrl}>; rel="successor-version"`,
+      );
+    } else if (options.link) {
+      res.setHeader("Link", options.link);
+    }
+
+    next();
+  };
+}
+
+/**
+ * Build a deprecation middleware bound to a fixed sunset date string.
+ * Accepts ISO-8601 strings ("2025-12-31") or Date objects.
+ */
+export function deprecateEndpoint(
+  sunsetDateOrString: Date | string,
+  successorUrl?: string,
+) {
+  const sunsetDate =
+    sunsetDateOrString instanceof Date
+      ? sunsetDateOrString
+      : new Date(sunsetDateOrString);
+  return deprecationMiddleware({ sunsetDate, successorUrl });
+}

package/dist/templates/middleware/error-handler.ts.ejs

@@ -0,0 +1,73 @@
+import type { Request, Response, NextFunction } from "express";
+
+/**
+ * RFC 7807 Problem Details shape.
+ * https://datatracker.ietf.org/doc/html/rfc7807
+ */
+export interface ProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  correlationId: string;
+}
+
+export class AppError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly title: string,
+    public readonly detail?: string,
+    public readonly type = "about:blank",
+  ) {
+    super(title);
+    this.name = "AppError";
+  }
+}
+
+/**
+ * Express error-handling middleware that produces RFC 7807 Problem Details
+ * responses. Attach as the last middleware in the chain.
+ *
+ * Never exposes stack traces to clients — logs internally only.
+ */
+export function errorHandler(
+  err: unknown,
+  req: Request,
+  res: Response,
+  _next: NextFunction,
+): void {
+  const correlationId =
+    (req as Request & { correlationId?: string }).correlationId ?? "unknown";
+
+  if (err instanceof AppError) {
+    const body: ProblemDetails = {
+      type: err.type,
+      title: err.title,
+      status: err.status,
+      detail: err.detail,
+      instance: req.path,
+      correlationId,
+    };
+    res
+      .status(err.status)
+      .contentType("application/problem+json")
+      .json(body);
+    return;
+  }
+
+  // Internal server-side error log, never sent to the client; swap for your
+  // project's logger (#1840 F4 tranche-3: the static-analysis gate's no-console
+  // rule flagged arbiter's OWN middleware — the disable directive below must be
+  // the LINE IMMEDIATELY BEFORE the call, not preceded by more comment lines.
+  // eslint-disable-next-line no-console
+  console.error("[errorHandler] unhandled error:", err);
+  const body: ProblemDetails = {
+    type: "about:blank",
+    title: "Internal Server Error",
+    status: 500,
+    instance: req.path,
+    correlationId,
+  };
+  res.status(500).contentType("application/problem+json").json(body);
+}

package/dist/templates/middleware/payload-size-limit.ts.ejs

@@ -0,0 +1,51 @@
+// Payload size limit middleware — Express/Node.js
+//
+// Usage:
+//   import { payloadSizeLimit } from "./middleware/payload-size-limit.js";
+//   app.use(payloadSizeLimit());           // default: 1 MiB
+//   app.use(payloadSizeLimit(512 * 1024)); // custom: 512 KiB
+//
+// Override at runtime via environment variable:
+//   MAX_REQUEST_BYTES=2097152 node server.js
+//
+// Known limitation:
+//   This middleware checks the Content-Length request header to enforce the
+//   limit. Requests that use Transfer-Encoding: chunked carry no Content-Length
+//   header — the body arrives in frames with no declared total size. Chunked
+//   requests are NOT blocked by this middleware. Full stream-level limiting
+//   requires wrapping the IncomingMessage socket or using an
+//   http.IncomingMessage transform (deferred).
+
+import type { Request, Response, NextFunction } from "express";
+
+const DEFAULT_MAX_BYTES = 1_048_576; // 1 MiB
+
+function resolvedMaxBytes(): number {
+  const n = Number(process.env.MAX_REQUEST_BYTES ?? DEFAULT_MAX_BYTES);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_BYTES;
+}
+
+export function payloadSizeLimit(
+  maxBytes: number = resolvedMaxBytes(),
+): (req: Request, res: Response, next: NextFunction) => void {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const contentLength = req.headers["content-length"];
+    if (contentLength !== undefined && Number(contentLength) > maxBytes) {
+      const rawCorrelationId = req.headers["x-correlation-id"];
+      const correlationId =
+        (Array.isArray(rawCorrelationId)
+          ? rawCorrelationId[0]
+          : rawCorrelationId) ?? "unknown";
+      res.status(413).contentType("application/problem+json").json({
+        type: "https://errors.example.com/problem-type/payload-too-large",
+        title: "Payload Too Large",
+        status: 413,
+        detail: `Request body exceeds the ${maxBytes}-byte limit.`,
+        instance: req.path,
+        correlationId,
+      });
+      return;
+    }
+    next();
+  };
+}

package/dist/templates/mutation/README.md.ejs

@@ -0,0 +1,67 @@
+# Mutation Testing — L3 Hard Gate
+
+Enforces INV-30: tests must have genuine fault-detection power (85% mutation score).
+
+## Per-Stack Setup
+
+<% if (language === 'java' && buildTool === 'gradle') { %>
+### Java (Gradle)
+
+`gradle/pitest.gradle` has been generated. Add to your `build.gradle`:
+
+```groovy
+apply from: 'gradle/pitest.gradle'
+```
+
+Run: `./gradlew pitest`
+<% } %><% if (language === 'java' && buildTool === 'maven') { %>
+### Java (Maven)
+
+See `docs/mutation/pitest-maven-setup.md` for the `<plugin>` block to add to `pom.xml`.
+
+Run: `mvn verify -Ppitest`
+<% } %><% if (language === 'typescript') { %>
+### TypeScript
+
+Install peer deps:
+
+```bash
+npm i -D @stryker-mutator/core @stryker-mutator/vitest-runner
+```
+
+`stryker.conf.json` has been generated at the project root.
+
+Run: `npx stryker run`
+<% } %><% if (language === 'rust') { %>
+### Rust (beta — requires `--accept-beta-tools`)
+
+Install cargo-mutants:
+
+```bash
+cargo install cargo-mutants
+```
+
+`cargo-mutants.toml` and `scripts/parse-mutants.mjs` have been generated.
+
+Run: `cargo mutants --config cargo-mutants.toml 2>&1 | node scripts/parse-mutants.mjs --threshold <%= mutationThreshold %>`
+<% } %><% if (language === 'python') { %>
+### Python (beta — requires `--accept-beta-tools`)
+
+Install mutmut:
+
+```bash
+pip install mutmut
+```
+
+`mutmut-config.toml` and `scripts/parse-mutmut.py` have been generated.
+
+Run: `mutmut run && python scripts/parse-mutmut.py --threshold <%= mutationThreshold %>`
+<% } %>
+
+## Threshold
+
+**<%= mutationThreshold %>% mutation score** required. Enforced by `node scripts/check-all.mjs L2`.
+
+## Disabling
+
+Lower governance to L2 (`arbiter init --level=L2`) to revert to advisory-only mutation guidance.

package/dist/templates/mutation/cargo-mutants.toml.ejs

@@ -0,0 +1,9 @@
+# cargo-mutants configuration — L3 mutation gate (beta)
+# Run: cargo mutants --config cargo-mutants.toml 2>&1 | node scripts/parse-mutants.mjs --threshold <%= mutationThreshold %>
+
+examine_globs = [
+    "src/domain/**/*.rs",
+    "src/application/**/*.rs"
+]
+
+minimum_test_timeout = 60

package/dist/templates/mutation/mutmut-config.toml.ejs

@@ -0,0 +1,7 @@
+# mutmut configuration — L3 mutation gate (beta)
+# Run: mutmut run && python scripts/parse-mutmut.py --threshold <%= mutationThreshold %>
+
+paths_to_mutate = "src/<%= modulePath %>/"
+runner = "pytest -x -q"
+tests_dir = "tests/"
+timeout_per_mutant = 120

package/dist/templates/mutation/parse-mutants.mjs.ejs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Parses cargo-mutants stdout and fails if caught% < threshold.
+// Tolerates cargo-mutants 24.x and 25.x stdout variants.
+// Usage: cargo mutants ... 2>&1 | node scripts/parse-mutants.mjs --threshold 85
+
+import { createInterface } from "node:readline";
+
+const thresholdArg = process.argv.indexOf("--threshold");
+const threshold = thresholdArg !== -1 ? Number(process.argv[thresholdArg + 1]) : <%= mutationThreshold %>;
+
+let caught = 0;
+let total = 0;
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on("line", (line) => {
+  // cargo-mutants 24.x: "42 mutants tested: 38 caught, 4 missed, 0 unviable"
+  // cargo-mutants 25.x: "Caught 38/42 (90.5%) mutants"
+  const v24 = line.match(/(\d+)\s+mutants tested:\s+(\d+)\s+caught/);
+  if (v24) {
+    total = Number(v24[1]);
+    caught = Number(v24[2]);
+    return;
+  }
+  const v25 = line.match(/Caught\s+(\d+)\/(\d+)/);
+  if (v25) {
+    caught = Number(v25[1]);
+    total = Number(v25[2]);
+  }
+});
+
+rl.on("close", () => {
+  if (total === 0) {
+    console.error("parse-mutants: no mutation results found in cargo-mutants output");
+    process.exit(1);
+  }
+  const pct = Math.round((caught / total) * 100);
+  console.log(`Mutation score: ${caught}/${total} (${pct}%) — threshold: ${threshold}%`);
+  if (pct < threshold) {
+    console.error(`FAIL: mutation score ${pct}% is below threshold ${threshold}%`);
+    process.exit(1);
+  }
+  console.log("PASS: mutation score meets threshold");
+});