2 Commits

Author SHA1 Message Date
nvaldez cfbb66ce39 docs: SPEC refresh - drop template wording, add release contract (9.9), PyPI install rows
Audit against the live repo after 0.11.0-0.13.1:
- preamble, item 1.2, and section 4 no longer claim "empty
  template" (five scripts registered; the registry is the truth)
- item 2.1 tree: MANIFEST.in shown, requirements.txt comment
  says test/lint/release tools
- item 9.1 install table: pipx install daedalus-tools from PyPI
  and pipx upgrade daedalus-tools rows; public Gitea URL
- new item 9.9 Releasing: version bump, changelog, annotated
  v<version> tag, latest follows, stable pinned, daedalus
  publish as the guarded one-command flow (cites the publish
  spec; a published version is immutable by design)
- items 7.11 and 9.6 include the build/twine release tooling

SPEC.md ships in the repo only (never in sdist/wheel), so no
version bump; docs-only commit on main after the v0.13.1 tag.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 11:10:28 +01:00
nvaldez aa813f0c89 fix: README repo-relative links 404 on PyPI (v0.13.1)
PyPI renders the README alone; ./INSTALL.md, ./SPEC.md and
./CHANGELOG.md have nothing to resolve against. Links now point
at the public Gitea repository (anchors kept). 0.13.0's page is
immutable and keeps its broken links; the project page shows the
newest release's README. Found by the owner on the 0.13.0 page.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 11:06:27 +01:00
6 changed files with 48 additions and 20 deletions
+14
View File
@@ -10,6 +10,20 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
- Nothing yet.
## [0.13.1] - 2026-11-19
### Fixed in 0.13.1
- The PyPI README's repo-relative links (`./INSTALL.md`,
`./SPEC.md`, `./CHANGELOG.md`) 404 on pypi.org - the package
metadata holds only the README itself. They now point at the
public Gitea repository
(`https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/...`)
with their anchors kept. 0.13.0's already-published page keeps
its broken links (PyPI metadata is immutable); the project page
shows the newest release's README. Found by the owner on the
0.13.0 page.
## [0.13.0] - 2026-11-19
### Changed in 0.13.0
+5 -5
View File
@@ -9,9 +9,9 @@ daedalus <category> [category...] # list scripts in the categories (AND)
daedalus --list # list everything
```
**[Install, usage, and development](./INSTALL.md)** ·
[SPEC](./SPEC.md) (how the repo is maintained) ·
[CHANGELOG](./CHANGELOG.md)
**[Install, usage, and development](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/INSTALL.md)** ·
[SPEC](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/SPEC.md) (how the repo is maintained) ·
[CHANGELOG](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/CHANGELOG.md)
## Available scripts
@@ -180,7 +180,7 @@ Bash (and other shells argcomplete supports) completes script names and
category labels: `daedalus hel` + TAB completes `hello`, `daedalus test h` +
TAB completes `hello` inside the category, and options complete after `-`.
Run `daedalus init` once to register the hook in `~/.bashrc` (below); see
also [INSTALL](./INSTALL.md#tab-completion).
also [INSTALL](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/INSTALL.md#tab-completion).
### init
@@ -232,7 +232,7 @@ check failed, `9` upload failed.
1. Clone or copy this template and name the Git remote for your team.
2. Add a script under `python/src/`, `bash/`, `powershell/`, or `batch/`
(see [SPEC layout](./SPEC.md#2-layout)); bash scripts implement the
(see [SPEC layout](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/SPEC.md#2-layout)); bash scripts implement the
shared `help()` interface (SPEC item 6.10).
3. Register it in `daedalus/registry.py`, add a row to the table above,
write tests, bump `version` in `pyproject.toml`, and run
+26 -12
View File
@@ -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.
<!-- toc-start: headings 2..6 -->
@@ -40,8 +40,8 @@ daedalus <category> [category...] list scripts (AND when multiple)
daedalus <category>… <name> [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/<path>`.
- **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<version>`, 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<version>` 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<version>` 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
+1 -1
View File
@@ -150,7 +150,7 @@ def test_path_with_extra_words_is_a_usage_error(fake_registry, plain, capsys):
assert "usage: daedalus --path <name>" in capsys.readouterr().err
@pytest.mark.parametrize("installed, expected", [(True, "daedalus 1.2.3"), (False, "daedalus 0.13.0")])
@pytest.mark.parametrize("installed, expected", [(True, "daedalus 1.2.3"), (False, "daedalus 0.13.1")])
def test_version(monkeypatch, capsys, installed, expected):
"""--version uses metadata or pyproject.toml in a checkout."""
def fake_version(_name):
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "daedalus-tools"
version = "0.13.0"
version = "0.13.1"
description = "Template for daedalus: loose scripts in one repo, run with: daedalus <name> [args...]"
readme = "README.md"
requires-python = ">=3.11"
+1 -1
View File
@@ -34,7 +34,7 @@ def test_app_version_falls_back_to_pyproject(monkeypatch):
raise hello.importlib.metadata.PackageNotFoundError(_name)
monkeypatch.setattr(hello.importlib.metadata, "version", not_found)
assert hello.app_version() == "0.13.0"
assert hello.app_version() == "0.13.1"
def test_help_exits_zero(capsys):