karni-cli 0.3.1__py3-none-any.whl

karni_cli/project.py

@@ -0,0 +1,248 @@
+"""Project discovery and manage.py execution.
+
+The CLI never imports Django. Everything project-side runs through the
+project's own interpreter, resolved in this order (per command flags):
+explicit ``--docker/--no-docker`` > ``<project>/.venv`` > a running docker
+compose service > a two-line error naming both remedies.
+
+Interactive runners (shell, test, worker, ...) pass ``interactive=True``:
+in docker mode that allocates a TTY (``docker compose exec`` without
+``-T``) when the CLI itself runs in a terminal, so prompts, colours and
+Ctrl-C work; scripted and agent runs (no TTY) keep ``-T``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+#: Typer ``context_settings`` for runners that pass unknown options through
+#: to the wrapped command (``karni test -x -k name``). Put ``--`` before
+#: arguments that clash with the runner's own options.
+PASSTHROUGH: dict[str, Any] = {"ignore_unknown_options": True, "allow_extra_args": True}
+
+
+class CliError(Exception):
+    """User-facing CLI failure; the message is printed without a traceback.
+
+    ``code`` is a registered code (``C101``, or a Karni code such as ``E704``
+    passed through); ``str()`` is ``"<code>: <message> See <docs url>"`` and
+    ``karni explain <code>`` prints the full entry offline.
+    """
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+
+    def __str__(self) -> str:
+        if not self.code:
+            return self.message
+        from karni_cli.errorcodes import docs_url
+
+        sep = "\n" if "\n" in self.message else " "
+        return f"{self.code}: {self.message}{sep}See {docs_url(self.code)}"
+
+
+def find_project(start: Path | None = None) -> Path | None:
+    """Walk up from ``start`` (default cwd) to the directory holding manage.py."""
+    current = (start or Path.cwd()).resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / "manage.py").is_file():
+            return candidate
+    return None
+
+
+def require_project(start: Path | None = None) -> Path:
+    project = find_project(start)
+    if project is None:
+        raise CliError(
+            "No manage.py found here or above — run inside a Karni project.", code="C001"
+        )
+    return project
+
+
+def venv_python(project: Path) -> Path | None:
+    """The project's interpreter: its ``.venv``, else the active virtualenv, else this one.
+
+    ``VIRTUAL_ENV`` covers the host setup where one activated venv holds
+    karni-cli and the project's dependencies (the quickstart). The interpreter
+    running karni-cli counts when it has Django and karni installed — the
+    quickstart's venv invoked by path, an MCP host that inherited no
+    ``VIRTUAL_ENV``. A pipx-installed ``karni`` has neither and keeps looking
+    for the project's own.
+    """
+    python = project / ".venv" / "bin" / "python"
+    if python.exists():
+        return python
+    active = os.environ.get("VIRTUAL_ENV")
+    if active:
+        candidate = Path(active) / "bin" / "python"
+        if candidate.exists():
+            return candidate
+    return _running_interpreter()
+
+
+def _running_interpreter() -> Path | None:
+    """``sys.executable`` when it can import Django and karni (never imported here)."""
+    if importlib.util.find_spec("django") is None or importlib.util.find_spec("karni") is None:
+        return None
+    return Path(sys.executable)
+
+
+def compose_service_running(project: Path, service: str) -> bool:
+    """True when ``docker compose ps`` reports the service as running."""
+    try:
+        proc = subprocess.run(
+            ["docker", "compose", "ps", "--status", "running", "--services"],
+            cwd=project,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return False
+    if proc.returncode != 0:
+        return False
+    return service in proc.stdout.split()
+
+
+def resolve_execution(project: Path, docker: bool | None, service: str) -> str:
+    """Pick "venv" or "docker" per the documented resolution order."""
+    if docker is True:
+        if not compose_service_running(project, service):
+            raise CliError(
+                f'docker compose service "{service}" is not running.\n'
+                "Start the stack first: docker compose up -d",
+                code="C002",
+            )
+        return "docker"
+    if docker is False:
+        if venv_python(project) is None:
+            raise CliError(
+                "No .venv in the project and no active virtualenv (and --no-docker was given).\n"
+                "Create one (python -m venv .venv && .venv/bin/pip install -e .), activate one "
+                "that has the project's dependencies, or drop --no-docker.",
+                code="C002",
+            )
+        return "venv"
+    if venv_python(project) is not None:
+        return "venv"
+    if compose_service_running(project, service):
+        return "docker"
+    raise CliError(
+        "No way to run the project: no .venv and the compose stack is not running.\n"
+        "Either `docker compose up -d`, or create a venv "
+        "(uv venv && uv pip install -r pyproject.toml).",
+        code="C002",
+    )
+
+
+def _tty() -> bool:
+    """True when the CLI runs in a terminal (both stdin and stdout)."""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def python_command(
+    project: Path,
+    args: list[str],
+    *,
+    docker: bool | None = None,
+    service: str = "django",
+    interactive: bool = False,
+) -> list[str]:
+    """The argv running ``python <args>`` in the resolved environment."""
+    mode = resolve_execution(project, docker, service)
+    if mode == "venv":
+        return [str(venv_python(project)), *args]
+    no_tty = [] if interactive and _tty() else ["-T"]
+    return ["docker", "compose", "exec", *no_tty, service, "python", *args]
+
+
+def run_python(
+    project: Path,
+    args: list[str],
+    *,
+    docker: bool | None = None,
+    service: str = "django",
+    capture: bool = True,
+    interactive: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Run ``python <args>`` through the project interpreter, cwd pinned to the project.
+
+    Returns the CompletedProcess (text mode, never raises on non-zero exit).
+    With ``capture=False`` output streams through to the terminal (stdin is
+    always inherited); ``interactive=True`` also asks docker for a TTY.
+    """
+    cmd = python_command(project, args, docker=docker, service=service, interactive=interactive)
+    return run_process(cmd, cwd=project, capture=capture)
+
+
+def run_process(
+    cmd: list[str], *, cwd: Path, capture: bool = False
+) -> subprocess.CompletedProcess[str]:
+    """``subprocess.run`` that passes SIGTERM on to the child.
+
+    ``karni serve`` and ``karni worker`` wrap a real server: a script or an
+    agent that stops the wrapper must stop the server too, not leak it.
+    Ctrl-C needs no forwarding (the terminal signals the whole group).
+    """
+    pipe = subprocess.PIPE if capture else None
+    with subprocess.Popen(cmd, cwd=cwd, text=True, stdout=pipe, stderr=pipe) as proc:
+
+        def forward(signum: int, _frame: Any) -> None:
+            with contextlib.suppress(ProcessLookupError):
+                proc.send_signal(signum)
+
+        previous: Any = None
+        try:
+            previous = signal.signal(signal.SIGTERM, forward)
+        except ValueError:  # not the main thread: no forwarding, same run
+            previous = None
+        try:
+            out, err = proc.communicate()
+        except KeyboardInterrupt:
+            proc.wait()
+            raise
+        finally:
+            if previous is not None:
+                signal.signal(signal.SIGTERM, previous)
+    return subprocess.CompletedProcess(cmd, proc.returncode, out, err)
+
+
+def run_manage(
+    project: Path,
+    args: list[str],
+    *,
+    docker: bool | None = None,
+    service: str = "django",
+    capture: bool = True,
+    interactive: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    """Run ``manage.py <args>`` in the resolved environment (see :func:`run_python`)."""
+    return run_python(
+        project,
+        ["manage.py", *args],
+        docker=docker,
+        service=service,
+        capture=capture,
+        interactive=interactive,
+    )
+
+
+def run_compose(project: Path, args: list[str]) -> subprocess.CompletedProcess[str]:
+    """Run ``docker compose <args>`` in the project, streaming to the terminal."""
+    try:
+        return run_process(["docker", "compose", *args], cwd=project)
+    except FileNotFoundError:
+        raise CliError(
+            "docker not found — install Docker with the compose plugin, "
+            "or run without it: karni serve --local",
+            code="C003",
+        ) from None

karni_cli/rules_render.py

@@ -0,0 +1,86 @@
+"""Text renderings of the agent data for terminals, agents and docs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from karni_cli.agent_data import AgentData
+
+PROMPTS_START = "<!-- karni:procedures:start (generated: `karni rules --prompts-doc`) -->"
+PROMPTS_END = "<!-- karni:procedures:end -->"
+
+
+def render_rules(data: AgentData, fragments: dict[str, str] | None = None) -> str:
+    """The ``karni rules`` listing: every rule's code + summary, grouped by category.
+
+    Kept under 400 tokens for Karni's own rules; project rules and module
+    guidance add to it (they are project-specific and needed to start work).
+    """
+    lines = ["Karni rules. ! = build-enforced."]
+    for category in data.categories:
+        lines.append(f"[{category}]")
+        for rule in data.rules:
+            if rule["category"] == category:
+                mark = "!" if rule["severity"] == "error" else ""
+                lines.append(f"{rule['code']}{mark} {rule['summary']}")
+    for name, fragment in (fragments or {}).items():
+        lines.append(f"[module:{name}]")
+        lines.append(fragment.strip())
+    lines.append("Why/fix: karni explain CODE")
+    return "\n".join(lines)
+
+
+def render_explain(rule: dict[str, Any]) -> str:
+    lines = [f"{rule['code']} [{rule['category']}, {rule['severity']}] {rule['rule']}"]
+    if rule.get("rationale"):
+        lines.append(f"Why: {rule['rationale']}")
+    if rule.get("fix"):
+        lines.append(f"Fix: {rule['fix']}")
+    if rule.get("enforced_by"):
+        lines.append("Enforced by: " + ", ".join(rule["enforced_by"]))
+    return "\n".join(lines)
+
+
+def render_procedure(procedure: dict[str, Any], arguments: str = "<arguments>") -> str:
+    lines = [procedure["intro"].replace("{arguments}", arguments), ""]
+    lines += [f"{i}. {step}" for i, step in enumerate(procedure["steps"], start=1)]
+    if procedure.get("outro"):
+        lines += ["", procedure["outro"]]
+    if procedure.get("rules"):
+        lines += ["", "Rules that apply: " + ", ".join(procedure["rules"])]
+    return "\n".join(lines)
+
+
+def render_findings(findings: list[dict[str, Any]]) -> str:
+    lines = []
+    for f in findings:
+        lines.append(f"{f['path']}:{f['line']}: {f['code']} [{f['rule_id']}] {f['message']}")
+        if f.get("fix"):
+            lines.append(f"  fix: {f['fix']}")
+    return "\n".join(lines)
+
+
+def render_prompts_doc(data: AgentData) -> str:
+    """Plain-language equivalents of the slash commands (docs/agents.md block)."""
+    lines = [PROMPTS_START, ""]
+    for procedure in data.procedures:
+        name = procedure["name"]
+        lines += [
+            f"### `{name}` — {procedure['description']}",
+            "",
+            "Prompt for tools without slash commands (replace the placeholder):",
+            "",
+            (
+                f"> Run `karni rules --procedure {name}` and follow every step for: "
+                f"`{procedure['argument_hint']}`"
+            ),
+            "",
+            "What `karni rules --procedure` returns:",
+            "",
+            "```text",
+            render_procedure(procedure, procedure["argument_hint"]),
+            "```",
+            "",
+        ]
+    lines.append(PROMPTS_END)
+    return "\n".join(lines)

karni_cli/scaffold.py

@@ -0,0 +1,197 @@
+"""Template, @karni/ui source resolution and slug rules for ``karni new``."""
+
+from __future__ import annotations
+
+import json
+import os
+import posixpath
+import re
+import shutil
+import subprocess
+from importlib import resources
+from pathlib import Path
+
+from karni_cli.project import CliError
+
+SLUG_RE = re.compile(r"^[a-z_][a-z0-9_]*$")
+
+UI_PACKAGE = "@karni/ui"
+#: The npm spec a project gets when no local @karni/ui is found.
+UI_REGISTRY_SPEC = "^0.3.0"
+#: What a ``file:`` consumer needs: package.json ``exports`` point into dist/.
+UI_DIST_FILES = ("dist/index.js", "dist/styles.css", "dist/tailwind-preset.js")
+#: Sources the dist is built from (staleness check).
+UI_BUILD_INPUTS = ("src", "tailwind-preset.ts")
+NPM_TIMEOUT = 900
+
+
+def derive_slug(project_name: str) -> str:
+    """Mirror cookiecutter.json's project_slug derivation exactly."""
+    return project_name.lower().replace(" ", "_").replace("-", "_")
+
+
+def validate_name(project_name: str) -> str:
+    slug = derive_slug(project_name)
+    if not SLUG_RE.match(slug):
+        raise CliError(
+            f'"{project_name}" derives the invalid slug "{slug}" '
+            "(allowed: lowercase letters, digits, underscores; must not start with a digit).",
+            code="C103",
+        )
+    return slug
+
+
+def _is_karni_template(candidate: Path) -> bool:
+    """The repo-walk must verify the directory is Karni's own template (E7)."""
+    cc = candidate / "cookiecutter.json"
+    if not cc.is_file():
+        return False
+    try:
+        keys = json.loads(cc.read_text())
+    except (OSError, json.JSONDecodeError):
+        return False
+    repo_root = candidate.parent.parent
+    return "project_slug" in keys and (repo_root / "packages" / "karni").is_dir()
+
+
+def resolve_template() -> Path:
+    """KARNI_TEMPLATES env > verified monorepo checkout > packaged copy."""
+    env = os.environ.get("KARNI_TEMPLATES")
+    if env:
+        path = Path(env).expanduser()
+        if not (path / "cookiecutter.json").is_file():
+            raise CliError(
+                f"KARNI_TEMPLATES={env} does not contain a cookiecutter template.", code="C007"
+            )
+        return path
+
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "templates" / "project"
+        if candidate.is_dir() and _is_karni_template(candidate):
+            return candidate
+
+    packaged = resources.files("karni_cli") / "_templates" / "project"
+    with resources.as_file(packaged) as path:
+        if path.is_dir():
+            return path
+    raise CliError(
+        "No project template found (no KARNI_TEMPLATES, no monorepo checkout, "
+        "no packaged copy) — reinstall karni-cli.",
+        code="C005",
+    )
+
+
+# @karni/ui source
+
+
+def _is_karni_ui(candidate: Path) -> bool:
+    """A directory is Karni's UI package when its package.json names @karni/ui."""
+    try:
+        meta = json.loads((candidate / "package.json").read_text())
+    except (OSError, json.JSONDecodeError):
+        return False
+    return isinstance(meta, dict) and meta.get("name") == UI_PACKAGE
+
+
+def resolve_ui_source(start: Path | None = None) -> Path | None:
+    """KARNI_UI_SRC env > verified monorepo checkout > ``None`` (the npm registry).
+
+    Mirrors :func:`resolve_template`: the repo-walk only accepts
+    ``packages/karni-ui`` when it really is @karni/ui AND sits next to
+    ``packages/karni`` — never some unrelated directory of the same name.
+    """
+    env = os.environ.get("KARNI_UI_SRC")
+    if env:
+        path = Path(env).expanduser().resolve()
+        if not _is_karni_ui(path):
+            raise CliError(
+                f"KARNI_UI_SRC={env} is not the {UI_PACKAGE} package "
+                "(expected a directory whose package.json is named @karni/ui, "
+                "e.g. /path/to/Karni/packages/karni-ui).",
+                code="C007",
+            )
+        return path
+    for parent in (start or Path(__file__).resolve()).parents:
+        candidate = parent / "packages" / "karni-ui"
+        if _is_karni_ui(candidate) and (parent / "packages" / "karni").is_dir():
+            return candidate
+    return None
+
+
+def ui_spec(source: Path | None, project: Path | None = None) -> str:
+    """The ``@karni/ui`` dependency spec written into frontend/package.json.
+
+    A local checkout is a ``file:`` path. When the project lives inside that
+    checkout (``examples/``), the path is relative to ``frontend/`` so the
+    project installs on any machine; elsewhere it is absolute.
+    """
+    if source is None:
+        return UI_REGISTRY_SPEC
+    root = source.parent.parent
+    if project is not None and project.resolve().is_relative_to(root):
+        return f"file:{os.path.relpath(source, project.resolve() / 'frontend')}"
+    return f"file:{source}"
+
+
+def ui_mount_target(spec: str, container_dir: str = "/app") -> str:
+    """Where a ``file:`` spec resolves inside the frontend container (compose bind target)."""
+    if not spec.startswith("file:"):
+        return spec
+    path = spec.removeprefix("file:")
+    if posixpath.isabs(path):
+        return path
+    return posixpath.normpath(posixpath.join(container_dir, path))
+
+
+def ui_dist_missing(source: Path) -> list[str]:
+    return [rel for rel in UI_DIST_FILES if not (source / rel).is_file()]
+
+
+def ui_dist_stale(source: Path) -> bool:
+    """True when a dist input (src/, the preset) changed after dist/index.js was built."""
+    built = source / UI_DIST_FILES[0]
+    if not built.is_file():
+        return False
+    stamp = built.stat().st_mtime
+    for name in UI_BUILD_INPUTS:
+        root = source / name
+        files = [root] if root.is_file() else (p for p in root.rglob("*") if p.is_file())
+        if any(path.stat().st_mtime > stamp for path in files):
+            return True
+    return False
+
+
+def ui_build_commands(source: Path) -> list[list[str]]:
+    """``npm install`` (only without node_modules) then ``npm run build``."""
+    commands = [] if (source / "node_modules").is_dir() else [["npm", "install", "--no-audit"]]
+    return [*commands, ["npm", "run", "build"]]
+
+
+def run_npm(argv: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    """Run one npm command (the seam tests replace)."""
+    npm = shutil.which(argv[0])
+    if npm is None:
+        return subprocess.CompletedProcess(argv, 127, stdout="", stderr="npm is not on PATH")
+    try:
+        return subprocess.run(
+            [npm, *argv[1:]],
+            cwd=cwd,
+            text=True,
+            capture_output=True,
+            check=False,
+            timeout=NPM_TIMEOUT,
+            env={**os.environ, "CI": "1"},
+        )
+    except subprocess.TimeoutExpired:
+        return subprocess.CompletedProcess(argv, 124, stdout="", stderr="timed out")
+
+
+def build_ui_dist(source: Path) -> str | None:
+    """Build @karni/ui's dist/ in ``source``; ``None`` on success, else the failure."""
+    for argv in ui_build_commands(source):
+        proc = run_npm(argv, source)
+        if proc.returncode != 0:
+            tail = "\n".join((proc.stdout + proc.stderr).strip().splitlines()[-15:])
+            return f"`{' '.join(argv)}` failed ({proc.returncode}):\n{tail}"
+    missing = ui_dist_missing(source)
+    return f"the build did not produce {', '.join(missing)}" if missing else None

karni_cli/settings_edit.py

@@ -0,0 +1,128 @@
+"""Marker-based edits to a project's config/settings.py.
+
+``karni add`` and ``karni make app`` manage the ``# karni:apps`` block,
+``karni make middleware`` the ``# karni:middleware`` block. Two accepted
+shapes of a marked block (``SETTING`` is ``INSTALLED_APPS`` / ``MIDDLEWARE``):
+
+    SETTING += [  # noqa: F821
+        "existing.entry",
+    ]  # karni:<name>
+
+    SETTING += ["existing.entry"]  # karni:<name>
+
+Anything else errors with the manual-edit escape hatch — this code never
+guesses at unfamiliar layouts.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from karni_cli.project import CliError
+
+MARKER = "# karni:apps"
+MIDDLEWARE_MARKER = "# karni:middleware"
+
+_QUOTED = re.compile(r"""["']([^"']+)["']""")
+
+
+def _single_line(setting: str) -> re.Pattern[str]:
+    return re.compile(
+        rf"^(?P<head>\s*{re.escape(setting)}\s*\+=\s*)\[(?P<body>.*)\]\s*(?P<tail>#.*)$"
+    )
+
+
+def _block_entries(lines: list[str], open_idx: int, close_idx: int) -> list[str]:
+    """Quoted entries on non-comment lines inside the block."""
+    entries: list[str] = []
+    for line in lines[open_idx + 1 : close_idx]:
+        stripped = line.strip()
+        if stripped.startswith("#"):
+            continue
+        entries.extend(_QUOTED.findall(stripped))
+    return entries
+
+
+def _locate(lines: list[str], setting: str, marker: str) -> tuple[int, int] | None:
+    """``(open line, marker line)`` of the block (equal for the single-line shape)."""
+    marker_idx = next((i for i, line in enumerate(lines) if marker in line), None)
+    if marker_idx is None:
+        return None
+    if _single_line(setting).match(lines[marker_idx]):
+        return marker_idx, marker_idx
+    if lines[marker_idx].strip().startswith("]"):
+        open_idx = next(
+            (i for i in range(marker_idx - 1, -1, -1) if setting in lines[i] and "[" in lines[i]),
+            None,
+        )
+        if open_idx is not None:
+            return open_idx, marker_idx
+    return -1, marker_idx
+
+
+def block_entries(text: str, setting: str = "INSTALLED_APPS", marker: str = MARKER) -> list[str]:
+    """The entries of the marked block in settings ``text`` (``[]`` when absent)."""
+    lines = text.splitlines()
+    found = _locate(lines, setting, marker)
+    if found is None or found[0] < 0:
+        return []
+    open_idx, marker_idx = found
+    if open_idx == marker_idx:
+        single = _single_line(setting).match(lines[marker_idx])
+        return _QUOTED.findall(single.group("body")) if single else []
+    return _block_entries(lines, open_idx, marker_idx)
+
+
+def add_entry(text: str, entry: str, *, setting: str, marker: str, filename: str) -> str | None:
+    """``text`` with ``entry`` inserted into the marked block; ``None`` when already present.
+
+    :raises CliError: when the marker is missing or the block has another shape.
+    """
+    lines = text.splitlines()
+    found = _locate(lines, setting, marker)
+    if found is None:
+        raise CliError(
+            f"No `{marker}` marker in {filename} — add {entry!r} to {setting} manually.",
+            code="C108",
+        )
+    open_idx, marker_idx = found
+    if open_idx < 0:
+        raise CliError(
+            f"Unrecognized `{marker}` block shape in {filename} — add {entry!r} to {setting} "
+            "manually.",
+            code="C108",
+        )
+    if open_idx == marker_idx:
+        single = _single_line(setting).match(lines[marker_idx])
+        assert single is not None  # _locate matched it
+        entries = _QUOTED.findall(single.group("body"))
+        if entry in entries:
+            return None
+        rebuilt = [f"{single.group('head').rstrip()} [  # noqa: F821"]
+        rebuilt += [f'    "{existing}",' for existing in entries]
+        rebuilt.append(f'    "{entry}",')
+        rebuilt.append(f"]  {marker}")
+        lines[marker_idx : marker_idx + 1] = rebuilt
+    else:
+        if entry in _block_entries(lines, open_idx, marker_idx):
+            return None
+        lines.insert(marker_idx, f'    "{entry}",')
+    return "\n".join(lines) + "\n"
+
+
+def add_app(settings_path: Path, app: str) -> bool:
+    """Insert ``app`` into the ``# karni:apps`` block. Returns False when already present."""
+    if not settings_path.is_file():
+        raise CliError(f"{settings_path} not found.", code="C001")
+    updated = add_entry(
+        settings_path.read_text(),
+        app,
+        setting="INSTALLED_APPS",
+        marker=MARKER,
+        filename=settings_path.name,
+    )
+    if updated is None:
+        return False
+    settings_path.write_text(updated)
+    return True