@1aboveio/skills 0.10.0

package/skills/engineering/e2e-test/scripts/detect-routes-fastapi.py

@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""
+Detect all FastAPI routes via static analysis and compare against endpoint manifest.
+Fails CI if any route exists in the app but not in the manifest.
+
+Scans Python files for:
+  - @router.get("/path")    @router.post("/path")
+  - @app.get("/path")       @app.post("/path")
+  - @api.get("/path")       @api.post("/path")
+  - app.include_router(router, prefix="/prefix")
+
+Handles:
+  - Decorator-based route definitions
+  - Router prefixes from include_router calls
+  - String literals and f-strings (partial — extracts static prefix)
+  - Commented-out routes (skipped)
+
+Usage:
+    python detect-routes-fastapi.py [options]
+
+Options:
+    --src-dir <path>        Path to scan for Python files (default: .)
+    --manifest <path>       Path to endpoint-manifest.json (default: tests/e2e/endpoint-manifest.json)
+    --exclude <pattern>     Glob pattern to exclude (repeatable, default: tests/*, **/test_*)
+    --strict                Exit 1 if any route missing from manifest (default)
+    --no-strict             Only warn, don't fail
+
+Exit codes:
+    0 = all routes accounted for
+    1 = routes missing from manifest (strict mode)
+"""
+
+import argparse
+import ast
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from fnmatch import fnmatch
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Detect FastAPI routes")
+    parser.add_argument("--src-dir", default=".", help="Source directory to scan")
+    parser.add_argument(
+        "--manifest",
+        default="tests/e2e/endpoint-manifest.json",
+        help="Path to endpoint manifest",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=None,
+        help="Glob patterns to exclude (repeatable)",
+    )
+    parser.add_argument(
+        "--strict",
+        dest="strict",
+        action="store_true",
+        default=True,
+        help="Fail on missing routes (default)",
+    )
+    parser.add_argument(
+        "--no-strict", dest="strict", action="store_false", help="Warn only"
+    )
+    return parser.parse_args()
+
+
+# ─── Route extraction ────────────────────────────────────────
+
+HTTP_METHODS = {"get", "post", "put", "delete", "patch", "head", "options"}
+
+# Pattern: @something.method("path") or @something.method("path", ...)
+ROUTE_DECORATOR_RE = re.compile(
+    r"^\s*@(\w+)\.(get|post|put|delete|patch|head|options)\(\s*"
+    r'["\']([^"\']*)["\']',
+    re.MULTILINE,
+)
+
+# Pattern: app.include_router(var, prefix="path")
+INCLUDE_ROUTER_RE = re.compile(
+    r'\.include_router\(\s*(\w+)(?:.*?prefix\s*=\s*["\']([^"\']*)["\'])?',
+    re.DOTALL,
+)
+
+
+def extract_routes_from_file(filepath: str) -> list[dict]:
+    """Extract route definitions from a Python file using regex.
+
+    Returns list of { method, path, file, line }
+    """
+    routes = []
+    try:
+        content = Path(filepath).read_text(encoding="utf-8")
+    except Exception:
+        return routes
+
+    lines = content.split("\n")
+    for i, line in enumerate(lines, 1):
+        # Skip comments
+        stripped = line.lstrip()
+        if stripped.startswith("#"):
+            continue
+
+        match = ROUTE_DECORATOR_RE.match(stripped)
+        if match:
+            _var_name, method, path = match.groups()
+            routes.append(
+                {
+                    "method": method.upper(),
+                    "path": path,
+                    "file": filepath,
+                    "line": i,
+                    "router_var": _var_name,
+                }
+            )
+
+    return routes
+
+
+def find_router_prefixes(filepath: str) -> dict[str, str]:
+    """Find include_router calls and their prefixes.
+
+    Returns { router_var_name: prefix }
+    """
+    prefixes = {}
+    try:
+        content = Path(filepath).read_text(encoding="utf-8")
+    except Exception:
+        return prefixes
+
+    for match in INCLUDE_ROUTER_RE.finditer(content):
+        var_name = match.group(1)
+        prefix = match.group(2) or ""
+        if prefix:
+            prefixes[var_name] = prefix
+
+    return prefixes
+
+
+def scan_directory(src_dir: str, excludes: list[str]) -> tuple[list[dict], dict]:
+    """Scan all Python files for routes and router prefixes."""
+    all_routes = []
+    all_prefixes = {}
+
+    for root, dirs, files in os.walk(src_dir):
+        # Skip common non-source directories
+        dirs[:] = [
+            d
+            for d in dirs
+            if d not in {"__pycache__", ".git", "node_modules", ".venv", "venv"}
+        ]
+
+        for fname in files:
+            if not fname.endswith(".py"):
+                continue
+
+            filepath = os.path.join(root, fname)
+            rel_path = os.path.relpath(filepath, src_dir)
+
+            # Check excludes
+            if any(fnmatch(rel_path, pat) for pat in excludes):
+                continue
+
+            routes = extract_routes_from_file(filepath)
+            if routes:
+                all_routes.extend(routes)
+
+            prefixes = find_router_prefixes(filepath)
+            all_prefixes.update(prefixes)
+
+    return all_routes, all_prefixes
+
+
+def resolve_full_paths(
+    routes: list[dict], prefixes: dict[str, str]
+) -> list[dict]:
+    """Apply router prefixes to route paths to get full paths."""
+    resolved = []
+    for route in routes:
+        prefix = prefixes.get(route["router_var"], "")
+        full_path = prefix.rstrip("/") + "/" + route["path"].lstrip("/")
+        # Normalize double slashes
+        full_path = re.sub(r"//+", "/", full_path)
+        if not full_path.startswith("/"):
+            full_path = "/" + full_path
+        resolved.append(
+            {
+                "method": route["method"],
+                "path": full_path,
+                "file": route["file"],
+                "line": route["line"],
+            }
+        )
+    return resolved
+
+
+# ─── Manifest comparison ─────────────────────────────────────
+
+
+def load_manifest(path: str) -> set[tuple[str, str]]:
+    """Load endpoint manifest. Returns set of (METHOD, path) tuples."""
+    if not os.path.exists(path):
+        print(f"❌ Manifest not found: {path}")
+        print(f'   Create it with: {{ "version": 1, "endpoints": [] }}')
+        sys.exit(1)
+
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"❌ Invalid JSON in manifest: {e}")
+        sys.exit(1)
+
+    endpoints = data.get("endpoints", [])
+    return {(ep.get("method", "GET").upper(), ep["path"]) for ep in endpoints}
+
+
+# ─── Main ────────────────────────────────────────────────────
+
+
+def main():
+    args = parse_args()
+    src_dir = os.path.abspath(args.src_dir)
+    manifest_path = os.path.abspath(args.manifest)
+    excludes = args.exclude or ["tests/*", "**/test_*", "**/*_test.py"]
+
+    print(f"🔍 Scanning: {os.path.relpath(src_dir)}/")
+    print(f"📋 Manifest: {os.path.relpath(manifest_path)}")
+    print(f"🚫 Excluding: {', '.join(excludes)}\n")
+
+    # Scan
+    raw_routes, prefixes = scan_directory(src_dir, excludes)
+    routes = resolve_full_paths(raw_routes, prefixes)
+
+    # Deduplicate
+    seen = set()
+    unique_routes = []
+    for r in routes:
+        key = (r["method"], r["path"])
+        if key not in seen:
+            seen.add(key)
+            unique_routes.append(r)
+
+    # Load manifest
+    manifest_entries = load_manifest(manifest_path)
+
+    # Compare
+    missing = []
+    accounted = []
+    for route in unique_routes:
+        key = (route["method"], route["path"])
+        if key in manifest_entries:
+            accounted.append(route)
+        else:
+            missing.append(route)
+
+    print(
+        f"Found {len(unique_routes)} routes "
+        f"({len(set(r['method'] for r in unique_routes))} methods)"
+    )
+    print(f"Manifest has {len(manifest_entries)} entries")
+    print(f"Accounted: {len(accounted)} | Missing: {len(missing)}\n")
+
+    if missing:
+        print("─" * 60)
+        print("❌ Routes in app but NOT in manifest:\n")
+        for route in sorted(missing, key=lambda r: r["path"]):
+            print(f"  {route['method']} {route['path']}")
+            print(f"    └─ {os.path.relpath(route['file'])}:{route['line']}")
+        print(f"\n{'─' * 60}")
+        print(f"\nAdd these to {os.path.relpath(manifest_path)}:")
+        print(
+            '  { "method": "<METHOD>", "path": "<path>", "tier": 1, "specs": [] }\n'
+        )
+        print("Endpoints with specs: [] will pass CI but show as uncovered")
+        print("in the E2E PR comment.\n")
+
+        if args.strict:
+            print("🚫 Failing CI (strict mode). Use --no-strict to warn only.")
+            sys.exit(1)
+        else:
+            print("⚠️  Warning only (non-strict mode).")
+    else:
+        print("✅ All API routes are accounted for in the manifest.")
+
+
+if __name__ == "__main__":
+    main()

package/skills/engineering/e2e-test/scripts/detect-routes-nextjs.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/*
+  detect-routes-nextjs.mjs
+
+  Detect all Next.js App Router routes and compare against route manifest.
+  Fails CI if any route exists in the app but not in the manifest.
+
+  Scans for page routes (page.tsx) and API routes (route.ts).
+
+  Handles Next.js conventions:
+    Route groups (auth)/ -- stripped from path
+    Dynamic segments [id]/ -- preserved
+    Catch-all [...slug]/ -- preserved
+    Parallel routes @panel/ -- skipped
+    Intercepting routes (.)/ -- skipped
+    Private folders _components/ -- skipped
+
+  Usage:
+    node detect-routes-nextjs.mjs [options]
+
+  Options:
+    --app-dir <path>       Path to app/ directory (default: src/app or app)
+    --manifest <path>      Path to route-manifest.json (default: e2e/route-manifest.json)
+    --strict               Exit 1 if any route is missing (default: true)
+    --no-strict            Only warn, don't fail
+
+  Exit codes:
+    0 -- all routes accounted for
+    1 -- routes missing from manifest (strict mode)
+*/
+
+import { readdirSync, existsSync, readFileSync, statSync } from 'fs';
+import { join, resolve, relative, sep } from 'path';
+
+// ─── CLI args ───────────────────────────────────────────────
+const args = process.argv.slice(2);
+function getArg(name, defaultVal) {
+  const idx = args.indexOf(`--${name}`);
+  return idx >= 0 && args[idx + 1] ? args[idx + 1] : defaultVal;
+}
+const hasFlag = (name) => args.includes(`--${name}`);
+const strict = !hasFlag('no-strict');
+
+// Auto-detect app directory
+function findAppDir() {
+  const explicit = getArg('app-dir', '');
+  if (explicit) return resolve(explicit);
+  if (existsSync('src/app')) return resolve('src/app');
+  if (existsSync('app')) return resolve('app');
+  return null;
+}
+
+const appDir = findAppDir();
+const manifestPath = resolve(getArg('manifest', 'e2e/route-manifest.json'));
+
+if (!appDir || !existsSync(appDir)) {
+  console.error(`❌ App directory not found. Use --app-dir <path>`);
+  process.exit(1);
+}
+
+// ─── Route scanning ─────────────────────────────────────────
+
+/**
+ * Recursively scan the app directory for page.tsx/ts and route.ts/tsx files.
+ * Returns an array of { path: string, type: 'page' | 'api', file: string }
+ */
+function scanRoutes(dir, segments = []) {
+  const routes = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return routes;
+  }
+
+  // Check for route files in current directory
+  const pageFile = entries.find(
+    (e) => e.isFile() && /^page\.(tsx?|jsx?)$/.test(e.name)
+  );
+  const routeFile = entries.find(
+    (e) => e.isFile() && /^route\.(tsx?|jsx?)$/.test(e.name)
+  );
+
+  if (pageFile) {
+    const routePath = '/' + segments.join('/') || '/';
+    routes.push({
+      path: routePath === '/' ? '/' : routePath,
+      type: 'page',
+      file: relative(process.cwd(), join(dir, pageFile.name)),
+    });
+  }
+
+  if (routeFile) {
+    const routePath = '/' + segments.join('/') || '/';
+    routes.push({
+      path: routePath,
+      type: 'api',
+      file: relative(process.cwd(), join(dir, routeFile.name)),
+    });
+  }
+
+  // Recurse into subdirectories
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const name = entry.name;
+
+    // Skip private folders (Next.js convention: _name)
+    if (name.startsWith('_')) continue;
+
+    // Skip parallel routes (@panel, @modal — not independent routes)
+    if (name.startsWith('@')) continue;
+
+    // Skip intercepting routes ((.), (..), (..)(..))
+    if (/^\(\.+\)/.test(name)) continue;
+
+    // Route groups: (groupName) => strip from path
+    if (/^\([^)]+\)$/.test(name) && !name.startsWith('(.)')) {
+      routes.push(...scanRoutes(join(dir, name), segments));
+      continue;
+    }
+
+    // Normal segment (including [dynamic], [...catchAll], [[...optional]])
+    routes.push(...scanRoutes(join(dir, name), [...segments, name]));
+  }
+
+  return routes;
+}
+
+// ─── Manifest comparison ────────────────────────────────────
+
+// Load manifest
+let manifest = { routes: [] };
+if (existsSync(manifestPath)) {
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    console.error(`❌ Invalid JSON in manifest: ${e.message}`);
+    process.exit(1);
+  }
+} else {
+  console.error(`❌ Manifest not found: ${manifestPath}`);
+  console.error(`   Create it with at minimum: { "version": 1, "routes": [] }`);
+  process.exit(1);
+}
+
+const manifestRoutes = new Set(
+  (manifest.routes || []).map((r) => r.path)
+);
+// Also check endpoints (for API routes in combined manifests)
+const manifestEndpoints = new Set(
+  (manifest.endpoints || []).map((r) => r.path)
+);
+const allManifestPaths = new Set([...manifestRoutes, ...manifestEndpoints]);
+
+// Scan
+console.log(`🔍 Scanning: ${relative(process.cwd(), appDir)}/`);
+console.log(`📋 Manifest: ${relative(process.cwd(), manifestPath)}\n`);
+
+const appRoutes = scanRoutes(appDir);
+const missing = [];
+const accounted = [];
+
+for (const route of appRoutes) {
+  if (allManifestPaths.has(route.path)) {
+    accounted.push(route);
+  } else {
+    missing.push(route);
+  }
+}
+
+// ─── Report ─────────────────────────────────────────────────
+
+console.log(`Found ${appRoutes.length} routes in app (${appRoutes.filter(r => r.type === 'page').length} pages, ${appRoutes.filter(r => r.type === 'api').length} API routes)`);
+console.log(`Manifest has ${allManifestPaths.size} entries`);
+console.log(`Accounted: ${accounted.length} | Missing: ${missing.length}\n`);
+
+if (missing.length > 0) {
+  console.log(`${'─'.repeat(60)}`);
+  console.log(`❌ Routes in app but NOT in manifest:\n`);
+  for (const route of missing) {
+    const tag = route.type === 'api' ? ' [API]' : '';
+    console.log(`  ${route.path}${tag}`);
+    console.log(`    └─ ${route.file}`);
+  }
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log(`\nAdd these to ${relative(process.cwd(), manifestPath)}:`);
+  console.log(`  { "path": "<route>", "tier": 1, "specs": [] }\n`);
+  console.log(`Routes with specs: [] will pass CI but show as uncovered`);
+  console.log(`in the E2E PR comment.\n`);
+
+  if (strict) {
+    console.log('🚫 Failing CI (strict mode). Use --no-strict to warn only.');
+    process.exit(1);
+  } else {
+    console.log('⚠️  Warning only (non-strict mode).');
+  }
+} else {
+  console.log('✅ All app routes are accounted for in the manifest.');
+}

package/skills/engineering/e2e-test/scripts/post-visual-evidence.mjs

@@ -0,0 +1,158 @@
+// Evidence-posting step for `presentation:visual` (runs after `visual-baseline-regen`).
+//
+// Closes the visual evidence loop: after baselines are regenerated, persist the
+// rendered evidence back to the work item — MECHANIZED, not a prose reminder (a
+// described step degrades to a lookalike that silently no-ops).
+//
+// It UPSERTS a single marker-tagged comment (never appends) to BOTH the source
+// issue and the PR, carrying:
+//   - the DURABLE committed-baseline link at the regenerated SHA (canonical —
+//     survives artifact expiry), and
+//   - the EPHEMERAL diff/preview artifact URL with its expiry noted.
+// The same two URLs are RETURNED as a value (`--evidence-out <file>`, and always on
+// stdout behind the `visual-evidence:` prefix) for the resolve-issues orchestrator to
+// record as the unit's visual proof-of-execution. This step runs inside a spawn/CI
+// job, and a spawn never writes the run manifest — the orchestrator is its only
+// writer (ADR 0001 decision 5, issue #579). It used to shell out to the orchestrator's
+// manifest CLI from here — the read-modify-write nothing guards once producers stop
+// being serialized.
+//
+// Idempotent upsert is what keeps CI re-runs from spamming the work item — the
+// marker `<!-- visual-evidence:<unit> -->` is matched and the comment edited in
+// place. Posting a comment is outward-facing, but it is a CI bot writing an
+// evidence comment this lane explicitly defines.
+//
+// Contract: ensure-coverage references/enforcement/ci-contract.md → "Evidence-
+// posting step (after baseline-regen)".
+
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+// ---- pure, unit-testable core (no gh / no network) ----
+
+export const MARKER = (unit) => `<!-- visual-evidence:${unit} -->`
+
+// Build the durable, SHA-pinned link to a committed baseline PNG. Survives artifact
+// expiry because it points at the file in git, not a CI artifact store.
+export function durableBaselineLink({ repo, sha, path }) {
+  return `https://github.com/${repo}/blob/${sha}/${path}`
+}
+
+// Render the evidence comment body. Durable link is canonical (always present);
+// the diff artifact is ephemeral and annotated with its expiry. `cells` is the
+// list of regenerated (route, viewport, baselinePath) plus optional diffArtifact.
+export function renderComment({ unit, repo, sha, cells, diffArtifact, diffExpiry }) {
+  const lines = [MARKER(unit), '', '### 🖼️ Visual baselines', '']
+  lines.push('**Durable** (committed at the regenerated SHA — survives artifact expiry):', '')
+  for (const c of cells) {
+    lines.push(`- \`${c.route}\` @${c.viewport} — [baseline](${durableBaselineLink({ repo, sha, path: c.baselinePath })})`)
+  }
+  if (diffArtifact) {
+    lines.push('', `**Preview** (ephemeral diff/render artifact — expires ${diffExpiry || 'per CI retention'}): ${diffArtifact}`)
+  }
+  lines.push('', '_A baseline change is reviewable evidence — it must correspond to a declared intended UI change, not a silent `--update-snapshots` to green._')
+  return lines.join('\n')
+}
+
+// The two URLs this step RETURNS, for the orchestrator to record as the unit's
+// visual proof-of-execution. Named for the return, not the manifest: nothing in a
+// leaf skill may write the manifest, and a helper called `manifestEvidence` invites
+// exactly the call that was removed here.
+export function returnedEvidence({ unit, repo, sha, cells, diffArtifact }) {
+  return {
+    unit,
+    visual: {
+      durableBaselines: cells.map((c) => ({
+        route: c.route, viewport: c.viewport,
+        url: durableBaselineLink({ repo, sha, path: c.baselinePath }),
+      })),
+      diffArtifact: diffArtifact || null,
+    },
+  }
+}
+
+// Decide upsert vs create from the existing comments on a target. Returns the id
+// to edit, or null to create. `comments` is [{ id, body }].
+export function findUpsertTarget(comments, unit) {
+  const marker = MARKER(unit)
+  const hit = (comments || []).find((c) => (c.body || '').includes(marker))
+  return hit ? hit.id : null
+}
+
+// Pure: extract the visual (route, viewport, baselinePath) cells from a
+// presentation-results.json the sweep emitted (runner-contract.md result shape).
+// Only `presentation:visual` rows carry a `baseline`; the floor levels don't.
+export function cellsFromResults(results) {
+  const rows = (results && Array.isArray(results.results)) ? results.results : []
+  return rows
+    .filter((r) => r.level === 'presentation:visual' && r.baseline)
+    .map((r) => ({ route: r.route, viewport: r.viewport, baselinePath: r.baseline }))
+}
+
+// Pure: parse argv into the options the CLI needs. Kept pure so it's tested.
+export function parseArgs(argv) {
+  const o = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) o[a.slice(2)] = (argv[i + 1] && !argv[i + 1].startsWith('--')) ? argv[++i] : 'true'
+  }
+  return o
+}
+
+// ---- gh + fs wrapper (thin; the pure core above is what doctrine pins) ----
+
+function gh(args) {
+  return execFileSync('gh', args, { encoding: 'utf8' })
+}
+
+// Upsert the marker comment on one target (issue or PR — both are "issues" to gh).
+// Edits in place when the marker already exists (idempotent across CI re-runs),
+// else creates. Listing is via `gh api` so we can match the hidden marker.
+function upsertComment(repo, number, unit, body) {
+  let existing = []
+  try {
+    existing = JSON.parse(gh(['api', `repos/${repo}/issues/${number}/comments`, '--paginate',
+      '--jq', '[.[] | {id: .id, body: .body}]']))
+  } catch { existing = [] }
+  const id = findUpsertTarget(existing, unit)
+  if (id) gh(['api', '--method', 'PATCH', `repos/${repo}/issues/comments/${id}`, '-f', `body=${body}`])
+  else gh(['issue', 'comment', String(number), '--repo', repo, '--body', body])
+}
+
+function main() {
+  const o = parseArgs(process.argv.slice(2))
+  const required = ['unit', 'repo', 'sha', 'results']
+  const missing = required.filter((k) => !o[k])
+  if (missing.length) { console.error(`post-visual-evidence: missing --${missing.join(', --')}`); process.exit(2) }
+
+  const results = JSON.parse(fs.readFileSync(o.results, 'utf8'))
+  const cells = cellsFromResults(results)
+
+  // Zero cells is a real answer ("this unit has no `presentation:visual` surface"), not
+  // an absence of one — so it still travels the return channel. Bailing before the
+  // marker and the file made the two indistinguishable to the orchestrator, and left
+  // the lane's `if: always()` artifact upload warning on a path that had simply
+  // finished. Only the outward-facing comment is skipped: there is nothing to say.
+  if (cells.length > 0) {
+    const body = renderComment({
+      unit: o.unit, repo: o.repo, sha: o.sha, cells,
+      diffArtifact: o['diff-artifact'], diffExpiry: o['diff-expiry'],
+    })
+    for (const target of [o.issue, o.pr].filter(Boolean)) upsertComment(o.repo, target, o.unit, body)
+  }
+
+  // Return the same URLs as a value. The orchestrator records them on the unit; this
+  // step does not touch the run manifest, because the orchestrator is its only writer
+  // (ADR 0001 decision 5). Always on stdout (so a spawn can quote it back in its
+  // result), and to a file when the caller wants it as a CI artifact.
+  const evidence = returnedEvidence({ unit: o.unit, repo: o.repo, sha: o.sha, cells, diffArtifact: o['diff-artifact'] })
+  console.log(`visual-evidence: ${JSON.stringify(evidence)}`)
+  if (o['evidence-out']) fs.writeFileSync(o['evidence-out'], `${JSON.stringify(evidence, null, 2)}\n`)
+
+  console.log(cells.length === 0
+    ? 'post-visual-evidence: no presentation:visual cells in results — nothing to comment; returned an empty evidence value'
+    : `post-visual-evidence: upserted visual evidence for ${cells.length} cell(s)`)
+}
+
+if (isMainModule(import.meta.url)) main()