heritage-cli 1.0.0__py3-none-any.whl

heritage_cli/__init__.py

@@ -0,0 +1,21 @@
+"""heritage-cli — Unified CLI for the heritage science open-source ecosystem.
+
+Provides a single `heritage` command that routes to sibling projects:
+    heritage run       → hoard run (HOARD pipeline)
+    heritage calibrate → libby (radiocarbon calibration)
+    heritage lithics   → dibble (lithic analysis)
+    heritage review    → trowel (review dashboard)
+    heritage matrix    → stratigraph (Harris Matrix)
+    heritage publish   → hoard export (final report)
+    heritage tools     → list installed ecosystem tools
+
+Usage:
+    heritage --help
+    heritage run --project X --phase 0
+    heritage calibrate --project X --input samples.json
+    heritage tools list
+
+Configuration: ~/.config/heritage/config.toml
+"""
+
+__version__ = "1.0.0"

heritage_cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""Command dispatch modules for sibling tools.
+
+Each module exposes `tool_name` and `dispatch()` for the plugin
+discovery system. Tools can be invoked via `heritage <tool>` or
+programmatically via `dispatch()`.
+"""

heritage_cli/commands/hoard.py

@@ -0,0 +1,19 @@
+"""HOARD command dispatch — run pipeline phases.
+
+Registered as heritage_cli.commands.hoard in entry_points.
+"""
+
+tool_name = "hoard"
+description = "Heritage Observation And Report Drafter — AI pipeline"
+
+
+def dispatch(args: list[str] | None = None) -> int:
+    """Run hoard with the given CLI arguments.
+
+    Returns subprocess exit code.
+    """
+    import subprocess
+    import sys
+    cmd = ["hoard"] + (args or sys.argv[2:])
+    result = subprocess.run(cmd)
+    return result.returncode

heritage_cli/main.py

@@ -0,0 +1,389 @@
+"""main.py — Heritage CLI entry point and command tree.
+
+Uses Typer for the command hierarchy with Rich for output formatting.
+Routes commands to sibling project executables or Python packages.
+
+Usage:
+    heritage --help
+    heritage run --project X --phase 0
+    heritage run --project X --auto
+    heritage calibrate --project X
+    heritage lithics --project X --input ./scans/
+    heritage review --project X
+    heritage matrix --project X
+    heritage publish --project X --format docx,pdf
+    heritage tools list
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from heritage_cli import __version__
+
+app = typer.Typer(
+    name="heritage",
+    help="Heritage science ecosystem CLI — orchestrates HOARD, StratiGraph, Trowel, Libby, and Dibble",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+console = Console()
+
+
+# ── Version callback ─────────────────────────────────────────────────────────
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"heritage-cli v{__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(False, "--version", "-V", help="Show version and exit", callback=_version_callback),
+) -> None:
+    """Heritage science ecosystem CLI."""
+
+
+# ── Config ───────────────────────────────────────────────────────────────────
+
+
+def load_config() -> dict:
+    """Load ~/.config/heritage/config.toml, returning defaults on failure."""
+    import tomllib
+    config_path = Path.home() / ".config" / "heritage" / "config.toml"
+    if not config_path.exists():
+        return {}
+    try:
+        with open(config_path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError):
+        return {}
+
+
+def find_tool(name: str) -> str | None:
+    """Find an installed tool's executable path via shutil.which."""
+    import shutil
+    return shutil.which(name)
+
+
+# ── Commands ─────────────────────────────────────────────────────────────────
+
+
+@app.command()
+def run(
+    project: str = typer.Option(..., "--project", "-p", help="Project ID"),
+    phase: int | None = typer.Option(None, "--phase", help="Run a single phase only"),
+    from_phase: int | None = typer.Option(None, "--from-phase", help="Run from this phase onward"),
+    pipeline: str | None = typer.Option(None, "--pipeline", "-P", help="Path to pipeline YAML file"),
+    auto: bool = typer.Option(False, "--auto", help="Run full pipeline from Phase 0 (or skip review gates with --pipeline)"),
+    input_dir: str = typer.Option("./input", "--input", "-i", help="Input directory"),
+    strict: bool = typer.Option(False, "--strict", "-s", help="Halt on schema validation failure"),
+    extractor: str = typer.Option("glm-ocr", "--extractor", "-e", help="Extraction model"),
+    workspace: str = typer.Option("./erd_workspace", "--workspace", "-w", help="Workspace root"),
+) -> None:
+    """Run the HOARD pipeline (or a single phase, or a multi-tool pipeline).
+
+    Use --pipeline to run a declarative multi-tool pipeline YAML with
+    automated steps and human review gates.
+
+    Examples:
+        heritage run --project X --phase 0       # Single phase
+        heritage run --project X --auto           # Full HOARD pipeline
+        heritage run --project X --pipeline pipe.yaml   # Multi-tool pipeline
+    """
+    if pipeline:
+        from heritage_cli.orchestrator import PipelineOrchestrator
+        orch = PipelineOrchestrator(
+            pipeline_path=pipeline,
+            project_id=project,
+            workspace=workspace,
+            auto=auto,
+        )
+        try:
+            orch.load()
+            orch.run()
+        except (FileNotFoundError, ValueError) as e:
+            console.print(f"[red]✗[/] {e}")
+            raise typer.Exit(1)
+        return
+
+    hoard_bin = find_tool("hoard")
+    if hoard_bin:
+        import subprocess
+        cmd = [hoard_bin, "run", "--project", project, "--workspace", workspace]
+        if phase is not None:
+            cmd.extend(["--phase", str(phase)])
+        if from_phase is not None:
+            cmd.extend(["--from-phase", str(from_phase)])
+        if input_dir:
+            cmd.extend(["--input", input_dir])
+        if strict:
+            cmd.append("--strict")
+        if extractor:
+            cmd.extend(["--extractor", extractor])
+        if auto:
+            cmd.extend(["--from-phase", "0"])
+        console.print(f"[blue]→[/] Running: {' '.join(cmd)}")
+        subprocess.run(cmd)
+    else:
+        # Fallback: import and run HOARD directly
+        try:
+            from hoard.config import Config
+            from hoard.cli.run import run_pipeline, run_single_phase
+
+            cfg = Config(
+                project_id=project,
+                project_name=project,
+                jurisdiction="historic_england_cl3",
+                workspace_root=Path(workspace).resolve(),
+                input_dir=Path(input_dir).resolve(),
+                strict=strict,
+                extractor=extractor,
+            )
+            if phase is not None:
+                run_single_phase(cfg, phase)
+            else:
+                run_pipeline(cfg)
+        except ImportError:
+            console.print("[red]✗[/] HOARD not installed. Run: pip install hoard")
+
+
+@app.command()
+def calibrate(
+    project: str = typer.Option(..., "--project", "-p", help="Project ID"),
+    input_file: str = typer.Option("", "--input", "-i", help="Samples JSON file path"),
+    workspace: str = typer.Option("./erd_workspace", "--workspace", "-w", help="Workspace root"),
+) -> None:
+    """Calibrate radiocarbon samples using Libby.
+
+    Reads sample data from the project workspace or specified input file,
+    runs Libby calibration, and writes calibrated dates back to the workspace.
+    """
+    libby_bin = find_tool("libby")
+    if libby_bin:
+        import subprocess
+        input_path = input_file or f"{workspace}/{project}/01_digitised/samples.json"
+        cmd = [libby_bin, "calibrate", "--input", input_path, "--workspace", f"{workspace}/{project}"]
+        console.print(f"[blue]→[/] Running: {' '.join(cmd)}")
+        subprocess.run(cmd)
+    else:
+        console.print("[yellow]ℹ[/] Libby not installed. Install with: pip install libby")
+        console.print("  Or manually calibrate samples at a Libby web instance.")
+
+
+@app.command(name="lithics")
+def lithics(
+    project: str = typer.Option(..., "--project", "-p", help="Project ID"),
+    input_dir: str = typer.Option("./scans", "--input", "-i", help="Directory with 3D scans or photos"),
+    workspace: str = typer.Option("./erd_workspace", "--workspace", "-w", help="Workspace root"),
+) -> None:
+    """Run lithic analysis using Dibble.
+
+    Processes 3D scans or photographs through Dibble's classification pipeline
+    and writes results into the project workspace for HOARD Phase 3 consumption.
+    """
+    dibble_bin = find_tool("dibble")
+    if dibble_bin:
+        import subprocess
+        cmd = [dibble_bin, "process", "--input", input_dir, "--output", f"{workspace}/{project}/02_spatial/lithics/"]
+        console.print(f"[blue]→[/] Running: {' '.join(cmd)}")
+        subprocess.run(cmd)
+    else:
+        console.print("[yellow]ℹ[/] Dibble not installed. Install with: pip install dibble")
+        console.print("  Or manually add lithic analysis to the specialist appendices.")
+
+
+@app.command()
+def review(
+    project: str = typer.Option(..., "--project", "-p", help="Project ID"),
+    workspace: str = typer.Option("./erd_workspace", "--workspace", "-w", help="Workspace root"),
+    reset: bool = typer.Option(False, "--reset", "-r", help="Reset all review decisions"),
+) -> None:
+    """Open the interactive review dashboard.
+
+    Delegates to Trowel (if installed as desktop app) or HOARD's terminal
+    review dashboard (CLI fallback). Both share the same flag data format.
+    """
+    trowel_bin = find_tool("trowel")
+    if trowel_bin:
+        import subprocess
+        cmd = [trowel_bin, "open", "--project", project, "--workspace", workspace]
+        if reset:
+            cmd.append("--reset")
+        console.print(f"[blue]→[/] Running: {' '.join(cmd)}")
+        subprocess.run(cmd)
+    else:
+        # Fallback: use HOARD's review dashboard
+        try:
+            from hoard.config import Config
+            hoard_cfg = Config(
+                project_id=project,
+                project_name=project,
+                jurisdiction="historic_england_cl3",
+                workspace_root=Path(workspace).resolve(),
+                input_dir=Path("./input"),
+            )
+            from hoard.review import ReviewSession
+            session = ReviewSession(hoard_cfg)
+            session.load()
+            if session.total == 0:
+                console.print(f"[yellow]ℹ[/] No flagged items for project '{project}'.")
+                return
+            session.run_interactive()
+        except ImportError:
+            console.print("[red]✗[/] Neither Trowel nor HOARD review dashboard available.")
+            console.print("  Install HOARD: pip install hoard")
+
+
+@app.command()
+def matrix(
+    project: str = typer.Option(..., "--project", "-p", help="Project ID"),
+    workspace: str = typer.Option("./erd_workspace", "--workspace", "-w", help="Workspace root"),
+) -> None:
+    """Open the Harris Matrix in StratiGraph.
+
+    Imports HOARD Phase 1 context data into StratiGraph for interactive
+    Harris Matrix visualisation, validation, and EEDP export.
+    """
+    stratigraph_bin = find_tool("stratigraph")
+    if stratigraph_bin:
+        import subprocess
+        cmd = [stratigraph_bin, "import", "--data", f"{workspace}/{project}/01_digitised/"]
+        console.print(f"[blue]→[/] Running: {' '.join(cmd)}")
+        subprocess.run(cmd)
+    else:
+        console.print("[yellow]ℹ[/] StratiGraph not installed.")
+        console.print("  Install from: https://github.com/mabo-du/stratigraph")
+        console.print(f"  Or import {workspace}/{project}/01_digitised/ manually.")
+
+
+@app.command()
+def publish(
+    project: str = typer.Option(..., "--project", "-p", help="Project ID"),
+    fmt: str = typer.Option("docx,pdf", "--format", "-f", help="Output formats (comma-separated)"),
+    workspace: str = typer.Option("./erd_workspace", "--workspace", "-w", help="Workspace root"),
+) -> None:
+    """Publish the final report (Phase 5 assembly + export).
+
+    Delegates to HOARD's Phase 5 export, which generates DOCX, PDF/A-2b,
+    TEI-XML, and ZIP outputs from the assembled report data.
+    """
+    try:
+        from hoard.config import load_config
+        cfg = load_config(project, Path(workspace))
+        if cfg is None:
+            console.print(f"[red]✗[/] Project '{project}' not found at {workspace}")
+            console.print("  Run 'hoard init' first.")
+            raise typer.Exit(1)
+
+        from hoard.phases.phase5 import run_phase5
+        formats = [f.strip() for f in fmt.split(",")]
+        console.print(f"[blue]→[/] Publishing [bold]{project}[/] as: {', '.join(formats)}")
+        result = run_phase5(cfg, formats=formats)
+        export_paths = result.get("export_paths", {})
+        if export_paths:
+            console.print(f"[green]✓[/] Published:")
+            for name, path in export_paths.items():
+                console.print(f"  • {name}: {path}")
+        else:
+            console.print("[yellow]ℹ[/] No output generated. Run the pipeline first.")
+    except ImportError:
+        console.print("[red]✗[/] HOARD not installed. Run: pip install hoard")
+
+
+# ── Pipeline Status ──────────────────────────────────────────────────────────
+
+
+@app.command(name="pipeline-status")
+def pipeline_status(
+    project: str = typer.Option(..., "--project", "-p", help="Project ID"),
+    workspace: str = typer.Option("./erd_workspace", "--workspace", "-w", help="Workspace root"),
+) -> None:
+    """Show the status of the most recent pipeline run for a project."""
+    from heritage_cli.orchestrator import PipelineOrchestrator
+
+    # Find the most recent pipeline state file
+    state_dir = Path(workspace) / project
+    state_file = state_dir / "pipeline_state.json"
+    if not state_file.exists():
+        console.print(f"[yellow]ℹ[/] No pipeline state found for project '{project}'")
+        console.print(f"  Run [bold]heritage run --project {project} --pipeline <file>[/] first")
+        return
+
+    try:
+        import json
+        data = json.loads(state_file.read_text())
+        console.print(f"[bold]Pipeline Status:[/] {data.get('project', project)}")
+        console.print(f"  State file:  {state_file}")
+        console.print(f"  Pipeline:    {data.get('pipeline', 'unknown')}")
+        console.print(f"  Last update: {data.get('updated_at', 'unknown')}")
+        console.print()
+        steps = data.get("steps", {})
+        console.print(f"[bold]Steps ({len(steps)}):[/]")
+        for step_id, status in steps.items():
+            icon = {"pending": "○", "running": "→", "complete": "✓",
+                    "skipped": "−", "failed": "✗", "blocked": "⊘"}
+            marker = icon.get(status, "?")
+            console.print(f"  {marker} {step_id}: {status}")
+    except (json.JSONDecodeError, OSError) as e:
+        console.print(f"[red]✗[/] Failed to read pipeline state: {e}")
+
+
+# ── Tools sub-command ────────────────────────────────────────────────────────
+
+
+@app.command(name="tools")
+def tools_list() -> None:
+    """List installed heritage ecosystem tools and their status."""
+    table = Table(title="Heritage Ecosystem Tools")
+    table.add_column("Tool", style="cyan")
+    table.add_column("Installed", style="green")
+    table.add_column("Version", style="yellow")
+    table.add_column("Description")
+
+    tools = [
+        ("hoard", find_tool("hoard"), "HOARD pipeline"),
+        ("stratigraph", find_tool("stratigraph"), "Harris Matrix editor"),
+        ("trowel", find_tool("trowel"), "Desktop report drafter"),
+        ("libby", find_tool("libby"), "Radiocarbon calibration"),
+        ("dibble", find_tool("dibble"), "Lithic analysis"),
+        ("fritts", find_tool("fritts"), "Dendrochronology"),
+        ("argus", find_tool("argus"), "Site surveillance"),
+    ]
+
+    for name, installed, desc in tools:
+        status = "[green]✓[/]" if installed else "[red]✗[/]"
+        version = ""
+        if installed:
+            import subprocess
+            try:
+                result = subprocess.run([name, "--version"], capture_output=True, text=True, timeout=5)
+                version = result.stdout.strip() or result.stderr.strip()
+                version = version[:30]
+                # Clean up traceback noise from stderr
+                if "Traceback" in version or "Error" in version:
+                    version = "?"
+            except (OSError, subprocess.TimeoutExpired):
+                version = "?"
+        table.add_row(name, status, version or "-", desc)
+
+    console.print(table)
+    console.print("\n[yellow]ℹ[/] Run [bold]pip install <tool>[/] for tools marked ✗")
+
+
+# ── Entry point ──────────────────────────────────────────────────────────────
+
+
+def entry_point() -> None:
+    """Console-scripts entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    app()

heritage_cli/orchestrator.py

@@ -0,0 +1,507 @@
+"""orchestrator.py — Pipeline orchestration engine with review gates.
+
+Implements a checkpoint-based execution model where a declarative YAML
+pipeline definition is run step by step, pausing at human review gates
+for expert validation. Pipeline state is persisted to a JSON file for
+resumability after interruption.
+
+Pipeline YAML format:
+    steps:
+      - project: hoard
+        phases: [0, 1, 2]
+      - gate: review
+        message: "Review the Harris Matrix in StratiGraph before proceeding"
+        action: "stratigraph import --path output/01_digitised"
+      - project: libby
+        action: calibrate
+        input: output/01_digitised/samples.json
+      - project: hoard
+        phases: [3, 4, 5]
+      - gate: review
+        message: "Review the draft before final export"
+      - project: hoard
+        action: export
+        formats: [docx, pdf]
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+# ── Step types ────────────────────────────────────────────────────────────────
+
+
+class StepStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETE = "complete"
+    SKIPPED = "skipped"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+
+
+class StepKind(str, Enum):
+    HOARD = "hoard"  # Run HOARD pipeline phases
+    GATE = "gate"  # Human review gate — pauses execution
+    COMMAND = "command"  # Run an arbitrary shell command
+    LIBBY = "libby"  # Calibrate samples
+    DIBBLE = "dibble"  # Run lithic analysis
+    EXPORT = "export"  # Final report export
+
+
+# ── Data models ───────────────────────────────────────────────────────────────
+
+
+@dataclass
+class PipelineStep:
+    """A single step in the pipeline DAG."""
+
+    id: str
+    kind: StepKind
+    status: StepStatus = StepStatus.PENDING
+    message: str = ""  # For GATE steps: prompt shown to user
+    action: str = ""  # For GATE steps: suggestion of what to do
+    tool_args: dict[str, Any] = field(default_factory=dict)  # Phase-specific args
+    depends_on: list[str] = field(default_factory=list)
+
+    # Runtime fields (not serialised in pipeline.yaml)
+    error: str = ""
+
+
+@dataclass
+class PipelineState:
+    """Persistent state ledger for pipeline resumability."""
+
+    project_id: str
+    pipeline_path: str
+    steps: dict[str, StepStatus] = field(default_factory=dict)
+    started_at: str = ""
+    updated_at: str = ""
+
+
+# ── Orchestrator ──────────────────────────────────────────────────────────────
+
+
+class PipelineOrchestrator:
+    """Executes a pipeline definition step by step with review gates.
+
+    Usage:
+        orch = PipelineOrchestrator("path/to/pipeline.yaml", project_id="my_site")
+        orch.run()
+    """
+
+    def __init__(
+        self,
+        pipeline_path: str | Path,
+        project_id: str = "",
+        workspace: str = "./erd_workspace",
+        auto: bool = False,
+    ) -> None:
+        self.pipeline_path = Path(pipeline_path)
+        self.project_id = project_id
+        self.workspace = Path(workspace)
+        self.auto = auto  # If True, skip review gates automatically
+        self.steps: list[PipelineStep] = []
+        self.state_dir = self.workspace / project_id
+        self.state_file = self.state_dir / "pipeline_state.json"
+        self._step_map: dict[str, PipelineStep] = {}
+
+    # ── Loading ──────────────────────────────────────────────────────────
+
+    def load(self) -> None:
+        """Load and parse a pipeline YAML definition."""
+        import yaml
+
+        if not self.pipeline_path.exists():
+            raise FileNotFoundError(f"Pipeline file not found: {self.pipeline_path}")
+
+        raw = yaml.safe_load(self.pipeline_path.read_text())
+        if not raw or "steps" not in raw:
+            raise ValueError(f"Pipeline file must contain a 'steps' list")
+
+        steps_raw = raw["steps"]
+        self.steps = []
+        for i, step_raw in enumerate(steps_raw):
+            step = self._parse_step(step_raw, i)
+            self.steps.append(step)
+            self._step_map[step.id] = step
+
+    def _parse_step(self, raw: dict, index: int) -> PipelineStep:
+        """Parse a single step from YAML."""
+        # Determine kind
+        if "gate" in raw:
+            kind = StepKind.GATE
+            step_id = raw.get("id", f"gate_{index}")
+        elif "project" in raw:
+            kind = StepKind(raw["project"])
+            step_id = raw.get("id", f"{kind.value}_{index}")
+        else:
+            kind = StepKind.COMMAND
+            step_id = raw.get("id", f"cmd_{index}")
+
+        return PipelineStep(
+            id=step_id,
+            kind=kind,
+            message=raw.get("message", ""),
+            action=raw.get("action", ""),
+            tool_args=self._extract_args(raw, kind),
+            depends_on=raw.get("depends_on", []),
+        )
+
+    def _extract_args(self, raw: dict, kind: StepKind) -> dict[str, Any]:
+        """Extract tool-specific arguments from the step definition."""
+        args: dict[str, Any] = {}
+        if kind == StepKind.HOARD:
+            args["phases"] = raw.get("phases", [])
+            args["from_phase"] = raw.get("from_phase")
+            args["extractor"] = raw.get("extractor", "glm-ocr")
+            args["strict"] = raw.get("strict", False)
+        elif kind == StepKind.LIBBY:
+            args["input"] = raw.get("input", "")
+            args["action"] = raw.get("action", "calibrate")
+        elif kind == StepKind.DIBBLE:
+            args["input"] = raw.get("input", "./scans")
+            args["output"] = raw.get("output", "")
+        elif kind == StepKind.EXPORT:
+            args["formats"] = raw.get("formats", ["docx", "pdf"])
+        elif kind == StepKind.COMMAND:
+            args["command"] = raw.get("command", "")
+        return args
+
+    # ── State Management ─────────────────────────────────────────────────
+
+    def _load_state(self) -> dict[str, StepStatus]:
+        """Load pipeline state from disk for resumability."""
+        if self.state_file.exists():
+            try:
+                data = json.loads(self.state_file.read_text())
+                raw_steps = data.get("steps", {})
+                return {k: StepStatus(v) for k, v in raw_steps.items()}
+            except (json.JSONDecodeError, ValueError):
+                pass
+        return {}
+
+    def _save_state(self) -> None:
+        """Persist current pipeline state to disk."""
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        from datetime import datetime, timezone
+        state = {
+            "project_id": self.project_id,
+            "pipeline": str(self.pipeline_path),
+            "steps": {s.id: s.status.value for s in self.steps},
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+        }
+        # Write atomically
+        tmp = self.state_file.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(state, indent=2))
+        tmp.rename(self.state_file)
+
+    # ── Execution ────────────────────────────────────────────────────────
+
+    def run(self) -> None:
+        """Execute the entire pipeline, pausing at review gates."""
+        # Restore state if resuming
+        saved_state = self._load_state()
+        if saved_state:
+            self._apply_saved_state(saved_state)
+
+        console = _get_console()
+
+        console.print(f"[bold]Pipeline:[/] {self.pipeline_path}")
+        console.print(f"[bold]Project:[/]  {self.project_id}")
+        console.print(f"[bold]Steps:[/]    {len(self.steps)}")
+        console.print()
+
+        for step in self.steps:
+            # Skip already completed steps
+            if step.status == StepStatus.COMPLETE:
+                console.print(f"  [dim]• {step.id}[/] [green](already complete)[/]")
+                continue
+            if step.status == StepStatus.SKIPPED:
+                console.print(f"  [dim]• {step.id}[/] [yellow](skipped)[/]")
+                continue
+
+            # Check dependencies
+            if not self._dependencies_met(step):
+                console.print(f"  [red]✗ {step.id}[/] dependencies not met — blocking")
+                step.status = StepStatus.BLOCKED
+                self._save_state()
+                return
+
+            # Execute
+            if step.kind == StepKind.GATE:
+                self._execute_gate(step)
+            else:
+                self._execute_step(step)
+
+            self._save_state()
+
+        console.print()
+        console.print("[green]✓[/] Pipeline complete!")
+
+    def _apply_saved_state(self, saved: dict[str, StepStatus]) -> None:
+        """Apply previously saved state to steps for resume."""
+        for step in self.steps:
+            if step.id in saved:
+                if saved[step.id] in (StepStatus.COMPLETE, StepStatus.SKIPPED):
+                    step.status = saved[step.id]
+                # PENDING/FAILED steps get re-executed
+
+    def _dependencies_met(self, step: PipelineStep) -> bool:
+        """Check if all dependency steps completed successfully."""
+        for dep_id in step.depends_on:
+            dep = self._step_map.get(dep_id)
+            if dep and dep.status != StepStatus.COMPLETE:
+                return False
+        return True
+
+    # ── Step Executors ───────────────────────────────────────────────────
+
+    def _execute_step(self, step: PipelineStep) -> None:
+        """Execute a non-gate step (HOARD, Libby, Dibble, Export, Command)."""
+        console = _get_console()
+        step.status = StepStatus.RUNNING
+        self._save_state()
+
+        console.print(f"  [blue]→[/] Running step: [bold]{step.id}[/]")
+
+        try:
+            if step.kind == StepKind.HOARD:
+                self._run_hoard(step)
+            elif step.kind == StepKind.LIBBY:
+                self._run_libby(step)
+            elif step.kind == StepKind.DIBBLE:
+                self._run_dibble(step)
+            elif step.kind == StepKind.EXPORT:
+                self._run_export(step)
+            elif step.kind == StepKind.COMMAND:
+                self._run_command(step)
+            else:
+                console.print(f"  [yellow]⚠[/] Unknown step kind: {step.kind} — skipping")
+                step.status = StepStatus.SKIPPED
+
+            if step.status != StepStatus.SKIPPED:
+                step.status = StepStatus.COMPLETE
+                console.print(f"  [green]✓[/] {step.id} complete")
+
+        except Exception as e:
+            step.status = StepStatus.FAILED
+            step.error = str(e)
+            console.print(f"  [red]✗[/] {step.id} failed: {e}")
+            self._save_state()
+            raise
+
+    def _run_hoard(self, step: PipelineStep) -> None:
+        """Execute HOARD pipeline phases."""
+        args = step.tool_args
+        phases = args.get("phases", [])
+        extractor = args.get("extractor", "glm-ocr")
+        strict = args.get("strict", False)
+
+        import shutil
+        hoard_bin = shutil.which("hoard")
+
+        if hoard_bin:
+            cmd = [hoard_bin, "run", "--project", self.project_id, "--workspace", str(self.workspace)]
+            if phases:
+                # Run each phase sequentially
+                for phase in phases:
+                    phase_cmd = cmd + ["--phase", str(phase)]
+                    if extractor:
+                        phase_cmd.extend(["--extractor", extractor])
+                    if strict:
+                        phase_cmd.append("--strict")
+                    _run_subprocess(phase_cmd, step.id)
+            else:
+                # Run specified from_phase or full pipeline
+                from_phase = args.get("from_phase")
+                if from_phase is not None:
+                    cmd.extend(["--from-phase", str(from_phase)])
+                if extractor:
+                    cmd.extend(["--extractor", extractor])
+                if strict:
+                    cmd.append("--strict")
+                _run_subprocess(cmd, step.id)
+        else:
+            # Fallback: Python import
+            from hoard.config import Config
+            from hoard.cli.run import run_single_phase
+
+            cfg = Config(
+                project_id=self.project_id,
+                project_name=self.project_id,
+                jurisdiction="historic_england_cl3",
+                workspace_root=self.workspace.resolve(),
+                input_dir=(self.workspace / self.project_id / "input").resolve(),
+                strict=strict,
+                extractor=extractor,
+            )
+            if phases:
+                for phase in phases:
+                    run_single_phase(cfg, phase)
+            else:
+                from hoard.cli.run import run_pipeline
+                run_pipeline(cfg)
+
+    def _run_libby(self, step: PipelineStep) -> None:
+        """Execute Libby radiocarbon calibration."""
+        args = step.tool_args
+        input_path = args.get("input", "") or str(self.workspace / self.project_id / "01_digitised" / "samples.json")
+        output_dir = str(self.workspace / self.project_id / "03_draft")
+
+        import shutil
+        libby_bin = shutil.which("libby")
+        if libby_bin:
+            _run_subprocess([
+                libby_bin, "calibrate",
+                "--input", input_path,
+                "--output", output_dir,
+            ], step.id)
+        else:
+            raise RuntimeError(
+                "Libby not installed. Install with: pip install libby\n"
+                f"  Or manually calibrate: {input_path}"
+            )
+
+    def _run_dibble(self, step: PipelineStep) -> None:
+        """Execute Dibble lithic analysis."""
+        args = step.tool_args
+        input_dir = args.get("input", "./scans")
+        output_dir = args.get("output", "") or str(self.workspace / self.project_id / "02_spatial" / "lithics")
+
+        import shutil
+        dibble_bin = shutil.which("dibble")
+        if dibble_bin:
+            _run_subprocess([
+                dibble_bin, "process",
+                "--input", input_dir,
+                "--output", output_dir,
+            ], step.id)
+        else:
+            raise RuntimeError(
+                "Dibble not installed. Install with: pip install dibble\n"
+                "  Or skip lithic analysis by removing the step."
+            )
+
+    def _run_export(self, step: PipelineStep) -> None:
+        """Execute HOARD Phase 5 export."""
+        args = step.tool_args
+        formats = args.get("formats", ["docx", "pdf"])
+
+        try:
+            from hoard.config import load_config
+            cfg = load_config(self.project_id, self.workspace)
+            if cfg is None:
+                raise RuntimeError(f"Project '{self.project_id}' not initialised")
+            from hoard.phases.phase5 import run_phase5
+            result = run_phase5(cfg, formats=formats)
+            export_paths = result.get("export_paths", {})
+            if export_paths:
+                console = _get_console()
+                for name, path in export_paths.items():
+                    console.print(f"    • {name}: {path}")
+        except ImportError:
+            raise RuntimeError("HOARD not installed. Run: pip install hoard")
+
+    def _run_command(self, step: PipelineStep) -> None:
+        """Execute an arbitrary shell command."""
+        cmd_str = step.tool_args.get("command", "")
+        if not cmd_str:
+            raise ValueError(f"Step '{step.id}' of kind 'command' has no 'command' field")
+        import shlex
+        cmd_parts = shlex.split(cmd_str)
+        # Substitute {project_id} and {workspace}
+        cmd_parts = [
+            p.replace("{project_id}", self.project_id).replace("{workspace}", str(self.workspace))
+            for p in cmd_parts
+        ]
+        _run_subprocess(cmd_parts, step.id)
+
+    # ── Review Gates ─────────────────────────────────────────────────────
+
+    def _execute_gate(self, step: PipelineStep) -> None:
+        """Pause execution for human review."""
+        console = _get_console()
+
+        console.print()
+        console.print("=" * 60)
+        console.print(f"[bold yellow]🔍 REVIEW GATE: {step.id}[/]")
+        if step.message:
+            console.print(f"  {step.message}")
+        if step.action:
+            console.print(f"  [dim]Suggested action:[/] {step.action}")
+        console.print("=" * 60)
+
+        if self.auto:
+            console.print("  [yellow](auto mode — proceeding)[/]")
+            step.status = StepStatus.COMPLETE
+            return
+
+        while True:
+            try:
+                response = input("  Continue? [Y]es / [s]kip / [q]uit: ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                console.print("[red]✗ Pipeline interrupted[/]")
+                step.status = StepStatus.PENDING
+                self._save_state()
+                sys.exit(1)
+
+            if response in ("", "y", "yes"):
+                step.status = StepStatus.COMPLETE
+                console.print("  [green]✓[/] Proceeding...")
+                break
+            elif response in ("s", "skip"):
+                step.status = StepStatus.SKIPPED
+                console.print("  [yellow]→[/] Gate skipped")
+                break
+            elif response in ("q", "quit"):
+                console.print("  [red]✗ Pipeline paused — resume with 'heritage run --pipeline ...'[/]")
+                step.status = StepStatus.PENDING
+                self._save_state()
+                sys.exit(0)
+
+    # ── Reporting ────────────────────────────────────────────────────────
+
+    def status_report(self) -> str:
+        """Generate a human-readable status report."""
+        lines = [
+            f"Pipeline: {self.pipeline_path}",
+            f"Project:  {self.project_id}",
+            f"State:    {self.state_file}",
+            "",
+            "Steps:",
+        ]
+        for step in self.steps:
+            icon = {"pending": "○", "running": "→", "complete": "✓", "skipped": "−", "failed": "✗", "blocked": "⊘"}
+            marker = icon.get(step.status.value, "?")
+            lines.append(f"  {marker} {step.id}: {step.status.value}")
+            if step.error:
+                lines.append(f"       error: {step.error}")
+        return "\n".join(lines)
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+
+def _run_subprocess(cmd: list[str], step_id: str) -> None:
+    """Run a subprocess with passthrough stdout/stderr."""
+    console = _get_console()
+    console.print(f"    $ {' '.join(cmd)}")
+    result = subprocess.run(cmd)
+    if result.returncode != 0:
+        raise RuntimeError(f"Step '{step_id}' exited with code {result.returncode}")
+
+
+def _get_console():
+    """Get or create a Rich Console instance."""
+    from rich.console import Console
+    return Console()

heritage_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: heritage-cli
+Version: 1.0.0
+Summary: Unified CLI for the heritage science open-source ecosystem — orchestrates HOARD, StratiGraph, Trowel, Libby, Dibble, and other tools
+Author: Marcus Quinn
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: platformdirs>=4
+Requires-Dist: tomli>=2; python_version < "3.11"

heritage_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+heritage_cli/__init__.py,sha256=hqEfPIisES2devRHemr6MAZg-anABvhD3V6ZBCqHL_M,758
+heritage_cli/main.py,sha256=vnu2VCWnnreB0V_Vg2eeKBtpXyzPOHv3rqt8_ceLrA8,16000
+heritage_cli/orchestrator.py,sha256=Ru9uZrXqRglgtNgyV5FqwKHKhsLxcwbgo5q1O-_6ToY,19895
+heritage_cli/commands/__init__.py,sha256=IIsQBPZxOllXFD85bsItdor-R2RUVLBEis3IzN-zJQM,215
+heritage_cli/commands/hoard.py,sha256=rFSEZSeVQfMTN0BzmWrd_472guwxeADJnKgr6oJRubA,496
+heritage_cli-1.0.0.dist-info/METADATA,sha256=aFeU_SCjG5FSrM4vxcD3vafyJ0wuPYAN45i_QEnsrmc,389
+heritage_cli-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+heritage_cli-1.0.0.dist-info/entry_points.txt,sha256=xfD1N_Huyz7HJbdwhoF6470KEEwexyLvziF5QWJspTM,265
+heritage_cli-1.0.0.dist-info/top_level.txt,sha256=HDowMMpJEJf_zdm0IvpxhYOwS9WDw12BUs0lX8D53lA,13
+heritage_cli-1.0.0.dist-info/RECORD,,

heritage_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

heritage_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,9 @@
+[console_scripts]
+heritage = heritage_cli.main:app
+
+[heritage.tools]
+dibble = heritage_cli.commands.dibble
+hoard = heritage_cli.commands.hoard
+libby = heritage_cli.commands.libby
+stratigraph = heritage_cli.commands.stratigraph
+trowel = heritage_cli.commands.trowel

heritage_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+heritage_cli