bookwright-cli 0.2.0__py3-none-any.whl

bookwright/commands/init/resolve.py

@@ -0,0 +1,193 @@
+"""Resolution helpers consumed by ``init.run`` (research §R1, §R2, §R3, §R7).
+
+Each helper is one source of truth so the orchestrator never needs to
+re-derive the values. Tests monkeypatch a single symbol per behaviour.
+"""
+
+from __future__ import annotations
+
+import locale
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from slugify import slugify
+
+from bookwright import integrations as _integrations
+from bookwright.core.iso639_1 import ISO_639_1_CODES
+
+from .envelope import emit_error
+from .validate import (
+    InvalidProjectNameError,
+    check_slug_not_reserved,
+)
+
+AUTHOR_SENTINEL = "Unknown Author"
+DEFAULT_LANGUAGE = "es"
+
+AUTHOR_FALLBACK_WARNING = (
+    "bookwright: warning: author could not be resolved from git config or $USER; "
+    "using 'Unknown Author'"
+)
+
+
+def _git_config_user_name(cwd: Path) -> str | None:
+    """Read ``git config --get user.name`` scoped to ``cwd``.
+
+    Returns the trimmed value, or ``None`` if git is missing, the lookup
+    failed, or the value is empty.
+    """
+
+    try:
+        completed = subprocess.run(
+            ["git", "config", "--get", "user.name"],
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return None
+    if completed.returncode != 0:
+        return None
+    candidate = completed.stdout.strip()
+    return candidate or None
+
+
+def resolve_authors(project_root: Path) -> tuple[list[str], bool]:
+    """Resolve ``book.authors`` per FR-016 / research §R1.
+
+    Returns ``(authors, fellback_to_sentinel)``. ``project_root`` is the
+    directory used as ``cwd`` for the ``git config`` probe (the project
+    parent in ``named`` mode is fine — git walks upward). Always returns
+    a non-empty list.
+    """
+
+    candidate = _git_config_user_name(project_root)
+    if candidate:
+        return [candidate], False
+
+    env_user = os.environ.get("USER", "").strip()
+    if env_user:
+        return [env_user], False
+
+    return [AUTHOR_SENTINEL], True
+
+
+def resolve_language() -> str:
+    """Resolve ``book.language`` per FR-018 / research §R2.
+
+    Reads ``locale.getlocale()`` (no ``setlocale`` mutation), takes the
+    two-letter prefix, lower-cases it, and validates against
+    ``ISO_639_1_CODES``. Falls back silently to ``"es"`` on any failure.
+    """
+
+    try:
+        lang, _encoding = locale.getlocale()
+    except (ValueError, TypeError):
+        return DEFAULT_LANGUAGE
+    if not lang:
+        return DEFAULT_LANGUAGE
+    prefix = lang[:2].lower()
+    if prefix in ISO_639_1_CODES:
+        return prefix
+    return DEFAULT_LANGUAGE
+
+
+def derive_slug(raw_name: str) -> str:
+    """Slugify ``raw_name`` per FR-021 / research §R3.
+
+    Uses ``python-slugify`` with the documented settings. Re-checks the
+    slug against the FR-021a reserved-name list so a name that slugifies
+    to ``"con"`` still trips.
+    """
+
+    slug = slugify(
+        raw_name,
+        lowercase=True,
+        separator="-",
+        allow_unicode=False,
+        regex_pattern=r"[^A-Za-z0-9]+",
+    )
+    if not slug:
+        raise InvalidProjectNameError(value=raw_name, rule="empty")
+    return check_slug_not_reserved(slug)
+
+
+def is_interactive() -> bool:
+    """``True`` when stdin AND stdout are both TTYs (research §R7)."""
+
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def parse_named_slug(name: str, json_output: bool) -> str:
+    """Run ``derive_slug`` and translate failures to an envelope."""
+
+    try:
+        return derive_slug(name)
+    except InvalidProjectNameError as exc:
+        emit_error(
+            code=exc.code,
+            message=str(exc),
+            details=exc.details or {},
+            exit_code=2,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+
+def resolve_authors_or_warn(
+    project_root: Path,
+    warnings: list[str],
+) -> list[str]:
+    """Resolve authors and emit the FR-016 fallback warning on stderr if used.
+
+    Per contract §5 the warning goes to stderr regardless of ``--json``; the
+    JSON envelope mirrors it via the ``warnings`` list on the success path.
+    """
+
+    authors, fellback = resolve_authors(project_root)
+    if fellback:
+        warnings.append(AUTHOR_FALLBACK_WARNING)
+        sys.stderr.write(AUTHOR_FALLBACK_WARNING + "\n")
+    return authors
+
+
+def resolve_integration(
+    key: str,
+    raw_options: str,
+    *,
+    json_output: bool,
+) -> tuple[type[_integrations.SkillsIntegration], dict[str, str | bool]]:
+    """Look up the integration class and parse its options, emitting on failure."""
+
+    try:
+        integration_cls = _integrations.get(key)
+    except _integrations.UnknownIntegrationError as exc:
+        emit_error(
+            code=exc.code,
+            message=exc.message,
+            details=exc.details or {},
+            exit_code=5,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+    try:
+        parsed_options = _integrations.parse_options(raw_options, integration_cls)
+    except (
+        _integrations.UnknownOptionError,
+        _integrations.MalformedOptionError,
+        _integrations.InvalidOptionDeclarationError,
+    ) as exc:
+        emit_error(
+            code=exc.code,
+            message=exc.message,
+            details=exc.details or {},
+            exit_code=5,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+    return integration_cls, parsed_options

bookwright/commands/init/scaffold.py

@@ -0,0 +1,242 @@
+"""Manifest writer + template walker + orchestration for ``bookwright init``.
+
+The atomic-or-nothing rollback ledger and the tracked fs primitives now live in
+the shared :mod:`bookwright.io.fs` module (extracted in iteration 9 so the skills
+materializer can record through the same ledger). They are re-exported here for
+backward compatibility with the ``init`` package's importers. The template walker
+drives Jinja2 over packaged resources (research §R9).
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib.resources import as_file, files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import jinja2
+
+from bookwright import integrations as _integrations
+from bookwright.core.manifest import Manifest
+from bookwright.io.fs import (
+    BackupCreationError,
+    BackupLedger,
+    TargetOutsideProjectRootError,
+    _register_target,
+    mkdir_tracked,
+    write_bytes_atomic,
+)
+
+from . import envelope, git
+
+if TYPE_CHECKING:
+    from .envelope import ResolvedInvocation
+
+# Re-exported from io.fs for the init package's importers (envelope, git,
+# conflict) and the resource-render tests. Listed in __all__ so linters do not
+# flag the re-exports as unused.
+__all__ = [
+    "COMMIT_MESSAGE",
+    "GIT_EXISTING_WARNING",
+    "GIT_MISSING_WARNING",
+    "BackupCreationError",
+    "BackupLedger",
+    "TargetOutsideProjectRootError",
+    "copy_resource_file",
+    "dump_manifest_tracked",
+    "mkdir_tracked",
+    "render_resource_tree",
+    "run_scaffold_steps",
+    "write_bytes_atomic",
+]
+
+COMMIT_MESSAGE = "Initial commit from bookwright init"
+
+GIT_MISSING_WARNING = (
+    "bookwright: warning: git not found on PATH; project created without a repository"
+)
+GIT_EXISTING_WARNING = "bookwright: warning: existing .git/ detected; skipped git init and commit"
+
+
+def dump_manifest_tracked(manifest: Manifest, target: Path, ledger: BackupLedger) -> None:
+    """Register ``target`` with the ledger, then delegate to ``Manifest.dump``.
+
+    Keeps ``Manifest.dump`` as the sole TOML writer (FR-015) while still
+    participating the write in the backup ledger (FR-030).
+    """
+
+    _register_target(target, ledger)
+    manifest.dump(target, overwrite=target.exists())
+
+
+_J2_SUFFIX = ".j2"
+_RESOURCE_PACKAGE = "bookwright.resources.project"
+
+
+def _iter_resource_files(root: Traversable) -> list[tuple[str, Traversable]]:
+    """Walk a ``Traversable`` resource tree, yielding ``(rel_posix, node)``.
+
+    ``rel_posix`` uses ``/`` separators and is relative to ``root``. The
+    ``__init__.py`` marker file is filtered out — it is implementation
+    detail of the package layout, not part of the project template.
+    """
+
+    results: list[tuple[str, Traversable]] = []
+
+    def _walk(node: Traversable, prefix: str) -> None:
+        for child in node.iterdir():
+            name = child.name
+            if name == "__pycache__":
+                continue
+            if prefix == "" and name == "__init__.py":
+                continue
+            rel = f"{prefix}{name}" if prefix == "" else f"{prefix}/{name}"
+            if child.is_dir():
+                _walk(child, rel)
+            else:
+                results.append((rel, child))
+
+    _walk(root, "")
+    return results
+
+
+def _target_relpath(rel: str) -> Path:
+    """Drop the ``.j2`` suffix when present; preserve directory layout."""
+
+    return Path(rel[: -len(_J2_SUFFIX)]) if rel.endswith(_J2_SUFFIX) else Path(rel)
+
+
+def render_resource_tree(
+    target_root: Path,
+    context: dict[str, Any],
+    ledger: BackupLedger,
+) -> None:
+    """Walk ``bookwright.resources.project`` and render it into ``target_root``.
+
+    ``.j2`` files go through one shared Jinja2 environment with strict
+    undefined; everything else is byte-copied. Empty directories are
+    preserved via ``.gitkeep`` resources.
+    """
+
+    env = jinja2.Environment(
+        loader=jinja2.PackageLoader(_RESOURCE_PACKAGE, ""),
+        autoescape=False,
+        keep_trailing_newline=True,
+        undefined=jinja2.StrictUndefined,
+    )
+
+    package_root = files(_RESOURCE_PACKAGE)
+    entries = _iter_resource_files(package_root)
+
+    for rel, node in sorted(entries, key=lambda item: item[0]):
+        target = target_root / _target_relpath(rel)
+        mkdir_tracked(target.parent, ledger)
+
+        if rel.endswith(_J2_SUFFIX):
+            template = env.get_template(rel)
+            rendered = template.render(**context)
+            write_bytes_atomic(target, rendered.encode("utf-8"), ledger)
+            continue
+
+        with as_file(node) as src:
+            payload = Path(src).read_bytes()
+        write_bytes_atomic(target, payload, ledger)
+
+
+def copy_resource_file(
+    package: str,
+    name: str,
+    target: Path,
+    ledger: BackupLedger,
+) -> None:
+    """Copy a single packaged resource file to ``target`` through the ledger."""
+
+    node = files(package).joinpath(name)
+    with as_file(node) as src:
+        payload = Path(src).read_bytes()
+    write_bytes_atomic(target, payload, ledger)
+
+
+def run_scaffold_steps(  # noqa: PLR0913 — orchestrator: gathers every previously-resolved input in one call
+    *,
+    resolved: ResolvedInvocation,
+    integration: _integrations.SkillsIntegration,
+    parsed_options: dict[str, str | bool],
+    ledger: BackupLedger,
+    warnings: list[str],
+    author_name: str,
+) -> None:
+    """All filesystem mutations + integration setup + git step.
+
+    The orchestrator behind ``bookwright init``'s success path: renders
+    the packaged template tree, dumps the manifest, copies vocabularies,
+    runs the integration's ``setup()`` and finally ``git init + commit``
+    when applicable. The ``git_status`` on ``resolved`` is settled by
+    ``main.run`` before this function is called.
+    """
+
+    project_root = Path(resolved.project_root)
+
+    template_context = {
+        "title": resolved.title,
+        "project_slug": resolved.project_slug,
+        "author": resolved.authors[0],
+        "language": resolved.language,
+        "integration_key": resolved.integration_key,
+    }
+
+    # 1) Render the packaged template tree.
+    render_resource_tree(project_root, template_context, ledger)
+
+    # 2) Build and dump the manifest.
+    manifest = Manifest.build(
+        title=resolved.title,
+        authors=list(resolved.authors),
+        integration_key=resolved.integration_key,
+        integration_skills_dir=resolved.integration_skills_dir,
+        integration_options=dict(parsed_options),
+        language=resolved.language,
+        type="novel",
+        status="idea",
+        uri_base=f"https://example.org/{resolved.project_slug}/",
+    )
+    dump_manifest_tracked(manifest, project_root / "manifest.toml", ledger)
+
+    # 3) Copy bundled vocabularies into .bookwright/vocabularies/.
+    vocab_target = project_root / ".bookwright" / "vocabularies"
+    mkdir_tracked(vocab_target, ledger)
+    for vocab in ("propp.ttl", "greimas.ttl"):
+        copy_resource_file(
+            "bookwright.resources.vocabularies",
+            vocab,
+            vocab_target / vocab,
+            ledger,
+        )
+
+    # 4) Wire the integration's setup() through the ledger. The materializer
+    # records every directory and file it creates via this live BackupLedger, so
+    # a failed init unwinds all materialized skills — including over a pre-existing
+    # skills_dir (FR-019/SC-008). setup() resolves + mkdir_tracked's the target.
+    integration.setup(project_root, manifest, parsed_options, ledger=ledger)
+
+    # 5) Write the init-options record (git_status already settled by main.run).
+    record = envelope.build_options_record(resolved)
+    options_payload = envelope.serialize_options_record(record)
+    write_bytes_atomic(
+        project_root / ".bookwright" / "init-options.json",
+        options_payload,
+        ledger,
+    )
+
+    # 6) Run git init + commit if applicable. Warnings go to stderr regardless
+    # of ``--json`` (contract §5); the JSON envelope mirrors them via the
+    # ``warnings`` list on the success path.
+    if resolved.git_status == "initialized":
+        git.init_and_commit(project_root, COMMIT_MESSAGE, author_name, ledger)
+    elif resolved.git_status == "skipped_existing_repo":
+        warnings.append(GIT_EXISTING_WARNING)
+        sys.stderr.write(GIT_EXISTING_WARNING + "\n")
+    elif resolved.git_status == "skipped_no_binary":
+        warnings.append(GIT_MISSING_WARNING)
+        sys.stderr.write(GIT_MISSING_WARNING + "\n")

bookwright/commands/init/validate.py

@@ -0,0 +1,172 @@
+"""FR-021a ``PROJECT_NAME`` validation.
+
+Pure functions only; no filesystem side-effects. Surfaces structured
+``InvalidProjectNameError`` so the caller can branch on ``rule`` instead of
+prose. Rules per research §R3 and contract §4.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from bookwright.errors import BookwrightError
+
+from .envelope import emit_error
+
+ProjectNameRule = Literal[
+    "empty",
+    "path_separator",
+    "dot_or_dotdot",
+    "leading_dot",
+    "too_long",
+    "reserved_name",
+]
+
+_MAX_LENGTH = 100
+
+_WINDOWS_RESERVED: frozenset[str] = frozenset(
+    {
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        *(f"COM{i}" for i in range(1, 10)),
+        *(f"LPT{i}" for i in range(1, 10)),
+    }
+)
+
+
+class InvalidProjectNameError(BookwrightError):
+    """Raised when ``PROJECT_NAME`` violates one of the FR-021a rules."""
+
+    code = "invalid_project_name"
+
+    def __init__(self, *, value: str, rule: ProjectNameRule) -> None:
+        self.value = value
+        self.rule = rule
+        super().__init__(
+            f"invalid project name {value!r}; rule: {rule}",
+            {"value": value, "rule": rule},
+        )
+
+
+def _is_reserved(candidate: str) -> bool:
+    return candidate.upper() in _WINDOWS_RESERVED
+
+
+def validate_project_name(value: str) -> str:
+    """Validate and normalise a raw ``PROJECT_NAME``.
+
+    Returns the value with leading/trailing whitespace stripped. Raises
+    ``InvalidProjectNameError`` on any rule violation. The check order is
+    fixed: empty → path_separator → dot_or_dotdot → leading_dot → too_long
+    → reserved_name. The first failing rule wins (so ``"."`` is
+    ``dot_or_dotdot``, not ``leading_dot``).
+    """
+
+    stripped = value.strip()
+    if not stripped:
+        raise InvalidProjectNameError(value=value, rule="empty")
+    if "/" in stripped or "\\" in stripped:
+        raise InvalidProjectNameError(value=stripped, rule="path_separator")
+    if stripped in {".", ".."}:
+        raise InvalidProjectNameError(value=stripped, rule="dot_or_dotdot")
+    if stripped.startswith("."):
+        raise InvalidProjectNameError(value=stripped, rule="leading_dot")
+    if len(stripped) > _MAX_LENGTH:
+        raise InvalidProjectNameError(value=stripped, rule="too_long")
+    if _is_reserved(stripped):
+        raise InvalidProjectNameError(value=stripped, rule="reserved_name")
+    return stripped
+
+
+def check_slug_not_reserved(slug: str) -> str:
+    """Re-check a slug against the reserved-name list (R3).
+
+    Same exception family so callers can fold both checks into one
+    error envelope.
+    """
+
+    if not slug:
+        raise InvalidProjectNameError(value=slug, rule="empty")
+    if _is_reserved(slug):
+        raise InvalidProjectNameError(value=slug, rule="reserved_name")
+    return slug
+
+
+def check_mutex(project_name: str | None, here: bool, *, json_output: bool) -> None:
+    """FR-002 — exactly one of ``PROJECT_NAME`` / ``--here`` is required.
+
+    Emits a ``mutually_exclusive`` envelope and exits with code 2 on
+    violation.
+    """
+
+    if project_name is not None and here:
+        emit_error(
+            code="mutually_exclusive",
+            message="PROJECT_NAME and --here are mutually exclusive",
+            details={},
+            exit_code=2,
+            json_output=json_output,
+            rolled_back=False,
+        )
+    if project_name is None and not here:
+        emit_error(
+            code="mutually_exclusive",
+            message="must specify PROJECT_NAME or --here",
+            details={},
+            exit_code=2,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+
+def parse_named_name(value: str, json_output: bool) -> str:
+    """Run ``validate_project_name`` and translate failures to an envelope."""
+
+    try:
+        return validate_project_name(value)
+    except InvalidProjectNameError as exc:
+        emit_error(
+            code=exc.code,
+            message=str(exc),
+            details=exc.details or {},
+            exit_code=2,
+            json_output=json_output,
+            rolled_back=False,
+        )
+
+
+def parse_here_basename(basename: str, json_output: bool) -> str:
+    """Reduced FR-021a check for ``--here``: empty / path-separator / reserved only."""
+
+    if not basename.strip():
+        emit_error(
+            code="invalid_project_name",
+            message="current directory basename is empty",
+            details={"value": basename, "rule": "empty"},
+            exit_code=2,
+            json_output=json_output,
+            rolled_back=False,
+        )
+    if "/" in basename or "\\" in basename:
+        emit_error(
+            code="invalid_project_name",
+            message=f"current directory basename {basename!r} contains a path separator",
+            details={"value": basename, "rule": "path_separator"},
+            exit_code=2,
+            json_output=json_output,
+            rolled_back=False,
+        )
+    try:
+        check_slug_not_reserved(basename)
+    except InvalidProjectNameError as exc:
+        emit_error(
+            code=exc.code,
+            message=str(exc),
+            details=exc.details or {},
+            exit_code=2,
+            json_output=json_output,
+            rolled_back=False,
+        )
+    return basename

bookwright/commands/integration/__init__.py

@@ -0,0 +1,22 @@
+"""The ``bookwright integration`` Typer sub-app.
+
+Manages a project's active agent integration. ``use`` lives in its own module
+(Principle IV) and registers its callback here. Wired into the root CLI in
+:mod:`bookwright.cli` via ``app.add_typer(integration.app, name="integration")``.
+"""
+
+from __future__ import annotations
+
+import typer
+
+app = typer.Typer(
+    name="integration",
+    help="Manage the project's agent integration (re-materialize skills).",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# `use` registers its callback on `app` at import time; importing it here keeps
+# the sub-app self-contained. The `as` redirect marks the import as an
+# intentional re-export (registration side effect).
+from . import use as use  # noqa: E402