diff --git a/SPEC.md b/SPEC.md index 2c3af81..95b4252 100644 --- a/SPEC.md +++ b/SPEC.md @@ -6,8 +6,8 @@ tool: it states every observable behavior (arguments, output, exit codes, environment variables, files written, packaging, checks). Change this file first when the behavior changes, then change the code and tests to match. -This checkout is an **empty template**: the CLI and quality gates are -ready; add scripts per section 6. +This checkout ships the CLI, the quality gates, and the registered +scripts; add new ones per section 6. @@ -40,8 +40,8 @@ daedalus [category...] list scripts (AND when multiple) daedalus … [args...] run when the script has every category ``` -In this template checkout, `SCRIPTS` is empty until the first script is -added (section 6). +The registry (section 4) is the source of truth for what is +registered today. - **1.3** The same tool runs on a Windows workstation and on a Linux host, either installed with pipx (section 9) or run from a checkout @@ -89,7 +89,8 @@ daedalus/ ├── ci/ # sanity.py, checks.py, with tests ├── autotest.py # Runs every check (local and CI) ├── pyproject.toml # Package, version, entry point, package data -├── requirements.txt # Test and lint tools +├── MANIFEST.in # Ships the placeholder script folders in sdists (SPEC item 9.2.1) +├── requirements.txt # Test, lint, and release tools ├── .gitea/workflows/ci.yml # CI job that runs autotest.py ├── .gitattributes # LF everywhere, CRLF for *.bat ├── .editorconfig # UTF-8, LF, final newline, 4 spaces (2 for yml/json/md) @@ -317,8 +318,7 @@ help. ## 4. Registry -`daedalus/registry.py` holds one dictionary. In this template checkout it -is empty until the first script is added: +`daedalus/registry.py` holds one dictionary of entries shaped like: ```python SCRIPTS: dict[str, Script] = { @@ -595,8 +595,10 @@ autotest results `pip install -r requirements.txt`, then `python autotest.py`. The sanity diff base is passed as `SANITY_DIFF_BASE`. - **7.11** `requirements.txt` holds the tools: `pytest`, `pytest-cov`, - `pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, `setuptools`, - and `argcomplete` (the runtime dependency, so the completion tests run). + `pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, + `setuptools`, `argcomplete` (the runtime dependency, so the + completion tests run), and `build` + `twine` (the release + tooling the publish script probes for, SPEC item 9.9). ## 8. Conventions @@ -625,10 +627,11 @@ autotest results | Command | Use | | --- | --- | -| `pipx install git+https://example.com/your-org/daedalus.git` | Own isolated environment, `daedalus` on `PATH` (recommended; works on Debian 12, where plain `pip install` is blocked) | +| `pipx install daedalus-tools` | From PyPI: own isolated environment, `daedalus` on `PATH` (the distribution name; works on Debian 12, where plain `pip install` is blocked) | +| `pipx install git+https://gitea.nolivaldeziii.com/nvaldez/daedalus.git` | From the public Git repository, same environment as above | | `pip install --user .` | From a checkout, into the user site | | `pip install -e .` | Development: the installed command runs the scripts in the checkout | -| `pipx upgrade daedalus` / `pip install --upgrade .` | Pick up new scripts | +| `pipx upgrade daedalus-tools` | Pick up a new PyPI release (Git installs: re-run the install block; `pipx upgrade` does not pull the repo, see [INSTALL](./INSTALL.md)) | - **9.2** The script folders are copied into the wheel under `daedalus/_library/`, with the same relative paths as in the repository: @@ -667,7 +670,7 @@ autotest results other third-party packages says so in its own help text and fails with a clear message when they are missing; `DAEDALUS_PYTHON` (SPEC item 5.2) points it at their environment. - Test and lint tools stay in `requirements.txt`. + Test, lint, and release tools stay in `requirements.txt`. - **9.7** Tests build the wheel from a copy of the checkout and check: - **9.7.1** Every registered script is at `daedalus/_library/`. - **9.7.2** No `/tests/`, `*.pyc`, or `.gitkeep` entry is present. @@ -678,6 +681,17 @@ autotest results import resolves. - **9.8** Bump `version` in `pyproject.toml` when scripts or the CLI change, so `pipx upgrade` picks them up. +- **9.9** Releasing: bump per 9.8, write the `CHANGELOG.md` entry, + commit, tag annotated `v`, move the `latest` tag, then + run `daedalus publish` - the guards section of + `python/src/publish/spec.md` (items 3.3-3.6) is the contract: + clean tree, `v` among `git tag --points-at HEAD`, + version free on PyPI, tooling present, chained build, twine + check, and with `--upload` exactly that version's artifacts. + Tag policy: one annotated `v` per release; `latest` + follows the newest; `stable` stays pinned until moved by hand. + A published version is immutable - the version-free guard + refuses a re-release by design. ## 10. Library imports