moarch-py 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. moarch_py-0.1.0/.agents/skills/add-template/SKILL.md +45 -0
  2. moarch_py-0.1.0/.agents/skills/explain/SKILL.md +66 -0
  3. moarch_py-0.1.0/.agents/skills/make-readable/SKILL.md +69 -0
  4. moarch_py-0.1.0/.agents/skills/release/SKILL.md +28 -0
  5. moarch_py-0.1.0/.agents/skills/try-scaffold/SKILL.md +54 -0
  6. moarch_py-0.1.0/.claude/skills/add-template/SKILL.md +9 -0
  7. moarch_py-0.1.0/.claude/skills/explain/SKILL.md +9 -0
  8. moarch_py-0.1.0/.claude/skills/make-readable/SKILL.md +9 -0
  9. moarch_py-0.1.0/.claude/skills/release/SKILL.md +9 -0
  10. moarch_py-0.1.0/.claude/skills/try-scaffold/SKILL.md +9 -0
  11. moarch_py-0.1.0/.github/workflows/ci.yml +42 -0
  12. moarch_py-0.1.0/.github/workflows/release.yml +24 -0
  13. moarch_py-0.1.0/.gitignore +13 -0
  14. moarch_py-0.1.0/.python-version +1 -0
  15. moarch_py-0.1.0/.vscode/extensions.json +8 -0
  16. moarch_py-0.1.0/.vscode/settings.json +20 -0
  17. moarch_py-0.1.0/AGENTS.md +129 -0
  18. moarch_py-0.1.0/CHANGELOG.md +18 -0
  19. moarch_py-0.1.0/CLAUDE.md +6 -0
  20. moarch_py-0.1.0/LICENSE +21 -0
  21. moarch_py-0.1.0/PKG-INFO +147 -0
  22. moarch_py-0.1.0/README.md +119 -0
  23. moarch_py-0.1.0/pyproject.toml +58 -0
  24. moarch_py-0.1.0/src/moarch_py/__init__.py +7 -0
  25. moarch_py-0.1.0/src/moarch_py/__main__.py +5 -0
  26. moarch_py-0.1.0/src/moarch_py/catalog.py +223 -0
  27. moarch_py-0.1.0/src/moarch_py/cli.py +136 -0
  28. moarch_py-0.1.0/src/moarch_py/commands.py +253 -0
  29. moarch_py-0.1.0/src/moarch_py/dependencies.py +43 -0
  30. moarch_py-0.1.0/src/moarch_py/file_plan.py +101 -0
  31. moarch_py-0.1.0/src/moarch_py/manifest.py +121 -0
  32. moarch_py-0.1.0/src/moarch_py/naming.py +134 -0
  33. moarch_py-0.1.0/src/moarch_py/options.py +105 -0
  34. moarch_py-0.1.0/src/moarch_py/pyproject_file.py +112 -0
  35. moarch_py-0.1.0/src/moarch_py/render.py +41 -0
  36. moarch_py-0.1.0/src/moarch_py/scaffold.py +139 -0
  37. moarch_py-0.1.0/src/moarch_py/templates/ai/AGENTS.md.j2 +134 -0
  38. moarch_py-0.1.0/src/moarch_py/templates/ai/CLAUDE.md.j2 +6 -0
  39. moarch_py-0.1.0/src/moarch_py/templates/ai/claude-settings.json.j2 +25 -0
  40. moarch_py-0.1.0/src/moarch_py/templates/ai/claude_skill.md.j2 +11 -0
  41. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/_done.md.j2 +10 -0
  42. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/_header.md.j2 +9 -0
  43. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/add-feature.md.j2 +73 -0
  44. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/explain.md.j2 +101 -0
  45. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/fix-bug.md.j2 +45 -0
  46. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/make-readable.md.j2 +104 -0
  47. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/review.md.j2 +47 -0
  48. moarch_py-0.1.0/src/moarch_py/templates/ai/skills/write-tests.md.j2 +57 -0
  49. moarch_py-0.1.0/src/moarch_py/templates/app/api/health.py.j2 +25 -0
  50. moarch_py-0.1.0/src/moarch_py/templates/app/api/v1/router.py.j2 +13 -0
  51. moarch_py-0.1.0/src/moarch_py/templates/app/core/config.py.j2 +46 -0
  52. moarch_py-0.1.0/src/moarch_py/templates/app/core/errors.py.j2 +56 -0
  53. moarch_py-0.1.0/src/moarch_py/templates/app/core/logging.py.j2 +32 -0
  54. moarch_py-0.1.0/src/moarch_py/templates/app/db/base.py.j2 +35 -0
  55. moarch_py-0.1.0/src/moarch_py/templates/app/db/models.py.j2 +12 -0
  56. moarch_py-0.1.0/src/moarch_py/templates/app/db/repository.py.j2 +54 -0
  57. moarch_py-0.1.0/src/moarch_py/templates/app/db/session.py.j2 +59 -0
  58. moarch_py-0.1.0/src/moarch_py/templates/app/empty_init.py.j2 +0 -0
  59. moarch_py-0.1.0/src/moarch_py/templates/app/features_init.py.j2 +12 -0
  60. moarch_py-0.1.0/src/moarch_py/templates/app/main.py.j2 +58 -0
  61. moarch_py-0.1.0/src/moarch_py/templates/app/package_init.py.j2 +1 -0
  62. moarch_py-0.1.0/src/moarch_py/templates/app/py.typed.j2 +0 -0
  63. moarch_py-0.1.0/src/moarch_py/templates/ci/ci.yml.j2 +87 -0
  64. moarch_py-0.1.0/src/moarch_py/templates/ci/pre-commit-config.yaml.j2 +24 -0
  65. moarch_py-0.1.0/src/moarch_py/templates/docker/Dockerfile.j2 +59 -0
  66. moarch_py-0.1.0/src/moarch_py/templates/docker/docker-compose.yml.j2 +68 -0
  67. moarch_py-0.1.0/src/moarch_py/templates/docker/dockerignore.j2 +19 -0
  68. moarch_py-0.1.0/src/moarch_py/templates/editor/vscode-extensions.json.j2 +8 -0
  69. moarch_py-0.1.0/src/moarch_py/templates/editor/vscode-settings.json.j2 +20 -0
  70. moarch_py-0.1.0/src/moarch_py/templates/feature/dependencies.py.j2 +17 -0
  71. moarch_py-0.1.0/src/moarch_py/templates/feature/models.py.j2 +15 -0
  72. moarch_py-0.1.0/src/moarch_py/templates/feature/package_init.py.j2 +1 -0
  73. moarch_py-0.1.0/src/moarch_py/templates/feature/repository.py.j2 +10 -0
  74. moarch_py-0.1.0/src/moarch_py/templates/feature/router.py.j2 +52 -0
  75. moarch_py-0.1.0/src/moarch_py/templates/feature/schemas.py.j2 +38 -0
  76. moarch_py-0.1.0/src/moarch_py/templates/feature/service.py.j2 +60 -0
  77. moarch_py-0.1.0/src/moarch_py/templates/feature/test_api.py.j2 +52 -0
  78. moarch_py-0.1.0/src/moarch_py/templates/migrations/alembic.ini.j2 +54 -0
  79. moarch_py-0.1.0/src/moarch_py/templates/migrations/env.py.j2 +62 -0
  80. moarch_py-0.1.0/src/moarch_py/templates/migrations/script.py.mako.j2 +26 -0
  81. moarch_py-0.1.0/src/moarch_py/templates/project/ARCHITECTURE.md.j2 +74 -0
  82. moarch_py-0.1.0/src/moarch_py/templates/project/README.md.j2 +57 -0
  83. moarch_py-0.1.0/src/moarch_py/templates/project/env.example.j2 +12 -0
  84. moarch_py-0.1.0/src/moarch_py/templates/project/gitignore.j2 +31 -0
  85. moarch_py-0.1.0/src/moarch_py/templates/project/python-version.j2 +1 -0
  86. moarch_py-0.1.0/src/moarch_py/templates/tests/conftest.py.j2 +44 -0
  87. moarch_py-0.1.0/src/moarch_py/templates/tests/test_health.py.j2 +15 -0
  88. moarch_py-0.1.0/src/moarch_py/terminal.py +35 -0
  89. moarch_py-0.1.0/src/moarch_py/uv_runner.py +41 -0
  90. moarch_py-0.1.0/src/moarch_py/wizard.py +38 -0
  91. moarch_py-0.1.0/tests/test_file_plan.py +64 -0
  92. moarch_py-0.1.0/tests/test_naming.py +45 -0
  93. moarch_py-0.1.0/tests/test_scaffold.py +142 -0
  94. moarch_py-0.1.0/tests/test_scaffold_real_project.py +48 -0
  95. moarch_py-0.1.0/uv.lock +604 -0
@@ -0,0 +1,45 @@
1
+ ---
2
+ name: add-template
3
+ description: "Add a file that moarch-py generates, or a new checklist option for `moarch-py init`, end to end: the Jinja template, its catalog entry, the option and its `when`, and the tests. Use when a generated project should get a new file, or a choice the wizard should offer."
4
+ ---
5
+
6
+ # Add a generated file or an init option
7
+
8
+ ## A new generated file
9
+
10
+ 1. **Template.** Write `src/moarch_py/templates/<area>/<file>.j2`. It can read
11
+ everything `scaffold.project_context` provides: `name` (`.distribution`,
12
+ `.package`, `.title`), `options`, `database`, `python_version`,
13
+ `uv_version`, `moarch_version`, `skills`. A misspelt variable fails the
14
+ render (`StrictUndefined`).
15
+ - `${{ }}` and Mako `${}` go inside `{% raw %}…{% endraw %}`.
16
+ - A literal `{` beside an expression is `{% raw %}{{% endraw %}`.
17
+ - Generated Python follows `templates/ai/AGENTS.md.j2`: typed, docstrings,
18
+ comments that say why.
19
+ 2. **Catalog entry** in `src/moarch_py/catalog.py`: a `ScaffoldSpec(slug, path,
20
+ template, group, when)`. The `slug` is unique and is what
21
+ `moarch-py update <slug>` will take; `group` is the batch `update <group>`
22
+ refreshes; `when` is a predicate on `ProjectOptions` (leave it out for
23
+ "always").
24
+ 3. **Test** in `tests/test_scaffold.py`: assert the content that matters
25
+ (not the whole file). The combination test already parses every `.py`,
26
+ `.yml` and `.json` for all 96 option sets.
27
+ 4. If the AI guide should mention it, update `templates/ai/AGENTS.md.j2`
28
+ and the skill that covers the task.
29
+
30
+ ## A new checklist option
31
+
32
+ 1. A field on `ProjectOptions` and a `ChecklistOption(key, label, default)`
33
+ in `options.CHECKLIST` (`key` equals the field name; it is what
34
+ `.moarch-py.yaml` records under `stack`).
35
+ 2. Its packages in `dependencies.dependencies_for`.
36
+ 3. Its files: catalog entries with `when=lambda options: options.<key>`
37
+ (as a named module-level function, like `_docker`).
38
+ 4. Anything it changes in shared files (`docker-compose.yml`, `ci.yml`,
39
+ `README.md`, `AGENTS.md`) as `{% if options.<key> %}` blocks.
40
+ 5. Tests: one that it is present when on, and the existing
41
+ `test_switched_off_options_leave_no_files` extended for "off".
42
+
43
+ ## Done when
44
+
45
+ `uv run python -m pytest` passes, then `try-scaffold` for the option on and off.
@@ -0,0 +1,66 @@
1
+ ---
2
+ name: explain
3
+ description: "Explain what the moarch-py CLI does, step by step, and teach the Python behind it with this repo's own code as the example: traces a command from the terminal through cli.py, commands.py, scaffold.py and the templates to the files on disk, names each concept with a short explanation and a link to the official docs, and ends with a way to see it happen. Use when asked how something works, why it is written that way, what happens when…, or to learn Python, Typer, Jinja or uv."
4
+ ---
5
+
6
+ # Explain the code and teach the Python behind it
7
+
8
+ The user should leave knowing **what happens, in what order, and why** — and
9
+ next time, need you a little less. Do not change code while explaining unless
10
+ asked; if the code is what makes it hard to follow, offer `make-readable`.
11
+
12
+ ## 1. Answer first, then show the path
13
+
14
+ One or two plain sentences, then the path through the files in the order it
15
+ runs, quoting the lines that matter as `path:line`, numbered.
16
+
17
+ | What happens | Starts at | Then |
18
+ |---|---|---|
19
+ | `moarch-py init shop-api` | `cli.py` → `init()` | `commands.run_init` → `resolve_project_root` → `collect_options` (flags or `wizard.py`) → `scaffold.plan_project` (each `catalog` spec → `render`) → `pyproject_file.build_pyproject` → `FilePlan.write` → `uv add` → `ruff format` → `git init` → `.moarch-py.yaml` |
20
+ | `moarch-py create feature orders` | `cli.py` → `create_feature()` | `commands.run_create_feature` → `load_manifest` → `FeatureName.parse` → `scaffold.plan_feature` (feature templates + `insert_at_anchor` ×3) → write → format → manifest |
21
+ | A name becomes identifiers | `naming.py` | `ProjectName.parse` / `FeatureName.parse` → every form the templates use |
22
+ | A file conflicts | `FilePlan.conflicts` | `FileConflictError` before anything is written → `cli._run` prints it, exit 1 |
23
+
24
+ Draw anything with more than three steps.
25
+
26
+ ## 2. Name every concept you pass
27
+
28
+ First time a concept comes up: one plain sentence, why it is used here, and
29
+ the link. Skip what the user already knows.
30
+
31
+ | Concept | In one sentence | Read more |
32
+ |---|---|---|
33
+ | `dataclass(frozen=True)` | A class whose fields are set once — options and names cannot change halfway through a run. | [docs.python.org](https://docs.python.org/3/library/dataclasses.html) |
34
+ | `StrEnum` | An enum whose values are strings, so `Database.POSTGRES == "postgres"` and Typer can parse it. | [docs.python.org](https://docs.python.org/3/library/enum.html#enum.StrEnum) |
35
+ | Type hints, `Annotated` | Hints document and check types; `Annotated` attaches extra info (Typer's option help) to one. | [docs.python.org](https://docs.python.org/3/library/typing.html#typing.Annotated) |
36
+ | `pathlib.Path` | Paths as objects (`root / "src"`), the same on Windows and Linux. | [docs.python.org](https://docs.python.org/3/library/pathlib.html) |
37
+ | `subprocess.run` | Runs another program (uv, git) and collects its output and exit code. | [docs.python.org](https://docs.python.org/3/library/subprocess.html) |
38
+ | Exceptions as control flow | Expected failures are custom exception classes, caught once in `cli._run`. | [docs.python.org](https://docs.python.org/3/tutorial/errors.html) |
39
+ | Typer commands | A function's parameters become the command's arguments and options. | [typer.tiangolo.com](https://typer.tiangolo.com/tutorial/) |
40
+ | Jinja templates | Text with `{{ variables }}` and `{% if %}` blocks, rendered into each file. | [jinja.palletsprojects.com](https://jinja.palletsprojects.com/en/stable/templates/) |
41
+ | `PackageLoader` | Loads templates from inside the installed package, so they ship in the wheel. | [jinja.palletsprojects.com](https://jinja.palletsprojects.com/en/stable/api/#jinja2.PackageLoader) |
42
+ | tomlkit | Edits TOML while keeping comments and order — for an existing `pyproject.toml`. | [tomlkit docs](https://tomlkit.readthedocs.io/) |
43
+ | uv, `uv add`, `uv.lock` | uv resolves packages; `add` records a lower bound in pyproject and the exact version in the lock. | [docs.astral.sh/uv](https://docs.astral.sh/uv/concepts/projects/dependencies/) |
44
+ | Entry points (`[project.scripts]`) | How installing the package creates the `moarch-py` command. | [packaging.python.org](https://packaging.python.org/en/latest/specifications/entry-points/) |
45
+ | pytest `parametrize`, `tmp_path` | One test run for many inputs; a fresh temp folder per test. | [docs.pytest.org](https://docs.pytest.org/en/stable/how-to/parametrize.html) |
46
+
47
+ Tie each concept to *this* code, and read a library's docs or source before
48
+ answering about it — never guess an API.
49
+
50
+ ## 3. Let them see it happen
51
+
52
+ - `uv run python -m moarch_py init demo --all --dry-run` lists every file without writing;
53
+ - `uv run python -c "from moarch_py.naming import FeatureName; print(FeatureName.parse('order_items'))"`;
54
+ - add a `breakpoint()` in `scaffold.plan_feature` and run
55
+ `uv run python -m pytest tests/test_scaffold.py -k feature`, then `p plan.files.keys()`.
56
+
57
+ ## 4. Check, then go one step further
58
+
59
+ End with one short question that checks the key idea ("why is the manifest
60
+ hashed after ruff runs, not before?") and offer the next thing worth learning.
61
+
62
+ ## After changing code
63
+
64
+ Whenever you change code for this user, end with: **what changed**, **what
65
+ happens now** step by step, **new concepts** with a link each, and **how to
66
+ see it** yourself.
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: make-readable
3
+ description: "Make code in the moarch-py CLI or its templates easier to read without changing what it does: names that say what a variable, function or class is, functions that do one thing, and comments that explain why wherever the logic is not obvious. Use when asked to clean up, clarify, rename, document or comment code, or when code is hard to follow."
4
+ ---
5
+
6
+ # Make code readable
7
+
8
+ The goal is code someone new can follow on the first read. Behaviour does not
9
+ change: the same command writes the same files, and every test that passed
10
+ before passes after.
11
+
12
+ ## 0. Before touching anything
13
+
14
+ - Read the code **and its callers** (search for each name you might change).
15
+ - Run `uv run python -m pytest` once, so you know what "still passes" means.
16
+ - Keep a readability change apart from a behaviour change; report a bug you
17
+ find separately.
18
+ - In a template, remember there are two readers: the person editing the
19
+ template here, and the person reading the generated file in their project.
20
+ Generated output matters more.
21
+
22
+ ## 1. Names
23
+
24
+ A name says **what the thing is**, in the words of the domain (projects,
25
+ features, templates, anchors, the manifest), not how it is stored.
26
+
27
+ | Instead of | Write | Why |
28
+ |---|---|---|
29
+ | `data`, `info`, `obj`, `tmp`, `res`, `ctx` | `plan`, `manifest`, `feature`, `template_context` | Says what it holds |
30
+ | `files_list`, `spec_dict` | `generated_files`, `specs_by_slug` | Plural for collections; no type in the name |
31
+ | `flag`, `check`, `ok` (a bool) | `is_installed`, `has_anchor`, `take_defaults` | A bool reads as a yes/no question |
32
+ | `handle()`, `process()`, `do()` | `plan_feature()`, `insert_at_anchor()` | A verb for what it does |
33
+ | `get_x()` that also writes | `write_manifest()` | No hidden side effects |
34
+ | `cfg`, `opts`, `p`, `s` | `settings`, `options`, `path`, `source` | No abbreviations (`id`, `url`, `uv`, `db` are fine) |
35
+ | `not_disabled` | `is_enabled` | No double negatives |
36
+ | `TemplateManager`, `helpers.py` | `render.py`, `catalog.py` | Name the job, not "manager" or "helper" |
37
+
38
+ PEP 8: `PascalCase` classes, `snake_case` everything else, `UPPER_SNAKE`
39
+ constants, `_private` for module-internal names. A rename of anything a
40
+ template reads (`name.package`, `options.docker`) must be made in every
41
+ template too — search `src/moarch_py/templates/`.
42
+
43
+ ## 2. Structure
44
+
45
+ - **One job per function**; split anything you need "and" to describe.
46
+ - **Pure first:** generation (`scaffold.py`) stays free of disk and
47
+ subprocesses; side effects belong in `commands.py`.
48
+ - **Return early** instead of nesting; give complex conditions a name.
49
+ - **No magic values:** a named constant (`PYTHON_VERSION`, `MANIFEST_FILE`).
50
+ - Delete commented-out code and unused imports.
51
+
52
+ ## 3. Comments and docstrings
53
+
54
+ Code says what; a comment says **why**, wherever a reader would stop: an
55
+ order that matters ("hash after ruff formats, or update sees an edit"), a
56
+ platform quirk ("cp1252 consoles cannot print ✓"), a Jinja trick
57
+ (`{% raw %}`), a choice that looks odd. Every public module, class and
58
+ function gets a one-line docstring. Never a comment that repeats the code;
59
+ never one that is no longer true.
60
+
61
+ ## 4. Report
62
+
63
+ 1. Renames as `old → new`, with why where not obvious.
64
+ 2. What you split, moved or commented, by `path:line`.
65
+ 3. What you left alone on purpose (a name templates or `.moarch-py.yaml` depend on).
66
+
67
+ ## Done when
68
+
69
+ `uv run python -m ruff format --check .`, `uv run python -m ruff check .` and `uv run python -m pytest` pass.
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: release
3
+ description: "Release a new moarch-py version to PyPI: pick the semver bump, update pyproject.toml and CHANGELOG.md, run every check, tag, and publish. Use when asked to release, publish, bump the version or cut a tag."
4
+ ---
5
+
6
+ # Release
7
+
8
+ 1. **Pick the bump** from what changed since the last tag
9
+ (`git log $(git describe --tags --abbrev=0)..HEAD --oneline`):
10
+ - patch: fixes to templates or the CLI, no new option or command;
11
+ - minor: a new command, option, generated file or skill;
12
+ - major: a command, flag or generated layout that works differently.
13
+ 2. **Version** in `pyproject.toml` only (`moarch_py.__version__` reads it from
14
+ the installed metadata): `uv version --bump <major|minor|patch>`.
15
+ Skip the bump when no tag exists yet and `uv version --short` is already
16
+ the version to release (the first release): bumping then makes the tag
17
+ and `pyproject.toml` disagree, and `release.yml` refuses to publish.
18
+ Before tagging, check `uv version --short` equals the tag without its `v`.
19
+ 3. **CHANGELOG.md**: a newest-first `## <version> — <date>` entry, written for
20
+ users: what they can now do, what changed in generated projects, and what
21
+ to run (`moarch-py update …`) to get it.
22
+ 4. **Checks:** `uv run python -m ruff format --check .`, `uv run python -m ruff check .`,
23
+ `uv run python -m pytest`, `uv run python -m pytest -m scaffold`, then `uv build` and inspect
24
+ that the wheel contains `moarch_py/templates/` (`unzip -l dist/*.whl`).
25
+ 5. **Commit and tag** only when the user asks: `git tag v<version>`.
26
+ 6. **Publish** only when the user asks: pushing the tag runs
27
+ `.github/workflows/release.yml` (PyPI trusted publishing). Never run
28
+ `uv publish` from a laptop with a token.
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: try-scaffold
3
+ description: "Generate real FastAPI projects from this moarch-py checkout and check they install, format, lint, type-check, migrate and test clean. Use after changing a template, before a release, or to reproduce a bug a user reported in a generated project."
4
+ ---
5
+
6
+ # Scaffold a real project
7
+
8
+ The fast tests check that templates render and parse; only a real project
9
+ checks that the result installs, passes ruff and mypy, and runs. Work in a
10
+ temporary directory, never inside this repository.
11
+
12
+ ## Automated
13
+
14
+ ```bash
15
+ uv run python -m pytest -m scaffold
16
+ ```
17
+
18
+ generates a Postgres and a SQLite project with `--all`, adds a feature, and
19
+ runs `ruff format --check`, `ruff check`, `mypy src` and `pytest` in each.
20
+
21
+ ## By hand (for an option off by default, or migrations and Docker)
22
+
23
+ ```bash
24
+ cd "$(mktemp -d)"
25
+ uv run --project <repo> python -m moarch_py init demo-api --all --db postgres
26
+ cd demo-api
27
+ uv run --project <repo> python -m moarch_py create feature orders
28
+ uv run --project <repo> python -m moarch_py create feature order_items
29
+ uv run python -m ruff format --check . && uv run python -m ruff check . && uv run python -m mypy src && uv run python -m pytest
30
+ ```
31
+
32
+ Migrations, against SQLite when no database server is running:
33
+
34
+ ```bash
35
+ DATABASE_URL=sqlite+aiosqlite:///./check.db uv run python -m alembic revision --autogenerate -m "init"
36
+ DATABASE_URL=sqlite+aiosqlite:///./check.db uv run python -m alembic upgrade head
37
+ DATABASE_URL=sqlite+aiosqlite:///./check.db uv run python -m alembic check
38
+ uv run python -m ruff check migrations
39
+ ```
40
+
41
+ Docker (needs the Docker daemon):
42
+
43
+ ```bash
44
+ docker compose up --build -d
45
+ curl http://localhost:8000/health/ready # {"status": "ok", "database": "ok"}
46
+ docker compose down -v
47
+ ```
48
+
49
+ Behind a TLS-intercepting proxy, export `UV_SYSTEM_CERTS=1` first.
50
+
51
+ ## Report
52
+
53
+ Each failure with the generated file and line and the template it came from.
54
+ Fix the **template**, never the generated file, and run again from the start.
@@ -0,0 +1,9 @@
1
+ ---
2
+ name: add-template
3
+ description: "Add a file that moarch-py generates, or a new checklist option for `moarch-py init`, end to end: the Jinja template, its catalog entry, the option and its `when`, and the tests. Use when a generated project should get a new file, or a choice the wizard should offer."
4
+ ---
5
+
6
+ Read `.agents/skills/add-template/SKILL.md` and follow it.
7
+
8
+ <!-- The steps live in .agents/skills/, which every other coding agent reads;
9
+ Claude Code only looks in .claude/skills/, so this file points there. -->
@@ -0,0 +1,9 @@
1
+ ---
2
+ name: explain
3
+ description: "Explain what the moarch-py CLI does, step by step, and teach the Python behind it with this repo's own code as the example: traces a command from the terminal through cli.py, commands.py, scaffold.py and the templates to the files on disk, names each concept with a short explanation and a link to the official docs, and ends with a way to see it happen. Use when asked how something works, why it is written that way, what happens when…, or to learn Python, Typer, Jinja or uv."
4
+ ---
5
+
6
+ Read `.agents/skills/explain/SKILL.md` and follow it.
7
+
8
+ <!-- The steps live in .agents/skills/, which every other coding agent reads;
9
+ Claude Code only looks in .claude/skills/, so this file points there. -->
@@ -0,0 +1,9 @@
1
+ ---
2
+ name: make-readable
3
+ description: "Make code in the moarch-py CLI or its templates easier to read without changing what it does: names that say what a variable, function or class is, functions that do one thing, and comments that explain why wherever the logic is not obvious. Use when asked to clean up, clarify, rename, document or comment code, or when code is hard to follow."
4
+ ---
5
+
6
+ Read `.agents/skills/make-readable/SKILL.md` and follow it.
7
+
8
+ <!-- The steps live in .agents/skills/, which every other coding agent reads;
9
+ Claude Code only looks in .claude/skills/, so this file points there. -->
@@ -0,0 +1,9 @@
1
+ ---
2
+ name: release
3
+ description: "Release a new moarch-py version to PyPI: pick the semver bump, update pyproject.toml and CHANGELOG.md, run every check, tag, and publish. Use when asked to release, publish, bump the version or cut a tag."
4
+ ---
5
+
6
+ Read `.agents/skills/release/SKILL.md` and follow it.
7
+
8
+ <!-- The steps live in .agents/skills/, which every other coding agent reads;
9
+ Claude Code only looks in .claude/skills/, so this file points there. -->
@@ -0,0 +1,9 @@
1
+ ---
2
+ name: try-scaffold
3
+ description: "Generate real FastAPI projects from this moarch-py checkout and check they install, format, lint, type-check, migrate and test clean. Use after changing a template, before a release, or to reproduce a bug a user reported in a generated project."
4
+ ---
5
+
6
+ Read `.agents/skills/try-scaffold/SKILL.md` and follow it.
7
+
8
+ <!-- The steps live in .agents/skills/, which every other coding agent reads;
9
+ Claude Code only looks in .claude/skills/, so this file points there. -->
@@ -0,0 +1,42 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ concurrency:
9
+ group: ${{ github.workflow }}-${{ github.ref }}
10
+ cancel-in-progress: true
11
+
12
+ jobs:
13
+ checks:
14
+ name: Format, lint, tests (Python ${{ matrix.python }}, ${{ matrix.os }})
15
+ runs-on: ${{ matrix.os }}
16
+ strategy:
17
+ fail-fast: false
18
+ matrix:
19
+ os: [ubuntu-latest, windows-latest]
20
+ python: ["3.12", "3.13"]
21
+ steps:
22
+ - uses: actions/checkout@v5
23
+ - uses: astral-sh/setup-uv@v6
24
+ with:
25
+ enable-cache: true
26
+ python-version: ${{ matrix.python }}
27
+ - run: uv sync --locked
28
+ - run: uv run ruff format --check .
29
+ - run: uv run ruff check .
30
+ - run: uv run pytest
31
+
32
+ scaffold:
33
+ name: Generated projects pass their own checks
34
+ runs-on: ubuntu-latest
35
+ needs: checks
36
+ steps:
37
+ - uses: actions/checkout@v5
38
+ - uses: astral-sh/setup-uv@v6
39
+ with:
40
+ enable-cache: true
41
+ - run: uv sync --locked
42
+ - run: uv run pytest -m scaffold
@@ -0,0 +1,24 @@
1
+ name: Release
2
+
3
+ # Pushing a tag `v1.2.3` builds and publishes that version to PyPI.
4
+ on:
5
+ push:
6
+ tags: ["v*"]
7
+
8
+ jobs:
9
+ publish:
10
+ runs-on: ubuntu-latest
11
+ environment: pypi
12
+ permissions:
13
+ # Trusted publishing: PyPI accepts this workflow's OIDC token, so no
14
+ # API token is stored anywhere. Configure it once on pypi.org.
15
+ id-token: write
16
+ steps:
17
+ - uses: actions/checkout@v5
18
+ - uses: astral-sh/setup-uv@v6
19
+ - run: uv sync --locked
20
+ - run: uv run pytest
21
+ - name: Tag matches pyproject version
22
+ run: test "v$(uv version --short)" = "${GITHUB_REF_NAME}"
23
+ - run: uv build
24
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,13 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ build/
5
+ dist/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .mypy_cache/
10
+ .coverage
11
+ .claude/settings.local.json
12
+ .DS_Store
13
+ Thumbs.db
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,8 @@
1
+ {
2
+ // VS Code offers to install these when the project is opened.
3
+ "recommendations": [
4
+ "charliermarsh.ruff",
5
+ "ms-python.python",
6
+ "ms-python.mypy-type-checker"
7
+ ]
8
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ // Ruff is the formatter and linter: the same tool, version and rules
3
+ // (pyproject.toml → [tool.ruff]) as CI and pre-commit, so a file saved here
4
+ // never fails `ruff format --check` or `ruff check` later.
5
+ "[python]": {
6
+ "editor.defaultFormatter": "charliermarsh.ruff",
7
+ "editor.formatOnSave": true,
8
+ "editor.codeActionsOnSave": {
9
+ "source.fixAll.ruff": "explicit",
10
+ "source.organizeImports.ruff": "explicit"
11
+ }
12
+ },
13
+ // The project's own environment, created by `uv sync`.
14
+ "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
15
+ "python.testing.pytestEnabled": true,
16
+ "python.testing.pytestArgs": ["tests"],
17
+ "mypy-type-checker.importStrategy": "fromEnvironment",
18
+ "files.insertFinalNewline": true,
19
+ "files.trimTrailingWhitespace": true
20
+ }
@@ -0,0 +1,129 @@
1
+ # AGENTS.md
2
+
3
+ Guidance for coding agents (Claude Code, Codex, Cursor, Copilot, Gemini CLI)
4
+ working in this repository. `CLAUDE.md` imports this file; step-by-step
5
+ procedures for the common changes are in `.agents/skills/` (see
6
+ [Skills](#skills)).
7
+
8
+ ## What this is
9
+
10
+ `moarch-py` (PyPI) is a Python CLI that scaffolds **feature-first FastAPI
11
+ projects** on uv, SQLAlchemy 2 async, Alembic and Pydantic v2. It is the
12
+ Python sibling of the Flutter CLI
13
+ (`moarch`, https://pub.dev/packages/moarch) and **must keep the same command grammar**:
14
+ `init`, `create <thing>`, `update [name|group]`, `doctor [--fix]`,
15
+ `release bump`, with `--all`, `--preset`, `--dry-run`, `--list`, `--diff`,
16
+ `# moarch:<anchor>` comments and a `.moarch-py.yaml` manifest. Before naming a
17
+ command or flag, check the Flutter README and reuse its word.
18
+
19
+ Every file the CLI generates is a **Jinja template** in
20
+ `src/moarch_py/templates/`. Editing a template changes what other people's
21
+ projects get, so treat template text as production code.
22
+
23
+ ## Commands
24
+
25
+ ```bash
26
+ uv sync
27
+ uv run python -m pytest # fast suite (every option combination, no network)
28
+ uv run python -m pytest -m scaffold # generates real projects and runs their checks (slow)
29
+ uv run python -m pytest tests/test_scaffold.py -k feature
30
+ uv run python -m ruff format .
31
+ uv run python -m ruff check .
32
+ uv run python -m moarch_py <args> # run this checkout's CLI
33
+ uv tool install --editable . # install this checkout as `moarch-py`
34
+ ```
35
+
36
+ Behind a TLS-intercepting proxy, uv needs `UV_SYSTEM_CERTS=1`.
37
+
38
+ **Run tools as `python -m <tool>`, never the `.venv/Scripts/*.exe` launchers**
39
+ (`uv run pytest`, `uv run python -m mypy`…). On the maintainer's Windows machine, AVG's
40
+ Auto-Sandbox sandboxes every such launcher and can freeze the PC; `python.exe`
41
+ is not flagged. For the same reason the `scaffold` tests (which build fresh
42
+ venvs) are skipped locally unless `MOARCH_PY_SCAFFOLD=1`; CI runs them.
43
+
44
+ ## Architecture
45
+
46
+ `cli.py` (Typer) → `commands.py` (disk, uv, git, output) → `scaffold.py`
47
+ (pure: options → `FilePlan`) → `render.py` (Jinja) + `catalog.py`.
48
+
49
+ - **Generation is pure.** `scaffold.plan_project` / `plan_feature` return a
50
+ `FilePlan` (path → content) and never touch disk or run processes. That is
51
+ what makes `--dry-run` exact and lets `tests/test_scaffold.py` render all 96
52
+ option combinations in about a second. Side effects live only in `commands.py`.
53
+ - **Plan, check, then write.** `FilePlan.write` checks every conflict before
54
+ writing the first file, so a failed command leaves nothing half-written.
55
+ `plan.edit()` marks an intended change to an existing file (an anchor
56
+ insert), which is never a conflict.
57
+ - **The catalog is the registry.** `catalog.CATALOG` lists every file `init`
58
+ writes as a `ScaffoldSpec` (slug, path, template, group, `when`). **A new
59
+ generated file is a template plus a catalog entry**; miss the entry and it
60
+ is never written, and `update` can never refresh it. Slugs are unique
61
+ (tested).
62
+ - **Options are one dataclass.** `options.ProjectOptions` holds every
63
+ answer; `options.CHECKLIST` is the wizard's checklist. A new checklist
64
+ option is a field there, a `ChecklistOption`, and `when=` predicates in the
65
+ catalog; the combination test picks it up on its own.
66
+ - **Anchors.** `file_plan.insert_at_anchor` inserts above a
67
+ `# moarch:<name>` line with its indentation, idempotently; a missing anchor
68
+ raises `AnchorNotFoundError` carrying the snippet to paste by hand.
69
+ - **Dependencies are not pinned here.** `dependencies.py` lists names;
70
+ `init` runs `uv add`, which writes the newest compatible versions as lower
71
+ bounds and the exact ones to `uv.lock`.
72
+ - **The manifest** (`manifest.py`, `.moarch-py.yaml`) records each generated
73
+ file's hash *after* ruff formats it, so `update` can tell untouched files
74
+ from edited ones.
75
+ - **Generated projects target Python 3.12** (`scaffold.PYTHON_VERSION`), the
76
+ most used version; `requires-python` is a floor.
77
+
78
+ ## Rules for templates
79
+
80
+ - Generated code must pass, in the generated project: `ruff format --check`,
81
+ `ruff check` (the rule set in `pyproject_file._ruff_config`), `mypy --strict`
82
+ and its own `pytest`. The `scaffold` tests check exactly that.
83
+ - `StrictUndefined` is on: a misspelt variable fails the render.
84
+ - `${{ }}` (GitHub Actions) and Mako's `${}` go inside `{% raw %}`.
85
+ - A literal `{` next to a Jinja expression (an f-string, a path parameter) is
86
+ written `{% raw %}{{% endraw %}`.
87
+ - Generated code follows the rules it teaches (`templates/ai/AGENTS.md.j2`):
88
+ names in the product's words, one job per function, comments that say why,
89
+ a docstring on every public class and function.
90
+
91
+ ## Code you can read
92
+
93
+ The same standard applies to this repo's own code: names that say what a
94
+ thing is, one job per function, early returns, comments for the why, and a
95
+ docstring on every public module, class and function. Follow
96
+ `make-readable` for a cleanup pass.
97
+
98
+ ## Done when
99
+
100
+ ```bash
101
+ uv run python -m ruff format --check .
102
+ uv run python -m ruff check .
103
+ uv run python -m pytest
104
+ ```
105
+
106
+ pass, and for a template change, `uv run python -m pytest -m scaffold` too (or the
107
+ `try-scaffold` skill).
108
+
109
+ ## After every change, tell the user
110
+
111
+ 1. **What changed:** the files, and what each change does.
112
+ 2. **What happens now** when it runs: the path through the code, step by step.
113
+ 3. **Concepts used:** any Python or library idea the change relies on, one
114
+ sentence and a link to its official docs.
115
+ 4. **How to see it:** the command to run to watch it work.
116
+
117
+ When asked how something works, follow `explain`.
118
+
119
+ ## Skills
120
+
121
+ | Skill | For |
122
+ |---|---|
123
+ | [`add-template`](.agents/skills/add-template/SKILL.md) | A new generated file or checklist option |
124
+ | [`try-scaffold`](.agents/skills/try-scaffold/SKILL.md) | Generate real projects and check they build, lint, type-check and test clean |
125
+ | [`release`](.agents/skills/release/SKILL.md) | Bump the version, changelog, publish to PyPI |
126
+ | [`make-readable`](.agents/skills/make-readable/SKILL.md) | Clearer names, smaller functions, comments that explain why |
127
+ | [`explain`](.agents/skills/explain/SKILL.md) | Teach how this CLI works, step by step, with links |
128
+
129
+ Claude Code reads `.claude/skills/`, whose files point here.
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 — 21/11/2026
4
+
5
+ First version.
6
+
7
+ - `moarch-py init [name]`: interactive wizard (database; migrations, Docker,
8
+ CI, pre-commit, AI guide), `--all`, `--db`, `--dry-run`, `--no-install`,
9
+ `--force`. Runs `uv add`, formats with Ruff, starts a git repository and
10
+ writes `.moarch-py.yaml`.
11
+ - `moarch-py create feature <name>`: model, schemas, repository, service,
12
+ router, dependencies and API tests, registered at the `# moarch:` anchors.
13
+ - Generated projects: Python 3.12, FastAPI, SQLAlchemy 2 async, Alembic,
14
+ pydantic-settings, multi-stage uv Dockerfile, docker-compose, GitHub
15
+ Actions, pre-commit, Ruff (CLI, pre-commit, CI and VS Code on save), mypy
16
+ strict, pytest on in-memory SQLite.
17
+ - AI agent guide: `AGENTS.md`, `CLAUDE.md` and six skills (add-feature,
18
+ write-tests, fix-bug, review, make-readable, explain).
@@ -0,0 +1,6 @@
1
+ # CLAUDE.md
2
+
3
+ @AGENTS.md
4
+
5
+ <!-- The instructions live in AGENTS.md, which every coding agent reads; this
6
+ file only imports them for Claude Code. -->
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 André Montoito
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.