redeploy 0.2.17__tar.gz → 0.2.18__tar.gz

{redeploy-0.2.17 → redeploy-0.2.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redeploy
-Version: 0.2.17
+Version: 0.2.18
 Summary: Infrastructure migration toolkit: detect → plan → apply
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -27,17 +27,17 @@ Requires-Dist: pfix>=0.1.60; extra == "dev"
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.2.17-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-$5.40-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-11.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.18-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-$5.55-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-12.6h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $5.4000 (36 commits)
-- 👤 **Human dev:** ~$1130 (11.3h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $5.5500 (37 commits)
+- 👤 **Human dev:** ~$1255 (12.6h @ $100/h, 30min dedup)
 
 Generated on 2026-04-21 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.17-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.18-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.
 
@@ -428,6 +428,108 @@ extra_steps:
 
 The script is base64-encoded and executed via SSH with automatic temp file cleanup. Use `command` field for multiline script content (YAML `|` preserves newlines).
 
+### Script References (`command_ref`)
+
+Instead of duplicating scripts in YAML, reference a script defined in a markdown codeblock:
+
+```yaml
+extra_steps:
+  - id: configure_kiosk
+    action: inline_script
+    description: "Execute kiosk script from markdown"
+    command_ref: "#kiosk-browser-configuration-script"
+    risk: medium
+```
+
+In your migration markdown file, define the script in a section:
+
+```markdown
+## Kiosk Browser Configuration Script
+
+```bash
+#!/bin/bash
+# Auto-detect browser...
+if command -v chromium-browser >/dev/null 2>&1; then
+  chromium-browser --kiosk http://localhost:8100
+fi
+```
+```
+
+**Benefits:**
+- Single source of truth — script lives in one place (markdown codeblock)
+- No duplication between markdown documentation and YAML
+- Easy to read and maintain
+- Changes to the codeblock automatically apply to the deployment
+
+**Reference formats:**
+- `"#section-id"` — script from section in current spec file
+- `"./file.md#section-id"` — script from section in specific file
+
+The section ID is derived from the heading: spaces become hyphens, lowercase.
+Example: `## Kiosk Browser Configuration Script` → `#kiosk-browser-configuration-script`
+
+### Execute Script by Reference (`redeploy exec`)
+
+Run a single script from markdown without running the full migration:
+
+```bash
+# Execute script from codeblock on remote host
+redeploy exec '#kiosk-browser-configuration-script' \
+    --host pi@192.168.188.108 \
+    --file migration.podman-rpi5-resume.md
+
+# With file in reference
+redeploy exec './migration.md#install-deps' --host root@server.com
+
+# Using markpact:ref (more explicit)
+redeploy exec 'kiosk-script-id' --host pi@192.168.188.108 --file migration.md
+
+# Dry-run to preview script
+redeploy exec '#backup-script' --host pi@192.168.188.108 --file ops.md --dry-run
+```
+
+This is useful for:
+- One-off operations defined in markdown docs
+- Testing individual scripts before full migration
+- Running maintenance tasks
+
+### Execute Multiple Scripts (`redeploy exec-multi`)
+
+Test multiple scripts at once:
+
+```bash
+# Execute multiple scripts by ref
+redeploy exec-multi 'kiosk-script,install-deps,cleanup' \
+    --host pi@192.168.188.108 \
+    --file migration.md
+
+# Mix of markpact:ref and section headings
+redeploy exec-multi 'script1,#section2,script3' \
+    --host root@server.com \
+    --file deploy.md \
+    --dry-run
+```
+
+### Marking Codeblocks with `markpact:ref`
+
+For more explicit script identification, use `markpact:ref <id>` in codeblock:
+
+```markdown
+```bash markpact:ref kiosk-browser-configuration-script
+#!/bin/bash
+# Auto-detect browser...
+if command -v chromium-browser >/dev/null 2>&1; then
+  chromium-browser --kiosk http://localhost:8100
+fi
+```
+```
+
+Benefits of `markpact:ref`:
+- Explicit ID assignment (not derived from heading)
+- Multiple scripts per section
+- Can reference by simple ID instead of full heading
+- Self-documenting in markdown
+
 
 
 Place in project root — `redeploy run` (no args) uses it automatically.

{redeploy-0.2.17 → redeploy-0.2.18}/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.17-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-$5.40-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-11.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.18-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-$5.55-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-12.6h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $5.4000 (36 commits)
-- 👤 **Human dev:** ~$1130 (11.3h @ $100/h, 30min dedup)
+- 🤖 **LLM usage:** $5.5500 (37 commits)
+- 👤 **Human dev:** ~$1255 (12.6h @ $100/h, 30min dedup)
 
 Generated on 2026-04-21 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.17-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.18-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.
 
@@ -404,6 +404,108 @@ extra_steps:
 
 The script is base64-encoded and executed via SSH with automatic temp file cleanup. Use `command` field for multiline script content (YAML `|` preserves newlines).
 
+### Script References (`command_ref`)
+
+Instead of duplicating scripts in YAML, reference a script defined in a markdown codeblock:
+
+```yaml
+extra_steps:
+  - id: configure_kiosk
+    action: inline_script
+    description: "Execute kiosk script from markdown"
+    command_ref: "#kiosk-browser-configuration-script"
+    risk: medium
+```
+
+In your migration markdown file, define the script in a section:
+
+```markdown
+## Kiosk Browser Configuration Script
+
+```bash
+#!/bin/bash
+# Auto-detect browser...
+if command -v chromium-browser >/dev/null 2>&1; then
+  chromium-browser --kiosk http://localhost:8100
+fi
+```
+```
+
+**Benefits:**
+- Single source of truth — script lives in one place (markdown codeblock)
+- No duplication between markdown documentation and YAML
+- Easy to read and maintain
+- Changes to the codeblock automatically apply to the deployment
+
+**Reference formats:**
+- `"#section-id"` — script from section in current spec file
+- `"./file.md#section-id"` — script from section in specific file
+
+The section ID is derived from the heading: spaces become hyphens, lowercase.
+Example: `## Kiosk Browser Configuration Script` → `#kiosk-browser-configuration-script`
+
+### Execute Script by Reference (`redeploy exec`)
+
+Run a single script from markdown without running the full migration:
+
+```bash
+# Execute script from codeblock on remote host
+redeploy exec '#kiosk-browser-configuration-script' \
+    --host pi@192.168.188.108 \
+    --file migration.podman-rpi5-resume.md
+
+# With file in reference
+redeploy exec './migration.md#install-deps' --host root@server.com
+
+# Using markpact:ref (more explicit)
+redeploy exec 'kiosk-script-id' --host pi@192.168.188.108 --file migration.md
+
+# Dry-run to preview script
+redeploy exec '#backup-script' --host pi@192.168.188.108 --file ops.md --dry-run
+```
+
+This is useful for:
+- One-off operations defined in markdown docs
+- Testing individual scripts before full migration
+- Running maintenance tasks
+
+### Execute Multiple Scripts (`redeploy exec-multi`)
+
+Test multiple scripts at once:
+
+```bash
+# Execute multiple scripts by ref
+redeploy exec-multi 'kiosk-script,install-deps,cleanup' \
+    --host pi@192.168.188.108 \
+    --file migration.md
+
+# Mix of markpact:ref and section headings
+redeploy exec-multi 'script1,#section2,script3' \
+    --host root@server.com \
+    --file deploy.md \
+    --dry-run
+```
+
+### Marking Codeblocks with `markpact:ref`
+
+For more explicit script identification, use `markpact:ref <id>` in codeblock:
+
+```markdown
+```bash markpact:ref kiosk-browser-configuration-script
+#!/bin/bash
+# Auto-detect browser...
+if command -v chromium-browser >/dev/null 2>&1; then
+  chromium-browser --kiosk http://localhost:8100
+fi
+```
+```
+
+Benefits of `markpact:ref`:
+- Explicit ID assignment (not derived from heading)
+- Multiple scripts per section
+- Can reference by simple ID instead of full heading
+- Self-documenting in markdown
+
 
 
 Place in project root — `redeploy run` (no args) uses it automatically.

{redeploy-0.2.17 → redeploy-0.2.18}/pyproject.toml

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

{redeploy-0.2.17 → redeploy-0.2.18}/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.17"
+__version__ = "0.2.18"
 
 # ── Core models ───────────────────────────────────────────────────────────────
 from .models import (  # noqa: F401

{redeploy-0.2.17 → redeploy-0.2.18}/redeploy/apply/executor.py

@@ -143,10 +143,14 @@ class Executor:
         self._audit_path = audit_path
         self._t0: float = 0.0
 
+        # ── spec path for command_ref resolution ─────────────────────────────
+        if spec_path and not plan.spec_path:
+            plan.spec_path = spec_path
+
         # ── resume / checkpoint ──────────────────────────────────────────────
         self._resume = resume
         self._from_step = from_step
-        spec_id = spec_path or plan.target_file or plan.infra_file or plan.app
+        spec_id = spec_path or plan.spec_path or plan.target_file or plan.infra_file or plan.app
         if state_path is None and not dry_run:
             state_path = default_state_path(spec_id, plan.host)
         self._state_path: Optional[Path] = (
@@ -578,9 +582,10 @@ class Executor:
         command_ref formats:
         - "./file.md#section-id" - script from section in specific file
         - "#section-id" - script from section in current spec file
+        - "#kiosk-browser-configuration-script" - markpact:ref block
         """
         from pathlib import Path
-        from ..markpact.parser import extract_script_from_markdown
+        from ..markpact.parser import extract_script_from_markdown, extract_script_by_ref
         
         # Parse command_ref
         if "#" in command_ref:
@@ -597,12 +602,20 @@ class Executor:
         if not file_path.exists():
             raise StepError(step, f"Command ref file not found: {file_path}")
         
-        # Extract script from markdown
+        # Extract script from markdown - try both methods:
+        # 1. First try markpact:ref codeblock (new format)
+        # 2. Then try section heading (old format)
         markdown_content = file_path.read_text(encoding="utf-8")
-        script = extract_script_from_markdown(markdown_content, section_id, language="bash")
+        
+        # Try markpact:ref format first
+        script = extract_script_by_ref(markdown_content, section_id, language="bash")
+        
+        # Fallback to section heading format
+        if script is None:
+            script = extract_script_from_markdown(markdown_content, section_id, language="bash")
         
         if script is None:
-            raise StepError(step, f"Could not find bash script in section '{section_id}' of {file_path}")
+            raise StepError(step, f"Could not find bash script for ref '{section_id}' in {file_path} (tried markpact:ref and section heading)")
         
         return script
 

{redeploy-0.2.17 → redeploy-0.2.18}/redeploy/cli.py

@@ -743,6 +743,237 @@ def plugin_cmd(ctx, subcommand, name):
         console.print(f"\n{doc}")
 
 
+# ── exec (execute script from markdown by reference) ───────────────────────────
+
+@cli.command("exec")
+@click.argument("ref", required=True)
+@click.option("--host", required=True, help="SSH host (user@ip) or 'local'")
+@click.option("--file", "markdown_file", default=None, type=click.Path(),
+              help="Markdown file (required if ref doesn't specify file)")
+@click.option("--dry-run", is_flag=True, help="Show script without executing")
+@click.option("--timeout", default=300, help="Step timeout in seconds")
+@click.pass_context
+def exec_cmd(ctx, ref, host, markdown_file, dry_run, timeout):
+    """Execute a script from a markdown codeblock by reference.
+
+    REF format: #section-id or ./file.md#section-id or just ref-id (for markpact:ref)
+
+    Extracts the script from a ```bash codeblock in the specified section
+    or from a codeblock marked with markpact:ref <id>.
+
+    \b
+    Examples:
+        redeploy exec '#kiosk-browser-configuration-script' --host pi@192.168.188.108 --file migration.md
+        redeploy exec './migration.md#kiosk-script' --host pi@192.168.188.108
+        redeploy exec '#install-deps' --host root@server.com --file deploy.md --dry-run
+        redeploy exec 'kiosk-browser-configuration-script' --host pi@192.168.188.108 --file migration.md
+    """
+    from rich.console import Console
+    from pathlib import Path
+    from .markpact.parser import extract_script_from_markdown, extract_script_by_ref
+    from .detect.remote import RemoteProbe
+    from .apply.executor import Executor, MigrationPlan, MigrationStep, StepAction, StepStatus
+
+    console = Console()
+
+    # Parse reference
+    if "#" in ref:
+        file_part, section_id = ref.split("#", 1)
+        if file_part:
+            md_path = Path(file_part)
+        elif markdown_file:
+            md_path = Path(markdown_file)
+        else:
+            console.print("[red]✗ No file specified in ref and no --file provided[/red]")
+            sys.exit(1)
+        ref_id = section_id
+        use_section_lookup = True
+    else:
+        ref_id = ref
+        if not markdown_file:
+            console.print("[red]✗ --file required when ref doesn't specify file[/red]")
+            sys.exit(1)
+        md_path = Path(markdown_file)
+        use_section_lookup = False
+
+    if not md_path.exists():
+        console.print(f"[red]✗ File not found: {md_path}[/red]")
+        sys.exit(1)
+
+    # Extract script from markdown
+    console.print(f"[dim]Reading {md_path}...[/dim]")
+    md_content = md_path.read_text(encoding="utf-8")
+    
+    # Try markpact:ref lookup first (more specific), then fallback to section lookup
+    script = extract_script_by_ref(md_content, ref_id, language="bash")
+    lookup_method = "markpact:ref"
+    
+    if script is None and use_section_lookup:
+        script = extract_script_from_markdown(md_content, ref_id, language="bash")
+        lookup_method = "section heading"
+    
+    if script is None:
+        console.print(f"[red]✗ Could not find bash script with ref '#{ref_id}'[/red]")
+        console.print("[dim]  Make sure there's either:[/dim]")
+        console.print("[dim]    - A codeblock: ```bash markpact:ref {ref_id}[/dim]")
+        console.print("[dim]    - Or a ## section heading and ```bash codeblock[/dim]")
+        sys.exit(1)
+
+    console.print(f"[green]✓[/green] Found script ({len(script)} chars) via {lookup_method} '#{ref_id}'")
+
+    if dry_run:
+        console.print(f"\n[bold]Script content (dry-run):[/bold]")
+        console.print("```bash")
+        console.print(script)
+        console.print("```")
+        return
+
+    # Execute script on remote host
+    console.print(f"\n[bold]Executing on {host}...[/bold]")
+
+    # Create minimal plan with single step
+    step = MigrationStep(
+        id=f"exec_{ref_id}",
+        action=StepAction.INLINE_SCRIPT,
+        description=f"Execute script from #{ref_id}",
+        command=script,
+        timeout=timeout,
+    )
+    plan = MigrationPlan(
+        host=host,
+        app="exec",
+        from_strategy="unknown",
+        to_strategy="unknown",
+        steps=[step],
+    )
+
+    executor = Executor(plan, dry_run=False)
+    ok = executor.run()
+
+    if not ok:
+        sys.exit(1)
+
+    console.print(f"[green]✓ Script executed successfully[/green]")
+
+
+# ── exec-multi (execute multiple scripts by ref) ───────────────────────────────
+
+@cli.command("exec-multi")
+@click.argument("refs")
+@click.option("--host", required=True, help="SSH host (user@ip) or 'local'")
+@click.option("--file", "markdown_file", required=True, type=click.Path(),
+              help="Markdown file containing scripts")
+@click.option("--dry-run", is_flag=True, help="Show scripts without executing")
+@click.option("--timeout", default=300, help="Step timeout in seconds")
+@click.option("--parallel", is_flag=True, help="Execute scripts in parallel (default: sequential)")
+@click.pass_context
+def exec_multi_cmd(ctx, refs, host, markdown_file, dry_run, timeout, parallel):
+    """Execute multiple scripts from markdown codeblocks by reference.
+
+    REFS format: comma-separated list of ref ids (markpact:ref or section headings)
+
+    \b
+    Examples:
+        redeploy exec-multi 'kiosk-script,install-deps,cleanup' \
+            --host pi@192.168.188.108 --file migration.md
+
+        redeploy exec-multi '#section1,#section2' \
+            --host root@server.com --file deploy.md --dry-run
+    """
+    from rich.console import Console
+    from rich.table import Table
+    from pathlib import Path
+    from .markpact.parser import extract_script_from_markdown, extract_script_by_ref
+    from .apply.executor import Executor, MigrationPlan, MigrationStep, StepAction, StepStatus
+
+    console = Console()
+    md_path = Path(markdown_file)
+
+    if not md_path.exists():
+        console.print(f"[red]✗ File not found: {md_path}[/red]")
+        sys.exit(1)
+
+    # Parse refs
+    ref_list = [r.strip() for r in refs.split(",")]
+    console.print(f"[bold]Loading {len(ref_list)} scripts from {md_path}...[/bold]")
+
+    md_content = md_path.read_text(encoding="utf-8")
+
+    # Extract all scripts
+    scripts: list[tuple[str, str, str]] = []  # (ref_id, script, lookup_method)
+    for ref_id in ref_list:
+        # Try markpact:ref first
+        script = extract_script_by_ref(md_content, ref_id, language="bash")
+        lookup_method = "markpact:ref"
+
+        if script is None and ref_id.startswith("#"):
+            # Try section lookup
+            script = extract_script_from_markdown(md_content, ref_id[1:], language="bash")
+            lookup_method = "section"
+
+        if script is None:
+            console.print(f"[red]✗ Could not find script: {ref_id}[/red]")
+            sys.exit(1)
+
+        scripts.append((ref_id, script, lookup_method))
+        console.print(f"  [green]✓[/green] {ref_id} ({len(script)} chars, {lookup_method})")
+
+    if dry_run:
+        console.print(f"\n[bold]Scripts (dry-run):[/bold]")
+        for ref_id, script, _ in scripts:
+            console.print(f"\n--- {ref_id} ---")
+            console.print("```bash")
+            console.print(script[:500] + ("..." if len(script) > 500 else ""))
+            console.print("```")
+        return
+
+    # Execute scripts
+    console.print(f"\n[bold]Executing on {host}...[/bold]")
+
+    results = []
+    for ref_id, script, _ in scripts:
+        console.print(f"  Running {ref_id}...", end=" ")
+
+        step = MigrationStep(
+            id=f"exec_{ref_id}",
+            action=StepAction.INLINE_SCRIPT,
+            description=f"Execute script from {ref_id}",
+            command=script,
+            timeout=timeout,
+        )
+        plan = MigrationPlan(
+            host=host,
+            app="exec-multi",
+            from_strategy="unknown",
+            to_strategy="unknown",
+            steps=[step],
+        )
+
+        executor = Executor(plan, dry_run=False)
+        ok = executor.run()
+        results.append((ref_id, ok))
+
+        if ok:
+            console.print("[green]✓[/green]")
+        else:
+            console.print("[red]✗[/red]")
+
+    # Summary table
+    console.print(f"\n[bold]Results:[/bold]")
+    t = Table(show_header=True, box=None)
+    t.add_column("Script")
+    t.add_column("Status")
+    for ref_id, ok in results:
+        status = "[green]✓ OK[/green]" if ok else "[red]✗ Failed[/red]"
+        t.add_row(ref_id, status)
+    console.print(t)
+
+    if not all(ok for _, ok in results):
+        sys.exit(1)
+
+    console.print(f"\n[green]✓ All {len(scripts)} scripts executed successfully[/green]")
+
+
 # ── plan ──────────────────────────────────────────────────────────────────────
 
 @cli.command()
@@ -1047,6 +1278,98 @@ def run(ctx, spec_file, dry_run, plan_only, do_detect, plan_out, output,
         sys.exit(1)
 
 
+# ── state (resume checkpoints) ───────────────────────────────────────────────
+
+@cli.command("state")
+@click.argument("action", type=click.Choice(["show", "clear", "ls"]),
+                default="show")
+@click.argument("spec_file", default=None, required=False, type=click.Path())
+@click.option("--host", default=None, help="Override host (default: from spec)")
+@click.option("--state-file", default=None, type=click.Path(),
+              help="Explicit checkpoint path")
+@click.pass_context
+def state_cmd(ctx, action, spec_file, host, state_file):
+    """Inspect or clear resume checkpoints.
+
+    \b
+    Examples:
+        redeploy state show migration.yaml      # current checkpoint
+        redeploy state clear migration.yaml     # delete checkpoint
+        redeploy state ls                       # list all checkpoints in CWD
+    """
+    from rich.console import Console
+    from rich.table import Table
+    from .apply.state import DEFAULT_STATE_DIR, ResumeState, default_state_path
+
+    console = Console()
+
+    if action == "ls":
+        base = DEFAULT_STATE_DIR
+        if not base.exists():
+            console.print(f"[dim]no checkpoints under {base}/[/dim]")
+            return
+        files = sorted(base.glob("*.yaml"))
+        if not files:
+            console.print(f"[dim]no checkpoints under {base}/[/dim]")
+            return
+        t = Table(show_header=True, box=None, padding=(0, 2))
+        t.add_column("File", style="bold")
+        t.add_column("Spec")
+        t.add_column("Host", style="cyan")
+        t.add_column("Done")
+        t.add_column("Failed", style="red")
+        t.add_column("Updated", style="dim")
+        for f in files:
+            try:
+                st = ResumeState.load(f)
+                t.add_row(
+                    f.name, st.spec_path or "?", st.host,
+                    f"{st.completed_count}/{st.total_steps}",
+                    st.failed_step_id or "—",
+                    st.updated_at,
+                )
+            except Exception as e:
+                t.add_row(f.name, "[red]parse error[/red]", "—", "—", "—", str(e)[:40])
+        console.print(t)
+        return
+
+    # show / clear need a path
+    if state_file:
+        path = Path(state_file)
+    else:
+        if not spec_file:
+            console.print("[red]✗ provide SPEC or --state-file[/red]")
+            sys.exit(2)
+        spec = _load_spec_or_exit(console, spec_file)
+        target_host = host or spec.source.host or "local"
+        path = default_state_path(spec_file, target_host)
+
+    if not path.exists():
+        console.print(f"[dim]no checkpoint at {path}[/dim]")
+        return
+
+    if action == "clear":
+        path.unlink()
+        console.print(f"[green]✓ removed {path}[/green]")
+        return
+
+    # show
+    st = ResumeState.load(path)
+    console.print(f"[bold]checkpoint[/bold] {path}")
+    console.print(f"  spec:        {st.spec_path}")
+    console.print(f"  host:        {st.host}")
+    console.print(f"  progress:    {st.completed_count}/{st.total_steps} "
+                  f"({st.remaining} pending)")
+    console.print(f"  started:     {st.started_at}")
+    console.print(f"  updated:     {st.updated_at}")
+    if st.failed_step_id:
+        console.print(f"  [red]failed:      {st.failed_step_id}[/red]")
+        if st.failed_error:
+            console.print(f"  [red]error:       {st.failed_error[:200]}[/red]")
+    if st.completed_step_ids:
+        console.print(f"  done:        {', '.join(st.completed_step_ids)}")
+
+
 # ── helper ────────────────────────────────────────────────────────────────────
 
 def _find_manifest_path() -> str: