@topy-ai/maggie 0.6.7 → 0.6.8

package/README.md

@@ -179,8 +179,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.6.7 update --project . --force
-npx @topy-ai/maggie@0.6.7 cleanup --project .
+npx @topy-ai/maggie@0.6.8 update --project . --force
+npx @topy-ai/maggie@0.6.8 cleanup --project .
 ```
 
 ## MaggieDash lifecycle

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.6.7 init --agent all
+npx @topy-ai/maggie@0.6.8 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 

package/bundled-skills/maggie-deployment/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie Deployment
@@ -70,6 +70,20 @@ The output contains only the immutable release/current layout, systemd unit,
 Nginx reverse-proxy config, health commands and rollback command. It never
 contains credentials and never SSHs, changes DNS, restarts systemd or deploys.
 
+VPS plans include a bounded retention policy: keep two immutable releases,
+preserve the `current` target and rollback target, and review prune candidates
+before any operator executes cleanup. Generate a read-only candidate report:
+
+```bash
+python3 tools/clis/maggie_deployment.py --retention-plan \
+  --release-root /var/www/example \
+  --current-link /var/www/example/current \
+  --keep-releases 2 --output .maggie/deployment/retention-plan.json
+```
+
+The CLI never deletes release directories and never permits fewer than two
+retained releases.
+
 Validate the database release separately before a VPS migration:
 
 ```bash
@@ -81,6 +95,14 @@ The manifest must reference `DATABASE_URL` (not a literal URL), declare an
 advancing version, forward-only/idempotent policy, backup and restore commands,
 and a tested restore artifact. The validator never runs those commands.
 
+If a release depends on existing rows or seeded data, set
+`dataDependencies: true` in `.maggie/migration-manifest.json` and provide
+`.maggie/deployment/data-release.json` before deployment. The checkpoint must
+use `maggie-data-release.v1`, declare `requiredTables`, compare
+`previousCounts` and `currentCounts`, and include the release, check time, and
+`passed: true`. Deployment preflight fails closed when this evidence is absent
+or incomplete; it does not copy or mutate data.
+
 Validate and materialise scheduled jobs only after their quota and lock policy
 has been reviewed:
 

package/bundled-tools/clis/maggie_deployment.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 import re
+from datetime import datetime, timezone
 from pathlib import Path
 
 
@@ -57,10 +58,21 @@ def preflight(project: Path, target: str, environment: str) -> dict:
                 rollback_passed = bool(evidence.get("passed") is True and evidence.get("environment") == "production" and evidence.get("previousRelease") and evidence.get("testedAt"))
             except (OSError, json.JSONDecodeError):
                 rollback_passed = False
-        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, "remote_verification_pending": True, "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})
+        migration_manifest = project / ".maggie" / "migration-manifest.json"
+        migration = {}
+        if migration_manifest.exists():
+            try:
+                migration = json.loads(migration_manifest.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                migration = {}
+        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"))
+        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": True, "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["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"
-        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_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
+        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"]
     else:
         result["blocking_checks"] = ["package_manifest", "build_command", "env_example"]
     return result
@@ -85,6 +97,7 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> di
         "current_release": current,
         "node_port": node_port,
         "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 --"},
         "staging_first": True,
         "secrets": "external environment file; no secrets in generated artifacts",
         "commands": {
@@ -101,6 +114,38 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> di
     }
 
 
+def validate_data_checkpoint(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"passed": False, "declared": True, "errors": [f"data checkpoint unreadable: {exc}"]}
+    required = value.get("requiredTables")
+    previous = value.get("previousCounts")
+    current = value.get("currentCounts")
+    errors = []
+    if value.get("schemaVersion") != "maggie-data-release.v1": errors.append("data checkpoint schemaVersion is unsupported")
+    if value.get("passed") is not True: errors.append("data checkpoint is not passed")
+    if not isinstance(required, list) or not required: errors.append("requiredTables must be a non-empty list")
+    if not isinstance(previous, dict) or not isinstance(current, dict): errors.append("previousCounts and currentCounts are required")
+    if isinstance(required, list) and isinstance(current, dict):
+        missing = [table for table in required if table not in current]
+        if missing: errors.append("currentCounts is missing required tables")
+    if not value.get("release") or not value.get("checkedAt"): errors.append("release and checkedAt are required")
+    return {"passed": not errors, "declared": True, "errors": errors}
+
+
+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")
+    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()}
+
+
 def write_vps_plan(output_dir: Path, plan: dict) -> None:
     output_dir.mkdir(parents=True, exist_ok=True)
     domain = plan["domain"]
@@ -158,6 +203,9 @@ def main() -> int:
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
     parser.add_argument("--node-port", type=int, default=4321)
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
+    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)
     args = parser.parse_args()
     try:
         if args.vps_plan:
@@ -168,6 +216,16 @@ def main() -> int:
                 write_vps_plan(Path(args.plan_dir).resolve(), plan)
             print(json.dumps(plan, indent=2, ensure_ascii=False))
             return 0
+        if args.retention_plan:
+            if not args.current_link:
+                parser.error("--current-link is required with --retention-plan")
+            plan = retention_plan(args.release_root, args.current_link, args.keep_releases)
+            output = Path(args.output).resolve() if args.output else None
+            if output:
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_text(json.dumps(plan, indent=2) + "\n", encoding="utf-8")
+            print(json.dumps(plan, indent=2, ensure_ascii=False))
+            return 0
         result = preflight(Path(args.project).resolve(), args.target, args.environment)
         if args.output:
             Path(args.output).parent.mkdir(parents=True, exist_ok=True)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",