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.
10 KiB
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
- 2. Layout
- 3. Command line
- 4. Registry
- 5. Runners
- 6. Adding a script
- 7. Quality gates
- 8. Conventions
- 9. Packaging
- 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:
daedalus <name> [args...]
The same checkout is used on a Windows workstation and on a Linux host.
2. Layout
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 --helpshows the help ofmy_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).
daedalusis then onPATHeverywhere, with every registered script bundled. bin/daedalus(Linux) orbin\daedalus.bat(Windows). Addbin/toPATHto call plaindaedalus. Needs no install.python -m daedalusfrom the repository root.
4. Registry
daedalus/registry.py holds one dictionary:
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.
Scriptis a frozen dataclass withpath(repo-relative, forward slashes) anddescription(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/srcprepended toPYTHONPATH, so they can import shared modules from there. - Set
DAEDALUS_PYTHONto 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 togiton Windows (<git root>/bin/bash.exe), thenbashonPATH. On Windows,bashonPATHis often the WSL launcher, which cannot open Windows paths, so Git Bash comes first. - PowerShell lookup order:
pwsh, thenpowershell. - A missing interpreter or a
.baton 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 exposemain(argv: list[str] | None)and end withif __name__ == "__main__": sys.exit(main()). - Add one entry to
SCRIPTSindaedalus/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 withfrom <name> import <name>. - bash:
bash/tests/test_<name>.py, running the script withsubprocessand 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.
- Python:
- 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 andgotoin LF-only batch files..gitattributesenforces both on checkout. - Python targets 3.11. Standard library imports use
import module. Logging uses lazy%formatting. - Markdown lists use dashes.
bin/daedalusand every*.share committed executable:git add --chmod=+x <file>.MIN_COVERAGE_PERCENTinautotest.pyonly 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_ROOTindaedalus/__init__.pyisdaedalus/_librarywhen that folder exists (a normal install), otherwise the repository root (a checkout or an editable install). Registry paths resolve against it, soSCRIPTSentries 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
versioninpyproject.tomlwhen scripts or the CLI change, sopipx upgradepicks 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 |