792beca2c5
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.
228 lines
10 KiB
Markdown
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 |
|