karni-cli 0.3.1__tar.gz → 0.5.0__tar.gz

{karni_cli-0.3.1 → karni_cli-0.5.0}/.gitignore

@@ -19,6 +19,9 @@ packages/karni-cli/karni_cli/_templates/
 packages/karni-cli/karni_cli/_agent/
 packages/karni-cli/karni_cli/_changelog/
 packages/karni-cli/karni_cli/_errorcodes/
+packages/karni-cli/karni_cli/_settings/
+packages/karni-cli/karni_cli/_catalog/
+packages/karni-cli/karni_cli/_ui/
 
 # Node
 node_modules/
@@ -31,8 +34,11 @@ storybook-static/
 !.env.example
 .DS_Store
 .idea/
-.claude/scheduled_tasks.lock
-.claude/settings.local.json
 
 # MkDocs build output
 site/
+.github/ci/prod_e2e/test-results/
+
+# Contributors' own agent working files stay on their machines
+/CLAUDE.md
+/.claude/

{karni_cli-0.3.1 → karni_cli-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: karni-cli
-Version: 0.3.1
-Summary: The karni command for the Karni Django + React framework: scaffold a project, generate models, viewsets and pages, run it, upgrade it across releases, and give AI coding agents its context, rules and error explanations.
+Version: 0.5.0
+Summary: The karni command: scaffold, generate, run and upgrade Karni projects. Karni is an open-source Django + React framework for building with AI coding agents. Your agent writes only your domain. The API, admin, permissions and React screens come from a package you upgrade, not code it rewrites in each project. One rule set covers every coding agent. The build fails when an agent hand-writes what Karni ships.
 Project-URL: Homepage, https://github.com/cbsshekhawat18-lab/karni
 Project-URL: Documentation, https://cbsshekhawat18-lab.github.io/karni/
 Project-URL: Repository, https://github.com/cbsshekhawat18-lab/karni
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/cbsshekhawat18-lab/karni/tree/main/do
 Author-email: Chandrabhan Shekhawat <cbsshekhawat18@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: ai-agents,claude-code,cli,code-generation,cookiecutter,copilot,cursor,django,mcp,project-template,react,scaffolding
+Keywords: ai-agents,cli,code-generation,cookiecutter,django,mcp,project-template,react,scaffolding
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Framework :: Django
@@ -29,6 +29,7 @@ Requires-Python: >=3.12
 Requires-Dist: cookiecutter>=2.5
 Requires-Dist: libcst>=1.4
 Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic>=2
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tomlkit>=0.12
 Requires-Dist: typer>=0.12
@@ -38,66 +39,109 @@ Description-Content-Type: text/markdown
 
 # karni-cli
 
-The `karni` command. Orchestrates a Karni project's own `manage.py` via
-subprocess — the CLI itself never imports Django.
+The karni command: scaffold, generate, run and upgrade Karni projects.
+
+[![PyPI](https://img.shields.io/pypi/v/karni-cli)](https://pypi.org/project/karni-cli/) [![Python versions](https://img.shields.io/pypi/pyversions/karni-cli)](https://pypi.org/project/karni-cli/) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/cbsshekhawat18-lab/karni/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-online-FB5D08)](https://cbsshekhawat18-lab.github.io/karni/cli/)
+
+It runs a project's own `manage.py` as a subprocess, so the CLI itself never imports Django. Karni's Python core is [`karni`](https://pypi.org/project/karni/) and its React side [`@karni/ui`](https://www.npmjs.com/package/@karni/ui).
+
+## Install
+
+```sh
+pip install karni-cli
+```
+
+## A minimal example
+
+The shop recipe, built on SQLite with no Docker:
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install karni karni-cli karni-payments pytest pytest-django
+karni new "Corner Shop" --recipe shop && cd corner_shop
+printf 'DATABASE_URL=sqlite:///data/db.sqlite3\nKARNI_CACHE=locmem\n' > .env
+karni build
+karni serve --local
+```
+
+`karni build` runs the migrations, seeds demo data, generates the TypeScript types, and runs the tests and `karni check`. The [quickstart](https://cbsshekhawat18-lab.github.io/karni/quickstart/) does the same on PostgreSQL.
+
+## Main features
+
+- **Start a project.** `karni new` scaffolds a site, an app or both, blank or from one of six [recipes](https://cbsshekhawat18-lab.github.io/karni/recipes/).
+- **Build from a spec.** `karni spec validate`, `karni plan` and `karni build` turn `karni.yaml` into code ([the app spec](https://cbsshekhawat18-lab.github.io/karni/app-spec/)).
+- **Generate.** `karni make app`, `model`, `page`, `schedule`, `task`, `site` and `form` write the files a project owns.
+- **Modules.** `karni add` and `karni remove` wire a module in and out, and `karni modules` lists the catalog.
+- **Run and check.** `karni serve`, `seed`, `migrate`, `test`, `types` and `check`, the last one failing the build when code rebuilds what Karni ships.
+- **For coding agents.** `karni context`, `karni rules`, the procedures in AGENTS.md and `karni mcp`, the MCP server ([Karni for coding agents](https://cbsshekhawat18-lab.github.io/karni/agents/)).
+- **Debugging.** `karni why`, `karni explain`, `karni trace`, `karni replay` and `karni queries` ([debugging](https://cbsshekhawat18-lab.github.io/karni/debugging/why/)).
+- **Upgrades.** `karni upgrade` applies each release's codemods and lists what it could not change.
+
+Every command and option is in [the karni command](https://cbsshekhawat18-lab.github.io/karni/cli/). A short list follows.
 
 ## Commands
-- `karni new <name>` — scaffold a project from the bundled cookiecutter
-  template (monorepo checkouts use the live `templates/project`; override with
-  `KARNI_TEMPLATES`).
-- `karni add <module>` — add `karni-<module>` to `[project].dependencies` and
+- `karni new <name>`: scaffold a project from the bundled cookiecutter
+  template. Monorepo checkouts use the live `templates/project`, and
+  `KARNI_TEMPLATES` overrides it.
+- `karni add <module>`: add `karni-<module>` to `[project].dependencies` and
   wire `karni_<module>` into the `# karni:apps` block in config/settings.py.
-  Only that marker block is managed; any other layout gets a clear error and
+  Only that marker block is managed. Any other layout gets a clear error, and
   you edit settings manually.
   Once the module is installed it also records the module's
   `AGENTS.fragment.md` as `.karni/modules/<module>.md` and refreshes the agent
   adapters.
-- `karni types` — dump the OpenAPI schema (`manage.py spectacular`), generate
+- `karni types`: dump the OpenAPI schema (`manage.py spectacular`), generate
   `types.ts` (openapi-typescript, project-pinned binary preferred, else
   `npx openapi-typescript@^7`) and typed hooks (`hooks.ts`) over @karni/ui.
-- `karni context` — compact machine-readable inventory (< 200 tokens for a
-  typical project): APPS (from the `# karni:apps` block) and PAGES (from
-  `frontend/src/pages/`) read statically, MODELS/VIEWSETS from `manage.py karni_context`,
-  COMPONENTS/HOOKS from @karni/ui's build-generated `dist/manifest.json`
-  (omitted when absent — run `npm i @karni/ui` in `frontend/` on the host to
-  enable them; `--manifest PATH` overrides). Nothing is hand-maintained.
-- `karni context --with-history [PATH]` — the same inventory plus a
+- `karni ui detect`: map the frontend's design system (shadcn/ui, a Tailwind
+  theme, Material UI, Chakra UI or Mantine) onto @karni/ui's `--karni-*`
+  tokens in `karni-theme.css`, plus `karni-primitives.tsx` for shadcn/ui.
+  `--dry-run` previews, `--json` reports for agents, and edited files are kept
+  unless `--force`.
+- `karni context`: a compact machine-readable inventory (< 200 tokens for a
+  typical project). APPS (from the `# karni:apps` block) and PAGES (from
+  `frontend/src/pages/`) are read statically, MODELS/VIEWSETS come from `manage.py karni_context`,
+  and COMPONENTS/HOOKS from @karni/ui's build-generated `dist/manifest.json`.
+  Those two are omitted when the manifest is absent. Run `npm i @karni/ui` in
+  `frontend/` on the host to enable them, or override with `--manifest PATH`.
+  Nothing is hand-maintained.
+- `karni context --with-history [PATH]`: the same inventory plus a
   `HISTORY:` brief of what was already asked and decided about PATH (without
   PATH: the project's recorded decisions) from any history provider that
   detects a store, e.g. Gigai Chronicle's `.chronicle/`. Capped at ~300
   tokens (characters ÷ 4), cut at line boundaries with a last line naming the
   full-brief command. With no store the output is exactly `karni context`'s.
   See `docs/concepts/history-providers.md`.
-- `karni check [-q]` — Django system checks plus `karni.checks` entry-point hooks
+- `karni check [-q]`: Django system checks plus `karni.checks` entry-point hooks
   (the architecture-test extension surface). A clean run outside CI may end
-  with one tip on stderr, at most once per project; `-q` suppresses it.
-- `karni doctor [-q]` — human-readable environment report: project,
-  interpreter (`.venv` / compose service), Node/npm, the @karni/ui manifest,
-  adapter freshness, history providers. May end with the same one-time tip.
-- `karni config get|set|list [--global] KEY [VALUE]` — settings
-  (`suggest_tools`): `.karni/config.toml` in the project (committed) or
-  `$XDG_CONFIG_HOME/karni/config.toml` with `--global`; the project wins.
+  with one tip on stderr, at most once per project. `-q` suppresses it.
+- `karni doctor [-q]`: a human-readable environment report covering the
+  project, interpreter (`.venv` / compose service), Node/npm, the @karni/ui
+  manifest, adapter freshness and history providers. It may end with the same
+  one-time tip.
+- `karni config get|set|list [--global] KEY [VALUE]`: settings
+  (`suggest_tools`), kept in `.karni/config.toml` in the project (committed) or
+  in `$XDG_CONFIG_HOME/karni/config.toml` with `--global`. The project wins.
   Machine-local state (e.g. "tip shown") lives in the self-ignoring
   `.karni/local/`.
-- `karni rules [--explain CODE | --procedure NAME | --check FILE... | --json]`
-  — Karni's conventions from `karni.agent.rules` (no Django needed), and
+- `karni rules [--explain CODE | --procedure NAME | --check FILE... | --json]`:
+  Karni's conventions from `karni.agent.rules` (no Django needed), and
   static single-file checks (exit 1 on violations).
-- `karni rules sync [--check] [--force]` — regenerate the thin agent adapters
-  (AGENTS.md, CLAUDE.md, Cursor, Windsurf, Copilot, Cline, Aider, Junie) and
-  slash commands from `karni_cli/agent_adapters.toml`; `--check` is the CI
-  staleness gate.
-- `karni mcp` — context, rules and check as MCP tools
+- `karni rules sync [--check] [--force]`: regenerate AGENTS.md, the agent
+  instructions with the procedures for routine tasks, from
+  `karni_cli/agent_adapters.toml`. `--check` is the CI staleness gate.
+- `karni mcp`: context, rules and check as MCP tools
   (`pip install 'karni-cli[mcp]'`).
 - `karni upgrade [--to VERSION] [--from VERSION] [--dry-run] [--allow-dirty] [--list]`
   moves the project across Karni versions. It reads the karni installed in
   the project (`--from` overrides), takes every breaking change between that
   and `--to` from Karni's machine-readable changelog
   (`packages/karni/karni/changelog/*.toml`, bundled into karni-cli), and runs
-  their codemods in release order. Python codemods use libcst; TypeScript
-  codemods use a pinned jscodeshift through `npx` and are skipped, with the
-  reason, without Node.js. The codemods run on a scratch copy, and the result
+  their codemods in release order. Python codemods use libcst. TypeScript
+  codemods use a pinned jscodeshift through `npx`, and without Node.js they
+  are skipped with the reason. The codemods run on a scratch copy, and the result
   is written back all at once, or not at all if one fails. `--dry-run` prints
-  a unified diff and writes nothing. Writing needs a clean git tree;
+  a unified diff and writes nothing. Writing needs a clean git tree.
   `--allow-dirty` overrides that, and is also required outside git. The
   report lists what was applied (each file and its rewrite count), what could
   not be fixed automatically (the sites found, with each migration-note link)
@@ -110,7 +154,7 @@ See `docs/agents.md` for the agent surface in full.
 Artisan-style shortcuts. Each runner runs one project command through the
 project interpreter (see *Execution environment* below), streams its output
 and exits with its exit code. `--help` on each names the command it wraps.
-Extra arguments pass straight through; put `--` before any that clash with
+Extra arguments pass straight through. Put `--` before any that clash with
 karni's own options (`--docker`, `--service`, `--help`).
 
 | Command | Runs |
@@ -138,25 +182,25 @@ With the compose stack up, `worker` and `beat` already run as services, so
 ## Generators
 `karni make <type>` writes the project code a task needs, so neither a person
 nor an AI agent hand-creates a file a generator makes. `karni make --list`
-prints them all; every one is also a hidden Laravel-style alias
+prints them all. Each one is also available as a hidden Laravel-style alias,
 `karni make:<type>`. The full reference (every option, the field DSL) is
 [docs/cli.md](https://cbsshekhawat18-lab.github.io/karni/cli/), generated from this CLI.
 
 | Command | Writes |
 |---|---|
-| `karni make app NAME` | `NAME/{__init__,apps,models,viewsets}.py`, `migrations/`, `tests/`; wires `# karni:apps` |
-| `karni make model NAME [FIELD...]` | `class NAME(BaseModel)` in `<app>/models.py`; `--with viewset,page` / `-a` chains; `--migrate` |
+| `karni make app NAME` | `NAME/{__init__,apps,models,viewsets}.py`, `migrations/`, `tests/`, and wires `# karni:apps` |
+| `karni make model NAME [FIELD...]` | `class NAME(BaseModel)` in `<app>/models.py`, with `--with viewset,page` / `-a` chains and `--migrate` |
 | `karni make viewset MODEL` | `<Model>ViewSet` with its `access` (`--access authenticated\|public-read\|owned:<field>\|staff\|role:<name>`), `--search` |
 | `karni make serializer MODEL --reason ...` | `<app>/serializers.py` + `serializer_class` on the viewset |
 | `karni make migration [NAME]` | runs `manage.py makemigrations [--app] [--name] [--empty]` through the project interpreter |
 | `karni make task NAME` | `@shared_task` in `<app>/tasks.py` (`--retry N`) |
 | `karni make schedule NAME` | `every(...)`/`cron(...)` in `<app>/schedules.py` (`--every 15m` / `--cron "0 3 * * *"`, `--task`) |
 | `karni make event NAME` | a `Signal` in `<app>/events.py` |
-| `karni make listener NAME --on ...` | `<app>/listeners.py`: `Model.created\|updated\|deleted` or a custom event; `--queued` |
+| `karni make listener NAME --on ...` | `<app>/listeners.py`: `Model.created\|updated\|deleted` or a custom event, with `--queued` |
 | `karni make command NAME` | `<app>/management/commands/NAME.py` |
 | `karni make service NAME` | `<app>/services/NAME.py` (where HTTP clients are allowed) |
 | `karni make middleware NAME` | `<app>/middleware.py`, wired through `# karni:middleware` |
-| `karni make page NAME` | `frontend/src/pages/NAME.tsx` (≤ 50 lines; `--resource R --kind list\|detail\|form`), route in `frontend/src/routes.tsx` |
+| `karni make page NAME` | `frontend/src/pages/NAME.tsx` (≤ 50 lines, `--resource R --kind list\|detail\|form`), route in `frontend/src/routes.tsx` |
 | `karni make component NAME` | `frontend/src/components/NAME.tsx` claiming a role (`--role`) |
 | `karni make module NAME` | `modules/karni-NAME/` per docs/modules.md |
 
@@ -169,23 +213,33 @@ karni make listener notify_organizer --on Event.created --queued
 karni make schedule nightly-report --cron "0 3 * * *"
 ```
 
-Every generator: never overwrites without `--force`; `--dry-run` prints the
-files and diff and writes nothing; prints each created/modified file plus
-notes (the chosen `access`, the route, the next command); resolves the app
-from `--app` or the project's only local app; edits existing files only
-through marker comments or AST-located appends (an unfamiliar layout is an
-error naming the manual step); never imports Django. Generated Python is
-clean under ruff (lint and format) and `karni rules --check`, and generated
-pages parse and stay within 50 lines — `tests/test_make_gate.py` generates
-every type into a fresh scaffold and asserts it (plus `tsc` and the
-frontend's ESLint config when `KARNI_TEST_NODE_MODULES` points at an
-installed `frontend/node_modules`), then runs the generated backend for real
-(makemigrations, migrate, check, requests through the Django test client).
+Every generator follows the same rules. It never overwrites without
+`--force`, and `--dry-run` prints the files and diff and writes nothing. It
+prints each created/modified file plus notes (the chosen `access`, the route,
+the next command). It resolves the app from `--app` or the project's only
+local app. It edits existing files only through marker comments or
+AST-located appends, and an unfamiliar layout is an error naming the manual
+step. It never imports Django. Generated Python is clean under ruff (lint and
+format) and `karni rules --check`, and generated pages parse and stay within
+50 lines. `tests/test_make_gate.py` generates every type into a fresh scaffold
+and asserts this (plus `tsc` and the frontend's ESLint config when
+`KARNI_TEST_NODE_MODULES` points at an installed `frontend/node_modules`).
+Then it runs the generated backend for real (makemigrations, migrate, check,
+requests through the Django test client).
 
 Quote fields that end in `?` in zsh (`'venue:fk:Venue?'`) and choice values
 joined by `|`.
 
 ## Execution environment
 Commands that run the project resolve, in order: `--docker/--no-docker` flag →
-`<project>/.venv` → a running compose service (default `django`; change with
+`<project>/.venv` → a running compose service (default `django`, changed with
 `--service` or `KARNI_COMPOSE_SERVICE`) → an error naming both remedies.
+
+## Links
+
+- The karni command: <https://cbsshekhawat18-lab.github.io/karni/cli/>
+- Quickstart: <https://cbsshekhawat18-lab.github.io/karni/quickstart/>
+- Karni, the framework this package is part of: <https://github.com/cbsshekhawat18-lab/karni>
+- Changelog: <https://github.com/cbsshekhawat18-lab/karni/blob/main/CHANGELOG.md>
+- Issues: <https://github.com/cbsshekhawat18-lab/karni/issues>
+- License: Apache-2.0. karni-cli is released with every other Karni package, at one version.

karni_cli-0.5.0/README.md

@@ -0,0 +1,206 @@
+# karni-cli
+
+The karni command: scaffold, generate, run and upgrade Karni projects.
+
+[![PyPI](https://img.shields.io/pypi/v/karni-cli)](https://pypi.org/project/karni-cli/) [![Python versions](https://img.shields.io/pypi/pyversions/karni-cli)](https://pypi.org/project/karni-cli/) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/cbsshekhawat18-lab/karni/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-online-FB5D08)](https://cbsshekhawat18-lab.github.io/karni/cli/)
+
+It runs a project's own `manage.py` as a subprocess, so the CLI itself never imports Django. Karni's Python core is [`karni`](https://pypi.org/project/karni/) and its React side [`@karni/ui`](https://www.npmjs.com/package/@karni/ui).
+
+## Install
+
+```sh
+pip install karni-cli
+```
+
+## A minimal example
+
+The shop recipe, built on SQLite with no Docker:
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install karni karni-cli karni-payments pytest pytest-django
+karni new "Corner Shop" --recipe shop && cd corner_shop
+printf 'DATABASE_URL=sqlite:///data/db.sqlite3\nKARNI_CACHE=locmem\n' > .env
+karni build
+karni serve --local
+```
+
+`karni build` runs the migrations, seeds demo data, generates the TypeScript types, and runs the tests and `karni check`. The [quickstart](https://cbsshekhawat18-lab.github.io/karni/quickstart/) does the same on PostgreSQL.
+
+## Main features
+
+- **Start a project.** `karni new` scaffolds a site, an app or both, blank or from one of six [recipes](https://cbsshekhawat18-lab.github.io/karni/recipes/).
+- **Build from a spec.** `karni spec validate`, `karni plan` and `karni build` turn `karni.yaml` into code ([the app spec](https://cbsshekhawat18-lab.github.io/karni/app-spec/)).
+- **Generate.** `karni make app`, `model`, `page`, `schedule`, `task`, `site` and `form` write the files a project owns.
+- **Modules.** `karni add` and `karni remove` wire a module in and out, and `karni modules` lists the catalog.
+- **Run and check.** `karni serve`, `seed`, `migrate`, `test`, `types` and `check`, the last one failing the build when code rebuilds what Karni ships.
+- **For coding agents.** `karni context`, `karni rules`, the procedures in AGENTS.md and `karni mcp`, the MCP server ([Karni for coding agents](https://cbsshekhawat18-lab.github.io/karni/agents/)).
+- **Debugging.** `karni why`, `karni explain`, `karni trace`, `karni replay` and `karni queries` ([debugging](https://cbsshekhawat18-lab.github.io/karni/debugging/why/)).
+- **Upgrades.** `karni upgrade` applies each release's codemods and lists what it could not change.
+
+Every command and option is in [the karni command](https://cbsshekhawat18-lab.github.io/karni/cli/). A short list follows.
+
+## Commands
+- `karni new <name>`: scaffold a project from the bundled cookiecutter
+  template. Monorepo checkouts use the live `templates/project`, and
+  `KARNI_TEMPLATES` overrides it.
+- `karni add <module>`: add `karni-<module>` to `[project].dependencies` and
+  wire `karni_<module>` into the `# karni:apps` block in config/settings.py.
+  Only that marker block is managed. Any other layout gets a clear error, and
+  you edit settings manually.
+  Once the module is installed it also records the module's
+  `AGENTS.fragment.md` as `.karni/modules/<module>.md` and refreshes the agent
+  adapters.
+- `karni types`: dump the OpenAPI schema (`manage.py spectacular`), generate
+  `types.ts` (openapi-typescript, project-pinned binary preferred, else
+  `npx openapi-typescript@^7`) and typed hooks (`hooks.ts`) over @karni/ui.
+- `karni ui detect`: map the frontend's design system (shadcn/ui, a Tailwind
+  theme, Material UI, Chakra UI or Mantine) onto @karni/ui's `--karni-*`
+  tokens in `karni-theme.css`, plus `karni-primitives.tsx` for shadcn/ui.
+  `--dry-run` previews, `--json` reports for agents, and edited files are kept
+  unless `--force`.
+- `karni context`: a compact machine-readable inventory (< 200 tokens for a
+  typical project). APPS (from the `# karni:apps` block) and PAGES (from
+  `frontend/src/pages/`) are read statically, MODELS/VIEWSETS come from `manage.py karni_context`,
+  and COMPONENTS/HOOKS from @karni/ui's build-generated `dist/manifest.json`.
+  Those two are omitted when the manifest is absent. Run `npm i @karni/ui` in
+  `frontend/` on the host to enable them, or override with `--manifest PATH`.
+  Nothing is hand-maintained.
+- `karni context --with-history [PATH]`: the same inventory plus a
+  `HISTORY:` brief of what was already asked and decided about PATH (without
+  PATH: the project's recorded decisions) from any history provider that
+  detects a store, e.g. Gigai Chronicle's `.chronicle/`. Capped at ~300
+  tokens (characters ÷ 4), cut at line boundaries with a last line naming the
+  full-brief command. With no store the output is exactly `karni context`'s.
+  See `docs/concepts/history-providers.md`.
+- `karni check [-q]`: Django system checks plus `karni.checks` entry-point hooks
+  (the architecture-test extension surface). A clean run outside CI may end
+  with one tip on stderr, at most once per project. `-q` suppresses it.
+- `karni doctor [-q]`: a human-readable environment report covering the
+  project, interpreter (`.venv` / compose service), Node/npm, the @karni/ui
+  manifest, adapter freshness and history providers. It may end with the same
+  one-time tip.
+- `karni config get|set|list [--global] KEY [VALUE]`: settings
+  (`suggest_tools`), kept in `.karni/config.toml` in the project (committed) or
+  in `$XDG_CONFIG_HOME/karni/config.toml` with `--global`. The project wins.
+  Machine-local state (e.g. "tip shown") lives in the self-ignoring
+  `.karni/local/`.
+- `karni rules [--explain CODE | --procedure NAME | --check FILE... | --json]`:
+  Karni's conventions from `karni.agent.rules` (no Django needed), and
+  static single-file checks (exit 1 on violations).
+- `karni rules sync [--check] [--force]`: regenerate AGENTS.md, the agent
+  instructions with the procedures for routine tasks, from
+  `karni_cli/agent_adapters.toml`. `--check` is the CI staleness gate.
+- `karni mcp`: context, rules and check as MCP tools
+  (`pip install 'karni-cli[mcp]'`).
+- `karni upgrade [--to VERSION] [--from VERSION] [--dry-run] [--allow-dirty] [--list]`
+  moves the project across Karni versions. It reads the karni installed in
+  the project (`--from` overrides), takes every breaking change between that
+  and `--to` from Karni's machine-readable changelog
+  (`packages/karni/karni/changelog/*.toml`, bundled into karni-cli), and runs
+  their codemods in release order. Python codemods use libcst. TypeScript
+  codemods use a pinned jscodeshift through `npx`, and without Node.js they
+  are skipped with the reason. The codemods run on a scratch copy, and the result
+  is written back all at once, or not at all if one fails. `--dry-run` prints
+  a unified diff and writes nothing. Writing needs a clean git tree.
+  `--allow-dirty` overrides that, and is also required outside git. The
+  report lists what was applied (each file and its rewrite count), what could
+  not be fixed automatically (the sites found, with each migration-note link)
+  and what was skipped. Run it before you raise the karni pin. See
+  `docs/migrations/`.
+
+See `docs/agents.md` for the agent surface in full.
+
+## Runners
+Artisan-style shortcuts. Each runner runs one project command through the
+project interpreter (see *Execution environment* below), streams its output
+and exits with its exit code. `--help` on each names the command it wraps.
+Extra arguments pass straight through. Put `--` before any that clash with
+karni's own options (`--docker`, `--service`, `--help`).
+
+| Command | Runs |
+|---|---|
+| `karni serve` | `docker compose up` (`--build`, `-d`) |
+| `karni serve --local [--host H] [--port P]` | `manage.py runserver 127.0.0.1:8000` via `.venv` |
+| `karni migrate [ARGS]` | `manage.py migrate [ARGS]` |
+| `karni test [ARGS]` | `python -m pytest [ARGS]` |
+| `karni shell [ARGS]` | `manage.py shell [ARGS]` |
+| `karni routes [--json]` | `manage.py karni_routes`: every URL with methods, name, view, model, access |
+| `karni worker [-A APP] [-l LEVEL] [ARGS]` | `python -m celery -A config worker -l info [ARGS]` |
+| `karni beat [-A APP] [-l LEVEL] [ARGS]` | `python -m celery -A config beat -l info [ARGS]` |
+| `karni schedule list [--json]` | `manage.py karni_schedules`: every merged beat schedule |
+| `karni schedule run NAME` | `manage.py karni_schedules --run NAME`: runs the task once, synchronously |
+| `karni createsuperuser [ARGS]` | `manage.py createsuperuser [ARGS]` |
+| `karni manage ARGS` | `manage.py ARGS`: the raw passthrough for everything else |
+
+In docker mode, `shell`, `test`, `worker`, `beat`, `createsuperuser` and
+`manage` get a TTY (`docker compose exec` without `-T`) when karni runs in a
+terminal, so prompts and Ctrl-C work. Scripted and agent runs keep `-T`.
+With the compose stack up, `worker` and `beat` already run as services, so
+`karni worker` and `karni beat` are for `.venv` development. See
+`docs/events.md` and `docs/scheduling.md`.
+
+## Generators
+`karni make <type>` writes the project code a task needs, so neither a person
+nor an AI agent hand-creates a file a generator makes. `karni make --list`
+prints them all. Each one is also available as a hidden Laravel-style alias,
+`karni make:<type>`. The full reference (every option, the field DSL) is
+[docs/cli.md](https://cbsshekhawat18-lab.github.io/karni/cli/), generated from this CLI.
+
+| Command | Writes |
+|---|---|
+| `karni make app NAME` | `NAME/{__init__,apps,models,viewsets}.py`, `migrations/`, `tests/`, and wires `# karni:apps` |
+| `karni make model NAME [FIELD...]` | `class NAME(BaseModel)` in `<app>/models.py`, with `--with viewset,page` / `-a` chains and `--migrate` |
+| `karni make viewset MODEL` | `<Model>ViewSet` with its `access` (`--access authenticated\|public-read\|owned:<field>\|staff\|role:<name>`), `--search` |
+| `karni make serializer MODEL --reason ...` | `<app>/serializers.py` + `serializer_class` on the viewset |
+| `karni make migration [NAME]` | runs `manage.py makemigrations [--app] [--name] [--empty]` through the project interpreter |
+| `karni make task NAME` | `@shared_task` in `<app>/tasks.py` (`--retry N`) |
+| `karni make schedule NAME` | `every(...)`/`cron(...)` in `<app>/schedules.py` (`--every 15m` / `--cron "0 3 * * *"`, `--task`) |
+| `karni make event NAME` | a `Signal` in `<app>/events.py` |
+| `karni make listener NAME --on ...` | `<app>/listeners.py`: `Model.created\|updated\|deleted` or a custom event, with `--queued` |
+| `karni make command NAME` | `<app>/management/commands/NAME.py` |
+| `karni make service NAME` | `<app>/services/NAME.py` (where HTTP clients are allowed) |
+| `karni make middleware NAME` | `<app>/middleware.py`, wired through `# karni:middleware` |
+| `karni make page NAME` | `frontend/src/pages/NAME.tsx` (≤ 50 lines, `--resource R --kind list\|detail\|form`), route in `frontend/src/routes.tsx` |
+| `karni make component NAME` | `frontend/src/components/NAME.tsx` claiming a role (`--role`) |
+| `karni make module NAME` | `modules/karni-NAME/` per docs/modules.md |
+
+```sh
+karni make app events
+karni make model Event title:str:200 starts_at:datetime "status:choice:draft|live" \
+    organizer:fk:User 'venue:fk:Venue?' -a --access owned:organizer --search title
+karni make migration && karni migrate
+karni make listener notify_organizer --on Event.created --queued
+karni make schedule nightly-report --cron "0 3 * * *"
+```
+
+Every generator follows the same rules. It never overwrites without
+`--force`, and `--dry-run` prints the files and diff and writes nothing. It
+prints each created/modified file plus notes (the chosen `access`, the route,
+the next command). It resolves the app from `--app` or the project's only
+local app. It edits existing files only through marker comments or
+AST-located appends, and an unfamiliar layout is an error naming the manual
+step. It never imports Django. Generated Python is clean under ruff (lint and
+format) and `karni rules --check`, and generated pages parse and stay within
+50 lines. `tests/test_make_gate.py` generates every type into a fresh scaffold
+and asserts this (plus `tsc` and the frontend's ESLint config when
+`KARNI_TEST_NODE_MODULES` points at an installed `frontend/node_modules`).
+Then it runs the generated backend for real (makemigrations, migrate, check,
+requests through the Django test client).
+
+Quote fields that end in `?` in zsh (`'venue:fk:Venue?'`) and choice values
+joined by `|`.
+
+## Execution environment
+Commands that run the project resolve, in order: `--docker/--no-docker` flag →
+`<project>/.venv` → a running compose service (default `django`, changed with
+`--service` or `KARNI_COMPOSE_SERVICE`) → an error naming both remedies.
+
+## Links
+
+- The karni command: <https://cbsshekhawat18-lab.github.io/karni/cli/>
+- Quickstart: <https://cbsshekhawat18-lab.github.io/karni/quickstart/>
+- Karni, the framework this package is part of: <https://github.com/cbsshekhawat18-lab/karni>
+- Changelog: <https://github.com/cbsshekhawat18-lab/karni/blob/main/CHANGELOG.md>
+- Issues: <https://github.com/cbsshekhawat18-lab/karni/issues>
+- License: Apache-2.0. karni-cli is released with every other Karni package, at one version.

{karni_cli-0.3.1 → karni_cli-0.5.0}/hatch_build.py

@@ -11,7 +11,15 @@ to Karni's machine-readable changelog (packages/karni/karni/changelog ->
 karni_cli/_changelog), which `karni upgrade` reads: the CLI must know every
 change up to its own release, whatever karni the project has installed.
 Likewise Karni's error code registry (packages/karni/karni/errorcodes ->
-karni_cli/_errorcodes), which `karni explain` and error messages read.
+karni_cli/_errorcodes), which `karni explain` and error messages read, the
+settings reference (packages/karni/karni/conf/reference.py and the base.py it
+reads -> karni_cli/_settings), which `karni explain <SETTING>` reads, and
+@karni/ui's token stylesheet (packages/karni-ui/src/styles.css ->
+karni_cli/_ui/styles.css), whose defaults `karni ui detect` lists when a
+project has neither @karni/ui installed nor a monorepo checkout. And the
+module catalog (packages/karni/karni/catalog -> karni_cli/_catalog, with a
+copy of each module's karni.module.toml under _catalog/modules/), so
+`karni modules list` shows the modules a project has not installed.
 """
 
 from __future__ import annotations
@@ -49,6 +57,15 @@ class TemplateBundleHook(BuildHookInterface):
         self._bundle_karni(pkg_root, "agent", "_agent", "agent rules", build_data)
         self._bundle_karni(pkg_root, "changelog", "_changelog", "changelog", build_data)
         self._bundle_karni(pkg_root, "errorcodes", "_errorcodes", "error codes", build_data)
+        self._bundle_karni(pkg_root, "catalog", "_catalog", "module catalog", build_data)
+        manifests = sorted(pkg_root.parent.parent.glob("modules/*/karni_*/karni.module.toml"))
+        bundled_modules = pkg_root / "karni_cli" / "_catalog" / "modules"
+        if manifests:
+            bundled_modules.mkdir(parents=True, exist_ok=True)
+            for manifest in manifests:
+                shutil.copy2(manifest, bundled_modules / f"{manifest.parent.parent.name}.toml")
+        elif not bundled_modules.is_dir():
+            raise RuntimeError("No module manifests to bundle into karni_cli/_catalog/modules.")
         # karni.links (every published URL, stdlib only) rides inside the
         # errorcodes bundle: the registry loads it by path when karni is absent.
         links = pkg_root.parent / "karni" / "karni" / "links.py"
@@ -58,6 +75,26 @@ class TemplateBundleHook(BuildHookInterface):
         elif not bundled_links.is_file():
             raise RuntimeError("No karni/links.py to bundle into karni_cli/_errorcodes.")
 
+        # The settings reference (stdlib only) and the file it reads: `karni explain <SETTING>`.
+        settings_bundle = pkg_root / "karni_cli" / "_settings"
+        conf = pkg_root.parent / "karni" / "karni" / "conf"
+        if (conf / "reference.py").is_file():
+            settings_bundle.mkdir(parents=True, exist_ok=True)
+            for name in ("reference.py", "base.py"):
+                shutil.copy2(conf / name, settings_bundle / name)
+        elif not (settings_bundle / "reference.py").is_file():
+            raise RuntimeError("No karni/conf/reference.py to bundle into karni_cli/_settings.")
+        build_data["artifacts"].append("karni_cli/_settings/")
+
+        styles = pkg_root.parent / "karni-ui" / "src" / "styles.css"
+        bundled_styles = pkg_root / "karni_cli" / "_ui" / "styles.css"
+        if styles.is_file():
+            bundled_styles.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(styles, bundled_styles)
+        elif not bundled_styles.is_file():
+            raise RuntimeError("No @karni/ui styles.css to bundle into karni_cli/_ui.")
+        build_data["artifacts"].append("karni_cli/_ui/")
+
     @staticmethod
     def _bundle_karni(
         pkg_root: Path, package: str, bundle: str, what: str, build_data: dict[str, Any]

karni_cli-0.5.0/karni_cli/__init__.py

@@ -0,0 +1,8 @@
+"""karni-cli — the ``karni`` command."""
+
+from importlib import metadata as _metadata
+
+try:
+    __version__ = _metadata.version("karni-cli")  # [project] version in pyproject.toml
+except _metadata.PackageNotFoundError:  # a source tree on sys.path, never installed
+    __version__ = "0+unknown"

{karni_cli-0.3.1 → karni_cli-0.5.0}/karni_cli/_agent/__init__.py

@@ -16,7 +16,7 @@ from typing import Any
 from .check import check_file, check_source, supported
 from .history import active_conditions
 from .overrides import OVERRIDE_FILE, OverrideError, read_overrides, resolve_rules
-from .rules import CATEGORIES, PROCEDURES, RULES, Procedure, Rule
+from .rules import CATEGORIES, PROCEDURES, RULES, TOPICS, Procedure, Rule, Topic
 
 #: Bumped when the shape of :func:`dump` changes incompatibly.
 SCHEMA_VERSION = 1
@@ -27,9 +27,11 @@ __all__ = [
     "PROCEDURES",
     "RULES",
     "SCHEMA_VERSION",
+    "TOPICS",
     "OverrideError",
     "Procedure",
     "Rule",
+    "Topic",
     "check_file",
     "check_paths",
     "check_source",
@@ -64,6 +66,7 @@ def dump(root: str | Path | None = None) -> dict[str, Any]:
         "categories": [c for c in categories if any(r.category == c for r in rules)],
         "rules": [rule.to_dict() for rule in rules],
         "procedures": [procedure.to_dict() for procedure in PROCEDURES],
+        "topics": [topic.to_dict() for topic in TOPICS],
         "adapters": overrides.adapters,
         "overrides_file": str(overrides.path) if overrides.path else None,
         "conditions": sorted(conditions),