@topy-ai/maggie 0.7.31 → 0.7.32

package/bundled-tools/clis/maggie_blog.py

@@ -12,6 +12,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from maggie_blog import BlogStore, review_settings_from_adapter  # noqa: E402
 from localization_runner import process_adapter
 from integration_state import integration_state  # noqa: E402
+from maggie_blog_publish import validate_auto_publish  # noqa: E402
 
 
 def main() -> int:
@@ -28,6 +29,9 @@ def main() -> int:
     ingest = sub.add_parser("ingest"); ingest.add_argument("--project", type=Path, default=Path.cwd()); ingest.add_argument("--input", type=Path, required=True); ingest.add_argument("--source", default="local"); ingest.add_argument("--confirm", action="store_true")
     validate = sub.add_parser("validate"); validate.add_argument("--project", type=Path, default=Path.cwd())
     gate = sub.add_parser("check-gate", help="report whether generated content requires review before publication"); gate.add_argument("--project", type=Path, default=Path.cwd()); gate.add_argument("--settings-file", type=Path, help="sanitized host settings JSON"); gate.add_argument("--adapter-command", help="trusted provider JSON argv array that prints sanitized settings JSON"); gate.add_argument("--timeout", type=int, default=120)
+    auto_gate = sub.add_parser("auto-publish-gate", help="validate explicit opt-in evidence before an automated publish")
+    auto_gate.add_argument("--evidence", type=Path, required=True)
+    auto_gate.add_argument("--output", type=Path, required=True)
     approve = sub.add_parser("approve"); approve.add_argument("--project", type=Path, default=Path.cwd()); approve.add_argument("--slug", required=True); approve.add_argument("--actor", required=True); approve.add_argument("--reason", required=True); approve.add_argument("--confirm", action="store_true")
     publish = sub.add_parser("publish"); publish.add_argument("--project", type=Path, default=Path.cwd()); publish.add_argument("--slug", required=True); publish.add_argument("--actor", required=True); publish.add_argument("--reason", required=True); publish.add_argument("--confirm", action="store_true")
     sitemap = sub.add_parser("sitemap"); sitemap.add_argument("--project", type=Path, default=Path.cwd())
@@ -35,6 +39,15 @@ def main() -> int:
     state = sub.add_parser("integration-state"); state.add_argument("--configured", action="store_true"); state.add_argument("--consent-required", action="store_true"); state.add_argument("--consent", action="store_true"); state.add_argument("--authorized", action="store_true"); state.add_argument("--error")
     rollback = sub.add_parser("rollback"); rollback.add_argument("--project", type=Path, default=Path.cwd()); rollback.add_argument("--backup"); rollback.add_argument("--confirm", action="store_true")
     args = parser.parse_args()
+    if args.command == "auto-publish-gate":
+        try:
+            result = validate_auto_publish(json.loads(args.evidence.resolve().read_text(encoding="utf-8")))
+            args.output.resolve().parent.mkdir(parents=True, exist_ok=True)
+            args.output.resolve().write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"maggie-blog: {error}", file=sys.stderr); return 1
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result["passed"] else 1
     if args.command == "integration-state":
         result = integration_state(configured=args.configured, consent_required=args.consent_required, consent=args.consent, authorized=args.authorized, error=args.error)
         print(json.dumps(result, indent=2, ensure_ascii=False))

package/bundled-tools/clis/maggie_dash.py

@@ -27,6 +27,7 @@ from maggie_sections import catalogue, remap_translations, section_id_migration,
 from maggie_quality import validate_variant_copy, validate_media_uniqueness, classify_inventory, validate_bindings, validate_reconcile_contract  # noqa: E402
 from maggie_api_contract import load_api_contract_source, validate_api_contract  # noqa: E402
 from maggie_dash_runtime import validate_runtime_evidence  # noqa: E402
+from maggie_dash_panels import validate_panel_report  # noqa: E402
 from maggie_schema_audit import audit_schema_inventory  # noqa: E402
 from route_imports import classify_bindings  # noqa: E402
 
@@ -374,6 +375,18 @@ def command_ui(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_panels(args: argparse.Namespace) -> int:
+    value = json.loads(Path(args.report).resolve().read_text(encoding="utf-8"))
+    result = validate_panel_report(value)
+    if args.output:
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        result["output"] = str(output)
+    emit(result)
+    return 0 if result["passed"] else 1
+
+
 def command_sections(args: argparse.Namespace) -> int:
     if args.sections_command == "remap-translations":
         require_confirm(args)
@@ -711,6 +724,10 @@ def parser() -> argparse.ArgumentParser:
     conformance.add_argument("--evidence", required=True, help="sanitized endpoint observations JSON")
     conformance.add_argument("--output")
     conformance.set_defaults(func=command_conformance)
+    panels = sub.add_parser("panels-validate", help="validate dashboard panel source and freshness evidence")
+    panels.add_argument("--report", required=True, help="sanitized measurement-panel evidence JSON")
+    panels.add_argument("--output")
+    panels.set_defaults(func=command_panels)
     schema_audit = sub.add_parser("schema-audit", help="find declared tables with missing reader evidence")
     schema_audit.add_argument("--inventory", required=True, help="host-produced schema inventory JSON")
     schema_audit.add_argument("--fail-on-unread", action="store_true")

package/bundled-tools/clis/maggie_deployment.py

@@ -6,10 +6,77 @@ import argparse
 import json
 import re
 import subprocess
+import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
 
+DEPLOYMENT_CREDENTIALS = (
+    "DEPLOY_SERVER_IP",
+    "DEPLOY_SERVER_SSH_USER",
+    "DEPLOY_SERVER_SSH_PASSWORD",
+    "DEPLOY_SERVER_SSH_SUDOER",
+)
+
+
+def parse_env_file(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip("\"'")
+    return values
+
+
+def credential_preflight(env_file: Path, expected_host: str | None = None) -> dict:
+    """Check deployment variable presence without returning secret values."""
+    errors: list[str] = []
+    try:
+        values = parse_env_file(env_file)
+    except OSError as error:
+        values = {}
+        errors.append(f"cannot read env file: {error}")
+    present = {name: bool(values.get(name, "").strip()) for name in DEPLOYMENT_CREDENTIALS}
+    if not all(present.values()):
+        errors.append("required deployment credentials are missing from the env file")
+    host_guard = {"status": "not_requested", "matches": None}
+    if expected_host:
+        host_guard = {"status": "passed" if values.get("DEPLOY_SERVER_IP") == expected_host else "failed", "matches": values.get("DEPLOY_SERVER_IP") == expected_host}
+        if host_guard["status"] == "failed":
+            errors.append("DEPLOY_SERVER_IP does not match --expected-host")
+    return {
+        "schemaVersion": "maggie-deployment-credentials.v1",
+        "envFileProvided": True,
+        "credentialSource": "project-env-file",
+        "variables": present,
+        "hostGuard": host_guard,
+        "passed": not errors,
+        "errors": errors,
+        "mutation": "not executed",
+    }
+
+
+def credential_preflight_main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Check named deployment credentials without printing their values.")
+    parser.add_argument("--env-file", required=True)
+    parser.add_argument("--expected-host")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    result = credential_preflight(Path(args.env_file).expanduser().resolve(), args.expected_host)
+    if args.output:
+        output = Path(args.output).resolve()
+        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 preflight(project: Path, target: str, environment: str) -> dict:
     package_path = project / "package.json"
     package = json.loads(package_path.read_text(encoding="utf-8")) if package_path.exists() else {}
@@ -78,23 +145,37 @@ def preflight(project: Path, target: str, environment: str) -> dict:
     return result
 
 
-def vps_plan(domain: str, service: str, release_root: str, node_port: int | None) -> dict:
+def vps_plan(domain: str, service: str, release_root: str, node_port: int | None, deployer_user: str = "maggie-deploy") -> dict:
     """Create reviewable, secret-free VPS service and reverse-proxy artifacts."""
     if not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?", domain):
         raise ValueError("domain must be a hostname without a scheme or path")
     if not re.fullmatch(r"[A-Za-z0-9_.@-]+", service):
         raise ValueError("service must contain only safe systemd name characters")
+    if not re.fullmatch(r"[a-z_][a-z0-9_-]{0,31}\$?", deployer_user):
+        raise ValueError("deployer user must be a safe local account name")
     if node_port is None:
         raise ValueError("node port must be supplied explicitly; choose an unused port for this host")
     if not 1024 <= node_port <= 65535:
         raise ValueError("node port must be between 1024 and 65535")
     root = release_root.rstrip("/")
     current = f"{root}/current"
+    privileged_commands = [
+        f"/bin/systemctl restart {service}",
+        f"/bin/systemctl is-active {service}",
+    ]
     return {
         "schema_version": "1.0",
         "provider": "vps-with-cloudflare-dns",
         "domain": domain,
         "service": service,
+        "deployer_user": deployer_user,
+        "application_user": "www-data",
+        "privileged_commands": privileged_commands,
+        "sudoers": {
+            "user": deployer_user,
+            "commands": privileged_commands,
+            "policy": "exact service commands only; no shell, wildcard, or broad sudo",
+        },
         "release_root": root,
         "current_release": current,
         "node_port": node_port,
@@ -111,9 +192,9 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
         "commands": {
             "stage": "npm ci && npm run typecheck && npm run build",
             "switch": f"ln -sfn {root}/releases/<release> {current}",
-            "restart": f"systemctl restart {service}",
-            "verify": f"systemctl is-active {service} && curl -fsS https://{domain}/robots.txt && curl -fsS https://{domain}/sitemap.xml",
-            "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && systemctl restart {service}",
+            "restart": f"sudo -n /bin/systemctl restart {service}",
+            "verify": f"sudo -n /bin/systemctl is-active {service} && curl -fsS https://{domain}/robots.txt && curl -fsS https://{domain}/sitemap.xml",
+            "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && sudo -n /bin/systemctl restart {service}",
             "data_rollback": "restore the matching data checkpoint before restarting the previous code release",
         },
         "files": {
@@ -285,8 +366,8 @@ if [ -d "$CURRENT/.agents" ]; then cp -a "$CURRENT/.agents" "$RELEASE/.agents";
 if [ -d "$CURRENT/.claude" ]; then cp -a "$CURRENT/.claude" "$RELEASE/.claude"; fi
 
 ln -sfn "$RELEASE" "$CURRENT"
-systemctl restart "{service}"
-systemctl is-active --quiet "{service}"
+sudo -n /bin/systemctl restart "{service}"
+sudo -n /bin/systemctl is-active --quiet "{service}"
 curl -fsS "https://{domain}/robots.txt" >/dev/null
 curl -fsS "https://{domain}/sitemap.xml" >/dev/null
 
@@ -307,6 +388,8 @@ def write_release_runner(path: Path, plan: dict) -> None:
 
 
 def main() -> int:
+    if sys.argv[1:2] == ["credential-preflight"]:
+        return credential_preflight_main(sys.argv[2:])
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("project", nargs="?", default=".")
     parser.add_argument("--target", choices=("detected", "cloudflare", "vps", "vps-with-cloudflare-dns", "gcp", "aws"), default="detected")
@@ -317,6 +400,7 @@ def main() -> int:
     parser.add_argument("--service", default="maggie-site", help="systemd service name")
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
     parser.add_argument("--node-port", type=int, required=False, default=None, help="unused host port; required with --vps-plan")
+    parser.add_argument("--deployer-user", default="maggie-deploy", help="dedicated least-privilege SSH/deploy account")
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
     parser.add_argument("--runner-output", help="write a reviewable ordered VPS release runner")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
@@ -334,7 +418,7 @@ def main() -> int:
         if args.vps_plan:
             if not args.domain:
                 parser.error("--domain is required with --vps-plan")
-            plan = vps_plan(args.domain, args.service, args.release_root, args.node_port)
+            plan = vps_plan(args.domain, args.service, args.release_root, args.node_port, args.deployer_user)
             if args.plan_dir:
                 write_vps_plan(Path(args.plan_dir).resolve(), plan)
             if args.runner_output:

package/bundled-tools/clis/maggie_feedback.py

@@ -151,10 +151,20 @@ def collect(args: argparse.Namespace) -> int:
     if batch_id:
         if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
             raise ValueError("batch ID is invalid")
-        if not isinstance(batch_index, int) or isinstance(batch_index, bool) or batch_index < 0:
-            raise ValueError("batch index is required when batch ID is provided")
-        if not isinstance(batch_size, int) or isinstance(batch_size, bool) or batch_size < 1 or batch_index >= batch_size:
-            raise ValueError("batch size must be positive and greater than batch index")
+        batch_base = getattr(args, "batch_base", 0)
+        if batch_base not in (0, 1):
+            raise ValueError("batch base must be 0 or 1")
+        if not isinstance(batch_index, int) or isinstance(batch_index, bool):
+            raise ValueError(f"batch index is required and must be {batch_base}-based when batch ID is provided")
+        if not isinstance(batch_size, int) or isinstance(batch_size, bool) or batch_size < 1:
+            raise ValueError("batch size must be a positive integer")
+        if batch_base == 1 and not 1 <= batch_index <= batch_size:
+            raise ValueError(f"1-based batch index must be between 1 and {batch_size} inclusive")
+        if batch_base == 0 and not 0 <= batch_index < batch_size:
+            raise ValueError(f"0-based batch index must be between 0 and {batch_size - 1} inclusive; use --batch-base 1 for 1-based input")
+        # Persist one canonical representation so batch review and the hosted
+        # API do not have to guess which indexing convention was used.
+        batch_index -= batch_base
     priority = safe_text(getattr(args, "priority", "") or "normal").lower()
     if priority not in {"low", "normal", "high", "critical"}:
         raise ValueError("priority must be low, normal, high, or critical")
@@ -428,6 +438,10 @@ def main() -> int:
     collect_parser.add_argument("--batch-id", default="")
     collect_parser.add_argument("--batch-index", type=int)
     collect_parser.add_argument("--batch-size", type=int)
+    collect_parser.add_argument(
+        "--batch-base", type=int, choices=(0, 1), default=0,
+        help="indexing convention for --batch-index (default: 0; use 1 for 1-based input)",
+    )
     collect_parser.add_argument("--priority", choices=("low", "normal", "high", "critical"), default="normal")
     collect_parser.add_argument("--affected-cli", default="")
     collect_parser.add_argument("--route-id", dest="route_ids", action="append", default=[])

package/bundled-tools/clis/maggie_icon_release_gate.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Validate the complete source-to-browser icon release gate."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+
+def validate(icon_report: object, browser_report: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(icon_report, dict):
+        errors.append("icon report must be an object")
+        icon_report = {}
+    if not isinstance(browser_report, dict):
+        errors.append("browser report must be an object")
+        browser_report = {}
+    source_ok = (
+        icon_report.get("schemaVersion") == "maggie-icon-inventory.v1"
+        and icon_report.get("status") == "pass"
+        and icon_report.get("missing") == []
+        and icon_report.get("unknown") == []
+    )
+    if not source_ok:
+        errors.append("source/runtime icon inventory did not pass")
+    browser_ok = browser_report.get("schemaVersion") == "maggie-icon-browser-evidence.v1" and browser_report.get("passed") is True and isinstance(browser_report.get("routes"), list) and bool(browser_report["routes"])
+    if not browser_ok:
+        errors.append("browser icon evidence did not pass")
+    icons = browser_report.get("icons") if isinstance(browser_report.get("icons"), list) else []
+    if not icons:
+        errors.append("browser evidence must include painted icons")
+    invalid: list[str] = []
+    for index, icon in enumerate(icons):
+        name = str(icon.get("name") or f"icon-{index}") if isinstance(icon, dict) else f"icon-{index}"
+        if not isinstance(icon, dict) or icon.get("visible") is not True or not isinstance(icon.get("width"), (int, float)) or icon["width"] <= 0 or not isinstance(icon.get("height"), (int, float)) or icon["height"] <= 0 or not str(icon.get("accessibleName") or "").strip():
+            invalid.append(name)
+        if not isinstance(icon, dict) or not isinstance(icon.get("assetStatus"), int) or not 200 <= icon["assetStatus"] <= 299:
+            invalid.append(name)
+    if invalid:
+        errors.append("browser icon evidence has invisible, zero-size, inaccessible, or unserved glyphs")
+    return {
+        "schemaVersion": "maggie-icon-release-gate.v1",
+        "passed": not errors,
+        "errors": sorted(set(errors)),
+        "checks": {
+            "sourceRuntime": source_ok,
+            "servedAssets": browser_ok and not bool(invalid),
+            "paintedGlyphs": bool(icons) and not bool(invalid),
+            "accessibility": bool(icons) and not bool(invalid),
+        },
+        "iconCount": len(icons),
+        "invalidIcons": sorted(set(invalid)),
+        "mutation": "not executed",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--icon-report", required=True)
+    parser.add_argument("--browser-report", required=True)
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+    try:
+        icon = json.loads(Path(args.icon_report).resolve().read_text(encoding="utf-8"))
+        browser = json.loads(Path(args.browser_report).resolve().read_text(encoding="utf-8"))
+        result = validate(icon, browser)
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    except (OSError, json.JSONDecodeError) as error:
+        result = {"schemaVersion": "maggie-icon-release-gate.v1", "passed": False, "errors": [f"cannot read icon evidence: {error}"], "mutation": "not executed"}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_migration.py

@@ -58,6 +58,8 @@ def validate_project(project: Path, environment: str) -> dict:
 IDENTITY_SCHEMA = "maggie-database-identity.v1"
 PREFLIGHT_SCHEMA = "maggie-migration-preflight.v1"
 SAFE_NAME = re.compile(r"^[A-Za-z][A-Za-z0-9_.:-]{0,119}$")
+LEDGER_SCHEMA = "maggie-migration-ledger.v1"
+MIGRATION_FILE = re.compile(r"^(\d{1,9})[_-][A-Za-z0-9][A-Za-z0-9_.-]*\.sql$")
 
 
 def _identity_fingerprint(identity: dict) -> str:
@@ -160,11 +162,80 @@ def preflight_main(argv: list[str]) -> int:
     print(json.dumps(result, indent=2)); return 0 if not errors else 1
 
 
+def reconcile_main(argv: list[str]) -> int:
+    """Compare host-reported applied migrations with local migration files."""
+    parser = argparse.ArgumentParser(description="Build a read-only ordered plan for migrations missing from the server ledger.")
+    parser.add_argument("--evidence", required=True, help="host-produced ledger evidence JSON")
+    parser.add_argument("--migration-dir", required=True, help="directory containing numbered .sql migrations")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    errors: list[str] = []
+    try:
+        evidence = json.loads(Path(args.evidence).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        evidence = {}
+        errors.append(f"cannot read migration ledger evidence: {error}")
+    if not isinstance(evidence, dict):
+        evidence = {}
+        errors.append("migration ledger evidence must be an object")
+    if evidence.get("schemaVersion") != LEDGER_SCHEMA:
+        errors.append(f"schemaVersion must be {LEDGER_SCHEMA}")
+    if evidence.get("migrationTable") != "maggie_schema_migrations":
+        errors.append("migrationTable must be maggie_schema_migrations")
+    if evidence.get("environment") not in {"development", "staging", "production"}:
+        errors.append("environment is invalid")
+    applied = evidence.get("appliedVersions")
+    if not isinstance(applied, list) or any(not re.fullmatch(r"\d{1,9}", str(item)) for item in applied) or len(set(map(str, applied))) != len(applied):
+        errors.append("appliedVersions must be a unique array of numeric versions")
+        applied = []
+    applied_set = {str(item).zfill(3) for item in applied}
+    files: list[tuple[str, str]] = []
+    migration_dir = Path(args.migration_dir).resolve()
+    try:
+        entries = sorted(migration_dir.iterdir())
+    except OSError as error:
+        entries = []
+        errors.append(f"cannot read migration directory: {error}")
+    for entry in entries:
+        if not entry.is_file():
+            continue
+        match = MIGRATION_FILE.fullmatch(entry.name)
+        if match:
+            files.append((match.group(1).zfill(3), entry.name))
+    if not files:
+        errors.append("migration directory contains no numbered .sql files")
+    versions = [version for version, _ in files]
+    if len(set(versions)) != len(versions):
+        errors.append("migration directory contains duplicate migration versions")
+    ordered = [{"version": version, "file": name, "applied": version in applied_set} for version, name in sorted(files)]
+    missing = [item for item in ordered if not item["applied"]]
+    result = {
+        "schemaVersion": "maggie-migration-ledger-result.v1",
+        "environment": evidence.get("environment"),
+        "migrationTable": evidence.get("migrationTable"),
+        "passed": not errors and not missing,
+        "errors": errors,
+        "appliedVersions": sorted(applied_set),
+        "orderedMigrations": ordered,
+        "missing": missing,
+        "nextAction": "activate only after applying missing migrations in order" if missing else "ledger matches migration directory",
+        "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] == ["preflight"]:
         return preflight_main(sys.argv[2:])
     if sys.argv[1:2] == ["identity"]:
         return identity_main(sys.argv[2:])
+    if sys.argv[1:2] == ["reconcile"]:
+        return reconcile_main(sys.argv[2:])
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("manifest", nargs="?")
     parser.add_argument("--project")

package/bundled-tools/clis/maggie_release_manifest.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Validate a cross-workflow, secret-free release evidence manifest."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA = "maggie-release-evidence.v1"
+REQUIRED = ("routes", "migrations", "runtimeChecks", "assets", "icons", "edgeCache", "browser", "rendered", "rollback")
+VERSION = re.compile(r"0\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$")
+COMMIT = re.compile(r"[0-9a-fA-F]{7,64}$")
+SAFE_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$")
+
+
+def validate(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": "maggie-release-manifest.v1", "passed": False, "errors": ["evidence must be an object"], "mutation": "not executed"}
+    if value.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    release_id = value.get("releaseId")
+    if not isinstance(release_id, str) or not SAFE_ID.fullmatch(release_id):
+        errors.append("releaseId must be a safe identifier")
+    commit = value.get("commit")
+    if not isinstance(commit, str) or not COMMIT.fullmatch(commit):
+        errors.append("commit must be a git SHA")
+    version = value.get("maggieVersion")
+    if not isinstance(version, str) or not VERSION.fullmatch(version):
+        errors.append("maggieVersion must remain on the 0.x release line")
+    evidence: dict[str, Any] = {}
+    for name in REQUIRED:
+        item = value.get(name)
+        if not isinstance(item, dict):
+            errors.append(f"{name} evidence must be an object")
+            continue
+        if item.get("passed") is not True:
+            errors.append(f"{name}.passed must be true")
+        fingerprint = item.get("fingerprint")
+        if name in {"routes", "assets", "icons"} and (not isinstance(fingerprint, str) or not SAFE_ID.fullmatch(fingerprint)):
+            errors.append(f"{name}.fingerprint must be a safe release fingerprint")
+        evidence[name] = {
+            "passed": item.get("passed") is True,
+            "fingerprint": fingerprint if isinstance(fingerprint, str) else None,
+            "release": str(item.get("release") or "") if name in {"edgeCache", "browser", "rendered", "rollback"} else None,
+        }
+    return {
+        "schemaVersion": "maggie-release-manifest.v1",
+        "releaseId": release_id if isinstance(release_id, str) else None,
+        "commit": commit if isinstance(commit, str) else None,
+        "maggieVersion": version if isinstance(version, str) else None,
+        "passed": not errors,
+        "errors": sorted(set(errors)),
+        "evidence": evidence,
+        "mutation": "not executed",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--evidence", required=True, help="secret-free cross-workflow evidence JSON")
+    parser.add_argument("--output", required=True, help="normalized release manifest output")
+    args = parser.parse_args()
+    try:
+        value = json.loads(Path(args.evidence).resolve().read_text(encoding="utf-8"))
+        result = validate(value)
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    except (OSError, json.JSONDecodeError) as error:
+        result = {"schemaVersion": "maggie-release-manifest.v1", "passed": False, "errors": [f"cannot read release evidence: {error}"], "mutation": "not executed"}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_runtime_preflight.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Classify deployment runtime checks with actionable remediation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+
+SCHEMA = "maggie-runtime-preflight.v1"
+REQUIRED = ("dependencies", "browser", "worker", "database", "routes")
+STATUSES = {"pass", "missing", "incompatible", "misconfigured", "insufficient", "mismatch", "unknown"}
+
+
+def validate(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    checks: dict[str, dict[str, str]] = {}
+    if not isinstance(value, dict):
+        return {"schemaVersion": "maggie-runtime-preflight-result.v1", "passed": False, "errors": ["evidence must be an object"], "checks": {}, "mutation": "not executed"}
+    if value.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    if value.get("environment") not in {"development", "staging", "production"}:
+        errors.append("environment is invalid")
+    input_checks = value.get("checks")
+    if not isinstance(input_checks, dict):
+        input_checks = {}
+        errors.append("checks must be an object")
+    for name in REQUIRED:
+        item = input_checks.get(name)
+        if not isinstance(item, dict):
+            errors.append(f"checks.{name} must be an object")
+            checks[name] = {"status": "unknown", "remediation": "Collect this host check before deployment."}
+            continue
+        status = item.get("status")
+        remediation = str(item.get("remediation") or "").strip()
+        if status not in STATUSES:
+            errors.append(f"checks.{name}.status is unsupported")
+            status = "unknown"
+        if not remediation:
+            errors.append(f"checks.{name}.remediation is required")
+        checks[name] = {"status": status, "remediation": remediation}
+        if status != "pass" and not remediation:
+            errors.append(f"checks.{name} needs actionable remediation")
+    failed = sorted(name for name, item in checks.items() if item["status"] != "pass")
+    return {
+        "schemaVersion": "maggie-runtime-preflight-result.v1",
+        "environment": value.get("environment"),
+        "passed": not errors and not failed,
+        "errors": sorted(set(errors)),
+        "checks": checks,
+        "failedChecks": failed,
+        "mutation": "not executed",
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--evidence", required=True)
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+    try:
+        value = json.loads(Path(args.evidence).resolve().read_text(encoding="utf-8"))
+        result = validate(value)
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    except (OSError, json.JSONDecodeError) as error:
+        result = {"schemaVersion": "maggie-runtime-preflight-result.v1", "passed": False, "errors": [f"cannot read runtime evidence: {error}"], "checks": {}, "mutation": "not executed"}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())