@getarbiter/cli 0.5.0

package/dist/templates/mutation/parse-mutmut.py.ejs

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Parses mutmut results and fails if caught% < threshold."""
+
+import subprocess
+import sys
+import re
+
+
+def main() -> None:
+    threshold_arg = next(
+        (int(sys.argv[i + 1]) for i, a in enumerate(sys.argv) if a == "--threshold"),
+        <%= mutationThreshold %>,
+    )
+
+    result = subprocess.run(
+        ["mutmut", "results"],
+        capture_output=True,
+        text=True,
+    )
+    output = result.stdout + result.stderr
+
+    survived = len(re.findall(r"SURVIVED", output))
+    killed = len(re.findall(r"KILLED", output))
+    total = killed + survived
+
+    if total == 0:
+        print("parse-mutmut: no mutation results found", file=sys.stderr)
+        sys.exit(1)
+
+    pct = round((killed / total) * 100)
+    print(f"Mutation score: {killed}/{total} ({pct}%) — threshold: {threshold_arg}%")
+
+    if pct < threshold_arg:
+        print(
+            f"FAIL: mutation score {pct}% is below threshold {threshold_arg}%",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    print("PASS: mutation score meets threshold")
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/mutation/pitest-l2-setup.md.ejs

@@ -0,0 +1,66 @@
+# Pitest (PIT Mutation Testing) Setup — L2 Advisory Guide
+
+> **L2 projects:** use this guide to configure pitest manually.
+> **L3 projects:** arbiter emits an enforced `gradle/pitest.gradle` fragment automatically — see AGENTS.md §Mutation Testing.
+
+Mutation testing enforces INV-30: tests must have genuine fault-detection power, not just line coverage.
+Thresholds: **80% mutation score**, **85% line coverage**. Target: domain and application layers only.
+
+## Maven
+
+Add to your `pom.xml` inside `<build><plugins>`:
+
+```xml
+<plugin>
+  <groupId>org.pitest</groupId>
+  <artifactId>pitest-maven</artifactId>
+  <version>1.15.0</version>
+  <configuration>
+    <targetClasses>
+      <param><%= locals.basePackage ? locals.basePackage + '.domain.*' : '*.domain.*' %></param>
+      <param><%= locals.basePackage ? locals.basePackage + '.application.*' : '*.application.*' %></param>
+    </targetClasses>
+    <targetTests>
+      <param><%= locals.basePackage ? locals.basePackage + '.*Test' : '*.*Test' %></param>
+    </targetTests>
+    <mutationThreshold>80</mutationThreshold>
+    <coverageThreshold>85</coverageThreshold>
+    <outputFormats>
+      <outputFormat>XML</outputFormat>
+      <outputFormat>HTML</outputFormat>
+    </outputFormats>
+    <timestampedReports>false</timestampedReports>
+  </configuration>
+</plugin>
+```
+
+Run: `mvn org.pitest:pitest-maven:mutationCoverage`
+
+## Gradle
+
+Add to your `build.gradle`:
+
+```groovy
+plugins {
+  id 'info.solidsoft.pitest' version '1.15.0'
+}
+
+pitest {
+  targetClasses = ['<%= locals.basePackage ? locals.basePackage + '.domain.*' : '*.domain.*' %>', '<%= locals.basePackage ? locals.basePackage + '.application.*' : '*.application.*' %>']
+  mutationThreshold = 80
+  coverageThreshold = 85
+  outputFormats = ['XML', 'HTML']
+  timestampedReports = false
+}
+```
+
+Run: `./gradlew pitest`
+
+## CI Gate
+
+The `check-all.mjs L2` gate runs pitest automatically. Builds fail if mutation score drops below 80%.
+
+## Why mutation testing?
+
+Line coverage tells you which lines ran. Mutation testing tells you if tests actually verify behavior.
+A test that asserts nothing can achieve 100% coverage. A mutant that survives means a test gap.

package/dist/templates/mutation/pitest-maven-setup.md.ejs

@@ -0,0 +1,64 @@
+# PIT Mutation Testing — Maven Setup (L3 hard gate)
+
+Add the following plugin to your `pom.xml` inside `<build><plugins>`:
+
+```xml
+<plugin>
+    <groupId>org.pitest</groupId>
+    <artifactId>pitest-maven</artifactId>
+    <version>1.15.0</version>
+    <dependencies>
+        <dependency>
+            <groupId>org.pitest</groupId>
+            <artifactId>pitest-junit5-plugin</artifactId>
+            <version>1.2.1</version>
+        </dependency>
+    </dependencies>
+    <configuration>
+        <targetClasses>
+            <param><%= basePackage %>.domain.*</param>
+            <param><%= basePackage %>.application.service.*</param>
+            <param><%= basePackage %>.application.usecase.*</param>
+        </targetClasses>
+        <mutationThreshold><%= mutationThreshold %></mutationThreshold>
+        <coverageThreshold><%= mutationThreshold %></coverageThreshold>
+        <timeoutFactor>2.0</timeoutFactor>
+        <timeoutConstant>10000</timeoutConstant>
+        <avoidCallsTo>
+            <avoidCallsTo>java.util.logging</avoidCallsTo>
+            <avoidCallsTo>org.apache.log4j</avoidCallsTo>
+            <avoidCallsTo>org.slf4j</avoidCallsTo>
+        </avoidCallsTo>
+        <outputFormats>
+            <outputFormat>XML</outputFormat>
+            <outputFormat>HTML</outputFormat>
+        </outputFormats>
+        <withHistory>true</withHistory>
+        <failWhenNoMutations>true</failWhenNoMutations>
+    </configuration>
+    <executions>
+        <execution>
+            <id>pitest</id>
+            <phase>verify</phase>
+            <goals><goal>mutationCoverage</goal></goals>
+        </execution>
+    </executions>
+</plugin>
+```
+
+Run mutation tests:
+
+```bash
+mvn verify -Ppitest
+```
+
+Or bind to a profile in your `pom.xml`:
+
+```xml
+<profiles>
+    <profile>
+        <id>pitest</id>
+        <!-- plugin already bound to verify phase above -->
+    </profile>
+</profiles>
+```

package/dist/templates/mutation/pitest.gradle.ejs

@@ -0,0 +1,23 @@
+// PIT mutation testing — L3 hard gate (INV-30)
+// Wired automatically: arbiter declares the info.solidsoft.pitest plugin in the
+// root build's plugins block and applies this script from the arbiter-managed
+// block (a plugins {} block here would be ILLEGAL — Gradle forbids the plugins
+// DSL inside applied scripts).
+// Run: ./gradlew pitest
+
+pitest {
+    targetClasses = [
+        '<%= basePackage %>.domain.*',
+        '<%= basePackage %>.application.service.*',
+        '<%= basePackage %>.application.usecase.*'
+    ]
+    mutationThreshold = <%= mutationThreshold %>
+    coverageThreshold = <%= mutationThreshold %>
+    timeoutFactor = 2.0
+    timeoutConstInMillis = 10000
+    avoidCallsTo = ['java.util.logging', 'org.apache.log4j', 'org.slf4j']
+    outputFormats = ['XML', 'HTML']
+    withHistory = true
+    junit5PluginVersion = '1.2.1'
+    failWhenNoMutations = true
+}

package/dist/templates/mutation/stryker.conf.json.ejs

@@ -0,0 +1,17 @@
+{
+  "testRunner": "vitest",
+  "mutate": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
+  ],
+  "thresholds": {
+    "high": 90,
+    "low": <%= mutationThreshold %>,
+    "break": <%= mutationThreshold %>
+  },
+  "coverageAnalysis": "perTest",
+  "timeoutMS": 60000,
+  "concurrency": 2,
+  "reporters": ["progress", "clear-text", "html"]
+}

package/dist/templates/observability/setup.md.ejs

@@ -0,0 +1,495 @@
+# Observability Setup — <%= projectName %>
+
+<!-- arbiter-managed: observability (#725) -->
+
+> Provider: **<%= observability.provider %>**
+> Structured logging with `traceId` is required on all log lines (INV).
+
+---
+
+## Structured Logging Requirement
+
+Every log statement **must** include a `traceId` field for distributed tracing correlation.
+
+```typescript
+// Required log shape (all providers)
+logger.info({ traceId: ctx.traceId, msg: 'request completed', status: 200 })
+```
+
+---
+<% const _provider = observability.provider; %><% if (_provider === 'stdout-minimal') { %>
+
+## Stdout Minimal — Pino / Logrus
+
+Minimal footprint: structured JSON to stdout, Prometheus client library only. No Grafana, no log aggregation.
+
+### Install
+
+```bash
+# Node.js
+npm install pino prom-client
+
+# Go
+go get github.com/sirupsen/logrus github.com/prometheus/client_golang/prometheus
+```
+
+### Pino configuration (Node.js)
+
+```typescript
+import pino from 'pino'
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL ?? 'info',
+  base: { service: '<%= projectName %>' },
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+})
+```
+
+### Prometheus metrics endpoint
+
+```typescript
+import { register } from 'prom-client'
+import { collectDefaultMetrics } from 'prom-client'
+
+collectDefaultMetrics({ prefix: '<%= projectName %>_' })
+
+app.get('/metrics', async (_req, res) => {
+  res.set('Content-Type', register.contentType)
+  res.send(await register.metrics())
+})
+```
+
+### Environment variables
+
+```env
+LOG_LEVEL=info
+METRICS_PORT=9090
+```
+<% } else if (_provider === 'signoz') { %>
+
+## SigNoz — Self-hosted All-in-One (ClickHouse-based)
+
+Single-node metrics + logs + traces. Recommended for small-to-medium teams wanting no SaaS dependency.
+
+### docker-compose.signoz.yml
+
+```yaml
+version: '3.8'
+services:
+  signoz:
+    image: signoz/signoz:latest
+    container_name: signoz
+    ports:
+      - '3301:3301'   # UI
+      - '4317:4317'   # OTLP gRPC
+      - '4318:4318'   # OTLP HTTP
+    volumes:
+      - signoz-data:/var/lib/clickhouse
+    environment:
+      - SIGNOZ_LOCAL_DB_PATH=/var/lib/clickhouse/signoz.db
+    restart: unless-stopped
+
+volumes:
+  signoz-data:
+```
+
+### OpenTelemetry SDK setup (Node.js)
+
+```bash
+npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-otlp-grpc
+```
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-otlp-grpc'
+
+const sdk = new NodeSDK({
+  serviceName: '<%= projectName %>',
+  traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4317' }),
+  instrumentations: [getNodeAutoInstrumentations()],
+})
+sdk.start()
+```
+
+### Environment variables
+
+```env
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_SERVICE_NAME=<%= projectName %>
+```
+<% } else if (_provider === 'openobserve') { %>
+
+## OpenObserve — Self-hosted Single Binary
+
+Lightweight alternative to SigNoz. Single Go binary, S3-compatible storage backend.
+
+### docker-compose.openobserve.yml
+
+```yaml
+version: '3.8'
+services:
+  openobserve:
+    image: public.ecr.aws/zinclabs/openobserve:latest
+    container_name: openobserve
+    ports:
+      - '5080:5080'   # UI + API
+      - '5081:5081'   # gRPC OTLP
+    environment:
+      - ZO_ROOT_USER_EMAIL=admin@<%= projectName %>.local
+      - ZO_ROOT_USER_PASSWORD=changeme
+      - ZO_DATA_DIR=/data
+    volumes:
+      - openobserve-data:/data
+    restart: unless-stopped
+
+volumes:
+  openobserve-data:
+```
+
+### Log shipping (Vector)
+
+```yaml
+# vector.yaml
+sources:
+  app_logs:
+    type: file
+    include:
+      - /var/log/<%= projectName %>/*.log
+
+sinks:
+  openobserve:
+    type: http
+    uri: http://localhost:5080/api/default/<%= projectName %>/_json
+    auth:
+      strategy: basic
+      user: admin@<%= projectName %>.local
+      password: changeme
+```
+
+### Environment variables
+
+```env
+OO_ENDPOINT=http://localhost:5080
+OO_ORG=default
+OO_STREAM=<%= projectName %>
+```
+<% } else if (_provider === 'victoria-vector-quickwit') { %>
+
+## VictoriaMetrics + Vector + Quickwit — Lightweight Self-host Stack
+
+Prometheus-compatible metrics (VictoriaMetrics), log routing (Vector), fast log search (Quickwit).
+
+### docker-compose.vm-stack.yml
+
+```yaml
+version: '3.8'
+services:
+  victoriametrics:
+    image: victoriametrics/victoria-metrics:stable
+    container_name: victoriametrics
+    ports:
+      - '8428:8428'   # Prometheus-compatible API
+    volumes:
+      - vm-data:/storage
+    command:
+      - --storageDataPath=/storage
+      - --retentionPeriod=30d
+    restart: unless-stopped
+
+  vector:
+    image: timberio/vector:latest-alpine
+    container_name: vector
+    volumes:
+      - ./vector.yaml:/etc/vector/vector.yaml:ro
+    depends_on: [victoriametrics, quickwit]
+    restart: unless-stopped
+
+  quickwit:
+    image: quickwit/quickwit:latest
+    container_name: quickwit
+    ports:
+      - '7280:7280'   # UI + API
+    volumes:
+      - quickwit-data:/quickwit/qwdata
+    command: run
+    restart: unless-stopped
+
+volumes:
+  vm-data:
+  quickwit-data:
+```
+
+### Prometheus scrape config (VictoriaMetrics)
+
+```yaml
+# prometheus.yml — Victoria accepts standard Prometheus format
+scrape_configs:
+  - job_name: '<%= projectName %>'
+    static_configs:
+      - targets: ['host.docker.internal:9090']
+```
+
+### Environment variables
+
+```env
+VICTORIAMETRICS_URL=http://localhost:8428
+QUICKWIT_URL=http://localhost:7280
+VECTOR_CONFIG=./vector.yaml
+```
+<% } else if (_provider === 'prom-grafana-loki-jaeger') { %>
+
+## Prometheus + Grafana + Loki + Jaeger — Classic Stack
+
+Full-featured, battle-tested observability. Heavyweight — recommended for mature ops teams.
+
+### docker-compose.classic.yml
+
+```yaml
+version: '3.8'
+services:
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: prometheus
+    ports:
+      - '9091:9090'
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus-data:/prometheus
+    restart: unless-stopped
+
+  grafana:
+    image: grafana/grafana:latest
+    container_name: grafana
+    ports:
+      - '3000:3000'
+    environment:
+      - GF_SECURITY_ADMIN_PASSWORD=changeme
+    volumes:
+      - grafana-data:/var/lib/grafana
+    depends_on: [prometheus, loki, jaeger]
+    restart: unless-stopped
+
+  loki:
+    image: grafana/loki:latest
+    container_name: loki
+    ports:
+      - '3100:3100'
+    volumes:
+      - loki-data:/loki
+    restart: unless-stopped
+
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    container_name: jaeger
+    ports:
+      - '16686:16686'   # UI
+      - '14268:14268'   # HTTP collector
+      - '6831:6831/udp' # Thrift compact
+    restart: unless-stopped
+
+volumes:
+  prometheus-data:
+  grafana-data:
+  loki-data:
+```
+
+### Prometheus scrape config
+
+```yaml
+# prometheus.yml
+scrape_configs:
+  - job_name: '<%= projectName %>'
+    static_configs:
+      - targets: ['host.docker.internal:9090']
+    scrape_interval: 15s
+```
+
+### Environment variables
+
+```env
+PROMETHEUS_URL=http://localhost:9091
+GRAFANA_URL=http://localhost:3000
+LOKI_URL=http://localhost:3100
+JAEGER_ENDPOINT=http://localhost:14268/api/traces
+```
+<% } else if (_provider === 'saas-sentry') { %>
+
+## Sentry — SaaS Error Monitoring
+
+Best for error-first observability. Free tier available.
+
+### Install
+
+```bash
+npm install @sentry/node @sentry/tracing
+```
+
+### Initialization
+
+```typescript
+import * as Sentry from '@sentry/node'
+import * as Tracing from '@sentry/tracing'
+
+Sentry.init({
+  dsn: process.env.SENTRY_DSN,
+  environment: process.env.NODE_ENV,
+  release: '<%= projectName %>@' + process.env.npm_package_version,
+  tracesSampleRate: 1.0,
+  integrations: [new Tracing.Integrations.Http({ tracing: true })],
+})
+
+// Structured logging with traceId
+const traceId = Sentry.getCurrentHub().getScope()?.getSpan()?.toTraceparent() ?? 'none'
+logger.info({ traceId, msg: 'request completed' })
+```
+
+### Environment variables
+
+```env
+SENTRY_DSN=https://<key>@o<org>.ingest.sentry.io/<project>
+SENTRY_ENVIRONMENT=production
+```
+<% } else if (_provider === 'saas-datadog') { %>
+
+## Datadog — SaaS APM + Logs + Metrics
+
+Enterprise-grade. Unified platform — APM, infrastructure, logs, RUM.
+
+### Install
+
+```bash
+npm install dd-trace
+```
+
+### Initialization (must be first import)
+
+```typescript
+// tracing.ts — import before any other module
+import tracer from 'dd-trace'
+
+tracer.init({
+  service: '<%= projectName %>',
+  env: process.env.NODE_ENV,
+  version: process.env.npm_package_version,
+  logInjection: true,  // injects traceId into Pino/Winston logs
+})
+
+export default tracer
+```
+
+### Structured log correlation
+
+```typescript
+import { createLogger } from 'winston'
+// With logInjection=true, dd-trace injects dd.trace_id automatically
+// traceId is available as dd.trace_id in log output
+```
+
+### Environment variables
+
+```env
+DD_API_KEY=<your-datadog-api-key>
+DD_SITE=datadoghq.com
+DD_SERVICE=<%= projectName %>
+DD_ENV=production
+```
+<% } else if (_provider === 'saas-axiom') { %>
+
+## Axiom — SaaS Logs + Events
+
+Excellent for log/event analytics. Generous free tier (500GB/month).
+
+### Install
+
+```bash
+npm install @axiomhq/winston
+# or
+npm install @axiomhq/pino
+```
+
+### Pino transport
+
+```typescript
+import pino from 'pino'
+
+export const logger = pino({
+  level: 'info',
+  transport: {
+    target: '@axiomhq/pino',
+    options: {
+      dataset: process.env.AXIOM_DATASET,
+      token: process.env.AXIOM_TOKEN,
+    },
+  },
+  base: { service: '<%= projectName %>' },
+})
+
+// Every log line includes traceId
+logger.info({ traceId: ctx.traceId, msg: 'request completed' })
+```
+
+### Environment variables
+
+```env
+AXIOM_TOKEN=xaat-<your-token>
+AXIOM_DATASET=<%= projectName %>-logs
+```
+<% } else if (_provider === 'saas-betterstack') { %>
+
+## BetterStack — SaaS Logs + Uptime
+
+Logs + uptime monitoring in one. Good for teams wanting incident correlation.
+
+### Install
+
+```bash
+npm install @logtail/pino
+```
+
+### Pino transport
+
+```typescript
+import pino from 'pino'
+import { Logtail } from '@logtail/node'
+import { LogtailTransport } from '@logtail/pino'
+
+const logtail = new Logtail(process.env.BETTERSTACK_SOURCE_TOKEN!)
+
+export const logger = pino({ level: 'info' }, new LogtailTransport(logtail))
+
+// Every log line includes traceId
+logger.info({ traceId: ctx.traceId, msg: 'request completed' })
+```
+
+### Environment variables
+
+```env
+BETTERSTACK_SOURCE_TOKEN=<your-source-token>
+```
+<% } else { %>
+
+## Unknown provider — `<%= observability.provider %>`
+
+arbiter has no setup recipe for the configured `observability.provider`. This usually
+means a typo or a value from a newer arbiter version. No provider-specific instructions
+could be emitted.
+
+- Re-run the wizard (`arbiter init`) and pick a supported provider, or
+- Fix `observability.provider` in `arbiter.json` to a known value, then run `arbiter update`.
+
+<% } %>
+
+---
+
+## Checklist
+
+- [ ] Provider configured and `docker compose up` (self-host) or SDK initialized (SaaS)
+- [ ] Every log line includes `traceId` field
+- [ ] `/metrics` endpoint returns Prometheus-format metrics (self-host only)
+- [ ] Alerting rule configured for error-rate >1% and p99 latency >500ms
+- [ ] Dashboard imported or configured in provider UI
+
+_Generated by arbiter. Re-run `arbiter update` after changing `observability.provider`._