bookwright-cli 0.2.0__py3-none-any.whl

bookwright/commands/init/envelope.py

@@ -0,0 +1,322 @@
+"""Success/error JSON envelopes and the ``.bookwright/init-options.json`` record.
+
+Single source of truth for the contract-§3 envelope shapes and the
+``InitOptionsRecord`` schema pinned in data-model §1. Pure helpers; the
+only filesystem-touching primitive is ``dump_options_record`` and even
+that just writes one JSON file.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal, NoReturn
+
+import typer
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from bookwright import __version__ as _BOOKWRIGHT_VERSION
+from bookwright.core.iso639_1 import ISO_639_1_CODES
+from bookwright.errors import BookwrightError
+from bookwright.integrations import (
+    MalformedOptionError,
+    SkillLintError,
+    SkillMaterializationError,
+)
+
+from .git import GitInitError
+from .scaffold import BackupCreationError, TargetOutsideProjectRootError
+
+SCHEMA_VERSION = 1
+
+_ISO_UTC_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$")
+
+
+class ResolvedInvocation(BaseModel):
+    """Resolved values for one ``init`` invocation (data-model §2)."""
+
+    model_config = ConfigDict(extra="forbid", strict=False)
+
+    mode: Literal["named", "here"]
+    project_name: str | None
+    project_slug: str
+    project_root: str
+    title: str
+    authors: list[str]
+    language: str
+    integration_key: str
+    integration_skills_dir: str
+    integration_options: dict[str, str | bool] = Field(default_factory=dict)
+    no_git: bool
+    force: bool
+    json_output: bool
+    git_status: Literal[
+        "initialized",
+        "skipped_by_flag",
+        "skipped_no_binary",
+        "skipped_existing_repo",
+    ]
+    deprecated_flags_seen: list[str] = Field(default_factory=list)
+
+    @field_validator("language")
+    @classmethod
+    def _check_language(cls, value: str) -> str:
+        if value not in ISO_639_1_CODES:
+            raise ValueError(f"language {value!r} is not a valid ISO 639-1 code")
+        return value
+
+    @field_validator("authors")
+    @classmethod
+    def _check_authors(cls, value: list[str]) -> list[str]:
+        if not value:
+            raise ValueError("authors must be non-empty")
+        return value
+
+    @field_validator("integration_skills_dir")
+    @classmethod
+    def _check_skills_dir(cls, value: str) -> str:
+        if value.startswith("/"):
+            raise ValueError(f"integration_skills_dir must be relative (got {value!r})")
+        if ".." in Path(value).parts:
+            raise ValueError(f"integration_skills_dir must not contain '..' (got {value!r})")
+        return value
+
+
+class InitOptionsRecord(BaseModel):
+    """``.bookwright/init-options.json`` envelope (data-model §1)."""
+
+    model_config = ConfigDict(extra="forbid", strict=False)
+
+    schema_version: int = SCHEMA_VERSION
+    created_at: str
+    bookwright_version: str
+    options: ResolvedInvocation
+
+    @field_validator("schema_version")
+    @classmethod
+    def _check_schema_version(cls, value: int) -> int:
+        if value != SCHEMA_VERSION:
+            raise ValueError(f"schema_version must be {SCHEMA_VERSION} (got {value})")
+        return value
+
+    @field_validator("created_at")
+    @classmethod
+    def _check_created_at(cls, value: str) -> str:
+        if not _ISO_UTC_RE.match(value):
+            raise ValueError(f"created_at must match {_ISO_UTC_RE.pattern} (got {value!r})")
+        return value
+
+
+def _utc_now_iso_z() -> str:
+    """ISO 8601 UTC second-precision suffixed with ``Z``."""
+
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def success_envelope(
+    resolved: ResolvedInvocation,
+    warnings: list[str],
+) -> dict[str, Any]:
+    """Contract §3.1 success-envelope shape."""
+
+    return {
+        "status": "ok",
+        "project_root": resolved.project_root,
+        "project_slug": resolved.project_slug,
+        "mode": resolved.mode,
+        "integration": {
+            "key": resolved.integration_key,
+            "skills_dir": resolved.integration_skills_dir,
+            "options": dict(resolved.integration_options),
+        },
+        "git_status": resolved.git_status,
+        "warnings": list(warnings),
+        "bookwright_version": _BOOKWRIGHT_VERSION,
+    }
+
+
+def error_envelope(
+    error: BookwrightError | str,
+    message: str | None = None,
+    details: dict[str, Any] | None = None,
+    *,
+    rolled_back: bool,
+) -> dict[str, Any]:
+    """Contract §3.2 error-envelope shape: the canonical body + init's superset.
+
+    The ``{status,code,message[,details]}`` skeleton lives in exactly one place —
+    ``BookwrightError.to_json`` (review R1). Pass a ``BookwrightError`` to spread
+    that body; pass a primitive ``code`` (as ``error``) plus ``message``/``details``
+    for the non-``BookwrightError`` carve-outs that ``classify_filesystem_failure``
+    maps by hand (``OSError``/``PermissionError``/``GitInitError`` and the two
+    ``io.fs`` errors).
+    """
+
+    body: dict[str, Any]
+    if isinstance(error, BookwrightError):
+        body = error.to_json()
+    else:
+        body = {
+            "status": "error",
+            "code": error,
+            "message": message,
+            "details": dict(details or {}),
+        }
+    return {**body, "rolled_back": rolled_back, "bookwright_version": _BOOKWRIGHT_VERSION}
+
+
+def dump_success_to_stdout(payload: dict[str, Any]) -> None:
+    """Write the success envelope to stdout (contract §3.1 encoding)."""
+
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+
+
+def dump_error_to_stdout(payload: dict[str, Any]) -> None:
+    """Write the error envelope to stdout (contract §3.2 encoding)."""
+
+    sys.stdout.write(json.dumps(payload, separators=(",", ":")) + "\n")
+
+
+def _emit(payload: dict[str, Any], message: str, *, exit_code: int, json_output: bool) -> NoReturn:
+    """Surface an error envelope, then exit: one JSON document on stdout under
+    ``--json`` (contract §3.2), else a single ``bookwright: error: <message>``
+    line on stderr (Principle IX). Always raises."""
+
+    if json_output:
+        dump_error_to_stdout(payload)
+    else:
+        sys.stderr.write(f"bookwright: error: {message}\n")
+    raise typer.Exit(exit_code)
+
+
+def emit_error(  # noqa: PLR0913 — structured-error envelope demands all six fields
+    *,
+    code: str,
+    message: str,
+    details: dict[str, Any],
+    exit_code: int,
+    json_output: bool,
+    rolled_back: bool,
+) -> NoReturn:
+    """Build and emit the error envelope for a primitive ``code``/``message``/
+    ``details`` triple, then raise ``typer.Exit(exit_code)``.
+
+    The call sites with no ``BookwrightError`` in hand (mutex, removed flags, the
+    conflict matrix, and the filesystem/permission carve-outs). Always raises —
+    callers can rely on ``NoReturn`` for control-flow analysis.
+    """
+
+    _emit(
+        error_envelope(code, message, details, rolled_back=rolled_back),
+        message,
+        exit_code=exit_code,
+        json_output=json_output,
+    )
+
+
+def emit_scaffold_failure(exc: BaseException, *, json_output: bool) -> NoReturn:
+    """Emit the §3.2 envelope for a caught scaffold-time exception, then exit.
+
+    A ``BookwrightError`` (``MalformedOptionError``/``SkillLintError``/
+    ``SkillMaterializationError``) carries its own canonical body, so we spread
+    ``error_envelope(exc, ...)`` — keeping the skeleton single-sourced in
+    ``BookwrightError.to_json`` (review R1). The non-``BookwrightError`` carve-outs
+    (``OSError``/``PermissionError``/``GitInitError`` and the two ``io.fs`` errors)
+    have no envelope, so ``classify_filesystem_failure`` maps them to a primitive
+    ``code``/``details`` pair; only its ``exit_code`` is consulted for the base
+    path. The scaffold is already rolled back by the caller, hence
+    ``rolled_back=True``.
+    """
+
+    code, exit_code, details = classify_filesystem_failure(exc)
+    if isinstance(exc, BookwrightError):
+        payload = error_envelope(exc, rolled_back=True)
+        message = exc.message
+    else:
+        message = str(exc) or code
+        payload = error_envelope(code, message, details, rolled_back=True)
+    _emit(payload, message, exit_code=exit_code, json_output=json_output)
+
+
+def classify_filesystem_failure(  # noqa: PLR0911 — one branch per contract §4 exception type
+    exc: BaseException,
+) -> tuple[str, int, dict[str, Any]]:
+    """Map a scaffold-time exception to ``(code, exit_code, details)`` (contract §4)."""
+
+    if isinstance(exc, MalformedOptionError):
+        # `SkillsIntegration.setup()` raises this at scaffold time for
+        # `resolves_to_project_root` / `escapes_project_root` (and similar
+        # option-domain rules). Surface it with the same code/exit_code/details
+        # shape that parse-time `MalformedOptionError` uses in
+        # `resolve.resolve_integration`, so consumers see a single contract.
+        return (
+            "malformed_option",
+            5,
+            {"value": exc.value, "rule": exc.rule},
+        )
+    if isinstance(exc, (SkillLintError, SkillMaterializationError)):
+        # The skills materializer (SkillsIntegration.setup()) aborts the
+        # integration on a lint failure or an authoring error. Surface the
+        # structured error verbatim (its `code` distinguishes the two) so the
+        # JSON envelope carries the skill/rule/detail triple (FR-016/FR-020).
+        return (
+            exc.code,
+            6,
+            {"skill": exc.skill, "rule": exc.rule, "detail": exc.detail},
+        )
+    if isinstance(exc, BackupCreationError):
+        return (
+            "backup_creation_error",
+            6,
+            {"target": str(exc.target), "reason": exc.reason},
+        )
+    if isinstance(exc, PermissionError):
+        return (
+            "permission_denied",
+            6,
+            {"path": str(getattr(exc, "filename", "") or ""), "errno": exc.errno or 0},
+        )
+    if isinstance(exc, GitInitError):
+        return (
+            "git_error",
+            7,
+            {"stderr": exc.stderr},
+        )
+    if isinstance(exc, TargetOutsideProjectRootError):
+        return (
+            "filesystem_error",
+            6,
+            {"path": str(exc.target), "errno": 0},
+        )
+    if isinstance(exc, OSError):
+        return (
+            "filesystem_error",
+            6,
+            {"path": str(getattr(exc, "filename", "") or ""), "errno": exc.errno or 0},
+        )
+    return (
+        "filesystem_error",
+        6,
+        {"path": "", "errno": 0},
+    )
+
+
+def build_options_record(resolved: ResolvedInvocation) -> InitOptionsRecord:
+    """Wrap ``resolved`` in a versioned ``InitOptionsRecord``."""
+
+    return InitOptionsRecord(
+        schema_version=SCHEMA_VERSION,
+        created_at=_utc_now_iso_z(),
+        bookwright_version=_BOOKWRIGHT_VERSION,
+        options=resolved,
+    )
+
+
+def serialize_options_record(record: InitOptionsRecord) -> bytes:
+    """Encode an ``InitOptionsRecord`` for the on-disk copy (indent=2 + trailing newline)."""
+
+    payload = record.model_dump(mode="json")
+    return (json.dumps(payload, indent=2, sort_keys=False) + "\n").encode("utf-8")

bookwright/commands/init/git.py

@@ -0,0 +1,96 @@
+"""Thin git subprocess wrapper for ``bookwright init`` (research §R8).
+
+Three helpers: ``git_available()`` (PATH probe), ``is_inside_existing_repo()``
+(walks parents for ``.git/``), and ``init_and_commit(...)`` (runs ``git
+init`` + ``git add .`` + ``git commit -m <message>`` with author env vars
+filled in, and registers the partial ``.git/`` directory with the backup
+ledger so a failed commit rolls back cleanly).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .scaffold import BackupLedger
+
+_FALLBACK_EMAIL = "author@bookwright.local"
+
+
+class GitInitError(Exception):
+    """Raised when ``git init`` or ``git commit`` failed (FR-022)."""
+
+    code = "git_error"
+
+    def __init__(self, *, stderr: str) -> None:
+        self.stderr = stderr
+        super().__init__(stderr.strip() or "git command failed")
+
+
+def git_available() -> bool:
+    """``True`` when a ``git`` binary is on PATH."""
+
+    return shutil.which("git") is not None
+
+
+def is_inside_existing_repo(root: Path) -> bool:
+    """``True`` when ``root`` or any ancestor contains a ``.git`` entry."""
+
+    candidate = root.resolve()
+    while True:
+        if (candidate / ".git").exists():
+            return True
+        if candidate.parent == candidate:
+            return False
+        candidate = candidate.parent
+
+
+def _augmented_env(author_name: str) -> dict[str, str]:
+    """Build an env that forces an identity for the initial commit."""
+
+    env = os.environ.copy()
+    env["GIT_AUTHOR_NAME"] = author_name
+    env["GIT_COMMITTER_NAME"] = author_name
+    env.setdefault("GIT_AUTHOR_EMAIL", _FALLBACK_EMAIL)
+    env.setdefault("GIT_COMMITTER_EMAIL", _FALLBACK_EMAIL)
+    return env
+
+
+def init_and_commit(
+    root: Path,
+    message: str,
+    author_name: str,
+    ledger: BackupLedger,
+) -> None:
+    """Run ``git init`` + ``git add .`` + ``git commit`` inside ``root``.
+
+    Registers ``<root>/.git`` with the ledger before ``git init`` so a
+    commit failure unwinds the partial repository on rollback. Raises
+    ``GitInitError`` on subprocess failure.
+    """
+
+    git_dir = root / ".git"
+    if not git_dir.exists():
+        ledger.record_new_directory(git_dir)
+
+    env = _augmented_env(author_name)
+
+    for argv in (
+        ["git", "init"],
+        ["git", "add", "."],
+        ["git", "commit", "-m", message],
+    ):
+        completed = subprocess.run(
+            argv,
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            check=False,
+            env=env,
+        )
+        if completed.returncode != 0:
+            raise GitInitError(stderr=completed.stderr or completed.stdout)

bookwright/commands/init/main.py

@@ -0,0 +1,263 @@
+"""`bookwright init` — scaffold a new book project.
+
+Owns the Typer signature, the success-path orchestration, and the
+top-level ``try/except/ledger.rollback()`` wrapper. Delegates validation,
+resolution, conflict checks, scaffolding, envelope serialization, and the
+git step to the package's private sibling modules.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+
+from . import conflict, envelope, git, resolve, scaffold, validate
+from .envelope import ResolvedInvocation
+
+_REMOVED_FLAGS: dict[str, str] = {
+    "--ai-skills": ("--ai-skills is no longer accepted; Agent Skills is now the only output mode"),
+    "--ai-commands-dir": (
+        "--ai-commands-dir is no longer accepted; "
+        'for generic, use --integration-options="--skills-dir <path>"'
+    ),
+}
+
+_REMOVED_FLAG_MODERN: dict[str, str] = {
+    "--ai-skills": "(drop the flag; Agent Skills is the only output mode)",
+    "--ai-commands-dir": '--integration-options="--skills-dir <path>"',
+}
+
+_DEPRECATED_AI_WARNING = "bookwright: warning: --ai is deprecated; use --integration instead"
+
+
+def _check_removed_flags(args: list[str], json_output: bool) -> None:
+    """Inspect raw click args for ``--ai-skills`` / ``--ai-commands-dir`` (FR-004)."""
+
+    for raw in args:
+        bare = raw.partition("=")[0] if raw.startswith("--") else raw
+        if bare in _REMOVED_FLAGS:
+            envelope.emit_error(
+                code="removed_flag",
+                message=_REMOVED_FLAGS[bare],
+                details={"flag": bare, "modern": _REMOVED_FLAG_MODERN[bare]},
+                exit_code=2,
+                json_output=json_output,
+                rolled_back=False,
+            )
+
+
+def run(  # noqa: PLR0913, PLR0912, PLR0915 — single Typer entry point; surface is the CLI contract
+    ctx: typer.Context,
+    project_name: str | None = typer.Argument(
+        None, metavar="[PROJECT_NAME]", help="New project directory name (mutex with --here)."
+    ),
+    here: bool = typer.Option(False, "--here", help="Initialise in the current directory."),
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite name collisions under the project root."
+    ),
+    no_git: bool = typer.Option(False, "--no-git", help="Skip the automatic git init + commit."),
+    integration: str = typer.Option(
+        "claude",
+        "--integration",
+        help="Agent integration key (default: claude).",
+    ),
+    integration_options: str = typer.Option(
+        "",
+        "--integration-options",
+        help=(
+            "Quoted POSIX-tokenised options forwarded to the integration "
+            '(e.g., "--skills-dir .cursor/skills").'
+        ),
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit a single JSON document on stdout."
+    ),
+    ai: str | None = typer.Option(
+        None,
+        "--ai",
+        hidden=True,
+        help="Deprecated alias for --integration.",
+    ),
+) -> None:
+    """Scaffold a new Bookwright project."""
+
+    raw_args = list(ctx.args) if ctx.args else []
+    _check_removed_flags(raw_args, json_output=json_output)
+    validate.check_mutex(project_name, here, json_output=json_output)
+
+    # Reconcile --ai with --integration.
+    deprecated_seen: list[str] = []
+    warnings: list[str] = []
+    integration_source = ctx.get_parameter_source("integration")
+    integration_supplied = (
+        integration_source is not None and integration_source.name == "COMMANDLINE"
+    )
+    if ai is not None:
+        deprecated_seen.append("--ai")
+        sys.stderr.write(_DEPRECATED_AI_WARNING + "\n")
+        warnings.append(_DEPRECATED_AI_WARNING)
+        if not integration_supplied:
+            integration = ai
+
+    mode: Literal["named", "here"]
+    if here:
+        project_root = Path.cwd().resolve()
+        basename = project_root.name
+        validate.parse_here_basename(basename, json_output)
+        title = basename
+        project_slug = resolve.parse_named_slug(basename, json_output)
+        mode = "here"
+        cleanup_project_root = False
+    else:
+        assert project_name is not None  # narrowed by mutex check
+        title = validate.parse_named_name(project_name, json_output)
+        project_slug = resolve.parse_named_slug(title, json_output)
+        project_root = (Path.cwd() / project_slug).resolve()
+        mode = "named"
+        cleanup_project_root = not project_root.exists()
+
+    # Conflict matrix BEFORE author/integration resolution (which would touch git).
+    if here:
+        conflict.apply_here_conflict_matrix(project_root, force, json_output=json_output)
+    else:
+        conflict.apply_named_conflict_matrix(project_root, force, json_output=json_output)
+
+    # Resolve every value that can fail BEFORE touching the filesystem (FR-030 / SC-005:
+    # a failure here must leave the parent dir byte-identical, so we cannot mkdir first).
+    # `Path.cwd()` is the right cwd for the git-config probe regardless of mode: in
+    # named mode it equals project_root.parent (which always exists); in here mode it
+    # equals project_root itself. git walks upward in both cases, so the resolved name
+    # is identical to the legacy behaviour of probing inside project_root post-mkdir.
+    authors = resolve.resolve_authors_or_warn(Path.cwd(), warnings)
+    language = resolve.resolve_language()
+    integration_cls, parsed_options = resolve.resolve_integration(
+        integration, integration_options, json_output=json_output
+    )
+    integration_instance = integration_cls()
+    skills_dir = integration_instance.resolve_skills_dir(parsed_options).as_posix()
+
+    git_status: Literal[
+        "initialized",
+        "skipped_by_flag",
+        "skipped_no_binary",
+        "skipped_existing_repo",
+    ]
+    if no_git:
+        git_status = "skipped_by_flag"
+    elif not git.git_available():
+        git_status = "skipped_no_binary"
+    elif git.is_inside_existing_repo(project_root):
+        git_status = "skipped_existing_repo"
+    else:
+        git_status = "initialized"
+
+    try:
+        resolved = ResolvedInvocation(
+            mode=mode,
+            project_name=title if mode == "named" else None,
+            project_slug=project_slug,
+            project_root=project_root.as_posix(),
+            title=title,
+            authors=list(authors),
+            language=language,
+            integration_key=integration,
+            integration_skills_dir=skills_dir,
+            integration_options=dict(parsed_options),
+            no_git=no_git,
+            force=force,
+            json_output=json_output,
+            git_status=git_status,
+            deprecated_flags_seen=list(deprecated_seen),
+        )
+    except ValidationError as exc:
+        first = exc.errors()[0]
+        field = ".".join(str(part) for part in first.get("loc", ()))
+        envelope.emit_error(
+            code="malformed_option",
+            message=f"invalid {field}: {first.get('msg', str(exc))}",
+            details={
+                "field": field,
+                "value": str(first.get("input", "")),
+                "rule": first.get("type", "value_error"),
+            },
+            exit_code=5,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+    if not project_root.exists():
+        try:
+            project_root.mkdir(parents=True, exist_ok=False)
+        except PermissionError as exc:
+            envelope.emit_error(
+                code="permission_denied",
+                message=f"could not create {project_root}: {exc}",
+                details={"path": str(project_root), "errno": exc.errno or 0},
+                exit_code=6,
+                json_output=json_output,
+                rolled_back=False,
+            )
+        except OSError as exc:
+            envelope.emit_error(
+                code="filesystem_error",
+                message=f"could not create {project_root}: {exc}",
+                details={"path": str(project_root), "errno": exc.errno or 0},
+                exit_code=6,
+                json_output=json_output,
+                rolled_back=False,
+            )
+
+    ledger = conflict.seed_backup_ledger(project_root, cleanup_project_root)
+
+    def _rollback_and_cleanup() -> None:
+        ledger.rollback()
+        if cleanup_project_root and project_root.exists():
+            import shutil  # noqa: PLC0415 — local cleanup only
+
+            shutil.rmtree(project_root, ignore_errors=True)
+
+    try:
+        scaffold.run_scaffold_steps(
+            resolved=resolved,
+            integration=integration_instance,
+            parsed_options=parsed_options,
+            ledger=ledger,
+            warnings=warnings,
+            author_name=authors[0],
+        )
+    except (KeyboardInterrupt, SystemExit):
+        # Signal-like interruptions: roll back the partial scaffold and re-raise
+        # without writing an envelope, so the user sees the original signal.
+        _rollback_and_cleanup()
+        raise
+    except Exception as exc:
+        _rollback_and_cleanup()
+        if isinstance(exc, typer.Exit):
+            raise
+        envelope.emit_scaffold_failure(exc, json_output=json_output)
+
+    ledger.commit()
+
+    if json_output:
+        payload = envelope.success_envelope(resolved, warnings)
+        envelope.dump_success_to_stdout(payload)
+    else:
+        Console(stderr=True, highlight=False, soft_wrap=True).print(
+            f"bookwright: created [bold]{project_root}[/bold] "
+            f"(integration={resolved.integration_key}, "
+            f"git={resolved.git_status})"
+        )
+
+    raise typer.Exit(0)
+
+
+CONTEXT_SETTINGS: dict[str, Any] = {
+    "allow_extra_args": True,
+    "ignore_unknown_options": True,
+}
+"""Click context settings expected by ``cli.py`` when wiring the command."""