@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-tools/clis/maggie_clone_to_template.py

@@ -58,6 +58,8 @@ def job_args(job: dict, marketplace: Path, template_id: str) -> argparse.Namespa
     values.setdefault("tag", [])
     values.setdefault("site_url", None)
     values.setdefault("sample", None)
+    values.setdefault("display_name", None)
+    values.setdefault("display_description", None)
     return argparse.Namespace(**values)
 
 
@@ -169,6 +171,7 @@ def plan_job(args: argparse.Namespace) -> int:
         "options": {
             "provider": args.provider, "brand": args.brand, "category": args.category,
             "tag": args.tag, "site_url": args.site_url, "sample": str(args.sample) if args.sample else None,
+            "display_name": getattr(args, "display_name", None), "display_description": getattr(args, "display_description", None),
         },
         "history": [{"phase": "STARTED", "at": now()}],
     }
@@ -222,6 +225,13 @@ def package_step(args: argparse.Namespace) -> int:
         command.extend(("--site-url", options.site_url))
     if options.sample:
         command.extend(("--sample", str(options.sample)))
+    # The customer-facing style name is neutral and separate from source
+    # evidence; without an explicit name the importer derives one from the
+    # measured design and checks it against the source brand and catalog.
+    if options.display_name:
+        command.extend(("--display-name", options.display_name))
+    if options.display_description:
+        command.extend(("--display-description", options.display_description))
     try:
         result = subprocess.run(command, cwd=marketplace.parent)
         template = marketplace / "templates" / template_id
@@ -363,6 +373,8 @@ def main() -> int:
     plan_parser.add_argument("--category", action="append", default=[])
     plan_parser.add_argument("--tag", action="append", default=[])
     plan_parser.add_argument("--sample", type=Path)
+    plan_parser.add_argument("--display-name", help="neutral customer-facing style name; never the source brand")
+    plan_parser.add_argument("--display-description")
     plan_parser.add_argument("--force", action="store_true")
     plan_parser.set_defaults(func=plan_job)
     for name, func, help_text in (
@@ -390,6 +402,8 @@ def main() -> int:
     run_parser.add_argument("--category", action="append", default=[])
     run_parser.add_argument("--tag", action="append", default=[])
     run_parser.add_argument("--sample", type=Path)
+    run_parser.add_argument("--display-name", help="neutral customer-facing style name; never the source brand")
+    run_parser.add_argument("--display-description")
     run_parser.add_argument("--force", action="store_true")
     run_parser.set_defaults(func=run)
     status_parser = sub.add_parser("status", help="inspect a URL-to-template job")

package/bundled-tools/clis/maggie_deployment.py

@@ -81,6 +81,238 @@ def credential_preflight_main(argv: list[str]) -> int:
     return 0 if result["passed"] else 1
 
 
+ENV_KEY_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]{0,127}")
+SHA256_RE = re.compile(r"[0-9a-f]{64}")
+DATABASE_URL_KEYS = ("DATABASE_URL", "POSTGRES_URL", "POSTGRES_PRISMA_URL", "PG_URL", "MYSQL_URL", "MONGODB_URI", "REDIS_URL")
+DATABASE_HOST_KEYS = ("DB_HOST", "PGHOST", "POSTGRES_HOST", "MYSQL_HOST", "DATABASE_HOST")
+LOCAL_DATABASE_HOSTS = {"localhost", "127.0.0.1", "::1", "0.0.0.0", "db", "postgres", "host.docker.internal"}
+
+
+def env_fingerprint(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def fingerprint_manifest(env_file: Path, host: str, keys: list[str] | None = None) -> dict:
+    """Return key names and SHA-256 fingerprints only; values never leave this function."""
+    values = parse_env_file(env_file)
+    selected = sorted(set(keys)) if keys else sorted(values)
+    return {
+        "schemaVersion": "maggie-env-fingerprints.v1",
+        "host": host,
+        "keys": {key: env_fingerprint(values[key]) for key in selected if values.get(key, "").strip()},
+        "valuesReturned": False,
+    }
+
+
+def load_fingerprint_manifest(path: Path) -> dict:
+    """Read a JSON manifest or the `KEY <sha256>` lines emitted by the no-echo shell snippet."""
+    text = path.read_text(encoding="utf-8")
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError:
+        keys = {}
+        for line in text.splitlines():
+            parts = line.split()
+            if len(parts) == 2:
+                keys[parts[0]] = parts[1].lower()
+        value = {"schemaVersion": "maggie-env-fingerprints.v1", "host": path.stem, "keys": keys}
+    if not isinstance(value, dict) or not isinstance(value.get("keys"), dict):
+        raise ValueError(f"fingerprint manifest is invalid: {path.name}")
+    keys = {}
+    for key, digest in value["keys"].items():
+        if not ENV_KEY_RE.fullmatch(str(key)) or not SHA256_RE.fullmatch(str(digest)):
+            raise ValueError(f"fingerprint manifest {path.name} must contain only env names and SHA-256 hex digests")
+        keys[str(key)] = str(digest)
+    # The empty-string digest is what the snippet prints for an unset key.
+    empty = env_fingerprint("")
+    return {"host": str(value.get("host") or path.stem), "keys": {key: digest for key, digest in keys.items() if digest != empty}}
+
+
+def secret_parity(hosts: list[dict], required: list[str], strict: bool = False) -> dict:
+    """Compare env names and fingerprints across hosts; output carries short fingerprints only."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    names = [host["host"] for host in hosts]
+    if len(hosts) < 2:
+        errors.append("at least two hosts are required for a parity check")
+    if len(set(names)) != len(names):
+        errors.append("host names must be unique")
+    required_names = sorted({name.strip() for name in required if name.strip()})
+    invalid = [name for name in required_names if not ENV_KEY_RE.fullmatch(name)]
+    if invalid:
+        errors.append("required names must be environment variable names")
+    union = sorted(set().union(*(host["keys"] for host in hosts)) | set(required_names)) if hosts else required_names
+    keys = []
+    for key in union:
+        present = {host["host"]: host["keys"][key] for host in hosts if key in host["keys"]}
+        missing = [name for name in names if name not in present]
+        distinct = sorted(set(present.values()))
+        status = "ok"
+        if missing:
+            status = "missing"
+        elif len(distinct) > 1:
+            status = "mismatch"
+        is_required = key in required_names
+        keys.append({
+            "key": key,
+            "required": is_required,
+            "status": status,
+            "missingOn": missing,
+            "fingerprints": {name: digest[:12] for name, digest in present.items()} if status == "mismatch" else {},
+        })
+        if status != "ok":
+            message = f"{key} is {status}" + (f" on {', '.join(missing)}" if missing else " across hosts")
+            (errors if is_required or strict else warnings).append(message)
+    return {
+        "schemaVersion": "maggie-secret-parity.v1",
+        "hosts": names,
+        "required": required_names,
+        "keys": keys,
+        "valuesReturned": False,
+        "passed": not errors,
+        "errors": errors,
+        "warnings": warnings,
+        "mutation": "not executed",
+    }
+
+
+def secret_parity_main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="maggie deployment secret-parity",
+        description="Compare env key names and SHA-256 fingerprints across hosts without printing values.",
+    )
+    parser.add_argument("--host", action="append", default=[], metavar="NAME=ENV_FILE", help="local env file for one host; repeat")
+    parser.add_argument("--manifest", action="append", default=[], help="fingerprint manifest produced on a host; repeat")
+    parser.add_argument("--required", action="append", default=[], help="required key name; repeat")
+    parser.add_argument("--strict", action="store_true", help="fail on optional keys that differ, not only required keys")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    hosts = []
+    for item in args.host:
+        name, separator, path = item.partition("=")
+        if not separator or not name or not path:
+            parser.error("--host must be NAME=ENV_FILE")
+        hosts.append({"host": name, "keys": fingerprint_manifest(Path(path).expanduser(), name)["keys"]})
+    for path in args.manifest:
+        hosts.append(load_fingerprint_manifest(Path(path).expanduser()))
+    result = secret_parity(hosts, args.required, args.strict)
+    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 secret_fingerprint_main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="maggie deployment secret-fingerprint",
+        description="Write a host's env key names and SHA-256 fingerprints (never values) for secret-parity.",
+    )
+    parser.add_argument("--env-file", required=True)
+    parser.add_argument("--host", required=True, help="stable host label, e.g. api-1")
+    parser.add_argument("--key", action="append", default=[], help="limit to these key names; repeat")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    result = fingerprint_manifest(Path(args.env_file).expanduser(), args.host, args.key or None)
+    text = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
+    if args.output:
+        output = Path(args.output).resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(text, encoding="utf-8")
+    print(text, end="")
+    return 0
+
+
+def database_targets(values: dict[str, str]) -> list[dict]:
+    """Extract database host/port/name per key; credentials are discarded."""
+    from urllib.parse import urlsplit
+
+    targets = []
+    for key, value in values.items():
+        if not value:
+            continue
+        if key in DATABASE_URL_KEYS or key.endswith("_DATABASE_URL") or key.endswith("_DB_URL"):
+            try:
+                parsed = urlsplit(value)
+                host = (parsed.hostname or "").lower()
+                port = parsed.port
+            except ValueError:
+                continue
+            if host:
+                targets.append({"key": key, "host": host, "port": port, "database": parsed.path.lstrip("/") or None})
+        elif key in DATABASE_HOST_KEYS:
+            targets.append({"key": key, "host": value.lower(), "port": None, "database": None})
+    return targets
+
+
+def environment_isolation(local_env: Path, production_env: Path | None = None, production_hosts: list[str] | None = None) -> dict:
+    """Fail when a local env file points at the production database."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    local = database_targets(parse_env_file(local_env)) if local_env.is_file() else []
+    production = database_targets(parse_env_file(production_env)) if production_env and production_env.is_file() else []
+    production += [{"key": "--production-db-host", "host": host.lower(), "port": None, "database": None} for host in production_hosts or [] if host]
+    if not local:
+        warnings.append("no database connection setting found in the local env file")
+    if not production:
+        warnings.append("no production database host provided; pass --production-env or --production-db-host")
+    findings = []
+    for item in local:
+        if item["host"] in LOCAL_DATABASE_HOSTS:
+            continue
+        for prod in production:
+            if item["host"] != prod["host"]:
+                continue
+            same_port = item["port"] is None or prod["port"] is None or item["port"] == prod["port"]
+            same_database = item["database"] is None or prod["database"] is None or item["database"] == prod["database"]
+            shared = same_port and same_database
+            findings.append({"localKey": item["key"], "productionKey": prod["key"], "host": item["host"], "sameDatabase": shared})
+            if shared:
+                errors.append(f"{item['key']} points at the production database host {item['host']}; local test data will reach live pages and workers")
+            else:
+                warnings.append(f"{item['key']} uses the production database server {item['host']} with a different database or port")
+    return {
+        "schemaVersion": "maggie-environment-isolation.v1",
+        "localTargets": [{key: item[key] for key in ("key", "host", "port")} for item in local],
+        "productionHosts": sorted({item["host"] for item in production}),
+        "findings": findings,
+        "credentialsReturned": False,
+        "passed": not errors,
+        "errors": errors,
+        "warnings": warnings,
+        "mutation": "not executed",
+    }
+
+
+def environment_isolation_main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="maggie deployment env-isolation",
+        description="Check that local development does not use the production database.",
+    )
+    parser.add_argument("--project", default=".")
+    parser.add_argument("--local-env", help="defaults to PROJECT/.env")
+    parser.add_argument("--production-env", help="production env file (read locally; values are not printed)")
+    parser.add_argument("--production-db-host", action="append", default=[], help="production database hostname; repeat")
+    parser.add_argument("--output")
+    args = parser.parse_args(argv)
+    project = Path(args.project).expanduser().resolve()
+    hosts = list(args.production_db_host)
+    if os.environ.get("MAGGIE_PRODUCTION_DB_HOST"):
+        hosts.append(os.environ["MAGGIE_PRODUCTION_DB_HOST"])
+    result = environment_isolation(
+        Path(args.local_env).expanduser().resolve() if args.local_env else project / ".env",
+        Path(args.production_env).expanduser().resolve() if args.production_env else None,
+        hosts,
+    )
+    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 _secret_names(payload: object) -> list[str]:
     """Extract only binding names from a Wrangler secret-list response."""
     entries: object = payload
@@ -303,6 +535,14 @@ def preflight(
         "commands": {key: scripts[key] for key in ("build", "test", "lint", "typecheck", "deploy") if key in scripts},
         "next_action": "review target, environment, migrations, secrets, and rollback owner before execute",
     }
+    isolation_warnings: list[str] = []
+    production_env = next((path for path in (project / ".env.production", project / ".env.prod") if path.is_file()), None)
+    production_host = os.environ.get("MAGGIE_PRODUCTION_DB_HOST", "").strip()
+    if (project / ".env").is_file() and (production_env or production_host):
+        isolation = environment_isolation(project / ".env", production_env, [production_host] if production_host else [])
+        result["environment_isolation"] = {"passed": isolation["passed"], "productionHosts": isolation["productionHosts"], "errors": isolation["errors"]}
+        result["checks"]["local_database_isolated"] = isolation["passed"]
+        isolation_warnings = [f"environment isolation: {message}" for message in isolation["errors"]]
     if target in {"vps", "vps-with-cloudflare-dns"}:
         result["provider"] = "vps"
         result["architecture"] = "Astro Node standalone behind Nginx, managed by systemd, with release/current rollback layout"
@@ -326,7 +566,7 @@ def preflight(
         rollback_passed = False
         if rollback_evidence.exists():
             try:
-                rollback_passed = validate_rollback_evidence(json.loads(rollback_evidence.read_text(encoding="utf-8"))) ["passed"]
+                rollback_passed = validate_rollback_evidence(json.loads(rollback_evidence.read_text(encoding="utf-8")), plan.get("retention", {}).get("keep"))["passed"]
             except (OSError, json.JSONDecodeError):
                 rollback_passed = False
         migration_manifest = project / ".maggie" / "migration-manifest.json"
@@ -339,7 +579,12 @@ def preflight(
         data_path = project / ".maggie" / "deployment" / "data-release.json"
         data_required = bool(migration.get("dataDependencies"))
         data_checkpoint = validate_data_checkpoint(data_path) if data_path.exists() else {"passed": not data_required, "declared": False, "errors": ["data-release.json is required for a data-dependent release"] if data_required else []}
-        retention_ok = bool(plan.get("retention", {}).get("keep") in (2, 3, 4, 5) and plan.get("retention", {}).get("prune") and plan.get("retention", {}).get("preserve"))
+        retention = plan.get("retention", {}) if isinstance(plan.get("retention"), dict) else {}
+        keep = retention.get("keep")
+        retention_ok = bool(keep in (1, 2, 3, 4, 5) and retention.get("prune") and retention.get("preserve"))
+        rollback_command = (plan.get("commands") or {}).get("rollback")
+        # Never advertise a rollback target that the retention policy deletes.
+        rollback_consistent = retention_ok and (bool(rollback_command) if keep >= 2 else not rollback_command and not any("<previous-release>" in str(item) for item in retention.get("preserve", [])))
         delegation = {"passed": True, "state": "not-required", "errors": []}
         delegation_path = delegation_evidence or project / ".maggie" / "deployment" / "deployer-delegation.json"
         if require_deployer:
@@ -351,22 +596,38 @@ def preflight(
             else:
                 delegation = validate_deployer_delegation(delegation_value, plan.get("release_root"), plan.get("service"))
                 delegation["path"] = str(delegation_path)
-        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "release_retention_policy": retention_ok, "data_release_checkpoint": data_checkpoint["passed"], "remote_verification_pending": not delegation["passed"], "deployer_delegation": delegation["passed"], "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
+        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "release_retention_policy": retention_ok, "rollback_target_retained": rollback_consistent, "data_release_checkpoint": data_checkpoint["passed"], "remote_verification_pending": not delegation["passed"], "deployer_delegation": delegation["passed"], "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
         result["delegation"] = delegation
         result["vps"] = {"runtime":"Node.js standalone","reverseProxy":"Nginx","processManager":"systemd","releaseLayout":"/var/www/<site>/releases/<release> + current symlink","dns":"Cloudflare DNS or registrar DNS; verify apex and www separately","remoteCommands":["npm ci","npm run build","systemctl restart <service>","systemctl is-active <service>","curl -fsS https://<domain>/robots.txt","curl -fsS https://<domain>/sitemap.xml"],"handoverFields":["host","sshUser","domain","service","release","previousRelease","nginxConfig","migrationVersion","verification","rollback"]}
         result["next_action"] = "review VPS host, SSH user, domain/DNS, systemd service, Nginx config, release path, migrations, and rollback owner before execute"
         runners = sorted(deployment_dir.rglob("release-runner.sh")) if deployment_dir.exists() else []
         result["release_runners"] = [release_runner_status(path) for path in runners[:25]]
-        result["warnings"] = [f"generated release runner is stale or unmarked: {item['path']}" for item in result["release_runners"] if item["status"] == "stale"]
-        result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_retention_policy", "data_release_checkpoint", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
+        result["warnings"] = isolation_warnings + [f"generated release runner is stale or unmarked: {item['path']}" for item in result["release_runners"] if item["status"] == "stale"]
+        result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_retention_policy", "rollback_target_retained", "data_release_checkpoint", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
         if require_deployer:
             result["blocking_checks"].append("deployer_delegation")
     else:
         result["blocking_checks"] = ["package_manifest", "build_command", "env_example"]
+        if isolation_warnings:
+            result["warnings"] = isolation_warnings
     return result
 
 
-def vps_plan(domain: str, service: str, release_root: str, node_port: int | None, deployer_user: str = "maggie-deploy") -> dict:
+def retention_policy(root: str, current: str, keep: int) -> dict:
+    """One retention policy shared by the plan, runner, preflight, prune, and rollback evidence."""
+    if not isinstance(keep, int) or isinstance(keep, bool) or not 1 <= keep <= 5:
+        raise ValueError("keep must be between 1 and 5")
+    preserve = [current] + ([f"{root}/releases/<previous-release>"] if keep >= 2 else [])
+    return {
+        "keep": keep,
+        "preserve": preserve,
+        "prune": f"find {root}/releases -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | tail -n +{keep + 1} | cut -d' ' -f2- | xargs -r rm -rf --",
+        "rollbackAvailable": keep >= 2,
+        "rollbackUnavailableReason": "" if keep >= 2 else "retention keeps only the active release; recover by redeploying the previous commit as a new release and restoring its data checkpoint",
+    }
+
+
+def vps_plan(domain: str, service: str, release_root: str, node_port: int | None, deployer_user: str = "maggie-deploy", keep_releases: int = 2) -> 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")
@@ -380,6 +641,7 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
         raise ValueError("node port must be between 1024 and 65535")
     root = release_root.rstrip("/")
     current = f"{root}/current"
+    retention = retention_policy(root, current, keep_releases)
     privileged_commands = [
         f"/bin/systemctl restart {service}",
         f"/bin/systemctl is-active {service}",
@@ -407,7 +669,7 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
             "allowed_domains_required": True,
         },
         "release_layout": f"{root}/releases/<immutable-release> plus current symlink",
-        "retention": {"keep": 2, "preserve": [current, f"{root}/releases/<previous-release>"], "prune": f"find {root}/releases -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | tail -n +3 | cut -d' ' -f2- | xargs -r rm -rf --"},
+        "retention": retention,
         "staging_first": True,
         "secrets": "external environment file; no secrets in generated artifacts",
         "commands": {
@@ -415,7 +677,11 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int | None
             "switch": f"ln -sfn {root}/releases/<release> {current}",
             "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}",
+            "rollback": f"ln -sfn {root}/releases/<previous-release> {current} && sudo -n /bin/systemctl restart {service}" if retention["rollbackAvailable"] else None,
+            # The database owner (e.g. postgres) often cannot traverse a release
+            # under a deploy user's home; stream the file instead of widening
+            # filesystem permissions.
+            "migrate_as_db_owner": f"sudo cat {root}/releases/<release>/<migration.sql> | sudo -u postgres psql -v ON_ERROR_STOP=1 --single-transaction -d <database> -f -",
             "data_rollback": "restore the matching data checkpoint before restarting the previous code release",
         },
         "files": {
@@ -450,8 +716,12 @@ def validate_data_checkpoint(path: Path) -> dict:
     return {"passed": not errors, "declared": True, "errors": errors}
 
 
-def validate_rollback_evidence(value: object) -> dict:
-    """Validate release rollback evidence, including the explicitly safe first release."""
+def validate_rollback_evidence(value: object, keep: int | None = None) -> dict:
+    """Validate release rollback evidence, including the explicitly safe first release.
+
+    With a one-release retention policy no previous release stays on disk, so
+    upgrade evidence must say the code rollback is unavailable and name the
+    recovery plan instead of advertising a removed target."""
     if not isinstance(value, dict):
         return {"passed": False, "errors": ["rollback evidence must be an object"]}
     errors = []
@@ -471,6 +741,13 @@ def validate_rollback_evidence(value: object) -> dict:
             errors.append("first release evidence must not claim a previous release")
         if not value.get("notApplicableReason"):
             errors.append("first release evidence needs notApplicableReason")
+    elif keep == 1:
+        if value.get("codeRollback") != "unavailable":
+            errors.append("retention keeps one release; rollback evidence must declare codeRollback: unavailable")
+        if not value.get("recoveryPlan"):
+            errors.append("retention keeps one release; rollback evidence needs a recoveryPlan (redeploy previous commit + data checkpoint)")
+    elif value.get("codeRollback") == "unavailable":
+        errors.append("codeRollback unavailable contradicts a retention policy that keeps a previous release")
     elif not value.get("previousRelease"):
         errors.append("upgrade rollback evidence requires previousRelease")
     return {"passed": not errors, "errors": errors}
@@ -498,15 +775,14 @@ def verify_infrastructure(units_dir: Path | None, service: str, timer: str | Non
 
 
 def retention_plan(release_root: str, current_link: str, keep: int) -> dict:
-    if keep < 2 or keep > 5:
-        raise ValueError("keep must be between 2 and 5")
+    policy = retention_policy(release_root.rstrip("/"), current_link, keep)
     root = Path(release_root).resolve()
     releases = sorted((path for path in root.iterdir() if path.is_dir() and not path.is_symlink()), key=lambda path: path.stat().st_mtime, reverse=True) if root.is_dir() else []
     current_target = Path(current_link).resolve() if Path(current_link).exists() else None
     preserved = {str(current_target)} if current_target else set()
     preserved.update(str(path) for path in releases[:keep])
     candidates = [str(path) for path in releases if str(path) not in preserved]
-    return {"schemaVersion": "maggie-retention-plan.v1", "releaseRoot": str(root), "currentLink": str(Path(current_link)), "keep": keep, "preserved": sorted(preserved), "candidates": candidates, "mutation": "not executed", "generatedAt": datetime.now(timezone.utc).isoformat()}
+    return {"schemaVersion": "maggie-retention-plan.v1", "releaseRoot": str(root), "currentLink": str(Path(current_link)), "keep": keep, "preserved": sorted(preserved), "candidates": candidates, "rollbackAvailable": policy["rollbackAvailable"], "rollbackUnavailableReason": policy["rollbackUnavailableReason"], "mutation": "not executed", "generatedAt": datetime.now(timezone.utc).isoformat()}
 
 
 def write_vps_plan(output_dir: Path, plan: dict) -> None:
@@ -594,6 +870,7 @@ def release_runner(plan: dict) -> str:
     service = plan["service"]
     domain = plan["domain"]
     current = plan["current_release"]
+    keep = retention_policy(root, current, plan.get("retention", {}).get("keep", 2))["keep"]
     generator = release_runner_generator()
     return f'''#!/usr/bin/env bash
 set -euo pipefail
@@ -657,13 +934,19 @@ wait_for_active
 wait_for_http "https://{domain}/robots.txt"
 wait_for_http "https://{domain}/sitemap.xml"
 
-# Keep current plus one rollback candidate, and prune only after health checks.
+# Retention policy: keep {keep} release(s), and prune only after health checks.
+KEEP_RELEASES={keep}
 mapfile -t RELEASES < <(find "$RELEASE_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | cut -d' ' -f2-)
-for candidate in "${{RELEASES[@]:2}}"; do
-  [ "$candidate" = "$PREVIOUS" ] && continue
+for candidate in "${{RELEASES[@]:$KEEP_RELEASES}}"; do
+  [ "$KEEP_RELEASES" -ge 2 ] && [ "$candidate" = "$PREVIOUS" ] && continue
   [ "$candidate" = "$RELEASE" ] && continue
   rm -rf -- "$candidate"
 done
+if [ "$KEEP_RELEASES" -ge 2 ] && [ -n "$PREVIOUS" ]; then
+  echo "rollback target retained: $PREVIOUS"
+else
+  echo "rollback target: unavailable (retention keeps only the active release; redeploy the previous commit and restore its data checkpoint)"
+fi
 '''
 
 
@@ -678,6 +961,12 @@ def main() -> int:
         return credential_preflight_main(sys.argv[2:])
     if sys.argv[1:2] == ["worker-secrets"]:
         return worker_secret_preflight_main(sys.argv[2:])
+    if sys.argv[1:2] == ["secret-parity"]:
+        return secret_parity_main(sys.argv[2:])
+    if sys.argv[1:2] == ["secret-fingerprint"]:
+        return secret_fingerprint_main(sys.argv[2:])
+    if sys.argv[1:2] == ["env-isolation"]:
+        return environment_isolation_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")
@@ -698,7 +987,7 @@ def main() -> int:
     parser.add_argument("--check-runner", help="read-only check of a generated runner's Maggie version and template fingerprint")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
     parser.add_argument("--current-link", help="current symlink for --retention-plan")
-    parser.add_argument("--keep-releases", type=int, default=2)
+    parser.add_argument("--keep-releases", type=int, default=2, help="releases to keep (1-5); 1 means no on-disk rollback target, used by --vps-plan and --retention-plan")
     parser.add_argument("--verify-infra", action="store_true", help="verify declared or installed systemd service/timer")
     parser.add_argument("--units-dir", help="directory containing generated .service and .timer units")
     parser.add_argument("--timer", help="systemd timer unit name")
@@ -726,7 +1015,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, args.deployer_user)
+            plan = vps_plan(args.domain, args.service, args.release_root, args.node_port, args.deployer_user, args.keep_releases)
             if args.plan_dir:
                 write_vps_plan(Path(args.plan_dir).resolve(), plan)
             if args.runner_output: