karni-cli 0.3.1__py3-none-any.whl

karni_cli/commands/add.py

@@ -0,0 +1,144 @@
+"""``karni add <module>`` — wire an optional Karni module into the project.
+
+Wiring: dependency in ``pyproject.toml`` + app in the ``# karni:apps``
+marker block + the module's ``AGENTS.fragment.md`` recorded as
+``.karni/modules/<module>.md`` (project-owned, committed), from which
+``karni rules`` and the generated adapters (``karni rules sync``: AGENTS.md
+between ``<!-- karni:module:<module> -->`` markers) take the module's
+guidance. The fragment is read **through the project's interpreter** — the
+CLI never imports project code itself — so it is only recorded once the
+module is actually installed; until then the command says to run again
+after installing.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import tomlkit
+import typer
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+from karni_cli import agent_data
+from karni_cli.adapters import MODULES_DIR, sync
+from karni_cli.project import (
+    CliError,
+    compose_service_running,
+    require_project,
+    venv_python,
+)
+from karni_cli.settings_edit import add_app
+
+
+def _add_dependency(project_root: str, distribution: str) -> bool:
+    """Add the distribution to [project].dependencies. Returns False when present."""
+    pyproject = Path(project_root) / "pyproject.toml"
+    if not pyproject.is_file():
+        raise CliError("No pyproject.toml in the project root.", code="C207")
+    doc = tomlkit.parse(pyproject.read_text())
+    try:
+        deps = doc["project"]["dependencies"]
+    except (KeyError, TypeError):
+        raise CliError(
+            "pyproject.toml has no [project].dependencies table — "
+            "karni add only manages that table; add the dependency manually.",
+            code="C207",
+        ) from None
+    target = canonicalize_name(distribution)
+    for dep in deps:
+        try:
+            if canonicalize_name(Requirement(str(dep)).name) == target:
+                return False
+        except InvalidRequirement:
+            continue
+    deps.append(distribution)
+    pyproject.write_text(tomlkit.dumps(doc))
+    return True
+
+
+def _read_agents_fragment(project: Path, app_name: str) -> str | None:
+    """Read the installed module's ``AGENTS.fragment.md`` via the project interpreter.
+
+    Resolution mirrors the CLI's execution order: the project ``.venv``
+    first, then a running compose ``django`` service. Returns ``None`` when
+    no interpreter is reachable or the subprocess fails (module not
+    installed yet, no fragment shipped) — the caller falls back to the
+    "run again after installing" message.
+    """
+    code = (
+        "import importlib.resources as resources; "
+        f"print(resources.files({app_name!r}).joinpath('AGENTS.fragment.md')"
+        ".read_text(encoding='utf-8'), end='')"
+    )
+    python = venv_python(project)
+    if python is not None:
+        command = [str(python), "-c", code]
+    elif compose_service_running(project, "django"):
+        command = ["docker", "compose", "exec", "-T", "django", "python", "-c", code]
+    else:
+        return None
+    try:
+        proc = subprocess.run(command, cwd=project, text=True, capture_output=True, check=False)
+    except OSError:
+        return None
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    return proc.stdout
+
+
+def record_module_fragment(project: Path, module: str, fragment: str) -> bool:
+    """Store the module's guidance under ``.karni/modules/``. Returns True when changed."""
+    target = project / MODULES_DIR / f"{module}.md"
+    content = fragment.strip() + "\n"
+    if target.is_file() and target.read_text(encoding="utf-8") == content:
+        return False
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    return True
+
+
+def _refresh_adapters(project: Path) -> None:
+    try:
+        result = sync(project, agent_data.load(project))
+    except CliError as exc:
+        typer.echo(f"Agent adapters not refreshed ({exc}) — run `karni rules sync`.")
+        return
+    for rel in result.written:
+        typer.echo(f"{rel}: refreshed")
+    for rel in result.blocked:
+        typer.echo(
+            f"{rel}: not generated by karni, left untouched — run `karni upgrade` or "
+            "`karni rules sync --force`."
+        )
+
+
+def add(module: str = typer.Argument(..., help='Module short name, e.g. "payments"')) -> None:
+    project = require_project()
+    app_name = f"karni_{module.replace('-', '_')}"
+    distribution = f"karni-{module.replace('_', '-')}"
+
+    dep_added = _add_dependency(str(project), distribution)
+    app_added = add_app(project / "config" / "settings.py", app_name)
+
+    typer.echo(f"{distribution}: {'added to' if dep_added else 'already in'} pyproject.toml")
+    typer.echo(f"{app_name}: {'wired into' if app_added else 'already in'} INSTALLED_APPS")
+
+    fragment = _read_agents_fragment(project, app_name)
+    if fragment is None:
+        typer.echo(
+            f"{app_name} is not importable yet — run `karni add {module}` again "
+            "after installing to record its agent guidance."
+        )
+    else:
+        if record_module_fragment(project, module, fragment):
+            typer.echo(f"{(MODULES_DIR / f'{module}.md').as_posix()}: recorded agent guidance")
+        _refresh_adapters(project)
+
+    typer.echo("If the module ships URLs, add the include to config/urls.py:")
+    typer.echo(f'  path("{module}/", include("{app_name}.urls"))')
+    typer.echo("Install it, then migrate:")
+    typer.echo("  docker compose build        # container workflow")
+    typer.echo("  uv pip install -r pyproject.toml   # host venv workflow")
+    typer.echo("  make migrate")

karni_cli/commands/beat.py

@@ -0,0 +1,36 @@
+"""``karni beat`` — Celery beat (the scheduler) through the project interpreter.
+
+Beat merges every ``<app>/schedules.py`` declaration into its schedule at
+startup (``karni.schedule``); list them with ``karni schedule list``. With
+the docker compose stack up, a ``beat`` service already runs — run only one.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.commands.worker import celery_args
+from karni_cli.project import require_project
+
+
+def beat(
+    args: list[str] | None = typer.Argument(None, help="Passed to celery beat."),
+    celery_app: str = typer.Option(
+        "config", "--app", "-A", envvar="KARNI_CELERY_APP", help="Celery app module."
+    ),
+    loglevel: str = typer.Option("info", "--loglevel", "-l"),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Run Celery beat — wraps `python -m celery -A config beat -l info [ARGS]`."""
+    project = require_project()
+    proc = project_mod.run_python(
+        project,
+        celery_args(celery_app, "beat", loglevel, args),
+        docker=docker,
+        service=service,
+        capture=False,
+        interactive=True,
+    )
+    raise typer.Exit(proc.returncode)

karni_cli/commands/check.py

@@ -0,0 +1,101 @@
+"""``karni check`` — backend checks plus frontend duplicate detection.
+
+Runs ``manage.py karni_check`` (system checks + ``karni.checks`` hooks,
+including the architecture and duplication rules) and, when ``frontend/``
+exists, jscpd via the project's own pinned binary driven solely by
+``frontend/.jscpd.json``. Both steps always run; the exit code aggregates
+both and each step's output is shown.
+
+Outside CI, a clean run may end with one tip on stderr (:mod:`karni_cli.tips`,
+at most once per project); ``-q`` suppresses it.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli import tips
+from karni_cli.project import require_project
+
+_BARE_IGNORE = re.compile(r"jscpd:ignore-start\s*$")
+
+
+def _frontend_duplication(project: Path) -> int:
+    frontend = project / "frontend"
+    if not frontend.is_dir():
+        return 0
+    jscpd = frontend / "node_modules" / ".bin" / "jscpd"
+    if not jscpd.exists():
+        typer.echo(
+            "karni check: jscpd not installed — run `npm install` in frontend/ "
+            "(or pass --no-frontend to skip frontend duplication checks).",
+            err=True,
+        )
+        return 1
+    # Reason-required opt-outs: a bare jscpd:ignore-start (no reason after it)
+    # is itself a failure; ignore-end legitimately carries nothing.
+    bare = [
+        f"{path.relative_to(project)}:{lineno}"
+        for path in (frontend / "src").rglob("*.ts*")
+        for lineno, line in enumerate(path.read_text().splitlines(), start=1)
+        if _BARE_IGNORE.search(line)
+    ]
+    if bare:
+        for location in bare:
+            typer.echo(f"[duplicate] {location}: jscpd:ignore-start requires a reason", err=True)
+        return 1
+    proc = subprocess.run(
+        [str(jscpd), "--config", ".jscpd.json"],
+        cwd=frontend,
+        text=True,
+        check=False,
+    )
+    return proc.returncode
+
+
+def _frontend_lint(project: Path) -> int:
+    """``eslint .`` in frontend/ with the project's own binary (the @karni/ui rules live there)."""
+    frontend = project / "frontend"
+    if not frontend.is_dir():
+        return 0
+    eslint = frontend / "node_modules" / ".bin" / "eslint"
+    if not eslint.exists():
+        typer.echo(
+            "karni check: eslint not installed — run `npm install` in frontend/ "
+            "(or pass --no-frontend to skip the frontend checks).",
+            err=True,
+        )
+        return 1
+    proc = subprocess.run(
+        [str(eslint), ".", "--max-warnings", "0"], cwd=frontend, text=True, check=False
+    )
+    return proc.returncode
+
+
+def check(
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+    frontend: bool = typer.Option(True, "--frontend/--no-frontend"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Do not print the optional tip."),
+) -> None:
+    project = require_project()
+    backend = project_mod.run_manage(
+        project, ["karni_check"], docker=docker, service=service, capture=False
+    ).returncode
+    dup = _frontend_duplication(project) if frontend else 0
+    lint = _frontend_lint(project) if frontend else 0
+    if backend or dup or lint:
+        sys.stderr.write("karni check: FAILED\n")
+    else:
+        # Only after a clean run (failures deserve the attention), never in CI,
+        # and on stderr so stdout stays exactly the checks' output.
+        tip = tips.history_tip(project, quiet=quiet)
+        if tip:
+            sys.stderr.write(f"\n{tip}\n")
+    raise typer.Exit(1 if (backend or dup) else 0)

karni_cli/commands/config.py

@@ -0,0 +1,81 @@
+"""``karni config`` — read and write Karni CLI settings.
+
+karni config list                       every setting, its value and where it comes from
+karni config get suggest_tools          the effective value (project > global > default)
+karni config set suggest_tools false    write it to .karni/config.toml (committed)
+karni config set --global KEY VALUE     write it to ~/.config/karni/config.toml
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from karni_cli import config as config_mod
+from karni_cli.project import CliError, find_project
+
+config_app = typer.Typer(
+    help=(
+        "Read and write Karni settings: project .karni/config.toml (committed) or "
+        "--global ~/.config/karni/config.toml; the project wins."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+_GLOBAL_HELP = "Use the global file ($XDG_CONFIG_HOME/karni/config.toml) only."
+
+
+def _source(value: config_mod.Value, project: Path | None) -> str:
+    if value.path is None:
+        return value.source
+    shown: Path = value.path
+    if project is not None:
+        try:
+            shown = value.path.relative_to(project)
+        except ValueError:
+            pass
+    return f"{value.source}: {shown}"
+
+
+@config_app.command("get")
+def get_command(
+    key: str = typer.Argument(..., help="Setting name (see `karni config list`)."),
+    global_: bool = typer.Option(False, "--global", help=_GLOBAL_HELP),
+) -> None:
+    """Print the effective value of KEY."""
+    value = config_mod.resolve(key, find_project(), global_only=global_)
+    typer.echo(config_mod.render(value.value))
+
+
+@config_app.command("set")
+def set_command(
+    key: str = typer.Argument(..., help="Setting name (see `karni config list`)."),
+    value: str = typer.Argument(..., help="New value (true/false)."),
+    global_: bool = typer.Option(False, "--global", help=_GLOBAL_HELP),
+) -> None:
+    """Set KEY to VALUE in the project file (or --global)."""
+    parsed = config_mod.parse(key, value)
+    if global_:
+        path = config_mod.global_path()
+    else:
+        project = find_project()
+        if project is None:
+            raise CliError(
+                "Not inside a Karni project (no manage.py here or above) — "
+                "use --global to set it for every project.",
+                code="C001",
+            )
+        path = config_mod.project_path(project)
+    config_mod.write(key, parsed, path)
+    typer.echo(f"{key} = {config_mod.render(parsed)} ({path})")
+
+
+@config_app.command("list")
+def list_command() -> None:
+    """Every setting with its effective value and source."""
+    project = find_project()
+    for name in sorted(config_mod.KEYS):
+        value = config_mod.resolve(name, project)
+        typer.echo(f"{name} = {config_mod.render(value.value)}  # {_source(value, project)}")

karni_cli/commands/context.py

@@ -0,0 +1,171 @@
+"""``karni context`` — the token-efficiency mechanism.
+
+Backend inventory comes from ``manage.py karni_context``; COMPONENTS/HOOKS
+come from @karni/ui's build-generated dist/manifest.json. Absent manifest →
+those lines are omitted entirely (never stale, never guessed). Two lines are
+read statically from the project tree (no Django): APPS — the local apps in
+the ``# karni:apps`` block that live in this project — and PAGES — the files
+under ``frontend/src/pages/``. Together with ``karni rules`` this is enough
+for an agent to start work without reading files.
+
+``--with-history [PATH]`` appends a ``HISTORY:`` block from any history
+provider that detects a store (``karni.agent.history``), capped at ~300
+tokens; with no store the output is byte-identical to plain ``karni context``.
+stdout stays machine-clean in every mode: no tips, no warnings.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+import typer
+
+from karni_cli import history
+from karni_cli import project as project_mod
+from karni_cli.project import CliError, require_project
+from karni_cli.settings_edit import MARKER
+
+#: Mirrors karni.agent.history.HISTORY_TOKEN_CAP (that module enforces it); a
+#: constant here keeps `karni context --help` free of provider discovery.
+HISTORY_TOKEN_CAP = 300
+
+_PAGE_SUFFIXES = (".tsx", ".ts", ".jsx", ".js")
+_QUOTED = re.compile(r"""["']([^"']+)["']""")
+
+
+def find_manifest(project: Path, explicit: Path | None) -> Path | None:
+    if explicit is not None:
+        return explicit if explicit.is_file() else None
+    for base in (project / "frontend", project):
+        candidate = base / "node_modules" / "@karni" / "ui" / "dist" / "manifest.json"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def manifest_lines(manifest_path: Path) -> list[str]:
+    try:
+        data = json.loads(manifest_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return []
+    lines: list[str] = []
+    if data.get("components"):
+        lines.append("COMPONENTS: " + " ".join(sorted(data["components"])))
+    if data.get("hooks"):
+        lines.append("HOOKS: " + " ".join(sorted(data["hooks"])))
+    return lines
+
+
+def apps_line(project: Path) -> str | None:
+    """Local apps wired in the ``# karni:apps`` block, as ``label(path/)``."""
+    settings = project / "config" / "settings.py"
+    if not settings.is_file():
+        return None
+    lines = settings.read_text().splitlines()
+    end = next((i for i, line in enumerate(lines) if MARKER in line), None)
+    if end is None:
+        return None
+    start = next(
+        (i for i in range(end, -1, -1) if "INSTALLED_APPS" in lines[i] and "[" in lines[i]), end
+    )
+    names: list[str] = []
+    for line in lines[start : end + 1]:
+        code = line.split("#", 1)[0]
+        names += _QUOTED.findall(code)
+    found = []
+    for name in names:
+        module = name.split(".apps.", 1)[0]
+        path = Path(*module.split("."))
+        if (project / path).is_dir():
+            found.append(f"{module.rsplit('.', 1)[-1]}({path.as_posix()}/)")
+    return "APPS: " + " ".join(found) if found else None
+
+
+def pages_line(project: Path) -> str | None:
+    pages = project / "frontend" / "src" / "pages"
+    if not pages.is_dir():
+        return None
+    found = sorted(
+        path.relative_to(pages).with_suffix("").as_posix()
+        for path in pages.rglob("*")
+        if path.suffix in _PAGE_SUFFIXES and not path.name.endswith((".test.tsx", ".test.ts"))
+    )
+    return "PAGES: " + " ".join(found) if found else None
+
+
+def assemble(backend_output: str, ui_lines: list[str]) -> str:
+    """Merge UI lines into the backend sections, keeping the documented order
+    (MODELS, VIEWSETS, COMPONENTS, HOOKS, MODULES, BASES)."""
+    sections = [line for line in backend_output.split("\n") if line.strip()]
+    insert_at = next(
+        (i for i, line in enumerate(sections) if line.startswith(("MODULES:", "BASES:"))),
+        len(sections),
+    )
+    sections[insert_at:insert_at] = ui_lines
+    return "\n".join(sections)
+
+
+def build_context_text(
+    project: Path,
+    *,
+    docker: bool | None = None,
+    service: str = "django",
+    manifest: Path | None = None,
+) -> str:
+    """The full inventory: APPS, MODELS, VIEWSETS, COMPONENTS, HOOKS, PAGES, MODULES, BASES.
+
+    Raises :class:`CliError` when the backend inventory command fails.
+    """
+    proc = project_mod.run_manage(project, ["karni_context"], docker=docker, service=service)
+    if proc.stderr:
+        sys.stderr.write(proc.stderr)
+    if proc.returncode != 0:
+        raise CliError(f"manage.py karni_context failed (exit {proc.returncode}).", code="C009")
+    found = find_manifest(project, manifest)
+    ui_lines = manifest_lines(found) if found else []
+    pages = pages_line(project)
+    if pages:
+        ui_lines.append(pages)
+    text = assemble(proc.stdout, ui_lines)
+    apps = apps_line(project)
+    return f"{apps}\n{text}" if apps else text
+
+
+_WITH_HISTORY_HELP = (
+    "Append what a history provider (e.g. Gigai Chronicle) recorded about PATH under a "
+    "HISTORY: heading — without PATH, the project's recorded decisions, from providers "
+    f"that offer them. Capped at ~{HISTORY_TOKEN_CAP} tokens (~{4 * HISTORY_TOKEN_CAP} "
+    "characters), cut at line boundaries with a last line naming the command for the full "
+    "brief. With no history store detected, prints the plain inventory and nothing else."
+)
+
+
+def context(
+    path: str | None = typer.Argument(
+        None,
+        metavar="PATH",
+        help="File to brief, relative to the cwd (needs --with-history).",
+        show_default=False,
+    ),
+    with_history: bool = typer.Option(False, "--with-history", help=_WITH_HISTORY_HELP),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+    manifest: Path | None = typer.Option(None, "--manifest", help="Explicit manifest.json path"),
+) -> None:
+    if path is not None and not with_history:
+        raise typer.BadParameter("PATH is only used with --with-history.", param_hint="PATH")
+    project = require_project()
+    try:
+        target = history.target(project, path) if path is not None else None
+        text = build_context_text(project, docker=docker, service=service, manifest=manifest)
+    except CliError as exc:
+        sys.stderr.write(f"{exc}\n")
+        raise typer.Exit(1) from None
+    if with_history:
+        block = history.block(project, target)
+        if block:
+            text = f"{text}\n{block}"
+    typer.echo(text)

karni_cli/commands/createsuperuser.py

@@ -0,0 +1,28 @@
+"""``karni createsuperuser`` — create an admin user (prompts unless --noinput)."""
+
+from __future__ import annotations
+
+import typer
+
+from karni_cli import project as project_mod
+from karni_cli.project import require_project
+
+
+def createsuperuser(
+    args: list[str] | None = typer.Argument(
+        None, help="Passed to manage.py createsuperuser: --email E, --noinput …"
+    ),
+    docker: bool | None = typer.Option(None, "--docker/--no-docker"),
+    service: str = typer.Option("django", "--service", envvar="KARNI_COMPOSE_SERVICE"),
+) -> None:
+    """Create an admin user — wraps `manage.py createsuperuser [ARGS]`."""
+    project = require_project()
+    proc = project_mod.run_manage(
+        project,
+        ["createsuperuser", *(args or [])],
+        docker=docker,
+        service=service,
+        capture=False,
+        interactive=True,
+    )
+    raise typer.Exit(proc.returncode)