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

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

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 --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:

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