3 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
nvaldez bd1a10487c feat: PyPI distribution renamed daedalus-tools; PEP 625 artifact names (v0.13.0)
PyPI policy-blocks the plain name: the 0.12.1 upload was rejected
with "The name 'daedalus' isn't allowed" (near the existing
daedalus-cli and pydaedalus projects). The distribution is now
daedalus-tools; command, imports, registry, and the repository
name stay daedalus. hello's installed-version lookup follows.
publish now derives artifact file names from the PEP 625
normalized name (daedalus_tools-<version>.tar.gz) - with a
hyphenated project name the previously constructed names would
have missed what setuptools writes to dist/ (publish spec 3.2,
new regression test).

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 10:58:33 +01:00
11 changed files with 111 additions and 41 deletions
+35
View File
@@ -10,6 +10,41 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
- Nothing yet. - 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
- PyPI distribution renamed to **`daedalus-tools`** (from `daedalus`):
PyPI policy-blocks the plain name - the upload of 0.12.1 was rejected
with "The name 'daedalus' isn't allowed" (near the existing
`daedalus-cli` and `pydaedalus` projects). The `daedalus` command, the
`daedalus` import package, the registry, and the repository are
unchanged; only the value of `[project] name` (and hello's installed
version lookup) moved. `pipx install daedalus-tools` puts the same
`daedalus` CLI on PATH (SPEC item 9.1).
### Fixed in 0.13.0
- `publish`'s artifact names now use the PEP 625 normalized name
(`daedalus-tools` -> `daedalus_tools-0.13.0.tar.gz`), matching what
setuptools actually writes to `dist/`; with a hyphenated project name
the constructed names would have missed the files. PyPI's version
probe keeps using the project name as written (publish spec 3.2).
## [0.12.1] - 2026-11-19 ## [0.12.1] - 2026-11-19
### Fixed in 0.12.1 ### Fixed in 0.12.1
+6 -8
View File
@@ -17,23 +17,21 @@ Back to the [script list](./README.md#available-scripts). Repository rules:
### With pipx (recommended) ### With pipx (recommended)
[pipx](https://pipx.pypa.io/) installs daedalus into its own environment [pipx](https://pipx.pypa.io/) installs the `daedalus-tools` distribution
and puts the `daedalus` command on `PATH`. (from PyPI or Git) into its own environment and puts the `daedalus`
command on `PATH` — the project name and the command differ on purpose
(plain `daedalus` is policy-blocked on PyPI; see SPEC item 9.1).
Linux (Debian 12): paste once; open a new shell if `pipx` was just Linux (Debian 12): paste once; open a new shell if `pipx` was just
installed. Run the same block again to refresh from Git (`main`); do **not** installed. Run the same block again to refresh from Git (`main`); do **not**
use `pipx upgrade daedalus` for Git installs — it does not pull the repo. use `pipx upgrade daedalus-tools` for Git installs — it does not pull the repo.
```bash ```bash
daedalus_pipx_install() { daedalus_pipx_install() {
r="${1:-git+ssh://git@example.com/your-org/daedalus.git@main}" r="${1:-git+ssh://git@example.com/your-org/daedalus.git@main}"
command -v pipx >/dev/null || sudo apt install -y pipx command -v pipx >/dev/null || sudo apt install -y pipx
pipx ensurepath 2>/dev/null || pipx ensurepath --force pipx ensurepath 2>/dev/null || pipx ensurepath --force
if pipx list --short 2>/dev/null | grep -qE '^daedalus '; then pipx install --force "$r"
pipx install --force "$r"
else
pipx install "$r"
fi
daedalus --version daedalus --version
}; daedalus_pipx_install }; daedalus_pipx_install
``` ```
+5 -5
View File
@@ -9,9 +9,9 @@ daedalus <category> [category...] # list scripts in the categories (AND)
daedalus --list # list everything daedalus --list # list everything
``` ```
**[Install, usage, and development](./INSTALL.md)** · **[Install, usage, and development](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/INSTALL.md)** ·
[SPEC](./SPEC.md) (how the repo is maintained) · [SPEC](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/SPEC.md) (how the repo is maintained) ·
[CHANGELOG](./CHANGELOG.md) [CHANGELOG](https://gitea.nolivaldeziii.com/nvaldez/daedalus/src/branch/main/CHANGELOG.md)
## Available scripts ## 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` + category labels: `daedalus hel` + TAB completes `hello`, `daedalus test h` +
TAB completes `hello` inside the category, and options complete after `-`. TAB completes `hello` inside the category, and options complete after `-`.
Run `daedalus init` once to register the hook in `~/.bashrc` (below); see 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 ### init
@@ -232,7 +232,7 @@ check failed, `9` upload failed.
1. Clone or copy this template and name the Git remote for your team. 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/` 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). shared `help()` interface (SPEC item 6.10).
3. Register it in `daedalus/registry.py`, add a row to the table above, 3. Register it in `daedalus/registry.py`, add a row to the table above,
write tests, bump `version` in `pyproject.toml`, and run write tests, bump `version` in `pyproject.toml`, and run
+31 -14
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 environment variables, files written, packaging, checks). Change this file
first when the behavior changes, then change the code and tests to match. 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 This checkout ships the CLI, the quality gates, and the registered
ready; add scripts per section 6. scripts; add new ones per section 6.
<!-- toc-start: headings 2..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 daedalus <category>… <name> [args...] run when the script has every category
``` ```
In this template checkout, `SCRIPTS` is empty until the first script is The registry (section 4) is the source of truth for what is
added (section 6). registered today.
- **1.3** The same tool runs on a Windows workstation and on a Linux - **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 host, either installed with pipx (section 9) or run from a checkout
@@ -89,7 +89,8 @@ daedalus/
├── ci/ # sanity.py, checks.py, with tests ├── ci/ # sanity.py, checks.py, with tests
├── autotest.py # Runs every check (local and CI) ├── autotest.py # Runs every check (local and CI)
├── pyproject.toml # Package, version, entry point, package data ├── 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 ├── .gitea/workflows/ci.yml # CI job that runs autotest.py
├── .gitattributes # LF everywhere, CRLF for *.bat ├── .gitattributes # LF everywhere, CRLF for *.bat
├── .editorconfig # UTF-8, LF, final newline, 4 spaces (2 for yml/json/md) ├── .editorconfig # UTF-8, LF, final newline, 4 spaces (2 for yml/json/md)
@@ -317,8 +318,7 @@ help.
## 4. Registry ## 4. Registry
`daedalus/registry.py` holds one dictionary. In this template checkout it `daedalus/registry.py` holds one dictionary of entries shaped like:
is empty until the first script is added:
```python ```python
SCRIPTS: dict[str, Script] = { SCRIPTS: dict[str, Script] = {
@@ -595,8 +595,10 @@ autotest results
`pip install -r requirements.txt`, then `python autotest.py`. The `pip install -r requirements.txt`, then `python autotest.py`. The
sanity diff base is passed as `SANITY_DIFF_BASE`. sanity diff base is passed as `SANITY_DIFF_BASE`.
- **7.11** `requirements.txt` holds the tools: `pytest`, `pytest-cov`, - **7.11** `requirements.txt` holds the tools: `pytest`, `pytest-cov`,
`pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`, `setuptools`, `pycodestyle`, `pymarkdownlnt`, `pyyaml`, `shellcheck-py`,
and `argcomplete` (the runtime dependency, so the completion tests run). `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 ## 8. Conventions
@@ -616,16 +618,20 @@ autotest results
## 9. Packaging ## 9. Packaging
- **9.1** `pyproject.toml` builds one wheel (setuptools 68 or newer) named - **9.1** The PyPI distribution is named `daedalus-tools` (plain
`daedalus` that holds the CLI and every script. It requires Python `daedalus` is policy-blocked on PyPI - near the existing
`daedalus-cli`/`pydaedalus` projects; command and import names
stay `daedalus`). `pyproject.toml` builds one wheel (setuptools 68
or newer) that holds the CLI and every script. It requires Python
3.11 or newer. 3.11 or newer.
| Command | Use | | 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 --user .` | From a checkout, into the user site |
| `pip install -e .` | Development: the installed command runs the scripts in the checkout | | `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 - **9.2** The script folders are copied into the wheel under
`daedalus/_library/`, with the same relative paths as in the repository: `daedalus/_library/`, with the same relative paths as in the repository:
@@ -664,7 +670,7 @@ autotest results
other third-party packages says so in its own help text and fails other third-party packages says so in its own help text and fails
with a clear message when they are missing; with a clear message when they are missing;
`DAEDALUS_PYTHON` (SPEC item 5.2) points it at their environment. `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** 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.1** Every registered script is at `daedalus/_library/<path>`.
- **9.7.2** No `/tests/`, `*.pyc`, or `.gitkeep` entry is present. - **9.7.2** No `/tests/`, `*.pyc`, or `.gitkeep` entry is present.
@@ -675,6 +681,17 @@ autotest results
import resolves. import resolves.
- **9.8** Bump `version` in `pyproject.toml` when scripts or the CLI - **9.8** Bump `version` in `pyproject.toml` when scripts or the CLI
change, so `pipx upgrade` picks them up. 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 ## 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 assert "usage: daedalus --path <name>" in capsys.readouterr().err
@pytest.mark.parametrize("installed, expected", [(True, "daedalus 1.2.3"), (False, "daedalus 0.12.1")]) @pytest.mark.parametrize("installed, expected", [(True, "daedalus 1.2.3"), (False, "daedalus 0.13.1")])
def test_version(monkeypatch, capsys, installed, expected): def test_version(monkeypatch, capsys, installed, expected):
"""--version uses metadata or pyproject.toml in a checkout.""" """--version uses metadata or pyproject.toml in a checkout."""
def fake_version(_name): def fake_version(_name):
+2 -2
View File
@@ -3,8 +3,8 @@ requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta" build-backend = "setuptools.build_meta"
[project] [project]
name = "daedalus" name = "daedalus-tools"
version = "0.12.1" version = "0.13.1"
description = "Template for daedalus: loose scripts in one repo, run with: daedalus <name> [args...]" description = "Template for daedalus: loose scripts in one repo, run with: daedalus <name> [args...]"
readme = "README.md" readme = "README.md"
requires-python = ">=3.11" requires-python = ">=3.11"
+1 -1
View File
@@ -23,7 +23,7 @@ UNKNOWN = "unknown"
def app_version() -> str: def app_version() -> str:
"""Installed daedalus version, else the checkout pyproject, else 'unknown'.""" """Installed daedalus version, else the checkout pyproject, else 'unknown'."""
try: try:
return importlib.metadata.version("daedalus") # plain and editable installs return importlib.metadata.version("daedalus-tools") # plain and editable installs
except importlib.metadata.PackageNotFoundError: except importlib.metadata.PackageNotFoundError:
pass pass
# A checkout that is not installed: python/src/hello/hello.py -> pyproject.toml # A checkout that is not installed: python/src/hello/hello.py -> pyproject.toml
+8 -3
View File
@@ -14,6 +14,7 @@ from __future__ import annotations
import argparse import argparse
import logging import logging
import pathlib import pathlib
import re
import subprocess import subprocess
import sys import sys
import tomllib import tomllib
@@ -81,11 +82,15 @@ def pypi_status(url: str) -> int | None:
def artifact_names(name: str, version: str) -> tuple[str, str]: def artifact_names(name: str, version: str) -> tuple[str, str]:
"""The version's sdist and wheel file names (items 3.4-3.7). """The version's sdist and wheel file names (items 3.4-3.7).
File names use the PEP 625 normalized name (lowercase, runs
of `-._` collapsed to one underscore - what setuptools
writes to dist/); the PyPI JSON probe uses `name` as written.
The wheel is a pure-Python wheel (SPEC item 9.1), so its name The wheel is a pure-Python wheel (SPEC item 9.1), so its name
follows ``<name>-<version>-py3-none-any.whl``. follows ``<normalized>-<version>-py3-none-any.whl``.
""" """
return (f"{name}-{version}.tar.gz", safe = re.sub(r"[-_.]+", "_", name).lower()
f"{name}-{version}-py3-none-any.whl") return (f"{safe}-{version}.tar.gz",
f"{safe}-{version}-py3-none-any.whl")
def cmd_publish(args: argparse.Namespace, run_cmd=None, def cmd_publish(args: argparse.Namespace, run_cmd=None,
+7 -2
View File
@@ -33,7 +33,10 @@ are cited as `publish spec item N.M`.
exit 2. exit 2.
- **3.2** Version: read from `[project] version` in that - **3.2** Version: read from `[project] version` in that
`pyproject.toml` (tomllib); project name for PyPI checks from `pyproject.toml` (tomllib); project name for PyPI checks from
`[project] name`. `[project] name`. Artifact *file names* use the PEP 625
normalized name (lowercase, runs of `-._` collapsed to one
`_`, e.g. `daedalus-tools` -> `daedalus_tools-<version>.tar.gz`);
the PyPI JSON probe uses the project name as written.
- **3.3** Guards, in order, each stopping before anything is - **3.3** Guards, in order, each stopping before anything is
built: built:
- **3.3.1** Dirty working tree (`git status --porcelain` in the - **3.3.1** Dirty working tree (`git status --porcelain` in the
@@ -111,4 +114,6 @@ are cited as `publish spec item N.M`.
- **7.2** Repository rules: SPEC items 6.6 (tests), 9.8 (version - **7.2** Repository rules: SPEC items 6.6 (tests), 9.8 (version
bump). bump).
- **7.3** History: `CHANGELOG.md` entries 0.12.0 (script), - **7.3** History: `CHANGELOG.md` entries 0.12.0 (script),
0.12.1 (tag-guard fix, found by the first live run). 0.12.1 (tag-guard fix, found by the first live run), 0.13.0
(PEP 625 artifact names; distribution renamed daedalus-tools
after PyPI refused the name daedalus).
+1 -1
View File
@@ -34,7 +34,7 @@ def test_app_version_falls_back_to_pyproject(monkeypatch):
raise hello.importlib.metadata.PackageNotFoundError(_name) raise hello.importlib.metadata.PackageNotFoundError(_name)
monkeypatch.setattr(hello.importlib.metadata, "version", not_found) monkeypatch.setattr(hello.importlib.metadata, "version", not_found)
assert hello.app_version() == "0.12.1" assert hello.app_version() == "0.13.1"
def test_help_exits_zero(capsys): def test_help_exits_zero(capsys):
+14 -4
View File
@@ -166,6 +166,7 @@ def test_check_only_flow_builds_and_stops(tmp_path, capsys):
"""Without --upload: chained build, twine check, exit 0.""" """Without --upload: chained build, twine check, exit 0."""
name, version = publish.read_project( name, version = publish.read_project(
publish.find_repo_root() / "pyproject.toml") publish.find_repo_root() / "pyproject.toml")
sdist, wheel = publish.artifact_names(name, version)
calls = [] calls = []
assert publish.cmd_publish(publish.parse_args([]), assert publish.cmd_publish(publish.parse_args([]),
clean_runner(version, calls), clean_runner(version, calls),
@@ -175,7 +176,7 @@ def test_check_only_flow_builds_and_stops(tmp_path, capsys):
assert len(build) == 1 # chained, not two runs assert len(build) == 1 # chained, not two runs
assert not any(cmd[3:4] == ["upload"] for cmd, _ in calls) assert not any(cmd[3:4] == ["upload"] for cmd, _ in calls)
out = capsys.readouterr().out out = capsys.readouterr().out
assert f"{name}-{version}.tar.gz" in out assert f"{sdist}" in out
assert "--upload" in out # the next-step hint assert "--upload" in out # the next-step hint
@@ -183,14 +184,23 @@ def test_upload_sends_exactly_this_version():
"""--upload passes only this version's sdist and wheel.""" """--upload passes only this version's sdist and wheel."""
name, version = publish.read_project( name, version = publish.read_project(
publish.find_repo_root() / "pyproject.toml") publish.find_repo_root() / "pyproject.toml")
sdist, wheel = publish.artifact_names(name, version)
calls = [] calls = []
assert publish.cmd_publish(publish.parse_args(["--upload"]), assert publish.cmd_publish(publish.parse_args(["--upload"]),
clean_runner(version, calls), clean_runner(version, calls),
lambda _u: 404) == 0 lambda _u: 404) == 0
upload = [cmd for cmd, _ in calls if cmd[3:4] == ["upload"]][0] upload = [cmd for cmd, _ in calls if cmd[3:4] == ["upload"]][0]
assert upload[-2] == f"dist/{name}-{version}.tar.gz" assert upload[-2] == f"dist/{sdist}"
assert upload[-1].startswith(f"dist/{name}-{version}-") assert upload[-1] == f"dist/{wheel}"
assert upload[-1].endswith(".whl")
def test_artifact_names_normalize_pep625():
"""Filenames use the normalized name, not the project name."""
sdist, wheel = publish.artifact_names("daedalus-tools", "0.13.0")
assert sdist == "daedalus_tools-0.13.0.tar.gz"
assert wheel == "daedalus_tools-0.13.0-py3-none-any.whl"
assert publish.artifact_names("daedalus", "1.0") == \
("daedalus-1.0.tar.gz", "daedalus-1.0-py3-none-any.whl")
def test_build_failure_is_7(): def test_build_failure_is_7():