redeploy 0.2.66__tar.gz → 0.2.67__tar.gz

{redeploy-0.2.66 → redeploy-0.2.67}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redeploy
-Version: 0.2.66
+Version: 0.2.67
 Summary: Infrastructure migration toolkit: detect → plan → apply
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -32,17 +32,17 @@ Requires-Dist: mcp>=1.0; extra == "mcp"
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.66-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-33.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.67-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-34.2h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (86 commits)
-- 👤 **Human dev:** ~$3331 (33.3h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (88 commits)
+- 👤 **Human dev:** ~$3416 (34.2h @ $100/h, 30min dedup)
 
 Generated on 2026-04-23 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.66-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.67-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 Infrastructure migration and device deploy toolkit — VPS, Raspberry Pi kiosk, Podman Quadlet, k3s.
 

{redeploy-0.2.66 → redeploy-0.2.67}/README.md

@@ -3,17 +3,17 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.66-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-33.3h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.67-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.50-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-34.2h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $7.5000 (86 commits)
-- 👤 **Human dev:** ~$3331 (33.3h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $7.5000 (88 commits)
+- 👤 **Human dev:** ~$3416 (34.2h @ $100/h, 30min dedup)
 
 Generated on 2026-04-23 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
 
 ---
 
-![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.66-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![PyPI](https://img.shields.io/badge/pypi-redeploy-blue) ![Version](https://img.shields.io/badge/version-0.2.67-blue) ![Python](https://img.shields.io/badge/python-3.10+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 Infrastructure migration and device deploy toolkit — VPS, Raspberry Pi kiosk, Podman Quadlet, k3s.
 

{redeploy-0.2.66 → redeploy-0.2.67}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "redeploy"
-version = "0.2.66"
+version = "0.2.67"
 description = "Infrastructure migration toolkit: detect → plan → apply"
 readme = "README.md"
 requires-python = ">=3.11"

{redeploy-0.2.66 → redeploy-0.2.67}/redeploy/__init__.py

@@ -7,7 +7,7 @@ Public API (stable from 0.2.0, semver guaranteed)::
 
 Everything not listed in ``__all__`` is internal and may change without notice.
 """
-__version__ = "0.2.66"
+__version__ = "0.2.67"
 
 # ── Core models ───────────────────────────────────────────────────────────────
 from .models import (  # noqa: F401

{redeploy-0.2.66 → redeploy-0.2.67}/redeploy/analyze/spec_analyzer.py

@@ -293,6 +293,7 @@ class _ComposeChecker(_Checker):
     """Validate docker-compose files declared in spec or found in project."""
 
     def check(self, spec, document, base_dir, result):
+        ign = _IgnoreList(base_dir)
         compose_files = list(spec.target.compose_files or [])
         # Also try to discover common names if none explicitly declared
         if not compose_files:
@@ -310,15 +311,22 @@ class _ComposeChecker(_Checker):
                     suggestion=f"Create {path} or remove from target.compose_files."
                 )
                 continue
-            self._scan_compose(path, base_dir, result)
+            self._scan_compose(path, base_dir, result, ign)
 
-    def _scan_compose(self, path: Path, base_dir: Path, result: AnalysisResult):
+    def _scan_compose(self, path: Path, base_dir: Path, result: AnalysisResult, ign: _IgnoreList):
         try:
             data = yaml.safe_load(path.read_text()) or {}
         except Exception as exc:
             result.add(IssueSeverity.ERROR, "compose", f"Cannot parse {path}: {exc}")
             return
 
+        def _skip_ignored(check_path: Path) -> bool:
+            try:
+                rel = check_path.resolve().relative_to(base_dir.resolve())
+                return ign.is_ignored(rel)
+            except ValueError:
+                return False
+
         services = data.get("services", {})
         for svc_name, svc in services.items():
             if not isinstance(svc, dict):
@@ -337,7 +345,7 @@ class _ComposeChecker(_Checker):
                 dockerfile = build.get("dockerfile")
                 if dockerfile:
                     df_path = ctx_path / dockerfile
-                    if not df_path.exists():
+                    if not df_path.exists() and not _skip_ignored(df_path):
                         result.add(
                             IssueSeverity.ERROR, "compose",
                             f"Service '{svc_name}' Dockerfile missing: {df_path}",
@@ -349,7 +357,7 @@ class _ComposeChecker(_Checker):
                 env_files = [env_files]
             for ef in env_files:
                 ef_path = base_dir / ef if not str(ef).startswith("/") else Path(ef)
-                if not ef_path.exists():
+                if not ef_path.exists() and not _skip_ignored(ef_path):
                     result.add(
                         IssueSeverity.WARNING, "compose",
                         f"Service '{svc_name}' env_file missing: {ef}",
@@ -362,7 +370,7 @@ class _ComposeChecker(_Checker):
                         host_part = vol.split(":", 1)[0]
                         # Skip named volumes and relative paths that exist
                         if host_part.startswith("/"):
-                            if not Path(host_part).exists():
+                            if not Path(host_part).exists() and not _skip_ignored(Path(host_part)):
                                 result.add(
                                     IssueSeverity.WARNING, "compose",
                                     f"Service '{svc_name}' volume host path missing: {host_part}",
@@ -370,7 +378,7 @@ class _ComposeChecker(_Checker):
                                 )
                         elif host_part != "." and "/" in host_part:
                             hp = base_dir / host_part
-                            if not hp.exists():
+                            if not hp.exists() and not _skip_ignored(hp):
                                 result.add(
                                     IssueSeverity.WARNING, "compose",
                                     f"Service '{svc_name}' relative volume path missing: {hp}",
@@ -687,9 +695,11 @@ class SpecAnalyzer:
     ]
 
     def __init__(self, base_dir: Path | None = None,
-                 checkers: list[_Checker] | None = None):
+                 checkers: list[_Checker] | None = None,
+                 auto_create_redeployignore: bool = True):
         self.base_dir = base_dir or Path.cwd()
         self.checkers = checkers or list(self.DEFAULT_CHECKERS)
+        self.auto_create_redeployignore = auto_create_redeployignore
 
     def analyze(self, spec: MigrationSpec,
                 document: MarkpactDocument | None = None) -> AnalysisResult:
@@ -704,6 +714,10 @@ class SpecAnalyzer:
         from ..markpact.compiler import compile_markpact_document, MarkpactCompileError
         from ..models.spec import MigrationSpec as MS
 
+        # Ensure .redeployignore exists with sensible defaults
+        if self.auto_create_redeployignore:
+            ensure_redeployignore(self.base_dir)
+
         document = None
         spec = None
         result = AnalysisResult()

{redeploy-0.2.66 → redeploy-0.2.67}/redeploy/apply/handlers.py

@@ -21,6 +21,20 @@ if TYPE_CHECKING:
     from .progress import ProgressEmitter
 
 
+def _format_step_output(stdout: str, stderr: str, max_chars: int = 8000) -> str:
+    out = str(stdout or "").strip()
+    err = str(stderr or "").strip()
+    chunks: list[str] = []
+    if out:
+        chunks.append("stdout:\n" + out)
+    if err:
+        chunks.append("stderr:\n" + err)
+    if not chunks:
+        return "ok"
+    joined = "\n\n".join(chunks)
+    return joined[:max_chars]
+
+
 def run_ssh(step: MigrationStep, probe: RemoteProbe) -> None:
     """Execute SSH command on remote host."""
     cmd = step.command
@@ -28,9 +42,9 @@ def run_ssh(step: MigrationStep, probe: RemoteProbe) -> None:
         raise StepError(step, "No command specified")
     timeout = step.timeout or 300
     r = probe.run(cmd, timeout=timeout)
-    step.result = r.out[:500]
+    step.result = _format_step_output(r.out, r.stderr)
     if not r.ok:
-        raise StepError(step, f"exit={r.exit_code}: {r.stderr[:200]}")
+        raise StepError(step, f"exit={r.exit_code}: {_format_step_output(r.out, r.stderr, 400)}")
     step.status = StepStatus.DONE
 
 
@@ -51,9 +65,9 @@ def run_scp(step: MigrationStep, probe: RemoteProbe, plan: MigrationPlan) -> Non
                step.src, f"{plan.host}:{step.dst}"]
     result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
     if result.returncode != 0:
-        raise StepError(step, f"scp failed: {result.stderr[:200]}")
+        raise StepError(step, f"scp failed: {_format_step_output(result.stdout, result.stderr, 400)}")
     step.status = StepStatus.DONE
-    step.result = "ok"
+    step.result = _format_step_output(result.stdout, result.stderr)
 
 
 def run_rsync(step: MigrationStep, probe: RemoteProbe, plan: MigrationPlan) -> None:
@@ -80,9 +94,9 @@ def run_rsync(step: MigrationStep, probe: RemoteProbe, plan: MigrationPlan) -> N
     cmd += [step.src, dst]
     result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
     if result.returncode != 0:
-        raise StepError(step, f"rsync failed: {result.stderr[:200]}")
+        raise StepError(step, f"rsync failed: {_format_step_output(result.stdout, result.stderr, 400)}")
     step.status = StepStatus.DONE
-    step.result = "ok"
+    step.result = _format_step_output(result.stdout, result.stderr)
 
 
 def _ensure_remote_parent_dir(probe: RemoteProbe, remote_dst: str) -> None:

{redeploy-0.2.66 → redeploy-0.2.67}/redeploy/cli/commands/plan_apply.py

@@ -1,10 +1,13 @@
 """plan, apply, migrate, run commands — Migration planning and execution."""
 from __future__ import annotations
 
+import subprocess
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 
 import click
+from loguru import logger
 from rich.console import Console
 from rich.table import Table
 
@@ -234,6 +237,18 @@ def migrate(ctx, host, app, domain, target, strategy, target_version,
 @click.option(
     "-o", "--output", default=None, type=click.Path(), help="Save apply results to file"
 )
+@click.option(
+    "--report/--no-report", default=False, show_default=True,
+    help="Write Markdown execution report next to the spec file."
+)
+@click.option(
+    "--report-file", default=None, type=click.Path(),
+    help="Override Markdown report output path."
+)
+@click.option(
+    "--sync-project/--no-sync-project", default=True, show_default=True,
+    help="Before apply, sync full local project tree to target.remote_dir (respects .gitignore/.redeployignore)."
+)
 @click.option(
     "--env", "env_name", default="",
     help="Named environment from redeploy.yaml (e.g. prod, dev, rpi5)"
@@ -289,6 +304,7 @@ def migrate(ctx, host, app, domain, target, strategy, target_version,
 )
 @click.pass_context
 def run(ctx, spec_file, dry_run, plan_only, do_detect, plan_out, output,
+    report, report_file, sync_project,
         env_name, progress_yaml, resume, from_step, state_file, no_state,
         heal, fix_hint, max_heal_retries, lint,
         preflight, preflight_schema_out, preflight_remote, strict_preflight):
@@ -327,6 +343,19 @@ def run(ctx, spec_file, dry_run, plan_only, do_detect, plan_out, output,
         sys.exit(1)
 
     spec = load_spec_or_exit(console, resolved_spec)
+    started_at = datetime.now(timezone.utc)
+
+    # Redirect all logger output to a dated file under .redeploy/logs/
+    log_dir = Path.cwd() / ".redeploy" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / f"redeploy-{started_at.strftime('%Y%m%d_%H%M%S')}.log"
+    file_handler_id = logger.add(
+        log_file,
+        level="DEBUG",
+        format="{time:YYYY-MM-DD HH:mm:ss.SSS} | {level:<8} | {name}:{function}:{line} | {message}",
+        enqueue=True,
+    )
+    logger.info("redeploy run started — spec={}", resolved_spec)
 
     # Overlay manifest values
     _apply_manifest_to_spec(console, manifest, spec, env_name)
@@ -349,6 +378,7 @@ def run(ctx, spec_file, dry_run, plan_only, do_detect, plan_out, output,
                     console.print(f"      [dim]→ {i.suggestion}[/dim]")
             if not lint_result.passed:
                 console.print("\n[red]✗ lint failed — fix errors above or use --no-lint to skip.[/red]")
+                logger.remove(file_handler_id)
                 sys.exit(1)
             else:
                 console.print(f"[yellow]⚠ lint passed with {len(lint_result.warnings())} warning(s)[/yellow]")
@@ -365,6 +395,10 @@ def run(ctx, spec_file, dry_run, plan_only, do_detect, plan_out, output,
     console.print(f"\n[bold]plan[/bold]")
     migration = planner.run()
 
+    # Keep remote app tree synchronized on every deployment run.
+    if sync_project:
+        _inject_project_sync_step(migration, spec, Path.cwd(), console)
+
     if plan_out:
         planner.save(migration, Path(plan_out))
         console.print(f"  [dim]plan saved → {plan_out}[/dim]")
@@ -396,17 +430,28 @@ def run(ctx, spec_file, dry_run, plan_only, do_detect, plan_out, output,
                 console.print(f"  [dim]... and {blockers - 10} more blockers in schema file[/dim]")
             if strict_preflight:
                 console.print("\n[red]✗ strict preflight failed — aborting before apply[/red]")
+                logger.remove(file_handler_id)
                 sys.exit(1)
         else:
             console.print("[green]  ✓ preflight passed (no blockers)[/green]")
 
     if plan_only:
+        if report:
+            _write_markdown_report(
+                console=console,
+                migration=migration,
+                spec_path=Path(resolved_spec),
+                started_at=started_at,
+                ok=True,
+                executed=False,
+                report_file=Path(report_file) if report_file else None,
+            )
         console.print("\n[dim]--plan-only: stopping before apply[/dim]")
+        logger.remove(file_handler_id)
         return
 
     # Apply
     load_user_plugins()
-
     # Self-healing mode
     if heal and not dry_run:
         _load_dotenv()
@@ -441,7 +486,19 @@ def run(ctx, spec_file, dry_run, plan_only, do_detect, plan_out, output,
             spec_path=str(resolved_spec)
         )
 
+    if report:
+        _write_markdown_report(
+            console=console,
+            migration=migration,
+            spec_path=Path(resolved_spec),
+            started_at=started_at,
+            ok=ok,
+            executed=True,
+            report_file=Path(report_file) if report_file else None,
+        )
+
     if not ok:
+        logger.remove(file_handler_id)
         sys.exit(1)
 
 
@@ -599,8 +656,8 @@ def _ensure_redeployignore(project_root: Path, console) -> None:
         ".git/",
         ".venv/",
         "venv/",
-        ".env",
-        ".env.*",
+        "# NOTE: .env is intentionally not excluded by default",
+        "# so deployment workflows can choose to sync it.",
         "",
         "# Python / Node caches",
         "__pycache__/",
@@ -639,3 +696,310 @@ def _ensure_redeployignore(project_root: Path, console) -> None:
 
     target.write_text("\n".join(lines) + "\n", encoding="utf-8")
     console.print(f"[dim]generated {target.name} (first run)[/dim]")
+
+
+def _inject_project_sync_step(migration, spec, project_root: Path, console) -> None:
+    """Inject a full-project rsync step unless already present.
+
+    This keeps remote tree aligned with local sources and catches missing files.
+    """
+    from ...models import MigrationStep, StepAction
+
+    if any(s.id == "sync_project_tree" for s in migration.steps):
+        return
+
+    host = (migration.host or "").strip().lower()
+    if host in {"", "local", "localhost", "127.0.0.1"}:
+        return
+
+    remote_dir = (getattr(spec.target, "remote_dir", "") or "").strip()
+    if not remote_dir:
+        return
+
+    sync_step = MigrationStep(
+        id="sync_project_tree",
+        action=StepAction.RSYNC,
+        description="Sync full project tree to remote_dir (respect .gitignore/.redeployignore)",
+        src=f"{project_root.as_posix().rstrip('/')}/",
+        dst=f"{remote_dir.rstrip('/')}/",
+        excludes=[
+            ".git/",
+            ".redeploy/state/",
+            ".redeploy/logs/",
+        ],
+    )
+
+    insert_at = 0
+    for idx, step in enumerate(migration.steps):
+        if step.id == "sync_env":
+            insert_at = idx + 1
+            break
+    migration.steps.insert(insert_at, sync_step)
+    console.print("[dim]plan: injected sync_project_tree (full rsync before apply)[/dim]")
+
+
+def _default_report_path(spec_path: Path) -> Path:
+    return spec_path.parent / f".{spec_path.stem}.md"
+
+
+def _resolve_audit_entry(migration, started_at: datetime, ok: bool):
+    from ...observe import AuditEntry, DeployAuditLog
+
+    log = DeployAuditLog()
+    entries = log.filter(host=migration.host, app=migration.app, since=started_at)
+    if entries:
+        return entries[-1]
+
+    # Fallback if audit record is unavailable for any reason.
+    done_count = sum(1 for s in migration.steps if str(s.status).endswith("DONE"))
+    failed_count = sum(1 for s in migration.steps if str(s.status).endswith("FAILED"))
+    if ok and done_count == 0 and failed_count == 0:
+        # plan-only fallback: treat all planned steps as successful planning output
+        done_count = len(migration.steps)
+
+    data = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "host": migration.host,
+        "app": migration.app,
+        "from_strategy": migration.from_strategy.value,
+        "to_strategy": migration.to_strategy.value,
+        "ok": ok,
+        "dry_run": False,
+        "elapsed_s": 0.0,
+        "steps_total": len(migration.steps),
+        "steps_ok": done_count,
+        "steps_failed": failed_count,
+        "steps": [
+            {
+                "id": s.id,
+                "action": s.action.value,
+                "status": str(s.status).split(".")[-1].lower(),
+                "result": s.result,
+                "error": s.error,
+            }
+            for s in migration.steps
+        ],
+    }
+    return AuditEntry(data)
+
+
+def _step_command_block(step) -> str:
+    if step.command:
+        return step.command.strip()
+    if step.command_ref:
+        return f"command_ref: {step.command_ref}"
+    if step.action.value == "rsync":
+        parts = [f"rsync {step.src or ''} -> {step.dst or ''}"]
+        if step.excludes:
+            parts.append("excludes:")
+            parts.extend(f"- {x}" for x in step.excludes)
+        return "\n".join(parts)
+    if step.action.value == "scp":
+        return f"scp {step.src or ''} -> {step.dst or ''}"
+    if step.action.value in {"http_check", "version_check"}:
+        return f"url: {step.url or ''}\nexpect: {step.expect or ''}".strip()
+    return f"action: {step.action.value}"
+
+
+def _build_checksum_verification(migration, executed: bool) -> dict | None:
+    """Build post-deploy sync verification with checksum-aware rsync dry-run."""
+    sync_step = next((s for s in migration.steps if s.id == "sync_project_tree"), None)
+    if not sync_step:
+        return None
+
+    src = (sync_step.src or "").strip()
+    dst = (sync_step.dst or "").strip()
+    host = (migration.host or "").strip()
+
+    local_root = Path(src.rstrip("/")).expanduser() if src else Path.cwd()
+    remote_root = dst.rstrip("/") if dst else ""
+
+    if not executed:
+        return {
+            "status": "skipped",
+            "reason": "plan-only run (apply not executed)",
+            "host": host,
+            "local_root": str(local_root),
+            "remote_root": remote_root,
+            "command": "(not executed)",
+            "changed_paths": [],
+            "changed_count": 0,
+        }
+
+    if not host or host.lower() in {"local", "localhost", "127.0.0.1"}:
+        return {
+            "status": "skipped",
+            "reason": "remote checksum verification requires SSH host",
+            "host": host,
+            "local_root": str(local_root),
+            "remote_root": remote_root,
+            "command": "(not executed)",
+            "changed_paths": [],
+            "changed_count": 0,
+        }
+
+    if not local_root.exists() or not remote_root:
+        return {
+            "status": "error",
+            "reason": "sync scope is incomplete (missing local or remote root)",
+            "host": host,
+            "local_root": str(local_root),
+            "remote_root": remote_root,
+            "command": "(not executed)",
+            "changed_paths": [],
+            "changed_count": 0,
+        }
+
+    cmd = ["rsync", "-a", "-z", "--delete", "--checksum", "--dry-run", "--itemize-changes"]
+    if (local_root / ".gitignore").exists():
+        cmd += ["--filter=:- .gitignore"]
+    if (local_root / ".redeployignore").exists():
+        cmd += ["--filter=:- .redeployignore"]
+    for ex in sync_step.excludes or []:
+        cmd += ["--exclude", ex]
+    cmd += [f"{local_root.as_posix().rstrip('/')}/", f"{host}:{remote_root.rstrip('/')}/"]
+
+    command_preview = " ".join(cmd)
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=1200)
+    except Exception as exc:  # pragma: no cover - defensive, non-fatal for report
+        return {
+            "status": "error",
+            "reason": str(exc),
+            "host": host,
+            "local_root": str(local_root),
+            "remote_root": remote_root,
+            "command": command_preview,
+            "changed_paths": [],
+            "changed_count": 0,
+        }
+
+    raw_lines = [ln.rstrip() for ln in (result.stdout or "").splitlines() if ln.strip()]
+    changed_lines = [
+        ln
+        for ln in raw_lines
+        if ln not in {"sending incremental file list"}
+        and not ln.startswith("sent ")
+        and not ln.startswith("total size is ")
+        and not ln.startswith("created directory ")
+    ]
+
+    status = "match" if result.returncode == 0 and not changed_lines else "mismatch"
+    reason = ""
+    if result.returncode != 0:
+        status = "error"
+        reason = (result.stderr or "").strip() or f"rsync exited with {result.returncode}"
+
+    return {
+        "status": status,
+        "reason": reason,
+        "host": host,
+        "local_root": str(local_root),
+        "remote_root": remote_root,
+        "command": command_preview,
+        "changed_paths": changed_lines[:200],
+        "changed_count": len(changed_lines),
+    }
+
+
+def _render_markdown_report(entry, migration, spec_path: Path, checksum: dict | None = None) -> str:
+    by_id = {s.id: s for s in migration.steps}
+    lines: list[str] = [
+        f"# Redeploy Execution Report - {spec_path.name}",
+        "",
+        f"- Timestamp: {entry.ts}",
+        f"- Spec: {spec_path}",
+        f"- Host: {entry.host}",
+        f"- App: {entry.app}",
+        f"- Strategy: {entry.from_strategy} -> {entry.to_strategy}",
+        f"- Result: {'SUCCESS' if entry.ok else 'FAILED'}",
+        f"- Steps: {entry.steps_ok}/{entry.steps_total} ok",
+        f"- Elapsed: {entry.elapsed_s:.1f}s",
+        "",
+    ]
+
+    if checksum:
+        status = (checksum.get("status") or "unknown").upper()
+        lines += [
+            "## Sync Checksum Verification",
+            "",
+            "- Method: rsync --checksum --dry-run --itemize-changes",
+            f"- Scope: {checksum.get('local_root', '')} -> {checksum.get('host', '')}:{checksum.get('remote_root', '')}",
+            f"- Status: {status}",
+            f"- Changed Paths: {checksum.get('changed_count', 0)}",
+        ]
+        reason = (checksum.get("reason") or "").strip()
+        if reason:
+            lines.append(f"- Note: {reason}")
+        lines += [
+            "",
+            "#### Command",
+            "```bash",
+            checksum.get("command") or "(not executed)",
+            "```",
+            "",
+        ]
+        if checksum.get("changed_paths"):
+            lines += [
+                "#### Differences",
+                "```text",
+                "\n".join(checksum.get("changed_paths") or []),
+                "```",
+                "",
+            ]
+
+    lines += [
+        "## Step Logs",
+        "",
+    ]
+
+    for i, step_row in enumerate(entry.steps, 1):
+        sid = step_row.get("id", "")
+        status = (step_row.get("status") or "").upper()
+        action = step_row.get("action", "")
+        model_step = by_id.get(sid)
+        desc = model_step.description if model_step else ""
+        cmd = _step_command_block(model_step) if model_step else f"action: {action}"
+        result = (step_row.get("result") or "").strip()
+        error = (step_row.get("error") or "").strip()
+        log_text = error or result or "(no output captured)"
+
+        lines += [
+            f"### {i}. {sid} [{status}]",
+            "",
+            f"- Action: {action}",
+            f"- Description: {desc}",
+            "",
+            "#### Executed",
+            "```bash",
+            cmd,
+            "```",
+            "",
+            "#### Output",
+            "```text",
+            log_text,
+            "```",
+            "",
+        ]
+
+    return "\n".join(lines)
+
+
+def _write_markdown_report(
+    console,
+    migration,
+    spec_path: Path,
+    started_at: datetime,
+    ok: bool,
+    executed: bool,
+    report_file: Path | None = None,
+) -> None:
+    entry = _resolve_audit_entry(migration, started_at=started_at, ok=ok)
+    checksum = _build_checksum_verification(migration, executed=executed)
+    out_path = report_file or _default_report_path(spec_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(
+        _render_markdown_report(entry, migration, spec_path, checksum=checksum),
+        encoding="utf-8",
+    )
+    console.print(f"[bold]report[/bold]  [dim]saved → {out_path}[/dim]")