bookwright-cli 0.2.0__tar.gz → 0.3.2__tar.gz

{bookwright_cli-0.2.0 → bookwright_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bookwright-cli
-Version: 0.2.0
+Version: 0.3.2
 Summary: Spec-driven authoring toolkit for novels, essays, and memoirs.
 Project-URL: Homepage, https://github.com/jmorenobl/bookwright
 Project-URL: Repository, https://github.com/jmorenobl/bookwright
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <a href="https://github.com/jmorenobl/bookwright/actions/workflows/tests.yml"><img src="https://github.com/jmorenobl/bookwright/actions/workflows/tests.yml/badge.svg" alt="CI"></a>
-  <a href="https://github.com/jmorenobl/bookwright/blob/main/CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.2.0-6f42c1" alt="Versión 0.2.0"></a>
+  <a href="https://github.com/jmorenobl/bookwright/blob/main/CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.3.0-6f42c1" alt="Versión 0.3.0"></a>
   <a href="https://github.com/jmorenobl/bookwright/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Licencia: Apache-2.0"></a>
   <img src="https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python&logoColor=white" alt="Python 3.11+">
   <img src="https://img.shields.io/badge/coverage-%E2%89%A580%25-2ea44f" alt="Cobertura ≥80%">
@@ -61,21 +61,32 @@ IA escriba a partir de *ellos*, no de un chat libre. Tu libro vive en
 texto plano, versionado en git, completamente auditable, y sobrevive al
 toolkit.
 
-> ### Estado: v0.2.0
+> ### Estado: v0.3.0
 >
-> Dos hitos están en `main`. **v0.1.0** (el toolkit base, iteraciones
+> Tres hitos están en `main`. **v0.1.0** (el toolkit base, iteraciones
 > 1–11): scaffolding del proyecto (`bookwright init`), el modelo de
 > dominio GOLEM, el indexer y los comandos `bookwright graph`, las skills
 > de autoría materializadas como Agent Skills, y el sistema de validación
 > de continuidad. **v0.2.0 / M4** (investigación y verificación,
 > iteraciones 12–18): el modelo de procedencia `Source` / `Finding` /
 > `Anchor`, las skills `/bookwright-research` y `/bookwright-verify`, el
-> validador `factual_anchor` y la envoltura `--json` unificada. La
-> documentación de usuario completa vive en el
+> validador `factual_anchor` y la envoltura `--json` unificada.
+> **v0.3.0 / M5** (orquestación de contexto, iteraciones 19–23): el foco
+> autoral (`[focus]` + `bookwright focus`), el estado derivado
+> `bookwright status` con sus `next_actions`, y las skills que lo
+> consumen para guiar el siguiente paso. La documentación de usuario
+> completa vive en el
 > [sitio de documentación](https://github.com/jmorenobl/bookwright/blob/main/docs/index.md).
 
 ## El loop del escritor
 
+<p align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/jmorenobl/bookwright/main/assets/loop.svg" type="image/svg+xml">
+    <img src="https://raw.githubusercontent.com/jmorenobl/bookwright/main/assets/loop.png" alt="El loop del escritor: idea → scaffolding → destila → build y valida → edita, y vuelta a empezar" width="100%">
+  </picture>
+</p>
+
 1. **Idea libremente** — conversa con tu agente o tu libreta y vuelca un
    brief a Markdown.
 2. **Scaffolding del proyecto** —
@@ -108,15 +119,33 @@ toolkit.
 
 ## Instalación
 
+El paquete en PyPI es `bookwright-cli`; el comando que instala es `bookwright`.
+
+Desde PyPI (recomendado):
+
 ```bash
-uv build
-pipx install ./dist/bookwright_cli-*.whl   # o: uv tool install ./dist/*.whl
+uv tool install bookwright-cli   # con uv
+pipx install bookwright-cli      # o con pipx
 bookwright version
 ```
 
-Para desarrollar sobre el toolkit, sincroniza el entorno del proyecto:
+Directamente desde el repositorio (última versión de `main`):
 
 ```bash
+uv tool install "git+https://github.com/jmorenobl/bookwright"
+# o:  pipx install "git+https://github.com/jmorenobl/bookwright"
+```
+
+¿Solo quieres probarlo una vez, sin instalar nada?
+
+```bash
+uvx --from bookwright-cli bookwright version
+```
+
+Para desarrollar sobre el toolkit, clona el repo y sincroniza el entorno:
+
+```bash
+git clone https://github.com/jmorenobl/bookwright && cd bookwright
 uv sync
 uv run bookwright --help
 ```
@@ -156,6 +185,14 @@ bookwright graph query "SELECT ?c WHERE { ?c a golem:G1_Character }" --json
 bookwright validate                               # exit 0 si no hay errores
 ```
 
+Para mantener el hilo conductor entre sesiones, fija tu foco autoral y deja que
+Bookwright derive el estado y el siguiente paso:
+
+```bash
+bookwright focus set --target "Cerrar la investigación del libro de jornales"
+bookwright status --json                          # estado derivado + next_actions
+```
+
 ¿Quieres cambiar de integración (p. ej. de `claude` a `generic`)?
 
 ```bash
@@ -184,9 +221,11 @@ El recorrido completo está en
 ## Roadmap y fuera de scope
 
 Hecho: **v0.2 / M4** — investigación y verificación (modelo de procedencia,
-skills `research`/`verify`, validador `factual_anchor`). Planificado:
-**v0.3** — búsqueda vectorial (ChromaDB sobre rdflib, desacoplada); **v1.0** —
-export a EPUB / PDF / impresión vía pandoc.
+skills `research`/`verify`, validador `factual_anchor`); **v0.3 / M5** —
+orquestación de contexto (foco autoral `[focus]` + `bookwright focus`, estado
+derivado `bookwright status` con `next_actions`, y las skills que lo consumen).
+Planificado: **v0.4** — búsqueda vectorial (ChromaDB sobre rdflib, desacoplada);
+**v1.0** — export a EPUB / PDF / impresión vía pandoc.
 
 **Cancelado (decisión del owner), no lo pidas:** presets de género / paquetes
 de plantilla (la resolución es de 2 capas, overrides → core); el motor

{bookwright_cli-0.2.0 → bookwright_cli-0.3.2}/README.md

@@ -7,7 +7,7 @@
 
 <p align="center">
   <a href="https://github.com/jmorenobl/bookwright/actions/workflows/tests.yml"><img src="https://github.com/jmorenobl/bookwright/actions/workflows/tests.yml/badge.svg" alt="CI"></a>
-  <a href="https://github.com/jmorenobl/bookwright/blob/main/CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.2.0-6f42c1" alt="Versión 0.2.0"></a>
+  <a href="https://github.com/jmorenobl/bookwright/blob/main/CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.3.0-6f42c1" alt="Versión 0.3.0"></a>
   <a href="https://github.com/jmorenobl/bookwright/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Licencia: Apache-2.0"></a>
   <img src="https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python&logoColor=white" alt="Python 3.11+">
   <img src="https://img.shields.io/badge/coverage-%E2%89%A580%25-2ea44f" alt="Cobertura ≥80%">
@@ -28,21 +28,32 @@ IA escriba a partir de *ellos*, no de un chat libre. Tu libro vive en
 texto plano, versionado en git, completamente auditable, y sobrevive al
 toolkit.
 
-> ### Estado: v0.2.0
+> ### Estado: v0.3.0
 >
-> Dos hitos están en `main`. **v0.1.0** (el toolkit base, iteraciones
+> Tres hitos están en `main`. **v0.1.0** (el toolkit base, iteraciones
 > 1–11): scaffolding del proyecto (`bookwright init`), el modelo de
 > dominio GOLEM, el indexer y los comandos `bookwright graph`, las skills
 > de autoría materializadas como Agent Skills, y el sistema de validación
 > de continuidad. **v0.2.0 / M4** (investigación y verificación,
 > iteraciones 12–18): el modelo de procedencia `Source` / `Finding` /
 > `Anchor`, las skills `/bookwright-research` y `/bookwright-verify`, el
-> validador `factual_anchor` y la envoltura `--json` unificada. La
-> documentación de usuario completa vive en el
+> validador `factual_anchor` y la envoltura `--json` unificada.
+> **v0.3.0 / M5** (orquestación de contexto, iteraciones 19–23): el foco
+> autoral (`[focus]` + `bookwright focus`), el estado derivado
+> `bookwright status` con sus `next_actions`, y las skills que lo
+> consumen para guiar el siguiente paso. La documentación de usuario
+> completa vive en el
 > [sitio de documentación](https://github.com/jmorenobl/bookwright/blob/main/docs/index.md).
 
 ## El loop del escritor
 
+<p align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/jmorenobl/bookwright/main/assets/loop.svg" type="image/svg+xml">
+    <img src="https://raw.githubusercontent.com/jmorenobl/bookwright/main/assets/loop.png" alt="El loop del escritor: idea → scaffolding → destila → build y valida → edita, y vuelta a empezar" width="100%">
+  </picture>
+</p>
+
 1. **Idea libremente** — conversa con tu agente o tu libreta y vuelca un
    brief a Markdown.
 2. **Scaffolding del proyecto** —
@@ -75,15 +86,33 @@ toolkit.
 
 ## Instalación
 
+El paquete en PyPI es `bookwright-cli`; el comando que instala es `bookwright`.
+
+Desde PyPI (recomendado):
+
 ```bash
-uv build
-pipx install ./dist/bookwright_cli-*.whl   # o: uv tool install ./dist/*.whl
+uv tool install bookwright-cli   # con uv
+pipx install bookwright-cli      # o con pipx
 bookwright version
 ```
 
-Para desarrollar sobre el toolkit, sincroniza el entorno del proyecto:
+Directamente desde el repositorio (última versión de `main`):
 
 ```bash
+uv tool install "git+https://github.com/jmorenobl/bookwright"
+# o:  pipx install "git+https://github.com/jmorenobl/bookwright"
+```
+
+¿Solo quieres probarlo una vez, sin instalar nada?
+
+```bash
+uvx --from bookwright-cli bookwright version
+```
+
+Para desarrollar sobre el toolkit, clona el repo y sincroniza el entorno:
+
+```bash
+git clone https://github.com/jmorenobl/bookwright && cd bookwright
 uv sync
 uv run bookwright --help
 ```
@@ -123,6 +152,14 @@ bookwright graph query "SELECT ?c WHERE { ?c a golem:G1_Character }" --json
 bookwright validate                               # exit 0 si no hay errores
 ```
 
+Para mantener el hilo conductor entre sesiones, fija tu foco autoral y deja que
+Bookwright derive el estado y el siguiente paso:
+
+```bash
+bookwright focus set --target "Cerrar la investigación del libro de jornales"
+bookwright status --json                          # estado derivado + next_actions
+```
+
 ¿Quieres cambiar de integración (p. ej. de `claude` a `generic`)?
 
 ```bash
@@ -151,9 +188,11 @@ El recorrido completo está en
 ## Roadmap y fuera de scope
 
 Hecho: **v0.2 / M4** — investigación y verificación (modelo de procedencia,
-skills `research`/`verify`, validador `factual_anchor`). Planificado:
-**v0.3** — búsqueda vectorial (ChromaDB sobre rdflib, desacoplada); **v1.0** —
-export a EPUB / PDF / impresión vía pandoc.
+skills `research`/`verify`, validador `factual_anchor`); **v0.3 / M5** —
+orquestación de contexto (foco autoral `[focus]` + `bookwright focus`, estado
+derivado `bookwright status` con `next_actions`, y las skills que lo consumen).
+Planificado: **v0.4** — búsqueda vectorial (ChromaDB sobre rdflib, desacoplada);
+**v1.0** — export a EPUB / PDF / impresión vía pandoc.
 
 **Cancelado (decisión del owner), no lo pidas:** presets de género / paquetes
 de plantilla (la resolución es de 2 capas, overrides → core); el motor

{bookwright_cli-0.2.0 → bookwright_cli-0.3.2}/src/bookwright/__init__.py

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

{bookwright_cli-0.2.0 → bookwright_cli-0.3.2}/src/bookwright/cli.py

@@ -2,7 +2,7 @@
 
 import typer
 
-from bookwright.commands import check, graph, init, integration, validate, version
+from bookwright.commands import check, focus, graph, init, integration, status, validate, version
 
 app = typer.Typer(
     name="bookwright",
@@ -14,6 +14,8 @@ app = typer.Typer(
 app.command("version")(version.run)
 app.command("check")(check.run)
 app.command("init", context_settings=init.CONTEXT_SETTINGS)(init.run)
+app.command("status")(status.run)
 app.command("validate")(validate.run)
 app.add_typer(graph.app, name="graph")
 app.add_typer(integration.app, name="integration")
+app.add_typer(focus.app, name="focus")

bookwright_cli-0.3.2/src/bookwright/commands/_envelope.py

@@ -0,0 +1,116 @@
+"""Shared command-layer envelope helpers.
+
+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.
+
+The :func:`emit_json` / :func:`emit_error` pair is single-sourced here too: a
+single-line ``json.dumps(payload, separators=(",", ":")) + "\\n"`` to stdout,
+with human prose / progress going to stderr via a ``Console(stderr=True)`` owned
+by each command. Every ``--json`` command (``check``, ``focus``, ``graph``,
+``init``, ``integration``, ``validate``, ``version``) routes its stdout encoding
+through :func:`emit_json` instead of hand-rolling a per-group copy.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import TYPE_CHECKING, Any
+
+from bookwright.errors import BookwrightError
+
+if TYPE_CHECKING:
+    from bookwright.io.errors import ProjectNotFoundError
+
+#: The CLI-wide "configuration fault" exit status (missing project, unparseable
+#: manifest, unknown engine/integration, bad scope, …). Single-sourced here so
+#: the command groups cannot drift to different statuses for the same fault class.
+EXIT_CONFIG = 2
+
+#: The CLI-wide "slug collision" exit status. ``graph build`` and ``status``
+#: must exit identically on the same corpus (020 research D4), so the literal
+#: lives once here, beside :data:`EXIT_CONFIG`.
+EXIT_COLLISION = 3
+
+
+def ok_payload(**fields: Any) -> dict[str, Any]:
+    """The success-envelope skeleton: ``{"status": "ok", **fields}`` (Principle IX).
+
+    The success-side complement of ``BookwrightError.to_json()`` — the one place
+    the ``"status": "ok"`` literal lives for new success documents (020 research
+    D6). Existing ``check``/``focus``/``graph`` call sites keep their hand-built
+    dicts for now; migrating them is out of 020's scope.
+    """
+    return {"status": "ok", **fields}
+
+
+def render_json(payload: dict[str, Any]) -> str:
+    """The canonical one-line JSON encoding of a contract document.
+
+    The single place the compact-separators + trailing-newline format lives:
+    :func:`emit_json` routes stdout through it, and ``status`` renders its
+    document once here so stdout and the cache file share the exact bytes
+    (020 research D6) by construction, not by parallel formatting calls.
+    """
+    return json.dumps(payload, separators=(",", ":")) + "\n"
+
+
+def emit_json(payload: dict[str, Any]) -> None:
+    """Write exactly one JSON document to stdout (the only thing on stdout)."""
+    sys.stdout.write(render_json(payload))
+
+
+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")
+
+
+#: 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()
+
+
+#: The contract code for "ran outside a project" at a ``--json`` boundary.
+#: Single-sourced here so the two remap sites — ``commands.status`` and
+#: ``commands.validate._UsageError`` — cannot drift to different literals.
+NO_PROJECT_CODE = "no_project"
+
+
+class _NoProjectError(BookwrightError):
+    """A caught ``ProjectNotFoundError`` re-coded to the contract's ``no_project``.
+
+    Mirrors :class:`_InvalidManifestError`: the remap is a ``BookwrightError``
+    whose canonical ``to_json()`` builds the envelope, never a hand-rolled dict.
+    """
+
+    code = NO_PROJECT_CODE
+
+
+def no_project_payload(exc: ProjectNotFoundError) -> dict[str, Any]:
+    """The ``no_project`` error envelope for a caught ``ProjectNotFoundError``."""
+    return _NoProjectError(str(exc), {"start": exc.start}).to_json()

bookwright_cli-0.3.2/src/bookwright/commands/_graph.py

@@ -0,0 +1,135 @@
+"""The shared graph-build pipeline (`graph build` + `status`, 020 research D1).
+
+The pipeline body extracted from ``commands/graph/build.py``: map the bible to
+GOLEM entities (with CIDOC provenance), map ``bible/research/``, feed every
+triple into one manifest-selected engine, and refresh the derived
+``bible/graph.ttl`` cache. Both verbs consume this one implementation so the
+graph they reason over can never diverge.
+
+The fault model is the pipeline's own — :class:`MissingDirectoryError` for
+absent prerequisites, ``UnknownIndexerError`` from engine resolution,
+``SlugCollisionError`` / ``ResearchError`` from the mappers. Callers own
+project/manifest resolution and the exit-code mapping (`graph build` per
+cli-graph.md R7; `status` per 020 research D4/D5).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from bookwright.golem.namespaces import timeline_uri
+from bookwright.indexers import Indexer, UnknownIndexerError, resolve_indexer
+from bookwright.io.bible import build_provenance, map_bible
+from bookwright.io.errors import MissingDirectoryError, ResearchError
+from bookwright.io.manuscript import manuscript_present
+from bookwright.io.report import BuildReport, ResearchTargetWarning
+from bookwright.io.research import ResearchResult, map_research
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from bookwright.core.manifest import Manifest
+    from bookwright.errors import BookwrightError
+
+#: The pipeline's own exit-2 fault classes, single-sourced beside the pipeline
+#: that raises them so the two consuming except-ladders (`graph build`,
+#: `status`) cannot drift apart on the same corpus (020 research D4).
+PIPELINE_CONFIG_FAULTS: tuple[type[BookwrightError], ...] = (
+    MissingDirectoryError,
+    UnknownIndexerError,
+    ResearchError,
+)
+
+
+def missing_prerequisite(root: Path, manifest: Manifest) -> tuple[str, Path] | None:
+    """The first absent build prerequisite as ``(label, path)``, or ``None``.
+
+    The single statement of "can this corpus build?": :func:`build_project_graph`
+    raises ``MissingDirectoryError`` from it, and ``status`` branches to its
+    degraded report on it (020 research D5) — one predicate, no drift.
+    """
+    bible_dir = root / manifest.paths.bible
+    if not bible_dir.is_dir():
+        return ("bible", bible_dir)
+    manuscript_dir = root / manifest.paths.manuscript
+    if not manuscript_present(manuscript_dir):
+        return ("manuscript", manuscript_dir)
+    return None
+
+
+@dataclass(frozen=True)
+class BuildOutcome:
+    """Everything one pipeline run yields (data-model 020 § 5).
+
+    ``report`` is what `graph build` emits; ``engine`` (already populated and
+    saved) and ``research`` (carrying the authored identities, research D2) are
+    what ``status`` aggregates over.
+    """
+
+    engine: Indexer
+    report: BuildReport
+    research: ResearchResult
+
+
+def build_project_graph(root: Path, manifest: Manifest) -> BuildOutcome:
+    """Build the project graph from the bible and write ``manifest.paths.graph``.
+
+    Raises the fault-model exceptions documented in the module docstring; on
+    success the returned engine holds the full graph and the Turtle cache on
+    disk matches it.
+    """
+    missing = missing_prerequisite(root, manifest)
+    if missing is not None:
+        label, path = missing
+        raise MissingDirectoryError(label, str(path))
+
+    bible_dir = root / manifest.paths.bible
+    engine_cls = resolve_indexer(manifest.bookwright.indexer)
+    engine = engine_cls()
+
+    uri_base = manifest.bookwright.uri_base
+    result = map_bible(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(
+        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(root / graph_rel)
+
+    report = 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
+        ),
+    )
+    return BuildOutcome(engine=engine, report=report, research=research)

bookwright_cli-0.3.2/src/bookwright/commands/_project.py

@@ -0,0 +1,44 @@
+"""Shared project-load + ``--json`` fault boundary for the command layer.
+
+Every manifest-reading subcommand locates the project and loads the manifest the
+same way and remaps the same two faults to exit 2 (research D10). Factoring it
+here — next to the envelope helpers in :mod:`bookwright.commands._envelope` —
+keeps each command body to its own logic and gives later iterations (e.g. the
+020 ``bookwright status`` read path) the boundary without reaching into a
+sibling command package.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from bookwright.core.errors import ManifestError
+from bookwright.core.manifest import Manifest
+from bookwright.io.errors import ProjectNotFoundError
+from bookwright.io.project import find_project_root
+
+from ._envelope import EXIT_CONFIG, emit_error, invalid_manifest_payload
+
+
+def load_manifest_or_exit(json_output: bool) -> tuple[Path, Manifest]:
+    """Return ``(manifest_path, manifest)`` or emit the fault envelope and exit 2.
+
+    A caught ``ManifestError`` collapses to the contract's ``invalid_manifest``
+    code; ``ProjectNotFoundError`` carries its own ``not_a_project`` code. Both
+    exit 2 — the structured distinction lives in the envelope ``code`` (research
+    D7), never the exit status.
+    """
+
+    try:
+        root = find_project_root()
+        path = root / "manifest.toml"
+        manifest = Manifest.load(path)
+    except ManifestError as exc:
+        emit_error(invalid_manifest_payload(exc), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    except ProjectNotFoundError as exc:
+        emit_error(exc.to_json(), json_output)
+        raise typer.Exit(EXIT_CONFIG) from exc
+    return path, manifest

{bookwright_cli-0.2.0 → bookwright_cli-0.3.2}/src/bookwright/commands/check.py

@@ -1,13 +1,14 @@
 """`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
 
+from ._envelope import emit_json
+
 RUNTIME_MODULES: tuple[str, ...] = (
     "typer",
     "rich",
@@ -64,7 +65,7 @@ def run(
     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")
+        emit_json(payload)
     else:
         console = Console()
         for check in checks:

bookwright_cli-0.3.2/src/bookwright/commands/focus/__init__.py

@@ -0,0 +1,24 @@
+"""The ``bookwright focus`` Typer sub-app.
+
+``show``, ``set``, and ``clear`` 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(focus.app, name="focus")``.
+"""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    name="focus",
+    help="Record, view, and clear the authored focus state.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# Each subcommand registers its callback on `app` at import time; the per-story
+# `from . import …` lines are appended below as the modules land. The `as`
+# redirect marks the import as an intentional re-export (registration side effect).
+from . import clear as clear  # noqa: E402
+from . import set_ as set_  # noqa: E402  (module name avoids shadowing builtins.set)
+from . import show as show  # noqa: E402

bookwright_cli-0.3.2/src/bookwright/commands/focus/clear.py

@@ -0,0 +1,40 @@
+"""``bookwright focus clear [--json]``.
+
+Remove the ``[focus]`` block, preserving the rest of the manifest. Absent block ⇒
+a successful no-op (FR-010). Under ``--json`` emit
+``{"status":"ok","cleared":<bool>}`` — the boolean discriminator lets an agent
+tell a real removal from a no-op without a second read; both exit 0. Human prose
+goes to stderr (Principle IX).
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from .._envelope import emit_json
+from .._project import load_manifest_or_exit
+from . import app
+
+
+@app.command("clear")
+def run(
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit the result as one JSON document on stdout."
+    ),
+) -> None:
+    """Clear the authored focus state (no-op when none is set)."""
+    path, manifest = load_manifest_or_exit(json_output)
+    had_focus = manifest.focus is not None
+
+    manifest.clear_focus()
+    # Only rewrite when something actually changed — a no-op leaves the bytes
+    # untouched rather than re-serializing an unchanged manifest.
+    if had_focus:
+        manifest.dump(path, overwrite=True)
+
+    if json_output:
+        emit_json({"status": "ok", "cleared": had_focus})
+    else:
+        message = "focus cleared" if had_focus else "no focus to clear"
+        Console(stderr=True, highlight=False).print(message)