heritage-cli 1.0.1__tar.gz → 1.0.3__tar.gz

heritage_cli-1.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Bouck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heritage_cli-1.0.3/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: heritage-cli
+Version: 1.0.3
+Summary: Unified CLI for the heritage science open-source ecosystem — orchestrates HOARD, StratiGraph, Trowel, Libby, Dibble, and other tools
+Author-email: Mark Bouck <markbouck@duck.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dig-tools/heritage-cli
+Project-URL: Documentation, https://github.com/dig-tools/heritage-cli#readme
+Project-URL: Issues, https://github.com/dig-tools/heritage-cli/issues
+Project-URL: Repository, https://github.com/dig-tools/heritage-cli.git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: hoard
+Requires-Dist: hoard; extra == "hoard"
+Provides-Extra: libby
+Requires-Dist: libby; extra == "libby"
+Provides-Extra: dibble
+Requires-Dist: dibble; extra == "dibble"
+Provides-Extra: trowel
+Requires-Dist: trowel; extra == "trowel"
+Provides-Extra: stratigraph
+Requires-Dist: stratigraph; extra == "stratigraph"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/brand/project-lockup.svg" alt="Dig:Tools" width="720">
+</p>
+
+# heritage-cli
+
+> One command-line front door for repeatable Dig:Tools heritage workflows.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](#licence)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python)](pyproject.toml)
+[![GitHub](https://img.shields.io/badge/GitHub-dig--tools%2Fheritage--cli-181717?logo=github)](https://github.com/dig-tools/heritage-cli)
+
+`heritage-cli` orchestrates existing applications; it does not reimplement their
+analysis. It can run HOARD phases, invoke compatible radiocarbon, lithics,
+matrix, review, and publishing commands, and execute declarative YAML pipelines
+with resumable state and explicit human-review gates.
+
+## Install
+
+```bash
+python -m pip install heritage-cli
+heritage --version
+heritage --help
+```
+
+Install the tools used by your workflow separately. Compatibility extras are
+available for the historical command packages:
+
+```bash
+python -m pip install "heritage-cli[hoard,libby,stratigraph,dibble,trowel]"
+```
+
+## Common commands
+
+```bash
+# Inspect discoverable tools
+heritage tools
+
+# Discover open archaeological data with provenance retained
+heritage open-context "amphora" --details
+heritage open-context "amphora" --details --json > comparanda.json
+
+# Run a single HOARD phase or the full pipeline
+heritage run --project my_site --phase 0
+heritage run --project my_site --auto
+
+# Run a declarative multi-tool workflow
+heritage run --project my_site \
+  --pipeline pipeline.example.yaml \
+  --workspace ./erd_workspace
+
+# Specialist hand-offs
+heritage calibrate --project my_site
+heritage lithics --project my_site --input ./scans
+heritage review --project my_site
+heritage matrix --project my_site
+heritage publish --project my_site --format docx,pdf
+```
+
+Run `heritage COMMAND --help` before scripting a command; the installed version’s
+help is authoritative.
+
+### Open Context discovery
+
+`heritage open-context` is a bounded, read-only connector to Open Context's
+public JSON-LD API. It does not mirror data or automatically paginate. Geometry
+is omitted by default; add `--include-geometry` only when published coordinates
+are necessary and ethically appropriate. `--details` retrieves each record's
+exact Creative Commons licence, creators, project, and persistent identifier at
+a service-friendly rate below three requests per second.
+
+Open Context's terms, record-level licences, contributor attribution, and
+archaeological ethics continue to apply to downloaded results. Human-remains-
+related records are flagged and produce an ethical-use notice.
+
+## Pipelines and state
+
+Pipeline YAML describes ordered application steps and review gates. Progress is
+stored beneath the selected workspace, allowing an interrupted run to resume
+without silently repeating completed work. [`pipeline.example.yaml`](pipeline.example.yaml)
+is a minimal working template.
+
+Human gates are intentional. `--auto` may skip them in pipeline mode and should
+only be used when the inputs and outputs are independently reviewed elsewhere.
+
+## Dig:Tools relationships
+
+| Repository | Role |
+|---|---|
+| [Dig:Codex](https://github.com/dig-tools/codex) | Report generation and research/archive tools |
+| [Dig:Stratum](https://github.com/dig-tools/stratum) | Field recording and Harris Matrices |
+| [Dig:Crucible](https://github.com/dig-tools/crucible) | Lithics, dating, and laboratory analysis |
+| [Dig:Folio](https://github.com/dig-tools/folio) | Collections management and vocabulary generation |
+| [heritage-types](https://github.com/dig-tools/heritage-types) | Canonical cross-tool schemas |
+
+Some command adapters retain historical executable names (`hoard`, `libby`,
+`dibble`, `trowel`, `stratigraph`) for compatibility after consolidation.
+
+## Development
+
+```bash
+git clone https://github.com/dig-tools/heritage-cli.git
+cd heritage-cli
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest tests -m "not integration"
+mypy src
+```
+
+See [USER_GUIDE.md](USER_GUIDE.md) for pipeline setup, review gates, state, and
+troubleshooting.
+
+## Licence
+
+MIT.

heritage_cli-1.0.3/README.md

@@ -0,0 +1,116 @@
+<p align="center">
+  <img src="docs/brand/project-lockup.svg" alt="Dig:Tools" width="720">
+</p>
+
+# heritage-cli
+
+> One command-line front door for repeatable Dig:Tools heritage workflows.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](#licence)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python)](pyproject.toml)
+[![GitHub](https://img.shields.io/badge/GitHub-dig--tools%2Fheritage--cli-181717?logo=github)](https://github.com/dig-tools/heritage-cli)
+
+`heritage-cli` orchestrates existing applications; it does not reimplement their
+analysis. It can run HOARD phases, invoke compatible radiocarbon, lithics,
+matrix, review, and publishing commands, and execute declarative YAML pipelines
+with resumable state and explicit human-review gates.
+
+## Install
+
+```bash
+python -m pip install heritage-cli
+heritage --version
+heritage --help
+```
+
+Install the tools used by your workflow separately. Compatibility extras are
+available for the historical command packages:
+
+```bash
+python -m pip install "heritage-cli[hoard,libby,stratigraph,dibble,trowel]"
+```
+
+## Common commands
+
+```bash
+# Inspect discoverable tools
+heritage tools
+
+# Discover open archaeological data with provenance retained
+heritage open-context "amphora" --details
+heritage open-context "amphora" --details --json > comparanda.json
+
+# Run a single HOARD phase or the full pipeline
+heritage run --project my_site --phase 0
+heritage run --project my_site --auto
+
+# Run a declarative multi-tool workflow
+heritage run --project my_site \
+  --pipeline pipeline.example.yaml \
+  --workspace ./erd_workspace
+
+# Specialist hand-offs
+heritage calibrate --project my_site
+heritage lithics --project my_site --input ./scans
+heritage review --project my_site
+heritage matrix --project my_site
+heritage publish --project my_site --format docx,pdf
+```
+
+Run `heritage COMMAND --help` before scripting a command; the installed version’s
+help is authoritative.
+
+### Open Context discovery
+
+`heritage open-context` is a bounded, read-only connector to Open Context's
+public JSON-LD API. It does not mirror data or automatically paginate. Geometry
+is omitted by default; add `--include-geometry` only when published coordinates
+are necessary and ethically appropriate. `--details` retrieves each record's
+exact Creative Commons licence, creators, project, and persistent identifier at
+a service-friendly rate below three requests per second.
+
+Open Context's terms, record-level licences, contributor attribution, and
+archaeological ethics continue to apply to downloaded results. Human-remains-
+related records are flagged and produce an ethical-use notice.
+
+## Pipelines and state
+
+Pipeline YAML describes ordered application steps and review gates. Progress is
+stored beneath the selected workspace, allowing an interrupted run to resume
+without silently repeating completed work. [`pipeline.example.yaml`](pipeline.example.yaml)
+is a minimal working template.
+
+Human gates are intentional. `--auto` may skip them in pipeline mode and should
+only be used when the inputs and outputs are independently reviewed elsewhere.
+
+## Dig:Tools relationships
+
+| Repository | Role |
+|---|---|
+| [Dig:Codex](https://github.com/dig-tools/codex) | Report generation and research/archive tools |
+| [Dig:Stratum](https://github.com/dig-tools/stratum) | Field recording and Harris Matrices |
+| [Dig:Crucible](https://github.com/dig-tools/crucible) | Lithics, dating, and laboratory analysis |
+| [Dig:Folio](https://github.com/dig-tools/folio) | Collections management and vocabulary generation |
+| [heritage-types](https://github.com/dig-tools/heritage-types) | Canonical cross-tool schemas |
+
+Some command adapters retain historical executable names (`hoard`, `libby`,
+`dibble`, `trowel`, `stratigraph`) for compatibility after consolidation.
+
+## Development
+
+```bash
+git clone https://github.com/dig-tools/heritage-cli.git
+cd heritage-cli
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest tests -m "not integration"
+mypy src
+```
+
+See [USER_GUIDE.md](USER_GUIDE.md) for pipeline setup, review gates, state, and
+troubleshooting.
+
+## Licence
+
+MIT.

{heritage_cli-1.0.1 → heritage_cli-1.0.3}/pyproject.toml

@@ -4,12 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "heritage-cli"
-version = "1.0.1"
+version = "1.0.3"
 description = "Unified CLI for the heritage science open-source ecosystem — orchestrates HOARD, StratiGraph, Trowel, Libby, Dibble, and other tools"
 requires-python = ">=3.11"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
 authors = [
-    { name = "Mark Bouck" },
+    { name = "Mark Bouck", email = "markbouck@duck.com" },
 ]
 dependencies = [
     "typer>=0.12",
@@ -17,7 +19,19 @@ dependencies = [
     "pyyaml>=6",
 ]
 
+[project.urls]
+Homepage = "https://github.com/dig-tools/heritage-cli"
+Documentation = "https://github.com/dig-tools/heritage-cli#readme"
+Issues = "https://github.com/dig-tools/heritage-cli/issues"
+Repository = "https://github.com/dig-tools/heritage-cli.git"
+
 [project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "mypy>=1.10",
+    "pytest>=8",
+    "ruff>=0.4",
+]
 hoard = ["hoard"]
 libby = ["libby"]
 dibble = ["dibble"]
@@ -42,3 +56,11 @@ python_version = "3.11"
 warn_return_any = true
 warn_unused_configs = true
 ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: tests that require sibling ecosystem packages to be installed",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/test_smoke.py" = ["F401"]  # Importability is the assertion in this smoke test.

{heritage_cli-1.0.1 → heritage_cli-1.0.3}/src/heritage_cli/__init__.py

@@ -23,4 +23,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("heritage-cli")
 except PackageNotFoundError:
-    __version__ = "1.0.0"
+    __version__ = "1.0.3"

{heritage_cli-1.0.1 → heritage_cli-1.0.3}/src/heritage_cli/main.py

@@ -18,12 +18,14 @@ Usage:
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Annotated, Optional
 
 import typer
 from rich.console import Console
 from rich.table import Table
 
 from heritage_cli import __version__
+from heritage_cli.vocab_generator import generate as _generate_vocab
 
 app = typer.Typer(
     name="heritage",
@@ -459,6 +461,107 @@ def pipeline_status(
         raise typer.Exit(1)
 
 
+# ── Code generation sub-commands ─────────────────────────────────────────────
+
+
+@app.command(name="open-context")
+def open_context(
+    query: Annotated[str, typer.Argument(help="Text to search for")],
+    limit: int = typer.Option(
+        10, "--limit", "-n", min=1, max=20, help="Results (1–20)"
+    ),
+    start: int = typer.Option(
+        0, "--start", min=0, help="Result offset; no automatic paging"
+    ),
+    details: bool = typer.Option(
+        False, "--details", help="Fetch exact licence and creator metadata"
+    ),
+    include_geometry: bool = typer.Option(
+        False,
+        "--include-geometry",
+        help="Include published coordinates in JSON output (off by default)",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit reproducible JSON instead of a table"
+    ),
+) -> None:
+    """Search Open Context's public archaeological-data catalogue.
+
+    Results retain source and citation URIs. Geometry is deliberately omitted
+    unless explicitly requested. Open Context's terms and each record's licence
+    continue to apply.
+    """
+    import json
+
+    from heritage_cli.open_context import OpenContextClient, OpenContextError
+
+    try:
+        result = OpenContextClient().search(
+            query,
+            rows=limit,
+            start=start,
+            details=details,
+            include_geometry=include_geometry,
+        )
+    except (OpenContextError, ValueError) as exc:
+        console.print(f"[red]✗[/] {exc}")
+        raise typer.Exit(1) from exc
+
+    if json_output:
+        typer.echo(json.dumps(result.to_dict(), indent=2, ensure_ascii=False))
+    else:
+        table = Table(title=f"Open Context — {result.total_results:,} matches")
+        table.add_column("Record", style="cyan", overflow="fold")
+        table.add_column("Category")
+        table.add_column("Project", overflow="fold")
+        table.add_column("Licence / citation", overflow="fold")
+        for record in result.records:
+            attribution = record.license_label or "Run with --details for exact licence"
+            citation = record.citation_uri or record.uri
+            if record.human_remains_related:
+                attribution = f"⚠ human-remains-related\n{attribution}"
+            table.add_row(
+                f"{record.label}\n{record.uri}",
+                record.item_category,
+                record.project_label,
+                f"{attribution}\n{citation}",
+            )
+        console.print(table)
+        console.print(f"[dim]Source: {result.source}[/]")
+
+    if any(record.human_remains_related for record in result.records):
+        console.print(
+            "[yellow]Ethical-use notice:[/] One or more records relate to human remains. "
+            "Follow Open Context's terms, relevant community protocols, and professional ethics."
+        )
+
+
+# ── Code generation sub-commands ─────────────────────────────────────────────
+
+
+@app.command(name="generate-vocab")
+def generate_vocab(
+    input_file: Annotated[Path, typer.Argument(help="Vocabulary JSON file")] = Path(
+        "vocabulary.json"
+    ),
+    ts_output: Annotated[
+        Optional[Path], typer.Option("--ts", help="TypeScript output path")
+    ] = None,
+    rust_output: Annotated[
+        Optional[Path], typer.Option("--rust", help="Rust output path")
+    ] = None,
+) -> None:
+    """Generate TypeScript and/or Rust source from a vocabulary JSON file."""
+    try:
+        _generate_vocab(input_file, ts_output, rust_output)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else 1
+        raise typer.Exit(code=code or 1)
+    except Exception as exc:
+        console.print(f"[red]✗[/] {exc}")
+        raise typer.Exit(1)
+
+
 # ── Tools sub-command ────────────────────────────────────────────────────────