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.
This commit is contained in:
+135
@@ -0,0 +1,135 @@
|
||||
# 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)
|
||||
- [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 NAME goes to it
|
||||
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.
|
||||
|
||||
## 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`.
|
||||
- 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/`.
|
||||
- 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.
|
||||
Reference in New Issue
Block a user