claude-code-kit 0.7.0__py3-none-any.whl

claude_kit/models.py

@@ -0,0 +1,205 @@
+"""Typed data structures for claude-kit's catalog-driven scaffolder.
+
+These dataclasses are the contract between the prompt layer (:mod:`claude_kit.prompts`), the
+catalog resolver (:mod:`claude_kit.catalog`), and the installer (:mod:`claude_kit.scaffold`).
+Using explicit types (rather than loose dicts) honours the kit's own "no bare container types"
+documentation rule and keeps ``init-options.json`` round-trippable for ``validate``/``upgrade``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+#: Schema version of the persisted ``.claude/config/init-options.json`` document.
+INIT_OPTIONS_SCHEMA = 1
+
+
+@dataclass
+class Selection:
+    """A fully-resolved set of user choices from ``init`` (prompts, ``--defaults``, or ``--config``).
+
+    Attributes:
+        frontend_framework: Frontend framework id (e.g. ``"react"``).
+        frontend_language: Frontend language id (e.g. ``"typescript"``).
+        backend_language: Backend language id (e.g. ``"python"``).
+        backend_framework: Backend framework id (e.g. ``"fastapi"``).
+        database: Database id (``"postgres"`` or ``"mongodb"``).
+        profile: SDLC profile id (``"lean"``/``"standard"``/``"enterprise"``).
+        mcp: Selected MCP server ids (empty means no ``.mcp.json`` is written).
+        scope: Usage scope (``"individual"``/``"team"``/``"organization"``). Only ``organization``
+            installs the org capability layer (packs, persona agents, org rules, autonomy hooks).
+        teams: Teams adopting the config (organization scope only; personalises the generated README).
+        autonomy: Autonomy level (``advisory``/``assisted``/``autonomous-local``/``autonomous-pr``/
+            ``enterprise-controlled``); higher levels enable more guardrail hooks. Prompted only in
+            organization scope; defaults to ``assisted`` everywhere else.
+        review_strictness: Review strictness (``light``/``standard``/``regulated``); ``regulated``
+            adds extra gates/hooks. Prompted only in organization scope.
+        org_packs: Whether to generate the reusable org capability packs (organization scope only).
+    """
+
+    frontend_framework: str
+    frontend_language: str
+    backend_language: str
+    backend_framework: str
+    database: str
+    profile: str
+    mcp: list[str] = field(default_factory=list)
+    scope: str = "team"
+    teams: list[str] = field(default_factory=list)
+    autonomy: str = "assisted"
+    review_strictness: str = "standard"
+    org_packs: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON/YAML-serialisable mapping of this selection."""
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Selection:
+        """Build a :class:`Selection` from a mapping, ignoring unknown keys.
+
+        Args:
+            data: A mapping with the selection fields (e.g. parsed from ``--config``). Org fields
+                may be absent in older documents; their dataclass defaults apply (back-compatible).
+
+        Returns:
+            A populated :class:`Selection`.
+        """
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        kwargs = {k: v for k, v in data.items() if k in known}
+        kwargs.setdefault("mcp", [])
+        return cls(**kwargs)
+
+
+@dataclass
+class OrgPlan:
+    """The resolved organization capability layer (only present when ``scope == organization``).
+
+    Produced by :func:`claude_kit.catalog.resolve` from ``catalog/org.yaml`` and consumed by
+    :func:`claude_kit.scaffold.install_sdlc` (its ``_install_org`` step). The new skills/agents/rules
+    install into the standard auto-discovered ``.claude/{skills,agents,rules}`` dirs; the packs install
+    as manifests under ``.claude/org-packs/``. Autonomy hooks are merged into :attr:`ResolvedPlan.hooks`
+    so they flow through the normal settings assembly.
+
+    Attributes:
+        scope: The usage scope (always ``"organization"`` here).
+        teams: Teams adopting the config (personalises the generated README).
+        autonomy: The chosen autonomy level id.
+        autonomy_policy: One-line human-readable policy for the chosen autonomy level.
+        review_strictness: The chosen review-strictness id.
+        packs: Org-pack ids whose manifests install under ``.claude/org-packs/``.
+        org_skills: New skill dir names to copy from ``templates/org/skills/`` into ``.claude/skills/``.
+        org_agents: New persona agent names to copy from ``templates/org/agents/`` into ``.claude/agents/``.
+        org_rules: New rule filenames to copy from ``templates/org/rules/`` into ``.claude/rules/``.
+        added_hooks: Hook ids added by the autonomy level / strictness (merged into the plan's hooks).
+        added_agents: Core agent names the org layer activates regardless of profile (e.g.
+            ``risk-classifier``; installed via the normal core-agent path, so merged into the plan's
+            ``agents``).
+        extra_gates: Quality-gate ids added by the chosen review strictness (merged into the plan's
+            ``gates``).
+    """
+
+    scope: str
+    teams: list[str]
+    autonomy: str
+    autonomy_policy: str
+    review_strictness: str
+    packs: list[str]
+    org_skills: list[str]
+    org_agents: list[str]
+    org_rules: list[str]
+    added_hooks: list[str]
+    added_agents: list[str] = field(default_factory=list)
+    extra_gates: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON/YAML-serialisable mapping of this org plan."""
+        return asdict(self)
+
+
+@dataclass
+class ResolvedPlan:
+    """The concrete install plan produced by :func:`claude_kit.catalog.resolve`.
+
+    Attributes:
+        selection: The originating :class:`Selection`.
+        agents: Core agent names to install (profile subset, ∪ org core agents in organization scope).
+        skills: Skill directory names to install (profile subset ∪ stack-suggested).
+        overlay_rules: Overlay rule filenames to copy from the selected stacks.
+        overlay_agents: Overlay agent names to copy from the selected stacks.
+        hooks: Hook ids to enable (drives copied scripts + assembled ``settings.json``).
+        gates: Quality-gate ids active for the chosen profile (∪ strictness gates in org scope).
+        mcp_servers: Mapping of selected MCP server id to its ``.mcp.json`` config fragment.
+        context: Flat string context for rendering ``CLAUDE.md`` / ``README`` (labels + commands).
+        stack_dirs: Mapping of selected stack kind to its ``templates/stacks`` subdir.
+        org: The resolved org capability layer, or ``None`` for individual/team scope.
+    """
+
+    selection: Selection
+    agents: list[str]
+    skills: list[str]
+    overlay_rules: list[str]
+    overlay_agents: list[str]
+    hooks: list[str]
+    gates: list[str]
+    mcp_servers: dict[str, dict[str, Any]]
+    context: dict[str, str]
+    stack_dirs: dict[str, str]
+    org: OrgPlan | None = None
+
+
+@dataclass
+class FileRecord:
+    """A single installed file tracked in ``init-options.json`` for safe upgrades.
+
+    Attributes:
+        path: Path relative to the project root (POSIX separators).
+        sha256: Hex SHA-256 of the file contents at install time.
+        owner: One of ``"kit"`` (refreshed on upgrade), ``"overlay"`` (follows the selection),
+            or ``"user-editable"`` (never clobbered).
+    """
+
+    path: str
+    sha256: str
+    owner: str
+
+    def to_dict(self) -> dict[str, str]:
+        """Return a JSON-serialisable mapping of this record."""
+        return asdict(self)
+
+
+@dataclass
+class InitOptions:
+    """The persisted ``.claude/config/init-options.json`` document.
+
+    Attributes:
+        claude_kit_version: Kit version that produced the install.
+        selection: The user's resolved choices.
+        files: Per-file checksum + ownership records (drives ``diff``/``upgrade``).
+        schema_version: Document schema version (:data:`INIT_OPTIONS_SCHEMA`).
+    """
+
+    claude_kit_version: str
+    selection: Selection
+    files: list[FileRecord]
+    schema_version: int = INIT_OPTIONS_SCHEMA
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serialisable mapping (checksums excluded from no field)."""
+        return {
+            "schema_version": self.schema_version,
+            "claude_kit_version": self.claude_kit_version,
+            "selection": self.selection.to_dict(),
+            "files": [r.to_dict() for r in self.files],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> InitOptions:
+        """Reconstruct :class:`InitOptions` from a parsed ``init-options.json`` mapping."""
+        return cls(
+            claude_kit_version=str(data.get("claude_kit_version", "")),
+            selection=Selection.from_dict(data.get("selection", {})),
+            files=[FileRecord(**r) for r in data.get("files", [])],
+            schema_version=int(data.get("schema_version", INIT_OPTIONS_SCHEMA)),
+        )

claude_kit/prompts.py

@@ -0,0 +1,209 @@
+"""Interactive (and non-interactive) selection of an init configuration.
+
+Produces a :class:`~claude_kit.models.Selection` three ways: ordered interactive prompts, the
+catalog defaults (``--defaults``), or a YAML config file (``--config``). The prompt order matches
+the spec: frontend framework → frontend language → backend language → backend framework → database →
+SDLC profile → MCP integrations. (The target path is handled by the CLI before prompting.)
+
+I/O uses ``input``/``print`` so it is trivially testable via a Typer ``CliRunner(input=...)`` or by
+monkeypatching ``builtins.input``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from claude_kit import catalog
+from claude_kit.models import Selection
+
+
+def _ask(prompt: str, default: str) -> str:
+    """Prompt for a single value with a default, tolerant of EOF (non-interactive) input."""
+    try:
+        resp = input(f"{prompt} [{default}]: ").strip()
+    except EOFError:
+        return default
+    return resp or default
+
+
+def _choose_one(title: str, options: list[dict[str, Any]], default: str) -> str:
+    """Render a numbered menu of live options (planned ones shown but not selectable).
+
+    Args:
+        title: Section heading.
+        options: Each dict has ``id``, ``label`` and may have ``status`` (``"planned"`` = disabled).
+        default: The default option id (must be live).
+
+    Returns:
+        The chosen option id.
+    """
+    live = [o for o in options if o.get("status", "live") != "planned"]
+    print(f"\n{title}")
+    for n, o in enumerate(live, 1):
+        mark = "  (default)" if o["id"] == default else ""
+        print(f"  {n}) {o['label']}{mark}")
+    for o in options:
+        if o.get("status") == "planned":
+            print(f"  -) {o['label']} (coming soon)")
+    valid = {o["id"] for o in live}
+    while True:
+        resp = _ask("  choose", default)
+        if resp in valid:
+            return resp
+        if resp.isdigit() and 1 <= int(resp) <= len(live):
+            return live[int(resp) - 1]["id"]
+        print("  please enter one of the listed ids or numbers")
+
+
+def _ask_bool(prompt: str, default: bool) -> bool:
+    """Prompt for a yes/no answer with a default, tolerant of EOF (non-interactive) input."""
+    resp = _ask(f"{prompt} [y/n]", "y" if default else "n").strip().lower()
+    if resp in ("y", "yes", "true", "1"):
+        return True
+    if resp in ("n", "no", "false", "0"):
+        return False
+    return default
+
+
+def _choose_many(title: str, options: list[dict[str, Any]]) -> list[str]:
+    """Render a menu and read a comma/space-separated multi-selection (empty = none)."""
+    print(f"\n{title} (comma-separated ids or numbers; empty = none)")
+    for n, o in enumerate(options, 1):
+        print(f"  {n}) {o['id']} — {o['label']}")
+    resp = _ask("  select", "none")
+    if resp.lower() in ("", "none"):
+        return []
+    chosen: list[str] = []
+    by_id = {o["id"]: o["id"] for o in options}
+    for tok in resp.replace(",", " ").split():
+        if tok in by_id:
+            chosen.append(tok)
+        elif tok.isdigit() and 1 <= int(tok) <= len(options):
+            chosen.append(options[int(tok) - 1]["id"])
+        else:
+            print(f"  (ignoring unknown selection: {tok})")
+    # de-dup, preserve order
+    seen: set[str] = set()
+    return [c for c in chosen if not (c in seen or seen.add(c))]
+
+
+def interactive(payload_root: str | Path) -> Selection:
+    """Run the ordered prompts and return the chosen :class:`Selection`."""
+    opts = catalog.list_options(payload_root)
+    dflt = catalog.defaults(payload_root)
+
+    fe = _choose_one("Frontend framework", opts["frontend"], dflt.frontend_framework)
+    fe_entry = next(o for o in opts["frontend"] if o["id"] == fe)
+    langs = fe_entry.get("languages", []) or ["typescript"]
+    lang_options = [{"id": lang_id, "label": lang_id} for lang_id in langs]
+    fe_lang = _choose_one(
+        "Frontend language",
+        lang_options,
+        fe_entry.get("default_language", "typescript"),
+    )
+
+    be = _choose_one("Backend language", opts["backend"], dflt.backend_language)
+    be_entry = next(o for o in opts["backend"] if o["id"] == be)
+    be_fw = _choose_one(
+        "Backend framework",
+        be_entry.get("frameworks", []),
+        be_entry.get("default_framework", ""),
+    )
+
+    db = _choose_one("Database", opts["database"], dflt.database)
+    profile = _choose_one("SDLC profile", opts["profiles"], dflt.profile)
+    mcp = _choose_many("Optional MCP integrations", opts["mcp"])
+
+    # Usage scope — and, for organizations, the capability-layer questions.
+    org = catalog.org_options(payload_root)
+    scope = _choose_one("Usage scope", org["scopes"], org["defaults"]["scope"])
+    teams: list[str] = []
+    autonomy = org["defaults"]["autonomy"]
+    review_strictness = org["defaults"]["strictness"]
+    org_packs = True
+    if scope == "organization":
+        teams = _choose_many("Which teams will use this?", org["teams"])
+        autonomy = _choose_one("Autonomy level", org["autonomy"], autonomy)
+        review_strictness = _choose_one(
+            "Review strictness", org["strictness"], review_strictness
+        )
+        org_packs = _ask_bool("Generate reusable org capability packs?", True)
+
+    return Selection(
+        frontend_framework=fe,
+        frontend_language=fe_lang,
+        backend_language=be,
+        backend_framework=be_fw,
+        database=db,
+        profile=profile,
+        mcp=mcp,
+        scope=scope,
+        teams=teams,
+        autonomy=autonomy,
+        review_strictness=review_strictness,
+        org_packs=org_packs,
+    )
+
+
+def from_config(config_path: str | Path, payload_root: str | Path) -> Selection:
+    """Build a :class:`Selection` from a YAML config file (``--config``).
+
+    Accepts either flat keys (matching :class:`Selection` fields) or a friendly nested form::
+
+        frontend: { framework: react, language: typescript }
+        backend:  { language: python, framework: fastapi }
+        database: postgres
+        profile:  standard
+        mcp:      [github]
+        scope:    organization
+        org:      { teams: [engineering, product], autonomy: autonomous-pr,
+                    review_strictness: regulated, packs: true }
+
+    Org fields may also be given flat (``scope``/``teams``/``autonomy``/``review_strictness``/
+    ``org_packs``). Missing keys fall back to the catalog defaults.
+    """
+    data = yaml.safe_load(Path(config_path).read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise ValueError("config file did not parse to a mapping")
+    dflt = catalog.defaults(payload_root)
+    org_defaults = catalog.org_options(payload_root)["defaults"]
+
+    fe = data.get("frontend", {})
+    be = data.get("backend", {})
+    org = data.get("org", {})
+    if not isinstance(org, dict):
+        org = {}
+    flat = {
+        "frontend_framework": data.get("frontend_framework")
+        or (fe.get("framework") if isinstance(fe, dict) else fe)
+        or dflt.frontend_framework,
+        "frontend_language": data.get("frontend_language")
+        or (fe.get("language") if isinstance(fe, dict) else None)
+        or dflt.frontend_language,
+        "backend_language": data.get("backend_language")
+        or (be.get("language") if isinstance(be, dict) else be)
+        or dflt.backend_language,
+        "backend_framework": data.get("backend_framework")
+        or (be.get("framework") if isinstance(be, dict) else None)
+        or dflt.backend_framework,
+        "database": data.get("database") or dflt.database,
+        "profile": data.get("profile") or dflt.profile,
+        "mcp": data.get("mcp") or [],
+        "scope": data.get("scope") or org_defaults["scope"],
+        "teams": data.get("teams") or org.get("teams") or [],
+        "autonomy": data.get("autonomy")
+        or org.get("autonomy")
+        or org_defaults["autonomy"],
+        "review_strictness": data.get("review_strictness")
+        or org.get("review_strictness")
+        or org_defaults["strictness"],
+    }
+    # org_packs / org.packs: accept an explicit bool, else default True.
+    packs = data.get("org_packs")
+    if packs is None:
+        packs = org.get("packs")
+    flat["org_packs"] = True if packs is None else bool(packs)
+    return Selection.from_dict(flat)

claude_kit/render.py

@@ -0,0 +1,146 @@
+"""Jinja2-backed template renderer for claude-kit.
+
+Design goals (unchanged from the original stdlib renderer, now powered by Jinja2):
+
+* **Never corrupt literal braces.** Only files whose name ends in ``.tmpl`` are rendered; every
+  other file is copied byte-for-byte. So any literal ``{{``/``{%`` in non-template files (JSON
+  examples, shell, etc.) is left exactly as written.
+* **Ship dotfiles reliably.** A path segment named ``dot__foo`` is written as ``.foo``
+  (``dot__gitignore`` -> ``.gitignore``). This keeps real dotfiles out of the template tree (where
+  some packaging tools silently drop them) and greppable in the repo.
+* **Fail loud on a missing value.** The Jinja environment uses ``StrictUndefined``; an undefined
+  placeholder raises (surfaced as :class:`KeyError`) rather than rendering a blank.
+
+Substitution syntax is Jinja2 (``{{ name }}``), so existing ``.tmpl`` files work unchanged.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, StrictUndefined
+from jinja2.exceptions import UndefinedError
+
+#: Suffix marking a file as a template (stripped from the rendered output name).
+TEMPLATE_SUFFIX = ".tmpl"
+
+#: Prefix marking a path segment that should become a dotfile/dotdir on output.
+DOTFILE_PREFIX = "dot__"
+
+#: Shared Jinja environment. ``keep_trailing_newline`` preserves files' final newline; autoescape is
+#: off because we render Markdown/JSON/text, never HTML.
+_ENV = Environment(
+    undefined=StrictUndefined,
+    keep_trailing_newline=True,
+    autoescape=False,
+    trim_blocks=False,
+    lstrip_blocks=False,
+)
+
+#: Directory names never copied from a template tree (build droppings / VCS / vendored deps).
+_IGNORE_DIRS = frozenset(
+    {
+        "__pycache__",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".mypy_cache",
+        ".git",
+        ".venv",
+        "venv",
+        "node_modules",
+        "dist",
+        "coverage",
+        ".DS_Store",
+    }
+)
+
+#: File names/suffixes never copied from a template tree.
+_IGNORE_FILE_SUFFIXES = (".pyc", ".pyo")
+_IGNORE_FILE_NAMES = frozenset({".DS_Store"})
+
+
+def _is_ignored(rel: Path) -> bool:
+    """Return True if ``rel`` is build/VCS junk that must never be rendered."""
+    if _IGNORE_DIRS & set(rel.parts):
+        return True
+    name = rel.name
+    return name in _IGNORE_FILE_NAMES or name.endswith(_IGNORE_FILE_SUFFIXES)
+
+
+def render_text(text: str, context: dict[str, Any]) -> str:
+    """Render Jinja2 ``text`` against ``context``.
+
+    Args:
+        text: Template text (Jinja2 syntax, e.g. ``{{ name }}``).
+        context: Mapping of placeholder name to replacement value.
+
+    Returns:
+        The rendered text.
+
+    Raises:
+        KeyError: If the template references a name absent from ``context`` (fail-loud parity
+            with the previous renderer).
+    """
+    try:
+        return _ENV.from_string(text).render(**context)
+    except UndefinedError as exc:  # surface as KeyError to keep the existing contract
+        raise KeyError(str(exc)) from exc
+
+
+def _resolve_name(name: str) -> str:
+    """Map a single template path segment to its output name (strip ``.tmpl``, ``dot__`` -> ``.``)."""
+    if name.endswith(TEMPLATE_SUFFIX):
+        name = name[: -len(TEMPLATE_SUFFIX)]
+    if name.startswith(DOTFILE_PREFIX):
+        name = "." + name[len(DOTFILE_PREFIX) :]
+    return name
+
+
+def _resolve_relpath(rel: Path) -> Path:
+    """Apply :func:`_resolve_name` to every segment of a relative path."""
+    return Path(*[_resolve_name(part) for part in rel.parts])
+
+
+def render_tree(src: Path, dest: Path, context: dict[str, Any]) -> list[Path]:
+    """Render the template directory ``src`` into ``dest``.
+
+    The *contents* of ``src`` are written into ``dest``. ``*.tmpl`` files are rendered with Jinja2
+    and written without the suffix; all other files are copied verbatim. ``dot__``-prefixed segments
+    become dotfiles/dotdirs. Existing destination files are overwritten; parents are created.
+
+    Args:
+        src: Source template directory.
+        dest: Destination directory (created if missing).
+        context: Substitution values for ``.tmpl`` files.
+
+    Returns:
+        The written destination file paths (directories excluded).
+
+    Raises:
+        FileNotFoundError: If ``src`` is not an existing directory.
+        KeyError: If a ``.tmpl`` file references an unknown placeholder.
+    """
+    if not src.is_dir():
+        raise FileNotFoundError(f"template source not found: {src}")
+
+    written: list[Path] = []
+    for entry in sorted(src.rglob("*")):
+        rel = entry.relative_to(src)
+        if _is_ignored(rel):
+            continue
+        target = dest / _resolve_relpath(rel)
+        if entry.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if entry.name.endswith(TEMPLATE_SUFFIX):
+            target.write_text(
+                render_text(entry.read_text(encoding="utf-8"), context),
+                encoding="utf-8",
+            )
+        else:
+            shutil.copy2(entry, target)
+        written.append(target)
+    return written