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

claude_kit/cli.py

@@ -0,0 +1,327 @@
+"""Command-line interface for claude-kit (``claude-kit`` · aliases ``ckit`` / ``claude-sdlc``).
+
+A Cookiecutter-style scaffolder for a Claude Code **configuration** (no application code, no Docker):
+``init`` asks ordered questions and lays down ``CLAUDE.md`` + ``.claude/`` (rules, the profile's
+agents/skills, hooks, artifact templates, config) + an optional ``.mcp.json`` and a README. Lifecycle
+commands — ``validate``, ``doctor``, ``diff``, ``upgrade``, ``list-options``, ``status`` — manage it.
+"""
+
+from __future__ import annotations
+
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from claude_kit import __version__, catalog, prompts, scaffold, upgrader, validator
+
+BANNER = r"""
+  ___ _      _   _ ___  ___   _  _____ _____
+ / __| |    /_\ | | |   \| __| | |/ /_ _|_   _|
+| (__| |__ / _ \| |_| | |) | _|  | ' < | |  | |
+ \___|____/_/ \_\\___/|___/|___| |_|\_\___| |_|   autonomous SDLC config for Claude Code
+"""
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=False,
+    help="Scaffold and manage a Claude Code autonomous-SDLC configuration.",
+)
+research_app = typer.Typer(
+    no_args_is_help=True, help="Research helpers (license-respecting)."
+)
+app.add_typer(research_app, name="research")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"claude-kit {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def _root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "-V",
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="print the version",
+    ),
+) -> None:
+    """Show the banner + help when invoked with no subcommand."""
+    if ctx.invoked_subcommand is None:
+        typer.echo(BANNER)
+        typer.echo(ctx.get_help())
+
+
+def _print_report(ok: bool, messages: list[str]) -> None:
+    """Print a check report and exit non-zero on failure."""
+    for line in messages:
+        typer.echo(line)
+    if not ok:
+        raise typer.Exit(1)
+
+
+@app.command()
+def init(
+    path: Optional[str] = typer.Argument(
+        None, help="target project dir (prompted if omitted; default: current dir)"
+    ),
+    defaults: bool = typer.Option(
+        False, "--defaults", help="non-interactive; use catalog defaults"
+    ),
+    config: Optional[str] = typer.Option(
+        None, "--config", help="non-interactive; read the selection from a YAML file"
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="overwrite existing CLAUDE.md / settings.json / .mcp.json",
+    ),
+) -> None:
+    """Scaffold a Claude Code SDLC configuration into a project."""
+    non_interactive = defaults or config is not None
+    with ExitStack() as stack:
+        src = scaffold.payload_dir(stack)
+
+        # 1) Target path.
+        if path is None:
+            raw = "." if non_interactive else input("Target path [.]: ").strip() or "."
+        else:
+            raw = path
+        target = Path(raw).expanduser().resolve()
+        if not target.exists():
+            if not non_interactive and not typer.confirm(
+                f"Create {target}?", default=True
+            ):
+                typer.echo("aborted.")
+                raise typer.Exit(0)
+            target.mkdir(parents=True, exist_ok=True)
+
+        # 2) Existing .claude handling: merge / overwrite / backup / abort.
+        overwrite = force
+        if (target / ".claude").exists():
+            if force:
+                mode = "overwrite"
+            elif non_interactive:
+                mode = "merge"
+            else:
+                mode = (
+                    typer.prompt(
+                        ".claude already exists — [merge/overwrite/backup/abort]",
+                        default="merge",
+                    )
+                    .strip()
+                    .lower()
+                )
+            if mode == "abort":
+                typer.echo("aborted — nothing changed.")
+                raise typer.Exit(0)
+            if mode == "overwrite":
+                overwrite = True
+            if mode == "backup":
+                n = 1
+                while (target / f".claude.bak-{n}").exists():
+                    n += 1
+                (target / ".claude").rename(target / f".claude.bak-{n}")
+                typer.echo(f"  • backed up existing .claude/ -> .claude.bak-{n}")
+
+        # 3) Resolve the selection.
+        try:
+            if config is not None:
+                selection = prompts.from_config(config, src)
+            elif defaults:
+                selection = catalog.defaults(src)
+            else:
+                selection = prompts.interactive(src)
+            plan = catalog.resolve(src, selection)
+        except (ValueError, FileNotFoundError) as exc:
+            typer.echo(f"error: {exc}", err=True)
+            raise typer.Exit(2) from exc
+
+        # 4) Install.
+        typer.echo(f"\nclaude-kit: installing into {target}")
+        for line in scaffold.install_sdlc(src, target, plan, force=overwrite):
+            typer.echo(line)
+
+    typer.echo(
+        "\nDone. Open the project in Claude Code and run `/sdlc <your task>` to start the pipeline."
+    )
+
+
+@app.command()
+def validate(
+    path: str = typer.Argument(".", help="target project dir (default: .)"),
+) -> None:
+    """Structurally validate a scaffolded .claude/ configuration."""
+    _print_report(*validator.validate(path))
+
+
+@app.command()
+def doctor(
+    path: str = typer.Argument(".", help="target project dir (default: .)"),
+) -> None:
+    """Run validation plus environment/health checks with fix hints."""
+    _print_report(*validator.doctor(path))
+
+
+@app.command()
+def diff(
+    path: str = typer.Argument(".", help="target project dir (default: .)"),
+) -> None:
+    """Preview what an upgrade would change (no writes)."""
+    _print_report(*upgrader.diff(path))
+
+
+@app.command()
+def upgrade(
+    path: str = typer.Argument(".", help="target project dir (default: .)"),
+    force: bool = typer.Option(
+        False, "--force", help="overwrite user-modified kit files"
+    ),
+) -> None:
+    """Refresh kit-owned files, backing up user-modified ones."""
+    _print_report(*upgrader.upgrade(path, force=force))
+
+
+@app.command("list-options")
+def list_options() -> None:
+    """List the available frontend/backend/database/profile/MCP options from the catalog."""
+    with ExitStack() as stack:
+        src = scaffold.payload_dir(stack)
+        opts = catalog.list_options(src)
+
+    def _badge(entry: dict) -> str:
+        return "" if entry.get("status", "live") == "live" else "  (coming soon)"
+
+    typer.echo("\nFrontend frameworks:")
+    for fe in opts["frontend"]:
+        langs = ", ".join(fe.get("languages", [])) or "—"
+        typer.echo(f"  • {fe['id']}: {fe['label']}{_badge(fe)}  [languages: {langs}]")
+    typer.echo("\nBackend languages & frameworks:")
+    for be in opts["backend"]:
+        typer.echo(f"  • {be['id']}: {be['label']}{_badge(be)}")
+        for fw in be["frameworks"]:
+            typer.echo(f"      - {fw['id']}: {fw['label']}{_badge(fw)}")
+    typer.echo("\nDatabases:")
+    for db in opts["database"]:
+        typer.echo(f"  • {db['id']}: {db['label']}")
+    typer.echo("\nSDLC profiles:")
+    for pr in opts["profiles"]:
+        typer.echo(f"  • {pr['id']}: {pr['label']}")
+    typer.echo("\nMCP integrations (optional):")
+    for mc in opts["mcp"]:
+        typer.echo(f"  • {mc['id']}: {mc['label']}")
+
+
+@app.command()
+def status(
+    path: str = typer.Argument(".", help="target project dir (default: .)"),
+) -> None:
+    """Show what's installed and the current working memory."""
+    target = Path(path).expanduser().resolve()
+    dest = target / ".claude"
+    typer.echo(f"claude-kit status for {target}")
+    if not dest.is_dir():
+        typer.echo("  not installed — run `claude-kit init` here.")
+        return
+    for name in ("rules", "agents", "skills", "hooks"):
+        d = dest / name
+        if d.is_dir():
+            n = sum(1 for p in d.iterdir() if p.name != ".gitkeep")
+            typer.echo(f"  • {name}/: {n}")
+        else:
+            typer.echo(f"  • {name}/: (missing)")
+    options = dest / "config" / "init-options.json"
+    if options.is_file():
+        import json
+
+        data = json.loads(options.read_text(encoding="utf-8"))
+        sel = data.get("selection", {})
+        typer.echo(
+            f"  • selection: {sel.get('frontend_framework')} + "
+            f"{sel.get('backend_language')}/{sel.get('backend_framework')} + "
+            f"{sel.get('database')} · profile={sel.get('profile')} · mcp={sel.get('mcp') or 'none'}"
+        )
+    continuity = dest / "CONTINUITY.md"
+    if continuity.is_file():
+        typer.echo("\n  working memory (.claude/CONTINUITY.md):")
+        for line in continuity.read_text(
+            encoding="utf-8", errors="replace"
+        ).splitlines()[:30]:
+            typer.echo(f"    {line}")
+    else:
+        typer.echo("\n  no CONTINUITY.md yet (no pipeline run recorded).")
+
+
+@app.command()
+def version() -> None:
+    """Print the version."""
+    typer.echo(f"claude-kit {__version__}")
+
+
+@app.command("package-org-pack")
+def package_org_pack(
+    pack: str = typer.Argument(
+        ..., help="org-pack id under .claude/org-packs/ (e.g. engineering-core)"
+    ),
+    out: Optional[str] = typer.Option(
+        None, "--out", help="output directory for the packaged plugin"
+    ),
+) -> None:
+    """(Planned) Package an org-pack into a reusable, versioned plugin-style directory."""
+    typer.echo(
+        "package-org-pack is planned but not yet implemented.\n"
+        "When available it will bundle the selected org-pack (manifest + the skills/agents/hooks it "
+        "references + settings + README + CHANGELOG + version + license + compatibility metadata) into "
+        "a distributable plugin directory for an internal registry.\n"
+        f"(given: pack={pack}, out={out or 'dist/org-packs/'})"
+    )
+
+
+@app.command("install-org-pack")
+def install_org_pack(
+    source: str = typer.Argument(
+        ..., help="path or registry id of an approved org-pack"
+    ),
+    user: bool = typer.Option(
+        False, "--user", help="install into user-level ~/.claude instead of this repo"
+    ),
+) -> None:
+    """(Planned) Install an approved org-pack into a repo or user-level Claude config."""
+    typer.echo(
+        "install-org-pack is planned but not yet implemented.\n"
+        "When available it will verify a pack's compatibility metadata and merge its components into "
+        "the target .claude/ (repo) or ~/.claude (user) config, recording the pack id + version for "
+        "safe upgrades.\n"
+        f"(given: source={source}, target={'user (~/.claude)' if user else 'repo (.claude)'})"
+    )
+
+
+@research_app.command("import-sources")
+def research_import_sources(
+    sources: str = typer.Argument(
+        ..., help="YAML file of explicit, license-cleared sources"
+    ),
+) -> None:
+    """(Planned) Summarise explicit, license-cleared sources into original skill/agent proposals."""
+    typer.echo(
+        "research import-sources is planned but not yet implemented.\n"
+        "When available it will: read explicit source URLs/files from the given YAML, record each "
+        "source's name/URL/license/author/date, summarise ideas into ORIGINAL skill/agent proposals "
+        "(never copying proprietary text), and require human approval before adding anything.\n"
+        f"(given: {sources})"
+    )
+
+
+def main() -> None:
+    """Console-script entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

claude_kit/hooks.py

@@ -0,0 +1,246 @@
+"""Hook registry — the single definition of every hook claude-kit can install.
+
+A *profile* selects hook ids (see ``catalog/profiles.yaml``); the installer turns the selected ids
+into (a) the set of ``.sh`` scripts to copy into ``.claude/hooks/`` and (b) an assembled
+``.claude/settings.json`` ``hooks`` block. Keeping the registry in one module lets both
+:mod:`claude_kit.catalog` (to resolve the ``all`` token) and :mod:`claude_kit.scaffold`
+(to build settings) share it without duplication.
+
+Hooks are deliberately **conservative**: guardrails block obviously dangerous actions; the quality
+hooks only *suggest* running tools. Script-backed hooks reference ``$CLAUDE_PROJECT_DIR`` so they
+work in a scaffolded project (the plugin variant uses ``${CLAUDE_PLUGIN_ROOT}``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# --- inline guard commands (no script file needed) -------------------------------------------------
+
+_RM_RF_GUARD = (
+    "CMD=$(jq -r '.tool_input.command'); "
+    "if echo \"$CMD\" | grep -qE 'rm[[:space:]]+-[^[:space:]]*r[^[:space:]]*f'; then "
+    "echo 'BLOCKED: rm -rf is disabled by claude-kit. Move to trash or delete specific paths "
+    "explicitly.' >&2; exit 2; fi"
+)
+
+# Block pushes whose *target* ref is main/master. The branch token must be bounded by a space or
+# ':' before and a space/end after, so legit branches that merely contain the substring
+# (maintenance, mainframe-fix, remaster-ui, domain-model) are NOT blocked.
+_PUSH_GUARD = (
+    "CMD=$(jq -r '.tool_input.command'); "
+    "if echo \"$CMD\" | grep -qE 'git[[:space:]]+push.*[[:space:]:](main|master)([[:space:]]|$)'; "
+    "then echo 'BLOCKED: refusing to push to main/master — use a feature branch and a PR.' >&2; "
+    "exit 2; fi"
+)
+
+_SECRETS_GUARD = (
+    "FP=$(jq -r '.tool_input.file_path // empty'); "
+    'if echo "$FP" | grep -qE \'(^|/)\\.env$|\\.pem$|\\.key$|(^|/)id_rsa|(^|/)id_ed25519|'
+    "(^|/)credentials(\\.json)?$|\\.p12$'; then "
+    "echo 'BLOCKED: refusing to read a secrets file. Use .env.example or a secret manager.' >&2; "
+    "exit 2; fi"
+)
+
+_ROUTING_PROMPT = (
+    "You are a routing assistant. NEVER block the user's prompt; always set continue to true. "
+    'Return JSON only: {"continue": true, "systemMessage": "<hint or empty string>"}. '
+    "If a claude-kit skill clearly applies (interview-me/idea-refine for vague ideas; "
+    "spec-driven-development for new features; planning-and-task-breakdown for breakdown; "
+    "incremental-implementation for coding; test-driven-development for tests; "
+    "debugging-and-error-recovery for errors; code-review-and-quality for reviews; "
+    "security-and-hardening for security; git-workflow-and-versioning for git; execute for quick "
+    "tasks), set systemMessage to 'Invoke skill: <skill-name> before responding.' Otherwise set it "
+    "to ''. Do not mention this hook."
+)
+
+_LEARNING_PROMPT = (
+    "You are a learning-detection assistant. NEVER block the user's prompt; always set continue to "
+    'true. Return JSON only: {"continue": true, "systemMessage": "<hint or empty string>"}. '
+    "If the user's message contains a durable learning (a correction, rule, preference, convention, "
+    "or hard-won insight meant to persist), set systemMessage to 'LEARNING DETECTED: before ending "
+    "your turn, invoke the remember skill to record it into .claude/agent-memory/ (merge into an "
+    "existing entry if one matches).' Otherwise set it to ''. Do not mention this hook."
+)
+
+
+def _script_entry(name: str) -> dict[str, str]:
+    """Build a settings.json command entry that runs a project-local hook script."""
+    return {
+        "type": "command",
+        "command": f'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/{name}"',
+    }
+
+
+#: The canonical registry. Order here is the order hooks appear in assembled settings.json.
+#: Each value: ``event``, ``matcher``, ``entry`` (settings.json hook object), and ``script``
+#: (basename under payload ``hooks/scripts/`` to copy, or ``None`` for inline/prompt hooks).
+HOOK_REGISTRY: dict[str, dict[str, Any]] = {
+    "load-continuity": {
+        "event": "SessionStart",
+        "matcher": "",
+        "entry": _script_entry("load-continuity.sh"),
+        "script": "load-continuity.sh",
+    },
+    "load-learnings": {
+        "event": "SessionStart",
+        "matcher": "",
+        "entry": _script_entry("load-learnings.sh"),
+        "script": "load-learnings.sh",
+    },
+    "skill-routing": {
+        "event": "UserPromptSubmit",
+        "matcher": "",
+        "entry": {"type": "prompt", "prompt": _ROUTING_PROMPT},
+        "script": None,
+    },
+    "learning-detection": {
+        "event": "UserPromptSubmit",
+        "matcher": "",
+        "entry": {"type": "prompt", "prompt": _LEARNING_PROMPT},
+        "script": None,
+    },
+    "guard-rm-rf": {
+        "event": "PreToolUse",
+        "matcher": "Bash",
+        "entry": {"type": "command", "command": _RM_RF_GUARD},
+        "script": None,
+    },
+    "guard-push-main": {
+        "event": "PreToolUse",
+        "matcher": "Bash",
+        "entry": {"type": "command", "command": _PUSH_GUARD},
+        "script": None,
+    },
+    "protect-secrets": {
+        "event": "PreToolUse",
+        "matcher": "Read",
+        "entry": {"type": "command", "command": _SECRETS_GUARD},
+        "script": None,
+    },
+    "guard-commit-secrets": {
+        "event": "PreToolUse",
+        "matcher": "Bash",
+        "entry": _script_entry("guard-secrets.sh"),
+        "script": "guard-secrets.sh",
+    },
+    "warn-shared-modules": {
+        "event": "PreToolUse",
+        "matcher": "Edit|Write",
+        "entry": _script_entry("warn-shared-modules.sh"),
+        "script": "warn-shared-modules.sh",
+    },
+    "warn-sensitive-files": {
+        "event": "PreToolUse",
+        "matcher": "Edit|Write",
+        "entry": _script_entry("warn-sensitive-files.sh"),
+        "script": "warn-sensitive-files.sh",
+    },
+    "warn-large-edits": {
+        "event": "PreToolUse",
+        "matcher": "Edit|Write",
+        "entry": _script_entry("warn-large-edits.sh"),
+        "script": "warn-large-edits.sh",
+    },
+    "validate-frontmatter": {
+        "event": "PreToolUse",
+        "matcher": "Write",
+        "entry": _script_entry("validate-frontmatter.sh"),
+        "script": "validate-frontmatter.sh",
+    },
+    "validate-settings": {
+        "event": "PreToolUse",
+        "matcher": "Write",
+        "entry": _script_entry("validate-settings.sh"),
+        "script": "validate-settings.sh",
+    },
+    "warn-missing-tests": {
+        "event": "PostToolUse",
+        "matcher": "Edit|Write",
+        "entry": _script_entry("warn-missing-tests.sh"),
+        "script": "warn-missing-tests.sh",
+    },
+    "audit-log": {
+        "event": "PostToolUse",
+        "matcher": "",
+        "entry": _script_entry("audit-log.sh"),
+        "script": "audit-log.sh",
+    },
+    "lint-fix": {
+        "event": "Stop",
+        "matcher": "",
+        "entry": _script_entry("lint-fix.sh"),
+        "script": "lint-fix.sh",
+    },
+    "type-check": {
+        "event": "Stop",
+        "matcher": "",
+        "entry": _script_entry("type-check.sh"),
+        "script": "type-check.sh",
+    },
+}
+
+#: Event ordering for a stable, readable settings.json.
+_EVENT_ORDER = (
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+)
+
+
+def all_ids() -> list[str]:
+    """Return every hook id, in registry order (used to expand the ``all`` profile token)."""
+    return list(HOOK_REGISTRY)
+
+
+def scripts_for(hook_ids: list[str]) -> list[str]:
+    """Return the script basenames needed by ``hook_ids`` (inline/prompt hooks contribute none)."""
+    out: list[str] = []
+    for hid in hook_ids:
+        spec = HOOK_REGISTRY.get(hid)
+        if spec and spec["script"]:
+            out.append(spec["script"])
+    return sorted(set(out))
+
+
+def build_settings(hook_ids: list[str]) -> dict[str, Any]:
+    """Assemble a ``settings.json`` document from the selected hook ids.
+
+    Groups the selected hooks by event and matcher, preserving registry order, into the schema
+    Claude Code expects (``{"hooks": {EVENT: [{"matcher": …, "hooks": [entry, …]}]}}``).
+
+    Args:
+        hook_ids: Hook ids to enable.
+
+    Returns:
+        A JSON-serialisable settings mapping (always includes an explanatory ``$comment``).
+    """
+    selected = [hid for hid in HOOK_REGISTRY if hid in set(hook_ids)]
+    # event -> matcher -> [entries]
+    grouped: dict[str, dict[str, list[dict[str, Any]]]] = {}
+    for hid in selected:
+        spec = HOOK_REGISTRY[hid]
+        grouped.setdefault(spec["event"], {}).setdefault(spec["matcher"], []).append(
+            spec["entry"]
+        )
+
+    hooks_block: dict[str, list[dict[str, Any]]] = {}
+    ordered_events = [e for e in _EVENT_ORDER if e in grouped] + [
+        e for e in grouped if e not in _EVENT_ORDER
+    ]
+    for event in ordered_events:
+        hooks_block[event] = [
+            {"matcher": matcher, "hooks": entries}
+            for matcher, entries in grouped[event].items()
+        ]
+
+    return {
+        "$comment": (
+            "Claude Code settings installed by claude-kit. Hooks wire the SDLC working-memory, "
+            "learnings, guardrails, and quality checks to scripts in .claude/hooks/. Personal "
+            "overrides belong in .claude/settings.local.json (gitignored)."
+        ),
+        "hooks": hooks_block,
+    }