karni-cli 0.3.1__tar.gz

karni_cli-0.3.1/.gitignore

@@ -0,0 +1,38 @@
+.learning/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Build artifacts
+dist/
+build/
+packages/karni-cli/karni_cli/_templates/
+packages/karni-cli/karni_cli/_agent/
+packages/karni-cli/karni_cli/_changelog/
+packages/karni-cli/karni_cli/_errorcodes/
+
+# Node
+node_modules/
+storybook-static/
+*.tsbuildinfo
+
+# Local env / editor / tooling
+.env
+.env.*
+!.env.example
+.DS_Store
+.idea/
+.claude/scheduled_tasks.lock
+.claude/settings.local.json
+
+# MkDocs build output
+site/

karni_cli-0.3.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

karni_cli-0.3.1/PKG-INFO

@@ -0,0 +1,191 @@
+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.
+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
+Project-URL: Issues, https://github.com/cbsshekhawat18-lab/karni/issues
+Project-URL: Changelog, https://github.com/cbsshekhawat18-lab/karni/tree/main/docs/migrations
+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
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cookiecutter>=2.5
+Requires-Dist: libcst>=1.4
+Requires-Dist: packaging>=24.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomlkit>=0.12
+Requires-Dist: typer>=0.12
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+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.
+
+## 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
+  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 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
+  `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]` — 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.
+  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 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
+  (`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
+  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; every one is also 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 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 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: 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).
+
+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
+`--service` or `KARNI_COMPOSE_SERVICE`) → an error naming both remedies.

karni_cli-0.3.1/README.md

@@ -0,0 +1,153 @@
+# karni-cli
+
+The `karni` command. Orchestrates a Karni project's own `manage.py` via
+subprocess — the CLI itself never imports Django.
+
+## 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
+  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 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
+  `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]` — 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.
+  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 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
+  (`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
+  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; every one is also 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 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 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: 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).
+
+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
+`--service` or `KARNI_COMPOSE_SERVICE`) → an error naming both remedies.

karni_cli-0.3.1/hatch_build.py

@@ -0,0 +1,77 @@
+"""Hatch build hook: bundle templates/project into the wheel (contract E7).
+
+From the monorepo, ../../templates/project is copied to karni_cli/_templates/
+project so sdists are self-contained. Building a wheel FROM an sdist finds the
+copy already in-tree and no-ops — never a missing-source error.
+
+The same applies to Karni's stdlib-only agent rules (packages/karni/karni/
+agent -> karni_cli/_agent): the fallback `karni rules` / `karni new` use when
+karni itself is not importable and no project interpreter is reachable. And
+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.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class TemplateBundleHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        pkg_root = Path(self.root)
+        bundled = pkg_root / "karni_cli" / "_templates" / "project"
+        repo_source = pkg_root.parent.parent / "templates" / "project"
+
+        if repo_source.is_dir():
+            if bundled.exists():
+                shutil.rmtree(bundled)
+            shutil.copytree(
+                repo_source,
+                bundled,
+                ignore=shutil.ignore_patterns("__pycache__", "node_modules", ".DS_Store"),
+            )
+        elif not bundled.is_dir():
+            raise RuntimeError(
+                "No project template available: neither the monorepo templates/ "
+                "nor a bundled karni_cli/_templates copy exists."
+            )
+        build_data.setdefault("artifacts", []).append("karni_cli/_templates/")
+
+        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)
+        # 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"
+        bundled_links = pkg_root / "karni_cli" / "_errorcodes" / "links.py"
+        if links.is_file():
+            shutil.copy2(links, bundled_links)
+        elif not bundled_links.is_file():
+            raise RuntimeError("No karni/links.py to bundle into karni_cli/_errorcodes.")
+
+    @staticmethod
+    def _bundle_karni(
+        pkg_root: Path, package: str, bundle: str, what: str, build_data: dict[str, Any]
+    ) -> None:
+        """Copy the stdlib-only ``karni/<package>`` into ``karni_cli/<bundle>``."""
+        bundled = pkg_root / "karni_cli" / bundle
+        source = pkg_root.parent / "karni" / "karni" / package
+        if source.is_dir():
+            if bundled.exists():
+                shutil.rmtree(bundled)
+            shutil.copytree(source, bundled, ignore=shutil.ignore_patterns("__pycache__"))
+        elif not bundled.is_dir():
+            raise RuntimeError(
+                f"No {what} available: neither the monorepo packages/karni/karni/{package} "
+                f"nor a bundled karni_cli/{bundle} copy exists."
+            )
+        build_data["artifacts"].append(f"karni_cli/{bundle}/")