karni-cli 0.3.1__py3-none-any.whl

karni_cli/generators/viewset.py

@@ -0,0 +1,179 @@
+"""``karni make viewset <Model>`` — a BaseViewSet with its mandatory ``access``.
+
+ADR 0001 Q2.1: every viewset declares who reads and who writes. The default
+is ``Granted()`` (ADR 0002, P2): the roles' grants for the model, row scope
+included, so a generated viewset is scoped without anyone remembering to
+scope it. ``--access`` picks one of the other common shapes; whichever
+applies is printed so it is never silent. Anything richer (``Owned(...) |
+HasRole(...)``, ``Where(...)``) is an edit of the generated declaration.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+
+import typer
+
+from karni_cli.generators.core import (
+    APP_OPTION,
+    DRY_RUN_OPTION,
+    FORCE_OPTION,
+    App,
+    Workspace,
+    project_workspace,
+    resolve_app,
+    split_csv,
+)
+from karni_cli.generators.introspect import ModelInfo, require_model, viewsets_file
+from karni_cli.generators.naming import default_route, require_pascal
+from karni_cli.generators.pysource import (
+    Import,
+    call,
+    ensure_imports,
+    parse,
+    pystr,
+    replace_or_append,
+    tuple_literal,
+)
+from karni_cli.project import CliError
+
+NAME = "viewset"
+SUMMARY = "Add a BaseViewSet for a model, with its access declaration (--access)."
+
+DEFAULT_ACCESS = "granted"
+ACCESS_CHOICES = "granted|authenticated|public-read|owned:<field>|staff|role:<name>"
+_ROLE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]*$")
+_PATH = re.compile(r"^[a-z_][a-z0-9_]*(__[a-z_][a-z0-9_]*)*$")
+
+
+def access_declaration(spec: str, model: ModelInfo | None) -> tuple[list[str], list[str]]:
+    """``(Access(...) keyword arguments, predicate names to import)`` for ``--access``.
+
+    ``granted`` is the bare ``Granted()`` declaration: ``(["Granted()"], ["Granted"])``.
+    """
+    kind, _, arg = spec.partition(":")
+    if kind == "granted" and not arg:
+        return ["Granted()"], ["Granted"]
+    if kind == "authenticated" and not arg:
+        return ["read=Authenticated()", "write=Authenticated()"], ["Authenticated"]
+    if kind == "public-read" and not arg:
+        return ["read=Public()", "write=Authenticated()"], ["Authenticated", "Public"]
+    if kind == "staff" and not arg:
+        return ['read=HasRole("staff")', 'write=HasRole("staff")'], ["HasRole"]
+    if kind == "role":
+        if not _ROLE.match(arg):
+            raise CliError(
+                f"--access role:<name> needs a role (group) name, got {spec!r}.", code="C106"
+            )
+        role = pystr(arg)
+        return [f"read=HasRole({role})", f"write=HasRole({role})"], ["HasRole"]
+    if kind == "owned":
+        if not _PATH.match(arg):
+            raise CliError(
+                "--access owned:<field> needs the relation to the user, e.g. owned:organizer "
+                f'or owned:event__organizer (got {spec!r}). Owned("created_by") only when '
+                "whoever created the row is its owner.",
+                code="C106",
+            )
+        first = arg.split("__", 1)[0]
+        if model is not None and not model.is_relation(first):
+            raise CliError(
+                f"--access {spec}: {model.name}.{first} is not a relation field. Owned() needs "
+                f"a ForeignKey to the user, e.g. add owner:fk:User to {model.name} first.",
+                code="C106",
+            )
+        path = pystr(arg)
+        return [f"read=Owned({path})", f"write=Owned({path})"], ["Owned"]
+    raise CliError(f"--access {spec!r}: choose one of {ACCESS_CHOICES}.", code="C106")
+
+
+def plan(
+    ws: Workspace,
+    app: App,
+    model_name: str,
+    *,
+    access: str | None,
+    search: list[str],
+) -> str:
+    """Plan ``<Model>ViewSet`` in the app's viewsets module; returns its route."""
+    model = require_model(ws, app, model_name)
+    declaration, predicates = access_declaration(access or DEFAULT_ACCESS, model)
+    for name in search:
+        if not model.has_field(name):
+            raise CliError(f"--search {name}: {model.name} has no field {name!r}.", code="C106")
+    path = viewsets_file(ws, app)
+    rel = ws.rel(path)
+    text = ws.read(path) or ""
+    class_name = f"{model.name}ViewSet"
+    if text:
+        for node in parse(ws, rel, text).body:
+            if isinstance(node, ast.ClassDef) and node.name != class_name:
+                for stmt in node.body:
+                    if (
+                        isinstance(stmt, ast.Assign)
+                        and isinstance(stmt.value, ast.Name)
+                        and stmt.value.id == model.name
+                        and any(isinstance(t, ast.Name) and t.id == "model" for t in stmt.targets)
+                    ):
+                        raise CliError(
+                            f"{rel} already routes {model.name} through {node.name} — edit "
+                            "that class (or delete it first).",
+                            code="C107",
+                        )
+    line = ws.line_length
+    body = [f"class {class_name}(BaseViewSet):", f"    model = {model.name}"]
+    granted = predicates == ["Granted"]
+    if granted:
+        body.append("    access = Granted()")
+        imports = [Import("karni.api", name) for name in ("BaseViewSet", "Granted")]
+        shown = "Granted()"
+    else:
+        body.append(call("access = Access", declaration, "    ", line))
+        imports = [Import("karni.api", name) for name in ("Access", "BaseViewSet", *predicates)]
+        shown = "Access(" + ", ".join(declaration) + ")"
+    if search:
+        # A tuple: a list class attribute is a mutable default (ruff RUF012).
+        body.append(tuple_literal("search_fields = ", [pystr(s) for s in search], "    ", line))
+    block = "\n".join(body)
+    imports.append(Import(model.import_module, model.name))
+    text = ensure_imports(ws, rel, text, imports)
+    ws.write(path, replace_or_append(ws, rel, text, class_name, block))
+    if access is None:
+        ws.note(
+            f"access: {shown} — the default: what KARNI_ROLES grants for {model.name}, "
+            f"row-scoped; choose with --access {ACCESS_CHOICES}"
+        )
+    else:
+        ws.note(f"access: {shown}")
+    route = default_route(model.name)
+    ws.note(f"route: /api/{route}/ (auto-registered)")
+    return route
+
+
+def command(
+    model: str = typer.Argument(..., help="Model class name (e.g. Event)."),
+    access: str | None = typer.Option(
+        None,
+        "--access",
+        help=f"Who reads/writes: {ACCESS_CHOICES}. Default: granted (the roles' grants).",
+    ),
+    search: list[str] | None = typer.Option(
+        None, "--search", help="search_fields, comma-separated or repeated (e.g. title,venue)."
+    ),
+    app: str | None = APP_OPTION,
+    force: bool = FORCE_OPTION,
+    dry_run: bool = DRY_RUN_OPTION,
+) -> None:
+    """Add `<Model>ViewSet(BaseViewSet)` to APP/viewsets.py — CRUD at /api/<models>/.
+
+    Declares `model = <Model>` and the mandatory `access` (ADR 0001):
+    granted (default: whatever KARNI_ROLES grants for the model, row-scoped),
+    authenticated, public-read (anonymous reads), owned:<field> (rows whose
+    <field> is the user), staff (role "staff"), role:<name>.
+    """
+    ws = project_workspace(force)
+    target = resolve_app(ws, app)
+    name = require_pascal(model.removesuffix("ViewSet"), "Model")
+    plan(ws, target, name, access=access, search=split_csv(search))
+    ws.commit(dry_run=dry_run)

karni_cli/history.py

@@ -0,0 +1,59 @@
+"""The CLI's side of history providers (``karni.agent.history``).
+
+Providers run in the CLI's own environment, through
+:func:`karni_cli.agent_data.history_module` (karni's copy, else the bundled
+one). With no module, no provider or no store, every function here answers
+"nothing" — Karni behaves exactly as if history did not exist.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from karni_cli import agent_data
+from karni_cli.project import CliError
+
+
+def target(project: Path, raw: str) -> str:
+    """``raw`` (relative to the cwd, or absolute) as a project-relative POSIX path."""
+    candidate = Path(raw).expanduser()
+    absolute = (candidate if candidate.is_absolute() else Path.cwd() / candidate).resolve()
+    try:
+        relative = absolute.relative_to(project.resolve())
+    except ValueError:
+        raise CliError(f"{raw} is outside the project ({project}).", code="C010") from None
+    if relative == Path("."):
+        raise CliError("--with-history PATH names a file, not the project root.", code="C010")
+    return relative.as_posix()
+
+
+def block(project: Path, path: str | None) -> str | None:
+    """The capped ``HISTORY:`` block for ``path`` (or the project), or ``None``."""
+    module = agent_data.history_module()
+    if module is None:
+        return None
+    result = module.compose(project, path)
+    return result if isinstance(result, str) and result else None
+
+
+def discovered() -> Any | None:
+    """:class:`karni.agent.history.Discovered`, or ``None`` without the module."""
+    module = agent_data.history_module()
+    return None if module is None else module.discover()
+
+
+def detected_names(project: Path) -> list[str]:
+    module = agent_data.history_module()
+    if module is None:
+        return []
+    return [provider.name for provider in module.detected(project)]
+
+
+def provider_present(project: Path) -> bool:
+    """A provider detects a store here, or a third-party provider is installed."""
+    module = agent_data.history_module()
+    if module is None:
+        return False
+    found = module.discover()
+    return bool(found.third_party()) or module.store_detected(project, found.providers)

karni_cli/local_state.py

@@ -0,0 +1,73 @@
+"""Machine-local CLI state: ``.karni/local/state.json`` in the project.
+
+Never committed: ``.karni/local/`` carries its own ``.gitignore`` (``*``), so
+it stays untracked in any project without touching the root ``.gitignore``
+(the scaffold's ``.gitignore`` lists it too). Holds what must not be shared
+with the team — e.g. that a one-time tip was already shown on this machine.
+Unreadable or corrupt state reads as empty; a failed write is reported to the
+caller, never raised.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+LOCAL_DIR = Path(".karni") / "local"
+STATE_FILE = "state.json"
+GITIGNORE = "# Machine-local karni state (karni_cli.local_state); never commit it.\n*\n"
+
+
+def state_path(project: Path) -> Path:
+    return project / LOCAL_DIR / STATE_FILE
+
+
+def read_state(project: Path) -> dict[str, Any]:
+    try:
+        data = json.loads(state_path(project).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def write_state(project: Path, state: dict[str, Any]) -> bool:
+    """Write ``state`` atomically (creating the self-ignoring directory); False on failure."""
+    directory = project / LOCAL_DIR
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        ignore = directory / ".gitignore"
+        if not ignore.is_file():
+            ignore.write_text(GITIGNORE, encoding="utf-8")
+        fd, tmp = tempfile.mkstemp(dir=directory, prefix=".state-", suffix=".json")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump(state, handle, indent=2, sort_keys=True)
+                handle.write("\n")
+            os.replace(tmp, directory / STATE_FILE)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                os.unlink(tmp)
+            raise
+    except (OSError, TypeError, ValueError):
+        return False
+    return True
+
+
+def tip_shown(project: Path, tip: str) -> bool:
+    shown = read_state(project).get("tips_shown")
+    return isinstance(shown, dict) and tip in shown
+
+
+def mark_tip_shown(project: Path, tip: str) -> bool:
+    state = read_state(project)
+    shown = state.get("tips_shown")
+    if not isinstance(shown, dict):
+        shown = {}
+    shown[tip] = datetime.now(UTC).isoformat(timespec="seconds")
+    state["tips_shown"] = shown
+    return write_state(project, state)

karni_cli/main.py

@@ -0,0 +1,104 @@
+"""Entry point for the ``karni`` command."""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli import __version__
+from karni_cli.commands.add import add
+from karni_cli.commands.beat import beat
+from karni_cli.commands.check import check
+from karni_cli.commands.config import config_app
+from karni_cli.commands.context import context
+from karni_cli.commands.createsuperuser import createsuperuser
+from karni_cli.commands.doctor import doctor
+from karni_cli.commands.explain import explain
+from karni_cli.commands.make import make_app, register_aliases
+from karni_cli.commands.manage_passthrough import manage
+from karni_cli.commands.mcp import mcp
+from karni_cli.commands.migrate import migrate
+from karni_cli.commands.new import new
+from karni_cli.commands.routes import routes
+from karni_cli.commands.rules import rules_app
+from karni_cli.commands.run_tests import test
+from karni_cli.commands.schedule import schedule_app
+from karni_cli.commands.seed import seed
+from karni_cli.commands.serve import serve
+from karni_cli.commands.shell import shell
+from karni_cli.commands.sync_roles import sync_roles
+from karni_cli.commands.types import types
+from karni_cli.commands.upgrade import upgrade
+from karni_cli.commands.worker import worker
+from karni_cli.project import PASSTHROUGH, CliError
+
+app = typer.Typer(
+    name="karni",
+    help="The Karni framework CLI.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _show_version(value: bool) -> None:
+    if value:
+        typer.echo(f"karni-cli {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_show_version,
+        is_eager=True,
+        help="Print the karni-cli version and exit (the project's karni: karni doctor).",
+    ),
+) -> None:
+    """The Karni framework CLI."""
+
+
+app.command(help="Scaffold a project from templates/project")(new)
+app.command(help="Install an optional module and wire it into settings")(add)
+app.command(help="Generate TS types and typed hooks from the backend OpenAPI")(types)
+app.command(help="Print a compact machine-readable project inventory")(context)
+app.command(help="Run architecture and system checks")(check)
+app.command(help="Upgrade across Karni versions: codemods, diff, manual-change report")(upgrade)
+app.add_typer(rules_app, name="rules")
+app.command(help="Serve context, rules and check as MCP tools (needs karni-cli[mcp])")(mcp)
+app.command(help="Report the environment: project, interpreter, Node, adapters, history")(doctor)
+app.command(help="Explain an error code (E104, C101, PAY004, K106): why and the fix")(explain)
+app.add_typer(config_app, name="config")
+
+# Runners: each wraps one project command (named in its --help), run through
+# the project interpreter (.venv, else the running compose service).
+app.command()(serve)
+app.command(context_settings=PASSTHROUGH)(migrate)
+app.command(context_settings=PASSTHROUGH)(test)
+app.command(context_settings=PASSTHROUGH)(shell)
+app.command()(routes)
+app.command(context_settings=PASSTHROUGH)(worker)
+app.command(context_settings=PASSTHROUGH)(beat)
+app.add_typer(schedule_app, name="schedule")
+app.command(context_settings=PASSTHROUGH)(seed)
+app.command("sync-roles", context_settings=PASSTHROUGH)(sync_roles)
+app.command(context_settings=PASSTHROUGH)(createsuperuser)
+app.command(context_settings=PASSTHROUGH)(manage)
+
+# Generators: `karni make <type>` (+ hidden `karni make:<type>` aliases).
+app.add_typer(make_app, name="make")
+register_aliases(app)
+
+
+def run() -> None:
+    """Console-script entry that renders CliError without a traceback."""
+    try:
+        app(standalone_mode=True)
+    except CliError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    run()

karni_cli/mcp_server.py

@@ -0,0 +1,103 @@
+"""``karni mcp`` — Karni's agent surface as MCP tools (stdio).
+
+Tools: ``context`` (the ``karni context`` inventory), ``rules`` (the
+conventions, one rule in full, or a procedure) and ``check`` (static
+violations for one file). The tool functions are plain functions so they are
+testable without a client; :func:`build_server` registers them on the
+official MCP Python SDK server (``pip install 'karni-cli[mcp]'``): ``MCPServer``
+in mcp 2.x, ``FastMCP`` in mcp 1.x.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from karni_cli import agent_data
+from karni_cli.adapters import module_fragments
+from karni_cli.commands.context import build_context_text
+from karni_cli.commands.rules import check_text
+from karni_cli.project import CliError, find_project
+from karni_cli.rules_render import render_explain, render_procedure, render_rules
+
+INSTRUCTIONS = (
+    "Karni project tools. Call `context` and `rules` before any work and follow what they "
+    "return; call `check` on every file you write."
+)
+
+_project_override: Path | None = None
+
+
+def _project() -> Path | None:
+    return _project_override or find_project()
+
+
+def context_tool() -> str:
+    """Live project inventory: apps, models, viewsets, UI components, hooks, pages, modules."""
+    project = _project()
+    if project is None:
+        return "error: not inside a Karni project (no manage.py found)."
+    try:
+        return build_context_text(project)
+    except CliError as exc:
+        return f"error: {exc}"
+
+
+def rules_tool(code: str = "", procedure: str = "") -> str:
+    """Karni conventions. No arguments: every rule's code + summary. ``code``: one rule in
+    full (why + fix). ``procedure``: steps for new-model, new-page, add-module or new-module."""
+    project = _project()
+    try:
+        data = agent_data.load(project)
+    except CliError as exc:
+        return f"error: {exc}"
+    if code:
+        rule = data.rule(code)
+        return render_explain(rule) if rule else f"error: no rule {code!r}"
+    if procedure:
+        found = data.procedure(procedure)
+        return render_procedure(found) if found else f"error: no procedure {procedure!r}"
+    return render_rules(data, module_fragments(project) if project else {})
+
+
+def check_tool(path: str) -> str:
+    """Static check of one file against Karni's rules; returns violations with fixes."""
+    project = _project()
+    target = Path(path)
+    if not target.is_absolute() and project is not None:
+        target = project / target
+    try:
+        text, _count = check_text([target], project)
+    except CliError as exc:
+        return f"error: {exc}"
+    return text
+
+
+TOOLS: dict[str, Any] = {"context": context_tool, "rules": rules_tool, "check": check_tool}
+
+
+def _server_class() -> Any:
+    try:
+        from mcp.server.mcpserver import MCPServer
+
+        return MCPServer
+    except ImportError:
+        pass
+    try:
+        from mcp.server.fastmcp import FastMCP  # type: ignore[attr-defined,unused-ignore]
+
+        return FastMCP
+    except ImportError:
+        raise CliError(
+            "karni mcp needs the MCP SDK: pip install 'karni-cli[mcp]'", code="C006"
+        ) from None
+
+
+def build_server(project: Path | None = None) -> Any:
+    """The configured (not yet running) MCP server."""
+    global _project_override
+    _project_override = project
+    server = _server_class()(name="karni", instructions=INSTRUCTIONS)
+    for name, function in TOOLS.items():
+        server.tool(name=name, description=function.__doc__)(function)
+    return server