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.
- repocraft-0.4.0/.gitattributes +1 -0
- repocraft-0.4.0/.github/dependabot.yml +12 -0
- repocraft-0.4.0/.github/workflows/ci.yml +44 -0
- repocraft-0.4.0/.github/workflows/codeql.yml +26 -0
- repocraft-0.4.0/.gitignore +12 -0
- repocraft-0.4.0/CONTRIBUTING.md +57 -0
- repocraft-0.4.0/LICENSE +21 -0
- repocraft-0.4.0/PKG-INFO +311 -0
- repocraft-0.4.0/README.md +278 -0
- repocraft-0.4.0/SECURITY.md +20 -0
- repocraft-0.4.0/pyproject.toml +81 -0
- repocraft-0.4.0/scripts/check_junit.py +40 -0
- repocraft-0.4.0/scripts/local_ci.py +50 -0
- repocraft-0.4.0/src/repocraft/__init__.py +5 -0
- repocraft-0.4.0/src/repocraft/__main__.py +5 -0
- repocraft-0.4.0/src/repocraft/cli.py +284 -0
- repocraft-0.4.0/src/repocraft/craft.py +178 -0
- repocraft-0.4.0/src/repocraft/errors.py +27 -0
- repocraft-0.4.0/src/repocraft/intent.py +167 -0
- repocraft-0.4.0/src/repocraft/recipe.py +268 -0
- repocraft-0.4.0/src/repocraft/recipes/factorial.py.j2 +22 -0
- repocraft-0.4.0/src/repocraft/recipes/factorial.yaml +12 -0
- repocraft-0.4.0/src/repocraft/recipes/fibonacci.py.j2 +22 -0
- repocraft-0.4.0/src/repocraft/recipes/fibonacci.yaml +12 -0
- repocraft-0.4.0/src/repocraft/recipes/fizzbuzz.py.j2 +29 -0
- repocraft-0.4.0/src/repocraft/recipes/fizzbuzz.yaml +13 -0
- repocraft-0.4.0/src/repocraft/recipes/pascal.py.j2 +25 -0
- repocraft-0.4.0/src/repocraft/recipes/pascal.yaml +13 -0
- repocraft-0.4.0/src/repocraft/recipes/password.py.j2 +24 -0
- repocraft-0.4.0/src/repocraft/recipes/password.yaml +14 -0
- repocraft-0.4.0/src/repocraft/recipes/prime_sieve.py.j2 +31 -0
- repocraft-0.4.0/src/repocraft/recipes/prime_sieve.yaml +14 -0
- repocraft-0.4.0/src/repocraft/recipes/test_factorial.py.j2 +23 -0
- repocraft-0.4.0/src/repocraft/recipes/test_fibonacci.py.j2 +29 -0
- repocraft-0.4.0/src/repocraft/recipes/test_fizzbuzz.py.j2 +46 -0
- repocraft-0.4.0/src/repocraft/recipes/test_pascal.py.j2 +32 -0
- repocraft-0.4.0/src/repocraft/recipes/test_password.py.j2 +29 -0
- repocraft-0.4.0/src/repocraft/recipes/test_prime_sieve.py.j2 +30 -0
- repocraft-0.4.0/src/repocraft/recipes/test_triangle.py.j2 +27 -0
- repocraft-0.4.0/src/repocraft/recipes/triangle.py.j2 +21 -0
- repocraft-0.4.0/src/repocraft/recipes/triangle.yaml +13 -0
- repocraft-0.4.0/src/repocraft/render.py +126 -0
- repocraft-0.4.0/src/repocraft/schema/recipe.schema.json +72 -0
- repocraft-0.4.0/src/repocraft/schema/spec.schema.json +116 -0
- repocraft-0.4.0/src/repocraft/spec.py +104 -0
- repocraft-0.4.0/src/repocraft/templates/cli/cli.py.j2 +26 -0
- repocraft-0.4.0/src/repocraft/templates/cli/main.py.j2 +5 -0
- repocraft-0.4.0/src/repocraft/templates/cli/test_cli.py.j2 +36 -0
- repocraft-0.4.0/src/repocraft/templates/common/CONTRIBUTING.md.j2 +28 -0
- repocraft-0.4.0/src/repocraft/templates/common/README.md.j2 +53 -0
- repocraft-0.4.0/src/repocraft/templates/common/SECURITY.md.j2 +22 -0
- repocraft-0.4.0/src/repocraft/templates/common/check_junit.py +40 -0
- repocraft-0.4.0/src/repocraft/templates/common/ci.yml.j2 +38 -0
- repocraft-0.4.0/src/repocraft/templates/common/codeql.yml.j2 +26 -0
- repocraft-0.4.0/src/repocraft/templates/common/dependabot.yml +12 -0
- repocraft-0.4.0/src/repocraft/templates/common/gitignore.txt +12 -0
- repocraft-0.4.0/src/repocraft/templates/common/init.py.j2 +8 -0
- repocraft-0.4.0/src/repocraft/templates/common/py.typed +0 -0
- repocraft-0.4.0/src/repocraft/templates/common/pyproject.toml.j2 +64 -0
- repocraft-0.4.0/src/repocraft/templates/common/test_metadata.py.j2 +9 -0
- repocraft-0.4.0/src/repocraft/templates/library/core.py.j2 +8 -0
- repocraft-0.4.0/src/repocraft/templates/library/test_core.py.j2 +9 -0
- repocraft-0.4.0/src/repocraft/templates/licenses/Apache-2.0.txt.j2 +202 -0
- repocraft-0.4.0/src/repocraft/templates/licenses/MIT.txt.j2 +21 -0
- repocraft-0.4.0/tests/fixtures/cli.yaml +16 -0
- repocraft-0.4.0/tests/fixtures/library.yaml +8 -0
- repocraft-0.4.0/tests/golden/cli/.github/dependabot.yml +12 -0
- repocraft-0.4.0/tests/golden/cli/.github/workflows/ci.yml +38 -0
- repocraft-0.4.0/tests/golden/cli/.github/workflows/codeql.yml +26 -0
- repocraft-0.4.0/tests/golden/cli/.gitignore +12 -0
- repocraft-0.4.0/tests/golden/cli/CONTRIBUTING.md +28 -0
- repocraft-0.4.0/tests/golden/cli/LICENSE +202 -0
- repocraft-0.4.0/tests/golden/cli/README.md +42 -0
- repocraft-0.4.0/tests/golden/cli/SECURITY.md +18 -0
- repocraft-0.4.0/tests/golden/cli/pyproject.toml +67 -0
- repocraft-0.4.0/tests/golden/cli/scripts/check_junit.py +40 -0
- repocraft-0.4.0/tests/golden/cli/src/example_cli/__init__.py +3 -0
- repocraft-0.4.0/tests/golden/cli/src/example_cli/__main__.py +5 -0
- repocraft-0.4.0/tests/golden/cli/src/example_cli/cli.py +26 -0
- repocraft-0.4.0/tests/golden/cli/src/example_cli/py.typed +0 -0
- repocraft-0.4.0/tests/golden/cli/tests/test_cli.py +36 -0
- repocraft-0.4.0/tests/golden/cli/tests/test_metadata.py +9 -0
- repocraft-0.4.0/tests/golden/library/.github/dependabot.yml +12 -0
- repocraft-0.4.0/tests/golden/library/.github/workflows/ci.yml +38 -0
- repocraft-0.4.0/tests/golden/library/.github/workflows/codeql.yml +26 -0
- repocraft-0.4.0/tests/golden/library/.gitignore +12 -0
- repocraft-0.4.0/tests/golden/library/CONTRIBUTING.md +28 -0
- repocraft-0.4.0/tests/golden/library/LICENSE +21 -0
- repocraft-0.4.0/tests/golden/library/README.md +40 -0
- repocraft-0.4.0/tests/golden/library/SECURITY.md +17 -0
- repocraft-0.4.0/tests/golden/library/pyproject.toml +61 -0
- repocraft-0.4.0/tests/golden/library/scripts/check_junit.py +40 -0
- repocraft-0.4.0/tests/golden/library/src/example_library/__init__.py +6 -0
- repocraft-0.4.0/tests/golden/library/src/example_library/core.py +8 -0
- repocraft-0.4.0/tests/golden/library/src/example_library/py.typed +0 -0
- repocraft-0.4.0/tests/golden/library/tests/test_core.py +9 -0
- repocraft-0.4.0/tests/golden/library/tests/test_metadata.py +9 -0
- repocraft-0.4.0/tests/golden/recipes/factorial/factorial.py +22 -0
- repocraft-0.4.0/tests/golden/recipes/factorial/test_factorial.py +23 -0
- repocraft-0.4.0/tests/golden/recipes/fibonacci/fibonacci.py +22 -0
- repocraft-0.4.0/tests/golden/recipes/fibonacci/test_fibonacci.py +29 -0
- repocraft-0.4.0/tests/golden/recipes/fizzbuzz/fizzbuzz.py +29 -0
- repocraft-0.4.0/tests/golden/recipes/fizzbuzz/test_fizzbuzz.py +46 -0
- repocraft-0.4.0/tests/golden/recipes/pascal/pascal.py +25 -0
- repocraft-0.4.0/tests/golden/recipes/pascal/test_pascal.py +32 -0
- repocraft-0.4.0/tests/golden/recipes/password/password.py +24 -0
- repocraft-0.4.0/tests/golden/recipes/password/test_password.py +29 -0
- repocraft-0.4.0/tests/golden/recipes/prime_sieve/prime_sieve.py +31 -0
- repocraft-0.4.0/tests/golden/recipes/prime_sieve/test_prime_sieve.py +30 -0
- repocraft-0.4.0/tests/golden/recipes/triangle/test_triangle.py +27 -0
- repocraft-0.4.0/tests/golden/recipes/triangle/triangle.py +21 -0
- repocraft-0.4.0/tests/test_check_junit.py +68 -0
- repocraft-0.4.0/tests/test_cli.py +493 -0
- repocraft-0.4.0/tests/test_craft.py +246 -0
- repocraft-0.4.0/tests/test_intent.py +232 -0
- repocraft-0.4.0/tests/test_package.py +9 -0
- repocraft-0.4.0/tests/test_recipe.py +366 -0
- repocraft-0.4.0/tests/test_render.py +115 -0
- repocraft-0.4.0/tests/test_smoke.py +82 -0
- repocraft-0.4.0/tests/test_spec.py +112 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
* text=auto eol=lf
|
|
@@ -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,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.
|
repocraft-0.4.0/LICENSE
ADDED
|
@@ -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.
|
repocraft-0.4.0/PKG-INFO
ADDED
|
@@ -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`.
|