repocraft 0.4.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 (120) hide show
  1. repocraft-0.4.0/.gitattributes +1 -0
  2. repocraft-0.4.0/.github/dependabot.yml +12 -0
  3. repocraft-0.4.0/.github/workflows/ci.yml +44 -0
  4. repocraft-0.4.0/.github/workflows/codeql.yml +26 -0
  5. repocraft-0.4.0/.gitignore +12 -0
  6. repocraft-0.4.0/CONTRIBUTING.md +57 -0
  7. repocraft-0.4.0/LICENSE +21 -0
  8. repocraft-0.4.0/PKG-INFO +311 -0
  9. repocraft-0.4.0/README.md +278 -0
  10. repocraft-0.4.0/SECURITY.md +20 -0
  11. repocraft-0.4.0/pyproject.toml +81 -0
  12. repocraft-0.4.0/scripts/check_junit.py +40 -0
  13. repocraft-0.4.0/scripts/local_ci.py +50 -0
  14. repocraft-0.4.0/src/repocraft/__init__.py +5 -0
  15. repocraft-0.4.0/src/repocraft/__main__.py +5 -0
  16. repocraft-0.4.0/src/repocraft/cli.py +284 -0
  17. repocraft-0.4.0/src/repocraft/craft.py +178 -0
  18. repocraft-0.4.0/src/repocraft/errors.py +27 -0
  19. repocraft-0.4.0/src/repocraft/intent.py +167 -0
  20. repocraft-0.4.0/src/repocraft/recipe.py +268 -0
  21. repocraft-0.4.0/src/repocraft/recipes/factorial.py.j2 +22 -0
  22. repocraft-0.4.0/src/repocraft/recipes/factorial.yaml +12 -0
  23. repocraft-0.4.0/src/repocraft/recipes/fibonacci.py.j2 +22 -0
  24. repocraft-0.4.0/src/repocraft/recipes/fibonacci.yaml +12 -0
  25. repocraft-0.4.0/src/repocraft/recipes/fizzbuzz.py.j2 +29 -0
  26. repocraft-0.4.0/src/repocraft/recipes/fizzbuzz.yaml +13 -0
  27. repocraft-0.4.0/src/repocraft/recipes/pascal.py.j2 +25 -0
  28. repocraft-0.4.0/src/repocraft/recipes/pascal.yaml +13 -0
  29. repocraft-0.4.0/src/repocraft/recipes/password.py.j2 +24 -0
  30. repocraft-0.4.0/src/repocraft/recipes/password.yaml +14 -0
  31. repocraft-0.4.0/src/repocraft/recipes/prime_sieve.py.j2 +31 -0
  32. repocraft-0.4.0/src/repocraft/recipes/prime_sieve.yaml +14 -0
  33. repocraft-0.4.0/src/repocraft/recipes/test_factorial.py.j2 +23 -0
  34. repocraft-0.4.0/src/repocraft/recipes/test_fibonacci.py.j2 +29 -0
  35. repocraft-0.4.0/src/repocraft/recipes/test_fizzbuzz.py.j2 +46 -0
  36. repocraft-0.4.0/src/repocraft/recipes/test_pascal.py.j2 +32 -0
  37. repocraft-0.4.0/src/repocraft/recipes/test_password.py.j2 +29 -0
  38. repocraft-0.4.0/src/repocraft/recipes/test_prime_sieve.py.j2 +30 -0
  39. repocraft-0.4.0/src/repocraft/recipes/test_triangle.py.j2 +27 -0
  40. repocraft-0.4.0/src/repocraft/recipes/triangle.py.j2 +21 -0
  41. repocraft-0.4.0/src/repocraft/recipes/triangle.yaml +13 -0
  42. repocraft-0.4.0/src/repocraft/render.py +126 -0
  43. repocraft-0.4.0/src/repocraft/schema/recipe.schema.json +72 -0
  44. repocraft-0.4.0/src/repocraft/schema/spec.schema.json +116 -0
  45. repocraft-0.4.0/src/repocraft/spec.py +104 -0
  46. repocraft-0.4.0/src/repocraft/templates/cli/cli.py.j2 +26 -0
  47. repocraft-0.4.0/src/repocraft/templates/cli/main.py.j2 +5 -0
  48. repocraft-0.4.0/src/repocraft/templates/cli/test_cli.py.j2 +36 -0
  49. repocraft-0.4.0/src/repocraft/templates/common/CONTRIBUTING.md.j2 +28 -0
  50. repocraft-0.4.0/src/repocraft/templates/common/README.md.j2 +53 -0
  51. repocraft-0.4.0/src/repocraft/templates/common/SECURITY.md.j2 +22 -0
  52. repocraft-0.4.0/src/repocraft/templates/common/check_junit.py +40 -0
  53. repocraft-0.4.0/src/repocraft/templates/common/ci.yml.j2 +38 -0
  54. repocraft-0.4.0/src/repocraft/templates/common/codeql.yml.j2 +26 -0
  55. repocraft-0.4.0/src/repocraft/templates/common/dependabot.yml +12 -0
  56. repocraft-0.4.0/src/repocraft/templates/common/gitignore.txt +12 -0
  57. repocraft-0.4.0/src/repocraft/templates/common/init.py.j2 +8 -0
  58. repocraft-0.4.0/src/repocraft/templates/common/py.typed +0 -0
  59. repocraft-0.4.0/src/repocraft/templates/common/pyproject.toml.j2 +64 -0
  60. repocraft-0.4.0/src/repocraft/templates/common/test_metadata.py.j2 +9 -0
  61. repocraft-0.4.0/src/repocraft/templates/library/core.py.j2 +8 -0
  62. repocraft-0.4.0/src/repocraft/templates/library/test_core.py.j2 +9 -0
  63. repocraft-0.4.0/src/repocraft/templates/licenses/Apache-2.0.txt.j2 +202 -0
  64. repocraft-0.4.0/src/repocraft/templates/licenses/MIT.txt.j2 +21 -0
  65. repocraft-0.4.0/tests/fixtures/cli.yaml +16 -0
  66. repocraft-0.4.0/tests/fixtures/library.yaml +8 -0
  67. repocraft-0.4.0/tests/golden/cli/.github/dependabot.yml +12 -0
  68. repocraft-0.4.0/tests/golden/cli/.github/workflows/ci.yml +38 -0
  69. repocraft-0.4.0/tests/golden/cli/.github/workflows/codeql.yml +26 -0
  70. repocraft-0.4.0/tests/golden/cli/.gitignore +12 -0
  71. repocraft-0.4.0/tests/golden/cli/CONTRIBUTING.md +28 -0
  72. repocraft-0.4.0/tests/golden/cli/LICENSE +202 -0
  73. repocraft-0.4.0/tests/golden/cli/README.md +42 -0
  74. repocraft-0.4.0/tests/golden/cli/SECURITY.md +18 -0
  75. repocraft-0.4.0/tests/golden/cli/pyproject.toml +67 -0
  76. repocraft-0.4.0/tests/golden/cli/scripts/check_junit.py +40 -0
  77. repocraft-0.4.0/tests/golden/cli/src/example_cli/__init__.py +3 -0
  78. repocraft-0.4.0/tests/golden/cli/src/example_cli/__main__.py +5 -0
  79. repocraft-0.4.0/tests/golden/cli/src/example_cli/cli.py +26 -0
  80. repocraft-0.4.0/tests/golden/cli/src/example_cli/py.typed +0 -0
  81. repocraft-0.4.0/tests/golden/cli/tests/test_cli.py +36 -0
  82. repocraft-0.4.0/tests/golden/cli/tests/test_metadata.py +9 -0
  83. repocraft-0.4.0/tests/golden/library/.github/dependabot.yml +12 -0
  84. repocraft-0.4.0/tests/golden/library/.github/workflows/ci.yml +38 -0
  85. repocraft-0.4.0/tests/golden/library/.github/workflows/codeql.yml +26 -0
  86. repocraft-0.4.0/tests/golden/library/.gitignore +12 -0
  87. repocraft-0.4.0/tests/golden/library/CONTRIBUTING.md +28 -0
  88. repocraft-0.4.0/tests/golden/library/LICENSE +21 -0
  89. repocraft-0.4.0/tests/golden/library/README.md +40 -0
  90. repocraft-0.4.0/tests/golden/library/SECURITY.md +17 -0
  91. repocraft-0.4.0/tests/golden/library/pyproject.toml +61 -0
  92. repocraft-0.4.0/tests/golden/library/scripts/check_junit.py +40 -0
  93. repocraft-0.4.0/tests/golden/library/src/example_library/__init__.py +6 -0
  94. repocraft-0.4.0/tests/golden/library/src/example_library/core.py +8 -0
  95. repocraft-0.4.0/tests/golden/library/src/example_library/py.typed +0 -0
  96. repocraft-0.4.0/tests/golden/library/tests/test_core.py +9 -0
  97. repocraft-0.4.0/tests/golden/library/tests/test_metadata.py +9 -0
  98. repocraft-0.4.0/tests/golden/recipes/factorial/factorial.py +22 -0
  99. repocraft-0.4.0/tests/golden/recipes/factorial/test_factorial.py +23 -0
  100. repocraft-0.4.0/tests/golden/recipes/fibonacci/fibonacci.py +22 -0
  101. repocraft-0.4.0/tests/golden/recipes/fibonacci/test_fibonacci.py +29 -0
  102. repocraft-0.4.0/tests/golden/recipes/fizzbuzz/fizzbuzz.py +29 -0
  103. repocraft-0.4.0/tests/golden/recipes/fizzbuzz/test_fizzbuzz.py +46 -0
  104. repocraft-0.4.0/tests/golden/recipes/pascal/pascal.py +25 -0
  105. repocraft-0.4.0/tests/golden/recipes/pascal/test_pascal.py +32 -0
  106. repocraft-0.4.0/tests/golden/recipes/password/password.py +24 -0
  107. repocraft-0.4.0/tests/golden/recipes/password/test_password.py +29 -0
  108. repocraft-0.4.0/tests/golden/recipes/prime_sieve/prime_sieve.py +31 -0
  109. repocraft-0.4.0/tests/golden/recipes/prime_sieve/test_prime_sieve.py +30 -0
  110. repocraft-0.4.0/tests/golden/recipes/triangle/test_triangle.py +27 -0
  111. repocraft-0.4.0/tests/golden/recipes/triangle/triangle.py +21 -0
  112. repocraft-0.4.0/tests/test_check_junit.py +68 -0
  113. repocraft-0.4.0/tests/test_cli.py +493 -0
  114. repocraft-0.4.0/tests/test_craft.py +246 -0
  115. repocraft-0.4.0/tests/test_intent.py +232 -0
  116. repocraft-0.4.0/tests/test_package.py +9 -0
  117. repocraft-0.4.0/tests/test_recipe.py +366 -0
  118. repocraft-0.4.0/tests/test_render.py +115 -0
  119. repocraft-0.4.0/tests/test_smoke.py +82 -0
  120. repocraft-0.4.0/tests/test_spec.py +112 -0
@@ -0,0 +1 @@
1
+ * text=auto eol=lf
@@ -0,0 +1,12 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: pip
4
+ directory: "/"
5
+ schedule:
6
+ interval: weekly
7
+ open-pull-requests-limit: 5
8
+ - package-ecosystem: github-actions
9
+ directory: "/"
10
+ schedule:
11
+ interval: weekly
12
+ open-pull-requests-limit: 5
@@ -0,0 +1,44 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ concurrency:
12
+ group: ci-${{ github.ref }}
13
+ cancel-in-progress: true
14
+
15
+ jobs:
16
+ test:
17
+ runs-on: ubuntu-latest
18
+ strategy:
19
+ fail-fast: false
20
+ matrix:
21
+ python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
22
+ steps:
23
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
24
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
25
+ with:
26
+ python-version: ${{ matrix.python-version }}
27
+ - name: Install
28
+ run: |
29
+ python -m pip install --upgrade pip
30
+ python -m pip install -e ".[dev]"
31
+ - name: Lint
32
+ run: python -m ruff check .
33
+ - name: Type check
34
+ run: python -m mypy
35
+ - name: Test
36
+ run: >-
37
+ python -m pytest
38
+ --cov=repocraft
39
+ --cov-branch
40
+ --cov-report=term-missing
41
+ --cov-fail-under=100
42
+ --junitxml=junit.xml
43
+ - name: Reject skipped tests
44
+ run: python scripts/check_junit.py junit.xml
@@ -0,0 +1,26 @@
1
+ name: CodeQL
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+ schedule:
9
+ - cron: "17 4 * * 1"
10
+
11
+ permissions:
12
+ contents: read
13
+ security-events: write
14
+
15
+ jobs:
16
+ analyze:
17
+ # Code scanning is free for public repositories. Private repositories need
18
+ # GitHub Advanced Security, so the job is skipped there instead of failing.
19
+ if: ${{ github.event.repository.private == false }}
20
+ runs-on: ubuntu-latest
21
+ steps:
22
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
23
+ - uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
24
+ with:
25
+ languages: python
26
+ - uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
@@ -0,0 +1,12 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .venv*/
5
+ build/
6
+ dist/
7
+ .coverage
8
+ coverage.xml
9
+ junit.xml
10
+ .mypy_cache/
11
+ .pytest_cache/
12
+ .ruff_cache/
@@ -0,0 +1,57 @@
1
+ # Contributing
2
+
3
+ ## Setup
4
+
5
+ ```bash
6
+ python -m venv .venv
7
+ . .venv/bin/activate # Windows: .venv\Scripts\activate
8
+ python -m pip install -e ".[dev]"
9
+ ```
10
+
11
+ ## Checks
12
+
13
+ ```bash
14
+ python -m ruff check .
15
+ python -m mypy
16
+ python -m pytest --cov=repocraft --cov-branch --cov-report=term-missing --cov-fail-under=100
17
+ ```
18
+
19
+ Coverage must stay at 100% of branches. The test suite includes smoke tests that
20
+ render the fixtures, install them into temporary target directories, and run the
21
+ generated projects' own gates. It also runs every generated snippet's own
22
+ `unittest` file. A change that breaks generated output will fail the suite.
23
+
24
+ ## Recipes
25
+
26
+ Each recipe lives in `src/repocraft/recipes/` as `<id>.yaml` plus `<id>.py.j2`
27
+ and `test_<id>.py.j2`. The YAML is validated against
28
+ `schema/recipe.schema.json` at load time, and the id must match the file name.
29
+ Parameters are bounded integers; templates may only use the validated values.
30
+ The matcher, writer, and CLI live in `src/repocraft/recipe.py` and
31
+ `src/repocraft/cli.py`.
32
+
33
+ Add unit tests for new matching rules and recipes, and keep the generated
34
+ snippet executable with the standard library.
35
+
36
+ ## Golden snapshots
37
+
38
+ When a template changes intentionally, remove the affected snapshots first
39
+ because both renderers refuse to overwrite existing files, then regenerate them:
40
+
41
+ ```bash
42
+ rm -rf tests/golden/library tests/golden/cli
43
+ python -c "from pathlib import Path; from repocraft.render import render_project; from repocraft.spec import load_spec; [(render_project(load_spec(Path('tests/fixtures') / (name + '.yaml')), Path('tests/golden') / name)) for name in ('library', 'cli')]"
44
+ ```
45
+
46
+ ```bash
47
+ rm -rf tests/golden/recipes
48
+ python -c "from pathlib import Path; from repocraft.recipe import load_recipes, render_recipe, resolve_parameters, write_files; [(write_files(render_recipe(recipe, resolve_parameters(recipe, {})), Path('tests/golden/recipes') / recipe.id)) for recipe in load_recipes()]"
49
+ ```
50
+
51
+ Review every changed golden file before committing it.
52
+
53
+ ## Pull requests
54
+
55
+ - Keep each change focused and explain why it is needed.
56
+ - Add tests for behavior changes.
57
+ - Write code, comments, and documentation in English.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Furkan
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.
@@ -0,0 +1,311 @@
1
+ Metadata-Version: 2.5
2
+ Name: repocraft
3
+ Version: 0.4.0
4
+ Summary: Deterministic Python project scaffolding from a validated spec.
5
+ Project-URL: Repository, https://github.com/Furox-Art/repocraft
6
+ Author: Furkan
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: code-generation,deterministic,python,scaffolding
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Software Development :: Code Generators
20
+ Requires-Python: >=3.10
21
+ Requires-Dist: jinja2<4,>=3.1
22
+ Requires-Dist: jsonschema<5,>=4.23
23
+ Requires-Dist: pyyaml<7,>=6
24
+ Provides-Extra: dev
25
+ Requires-Dist: hatchling>=1.27; extra == 'dev'
26
+ Requires-Dist: mypy>=1.13; extra == 'dev'
27
+ Requires-Dist: pytest-cov>=5; extra == 'dev'
28
+ Requires-Dist: pytest>=8; extra == 'dev'
29
+ Requires-Dist: ruff>=0.8; extra == 'dev'
30
+ Requires-Dist: types-jsonschema; extra == 'dev'
31
+ Requires-Dist: types-pyyaml; extra == 'dev'
32
+ Description-Content-Type: text/markdown
33
+
34
+ # repocraft
35
+
36
+ Deterministic Python generation from validated input.
37
+
38
+ `repocraft` has four paths:
39
+
40
+ - a short request such as `triangle` selects a built-in recipe and writes one
41
+ `.py` file plus one `unittest` file;
42
+ - a small YAML spec becomes a complete Python project with packaging metadata,
43
+ a `src/` layout, tests, lint and type-check configuration, CI, CodeQL,
44
+ Dependabot, and a JUnit gate that rejects skipped tests;
45
+ - an optional `ask` path where a model only proposes a strict
46
+ `{recipe, parameters}` intent, which repocraft validates before writing;
47
+ - an optional `craft` path where a model writes the snippet and repocraft
48
+ verifies it through deterministic gates before anything is written.
49
+
50
+ The first two paths are deterministic: the same input and the same `repocraft`
51
+ version always produce byte-identical output. GitHub repository creation is a
52
+ roadmap item.
53
+
54
+ ## Status
55
+
56
+ Version 0.4.0 adds the `craft` path: a model writes a free-form snippet and
57
+ repocraft verifies it — python syntax, that the generated tests import the
58
+ module, ruff when it is installed, and the generated tests themselves — before
59
+ the confirmation prompt and the no-overwrite rules apply.
60
+
61
+ Version 0.3.0 adds the optional AI intent layer and three new recipes:
62
+
63
+ - `repocraft ask` sends a free-form request to an OpenAI-compatible endpoint
64
+ and turns the reply into a strict `{recipe, parameters}` intent;
65
+ - the model never writes code or files; the intent is validated against the
66
+ recipe catalog with the same rules as `make`;
67
+ - configuration through `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `REPOCRAFT_MODEL`,
68
+ or `--endpoint` and `--model`;
69
+ - new recipes: `fizzbuzz`, `pascal`, and `password`.
70
+
71
+ Version 0.2.0 added the deterministic snippet mode:
72
+
73
+ - strict JSON Schema validation for specs and recipes, plus duplicate-key
74
+ rejection in YAML;
75
+ - four built-in recipes: `fibonacci`, `factorial`, `prime_sieve`, and
76
+ `triangle`;
77
+ - deterministic English matching with case, accent, and suffix normalization;
78
+ - confirmation before writing, `--dry-run`, `--param`, and refusal to overwrite;
79
+ - golden snapshots and smoke tests for every generated snippet.
80
+
81
+ The project mode from 0.1.0 is unchanged: library and CLI scaffolds with
82
+ golden-tested templates, CI, CodeQL, Dependabot, and coverage/skip gates.
83
+
84
+ The deterministic commands (`validate`, `render`, `recipes`, `make`) have no
85
+ model or network dependency; only `ask` uses the network.
86
+
87
+ ## Requirements
88
+
89
+ - Python 3.10 or newer.
90
+
91
+ ## Installation
92
+
93
+ The package is not published on PyPI yet. From this checkout:
94
+
95
+ ```bash
96
+ python -m pip install .
97
+ ```
98
+
99
+ ## Snippet mode
100
+
101
+ List the closed recipe catalog:
102
+
103
+ ```bash
104
+ repocraft recipes
105
+ ```
106
+
107
+ Ask for a snippet. The command shows the selected recipe, its parameters, and
108
+ the target files, then asks for confirmation:
109
+
110
+ ```bash
111
+ repocraft make "triangle" # triangle.py and test_triangle.py
112
+ repocraft make "factorial"
113
+ repocraft make "prime numbers"
114
+ ```
115
+
116
+ Preview without writing anything:
117
+
118
+ ```bash
119
+ repocraft make "fibonacci" --dry-run
120
+ ```
121
+
122
+ Override a declared integer parameter. Free-text numbers are not interpreted:
123
+
124
+ ```bash
125
+ repocraft make "fibonacci" --param count=20 --yes
126
+ ```
127
+
128
+ Rules:
129
+
130
+ - only the built-in catalog is matched; unknown or ambiguous requests stop
131
+ without writing anything;
132
+ - requests containing standalone digits are refused; use `--param` instead;
133
+ - parameters are bounded integers and are validated before rendering;
134
+ - existing target files are never overwritten;
135
+ - `--yes` skips the confirmation prompt;
136
+ - generated tests use the standard library: `python test_<recipe>.py`.
137
+
138
+ The matcher normalizes case and accents and matches word prefixes, so
139
+ `Triangles` and `draw a triangle` both select the triangle recipe. It never
140
+ calls a model.
141
+
142
+ ## Ask mode (optional)
143
+
144
+ `ask` is the only command that calls a model. It turns a free-form request
145
+ into a validated intent and then reuses the snippet path end to end:
146
+
147
+ ```bash
148
+ export OPENAI_API_KEY=sk-... # required
149
+ repocraft ask "a tall triangle" # proposes triangle with its default height
150
+ repocraft ask "first 20 fibonacci numbers" --yes
151
+ ```
152
+
153
+ Rules:
154
+
155
+ - the model replies with JSON only: a recipe id and integer parameters, or
156
+ `null` with a reason when nothing fits;
157
+ - repocraft validates the reply against the catalog; unknown recipes, invalid
158
+ parameters, and malformed replies are rejected;
159
+ - the confirmation prompt, `--dry-run`, `--param`, and the refusal to
160
+ overwrite behave exactly as in `make`;
161
+ - `--endpoint` selects any OpenAI-compatible base URL; `--model` or
162
+ `REPOCRAFT_MODEL` selects the model;
163
+ - without `OPENAI_API_KEY` in the environment the command refuses to run.
164
+
165
+ ## Craft mode (optional)
166
+
167
+ `craft` is the path where the model writes the code and repocraft stays in
168
+ control of quality. The model proposes a module, its source, and a unittest
169
+ file; repocraft then runs deterministic gates on the proposal before anything
170
+ is written:
171
+
172
+ ```bash
173
+ export OPENAI_API_KEY=sk-... # required
174
+ repocraft craft "binary search" # proposes, verifies, asks, writes
175
+ ```
176
+
177
+ Gates, in order:
178
+
179
+ 1. python syntax of the code and the test;
180
+ 2. the test must import the proposed module by name;
181
+ 3. ruff on the generated files, when ruff is installed;
182
+ 4. the generated unittest file must run and pass at least one test;
183
+ 5. the confirmation prompt shows the code and every check that passed.
184
+
185
+ Rules:
186
+
187
+ - `--endpoint`, `--model`, `REPOCRAFT_MODEL`, and `OPENAI_BASE_URL` configure
188
+ the endpoint exactly as in `ask`;
189
+ - the module name must be a lowercase snake_case identifier;
190
+ - only the standard library is allowed in the prompt, but the gates verify
191
+ what actually runs;
192
+ - `--dry-run` lists the planned files after verification; the no-overwrite
193
+ rule applies;
194
+ - without `OPENAI_API_KEY` in the environment the command refuses to run.
195
+
196
+ Unlike the deterministic paths, the written content depends on the model;
197
+ repocraft guarantees only that every gate passed and that you saw the code
198
+ before it was written.
199
+
200
+ ## Project mode
201
+
202
+ Write a spec:
203
+
204
+ ```yaml
205
+ schema_version: 1
206
+ project:
207
+ name: example-cli
208
+ package: example_cli
209
+ description: An example command-line application.
210
+ type: cli
211
+ license: Apache-2.0
212
+ author: Your Name
213
+ version: 0.1.0
214
+ python: ">=3.10"
215
+ cli:
216
+ command: example-cli
217
+ repository:
218
+ owner: your-user
219
+ name: example-cli
220
+ private: true
221
+ ```
222
+
223
+ Validate it:
224
+
225
+ ```bash
226
+ repocraft validate spec.yaml
227
+ ```
228
+
229
+ Plan the output without writing anything:
230
+
231
+ ```bash
232
+ repocraft render spec.yaml example-cli --dry-run
233
+ ```
234
+
235
+ Render it:
236
+
237
+ ```bash
238
+ repocraft render spec.yaml example-cli
239
+ ```
240
+
241
+ `render` refuses an output directory that already contains files. It never
242
+ overwrites or merges into existing work.
243
+
244
+ ### Spec fields
245
+
246
+ | Field | Required | Meaning |
247
+ |---|---|---|
248
+ | `schema_version` | yes | Must be `1`. |
249
+ | `project.name` | yes | Distribution name, lowercase letters, digits, and hyphens. |
250
+ | `project.package` | yes | Import package name, lowercase letters, digits, and underscores. |
251
+ | `project.description` | yes | One-line description, 10 to 200 characters. |
252
+ | `project.type` | yes | `library` or `cli`. |
253
+ | `project.license` | yes | `MIT` or `Apache-2.0`. |
254
+ | `project.author` | yes | Copyright holder and package author. |
255
+ | `project.version` | no | Semantic version, default `0.1.0`. |
256
+ | `project.python` | no | `>=3.10` through `>=3.14`, default `>=3.10`. |
257
+ | `project.cli.command` | for `cli` | Console script name. Forbidden for `library`. |
258
+ | `project.repository` | no | `owner`, `name`, and `private` (default `true`). |
259
+
260
+ ## Determinism contract
261
+
262
+ For fixed input and a fixed `repocraft` version:
263
+
264
+ - output paths and file contents are byte-identical;
265
+ - recipe output depends only on the recipe version and validated parameters;
266
+ - recipe matching and error ordering are deterministic;
267
+ - entries are rendered in sorted order;
268
+ - files use LF line endings and a trailing newline;
269
+ - no timestamps, random identifiers, model output, or environment values are
270
+ embedded;
271
+ - the generated MIT copyright line carries the author but no year.
272
+
273
+ The golden tests in `tests/golden/` enforce the contract file by file,
274
+ including the built-in recipe snapshots.
275
+
276
+ The `ask` command adds a model, but the contract still holds: the model only
277
+ proposes an intent, and a confirmed intent renders exactly like `make`. The
278
+ `craft` command goes further — the model writes the code — so its output is
279
+ not part of the contract; its gates, the confirmation prompt, and the
280
+ no-overwrite rule are.
281
+
282
+ ## Development
283
+
284
+ ```bash
285
+ python -m venv .venv
286
+ . .venv/bin/activate # Windows: .venv\Scripts\activate
287
+ python -m pip install -e ".[dev]"
288
+ python -m ruff check .
289
+ python -m mypy
290
+ python -m pytest --cov=repocraft --cov-branch --cov-fail-under=100
291
+ ```
292
+
293
+ The smoke tests install the rendered fixtures into temporary target directories
294
+ with `--no-deps --no-build-isolation`, then run the generated projects' own
295
+ quality gates. Hatchling is a dev dependency for exactly that reason.
296
+
297
+ CI runs the suite on Python 3.10 through 3.14 and rejects skipped tests through
298
+ `scripts/check_junit.py`.
299
+
300
+ ## Roadmap
301
+
302
+ 1. Interactive wizard for people who do not want to write project YAML.
303
+ 2. Free-form natural language to a full project spec through an
304
+ OpenAI-compatible endpoint, with a confirmation step before any file is
305
+ written.
306
+ 3. GitHub repository creation and push, private by default.
307
+ 4. MCP server exposing the same validated core.
308
+
309
+ ## License
310
+
311
+ MIT. See `LICENSE`.