bookwright-cli 0.2.0__py3-none-any.whl

bookwright/commands/integration/use.py

@@ -0,0 +1,120 @@
+"""``bookwright integration use <key>`` — switch the project's agent integration.
+
+Re-materializes one ``SKILL.md`` per source command under the chosen integration's
+skills directory (reusing the shared materializer + the plugin registry —
+Principles V/VI/VII), updates the manifest's ``[integration]`` block, and leaves
+any previously-materialized skills directory **untouched** (the swap-residue
+policy: no cleanup in v0). The operation is atomic — a materialization or lint
+failure rolls the whole change back through a ``BackupLedger``.
+
+This is the supported integration-swap mechanism. ``init`` deliberately refuses to
+re-initialize an existing project (the ``.bookwright/`` guard), so switching the
+*integration* of a live book is its own intention-revealing command rather than a
+re-init flag. Principle IX: under ``--json`` exactly one JSON document on stdout;
+all human prose goes to stderr.
+
+Fault model: missing project / unparseable manifest / unknown integration key →
+exit 2; a skill materialization or lint failure → exit 3 (fully rolled back).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import typer
+from rich.console import Console
+
+from bookwright.core.errors import ManifestError
+from bookwright.core.manifest import Manifest
+from bookwright.integrations import UnknownIntegrationError, get
+from bookwright.integrations.errors import SkillLintError, SkillMaterializationError
+from bookwright.io.errors import ProjectNotFoundError
+from bookwright.io.fs import BackupLedger
+from bookwright.io.project import find_project_root
+
+from .._envelope import invalid_manifest_payload
+from . import app
+
+EXIT_CONFIG = 2
+EXIT_MATERIALIZE = 3
+
+
+@app.command("use")
+def run(
+    key: str = typer.Argument(..., help="Integration key to switch to (e.g. 'claude', 'generic')."),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit the result as one JSON document on stdout."
+    ),
+) -> None:
+    """Switch the project to integration ``key`` and re-materialize its skills."""
+    try:
+        payload = _use(key)
+    except ProjectNotFoundError as exc:
+        _emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except ManifestError as exc:
+        _emit_error(invalid_manifest_payload(exc), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except UnknownIntegrationError as exc:
+        _emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except (SkillLintError, SkillMaterializationError) as exc:
+        _emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_MATERIALIZE) from exc
+
+    if json_output:
+        _emit_json(payload)
+    else:
+        Console(stderr=True, highlight=False).print(
+            f"bookwright: switched integration to '{payload['integration']}' "
+            f"({payload['count']} skills → {payload['skills_dir']})"
+        )
+
+
+def _use(key: str) -> dict[str, Any]:
+    """Materialize the new integration, update the manifest, and return the report.
+
+    Resolves the integration *before* any filesystem mutation (an unknown key is a
+    no-op exit-2). All writes — the skills and the manifest overwrite — go through a
+    single ``BackupLedger`` so a failure leaves the project byte-identical.
+    """
+    root = find_project_root()
+    manifest_path = root / "manifest.toml"
+    manifest = Manifest.load(manifest_path)
+
+    integration = get(key)()  # raises UnknownIntegrationError on an unknown key
+    skills_dir = integration.resolve_skills_dir().as_posix()
+
+    ledger = BackupLedger(root)
+    try:
+        integration.setup(root, manifest, ledger=ledger)
+        ledger.record_overwrite(manifest_path)
+        manifest.set_integration(key=key, skills_dir=skills_dir)
+        manifest.dump(manifest_path, overwrite=True)
+    except BaseException:
+        ledger.rollback()
+        raise
+    ledger.commit()
+
+    materialized = sorted(p.parent.name for p in (root / skills_dir).rglob("SKILL.md"))
+    return {
+        "status": "ok",
+        "integration": key,
+        "skills_dir": skills_dir,
+        "materialized": materialized,
+        "count": len(materialized),
+    }
+
+
+def _emit_json(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+
+
+def _emit_error(payload: dict[str, Any], json_output: bool) -> None:
+    if json_output:
+        _emit_json(payload)
+    else:
+        message = payload.get("message", payload.get("code", "error"))
+        sys.stderr.write(f"bookwright: error: {message}\n")

bookwright/commands/validate.py

@@ -0,0 +1,160 @@
+"""``bookwright validate`` — run the active validators and report violations.
+
+Binding: contracts/cli-validate.md, FR-008..014, Principle IX. The CI gate (exit 1)
+is computed from the **unfiltered** error-severity set, so ``--scope`` / ``--severity``
+(display filters) can never hide an error. Under ``--json`` exactly one JSON document
+goes to stdout; all prose goes to stderr.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from bookwright.core.errors import ManifestError
+from bookwright.core.manifest import Manifest
+from bookwright.errors import BookwrightError
+from bookwright.indexers import GraphLoadError, UnknownIndexerError, resolve_indexer
+from bookwright.io.errors import ProjectNotFoundError
+from bookwright.io.project import find_project_root
+from bookwright.validation import (
+    ScopeFilter,
+    Severity,
+    UnknownValidatorError,
+    ValidationContext,
+    ValidationReport,
+    discover_validators,
+    resolve_active,
+    run_validators,
+)
+
+from ._envelope import INVALID_MANIFEST_CODE
+
+EXIT_OK = 0
+EXIT_GATE = 1
+EXIT_CONFIG = 2
+
+_CUSTOM_SUBPATH = (".bookwright", "validators")
+
+
+class _UsageError(BookwrightError):
+    """An exit-2 config/usage failure carrying a contract error envelope.
+
+    A single class whose ``code`` is set per instance (``no_project`` /
+    ``invalid_manifest`` / ``unknown_validator`` / ``empty_scope``) — hence the
+    per-instance ``self.code`` override the base supports (research Decision 2).
+    """
+
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        self.code = code
+        super().__init__(message, details)
+
+
+def run(
+    scope: Annotated[
+        Path | None,
+        typer.Option("--scope", help="Limit the reported violations to this file or directory."),
+    ] = None,
+    severity: Annotated[
+        Severity,
+        typer.Option("--severity", help="Report this level and above (error>warning>info)."),
+    ] = Severity.info,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Emit one JSON document on stdout and nothing else.")
+    ] = False,
+) -> None:
+    """Validate the project and report coherence violations (exit 1 gates on errors)."""
+    try:
+        report, scope_filter = _validate(scope)
+    except _UsageError as exc:
+        _emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+
+    if json_output:
+        _emit_json(report.to_json(scope=scope_filter, severity=severity))
+    else:
+        report.render(Console(), scope=scope_filter, severity=severity)
+
+    raise typer.Exit(EXIT_GATE if report.failed else EXIT_OK)
+
+
+def _validate(scope: Path | None) -> tuple[ValidationReport, ScopeFilter | None]:
+    """Run the pipeline, raising :class:`_UsageError` for every exit-2 condition."""
+    try:
+        root = find_project_root()
+    except ProjectNotFoundError as exc:
+        raise _UsageError("no_project", str(exc), {"start": exc.start}) from exc
+
+    try:
+        manifest = Manifest.load(root / "manifest.toml")
+    except ManifestError as exc:
+        raise _UsageError(INVALID_MANIFEST_CODE, str(exc)) from exc
+
+    indexer = _load_indexer(manifest, root)
+    project = ValidationContext(root=root, manifest=manifest)
+
+    builtins, customs, load_errors = discover_validators(root.joinpath(*_CUSTOM_SUBPATH))
+    try:
+        active = resolve_active(builtins, customs, manifest.validators)
+    except UnknownValidatorError as exc:
+        # UnknownValidatorError is itself a BookwrightError carrying the exact
+        # ``unknown_validator`` envelope; re-thread its code/message/details into
+        # the exit-2 funnel rather than rebuilding them by hand.
+        raise _UsageError(exc.code, exc.message, exc.details) from exc
+
+    scope_filter = _resolve_scope(scope, root)
+
+    violations, run_errors, ran = run_validators(active, project, indexer)
+    report = ValidationReport(
+        violations=tuple(violations),
+        errors=(*load_errors, *run_errors),
+        ran=tuple(ran),
+    )
+    return report, scope_filter
+
+
+def _load_indexer(manifest: Manifest, root: Path) -> Any:
+    """The manifest-selected engine, with ``graph.ttl`` loaded when it exists."""
+    try:
+        engine_cls = resolve_indexer(manifest.bookwright.indexer)
+    except UnknownIndexerError as exc:
+        raise _UsageError("invalid_manifest", str(exc)) from exc
+    engine = engine_cls()
+    graph_path = root / manifest.paths.graph
+    if graph_path.is_file():
+        try:
+            engine.load(graph_path)
+        except GraphLoadError as exc:
+            raise _UsageError("invalid_manifest", str(exc)) from exc
+    return engine
+
+
+def _resolve_scope(scope: Path | None, root: Path) -> ScopeFilter | None:
+    """Resolve ``--scope`` under the project root, or exit 2 ``empty_scope`` (D10)."""
+    if scope is None:
+        return None
+    resolved = scope if scope.is_absolute() else (Path.cwd() / scope)
+    resolved = resolved.resolve()
+    if not resolved.exists():
+        raise _UsageError("empty_scope", f"scope path does not exist: {scope}")
+    try:
+        rel = resolved.relative_to(root).as_posix()
+    except ValueError as exc:
+        raise _UsageError("empty_scope", f"scope path is outside the project: {scope}") from exc
+    return ScopeFilter(rel=rel, is_dir=resolved.is_dir())
+
+
+def _emit_json(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+
+
+def _emit_error(payload: dict[str, Any], json_output: bool) -> None:
+    if json_output:
+        _emit_json(payload)
+    else:
+        sys.stderr.write(f"bookwright: error: {payload['message']}\n")

bookwright/commands/version.py

@@ -0,0 +1,35 @@
+"""`bookwright version` — report the package and GOLEM schema versions."""
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+
+from bookwright import __version__
+from bookwright.resources.schemas import load_schema_version
+
+
+def _read_golem_schema_version() -> str:
+    try:
+        return load_schema_version()
+    except FileNotFoundError:
+        return "unknown"
+
+
+def run(
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit a single JSON document on stdout."
+    ),
+) -> None:
+    """Print the bookwright package version and the bundled GOLEM schema version."""
+    payload = {
+        "package_version": __version__,
+        "golem_schema_version": _read_golem_schema_version(),
+    }
+    if json_output:
+        sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+        return
+    console = Console()
+    console.print(f"bookwright {payload['package_version']}")
+    console.print(f"GOLEM schema: {payload['golem_schema_version']}")

bookwright/core/__init__.py

@@ -0,0 +1,35 @@
+"""Public API for the Bookwright core domain model.
+
+The members re-exported below are the stable iteration-2 contract; anything
+else is implementation detail. See specs/002-manifest-model/contracts/manifest_api.md.
+"""
+
+from bookwright.core._research_block import ResearchBlock
+from bookwright.core.errors import (
+    ManifestError,
+    ManifestNotFoundError,
+    ManifestOverwriteError,
+    ManifestSyntaxError,
+    ManifestValidationError,
+    ManifestWarning,
+)
+from bookwright.core.manifest import (
+    BOOK_STATUSES,
+    BOOK_TYPES,
+    KNOWN_MANIFEST_VERSIONS,
+    Manifest,
+)
+
+__all__ = [
+    "BOOK_STATUSES",
+    "BOOK_TYPES",
+    "KNOWN_MANIFEST_VERSIONS",
+    "Manifest",
+    "ManifestError",
+    "ManifestNotFoundError",
+    "ManifestOverwriteError",
+    "ManifestSyntaxError",
+    "ManifestValidationError",
+    "ManifestWarning",
+    "ResearchBlock",
+]

bookwright/core/_blocks.py

@@ -0,0 +1,239 @@
+"""TOML block models for the Bookwright manifest.
+
+Internal helper extracted from `bookwright.core.manifest` to honour the
+Principle IV 500-line ceiling, mirroring the established `_build`,
+`_translate`, and `_research_block` split. The root `Manifest` model and the
+load/dump/build entry points stay in `manifest.py`, which re-exports the
+public members defined here (`BOOK_TYPES`, `BOOK_STATUSES`) so the
+`bookwright.core` surface is unchanged.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal, get_args
+from urllib.parse import urlsplit
+
+from packaging.version import InvalidVersion, Version
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+)
+from pydantic_core import PydanticCustomError
+
+from bookwright.core.iso639_1 import ISO_639_1_CODES
+
+_MANIFEST_VERSION_RE = re.compile(r"^[1-9][0-9]*$")
+
+BookType = Literal["novel", "essay", "memoir", "non-fiction-narrative", "other"]
+BookStatus = Literal["idea", "structuring", "drafting", "revising", "done"]
+
+BOOK_TYPES: frozenset[str] = frozenset(get_args(BookType))
+BOOK_STATUSES: frozenset[str] = frozenset(get_args(BookStatus))
+
+
+def _parse_manifest_version(raw: str) -> int:
+    """Parse the `bookwright.manifest_version` string into a positive int.
+
+    Raises a Pydantic-friendly error when the value does not match the
+    `^[1-9][0-9]*$` shape required by FR-013.
+    """
+
+    if not _MANIFEST_VERSION_RE.match(raw):
+        raise PydanticCustomError(
+            "not_positive_integer_string",
+            "manifest_version must match ^[1-9][0-9]*$ (got '{value}')",
+            {"value": raw},
+        )
+    return int(raw)
+
+
+class BookwrightBlock(BaseModel):
+    """`[bookwright]` block — CLI/schema floor and project URI namespace."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    cli_version_min: str
+    schema_version: str
+    manifest_version: str
+    uri_base: str
+    indexer: str = "rdflib"
+
+    @field_validator("cli_version_min", mode="after")
+    @classmethod
+    def _check_cli_version_min(cls, value: str) -> str:
+        try:
+            Version(value)
+        except InvalidVersion as exc:
+            raise PydanticCustomError(
+                "not_pep440",
+                "cli_version_min '{value}' is not a valid PEP 440 version",
+                {"value": value},
+            ) from exc
+        return value
+
+    @field_validator("schema_version", mode="after")
+    @classmethod
+    def _check_schema_version(cls, value: str) -> str:
+        stripped = value.strip()
+        if not stripped:
+            raise PydanticCustomError(
+                "empty",
+                "schema_version must be a non-empty string",
+                {"value": value},
+            )
+        if stripped != value:
+            raise PydanticCustomError(
+                "whitespace",
+                "schema_version must not have leading or trailing whitespace",
+                {"value": value},
+            )
+        return value
+
+    @field_validator("manifest_version", mode="after")
+    @classmethod
+    def _check_manifest_version(cls, value: str) -> str:
+        _parse_manifest_version(value)
+        return value
+
+    @field_validator("uri_base", mode="after")
+    @classmethod
+    def _check_uri_base(cls, value: str) -> str:
+        try:
+            parts = urlsplit(value)
+        except ValueError as exc:
+            raise PydanticCustomError(
+                "invalid_uri",
+                "uri_base '{value}' is not a parseable URI",
+                {"value": value},
+            ) from exc
+        scheme = parts.scheme.lower()
+        if scheme not in {"http", "https"}:
+            raise PydanticCustomError(
+                "wrong_scheme",
+                "uri_base must use http or https (got scheme '{scheme}')",
+                {"scheme": parts.scheme, "value": value},
+            )
+        if not parts.netloc:
+            raise PydanticCustomError(
+                "empty_host",
+                "uri_base must include a non-empty host",
+                {"value": value},
+            )
+        if parts.query:
+            raise PydanticCustomError(
+                "has_query",
+                "uri_base must not include a query string",
+                {"value": value},
+            )
+        if parts.fragment:
+            raise PydanticCustomError(
+                "has_fragment",
+                "uri_base must not include a fragment",
+                {"value": value},
+            )
+        if not value.endswith("/"):
+            raise PydanticCustomError(
+                "no_trailing_slash",
+                "uri_base must end with '/'",
+                {"value": value},
+            )
+        return value
+
+
+class BookBlock(BaseModel):
+    """`[book]` block — author-facing metadata about the work."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    title: str
+    type: BookType
+    language: str
+    authors: list[str]
+    subtitle: str = ""
+    genre: list[str] = Field(default_factory=list)
+    target_length_words: int | None = None
+    status: BookStatus = "drafting"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("title", mode="after")
+    @classmethod
+    def _check_title(cls, value: str) -> str:
+        if not value.strip():
+            raise PydanticCustomError(
+                "empty",
+                "title must be a non-empty string",
+                {"value": value},
+            )
+        return value
+
+    @field_validator("language", mode="after")
+    @classmethod
+    def _check_language(cls, value: str) -> str:
+        if value not in ISO_639_1_CODES:
+            raise PydanticCustomError(
+                "not_iso_639_1",
+                "language '{value}' is not a valid ISO 639-1 code",
+                {"value": value},
+            )
+        return value
+
+    @field_validator("authors", mode="after")
+    @classmethod
+    def _check_authors(cls, value: list[str]) -> list[str]:
+        if not value:
+            raise PydanticCustomError(
+                "empty",
+                "authors must contain at least one entry",
+                {"value": value},
+            )
+        for index, entry in enumerate(value):
+            if not entry.strip():
+                raise PydanticCustomError(
+                    "entry.empty",
+                    "authors[{index}] must be a non-empty string",
+                    {"index": index, "value": entry},
+                )
+        return value
+
+
+class VocabulariesBlock(BaseModel):
+    """`[vocabularies]` block — names of active vocabulary lists."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    active: list[str] = Field(default_factory=list)
+
+
+class ValidatorsBlock(BaseModel):
+    """`[validators]` block — built-in and custom validator names."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    enabled: list[str] = Field(default_factory=list)
+    disabled: list[str] = Field(default_factory=list)
+    custom: list[str] = Field(default_factory=list)
+
+
+class IntegrationBlock(BaseModel):
+    """`[integration]` block — opaque data the loader never dispatches on."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    key: str
+    skills_dir: str
+    options: dict[str, Any] = Field(default_factory=dict)
+
+
+class PathsBlock(BaseModel):
+    """`[paths]` block — project-relative content roots."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    manuscript: str = "manuscript/"
+    bible: str = "bible/"
+    outline: str = "outline/"
+    graph: str = "bible/graph.ttl"
+    constitution: str = "bible/constitution.md"