Files
daedalus/SPEC.md
T
nvaldez 792beca2c5 daedalus 0.0.0: empty template - one CLI, many small scripts, each with tests
Sanitized open-source starter: renamed to daedalus, Norse-free of
internal references, AI attribution stripped, skill merged into
AGENTS.md, CI converted to Gitea Actions. No registered scripts yet.
2026-11-11 18:55:11 +01:00

228 lines
10 KiB
Markdown

# daedalus specification
How this repository is laid out, how scripts are registered and run, and
the rules for maintaining it. Change this file first when the behavior
changes, then change the code and tests to match.
- [1. Purpose](#1-purpose)
- [2. Layout](#2-layout)
- [3. Command line](#3-command-line)
- [4. Registry](#4-registry)
- [5. Runners](#5-runners)
- [6. Adding a script](#6-adding-a-script)
- [7. Quality gates](#7-quality-gates)
- [8. Conventions](#8-conventions)
- [9. Packaging](#9-packaging)
- [10. Implementation plan](#10-implementation-plan)
## 1. Purpose
This repository is an **empty template**: the CLI and quality gates are
ready; add scripts per section 6. A filled checkout keeps loose scripts in
one repository, each with tests, and runs any of them through one command:
```text
daedalus <name> [args...]
```
The same checkout is used on a Windows workstation and on a Linux host.
## 2. Layout
```text
daedalus/
├── bin/
│ ├── daedalus # Linux launcher (bash), no install needed
│ └── daedalus.bat # Windows launcher (cmd / PowerShell)
├── daedalus/ # The CLI package
│ ├── __main__.py # python -m daedalus
│ ├── cli.py # Argument handling, list, path, dispatch
│ ├── registry.py # SCRIPTS: name -> Script
│ ├── runners.py # Suffix -> interpreter command
│ └── tests/
├── python/
│ ├── src/<name>/ # Python scripts, one folder per script
│ └── tests/ # pytest tests for python/src
├── bash/ # *.sh scripts
│ └── tests/ # pytest tests that run them
├── powershell/ # *.ps1 scripts
├── batch/ # *.bat scripts
├── ci/ # Sanity, syntax, and lint checks, with tests
├── autotest.py # Runs every check (local and CI)
├── README.md # Script catalog (user-facing)
├── INSTALL.md # Install, usage, development
└── SPEC.md # This file
```
## 3. Command line
| Call | Result | Exit code |
| --- | --- | --- |
| `daedalus <name> [args...]` | Runs the registered script with `args` passed through unchanged | The script's exit code |
| `daedalus`, `daedalus -l`, `daedalus --list` | Prints every registered name, its type, and description | 0 |
| `daedalus -h`, `daedalus --help` | Prints usage | 0 |
| `daedalus --path <name>` | Prints the absolute path of the script | 0 |
| `daedalus --version` | Prints the installed version, or `project.version` from `pyproject.toml` in a checkout | 0 |
| Unknown name | Prints an error and close matches to stderr | 2 |
| Script file missing, or no interpreter found | Prints the reason to stderr | 2 |
- Everything after `<name>` belongs to the script, including `--help`:
`daedalus my_tool --help` shows the help of `my_tool`.
- The script runs in the caller's current directory, with the caller's
stdin, stdout, and stderr, so interactive scripts work.
- Ctrl+C reaches the script. daedalus waits for it to exit and returns its
exit code.
Ways to run the CLI:
- Install it with pip (section 9). `daedalus` is then on `PATH`
everywhere, with every registered script bundled.
- `bin/daedalus` (Linux) or `bin\daedalus.bat` (Windows). Add `bin/` to
`PATH` to call plain `daedalus`. Needs no install.
- `python -m daedalus` from the repository root.
## 4. Registry
`daedalus/registry.py` holds one dictionary:
```python
SCRIPTS: dict[str, Script] = {
"my_tool": Script(
path="python/src/my_tool/my_tool.py",
description="One-line summary for daedalus --list",
),
}
```
In this template checkout, `SCRIPTS` is empty until you add the first
script.
- `Script` is a frozen dataclass with `path` (repo-relative, forward
slashes) and `description` (one line).
- The key is the command name: lowercase letters, digits, `_`, and `-`,
starting with a letter.
- Names that start with `-` are reserved for daedalus options.
- The runner is chosen from the suffix of `path`. No other field selects it.
- Tests enforce, for every entry: the name is valid, the file exists, the
suffix has a runner, and the description is not empty.
## 5. Runners
| Suffix | Command | Platforms |
| --- | --- | --- |
| `.py` | `<python> <path> args...` (`DAEDALUS_PYTHON` or daedalus's interpreter) | All |
| `.sh` | `<bash> <path> args...` | All with bash |
| `.ps1` | `<pwsh or powershell> -NoProfile -ExecutionPolicy Bypass -File <path> args...` | All with PowerShell |
| `.bat` | `cmd /c <path> args...` | Windows only |
- Python scripts get `python/src` prepended to `PYTHONPATH`, so they can
import shared modules from there.
- Set `DAEDALUS_PYTHON` to a virtual-environment interpreter when a
script needs packages that are not in the pipx venv.
- bash lookup order: `DAEDALUS_BASH`, then Git Bash next to `git` on
Windows (`<git root>/bin/bash.exe`), then `bash` on `PATH`. On Windows,
`bash` on `PATH` is often the WSL launcher, which cannot open Windows
paths, so Git Bash comes first.
- PowerShell lookup order: `pwsh`, then `powershell`.
- A missing interpreter or a `.bat` on a non-Windows host is an error with a
clear message (exit code 2), never a silent skip.
## 6. Adding a script
- Put the file in the folder for its type (section 2). A Python script gets
its own folder: `python/src/<name>/<name>.py`.
- The script must run on its own (`python python/src/<name>/<name>.py`)
without daedalus. Python scripts expose `main(argv: list[str] | None)`
and end with `if __name__ == "__main__": sys.exit(main())`.
- Add one entry to `SCRIPTS` in `daedalus/registry.py`.
- Add a row to the "Available scripts" table in `README.md`, and a short
section with usage when the script takes arguments. A test fails when a
registered name has no row.
- Add tests:
- Python: `python/tests/test_<name>.py`, importing with
`from <name> import <name>`.
- bash: `bash/tests/test_<name>.py`, running the script with
`subprocess` and skipping when bash is missing.
- PowerShell and batch: a test under `python/tests/` that runs the
script, skipped when the interpreter or Windows is missing.
- Run `python autotest.py`. It must pass before pushing.
## 7. Quality gates
`python autotest.py` runs every check; CI runs the same command.
| Check | Rule |
| --- | --- |
| `sanity` | Changed files: line endings (section 8), no private keys, under 2 MB |
| `python_syntax` | Every `*.py` parses |
| `pycodestyle` | PEP 8 with the repository's ignore list (`PYCODESTYLE_IGNORE` in `ci/checks.py`) |
| `shellcheck` | Every `*.sh`, `*.bash`, and suffixless file with a shell shebang |
| `json`, `yaml` | Every file loads |
| `markdown` | markdownlint, MD013 and MD033 disabled |
| `pytest` | All tests pass; coverage of `ci`, `daedalus`, and `python/src` at least `MIN_COVERAGE_PERCENT` |
## 8. Conventions
- Line endings are LF everywhere except `*.bat`, which must be CRLF:
cmd.exe mishandles labels and `goto` in LF-only batch files.
`.gitattributes` enforces both on checkout.
- Python targets 3.11. Standard library imports use `import module`.
Logging uses lazy `%` formatting.
- Markdown lists use dashes.
- `bin/daedalus` and every `*.sh` are committed executable:
`git add --chmod=+x <file>`.
- `MIN_COVERAGE_PERCENT` in `autotest.py` only goes up. Raise it when
tests are added.
## 9. Packaging
`pyproject.toml` builds one wheel that holds the CLI and every script.
| Command | Use |
| --- | --- |
| `pipx install git+ssh://git@example.com/your-org/daedalus.git` | Own isolated environment, `daedalus` on `PATH` (recommended; works on Debian 12, where plain `pip install` is blocked) |
| `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 |
The script folders are copied into the wheel under
`daedalus/_library/`, with the same relative paths as in the repository:
| Repository folder | Installed folder | Files |
| --- | --- | --- |
| `python/src/` | `daedalus/_library/python/src/` | Everything except `__pycache__` and `*.pyc` |
| `bash/` | `daedalus/_library/bash/` | `*.sh` |
| `powershell/` | `daedalus/_library/powershell/` | `*.ps1` |
| `batch/` | `daedalus/_library/batch/` | `*.bat` |
- `LIBRARY_ROOT` in `daedalus/__init__.py` is `daedalus/_library` when
that folder exists (a normal install), otherwise the repository root (a
checkout or an editable install). Registry paths resolve against it, so
`SCRIPTS` entries are the same in both cases.
- Tests under `*/tests/` are not packaged.
- The CLI has no runtime dependencies. Test and lint tools stay in
`requirements.txt`.
- A test builds the wheel and fails when any registered script is missing
from it.
- Bump `version` in `pyproject.toml` when scripts or the CLI change, so
`pipx upgrade` picks them up.
## 10. Implementation plan
| Step | Work | Status |
| --- | --- | --- |
| 1 | This SPEC | Done |
| 2 | `daedalus/registry.py` with `Script` and `SCRIPTS` (empty in template) | Done |
| 3 | `daedalus/runners.py`: suffix table, interpreter lookup, `build_command`, `run` | Done |
| 4 | `daedalus/cli.py` and `__main__.py`: list, help, `--path`, dispatch, close-match errors | Done |
| 5 | `bin/daedalus`, `bin/daedalus.bat`, `[project.scripts]` in `pyproject.toml` | Done |
| 6 | Tests: registry consistency, every runner, CLI paths, launchers | Done |
| 7 | Per-script tests under `python/tests/` or `bash/tests/` when scripts exist | Template |
| 8 | CI: CRLF rule for `*.bat`, shellcheck on suffixless shell files, `daedalus` in coverage | Done |
| 9 | README: how to call `daedalus` | Done |
| 10 | `pyproject.toml`: map the script folders into `daedalus/_library` as package data | Done |
| 11 | `LIBRARY_ROOT` in `daedalus/__init__.py`; registry and runners resolve against it | Done |
| 12 | `daedalus --version` | Done |
| 13 | Tests: `LIBRARY_ROOT` selection, wheel contains every registered script, installed CLI | Done |
| 14 | README: install with pipx or pip | Done |