@topy-ai/maggie 0.7.12 → 0.7.14

package/bundled-tools/clis/maggie_dash.py

@@ -24,6 +24,7 @@ from maggie_dash_store import MaggieDashStore  # noqa: E402
 from service_variants import ServiceVariantStore  # noqa: E402
 from maggie_dash_ui import load_and_validate  # noqa: E402
 from maggie_sections import catalogue, remap_translations, section_id_migration, validate_registry, copy_notes, validate_values, validate_fanout, reconcile_fields, validate_locale_coverage  # noqa: E402
+from maggie_quality import validate_variant_copy, validate_media_uniqueness, classify_inventory, validate_bindings, validate_reconcile_contract  # noqa: E402
 from route_imports import classify_bindings  # noqa: E402
 
 
@@ -358,7 +359,29 @@ def command_sections(args: argparse.Namespace) -> int:
     if args.sections_command == "locale-validate":
         sections = json.loads(Path(args.sections_file).resolve().read_text(encoding="utf-8"))
         translations = json.loads(Path(args.translations_file).resolve().read_text(encoding="utf-8"))
-        result = validate_locale_coverage(args.page_id, sections, translations, args.locale)
+        registry = json.loads(Path(args.registry).resolve().read_text(encoding="utf-8")) if args.registry else None
+        result = validate_locale_coverage(args.page_id, sections, translations, args.locale, registry=registry)
+        emit(result)
+        return 0 if result["passed"] else 1
+    if args.sections_command == "variant-copy-validate":
+        value = json.loads(Path(args.pages_file).resolve().read_text(encoding="utf-8"))
+        result = validate_variant_copy(value, args.field or ["faq"])
+        emit(result)
+        return 0 if result["passed"] else 1
+    if args.sections_command == "media-validate":
+        value = json.loads(Path(args.pages_file).resolve().read_text(encoding="utf-8"))
+        result = validate_media_uniqueness(value, across_siblings=args.across_siblings)
+        emit(result)
+        return 0 if result["passed"] else 1
+    if args.sections_command == "bindings-validate":
+        sections = json.loads(Path(args.sections_file).resolve().read_text(encoding="utf-8"))
+        references = json.loads(Path(args.references_file).resolve().read_text(encoding="utf-8"))
+        result = validate_bindings(sections, references)
+        emit(result)
+        return 0 if result["passed"] else 1
+    if args.sections_command == "idempotency-validate":
+        contract = json.loads(Path(args.contract_file).resolve().read_text(encoding="utf-8"))
+        result = validate_reconcile_contract(contract)
         emit(result)
         return 0 if result["passed"] else 1
     registry = json.loads(Path(args.registry).resolve().read_text(encoding="utf-8"))
@@ -396,6 +419,14 @@ def command_components_audit(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_inventory(args: argparse.Namespace) -> int:
+    """Classify each published page once, with no broad predicate overlap."""
+    value = json.loads(Path(args.pages_file).resolve().read_text(encoding="utf-8"))
+    result = classify_inventory(value)
+    emit(result)
+    return 0 if result["passed"] else 1
+
+
 def variant_store(args: argparse.Namespace) -> ServiceVariantStore:
     return ServiceVariantStore(project_root(args) / ".maggie" / "service-variants.json")
 
@@ -518,8 +549,20 @@ def parser() -> argparse.ArgumentParser:
     sections_reconcile.add_argument("--current-file", required=True); sections_reconcile.add_argument("--desired-file", required=True); sections_reconcile.add_argument("--output", required=True); sections_reconcile.add_argument("--force", action="store_true"); sections_reconcile.add_argument("--confirm", action="store_true")
     sections_reconcile.set_defaults(func=command_sections)
     sections_locale = sections_sub.add_parser("locale-validate", help="check locale sidecar coverage for stored image alt fields")
-    sections_locale.add_argument("--page-id", required=True); sections_locale.add_argument("--sections-file", required=True); sections_locale.add_argument("--translations-file", required=True); sections_locale.add_argument("--locale", action="append", required=True)
+    sections_locale.add_argument("--page-id", required=True); sections_locale.add_argument("--sections-file", required=True); sections_locale.add_argument("--translations-file", required=True); sections_locale.add_argument("--locale", action="append", required=True); sections_locale.add_argument("--registry", help="registry for all declared translatable fields")
     sections_locale.set_defaults(func=command_sections)
+    sections_variants = sections_sub.add_parser("variant-copy-validate", help="detect duplicated copy across sibling variants")
+    sections_variants.add_argument("--pages-file", required=True); sections_variants.add_argument("--field", action="append", default=[])
+    sections_variants.set_defaults(func=command_sections)
+    sections_media = sections_sub.add_parser("media-validate", help="detect duplicate media within pages or sibling families")
+    sections_media.add_argument("--pages-file", required=True); sections_media.add_argument("--across-siblings", action="store_true")
+    sections_media.set_defaults(func=command_sections)
+    sections_bindings = sections_sub.add_parser("bindings-validate", help="resolve stored section references against a reference inventory")
+    sections_bindings.add_argument("--sections-file", required=True); sections_bindings.add_argument("--references-file", required=True)
+    sections_bindings.set_defaults(func=command_sections)
+    sections_idempotency = sections_sub.add_parser("idempotency-validate", help="validate a migration repair selection and convergence contract")
+    sections_idempotency.add_argument("--contract-file", required=True)
+    sections_idempotency.set_defaults(func=command_sections)
     sections_keys.set_defaults(func=command_sections)
     components = sub.add_parser("components-audit", help="classify route component bindings against live section/page inventories")
     components.add_argument("--bindings-file", required=True)
@@ -527,6 +570,9 @@ def parser() -> argparse.ArgumentParser:
     components.add_argument("--pages-file", required=True, help="JSON array/object of live page paths")
     components.add_argument("--output")
     components.set_defaults(func=command_components_audit)
+    inventory = sub.add_parser("inventory", help="classify published pages into disjoint band/code-rendered kinds")
+    inventory.add_argument("--pages-file", required=True, help="JSON page inventory")
+    inventory.set_defaults(func=command_inventory)
     variant = sub.add_parser("variant", help="manage service variant lifecycle")
     variant_sub = variant.add_subparsers(dest="variant_command", required=True)
     create = variant_sub.add_parser("create"); create.add_argument("--project", default="."); create.add_argument("--service-id", required=True); create.add_argument("--variant-id", required=True); create.add_argument("--variant-type", required=True); create.add_argument("--locale", required=True); create.add_argument("--market", required=True); create.add_argument("--slug", required=True); create.add_argument("--title", required=True); create.add_argument("--facts", required=True); create.add_argument("--source-revision", required=True); create.add_argument("--canonical-variant-id"); create.add_argument("--cluster-link", action="append", default=[]); create.add_argument("--layout-family", default="service-default"); create.add_argument("--confirm", action="store_true")

package/bundled-tools/clis/maggie_migration.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import re
 import sys
@@ -54,7 +55,73 @@ def validate_project(project: Path, environment: str) -> dict:
     return result
 
 
+IDENTITY_SCHEMA = "maggie-database-identity.v1"
+
+
+def _identity_fingerprint(identity: dict) -> str:
+    material = {key: identity.get(key) for key in ("environment", "targetName", "databaseName", "serverIdentity", "serviceIdentity", "rowCounts")}
+    return hashlib.sha256(json.dumps(material, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()).hexdigest()
+
+
+def validate_identity(identity: object, expected: object | None = None) -> dict:
+    """Gate a write against a non-secret database identity report.
+
+    The report intentionally contains names, server identity and row counts,
+    never a connection string. Comparing it with the service/deployment
+    identity catches the common case where staging and production credentials
+    resolve to different or unexpectedly identical databases.
+    """
+    errors: list[str] = []
+    if not isinstance(identity, dict):
+        return {"schemaVersion": IDENTITY_SCHEMA, "passed": False, "errors": ["identity report must be an object"], "mutation": "not executed"}
+    if identity.get("schemaVersion") != IDENTITY_SCHEMA:
+        errors.append(f"schemaVersion must be {IDENTITY_SCHEMA}")
+    for field in ("environment", "targetName", "databaseName", "serverIdentity", "serviceIdentity"):
+        if not str(identity.get(field) or "").strip():
+            errors.append(f"{field} is required")
+    if not isinstance(identity.get("rowCounts"), dict):
+        errors.append("rowCounts must be an object")
+    fingerprint = str(identity.get("fingerprint") or "")
+    if not re.fullmatch(r"[0-9a-f]{64}", fingerprint):
+        errors.append("fingerprint must be a SHA-256 hex digest")
+    elif fingerprint != _identity_fingerprint(identity):
+        errors.append("fingerprint does not match the reported identity")
+    compared: list[str] = []
+    if expected is not None:
+        if not isinstance(expected, dict):
+            errors.append("expected identity report must be an object")
+        else:
+            for field in ("environment", "targetName", "databaseName", "serverIdentity", "serviceIdentity"):
+                if str(identity.get(field)) != str(expected.get(field)):
+                    errors.append(f"target identity mismatch: {field}")
+                else:
+                    compared.append(field)
+    return {"schemaVersion": IDENTITY_SCHEMA, "passed": not errors, "errors": errors, "mutation": "not executed", "compared": compared, "target": {key: identity.get(key) for key in ("environment", "targetName", "databaseName", "serverIdentity", "serviceIdentity", "rowCounts")}}
+
+
+def identity_main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Validate a secret-free database target identity before migration writes.")
+    parser.add_argument("--identity-file", required=True)
+    parser.add_argument("--expected-file")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    try:
+        actual = json.loads(Path(args.identity_file).read_text(encoding="utf-8"))
+        expected = json.loads(Path(args.expected_file).read_text(encoding="utf-8")) if args.expected_file else None
+        result = validate_identity(actual, expected)
+    except (OSError, json.JSONDecodeError) as error:
+        result = {"schemaVersion": IDENTITY_SCHEMA, "passed": False, "errors": [f"cannot read identity report: {error}"], "mutation": "not executed"}
+    if args.output:
+        output = Path(args.output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def main() -> int:
+    if sys.argv[1:2] == ["identity"]:
+        return identity_main(sys.argv[2:])
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("manifest", nargs="?")
     parser.add_argument("--project")

package/bundled-tools/clis/maggie_qa_workflow.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""Track project scenario-based browser QA from test through retest.
+
+The command stores secret-free run state in ``.maggie/qa-runs``. Browser
+interaction remains with the selected browser skill; this CLI records the
+scenario, evidence references, fix event and final release decision.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+
+DEFAULT_SCENARIOS = Path(".maggie") / "scenario-manifest.json"
+VALID_STATUSES = {"pending", "pass", "fail", "blocked", "inconclusive"}
+VALID_PHASES = {"test", "fix", "retest"}
+SECRET_RE = re.compile(
+    r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|authorization|cookie)\s*[=:]\s*)[^\s,;]+"
+)
+EMAIL_RE = re.compile(r"\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b")
+QUERY_SECRET_RE = re.compile(r"(?i)([?&](?:token|key|secret|password|code|id_token|access_token)=)[^&\s]+")
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def safe_text(value: object, limit: int = 1200) -> str:
+    text = str(value or "").strip()
+    text = SECRET_RE.sub(r"\1[REDACTED]", text)
+    text = QUERY_SECRET_RE.sub(r"\1[REDACTED]", text)
+    text = EMAIL_RE.sub("[REDACTED_EMAIL]", text)
+    return text[:limit]
+
+
+def safe_base_url(value: object) -> str:
+    """Keep the origin only so reports do not retain private paths or queries."""
+    text = safe_text(value, 500)
+    try:
+        parsed = urlsplit(text)
+        if parsed.scheme and parsed.hostname:
+            netloc = parsed.hostname
+            if parsed.port:
+                netloc = f"{netloc}:{parsed.port}"
+            return urlunsplit((parsed.scheme, netloc, "", "", ""))
+    except ValueError:
+        pass
+    return text
+
+
+def project_root(value: str | os.PathLike[str]) -> Path:
+    return Path(value).expanduser().resolve()
+
+
+def load_json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"could not read JSON {path}: {error}") from error
+    if not isinstance(value, dict):
+        raise ValueError(f"JSON root must be an object: {path}")
+    return value
+
+
+def scenario_records(path: Path) -> list[dict]:
+    manifest = load_json(path)
+    scenarios = manifest.get("scenarios")
+    if not isinstance(scenarios, list) or not scenarios:
+        raise ValueError("scenario manifest must contain a non-empty scenarios array")
+    result = []
+    seen: set[str] = set()
+    for item in scenarios:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            raise ValueError("each scenario must be an object with an id")
+        scenario_id = item["id"]
+        if scenario_id in seen:
+            raise ValueError(f"duplicate scenario id: {scenario_id}")
+        seen.add(scenario_id)
+        result.append(item)
+    return result
+
+
+def run_directory(project: Path) -> Path:
+    directory = project / ".maggie" / "qa-runs"
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def normal_run_id(value: str | None) -> str:
+    if value:
+        value = re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip("-")
+        if not value:
+            raise ValueError("run id cannot be empty")
+        return value
+    return "qa-" + datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+
+
+def run_path(project: Path, value: str) -> Path:
+    candidate = Path(value).expanduser()
+    if candidate.suffix == ".json" or candidate.parent != Path("."):
+        path = candidate if candidate.is_absolute() else project / candidate
+    else:
+        path = run_directory(project) / f"{normal_run_id(value)}.json"
+    path = path.resolve()
+    if not path.is_file():
+        raise ValueError(f"QA run does not exist: {path}")
+    return path
+
+
+def write_json(path: Path, value: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def calculate(run: dict) -> dict:
+    counts = {status: 0 for status in VALID_STATUSES}
+    lifecycle_counts = {"ready": 0, "fix_pending": 0}
+    for item in run.get("scenarios", {}).values():
+        status = item.get("status", "pending")
+        counts[status] = counts.get(status, 0) + 1
+        lifecycle_counts["fix_pending" if item.get("lifecycle") == "fix_pending" else "ready"] += 1
+    if counts["fail"]:
+        gate = "fail"
+    elif counts["pending"] or counts["blocked"] or counts["inconclusive"]:
+        gate = "blocked"
+    else:
+        gate = "pass"
+    return {"gate": gate, "counts": counts, "lifecycle": lifecycle_counts, "total": sum(counts.values())}
+
+
+def start(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    manifest_path = project_root(args.scenario_file) if Path(args.scenario_file).is_absolute() else project / args.scenario_file
+    records = scenario_records(manifest_path)
+    run_id = normal_run_id(args.run_id)
+    path = run_directory(project) / f"{run_id}.json"
+    if path.exists():
+        raise ValueError(f"QA run already exists: {path}")
+    scenarios = {
+        item["id"]: {
+            "id": item["id"],
+            "group": item.get("group", ""),
+            "title": item.get("title", ""),
+            "priority": item.get("priority", "P2"),
+            "routes": item.get("routes", []),
+            "auth": item.get("auth", ""),
+            "browser": bool(item.get("browser", True)),
+            "status": "pending",
+            "lifecycle": "ready",
+            "history": [],
+        }
+        for item in records
+    }
+    try:
+        manifest_label = str(manifest_path.relative_to(project))
+    except ValueError:
+        # Do not persist an absolute path outside the project. The basename is
+        # enough to identify the source without leaking a local filesystem
+        # layout into a shareable run artifact.
+        manifest_label = manifest_path.name
+    run = {
+        "schemaVersion": "maggie.qa-run.v1",
+        "runId": run_id,
+        "createdAt": now(),
+        "updatedAt": now(),
+        "project": hashlib.sha256(str(project).encode()).hexdigest()[:16],
+        "environment": safe_text(args.environment),
+        "baseUrl": safe_base_url(args.base_url),
+        "browser": safe_text(args.browser),
+        "commit": safe_text(args.commit),
+        "release": safe_text(args.release),
+        "scenarioManifest": manifest_label,
+        "scenarios": scenarios,
+    }
+    run["summary"] = calculate(run)
+    write_json(path, run)
+    print(json.dumps({"runId": run_id, "path": str(path), "summary": run["summary"]}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def evidence(value: str, project: Path) -> dict:
+    clean = safe_text(value, 500)
+    path = Path(value).expanduser()
+    if path.is_file():
+        resolved = path.resolve()
+        try:
+            display = str(resolved.relative_to(project))
+        except ValueError:
+            display = resolved.name
+        return {"path": display, "sha256": hashlib.sha256(resolved.read_bytes()).hexdigest()}
+    return {"reference": clean}
+
+
+def record(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    path = run_path(project, args.run)
+    run = load_json(path)
+    scenarios = run.get("scenarios", {})
+    item = scenarios.get(args.scenario)
+    if not isinstance(item, dict):
+        raise ValueError(f"scenario is not in this run: {args.scenario}")
+    phase = args.phase
+    if phase not in VALID_PHASES:
+        raise ValueError(f"phase must be one of: {', '.join(sorted(VALID_PHASES))}")
+    if phase in {"test", "retest"} and args.status not in VALID_STATUSES - {"pending"}:
+        raise ValueError("test and retest require status pass, fail, blocked or inconclusive")
+    if phase == "fix" and not args.resolution:
+        raise ValueError("fix requires --resolution")
+    if phase == "fix" and item.get("status") != "fail":
+        raise ValueError("fix can only follow a recorded fail; use retest after a blocked or inconclusive run")
+    if phase == "retest" and not any(event.get("phase") == "test" for event in item.get("history", [])):
+        raise ValueError("retest requires an earlier test event")
+    if phase == "retest" and item.get("status") == "fail" and not any(event.get("phase") == "fix" for event in item.get("history", [])):
+        raise ValueError("a failed scenario must have a recorded fix before retest")
+    if phase == "test" and args.status == "fail" and not (args.expected and args.actual and args.error_fingerprint):
+        raise ValueError("a failed test requires --expected, --actual and --error-fingerprint")
+    event = {
+        "at": now(),
+        "phase": phase,
+        "status": args.status if phase != "fix" else "fix_pending",
+        "summary": safe_text(args.summary),
+        "expected": safe_text(args.expected),
+        "actual": safe_text(args.actual),
+        "errorFingerprint": safe_text(args.error_fingerprint, 300),
+        "issue": safe_text(args.issue, 500),
+        "resolution": safe_text(args.resolution),
+        "validation": safe_text(args.validation),
+        "evidence": [evidence(value, project) for value in args.evidence],
+    }
+    item.setdefault("history", []).append(event)
+    if phase == "fix":
+        item["lifecycle"] = "fix_pending"
+    else:
+        item["status"] = args.status
+        item["lifecycle"] = "ready"
+    run["updatedAt"] = now()
+    run["summary"] = calculate(run)
+    write_json(path, run)
+    print(json.dumps({"runId": run.get("runId"), "scenario": args.scenario, "event": event, "summary": run["summary"]}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def markdown(run: dict) -> str:
+    summary = run.get("summary") or calculate(run)
+    lines = [
+        f"# Maggie QA run `{run.get('runId', '')}`",
+        "",
+        "<!-- Generated by maggie_qa_workflow.py. Evidence is metadata-only. -->",
+        "",
+        f"- Environment: `{run.get('environment') or 'not provided'}`",
+        f"- Base URL: `{run.get('baseUrl') or 'not provided'}`",
+        f"- Browser: `{run.get('browser') or 'not provided'}`",
+        f"- Commit/release: `{run.get('commit') or 'not provided'}` / `{run.get('release') or 'not provided'}`",
+        f"- Gate: **{summary.get('gate', 'blocked').upper()}**",
+        "",
+        "## Scenario summary",
+        "",
+        "| ID | Priority | Scenario | Status | Lifecycle | Last result |",
+        "|---|---|---|---|---|---|",
+    ]
+    for scenario in run.get("scenarios", {}).values():
+        history = scenario.get("history", [])
+        last = history[-1] if history else {}
+        result = safe_text(last.get("summary") or last.get("actual") or "Not tested", 180).replace("|", "\\|")
+        lines.append(f"| {scenario.get('id')} | {scenario.get('priority')} | {scenario.get('title')} | **{scenario.get('status')}** | {scenario.get('lifecycle')} | {result} |")
+    lines += ["", "## Fix and retest history", ""]
+    for scenario in run.get("scenarios", {}).values():
+        for event in scenario.get("history", []):
+            lines.append(f"### {scenario.get('id')} — {event.get('phase')} ({event.get('at')})")
+            lines.append("")
+            if event.get("summary"): lines.append(f"- Summary: {event['summary']}")
+            if event.get("expected"): lines.append(f"- Expected: {event['expected']}")
+            if event.get("actual"): lines.append(f"- Actual: {event['actual']}")
+            if event.get("errorFingerprint"): lines.append(f"- Error fingerprint: `{event['errorFingerprint']}`")
+            if event.get("resolution"): lines.append(f"- Resolution: {event['resolution']}")
+            if event.get("validation"): lines.append(f"- Validation: {event['validation']}")
+            references = event.get("evidence", [])
+            if references: lines.append(f"- Evidence: {', '.join(str(value.get('path') or value.get('reference')) for value in references)}")
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def summary(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    run = load_json(run_path(project, args.run))
+    result = run.get("summary") or calculate(run)
+    if args.format == "markdown":
+        print(markdown(run))
+    else:
+        print(json.dumps({"runId": run.get("runId"), **result}, ensure_ascii=False, indent=2))
+    return 0 if result.get("gate") == "pass" else 1
+
+
+def export_run(args: argparse.Namespace) -> int:
+    project = project_root(args.project)
+    run = load_json(run_path(project, args.run))
+    output = Path(args.output).expanduser()
+    if not output.is_absolute(): output = project / output
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(markdown(run), encoding="utf-8")
+    print(json.dumps({"runId": run.get("runId"), "output": str(output.resolve()), "gate": run.get("summary", {}).get("gate")}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(description=__doc__)
+    root.add_argument("--project", default=".")
+    commands = root.add_subparsers(dest="command", required=True)
+
+    start_parser = commands.add_parser("start")
+    start_parser.add_argument("--project", default=argparse.SUPPRESS)
+    start_parser.add_argument("--scenario-file", default=str(DEFAULT_SCENARIOS))
+    start_parser.add_argument("--run-id")
+    start_parser.add_argument("--environment", required=True)
+    start_parser.add_argument("--base-url", required=True)
+    start_parser.add_argument("--browser", default="chrome")
+    start_parser.add_argument("--commit", default="")
+    start_parser.add_argument("--release", default="")
+
+    record_parser = commands.add_parser("record")
+    record_parser.add_argument("--project", default=argparse.SUPPRESS)
+    record_parser.add_argument("--run", required=True)
+    record_parser.add_argument("--scenario", required=True)
+    record_parser.add_argument("--phase", choices=sorted(VALID_PHASES), required=True)
+    record_parser.add_argument("--status", choices=sorted(VALID_STATUSES - {"pending"}))
+    record_parser.add_argument("--summary", default="")
+    record_parser.add_argument("--expected", default="")
+    record_parser.add_argument("--actual", default="")
+    record_parser.add_argument("--error-fingerprint", default="")
+    record_parser.add_argument("--issue", default="")
+    record_parser.add_argument("--resolution", default="")
+    record_parser.add_argument("--validation", default="")
+    record_parser.add_argument("--evidence", action="append", default=[])
+
+    for name in ("summary", "export"):
+        command = commands.add_parser(name)
+        command.add_argument("--project", default=argparse.SUPPRESS)
+        command.add_argument("--run", required=True)
+        if name == "summary": command.add_argument("--format", choices=("json", "markdown"), default="json")
+        else: command.add_argument("--output", required=True)
+    return root
+
+
+def main() -> int:
+    args = parser().parse_args()
+    try:
+        if args.command == "start": return start(args)
+        if args.command == "record": return record(args)
+        if args.command == "summary": return summary(args)
+        return export_run(args)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"QA workflow error: {safe_text(error)}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())