bookwright-cli 0.2.0__py3-none-any.whl

bookwright/integrations/generic/__init__.py

@@ -0,0 +1,56 @@
+"""``GenericIntegration`` — neutral agentskills.io layout (FR-008, FR-010, FR-014, FR-024)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import ClassVar
+
+from bookwright.integrations.base import SkillsIntegration
+from bookwright.integrations.options import IntegrationOption
+
+
+class GenericIntegration(SkillsIntegration):
+    """Integration for any agentskills.io-compliant agent (Codex CLI, Cursor, ...).
+
+    Declares one option (``--skills-dir``) so the user can re-target the
+    skills layout (e.g., ``.cursor/skills``) without writing a dedicated
+    integration class.
+    """
+
+    key: ClassVar[str] = "generic"
+    default_skills_dir: ClassVar[str] = ".agents/skills"
+    # FR-008: `context_file` MUST NOT be present in the generic config.
+    config: ClassVar[dict[str, str | bool]] = {
+        "name": "Generic (Agent Skills standard)",
+        "install_url": "https://agentskills.io",
+        "requires_cli": False,
+    }
+
+    supports_dynamic_context: ClassVar[bool] = False
+    supports_subagents: ClassVar[bool] = False
+    supports_tool_restrictions: ClassVar[bool] = False
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                flag="--skills-dir",
+                type="string",
+                required=False,
+                default=".agents/skills",
+                help=(
+                    "Directory where SKILL.md files are materialized. "
+                    "Default: .agents/skills (Codex/Cursor convention). "
+                    "Common alternatives: .cursor/skills, .github/skills."
+                ),
+            ),
+        ]
+
+    def resolve_skills_dir(
+        self,
+        parsed_options: Mapping[str, object] | None = None,
+    ) -> Path:
+        if parsed_options and "skills_dir" in parsed_options:
+            return Path(str(parsed_options["skills_dir"]))
+        return Path(self.default_skills_dir)

bookwright/integrations/lint.py

@@ -0,0 +1,160 @@
+"""Ad-hoc agentskills.io linter for a materialized skill directory (FR-015).
+
+``lint_skill_md`` enforces the agentskills.io invariants on one
+``<skills_dir>/<command>/SKILL.md`` and raises :class:`SkillLintError` on the
+**first** violation (Principle VII — fail loudly, never silently truncate or
+auto-fix). It is pure: it reads the file, it never mutates the filesystem.
+
+The full validation system is iteration 11; this module is the minimum gate
+needed for Principle VII (and is reused by that later system).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import shlex
+from pathlib import Path
+
+from bookwright.integrations.constants import (
+    INJECTION_READ_COMMANDS,
+    SKILL_BODY_MAX_TOKENS,
+    SKILL_DESCRIPTION_MAX_LENGTH,
+    SKILL_NAME_MAX_LENGTH,
+)
+from bookwright.integrations.errors import SkillLintError
+from bookwright.io.frontmatter import parse_frontmatter
+
+#: Matches a `` !`<cmd>` `` dynamic-context injection in a skill body.
+_INJECTION = re.compile(r"!`([^`]*)`")
+
+
+def approx_tokens(text: str) -> int:
+    """Token estimate for the Tier-2 body budget (R6).
+
+    Deterministic ``ceil(len / 4)`` char heuristic — the *same* definition of
+    "token" as the iteration-8 source-side authoring gate, so a body that passed
+    iteration 8 passes here, and the verdict never depends on which packages
+    happen to be installed. The budget is a 5x-margin regression guard, not an
+    authoring constraint, so the precision of a real tokenizer buys nothing here;
+    if iteration 11 needs exact counts it can introduce one where justified.
+    """
+
+    return math.ceil(len(text) / 4)
+
+
+def _check_injections(skill_name: str, body: str) -> None:
+    """Rule 5 — deny-by-default allowlist for `` !`…` `` injections (FR-013).
+
+    Enumerate the only two valid shapes and reject everything else:
+      - ``argv[0] == "bookwright"`` (the stable SKILL.md ↔ CLI contract), or
+      - ``argv[0]`` in :data:`INJECTION_READ_COMMANDS` AND no argument is an
+        absolute (``/``) or home-relative (``~``) path.
+
+    Pure/read-only — the invariant is about the *shape* of the injection, never
+    whether the target currently exists on disk.
+    """
+
+    for match in _INJECTION.finditer(body):
+        cmd = match.group(1)
+        try:
+            argv = shlex.split(cmd)
+        except ValueError as exc:
+            # Unbalanced quotes etc. — surface as a structured lint failure
+            # rather than letting shlex's ValueError escape the JSON envelope
+            # (Principle IX). lint_skill_md is user-edit-facing.
+            raise SkillLintError(
+                skill=skill_name,
+                rule="forbidden_injection",
+                detail=f"unparseable dynamic-context injection {cmd!r}: {exc}",
+            ) from exc
+        if not argv:
+            raise SkillLintError(
+                skill=skill_name,
+                rule="forbidden_injection",
+                detail=f"empty dynamic-context injection: {cmd!r}",
+            )
+        if argv[0] == "bookwright":
+            continue
+        if argv[0] in INJECTION_READ_COMMANDS:
+            bad = [a for a in argv[1:] if a.startswith("/") or a.startswith("~")]
+            if bad:
+                raise SkillLintError(
+                    skill=skill_name,
+                    rule="forbidden_injection",
+                    detail=f"read command targets a non-project path: {bad!r} in {cmd!r}",
+                )
+            continue
+        raise SkillLintError(
+            skill=skill_name,
+            rule="forbidden_injection",
+            detail=f"injection invokes a non-allowlisted executable: {argv[0]!r} in {cmd!r}",
+        )
+
+
+def lint_skill_md(skill_dir: Path) -> None:
+    """Validate one materialized skill dir against the agentskills.io spec.
+
+    Raises :class:`SkillLintError` (``rule`` + ``detail``) on the FIRST violation.
+    Returns ``None`` when compliant. Pure read-only; never mutates the filesystem.
+    """
+
+    skill_name = skill_dir.name
+    skill_md = skill_dir / "SKILL.md"
+
+    # Rule 1 — invalid_frontmatter: SKILL.md exists, valid YAML fence, non-empty metadata.
+    if not skill_md.is_file():
+        raise SkillLintError(
+            skill=skill_name,
+            rule="invalid_frontmatter",
+            detail=f"missing SKILL.md at {skill_md}",
+        )
+    parsed = parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+    metadata = parsed.metadata
+    if not metadata:
+        raise SkillLintError(
+            skill=skill_name,
+            rule="invalid_frontmatter",
+            detail="empty or unparseable frontmatter metadata",
+        )
+
+    # Rule 2 — name_mismatch: metadata["name"] == dir and < SKILL_NAME_MAX_LENGTH.
+    # Once name == skill_name is established, the length check is on the (always
+    # non-empty) directory name, so no separate type/lower-bound guard is needed.
+    name = metadata.get("name")
+    if name != skill_name:
+        raise SkillLintError(
+            skill=skill_name,
+            rule="name_mismatch",
+            detail=f"frontmatter name {name!r} != directory {skill_name!r}",
+        )
+    if len(skill_name) >= SKILL_NAME_MAX_LENGTH:
+        raise SkillLintError(
+            skill=skill_name,
+            rule="name_mismatch",
+            detail=f"name length {len(skill_name)} not below {SKILL_NAME_MAX_LENGTH}",
+        )
+
+    # Rule 3 — description_too_long: 0 < len(description) < SKILL_DESCRIPTION_MAX_LENGTH.
+    description = metadata.get("description")
+    if not isinstance(description, str) or not (
+        0 < len(description) < SKILL_DESCRIPTION_MAX_LENGTH
+    ):
+        length = len(description) if isinstance(description, str) else None
+        raise SkillLintError(
+            skill=skill_name,
+            rule="description_too_long",
+            detail=f"len={length} not in (0, {SKILL_DESCRIPTION_MAX_LENGTH})",
+        )
+
+    # Rule 4 — body_over_budget: approx_tokens(body) < SKILL_BODY_MAX_TOKENS.
+    tokens = approx_tokens(parsed.body)
+    if tokens >= SKILL_BODY_MAX_TOKENS:
+        raise SkillLintError(
+            skill=skill_name,
+            rule="body_over_budget",
+            detail=f"approx_tokens={tokens} >= {SKILL_BODY_MAX_TOKENS}",
+        )
+
+    # Rule 5 — forbidden_injection: deny-by-default allowlist (FR-013).
+    _check_injections(skill_name, parsed.body)

bookwright/integrations/materialize.py

@@ -0,0 +1,202 @@
+"""Shared ``SKILL.md`` materializer (FR-001..FR-020).
+
+``generate_skill_md`` turns one packaged source command into a per-skill
+directory ``<skills_dir>/<command>/SKILL.md`` with authoritative frontmatter, the
+source body (only ``{ARGS}`` → ``$ARGUMENTS`` substituted), and its cited
+``references/`` copied alongside — then lints the result. All *authoring*
+validation runs strictly **before** the first filesystem write, so a rejected
+source leaves zero on-disk state; a lint failure is the only post-write error and
+deletes its own half-written dir.
+
+Every directory and file it creates is recorded through a ``FileLedger`` so
+``init`` can roll the whole materialization back (FR-019), even over a
+pre-existing ``skills_dir``.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+import bookwright
+from bookwright.integrations.constants import DEFAULT_SKILL_LICENSE
+from bookwright.integrations.descriptions import get_description
+from bookwright.integrations.errors import SkillMaterializationError
+from bookwright.integrations.lint import lint_skill_md
+from bookwright.io.frontmatter import parse_frontmatter
+from bookwright.io.fs import mkdir_tracked, write_bytes_atomic
+
+if TYPE_CHECKING:
+    from bookwright.integrations.base import SkillsIntegration
+    from bookwright.io.fs import FileLedger
+
+#: Matches a ``references/<file>.md`` citation anywhere in a source body.
+_REFERENCE_CITATION = re.compile(r"references/([\w-]+)\.md")
+
+#: Tokens that MUST NOT survive the body transform (SC-003).
+_RESIDUAL_TOKENS = ("{ARGS}", "{SCRIPT}")
+
+
+def iter_command_sources() -> list[Traversable]:
+    """Yield the packaged source command ``*.md`` (excludes ``references/``, R4).
+
+    Enumerates the top level of ``bookwright.resources.commands`` — the whole
+    resources tree is force-included in the wheel, so this survives both editable
+    and wheel installs.
+    """
+
+    commands = files("bookwright.resources").joinpath("commands")
+    return sorted(
+        (child for child in commands.iterdir() if child.is_file() and child.name.endswith(".md")),
+        key=lambda node: node.name,
+    )
+
+
+def _transform_body(skill_name: str, body: str) -> str:
+    """Substitute the sole ``{ARGS}`` token; reject any residual token (SC-003).
+
+    Raises ``SkillMaterializationError`` (``residual_token``) rather than asserting,
+    so the fail-loud guarantee survives ``python -O`` (which strips ``assert``).
+    Pre-write, so a rejected source still leaves zero on-disk state.
+    """
+
+    transformed = body.replace("{ARGS}", "$ARGUMENTS")
+    for token in _RESIDUAL_TOKENS:
+        if token in transformed:
+            raise SkillMaterializationError(
+                skill=skill_name,
+                rule="residual_token",
+                detail=f"residual token {token!r} survived body transform",
+            )
+    return transformed
+
+
+def _render_frontmatter(name: str, description: str, license_: str, version: str) -> str:
+    """Render ordered ``name``/``description``/``license``/``metadata`` YAML frontmatter."""
+
+    document: dict[str, object] = {
+        "name": name,
+        "description": description,
+        "license": license_,
+        "metadata": {"author": "bookwright", "version": version},
+    }
+    block = yaml.safe_dump(document, allow_unicode=True, sort_keys=False)
+    return f"---\n{block}---\n"
+
+
+def _resolve_references(skill_name: str, body: str) -> list[tuple[str, Traversable]]:
+    """Resolve each distinct ``references/<file>.md`` cited in ``body`` (pure, no writes).
+
+    A citation with no matching packaged source raises ``SkillMaterializationError``
+    (``dangling_reference``) — before any directory is created. Returns the resolved
+    ``(filename, source_node)`` copy-list consumed by :func:`_copy_references`.
+
+    ``skill_name`` is the citing command's name, carried onto the error so the JSON
+    envelope's ``skill`` field identifies the skill (not the missing reference file).
+    """
+
+    refs_root = files("bookwright.resources").joinpath("commands").joinpath("references")
+    seen: dict[str, Traversable] = {}
+    for match in _REFERENCE_CITATION.finditer(body):
+        filename = f"{match.group(1)}.md"
+        if filename in seen:
+            continue
+        node = refs_root.joinpath(filename)
+        if not node.is_file():
+            raise SkillMaterializationError(
+                skill=skill_name,
+                rule="dangling_reference",
+                detail=f"cited reference {filename!r} has no packaged source",
+            )
+        seen[filename] = node
+    return list(seen.items())
+
+
+def _copy_references(
+    skill_dir: Path,
+    copy_list: list[tuple[str, Traversable]],
+    ledger: FileLedger,
+) -> None:
+    """Write the already-resolved reference copy-list into ``skill_dir/references/``."""
+
+    if not copy_list:
+        return
+    refs_target = skill_dir / "references"
+    mkdir_tracked(refs_target, ledger)
+    for filename, node in copy_list:
+        write_bytes_atomic(refs_target / filename, node.read_bytes(), ledger)
+
+
+def generate_skill_md(
+    command_path: Traversable | Path,
+    target_dir: Path,
+    integration: SkillsIntegration,
+    *,
+    ledger: FileLedger,
+) -> Path | None:
+    """Materialize one source command into a per-skill directory.
+
+    Returns the written ``SKILL.md`` path, or ``None`` if the skill already
+    existed (idempotency skip). Raises ``SkillLintError`` on a lint failure (after
+    removing the half-written skill dir). Raises ``SkillMaterializationError`` on a
+    dangling reference or a frontmatter ``name`` ≠ filename-stem mismatch.
+    """
+
+    # `integration` is read structurally in v0 only via the shared roster; its
+    # `supports_dynamic_context` flag is intentionally NOT acted on (FR-011).
+    del integration
+
+    name = Path(command_path.name).stem
+    skill_dir = target_dir / name
+
+    # Step 2 — idempotency (FR-014): never overwrite an existing skill.
+    if (skill_dir / "SKILL.md").exists():
+        return None
+
+    source_text = command_path.read_text(encoding="utf-8")
+    parsed = parse_frontmatter(source_text)
+
+    # Step 1 — authoring invariant (FR-020): frontmatter name == filename stem.
+    fm_name = parsed.metadata.get("name")
+    if fm_name != name:
+        raise SkillMaterializationError(
+            skill=name,
+            rule="name_frontmatter_mismatch",
+            detail=f"frontmatter name {fm_name!r} != filename stem {name!r}",
+        )
+
+    # Step 3 — authoritative description (R3, FR-004). The 1024-char cap is owned
+    # by get_description and re-enforced loudly by lint_skill_md's Rule 3 below.
+    description = get_description(name, parsed.metadata.get("description", ""))
+
+    # Step 4 — body transform (sole token substitution).
+    body = _transform_body(name, parsed.body)
+
+    # Step 5 — resolve cited references (pure; a dangling ref aborts pre-write).
+    copy_list = _resolve_references(name, body)
+
+    # Step 6 — frontmatter (honour a source-declared license, else the design default).
+    license_ = parsed.metadata.get("license", DEFAULT_SKILL_LICENSE)
+    frontmatter = _render_frontmatter(name, description, license_, bookwright.__version__)
+    skill_md_payload = (frontmatter + body).encode("utf-8")
+
+    # Step 7 — the single first mutation point. Every created path is recorded.
+    mkdir_tracked(skill_dir, ledger)
+    skill_md = skill_dir / "SKILL.md"
+    write_bytes_atomic(skill_md, skill_md_payload, ledger)
+    _copy_references(skill_dir, copy_list, ledger)
+
+    # Lint the result; on failure remove this skill dir and re-raise (FR-016).
+    try:
+        lint_skill_md(skill_dir)
+    except Exception:
+        shutil.rmtree(skill_dir, ignore_errors=True)
+        raise
+
+    return skill_md

bookwright/integrations/options.py

@@ -0,0 +1,203 @@
+"""``IntegrationOption`` declarative descriptor and ``parse_options`` parser.
+
+The descriptor is intentionally validation-free at construction time
+(per research R1) — structural validation runs the first time the parser
+introspects an integration's ``options()`` list, surfacing as
+``InvalidOptionDeclarationError`` (FR-015).
+"""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from bookwright.integrations.errors import (
+    InvalidOptionDeclarationError,
+    MalformedOptionError,
+    UnknownOptionError,
+)
+
+if TYPE_CHECKING:
+    from bookwright.integrations.base import SkillsIntegration
+
+
+_VALID_TYPES: frozenset[str] = frozenset({"flag", "string"})
+
+
+@dataclass(frozen=True)
+class IntegrationOption:
+    """Immutable declarative descriptor for one ``--integration-options`` flag.
+
+    Subclasses return a list of these from their ``options()`` classmethod.
+    The ``flag`` field MUST start with ``"--"`` (FR-012). The ``type`` field
+    drives parser behaviour: ``"flag"`` is presence-only (boolean),
+    ``"string"`` consumes the next token as its value.
+    """
+
+    flag: str
+    type: Literal["flag", "string"] = "flag"
+    required: bool = False
+    default: str | None = None
+    help: str = ""
+
+
+def _validate_descriptor(option: IntegrationOption) -> None:
+    """First-introspection validation of one declared option descriptor (FR-015)."""
+
+    if not option.flag.startswith("--"):
+        raise InvalidOptionDeclarationError(rule="bad_flag_prefix", value=option.flag)
+    if option.type not in _VALID_TYPES:
+        raise InvalidOptionDeclarationError(rule="bad_type", value=str(option.type))
+
+
+def _normalize_identifier(flag: str) -> str:
+    """``--skills-dir`` → ``skills_dir``."""
+
+    return flag.removeprefix("--").replace("-", "_")
+
+
+def parse_options(  # noqa: PLR0912, PLR0915 — small hand-rolled state machine, one branch per FR-016..FR-021 rule.
+    raw: str | None,
+    integration_cls: type[SkillsIntegration],
+) -> dict[str, str | bool]:
+    """Parse ``--integration-options`` raw input against an integration's options().
+
+    Returns a dict keyed by each captured option's normalized identifier
+    (``--skills-dir`` → ``"skills_dir"``). Empty / ``None`` / whitespace
+    input skips the tokenization loop and the required-flag check (FR-020
+    wins over FR-021), but declared defaults are still applied (R8). All
+    error paths raise structured exceptions; nothing is written to
+    stdout/stderr.
+    """
+
+    # Validate every declared descriptor up front (FR-015, R9).
+    # Runs BEFORE the empty-input short-circuit so a broken options()
+    # declaration surfaces on the first parse_options call, not only when
+    # the user happens to pass non-empty --integration-options.
+    declared = integration_cls.options()
+    for option in declared:
+        _validate_descriptor(option)
+
+    # R14 — two IntegrationOption descriptors with the same flag must not
+    # silently coalesce in the lookup dict; surface the programming error
+    # explicitly so the integration author fixes their options() list.
+    flags = [opt.flag for opt in declared]
+    if len(set(flags)) != len(flags):
+        dup = next(f for f in flags if flags.count(f) > 1)
+        raise InvalidOptionDeclarationError(rule="duplicate_flag", value=dup)
+
+    # R15 — two flags that normalize to the same identifier
+    # (e.g. `--skills-dir` and `--skills_dir` both → `skills_dir`) would
+    # silently last-wins in `result`; detect at declaration time. Build
+    # a flag→ident map so the error names BOTH colliding flags.
+    #
+    # R26 — `idents` is the canonical `flag → normalized identifier` map
+    # for the rest of this function: every subsequent ident lookup hits
+    # this dict instead of re-running `_normalize_identifier`, so the
+    # transform has exactly one source of truth and the normalization
+    # rule is in one place.
+    idents: dict[str, str] = {}
+    for flag in flags:
+        ident = _normalize_identifier(flag)
+        if ident in idents.values():
+            collider = next(f for f, i in idents.items() if i == ident)
+            raise InvalidOptionDeclarationError(
+                rule="colliding_identifiers",
+                value=f"{collider} and {flag} both normalize to {ident!r}",
+            )
+        idents[flag] = ident
+
+    # R28 — single source of truth for the empty-input gate so the
+    # tokenization branch and the FR-021 required-check branch can't
+    # drift on what counts as "empty" (FR-020 wins over FR-021 only
+    # when input is genuinely absent).
+    has_input = raw is not None and raw.strip() != ""
+
+    result: dict[str, str | bool] = {}
+
+    if has_input:
+        assert raw is not None  # narrowed by `has_input` for mypy
+        lookup: dict[str, IntegrationOption] = {opt.flag: opt for opt in declared}
+        declared_flags = sorted(lookup.keys())
+
+        try:
+            tokens = shlex.split(raw, posix=True)
+        except ValueError as exc:
+            # `shlex.split` raises `ValueError("No closing quotation")` on
+            # unbalanced quotes. Translate into the structured-error contract
+            # FR-035 promises — otherwise iteration-4's `--json` envelope sees
+            # a bare ValueError without `code`/`message` keys (R7).
+            raise MalformedOptionError(rule="malformed_shell_syntax", value=raw) from exc
+
+        seen: set[str] = set()
+
+        index = 0
+        while index < len(tokens):
+            token = tokens[index]
+            if "=" in token and token.startswith("--"):
+                flag, _, value = token.partition("=")
+                has_inline_value = True
+            else:
+                flag = token
+                value = ""
+                has_inline_value = False
+
+            if flag not in lookup:
+                raise UnknownOptionError(
+                    integration=integration_cls.key,
+                    value=flag,
+                    valid=declared_flags,
+                )
+
+            if flag in seen:
+                raise MalformedOptionError(rule="duplicate_flag", value=flag)
+            seen.add(flag)
+
+            option = lookup[flag]
+            ident = idents[flag]
+
+            if option.type == "string":
+                if has_inline_value:
+                    # R11 — `--flag=` (empty inline value) is treated as a
+                    # missing value, symmetric with bare `--flag`. Without
+                    # this guard the empty string slipped through to the
+                    # consumer and the failure surfaced later (e.g., as
+                    # `resolves_to_project_root` in setup() when the
+                    # consumer wrapped it as Path('')).
+                    if value == "":
+                        raise MalformedOptionError(rule="missing_value", value=flag)
+                    result[ident] = value
+                    index += 1
+                    continue
+                if index + 1 >= len(tokens):
+                    raise MalformedOptionError(rule="missing_value", value=flag)
+                result[ident] = tokens[index + 1]
+                index += 2
+                continue
+
+            # type == "flag"
+            if has_inline_value:
+                raise MalformedOptionError(rule="unexpected_value", value=flag)
+            result[ident] = True
+            index += 1
+
+    # R8 — apply declared defaults for opts the user did not supply. Runs
+    # in both paths (empty + non-empty input) so an integration that
+    # declares `default='X'` always sees `X` when the flag is omitted.
+    for option in declared:
+        if option.default is not None:
+            ident = idents[option.flag]
+            if ident not in result:
+                result[ident] = option.default
+
+    # Required-flag enforcement runs after defaults so `required=True,
+    # default='x'` is always satisfied (FR-021 only fires for required
+    # opts without a default that the user also omitted). Empty-input
+    # short-circuit at top of branch skips this — FR-020 wins.
+    if has_input:
+        for option in declared:
+            if option.required and idents[option.flag] not in result:
+                raise MalformedOptionError(rule="missing_required", value=option.flag)
+
+    return result

bookwright/io/__init__.py

@@ -0,0 +1 @@
+"""Plain-text → GOLEM-model parsing (frontmatter, bible mapper, build report)."""