bookwright-cli 0.2.0__py3-none-any.whl

bookwright/__init__.py

@@ -0,0 +1,3 @@
+"""Bookwright — Spec-driven authoring toolkit."""
+
+__version__ = "0.2.0"

bookwright/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m bookwright` to invoke the CLI."""
+
+from bookwright.cli import app
+
+if __name__ == "__main__":
+    app()

bookwright/cli.py

@@ -0,0 +1,19 @@
+"""Bookwright CLI entry point."""
+
+import typer
+
+from bookwright.commands import check, graph, init, integration, validate, version
+
+app = typer.Typer(
+    name="bookwright",
+    help="Bookwright — Spec-driven authoring toolkit.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.command("version")(version.run)
+app.command("check")(check.run)
+app.command("init", context_settings=init.CONTEXT_SETTINGS)(init.run)
+app.command("validate")(validate.run)
+app.add_typer(graph.app, name="graph")
+app.add_typer(integration.app, name="integration")

bookwright/commands/_envelope.py

@@ -0,0 +1,36 @@
+"""Shared command-layer envelope helper (review R1).
+
+Several agent-facing commands catch a ``ManifestError`` at their ``--json``
+boundary and remap it to the contract's single ``invalid_manifest`` code. Rather
+than re-build the ``{status,code,message}`` skeleton by hand in each command
+module, the remap routes through the base ``BookwrightError.to_json`` — the one
+place the envelope skeleton lives — exactly as ``commands.validate._UsageError``
+already does for the same case.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bookwright.errors import BookwrightError
+
+#: The contract code every caught ``ManifestError`` collapses to at a ``--json``
+#: boundary. Single-sourced here so the two remap sites — this module and
+#: ``commands.validate._UsageError`` — cannot drift to different literals.
+INVALID_MANIFEST_CODE = "invalid_manifest"
+
+
+class _InvalidManifestError(BookwrightError):
+    """A caught ``ManifestError`` re-coded to the contract's ``invalid_manifest``.
+
+    Mirrors ``commands.validate._UsageError(INVALID_MANIFEST_CODE, ...)``: the
+    remap is expressed as a ``BookwrightError`` whose canonical ``to_json()``
+    builds the envelope, never a hand-rolled dict.
+    """
+
+    code = INVALID_MANIFEST_CODE
+
+
+def invalid_manifest_payload(exc: Exception) -> dict[str, Any]:
+    """The ``invalid_manifest`` error envelope for a caught ``ManifestError``."""
+    return _InvalidManifestError(str(exc)).to_json()

bookwright/commands/check.py

@@ -0,0 +1,75 @@
+"""`bookwright check` — verify the running interpreter and runtime dependencies."""
+
+import importlib
+import json
+import sys
+from typing import TypedDict
+
+import typer
+from rich.console import Console
+
+RUNTIME_MODULES: tuple[str, ...] = (
+    "typer",
+    "rich",
+    "rdflib",
+    "pydantic",
+    "tomlkit",
+    "jinja2",
+    "slugify",
+    "platformdirs",
+    "uuid_utils",
+    "yaml",
+    "packaging",
+)
+
+
+class CheckResult(TypedDict, total=False):
+    name: str
+    status: str
+    detail: str
+
+
+def _python_version_check() -> CheckResult:
+    found = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    if sys.version_info >= (3, 11):  # noqa: UP036
+        return {"name": "python_version", "status": "ok", "detail": found}
+    return {
+        "name": "python_version",
+        "status": "fail",
+        "detail": f"found {found}, requires >=3.11",
+    }
+
+
+def _dependency_check(module_name: str) -> CheckResult:
+    try:
+        importlib.import_module(module_name)
+    except ImportError as exc:
+        return {
+            "name": f"dependency:{module_name}",
+            "status": "fail",
+            "detail": str(exc),
+        }
+    return {"name": f"dependency:{module_name}", "status": "ok"}
+
+
+def run(
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit a single JSON document on stdout."
+    ),
+) -> None:
+    """Verify Python version (>=3.11) and that all declared deps are importable."""
+    checks: list[CheckResult] = [_python_version_check()]
+    for module_name in RUNTIME_MODULES:
+        checks.append(_dependency_check(module_name))
+    ok = all(c["status"] == "ok" for c in checks)
+    payload = {"ok": ok, "checks": checks}
+    if json_output:
+        sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+    else:
+        console = Console()
+        for check in checks:
+            tag = "OK  " if check["status"] == "ok" else "FAIL"
+            detail = check.get("detail", "")
+            suffix = f" — {detail}" if detail else ""
+            console.print(f"{tag}  {check['name']}{suffix}")
+    raise typer.Exit(code=0 if ok else 1)

bookwright/commands/graph/__init__.py

@@ -0,0 +1,23 @@
+"""The ``bookwright graph`` Typer sub-app.
+
+``build`` and ``query`` live in their own modules (Principle IV) and register
+their callbacks here. The app is wired into the root CLI in
+:mod:`bookwright.cli` via ``app.add_typer(graph.app, name="graph")``.
+"""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    name="graph",
+    help="Build and query the project's GOLEM graph.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# `build` and `query` register their callbacks on `app` at import
+# time; importing them here keeps the sub-app self-contained. The `as` redirect
+# marks the imports as intentional re-exports (registration side effect).
+from . import build as build  # noqa: E402
+from . import query as query  # noqa: E402

bookwright/commands/graph/build.py

@@ -0,0 +1,157 @@
+"""`bookwright graph build` — read the bible, build the graph, write Turtle.
+
+Locates the project, resolves the manifest-selected engine, maps every
+recognised bible file to GOLEM entities (with CIDOC provenance), and serializes
+to ``bible/graph.ttl``. Fault model (R7, cli-graph.md): missing project /
+directory / unknown engine → exit 2; slug collision → exit 3 (no graph); ≥ 1
+skipped file → exit 4 (graph still written); clean build → exit 0.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from bookwright.core.errors import ManifestError
+from bookwright.core.manifest import Manifest
+from bookwright.golem.namespaces import timeline_uri
+from bookwright.indexers import UnknownIndexerError, resolve_indexer
+from bookwright.io.bible import build_provenance, map_bible
+from bookwright.io.errors import (
+    MissingDirectoryError,
+    ProjectNotFoundError,
+    ResearchError,
+    SlugCollisionError,
+)
+from bookwright.io.manuscript import manuscript_present
+from bookwright.io.project import find_project_root
+from bookwright.io.report import BuildReport, ResearchTargetWarning
+from bookwright.io.research import map_research
+
+from .._envelope import invalid_manifest_payload
+from . import app
+from .envelope import emit_error, emit_json
+
+EXIT_CONFIG = 2
+EXIT_COLLISION = 3
+
+
+@app.command("build")
+def run(
+    force: bool = typer.Option(
+        False, "--force", help="Rebuild from scratch, ignoring any cache (v0: no-op)."
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit the build report as one JSON document on stdout."
+    ),
+) -> None:
+    """Build the project graph from the bible and write ``bible/graph.ttl``."""
+    console = Console(stderr=True)
+    try:
+        report = _build()
+    except ManifestError as exc:
+        emit_error(invalid_manifest_payload(exc), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except (
+        ProjectNotFoundError,
+        MissingDirectoryError,
+        UnknownIndexerError,
+        ResearchError,
+    ) as exc:
+        emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except SlugCollisionError as exc:
+        emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_COLLISION) from exc
+
+    if json_output:
+        emit_json(report.to_json())
+    else:
+        _print_summary(console, report)
+    raise typer.Exit(report.exit_code)
+
+
+def _build() -> BuildReport:
+    """Run the build, returning the report. Raises the fault-model exceptions."""
+    project_root = find_project_root()
+    manifest = Manifest.load(project_root / "manifest.toml")
+
+    bible_dir = project_root / manifest.paths.bible
+    manuscript_dir = project_root / manifest.paths.manuscript
+    if not bible_dir.is_dir():
+        raise MissingDirectoryError("bible", str(bible_dir))
+    if not manuscript_present(manuscript_dir):
+        raise MissingDirectoryError("manuscript", str(manuscript_dir))
+
+    engine_cls = resolve_indexer(manifest.bookwright.indexer)
+    engine = engine_cls()
+
+    uri_base = manifest.bookwright.uri_base
+    result = map_bible(project_root, bible_dir, uri_base)
+
+    for mapped in result.mapped:
+        for triple in mapped.entity.to_triples():
+            engine.add_triple(*triple)
+        for assignment in build_provenance(mapped, uri_base):
+            for triple in assignment.to_triples():
+                engine.add_triple(*triple)
+
+    # Research pass: map bible/research/ and feed its triples into the same engine
+    # (one graph, one save — research D8). Research entities are already E13
+    # reifications, so they are NOT routed through build_provenance.
+    research = map_research(
+        project_root,
+        bible_dir / "research",
+        uri_base,
+        manifest.book.language,
+        result.entity_index,
+        timeline_uri(uri_base),
+    )
+    for entity in research.entities:
+        for triple in entity.to_triples():
+            engine.add_triple(*triple)
+
+    graph_rel = manifest.paths.graph
+    engine.save(project_root / graph_rel)
+
+    return BuildReport(
+        files_processed=result.files_processed + research.files_processed,
+        entities=len(result.entities) + len(research.entities),
+        triples=engine.count(),
+        graph_path=graph_rel,
+        skipped=tuple(result.skipped),
+        unknown_keys=tuple(result.unknown_keys),
+        unresolved_participants=tuple(result.unresolved_participants),
+        sources=len(research.sources),
+        findings=len(research.findings),
+        anchors=len(research.anchors),
+        research_warnings=tuple(
+            ResearchTargetWarning(path=w.relpath, field=w.field, name=w.name)
+            for w in research.warnings
+        ),
+    )
+
+
+def _print_summary(console: Console, report: BuildReport) -> None:
+    """Write the human build summary to stderr (one line per metric)."""
+    console.print(
+        f"processed {report.files_processed} files, "
+        f"{report.entities} entities, {report.triples} triples → {report.graph_path}"
+    )
+    if report.skipped:
+        console.print(f"skipped {len(report.skipped)} file(s):")
+        for item in report.skipped:
+            console.print(f"  - {item.path}: {item.reason}")
+    if report.unknown_keys:
+        console.print(f"{len(report.unknown_keys)} unknown frontmatter key(s) ignored")
+    if report.unresolved_participants:
+        console.print(f"{len(report.unresolved_participants)} unresolved participant reference(s)")
+    if report.sources or report.findings or report.anchors:
+        console.print(
+            f"research: {report.sources} source(s), "
+            f"{report.findings} finding(s), {report.anchors} anchor(s)"
+        )
+    if report.research_warnings:
+        console.print(f"{len(report.research_warnings)} unresolved research target(s):")
+        for warning in report.research_warnings:
+            console.print(f"  - {warning.path}: {warning.field} '{warning.name}' not in bible")

bookwright/commands/graph/envelope.py

@@ -0,0 +1,26 @@
+"""JSON success/error envelopes for the ``graph`` sub-commands (Principle IX).
+
+Single-line ``json.dumps(payload, separators=(",", ":")) + "\\n"`` to stdout,
+mirroring the pattern in :mod:`bookwright.commands.version`. Human prose and
+progress go to stderr via a ``Console(stderr=True)`` owned by each command.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def emit_json(payload: dict[str, Any]) -> None:
+    """Write exactly one JSON document to stdout (the only thing on stdout)."""
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+
+
+def emit_error(payload: dict[str, Any], json_output: bool) -> None:
+    """Surface an error envelope: one JSON doc on stdout under ``--json``, else a
+    single ``bookwright: error: <message>`` line on stderr (Principle IX)."""
+    if json_output:
+        emit_json(payload)
+    else:
+        sys.stderr.write(f"bookwright: error: {payload['message']}\n")

bookwright/commands/graph/query.py

@@ -0,0 +1,98 @@
+"""`bookwright graph query` — load ``bible/graph.ttl`` and run a SPARQL query.
+
+Read-only. Renders a ``rich`` table for humans (stdout) or, under ``--json``, a
+single ``{"status":"ok","results":[...],"count":N}`` document (Principle IX).
+Fault model (cli-graph.md): missing project / graph / unknown engine → exit 2;
+malformed SPARQL → exit 3 with no partial rows.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from bookwright.core.errors import ManifestError
+from bookwright.core.manifest import Manifest
+from bookwright.indexers import (
+    GraphLoadError,
+    GraphNotBuiltError,
+    InvalidQueryError,
+    UnknownIndexerError,
+    resolve_indexer,
+)
+from bookwright.io.errors import ProjectNotFoundError
+from bookwright.io.project import find_project_root
+
+from .._envelope import invalid_manifest_payload
+from . import app
+from .envelope import emit_error, emit_json
+
+EXIT_CONFIG = 2
+EXIT_INVALID_QUERY = 3
+
+
+@app.command("query")
+def run(
+    sparql: str = typer.Argument(..., help="The SPARQL query to run against the graph."),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit results as one JSON document on stdout."
+    ),
+) -> None:
+    """Run ``sparql`` against the project graph and print the rows."""
+    try:
+        rows = _query(sparql)
+    except ManifestError as exc:
+        emit_error(invalid_manifest_payload(exc), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except (
+        ProjectNotFoundError,
+        GraphNotBuiltError,
+        GraphLoadError,
+        UnknownIndexerError,
+    ) as exc:
+        emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except InvalidQueryError as exc:
+        emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_INVALID_QUERY) from exc
+
+    if json_output:
+        emit_json({"status": "ok", "results": rows, "count": len(rows)})
+    else:
+        _render_table(rows)
+
+
+def _query(sparql: str) -> list[dict[str, Any]]:
+    """Load the graph and run the query, returning fully materialized rows."""
+    project_root = find_project_root()
+    manifest = Manifest.load(project_root / "manifest.toml")
+
+    engine_cls = resolve_indexer(manifest.bookwright.indexer)
+    engine = engine_cls()
+
+    graph_path = project_root / manifest.paths.graph
+    if not graph_path.is_file():
+        raise GraphNotBuiltError(manifest.paths.graph)
+    engine.load(graph_path)
+
+    return list(engine.query(sparql))
+
+
+def _render_table(rows: list[dict[str, Any]]) -> None:
+    """Render rows as a ``rich`` table on stdout (an empty note when no matches)."""
+    console = Console()
+    if not rows:
+        Console(stderr=True).print("(no results)")
+        return
+    columns: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in columns:
+                columns.append(key)
+    table = Table(*columns)
+    for row in rows:
+        table.add_row(*(row.get(column, "") for column in columns))
+    console.print(table)

bookwright/commands/init/__init__.py

@@ -0,0 +1,5 @@
+"""Public surface for the `bookwright init` subcommand package."""
+
+from .main import CONTEXT_SETTINGS, run
+
+__all__ = ["CONTEXT_SETTINGS", "run"]

bookwright/commands/init/conflict.py

@@ -0,0 +1,107 @@
+"""Pre-scaffold conflict checks and ledger seeding for ``bookwright init``.
+
+Owns FR-026 / FR-027 / FR-028 / FR-029 — the name-collision matrices for
+``named`` and ``here`` modes — plus the tiny ``BackupLedger`` seeder that
+records the project root if ``init`` created it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from . import resolve
+from .envelope import emit_error
+from .scaffold import BackupLedger
+
+
+def apply_named_conflict_matrix(
+    target: Path,
+    force: bool,
+    *,
+    json_output: bool,
+) -> None:
+    """FR-026 / FR-027 / FR-028 — refuse with structured codes when conflicting."""
+
+    if (target / ".bookwright").exists():
+        emit_error(
+            code="already_initialized",
+            message=(
+                f"directory {str(target)!r} is already a Bookwright project (found .bookwright/)"
+            ),
+            details={"target": str(target)},
+            exit_code=3,
+            json_output=json_output,
+            rolled_back=False,
+        )
+    if not target.exists():
+        return
+    if any(target.iterdir()) and not force:
+        emit_error(
+            code="target_not_empty",
+            message=(
+                f"directory {target.name!r} is not empty; "
+                "use --force to overwrite or --here to initialise in place"
+            ),
+            details={"target": str(target)},
+            exit_code=4,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+
+def apply_here_conflict_matrix(
+    target: Path,
+    force: bool,
+    *,
+    json_output: bool,
+) -> None:
+    """FR-028 / FR-029 / interactive prompt for ``--here``."""
+
+    if (target / ".bookwright").exists():
+        emit_error(
+            code="already_initialized",
+            message=(
+                f"directory {str(target)!r} is already a Bookwright project (found .bookwright/)"
+            ),
+            details={"target": str(target)},
+            exit_code=3,
+            json_output=json_output,
+            rolled_back=False,
+        )
+    if not any(target.iterdir()):
+        return
+    if force:
+        return
+    if not resolve.is_interactive() or json_output:
+        emit_error(
+            code="non_interactive_here",
+            message="--here in a non-empty directory requires --force in non-interactive runs",
+            details={"target": str(target), "modern": "--force"},
+            exit_code=4,
+            json_output=json_output,
+            rolled_back=False,
+        )
+    confirmed = typer.confirm(
+        f"bookwright: directory {str(target)!r} is not empty. Overwrite name collisions?",
+        default=False,
+    )
+    if not confirmed:
+        emit_error(
+            code="user_declined_overwrite",
+            message="aborted by user",
+            details={"target": str(target)},
+            exit_code=4,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+
+def seed_backup_ledger(project_root: Path, cleanup_project_root: bool) -> BackupLedger:
+    """Return a ledger; record the project root itself if we created it."""
+
+    ledger = BackupLedger(project_root)
+    if cleanup_project_root:
+        ledger.record_new_directory(project_root)
+    return ledger