karni-cli 0.3.1__py3-none-any.whl

karni_cli/_templates/project/{{cookiecutter.project_slug}}/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "{{ cookiecutter.project_slug }}"
+version = "0.1.0"
+description = "{{ cookiecutter.project_name }} — a Karni project."
+requires-python = ">=3.12"
+dependencies = [
+    "karni",
+    "gunicorn",
+    "uvicorn-worker",
+    "psycopg[binary]",
+]
+
+[dependency-groups]
+# factory-boy and Faker come with karni (karni.testing factories, `karni seed`).
+dev = [
+    "pytest",
+    "pytest-django",
+]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "config.settings"
+# tests/ plus every app's own tests/ (`karni make test <Model>` writes there).
+# modules/ is left out: each module runs its own suite with its own settings.
+testpaths = ["tests", "*/tests"]
+# Karni's architecture rules run as a SEPARATE invocation (never via addopts):
+#   pytest --pyargs karni.testing.architecture
+
+[tool.karni]
+# The Karni release this project was generated for. `karni upgrade` starts
+# from here (or from the installed karni, whichever is newer).
+baseline = "{{ cookiecutter.karni_baseline }}"

karni_cli/_templates/project/{{cookiecutter.project_slug}}/tests/test_api_schema.py

@@ -0,0 +1,17 @@
+"""The API contract: the OpenAPI schema must match tests/openapi.snapshot.json.
+
+The first local run writes the snapshot — commit it. From then on any change
+to the API (a removed field, a changed type, a new endpoint) fails here with
+the changes listed. Accept an intended change with
+`KARNI_UPDATE_SNAPSHOTS=1 karni test` and commit the updated file. CI never
+writes a snapshot.
+"""
+
+import pytest
+
+from karni.testing import assert_schema_snapshot
+
+
+@pytest.mark.django_db
+def test_the_api_contract_is_unchanged():
+    assert_schema_snapshot()

karni_cli/_templates/project/{{cookiecutter.project_slug}}/tests/test_smoke.py

@@ -0,0 +1,11 @@
+"""Project test suite. Karni's architecture rules run separately in CI:
+
+    pytest --pyargs karni.testing.architecture
+"""
+
+import pytest
+
+
+@pytest.mark.django_db
+def test_health_liveness(client):
+    assert client.get("/health/").status_code == 200

karni_cli/adapters.py

@@ -0,0 +1,373 @@
+"""Thin per-tool agent adapters, generated from data (``karni rules sync``).
+
+Inputs, and nothing else: the adapter registry (``agent_adapters.toml``), the
+rule/procedure data (:mod:`karni_cli.agent_data`), the project's
+``karni.rules.py`` adapter overrides, the module guidance recorded by
+``karni add`` under ``.karni/modules/`` and the project name in
+``pyproject.toml``. Same inputs, same bytes — which is what makes
+``karni rules sync --check`` a reliable CI staleness gate.
+
+Safety: sync only overwrites files that carry the generated marker. A
+hand-written file in an adapter's place is reported, never clobbered, unless
+``--force`` (which backs it up under ``.karni/backup/`` first).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import tomllib
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from karni_cli.agent_data import AgentData
+from karni_cli.project import CliError
+
+GENERATED_MARK = "Generated by `karni rules sync`"
+MARKER_LINE = (
+    f"<!-- {GENERATED_MARK} from Karni's rule registry. Do not edit: "
+    "project rules go in karni.rules.py. -->"
+)
+MODULES_DIR = Path(".karni") / "modules"
+BACKUP_DIR = Path(".karni") / "backup"
+_TEMPLATES = ("instructions", "import", "command")
+_YAML_PLAIN = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9 _./()-]*$")
+
+
+@dataclass(frozen=True)
+class Adapter:
+    id: str
+    tool: str
+    path: str
+    template: str
+    modules: bool = False
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    imports: str | None = None
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class CommandTarget:
+    id: str
+    tool: str
+    dir: str
+    suffix: str
+    arguments: str
+    frontmatter: tuple[str, ...] = ()
+    agent: str | None = None
+
+
+@dataclass(frozen=True)
+class Registry:
+    adapters: tuple[Adapter, ...]
+    commands: tuple[CommandTarget, ...]
+    max_lines: int
+
+    def ids(self) -> set[str]:
+        return {a.id for a in self.adapters} | {c.id for c in self.commands}
+
+
+def load_registry(path: Path | None = None) -> Registry:
+    if path is None:
+        text = (resources.files("karni_cli") / "agent_adapters.toml").read_text(encoding="utf-8")
+    else:
+        text = path.read_text(encoding="utf-8")
+    data = tomllib.loads(text)
+    adapters = tuple(
+        Adapter(
+            id=entry["id"],
+            tool=entry.get("tool", entry["id"]),
+            path=entry["path"],
+            template=entry["template"],
+            modules=bool(entry.get("modules", False)),
+            frontmatter=dict(entry.get("frontmatter", {})),
+            imports=entry.get("import"),
+            note=entry.get("note", ""),
+        )
+        for entry in data.get("adapter", [])
+    )
+    commands = tuple(
+        CommandTarget(
+            id=entry["id"],
+            tool=entry.get("tool", entry["id"]),
+            dir=entry["dir"],
+            suffix=entry["suffix"],
+            arguments=entry["arguments"],
+            frontmatter=tuple(entry.get("frontmatter", [])),
+            agent=entry.get("agent"),
+        )
+        for entry in data.get("commands", [])
+    )
+    for adapter in adapters:
+        if adapter.template not in _TEMPLATES:
+            raise CliError(
+                f"agent adapter {adapter.id}: unknown template {adapter.template!r}", code="C205"
+            )
+    return Registry(adapters, commands, int(data.get("defaults", {}).get("max_lines", 100)))
+
+
+def apply_overrides(registry: Registry, overrides: dict[str, Any]) -> Registry:
+    """Honour ``ADAPTERS = {"disable": [...], "paths": {...}}`` from karni.rules.py."""
+    disable = set(overrides.get("disable", []))
+    paths: dict[str, str] = dict(overrides.get("paths", {}))
+    unknown = (disable | set(paths)) - registry.ids()
+    if unknown:
+        raise CliError(
+            f"karni.rules.py ADAPTERS names unknown adapter id(s): {', '.join(sorted(unknown))} "
+            f"(known: {', '.join(sorted(registry.ids()))}).",
+            code="C205",
+        )
+    adapters = tuple(
+        Adapter(**{**a.__dict__, "path": paths.get(a.id, a.path)})
+        for a in registry.adapters
+        if a.id not in disable
+    )
+    commands = tuple(
+        CommandTarget(**{**c.__dict__, "dir": paths.get(c.id, c.dir)})
+        for c in registry.commands
+        if c.id not in disable
+    )
+    return Registry(adapters, commands, registry.max_lines)
+
+
+# inputs from the project
+
+
+def module_fragments(project: Path) -> dict[str, str]:
+    """Module guidance recorded by ``karni add``: ``{module: fragment}``, sorted."""
+    directory = project / MODULES_DIR
+    if not directory.is_dir():
+        return {}
+    return {
+        path.stem: path.read_text(encoding="utf-8").strip()
+        for path in sorted(directory.glob("*.md"))
+    }
+
+
+def project_title(project: Path) -> str:
+    pyproject = project / "pyproject.toml"
+    if pyproject.is_file():
+        try:
+            name = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]["name"]
+            if isinstance(name, str) and name.strip():
+                return name.strip()
+        except (tomllib.TOMLDecodeError, KeyError, TypeError):
+            pass
+    return project.resolve().name
+
+
+# rendering
+
+
+def _yaml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None or value == "":
+        return ""
+    text = str(value)
+    return text if _YAML_PLAIN.match(text) else json.dumps(text, ensure_ascii=False)
+
+
+def _frontmatter(values: dict[str, Any]) -> list[str]:
+    if not values:
+        return []
+    lines = ["---"]
+    for key, value in values.items():
+        rendered = _yaml_value(value)
+        lines.append(f"{key}: {rendered}" if rendered else f"{key}:")
+    lines.append("---")
+    return lines
+
+
+def _procedure_names(data: AgentData) -> str:
+    return ", ".join(p["name"] for p in data.procedures)
+
+
+def instructions_body(title: str, data: AgentData, note: str = "") -> list[str]:
+    lines = [
+        MARKER_LINE,
+        f"# {title} — agent instructions",
+        "",
+        "This is a Karni project. Karni already implements everything generic; you write",
+        "only domain code.",
+        "",
+        "Before any work, run these two commands and follow what they return:",
+        "",
+        "1. `karni context` — live inventory: apps, models, viewsets, UI components, hooks,",
+        "   pages and installed modules.",
+        "2. `karni rules` — the conventions, each with a stable code (K###; project P###).",
+        "",
+        "While you work:",
+        "",
+        "- `karni rules --check <file>` on every file you write; fix each violation it prints.",
+        f"- `karni rules --procedure <name>` for routine tasks: {_procedure_names(data)}.",
+        "- `karni check` before committing; every enforced rule fails the build.",
+        "",
+        "If the `karni` command is unavailable, say so and stop; do not guess the conventions.",
+    ]
+    if note:
+        lines += ["", note]
+    return lines
+
+
+def _module_section(fragments: dict[str, str], inline: bool) -> list[str]:
+    if not fragments:
+        return []
+    lines = ["", "## Module guidance", ""]
+    if not inline:
+        lines += [f"- {name}: run `karni rules` (includes its guidance)" for name in fragments]
+        return lines
+    for name, fragment in fragments.items():
+        lines += [f"<!-- karni:module:{name} -->", fragment, f"<!-- /karni:module:{name} -->", ""]
+    return lines[:-1]
+
+
+def _join(lines: list[str]) -> str:
+    return "\n".join(lines).rstrip("\n") + "\n"
+
+
+def render_adapter(
+    adapter: Adapter,
+    registry: Registry,
+    data: AgentData,
+    title: str,
+    fragments: dict[str, str],
+) -> str:
+    if adapter.template == "import":
+        target = next((a for a in registry.adapters if a.id == adapter.imports), None)
+        if target is not None:
+            rel = Path(target.path)
+            return _join([MARKER_LINE, f"@{rel.as_posix()}"])
+        # The imported adapter is disabled: fall back to the full body.
+    head = _frontmatter(adapter.frontmatter)
+    body = head + instructions_body(title, data, adapter.note)
+    if not adapter.modules:
+        return _join(body)
+    full = _join(body + _module_section(fragments, inline=True))
+    if full.count("\n") <= registry.max_lines:
+        return full
+    return _join(body + _module_section(fragments, inline=False))
+
+
+def render_command(target: CommandTarget, procedure: dict[str, Any]) -> str:
+    values: dict[str, Any] = {}
+    for key in target.frontmatter:
+        if key == "description":
+            values[key] = procedure["description"]
+        elif key == "argument-hint":
+            values[key] = procedure["argument_hint"]
+        elif key == "agent":
+            values[key] = target.agent
+    lines = _frontmatter(values)
+    lines.append(procedure["intro"].replace("{arguments}", target.arguments))
+    lines.append("")
+    lines += [f"{i}. {step}" for i, step in enumerate(procedure["steps"], start=1)]
+    if procedure.get("outro"):
+        lines += ["", procedure["outro"]]
+    if procedure.get("rules"):
+        codes = ", ".join(procedure["rules"])
+        lines += ["", f"Rules that apply: {codes} (`karni rules --explain <code>`)."]
+    lines += ["", MARKER_LINE]
+    return _join(lines)
+
+
+def render_all(project: Path, data: AgentData, registry: Registry | None = None) -> dict[str, str]:
+    """Every generated file for ``project``: ``{posix relative path: content}``."""
+    registry = apply_overrides(registry or load_registry(), data.adapter_overrides)
+    title = project_title(project)
+    fragments = module_fragments(project)
+    files: dict[str, str] = {}
+    for adapter in registry.adapters:
+        files[Path(adapter.path).as_posix()] = render_adapter(
+            adapter, registry, data, title, fragments
+        )
+    for target in registry.commands:
+        for procedure in data.procedures:
+            command = Path(target.dir) / f"{procedure['name']}{target.suffix}"
+            files[command.as_posix()] = render_command(target, procedure)
+    for rel, content in files.items():
+        count = content.count("\n")
+        if count > registry.max_lines:
+            raise CliError(
+                f"{rel} would be {count} lines (cap {registry.max_lines}); shorten the "
+                "project rules or module guidance feeding it.",
+                code="C205",
+            )
+    return files
+
+
+# sync
+
+
+@dataclass
+class SyncResult:
+    written: list[str] = field(default_factory=list)
+    unchanged: list[str] = field(default_factory=list)
+    removed: list[str] = field(default_factory=list)
+    blocked: list[str] = field(default_factory=list)
+    backed_up: list[str] = field(default_factory=list)
+
+    @property
+    def stale(self) -> list[str]:
+        return sorted({*self.written, *self.removed, *self.blocked})
+
+
+def is_generated(path: Path) -> bool:
+    try:
+        return GENERATED_MARK in path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+
+
+def _candidates(project: Path, registry: Registry, overrides: dict[str, Any]) -> set[str]:
+    """Every place a generated file may have been written (for obsolete cleanup)."""
+    paths: dict[str, str] = dict(overrides.get("paths", {}))
+    found = {Path(a.path).as_posix() for a in registry.adapters}
+    found |= {Path(p).as_posix() for p in paths.values()}
+    dirs = {c.dir for c in registry.commands} | set(paths.values())
+    for directory in dirs:
+        base = project / directory
+        if base.is_dir():
+            found |= {p.relative_to(project).as_posix() for p in base.iterdir() if p.is_file()}
+    return found
+
+
+def backup(project: Path, rel: str) -> str:
+    source = project / rel
+    target = project / BACKUP_DIR / rel
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+    return (BACKUP_DIR / rel).as_posix()
+
+
+def sync(project: Path, data: AgentData, *, check: bool = False, force: bool = False) -> SyncResult:
+    """Write (or, with ``check``, only compare) every adapter and command file."""
+    registry = load_registry()
+    files = render_all(project, data, registry)
+    result = SyncResult()
+    for rel, content in sorted(files.items()):
+        target = project / rel
+        if target.is_file():
+            current = target.read_text(encoding="utf-8")
+            if current == content:
+                result.unchanged.append(rel)
+                continue
+            if GENERATED_MARK not in current and not force:
+                result.blocked.append(rel)
+                continue
+            if GENERATED_MARK not in current and not check:
+                result.backed_up.append(backup(project, rel))
+        result.written.append(rel)
+        if not check:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+    for rel in sorted(_candidates(project, registry, data.adapter_overrides) - set(files)):
+        path = project / rel
+        if path.is_file() and is_generated(path):
+            result.removed.append(rel)
+            if not check:
+                path.unlink()
+    return result

karni_cli/agent_adapters.toml

@@ -0,0 +1,160 @@
+# Agent adapter registry for `karni rules sync`.
+#
+# One entry per tool convention. Renaming a file or changing a frontmatter key
+# is an edit here, not a code change. Projects can disable entries or move
+# paths from karni.rules.py:  ADAPTERS = {"disable": [...], "paths": {...}}.
+#
+# Every adapter says the same thing: run `karni context` and `karni rules`
+# first, then follow what they return. The content lives in karni.agent.rules
+# (packages/karni/karni/agent/rules.py); these files are thin pointers.
+#
+# Templates (implemented in karni_cli/adapters.py):
+#   instructions  - the shared ~15-line body (+ optional YAML frontmatter)
+#   import        - an `@<file>` import of another adapter (Claude Code)
+#   command       - one file per procedure (slash commands / prompt files)
+#
+# Each entry records where its convention was verified, and when. Re-verify
+# before a release: these conventions change.
+
+[defaults]
+max_lines = 100
+
+# --- instruction adapters -----------------------------------------------------
+
+[[adapter]]
+id = "agents-md"
+tool = "AGENTS.md (canonical: Codex, Jules, Gemini CLI, Zed, Warp, Devin; also read by Cursor, Copilot, Windsurf, Cline, Junie)"
+path = "AGENTS.md"
+template = "instructions"
+modules = true
+# Source: https://agents.md/ (verified 2026-10-02). Plain Markdown at the
+# repository root, no required fields or frontmatter; the nearest AGENTS.md in
+# the directory tree wins.
+
+[[adapter]]
+id = "claude"
+tool = "Claude Code"
+path = "CLAUDE.md"
+template = "import"
+import = "agents-md"
+# Source: https://code.claude.com/docs/en/memory (verified 2026-10-02). When a
+# CLAUDE.md exists Claude Code reads it INSTEAD of AGENTS.md by default; the
+# documented way to share one file is a CLAUDE.md containing `@AGENTS.md`
+# (imports expand at launch; block-level HTML comments are stripped).
+
+[[adapter]]
+id = "cursor"
+tool = "Cursor"
+path = ".cursor/rules/karni.mdc"
+template = "instructions"
+frontmatter = { description = "Karni project conventions: run karni context and karni rules before any work", globs = "", alwaysApply = true }
+# Source: https://cursor.com/docs/context/rules (verified 2026-10-02). Project
+# rules are .mdc files in .cursor/rules with frontmatter keys description,
+# globs, alwaysApply (alwaysApply: true = every session). The legacy
+# .cursorrules file is no longer documented. Cursor also reads AGENTS.md.
+
+[[adapter]]
+id = "windsurf"
+tool = "Windsurf (Cascade; now documented as Devin Desktop)"
+path = ".windsurf/rules/karni.md"
+template = "instructions"
+frontmatter = { trigger = "always_on" }
+# Source: https://docs.devin.ai/desktop/cascade/memories (docs.windsurf.com
+# redirects there; verified 2026-10-02). Workspace rules are one Markdown file
+# per rule in .devin/rules/ (preferred) or .windsurf/rules/, frontmatter
+# `trigger: always_on|model_decision|glob|manual`, 12,000 chars per file. The
+# single-file .windsurfrules is legacy ("also still read"). .windsurf/rules/
+# is used because both Windsurf and Devin Desktop read it.
+
+[[adapter]]
+id = "copilot"
+tool = "GitHub Copilot"
+path = ".github/copilot-instructions.md"
+template = "instructions"
+# Source: https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
+# (verified 2026-10-02). Repository-wide instructions: .github/copilot-instructions.md,
+# natural-language Markdown, no frontmatter. Copilot also reads AGENTS.md.
+
+[[adapter]]
+id = "cline"
+tool = "Cline"
+path = ".clinerules/karni.md"
+template = "instructions"
+# Source: https://docs.cline.bot/features/cline-rules (verified 2026-10-02).
+# Workspace rules are Markdown files inside the .clinerules/ (or .cline/rules/)
+# DIRECTORY; optional `paths` frontmatter scopes a rule (none = always on).
+# Cline also reads AGENTS.md.
+
+[[adapter]]
+id = "aider"
+tool = "Aider"
+path = "CONVENTIONS.md"
+template = "instructions"
+note = "Aider does not load this file by itself: run `aider --read CONVENTIONS.md`, or add `read: CONVENTIONS.md` to .aider.conf.yml."
+# Source: https://aider.chat/docs/usage/conventions.html (verified 2026-10-02).
+# Not auto-loaded: `aider --read CONVENTIONS.md`, or `read: CONVENTIONS.md` in
+# .aider.conf.yml (the body says so; karni never writes your aider config).
+
+[[adapter]]
+id = "junie"
+tool = "JetBrains Junie"
+path = ".junie/AGENTS.md"
+template = "instructions"
+modules = true
+# Source: https://junie.jetbrains.com/docs/guidelines-and-memory.html
+# (verified 2026-10-02). Lookup order: .junie/AGENTS.md, then root AGENTS.md
+# (+ .junie/rules/*.md), then the LEGACY .junie/guidelines.md. A file at
+# .junie/guidelines.md would never be read while AGENTS.md exists, so the
+# preferred .junie/AGENTS.md is generated; it shadows the root file for Junie,
+# hence `modules = true` (same module guidance as AGENTS.md).
+
+# --- command targets (one file per procedure) ---------------------------------
+# `arguments` replaces {arguments} in the procedure's first line.
+
+[[commands]]
+id = "claude-commands"
+tool = "Claude Code"
+dir = ".claude/commands"
+suffix = ".md"
+arguments = "$ARGUMENTS"
+frontmatter = ["description", "argument-hint"]
+# Source: https://code.claude.com/docs/en/slash-commands (verified 2026-10-02).
+# .claude/commands/<name>.md creates /<name> (merged into skills; still
+# supported). Frontmatter description, argument-hint; $ARGUMENTS substitution.
+
+[[commands]]
+id = "cursor-commands"
+tool = "Cursor"
+dir = ".cursor/commands"
+suffix = ".md"
+arguments = "the request typed after the command"
+frontmatter = []
+# Source: Cursor commands docs (docs.cursor.com/en/agent/chat/commands now
+# redirects to the docs index; corroborated by forum.cursor.com threads,
+# verified 2026-10-02). .cursor/commands/<name>.md, plain Markdown, NO
+# frontmatter, invoked as /<name>.
+
+[[commands]]
+id = "windsurf-workflows"
+tool = "Windsurf"
+dir = ".windsurf/workflows"
+suffix = ".md"
+arguments = "the request typed after the command"
+frontmatter = ["description"]
+# Source: https://docs.devin.ai/desktop/cascade/workflows
+# (verified 2026-10-02). Markdown workflows in .devin/workflows/ (preferred) or
+# .windsurf/workflows/ (legacy, still read), invoked as /<name>; title,
+# description and steps; 12,000 chars per file.
+
+[[commands]]
+id = "copilot-prompts"
+tool = "GitHub Copilot (VS Code prompt files)"
+dir = ".github/prompts"
+suffix = ".prompt.md"
+arguments = "${input:request:what to add}"
+frontmatter = ["description", "argument-hint", "agent"]
+agent = "agent"
+# Source: https://code.visualstudio.com/docs/copilot/customization/prompt-files
+# (verified 2026-10-02). .github/prompts/<name>.prompt.md, frontmatter
+# description, name, argument-hint, agent, model, tools; invoked as /<name>;
+# ${input:var:placeholder} collects input.