c210e17661
- cli.py rewritten on argparse (build_parser, REMAINDER pass-through: everything after the script name still belongs to the script); help/errors are argparse-rendered, exit code 2 kept for all daedalus errors - completions.py (new): category-aware candidates for argcomplete - script names + unused labels narrowed by typed labels (daedalus test h<TAB> -> hello); --path completes scripts; after a completed script name daedalus offers nothing of its own and delegates .py scripts to their own parser via the run_python_script child with a rewritten COMP_LINE (daedalus hello -<TAB> -> hello's -h --help); SPEC 6.9 documents the autocomplete(parser) opt-in - SPEC: item 1.5 reuse-first third-party policy, 3.8/3.10/3.11 argparse texts, 3.13 completion catalog, 6.9 script opt-in, 9.6 argcomplete dependency - argcomplete>=3.3 as runtime dep (guarded import: CLI runs without it); register-python-argcomplete line for ~/.bashrc; PYTHON_ARGCOMPLETE_OK marker in bin/daedalus; README/INSTALL/CHANGELOG updated; hello opts in - tests: argparse CLI suites, completer units, end-to-end argcomplete probes through the bash fd-8 protocol and the delegation exec chain (autotest green, coverage 97%) Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
203 lines
6.9 KiB
Markdown
203 lines
6.9 KiB
Markdown
# Installing and using daedalus
|
|
|
|
Python 3.11 or newer. This checkout is an **empty template** (no scripts in
|
|
`SCRIPTS` yet). Once you add scripts, the installed `daedalus` command
|
|
bundles every registered one and works from any directory.
|
|
|
|
- [Install](#install)
|
|
- [Usage](#usage)
|
|
- [Tab completion](#tab-completion)
|
|
- [Add a script](#add-a-script)
|
|
- [Development](#development)
|
|
|
|
Back to the [script list](./README.md#available-scripts). Repository rules:
|
|
[SPEC](./SPEC.md).
|
|
|
|
## Install
|
|
|
|
### With pipx (recommended)
|
|
|
|
[pipx](https://pipx.pypa.io/) installs daedalus into its own environment
|
|
and puts the `daedalus` command on `PATH`.
|
|
|
|
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**
|
|
use `pipx upgrade daedalus` for Git installs — it does not pull the repo.
|
|
|
|
```bash
|
|
daedalus_pipx_install() {
|
|
r="${1:-git+ssh://git@example.com/your-org/daedalus.git@main}"
|
|
command -v pipx >/dev/null || sudo apt install -y pipx
|
|
pipx ensurepath 2>/dev/null || pipx ensurepath --force
|
|
if pipx list --short 2>/dev/null | grep -qE '^daedalus '; then
|
|
pipx install --force "$r"
|
|
else
|
|
pipx install "$r"
|
|
fi
|
|
daedalus --version
|
|
}; daedalus_pipx_install
|
|
```
|
|
|
|
No SSH key on the Git host: `daedalus_pipx_install git+https://example.com/your-org/daedalus.git`
|
|
|
|
Windows (PowerShell):
|
|
|
|
```powershell
|
|
python -m pip install --user pipx
|
|
python -m pipx ensurepath # once; then open a new terminal
|
|
pipx install git+ssh://git@example.com/your-org/daedalus.git
|
|
```
|
|
|
|
Without an SSH key for the Git host, use
|
|
`git+https://example.com/your-org/daedalus.git` instead.
|
|
|
|
### From a checkout
|
|
|
|
```bash
|
|
git clone git@example.com:your-org/daedalus.git
|
|
cd daedalus
|
|
pipx install . # or, inside a virtual environment: pip install .
|
|
```
|
|
|
|
On Debian 12, `pip install` into the system Python is blocked
|
|
(externally managed environment). Use pipx or a virtual environment.
|
|
|
|
### Without installing
|
|
|
|
Linux: add to `~/.bashrc`, call `daedalus_checkout` (clone once,
|
|
then `git pull --ff-only`).
|
|
|
|
```bash
|
|
daedalus_checkout() {
|
|
d="${1:-$HOME/daedalus}"
|
|
[[ -d "$d/.git" ]] && git -C "$d" pull --ff-only \
|
|
|| git clone git@example.com:your-org/daedalus.git "$d"
|
|
export PATH="$d/bin:$PATH"
|
|
}; daedalus_checkout
|
|
```
|
|
|
|
Windows: add `<checkout>\bin` to `PATH` (`bin\daedalus.bat`).
|
|
|
|
### Check, upgrade, remove
|
|
|
|
```bash
|
|
daedalus --version # confirm the install
|
|
daedalus_pipx_install # reinstall from Git (same as first paste block)
|
|
pipx uninstall daedalus
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
daedalus --help # usage
|
|
daedalus [--list] # list the available scripts
|
|
daedalus <name> [args...] # run a script; every argument after the name goes to it
|
|
daedalus <category> [category...] # list scripts that have every category
|
|
daedalus <category> <name> [args...] # run when the script has every category
|
|
daedalus --path <name> # print where the script file is
|
|
daedalus --version # print the installed version
|
|
```
|
|
|
|
- `daedalus NAME --help` shows the help of the script, not of daedalus.
|
|
- The exit code is the script's exit code. daedalus's own errors, such as
|
|
an unknown name, exit with 2 and suggest close matches.
|
|
- Listings print `Daedalus Version:`, a table of `script`, `type`, and
|
|
`categories`, and the wrapped description under each row. Colors follow
|
|
`NO_COLOR` / `FORCE_COLOR` and the terminal.
|
|
|
|
Environment variables:
|
|
|
|
| Variable | Effect |
|
|
| --- | --- |
|
|
| `DAEDALUS_PYTHON` | Interpreter for `.py` scripts (default: the interpreter running daedalus) |
|
|
| `DAEDALUS_BASH` | Override the bash used for `.sh` scripts |
|
|
| `DAEDALUS_LOGLEVEL` | Console log level for Python scripts (default `INFO`) |
|
|
| `DAEDALUS_NO_LOGGING` | Non-empty: Python scripts start without the daedalus logging setup |
|
|
| `NO_COLOR` / `FORCE_COLOR` | Colors on listings and console logs |
|
|
|
|
Python scripts run through `daedalus/run_python_script.py`: they get
|
|
`REPO_ROOT` on `PYTHONPATH` (so `import daedalus.<folder>` works for
|
|
shared code), file and console logging to `~/.daedalus/debug.log`, and
|
|
their `sys.argv` and exit code passed through unchanged.
|
|
|
|
## Tab completion
|
|
|
|
Completion is built with [argcomplete](https://github.com/kislyuk/argcomplete);
|
|
it completes script names, category labels, and options — including
|
|
script names after category labels.
|
|
|
|
Bash: register once per shell, e.g. in `~/.bashrc` (the program on
|
|
`PATH` must be able to `import argcomplete`):
|
|
|
|
```bash
|
|
eval "$(register-python-argcomplete daedalus)"
|
|
```
|
|
|
|
zsh:
|
|
|
|
```bash
|
|
autoload -U bashcompinit && bashcompinit
|
|
eval "$(register-python-argcomplete daedalus)"
|
|
```
|
|
|
|
Try it in a new shell:
|
|
|
|
```bash
|
|
daedalus hel<TAB> # completes hello
|
|
daedalus test <TAB><TAB> # lists the scripts (and labels) for the prefix
|
|
daedalus --<TAB> # completes the daedalus options
|
|
```
|
|
|
|
Notes:
|
|
|
|
- `register-python-argcomplete` ships with the argcomplete package; it
|
|
comes with the pipx/pip install (a daedalus dependency since 0.3.0)
|
|
or with your system package (Debian: `python3-argcomplete`).
|
|
- Arguments after the script name belong to the script: a Python script
|
|
that calls `argcomplete.autocomplete(parser)` (SPEC item 6.9) completes
|
|
its own arguments — `daedalus hello -<TAB>` offers hello's `-h`,
|
|
`--help`. Otherwise the shell offers file names there.
|
|
- A checkout run through `bin/daedalus` completes when the `python3`
|
|
it runs can `import argcomplete` and the marker comment stays in the
|
|
launcher (SPEC item 3.13.7).
|
|
|
|
## Add a script
|
|
|
|
- Put the file in the folder for its type:
|
|
| Type | Folder |
|
|
| --- | --- |
|
|
| Python | `python/src/<name>/<name>.py` |
|
|
| bash | `bash/<name>.sh` |
|
|
| PowerShell | `powershell/<name>.ps1` |
|
|
| Batch | `batch/<name>.bat` (CRLF line endings, Windows only) |
|
|
- Register it in `SCRIPTS` in `daedalus/registry.py` (set `categories`
|
|
when it belongs to a group such as `media` or `linux`; the default is
|
|
`general`).
|
|
- Add a row to the [Available scripts](./README.md#available-scripts)
|
|
table in `README.md`. A test fails when a registered script is missing
|
|
from that table.
|
|
- Add tests under `python/tests/` or `bash/tests/`. Python tests import
|
|
the script with `from daedalus.<name> import <name>`; a new
|
|
`python/src/<folder>/` also needs a matching `daedalus.<folder>`
|
|
entry in `pyproject.toml` (SPEC section 9).
|
|
- Bump `version` in `pyproject.toml`, then run `daedalus_pipx_install`
|
|
(or `pipx install --force` from the Git URL) so pipx picks up the change.
|
|
- Run `python autotest.py`.
|
|
|
|
Details: [SPEC section 6](./SPEC.md#6-adding-a-script).
|
|
|
|
## Development
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
|
|
python -m pip install -r requirements.txt
|
|
pip install -e . # daedalus command runs the checkout
|
|
python autotest.py # every check; CI runs the same
|
|
python autotest.py pytest # only some checks
|
|
```
|
|
|
|
`autotest.py` runs sanity (line endings, private keys, file size),
|
|
Python syntax, pycodestyle, shellcheck, JSON, YAML, markdown lint, and
|
|
pytest with coverage.
|