karni-cli 0.3.1__py3-none-any.whl

karni_cli/agent_data.py

@@ -0,0 +1,260 @@
+"""Where the CLI gets Karni's agent rules from (``karni.agent``).
+
+The CLI never imports project code, but ``karni.agent`` is Karni's own
+stdlib-only data module, so it may be imported when available. Resolution
+(first that works; force one with ``KARNI_AGENT_SOURCE=local|project|bundled``):
+
+1. ``local``   — ``import karni.agent`` in the CLI's own environment.
+2. ``project`` — ``python -m karni.agent`` through the project's interpreter
+   (``.venv``, else a running compose service — the same resolution as
+   ``karni context``); answers with the project's own karni version.
+3. ``bundled`` — the copy of ``karni/agent`` shipped inside karni-cli (the
+   monorepo source when run from a checkout), loaded by path. This is what
+   ``karni new`` uses on a machine where only karni-cli is installed.
+
+Every path yields the same JSON-able shape (``karni.agent.dump``), so the
+renderers below never care which one answered.
+
+History providers (``karni.agent.history``, :func:`history_module`) are the
+exception: they always run in the CLI's own environment, and in ``project``
+mode the CLI hands its detection to the project interpreter
+(``KARNI_AGENT_CONDITIONS``) so conditional rules follow the same providers.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from karni_cli import project as project_mod
+from karni_cli.project import CliError
+
+SOURCES = ("local", "project", "bundled")
+_BUNDLED_NAME = "karni_cli._bundled_karni_agent"
+
+
+@dataclass(frozen=True)
+class AgentData:
+    raw: dict[str, Any]
+    source: str
+
+    @property
+    def rules(self) -> list[dict[str, Any]]:
+        return list(self.raw["rules"])
+
+    @property
+    def procedures(self) -> list[dict[str, Any]]:
+        return list(self.raw["procedures"])
+
+    @property
+    def categories(self) -> list[str]:
+        return list(self.raw["categories"])
+
+    @property
+    def adapter_overrides(self) -> dict[str, Any]:
+        return dict(self.raw.get("adapters") or {})
+
+    def rule(self, code: str) -> dict[str, Any] | None:
+        return next((r for r in self.rules if r["code"] == code.upper()), None)
+
+    def procedure(self, name: str) -> dict[str, Any] | None:
+        return next((p for p in self.procedures if p["name"] == name), None)
+
+
+def _local() -> ModuleType | None:
+    try:
+        from karni import agent
+    except ImportError:
+        return None
+    return agent
+
+
+def _bundled_dir() -> Path | None:
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "packages" / "karni" / "karni" / "agent"
+        if (candidate / "rules.py").is_file():
+            return candidate
+    packaged = resources.files("karni_cli") / "_agent"
+    with resources.as_file(packaged) as path:
+        if (path / "rules.py").is_file():
+            return path
+    return None
+
+
+def _bundled() -> ModuleType | None:
+    if _BUNDLED_NAME in sys.modules:
+        return sys.modules[_BUNDLED_NAME]
+    directory = _bundled_dir()
+    if directory is None:
+        return None
+    spec = importlib.util.spec_from_file_location(
+        _BUNDLED_NAME, directory / "__init__.py", submodule_search_locations=[str(directory)]
+    )
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[_BUNDLED_NAME] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        del sys.modules[_BUNDLED_NAME]
+        raise
+    return module
+
+
+def history_module() -> ModuleType | None:
+    """``karni.agent.history`` for the CLI's own environment.
+
+    History providers always run in the CLI's environment (third-party
+    providers are discovered from its entry points): karni's module when
+    importable here (unless ``KARNI_AGENT_SOURCE=bundled``), else the bundled
+    copy, which carries the built-in Gigai Chronicle provider by itself.
+    """
+    if os.environ.get("KARNI_AGENT_SOURCE", "").strip() != "bundled":
+        try:
+            from karni.agent import history
+
+            return history
+        except ImportError:
+            pass  # karni absent here, or a karni older than history providers
+    bundled = _bundled()
+    if bundled is None:
+        return None
+    try:
+        return importlib.import_module(f"{bundled.__name__}.history")
+    except ImportError:
+        return None
+
+
+def _conditions_env(project: Path) -> dict[str, str]:
+    """The CLI's own condition detection, handed to the project interpreter so a
+    conditional rule follows the same providers as ``karni context --with-history``
+    (and a compose container that cannot see a store above its mount)."""
+    module = history_module()
+    if module is None:
+        return {}
+    return {module.CONDITIONS_ENV: ",".join(sorted(module.active_conditions(project)))}
+
+
+def _project_command(project: Path, env: dict[str, str] | None = None) -> list[str] | None:
+    python = project_mod.venv_python(project)
+    if python is not None:
+        return [str(python), "-m", "karni.agent"]
+    service = os.environ.get("KARNI_COMPOSE_SERVICE", "django")
+    if project_mod.compose_service_running(project, service):
+        flags = [flag for key, value in (env or {}).items() for flag in ("-e", f"{key}={value}")]
+        return ["docker", "compose", "exec", "-T", *flags, service, "python", "-m", "karni.agent"]
+    return None
+
+
+def _run_project(project: Path, args: list[str], env: dict[str, str] | None = None) -> Any | None:
+    command = _project_command(project, env)
+    if command is None:
+        return None
+    proc = subprocess.run(
+        [*command, *args],
+        cwd=project,
+        text=True,
+        capture_output=True,
+        check=False,
+        env={**os.environ, **env} if env else None,
+    )
+    if proc.returncode == 2:
+        raise CliError(proc.stderr.strip(), code="C009")
+    if proc.returncode != 0:
+        return None  # e.g. an older karni without karni.agent: try the next source
+    return json.loads(proc.stdout)
+
+
+def _order() -> tuple[str, ...]:
+    forced = os.environ.get("KARNI_AGENT_SOURCE", "").strip()
+    if not forced:
+        return SOURCES
+    if forced not in SOURCES:
+        raise CliError(
+            f"KARNI_AGENT_SOURCE must be one of {', '.join(SOURCES)}, got {forced!r}.", code="C007"
+        )
+    return (forced,)
+
+
+def _module_for(source: str) -> ModuleType | None:
+    return _local() if source == "local" else _bundled()
+
+
+def _call(module: ModuleType, name: str, *args: Any) -> Any:
+    try:
+        return getattr(module, name)(*args)
+    except module.OverrideError as exc:
+        raise CliError(_bare(exc), code=getattr(exc, "code", "E701")) from None
+
+
+def load(project: Path | None) -> AgentData:
+    """Rules + procedures with ``<project>/karni.rules.py`` applied."""
+    for source in _order():
+        if source == "project":
+            if project is None:
+                continue
+            raw = _run_project(project, ["dump", "--root", "."], _conditions_env(project))
+            if raw is not None:
+                return AgentData(raw, source)
+            continue
+        module = _module_for(source)
+        if module is not None:
+            return AgentData(_call(module, "dump", project), source)
+    raise CliError(
+        "Karni's agent rules are unavailable: karni is not importable here, the project "
+        "interpreter is unreachable, and no bundled copy ships with this karni-cli.\n"
+        "Install karni next to karni-cli, or run inside a project with a .venv.",
+        code="C005",
+    )
+
+
+def check(paths: list[Path], project: Path | None) -> list[dict[str, Any]]:
+    """Static findings for ``paths`` (each a dict with path/code/rule_id/line/message/fix)."""
+    for source in _order():
+        if source == "project":
+            if project is None:
+                continue
+            rel = [_relative(p, project) for p in paths]
+            found = _run_project(project, ["check", "--root", ".", *rel])
+            if found is not None:
+                return [{**f, "path": str(p)} for f, p in _rejoin(found, rel, paths)]
+            continue
+        module = _module_for(source)
+        if module is not None:
+            try:
+                return list(_call(module, "check_paths", paths, project))
+            except (OSError, ValueError) as exc:
+                raise CliError(_bare(exc), code=getattr(exc, "code", "C010")) from None
+    raise CliError("Karni's agent checks are unavailable (see `karni rules`).", code="C005")
+
+
+def _bare(exc: BaseException) -> str:
+    """The message without the code prefix the bundled exception adds to ``str()``."""
+    return str(exc.args[0]) if exc.args else str(exc)
+
+
+def _relative(path: Path, project: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(project.resolve()))
+    except ValueError:
+        raise CliError(
+            f"{path} is outside the project; the project interpreter can only check "
+            "files inside it.",
+            code="C010",
+        ) from None
+
+
+def _rejoin(
+    found: list[dict[str, Any]], rel: list[str], paths: list[Path]
+) -> list[tuple[dict[str, Any], Path]]:
+    by_rel = dict(zip(rel, paths, strict=True))
+    return [(f, by_rel.get(f["path"], Path(f["path"]))) for f in found]

karni_cli/brand.py

@@ -0,0 +1,55 @@
+"""The Karni mark for the terminal: a few lines, only where a person will see them.
+
+``print_mark()`` writes a small truecolor rendering of the crown when stdout
+is an interactive terminal; it writes nothing when the output is piped, when
+``NO_COLOR`` is set (https://no-color.org) or when ``TERM`` is ``dumb``, so
+no machine-readable output ever carries it.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from typing import IO
+
+ACCENT = "\x1b[38;2;251;93;8m"
+LINE = "\x1b[38;2;255;255;255m"
+RESET = "\x1b[0m"
+
+#: Rows of the mark, as (ink, text) runs — rings above the crown's legs, peak and crossings.
+ROWS: tuple[tuple[tuple[str, str], ...], ...] = (
+    ((ACCENT, "  ●   ●   ●"),),
+    ((LINE, "  │╲ ╱ ╲ ╱│"),),
+    ((LINE, "  │ ╳   ╳ │"),),
+    ((LINE, "  │╱ ╲ ╱ ╲│"),),
+)
+
+
+def wants_mark(stream: IO[str] | None = None, environ: Mapping[str, str] | None = None) -> bool:
+    """Is this an interactive, colour-capable terminal that has not opted out?"""
+    stream = stream or sys.stdout
+    env: Mapping[str, str] = os.environ if environ is None else environ
+    if env.get("NO_COLOR") or env.get("TERM", "") == "dumb":
+        return False
+    isatty = getattr(stream, "isatty", None)
+    return bool(isatty and isatty())
+
+
+def mark_lines(*, colour: bool = True) -> list[str]:
+    """The mark's rows, with or without ANSI colour."""
+    lines = []
+    for row in ROWS:
+        text = "".join(f"{ink}{run}{RESET}" if colour else run for ink, run in row)
+        lines.append(text)
+    return lines
+
+
+def print_mark(stream: IO[str] | None = None) -> bool:
+    """Print the mark when :func:`wants_mark`; returns whether it was printed."""
+    stream = stream or sys.stdout
+    if not wants_mark(stream):
+        return False
+    stream.write("\n".join(mark_lines()) + "\n\n")
+    stream.flush()
+    return True

karni_cli/clidoc.py

@@ -0,0 +1,254 @@
+"""Render docs/cli.md from the typer app — the CLI reference is generated, never hand-written.
+
+    python -m karni_cli.clidoc > docs/cli.md
+
+``tests/test_clidoc.py`` fails when docs/cli.md differs from :func:`render`,
+so a changed option or help text must be regenerated in the same commit.
+Everything comes from the click command tree typer builds (help texts,
+arguments, options, defaults) plus :data:`karni_cli.generators.GENERATORS`
+and the field DSL reference (:data:`karni_cli.generators.fields.FIELD_DOCS`).
+"""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import PurePath
+from typing import Any
+
+import typer
+
+from karni_cli.commands.make import list_text
+from karni_cli.generators.fields import FIELD_DOCS
+
+#: Section → top-level commands, in reading order. Anything else lands in "Other".
+SECTIONS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("Project", ("new", "add", "upgrade", "doctor", "config")),
+    ("Agents and checks", ("context", "rules", "check", "explain", "types", "mcp")),
+    (
+        "Runners",
+        (
+            "serve",
+            "migrate",
+            "test",
+            "shell",
+            "routes",
+            "worker",
+            "beat",
+            "schedule",
+            "seed",
+            "sync-roles",
+            "createsuperuser",
+            "manage",
+        ),
+    ),
+    ("Generators", ("make",)),
+)
+
+HEADER = """---
+description: Every karni command with its arguments and options, generated from the CLI's own help text.
+---
+
+# The `karni` command
+
+> Generated from the CLI itself — `python -m karni_cli.clidoc > docs/cli.md`;
+> `packages/karni-cli/tests/test_clidoc.py` fails when this file is stale.
+> Change a command's help, then regenerate; never edit this file by hand.
+
+`karni <command> --help` prints the same information. Runners execute in the
+project environment: the project's `.venv`, else the running docker compose
+service (`--docker/--no-docker` forces one; `--service` / `KARNI_COMPOSE_SERVICE`
+names it). Put `--` before passthrough arguments that clash with karni's own
+options.
+"""
+
+GENERATOR_RULES = """Every generator follows the same rules:
+
+- It writes project code only — never framework logic.
+- It never overwrites: an existing target is an error naming the file and
+  `--force` (which replaces it).
+- `--dry-run` prints the files and the diff it would write, and writes nothing.
+- It prints every created and modified file, then any notes (the chosen
+  `access`, the route, the next command).
+- The target app is `--app <label>`, else the project's only local app (local
+  apps are the `# karni:apps` entries of config/settings.py).
+- Existing files change only through marker comments (`# karni:apps`,
+  `# karni:middleware`, `// karni:page-imports`, `// karni:routes`) or
+  AST-located appends; an unfamiliar layout is an error that names the manual
+  step. Generated Python is ruff-clean (isort sections, ruff format layout).
+- It never imports Django: `karni make migration` (and `make model --migrate`)
+  run `manage.py makemigrations` through the project interpreter.
+- Every generator is also available as a hidden Laravel-style alias:
+  `karni make:<type>` (e.g. `karni make:model Event title:str`).
+"""
+
+
+def _md(text: str) -> str:
+    """Escape ``<`` / ``>`` outside backtick code spans (Markdown would eat ``<field>``)."""
+    parts = text.split("`")
+    for i in range(0, len(parts), 2):
+        parts[i] = parts[i].replace("<", "&lt;").replace(">", "&gt;")
+    return "`".join(parts)
+
+
+def _escape(text: str) -> str:
+    """A table cell: Markdown-escaped, pipes escaped, one line."""
+    return _md(text).replace("|", "\\|").replace("\n", " ")
+
+
+def _paragraphs(help_text: str | None) -> str:
+    """Help text as Markdown: paragraphs re-flowed, ``Example:`` paragraphs as code."""
+    if not help_text:
+        return ""
+    blocks: list[str] = []
+    for raw in textwrap.dedent(help_text).strip().split("\n\n"):
+        text = " ".join(line.strip() for line in raw.strip().splitlines())
+        if not text or text == "\b":
+            continue
+        for label in ("Example:", "Examples:"):
+            if text.startswith(label):
+                code = text[len(label) :].strip()
+                blocks.append(f"{label}\n\n```sh\n{code}\n```")
+                break
+        else:
+            blocks.append(_md(text))
+    return "\n\n".join(blocks)
+
+
+# Typer >= 0.20 vendors its own click (typer._click), older ones use click: the
+# command tree is read by duck typing, never isinstance against a click import.
+Command = Any
+Parameter = Any
+
+
+def _is_argument(param: Parameter) -> bool:
+    return getattr(param, "param_type_name", "") == "argument"
+
+
+def _subcommands(command: Command) -> dict[str, Command]:
+    commands = getattr(command, "commands", None)
+    return dict(commands) if isinstance(commands, dict) else {}
+
+
+_TYPE_LABELS = {"str": "TEXT", "string": "TEXT", "text": "TEXT", "int": "INTEGER"}
+
+
+def _metavar(param: Parameter) -> str:
+    """A stable value label (click and typer's vendored click name types differently)."""
+    name = str(getattr(param.type, "name", "text")).lower()
+    return _TYPE_LABELS.get(name, name.upper())
+
+
+def _default(param: Parameter) -> str:
+    value: Any = param.default
+    if callable(value) or value in (None, False, "", (), []):
+        return ""
+    if value is True:
+        return "on"
+    if isinstance(value, PurePath):
+        value = value.as_posix()
+    return f"`{value}`"
+
+
+def _param_row(param: Parameter) -> str | None:
+    if getattr(param, "hidden", False):
+        return None
+    help_text = _escape(getattr(param, "help", None) or "")
+    if _is_argument(param):
+        name = (param.name or "").rstrip("_").upper()
+        name += "..." if param.nargs == -1 else ""
+        label = f"`{name}`" + (" (required)" if param.required else "")
+    else:
+        flags = list(param.opts)
+        if param.secondary_opts:
+            flags = [f"{flags[0]}/{param.secondary_opts[0]}", *flags[1:]]
+        label = ", ".join(f"`{flag}`" for flag in flags)
+        if not param.is_flag:
+            label += f" {_metavar(param)}"
+        if param.multiple:
+            label += " (repeatable)"
+        if param.required:
+            label += " (required)"
+        if param.envvar:
+            envvars = [param.envvar] if isinstance(param.envvar, str) else list(param.envvar)
+            help_text = f"{help_text} Env: {', '.join(f'`{e}`' for e in envvars)}.".strip()
+    return f"| {label} | {_default(param)} | {help_text} |"
+
+
+def _usage(path: str, command: Command) -> str:
+    pieces = [f"karni {path}"]
+    if any(not _is_argument(p) and not getattr(p, "hidden", False) for p in command.params):
+        pieces.append("[OPTIONS]")
+    for param in command.params:
+        if _is_argument(param):
+            name = (param.name or "").rstrip("_").upper()
+            name += "..." if param.nargs == -1 else ""
+            pieces.append(name if param.required else f"[{name}]")
+    if _subcommands(command):
+        pieces.append("COMMAND [ARGS]...")
+    return " ".join(pieces)
+
+
+def _command(path: str, command: Command, level: int) -> list[str]:
+    out = [f"{'#' * level} `karni {path}`", ""]
+    body = _paragraphs(command.help)
+    if body:
+        out += [body, ""]
+    out += ["```", _usage(path, command), "```", ""]
+    rows = [row for row in (_param_row(p) for p in command.params) if row]
+    if rows:
+        out += ["| Argument / option | Default | Description |", "| --- | --- | --- |", *rows, ""]
+    if path == "make":
+        out += [
+            GENERATOR_RULES,
+            "`karni make --list`:",
+            "",
+            "```",
+            list_text(),
+            "```",
+            "",
+            "Field DSL for `karni make model NAME [FIELD...]`:",
+            "",
+            "| Field | Generates |",
+            "| --- | --- |",
+            *(f"| `{_escape(syntax)}` | {_escape(result)} |" for syntax, result in FIELD_DOCS),
+            "",
+        ]
+    for name, sub in _subcommands(command).items():
+        if not sub.hidden:
+            out += _command(f"{path} {name}", sub, level + 1)
+    return out
+
+
+def render(app: typer.Typer | None = None) -> str:
+    """docs/cli.md for ``app`` (default: the ``karni`` app)."""
+    if app is None:
+        from karni_cli.main import app as karni_app
+
+        app = karni_app
+    root = typer.main.get_command(app)
+    visible = {name: cmd for name, cmd in _subcommands(root).items() if not cmd.hidden}
+    placed = {name for _, names in SECTIONS for name in names}
+    sections = [*SECTIONS, ("Other", tuple(n for n in visible if n not in placed))]
+    out = [HEADER, "## Contents", ""]
+    for title, names in sections:
+        present = [n for n in names if n in visible]
+        if present:
+            links = ", ".join(f"[{n}](#karni-{n})" for n in present)
+            out.append(f"- **{title}**: {links}")
+    out.append("")
+    for title, names in sections:
+        present = [n for n in names if n in visible]
+        if not present:
+            continue
+        out += [f"## {title}", ""]
+        for name in present:
+            out += _command(name, visible[name], 3)
+    return "\n".join(out).rstrip("\n") + "\n"
+
+
+def main() -> None:
+    typer.echo(render(), nl=False)
+
+
+if __name__ == "__main__":
+    main()