frontos 0.2.0__py3-none-any.whl

frontos/__init__.py

@@ -0,0 +1,3 @@
+"""FrontOS: a local frontend specialist for AI coding agents."""
+
+__version__ = "0.2.0"

frontos/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

frontos/cli.py

@@ -0,0 +1,474 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import signal
+import sys
+from pathlib import Path
+from typing import Any
+
+from frontos import __version__
+from frontos.core.store import Store
+from frontos.engines.design_pack import DesignPackCompiler, list_presets, load_design_pack
+from frontos.engines.detect import detect_project
+from frontos.engines.patches import PatchEngine
+from frontos.engines.qa import QAEngine, load_latest_qa
+from frontos.engines.scanner import ProjectScanner, load_latest_scan
+from frontos.engines.security import SecurityAuditor
+from frontos.engines.visual import VisualQAEngine, load_latest_visual_comparison, load_latest_visual_report
+from frontos.engines.workflow import WorkflowEngine, load_latest_workflow
+from frontos.mcp.server import run_stdio
+from frontos.server.http_api import serve
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+    try:
+        result = args.func(args)
+    except BrokenPipeError:
+        return 1
+    except Exception as exc:
+        print(f"frontos: {exc}", file=sys.stderr)
+        return 1
+    if result is not None:
+        print_json(result)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="frontos", description="Local frontend specialist for AI coding agents.")
+    parser.add_argument("--home", help="Override FRONTOS_HOME for this command.")
+    parser.add_argument("--version", action="version", version=f"frontos {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    status = sub.add_parser("status", help="Show FrontOS home, daemon, and registry status.")
+    status.set_defaults(func=cmd_status)
+
+    serve_cmd = sub.add_parser("serve", help="Run the local HTTP daemon in the foreground.")
+    serve_cmd.add_argument("--host", default="127.0.0.1")
+    serve_cmd.add_argument("--port", type=int, default=4791)
+    serve_cmd.set_defaults(func=cmd_serve)
+
+    stop = sub.add_parser("stop", help="Stop a foreground/background FrontOS daemon by PID file.")
+    stop.set_defaults(func=cmd_stop)
+
+    mcp = sub.add_parser("mcp", help="Run the MCP-compatible stdio server or print client config.")
+    mcp.add_argument("mcp_args", nargs="*", help="Use `frontos mcp config codex|cursor|claude` for setup snippets.")
+    mcp.set_defaults(func=cmd_mcp)
+
+    project = sub.add_parser("project", help="Manage registered projects.")
+    project_sub = project.add_subparsers(dest="project_command", required=True)
+    project_add = project_sub.add_parser("add", help="Register a local project.")
+    project_add.add_argument("path")
+    project_add.add_argument("--name")
+    project_add.add_argument("--write", action="store_true", help="Allow direct writes. Default is patch-only.")
+    project_add.set_defaults(func=cmd_project_add)
+
+    project_list = project_sub.add_parser("list", help="List registered projects.")
+    project_list.set_defaults(func=cmd_project_list)
+
+    project_scan = project_sub.add_parser("scan", help="Scan a registered project.")
+    project_scan.add_argument("project")
+    project_scan.set_defaults(func=cmd_project_scan)
+
+    project_configure = project_sub.add_parser("configure", help="Configure project runtime URL and dev command.")
+    project_configure.add_argument("project")
+    project_configure.add_argument("--base-url")
+    project_configure.add_argument("--dev-command")
+    project_configure.set_defaults(func=cmd_project_configure)
+
+    scan = sub.add_parser("scan", help="Alias for project scan.")
+    scan.add_argument("project")
+    scan.set_defaults(func=cmd_project_scan)
+
+    design = sub.add_parser("design-pack", help="Create or inspect Design Packs.")
+    design_sub = design.add_subparsers(dest="design_command", required=True)
+    design_presets = design_sub.add_parser("presets", help="List available Design Pack presets.")
+    design_presets.set_defaults(func=cmd_design_pack_presets)
+    design_create = design_sub.add_parser("create", help="Create a project-specific Design Pack.")
+    design_create.add_argument("project")
+    design_create.add_argument("--preset", help="Use a specific Style DNA preset.")
+    design_create.set_defaults(func=cmd_design_pack_create)
+    design_get = design_sub.add_parser("get", help="Print the latest Design Pack.")
+    design_get.add_argument("project")
+    design_get.add_argument("--pack-id")
+    design_get.set_defaults(func=cmd_design_pack_get)
+
+    qa = sub.add_parser("qa", help="Run design QA for a project.")
+    qa.add_argument("project")
+    qa.set_defaults(func=cmd_qa)
+
+    security = sub.add_parser("security", help="Run local security checks.")
+    security_sub = security.add_subparsers(dest="security_command", required=True)
+    security_audit = security_sub.add_parser("audit", help="Scan a registered project for secret-like values.")
+    security_audit.add_argument("project")
+    security_audit.set_defaults(func=cmd_security_audit)
+
+    patch = sub.add_parser("patch", help="Generate or preview patch artifacts.")
+    patch_sub = patch.add_subparsers(dest="patch_command", required=True)
+    patch_generate = patch_sub.add_parser("generate", help="Generate a patch artifact.")
+    patch_generate.add_argument("project")
+    patch_generate.add_argument("--route")
+    patch_generate.add_argument("--mode", default="repair_existing_frontend")
+    patch_generate.set_defaults(func=cmd_patch_generate)
+    patch_preview = patch_sub.add_parser("preview", help="Preview a patch artifact.")
+    patch_preview.add_argument("patch_id")
+    patch_preview.add_argument("--diff", action="store_true", help="Print the unified diff instead of JSON metadata.")
+    patch_preview.set_defaults(func=cmd_patch_preview)
+    patch_validate = patch_sub.add_parser("validate", help="Validate a staged patch before applying it.")
+    patch_validate.add_argument("patch_id")
+    patch_validate.set_defaults(func=cmd_patch_validate)
+    patch_apply = patch_sub.add_parser("apply", help="Apply a staged patch to the registered project.")
+    patch_apply.add_argument("patch_id")
+    patch_apply.add_argument("--confirm", action="store_true", help="Allow writing into a patch-only project.")
+    patch_apply.add_argument("--dry-run", action="store_true", help="Validate without writing staged files.")
+    patch_apply.set_defaults(func=cmd_patch_apply)
+    patch_rollback = patch_sub.add_parser("rollback", help="Rollback an applied patch using its snapshot.")
+    patch_rollback.add_argument("patch_id")
+    patch_rollback.add_argument("--confirm", action="store_true", help="Allow writing rollback files into the project.")
+    patch_rollback.set_defaults(func=cmd_patch_rollback)
+
+    visual = sub.add_parser("visual", help="Capture screenshots and visual QA metadata.")
+    visual_sub = visual.add_subparsers(dest="visual_command", required=True)
+    visual_capture = visual_sub.add_parser("capture", help="Capture route screenshots for a running project.")
+    visual_capture.add_argument("project")
+    visual_capture.add_argument("--phase", default="before", choices=["before", "after", "current"])
+    visual_capture.add_argument("--base-url")
+    visual_capture.add_argument("--route", action="append")
+    visual_capture.add_argument("--viewport", action="append", choices=["desktop", "tablet", "mobile"])
+    visual_capture.add_argument("--timeout-ms", type=int, default=30000)
+    visual_capture.add_argument("--dry-run", action="store_true")
+    visual_capture.set_defaults(func=cmd_visual_capture)
+    visual_latest = visual_sub.add_parser("latest", help="Print the latest visual QA report for a project.")
+    visual_latest.add_argument("project")
+    visual_latest.set_defaults(func=cmd_visual_latest)
+    visual_compare = visual_sub.add_parser("compare", help="Compare latest before/after screenshots.")
+    visual_compare.add_argument("project")
+    visual_compare.add_argument("--route")
+    visual_compare.add_argument("--viewport", action="append", choices=["desktop", "tablet", "mobile"])
+    visual_compare.add_argument("--min-change-percent", type=float, default=0.1)
+    visual_compare.add_argument("--max-change-percent", type=float, default=65.0)
+    visual_compare.set_defaults(func=cmd_visual_compare)
+    visual_compare_latest = visual_sub.add_parser(
+        "comparison-latest", help="Print the latest visual comparison report."
+    )
+    visual_compare_latest.add_argument("project")
+    visual_compare_latest.set_defaults(func=cmd_visual_compare_latest)
+    visual_doctor = visual_sub.add_parser("doctor", help="Check optional visual QA dependencies.")
+    visual_doctor.add_argument("--check-browser", action="store_true", help="Launch Chromium to verify browser setup.")
+    visual_doctor.set_defaults(func=cmd_visual_doctor)
+
+    workflow = sub.add_parser("workflow", help="Run orchestrated FrontOS workflows.")
+    workflow_sub = workflow.add_subparsers(dest="workflow_command", required=True)
+    workflow_repair = workflow_sub.add_parser("repair", help="Run the full repair workflow.")
+    workflow_repair.add_argument("project")
+    workflow_repair.add_argument("--route")
+    workflow_repair.add_argument("--mode", default="repair_existing_frontend")
+    workflow_repair.add_argument("--base-url")
+    workflow_repair.add_argument("--dev-command")
+    workflow_repair.add_argument("--apply", action="store_true")
+    workflow_repair.add_argument("--confirm", action="store_true")
+    workflow_repair.add_argument("--skip-visual", action="store_true")
+    workflow_repair.add_argument("--visual-dry-run", action="store_true")
+    workflow_repair.add_argument("--start-server", action="store_true")
+    workflow_repair.add_argument("--keep-server", action="store_true")
+    workflow_repair.add_argument("--viewport", action="append", choices=["desktop", "tablet", "mobile"])
+    workflow_repair.add_argument("--timeout-ms", type=int, default=30000)
+    workflow_repair.add_argument("--startup-timeout-s", type=int, default=30)
+    workflow_repair.set_defaults(func=cmd_workflow_repair)
+    workflow_latest = workflow_sub.add_parser("latest", help="Print the latest workflow report.")
+    workflow_latest.add_argument("project")
+    workflow_latest.set_defaults(func=cmd_workflow_latest)
+
+    repair = sub.add_parser("repair", help="Scan, design, patch, and QA a project or route.")
+    repair.add_argument("project")
+    repair.add_argument("--route")
+    repair.add_argument("--mode", default="repair_existing_frontend")
+    repair.set_defaults(func=cmd_repair)
+
+    return parser
+
+
+def cmd_status(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    pid_path = store.home / "frontos.pid"
+    daemon = {"running": False, "pid": None}
+    if pid_path.exists():
+        pid = int(pid_path.read_text(encoding="utf-8").strip())
+        daemon = {"running": _pid_running(pid), "pid": pid}
+    return {
+        "version": __version__,
+        "home": str(store.home),
+        "db": str(store.db_path),
+        "projects": store.count_projects(),
+        "daemon": daemon,
+    }
+
+
+def cmd_serve(args: argparse.Namespace) -> None:
+    print(f"FrontOS serving on http://{args.host}:{args.port}", file=sys.stderr)
+    serve(args.host, args.port, _home(args))
+    return None
+
+
+def cmd_stop(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    pid_path = store.home / "frontos.pid"
+    if not pid_path.exists():
+        return {"status": "not_running"}
+    pid = int(pid_path.read_text(encoding="utf-8").strip())
+    if not _pid_running(pid):
+        pid_path.unlink(missing_ok=True)
+        return {"status": "stale_pid_removed", "pid": pid}
+    os.kill(pid, signal.SIGTERM)
+    return {"status": "stopping", "pid": pid}
+
+
+def cmd_mcp(args: argparse.Namespace) -> dict[str, Any] | None:
+    if args.mcp_args:
+        if len(args.mcp_args) == 2 and args.mcp_args[0] == "config":
+            return _mcp_config(args.mcp_args[1])
+        raise ValueError("Use `frontos mcp` or `frontos mcp config codex|cursor|claude`")
+    run_stdio(_home(args))
+    return None
+
+
+def cmd_project_add(args: argparse.Namespace) -> dict[str, Any]:
+    path = Path(args.path).expanduser().resolve()
+    return _store(args).add_project(path, args.name, detect_project(path), args.write)
+
+
+def cmd_project_list(args: argparse.Namespace) -> dict[str, Any]:
+    return {"projects": _store(args).list_projects()}
+
+
+def cmd_project_scan(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    return ProjectScanner(store).scan(project)
+
+
+def cmd_project_configure(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    if args.base_url is None and args.dev_command is None:
+        return store.get_project_runtime(project["id"])
+    return store.set_project_runtime(project["id"], args.base_url, args.dev_command)
+
+
+def cmd_design_pack_create(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    scan = load_latest_scan(store, project["id"]) or ProjectScanner(store).scan(project)
+    return DesignPackCompiler(store).create(project, scan, preset_id=args.preset)
+
+
+def cmd_design_pack_presets(args: argparse.Namespace) -> dict[str, Any]:
+    return {"presets": list_presets()}
+
+
+def cmd_design_pack_get(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    pack = load_design_pack(store, project["id"], args.pack_id)
+    if pack is None:
+        raise KeyError(f"No design pack found for {project['id']}")
+    return pack
+
+
+def cmd_qa(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    scan = load_latest_scan(store, project["id"]) or ProjectScanner(store).scan(project)
+    pack = load_design_pack(store, project["id"])
+    return QAEngine(store).run(project, scan, pack)
+
+
+def cmd_security_audit(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    return SecurityAuditor(store).audit_project(project)
+
+
+def cmd_patch_generate(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    scan = load_latest_scan(store, project["id"]) or ProjectScanner(store).scan(project)
+    pack = load_design_pack(store, project["id"]) or DesignPackCompiler(store).create(project, scan)
+    return PatchEngine(store).generate(project, scan, pack, route=args.route, mode=args.mode)
+
+
+def cmd_patch_preview(args: argparse.Namespace) -> Any:
+    preview = PatchEngine(_store(args)).preview(args.patch_id)
+    if args.diff:
+        print(preview["diff"])
+        return None
+    return preview["manifest"]
+
+
+def cmd_patch_validate(args: argparse.Namespace) -> dict[str, Any]:
+    return PatchEngine(_store(args)).validate(args.patch_id)
+
+
+def cmd_patch_apply(args: argparse.Namespace) -> dict[str, Any]:
+    return PatchEngine(_store(args)).apply(args.patch_id, confirm=args.confirm, dry_run=args.dry_run)
+
+
+def cmd_patch_rollback(args: argparse.Namespace) -> dict[str, Any]:
+    return PatchEngine(_store(args)).rollback(args.patch_id, confirm=args.confirm)
+
+
+def cmd_visual_capture(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    scan = load_latest_scan(store, project["id"]) or ProjectScanner(store).scan(project)
+    return VisualQAEngine(store).capture(
+        project,
+        scan,
+        phase=args.phase,
+        base_url=args.base_url,
+        routes=args.route,
+        viewports=args.viewport,
+        timeout_ms=args.timeout_ms,
+        dry_run=args.dry_run,
+    )
+
+
+def cmd_visual_latest(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    report = load_latest_visual_report(store, project["id"])
+    if report is None:
+        raise KeyError(f"No visual report found for {project['id']}")
+    return report
+
+
+def cmd_visual_compare(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    return VisualQAEngine(store).compare(
+        project,
+        route=args.route,
+        viewports=args.viewport,
+        minimum_change_percent=args.min_change_percent,
+        maximum_change_percent=args.max_change_percent,
+    )
+
+
+def cmd_visual_compare_latest(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    report = load_latest_visual_comparison(store, project["id"])
+    if report is None:
+        raise KeyError(f"No visual comparison report found for {project['id']}")
+    return report
+
+
+def cmd_visual_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    return VisualQAEngine(_store(args)).doctor(check_browser=args.check_browser)
+
+
+def cmd_workflow_repair(args: argparse.Namespace) -> dict[str, Any]:
+    return WorkflowEngine(_store(args)).repair(
+        args.project,
+        route=args.route,
+        mode=args.mode,
+        base_url=args.base_url,
+        dev_command=args.dev_command,
+        apply_patch=args.apply,
+        confirm=args.confirm,
+        capture_visual=not args.skip_visual,
+        visual_dry_run=args.visual_dry_run,
+        viewports=args.viewport,
+        timeout_ms=args.timeout_ms,
+        start_server=args.start_server,
+        stop_server=not args.keep_server,
+        startup_timeout_seconds=args.startup_timeout_s,
+    )
+
+
+def cmd_workflow_latest(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    report = load_latest_workflow(store, project["id"])
+    if report is None:
+        raise KeyError(f"No workflow report found for {project['id']}")
+    return report
+
+
+def cmd_repair(args: argparse.Namespace) -> dict[str, Any]:
+    store = _store(args)
+    project = store.get_project(args.project)
+    scan = ProjectScanner(store).scan(project)
+    pack = load_design_pack(store, project["id"]) or DesignPackCompiler(store).create(project, scan)
+    patch = PatchEngine(store).generate(project, scan, pack, route=args.route, mode=args.mode)
+    qa = QAEngine(store).run(project, scan, pack, patch, job_id=patch["id"].replace("patch_", "job_"))
+    return {
+        "jobId": qa["jobId"],
+        "project": project["id"],
+        "mode": args.mode,
+        "route": args.route,
+        "designPack": {
+            "id": pack["id"],
+            "styleDNA": pack["styleDNA"]["name"],
+            "tokensGenerated": True,
+            "componentContractsGenerated": True,
+            "screenPatternsGenerated": True,
+        },
+        "artifacts": {
+            "appMap": f"frontos://project/{project['id']}/app-map",
+            "behaviorContracts": f"frontos://project/{project['id']}/behavior-contracts",
+            "frontendAudit": f"frontos://project/{project['id']}/audit/latest",
+            "patch": f"frontos://patch/{patch['id']}",
+            "beforeScreenshot": f"frontos://project/{project['id']}/screenshots/before",
+            "afterScreenshot": f"frontos://project/{project['id']}/screenshots/after",
+            "visualDiff": f"frontos://project/{project['id']}/visual-comparison/latest",
+            "visualComparisonReport": f"frontos://project/{project['id']}/visual-comparison/latest",
+            "qaReport": f"frontos://qa/{qa['jobId']}",
+        },
+        "scores": qa["scores"],
+        "status": "ready_for_review" if qa["status"] == "passed" else "needs_repair",
+    }
+
+
+def print_json(data: Any) -> None:
+    print(json.dumps(data, indent=2, sort_keys=True))
+
+
+def _store(args: argparse.Namespace) -> Store:
+    return Store(_home(args))
+
+
+def _home(args: argparse.Namespace) -> str | None:
+    return getattr(args, "home", None)
+
+
+def _pid_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def _mcp_config(client: str) -> dict[str, Any]:
+    command = shutil.which("frontos") or "frontos"
+    if client == "codex":
+        return {
+            "client": "codex",
+            "config": f'[mcp_servers.frontos]\ncommand = "{command}"\nargs = ["mcp"]\n',
+        }
+    if client == "cursor":
+        return {"client": "cursor", "config": {"mcpServers": {"frontos": {"command": command, "args": ["mcp"]}}}}
+    if client in {"claude", "claude-desktop"}:
+        return {
+            "client": "claude",
+            "config": {"mcpServers": {"frontos": {"command": command, "args": ["mcp"]}}},
+        }
+    raise ValueError("Supported MCP config clients: codex, cursor, claude")

frontos/core/__init__.py

@@ -0,0 +1,2 @@
+"""Core storage and filesystem helpers."""
+

frontos/core/paths.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+FRONTOS_DIRS = (
+    "projects",
+    "design-packs",
+    "scans",
+    "behavior-contracts",
+    "screenshots",
+    "patches",
+    "qa-reports",
+    "registry",
+    "adapters",
+)
+
+
+def frontos_home(value: str | os.PathLike[str] | None = None) -> Path:
+    """Return the configured FrontOS home directory."""
+
+    raw = value or os.environ.get("FRONTOS_HOME") or "~/.frontos"
+    return Path(raw).expanduser().resolve()
+
+
+def ensure_frontos_home(value: str | os.PathLike[str] | None = None) -> Path:
+    """Create the FrontOS home layout and default config file."""
+
+    home = frontos_home(value)
+    home.mkdir(parents=True, exist_ok=True)
+    for dirname in FRONTOS_DIRS:
+        (home / dirname).mkdir(parents=True, exist_ok=True)
+
+    config_path = home / "config.yml"
+    if not config_path.exists():
+        config_path.write_text(
+            "\n".join(
+                [
+                    "version: 1",
+                    "mode: local-first",
+                    "default_permissions:",
+                    "  read: true",
+                    "  write: false",
+                    "  patchOnly: true",
+                    "network:",
+                    "  allowSourceUpload: false",
+                    "server:",
+                    "  host: 127.0.0.1",
+                    "  port: 4791",
+                    "",
+                ]
+            ),
+            encoding="utf-8",
+        )
+    return home
+
+
+def slugify(value: str) -> str:
+    cleaned = []
+    previous_dash = False
+    for char in value.lower().strip():
+        if char.isalnum():
+            cleaned.append(char)
+            previous_dash = False
+        elif not previous_dash:
+            cleaned.append("-")
+            previous_dash = True
+    return "".join(cleaned).strip("-") or "project"
+

frontos/core/redaction.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import re
+
+
+SECRET_PATTERNS = {
+    "github_token": re.compile(r"\bgh[pousr]_[A-Za-z0-9_]{20,}\b"),
+    "openai_key": re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"),
+    "aws_access_key": re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+    "private_key": re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----", re.S),
+    "env_assignment": re.compile(
+        r"(?i)\b(api[_-]?key|token|secret|password|private[_-]?key)\s*=\s*['\"]?[^'\"\s]{8,}"
+    ),
+}
+
+
+def redact_text(text: str) -> str:
+    redacted = text
+    for name, pattern in SECRET_PATTERNS.items():
+        redacted = pattern.sub(f"[REDACTED:{name}]", redacted)
+    return redacted
+
+
+def secret_findings(text: str) -> list[dict[str, str]]:
+    findings = []
+    for name, pattern in SECRET_PATTERNS.items():
+        for match in pattern.finditer(text):
+            findings.append({"type": name, "preview": _preview(match.group(0))})
+    return findings
+
+
+def _preview(value: str) -> str:
+    if len(value) <= 12:
+        return "[REDACTED]"
+    return f"{value[:4]}...{value[-4:]}"