# daedalus specification How this repository is laid out, how scripts are registered and run, and the rules for maintaining it. This file alone is enough to rebuild the tool: it states every observable behavior (arguments, output, exit codes, environment variables, files written, packaging, checks). Change this file first when the behavior changes, then change the code and tests to match. This checkout is an **empty template**: the CLI and quality gates are ready; add scripts per section 6. - [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. Library imports](#10-library-imports) - [11. Logging for Python scripts](#11-logging-for-python-scripts) - [12. Implementation plan](#12-implementation-plan) ## 1. Purpose - **1.1** Every heading and list item has a stable id. Cite an item as `SPEC item 3.7.1`. New items get the next free number; numbers of removed items are not reused. - **1.2** daedalus keeps loose personal scripts in one repository, each with tests, and runs any of them through one command: ```text daedalus [args...] daedalus [category...] list scripts (AND when multiple) daedalus … [args...] run when the script has every category ``` In this template checkout, `SCRIPTS` is empty until the first script is added (section 6). - **1.3** The same tool runs on a Windows workstation and on a Linux host, either installed with pipx (section 9) or run from a checkout (SPEC item 3.7.2). - **1.4** Scripts are written in Python, bash, PowerShell, or batch. The CLI picks the interpreter from the file suffix and passes arguments, terminal, and exit code straight through. - **1.5** Reuse first: when a popular, widely tested, trusted third-party package already solves a problem, use it instead of writing our own code; the Python standard library covers the rest. Python 3.11 or newer. Dependency policy: SPEC item 9.6. Today the one dependency is argcomplete, for shell completion (SPEC item 3.13); its import is guarded, so the CLI also runs where it is not installed — completion is then off. ## 2. Layout - **2.1** Repository tree: ```text daedalus/ ├── bin/ │ ├── daedalus # Linux launcher (bash), no install needed; PYTHON_ARGCOMPLETE_OK marker │ └── daedalus.bat # Windows launcher (cmd / PowerShell) ├── daedalus/ # The CLI package │ ├── __init__.py # PACKAGE_DIR, REPO_ROOT, LIBRARY_ROOT, checkout imports │ ├── __main__.py # python -m daedalus │ ├── cli.py # argparse parser, list, path, dispatch │ ├── completions.py # Completion candidates for argcomplete │ ├── registry.py # Script, SCRIPTS, category helpers │ ├── runners.py # Suffix -> interpreter command, run │ ├── run_python_script.py # Child entry for .py scripts (logging, argv) │ ├── daedalus_logging/ # File + console logging (section 11) │ └── tests/ ├── python/ │ ├── src// # Python scripts, one folder per script │ └── tests/ # pytest tests for python/src, .ps1, .bat ├── bash/ # *.sh scripts (SPEC item 6.10 interface) │ ├── daedalus_common.sh # shared helper: daedalus_bash_dispatch, help() routing │ └── tests/ # pytest tests that run them ├── powershell/ # *.ps1 scripts ├── batch/ # *.bat scripts (CRLF) ├── ci/ # sanity.py, checks.py, with tests ├── autotest.py # Runs every check (local and CI) ├── pyproject.toml # Package, version, entry point, package data ├── requirements.txt # Test and lint tools ├── .gitea/workflows/ci.yml # CI job that runs autotest.py ├── .gitattributes # LF everywhere, CRLF for *.bat ├── .editorconfig # UTF-8, LF, final newline, 4 spaces (2 for yml/json/md) ├── CHANGELOG.md # Release notes, newest first ├── README.md # Script catalog (user-facing) ├── INSTALL.md # Install, usage, development ├── AGENTS.md # Rules for AI agents └── SPEC.md # This file ``` - **2.2** Three paths are computed in `daedalus/__init__.py`: - **2.2.1** `PACKAGE_DIR`: the resolved folder of the `daedalus` package. - **2.2.2** `REPO_ROOT`: the parent of `PACKAGE_DIR` (the checkout root, or `site-packages` in an install). - **2.2.3** `LIBRARY_ROOT`: see SPEC item 9.3. ## 3. Command line | Call | Result | Exit code | | --- | --- | --- | | `daedalus [args...]` | Runs the registered script with `args` passed through unchanged | The script's exit code | | `daedalus [category...]` | Prints the version line, then scripts that have **every** listed category | 0 | | `daedalus … [args...]` | Runs `` when it has every category prefix; same pass-through as the flat form | The script's exit code | | `daedalus`, `daedalus -l`, `daedalus --list` | Prints the version line, then every script (SPEC item 3.3) | 0 | | `daedalus -h`, `daedalus --help` | Prints usage (SPEC item 3.8) | 0 | | `daedalus --path ` | Prints the absolute path of the script | 0 | | `daedalus --version` | Prints `daedalus ` (SPEC item 3.9) | 0 | | Unknown option, category, or script; script not in category | Prints an error and close matches to stderr | 2 | | Script file missing, unsupported suffix, or no interpreter found | Prints the reason to stderr | 2 | - **3.1** Everything after the script name belongs to the script, including `--help`; these forms show the script help: - **3.1.1** `daedalus sample_script --help` - **3.1.2** `daedalus general sample_script --help` - **3.1.3** `daedalus media convert_video --help` - **3.2** The flat form `daedalus ` stays valid; categories are optional grouping. - **3.3** Listing format (full list and category-filtered list): - **3.3.1** First line `Daedalus Version: `. When at least one script is listed, a blank line and the table follow; otherwise nothing follows. - **3.3.2** The table has a header row `script`, `type`, `categories`, then a rule row of `-` per column. Columns are left-aligned, padded to the widest cell (header included) and separated by two spaces. The `type` column is at least 4 wide. - **3.3.3** One row per script, sorted by name. `type` is the file suffix without the dot (`py`, `sh`, `ps1`, `bat`). `categories` is the labels joined with a comma and a space (`media, linux`). - **3.3.4** Under each row, the description is wrapped to the terminal width (at least 40 columns; 80 when the width cannot be read), every line indented by 8 spaces. Long words and hyphenated words are not split. - **3.3.5** Color: when enabled, the padded name cell is green (`ESC[32m`), the type cell yellow (`ESC[33m`), the categories cell bright blue (`ESC[94m`), each followed by `ESC[0m`. - **3.3.6** Color is enabled when `NO_COLOR` is empty or unset and either `FORCE_COLOR` is non-empty or stdout is a terminal. A non-empty `NO_COLOR` always wins. ```text Daedalus Version: 0.1.0 script type categories -------------------- ---- ------------------ sample_script_name py general, linux sample script description ``` - **3.4** A token is treated as a **category** only when it matches a category in use and is **not** also a registered script name (names and category labels must not collide, SPEC item 4.3). - **3.5** The script runs in the caller's current directory, with the caller's stdin, stdout, and stderr, so interactive scripts work. - **3.6** Ctrl+C reaches the script. daedalus waits for it to exit and returns its exit code. - **3.7** Ways to run the CLI: - **3.7.1** Install it with pipx or pip (section 9). `daedalus` is then on `PATH` everywhere, with every registered script bundled. - **3.7.2** `bin/daedalus` (Linux) or `bin\daedalus.bat` (Windows). Add `bin/` to `PATH` to call plain `daedalus`. Needs no install. - **3.7.2.1** `bin/daedalus` resolves its own real path (following symlinks), prepends the checkout root to `PYTHONPATH`, and `exec`s `python3 -m daedalus "$@"`. - **3.7.2.2** `bin\daedalus.bat` prepends `\..` to `PYTHONPATH`, runs `python -m daedalus %*`, and exits with its `ERRORLEVEL`. - **3.7.3** `python -m daedalus` from the repository root. - **3.7.4** The installed command is the entry point `daedalus = daedalus.cli:main`. - **3.8** `-h` / `--help` prints the argparse rendering of the parser in SPEC item 3.10 (80 columns shown; wrapped to the terminal width): ```text usage: daedalus [-h] [-l | --list] [--version] [--path ] [ ...] [ [args ...]] One CLI, many small scripts, each with tests (SPEC.md). positional arguments: category labels to filter or list, then the script name to run [args ...] arguments passed to the script options: -h, --help show this help message and exit -l, --list list all registered scripts --version print the installed version --path print the path of a script Forms: daedalus [args...] runs a script; daedalus [category...] lists the scripts with every category (AND when several); daedalus ... [args...] runs a script that has every category. ``` - **3.9** The version is resolved in this order: - **3.9.1** The installed distribution metadata for `daedalus`. - **3.9.2** `project.version` from `REPO_ROOT/pyproject.toml` (a checkout that is not installed). - **3.9.3** The string `unknown`. - **3.10** Argument resolution. One `argparse.ArgumentParser` (`prog="daedalus"`, `allow_abbrev=False`, subclass whose `error()` raises `UsageError` instead of exiting): ```text parser arguments: -l | --list store_true flag --version store_true flag --path words positional, nargs "*", metavar script_args positional, argparse.REMAINDER, metavar [args ...] main(argv = sys.argv[1:]): parser = build_parser() argcomplete.autocomplete(parser) when importable (SPEC item 3.13) try: parsed = parser.parse_args(argv) return dispatch(parsed) on usage or runner error: print "daedalus: " to stderr; return 2 dispatch(parsed): if --list or ((words and script_args both empty) and no option set): list(all scripts); return 0 if --version: print "daedalus " + version; return 0 if --path: if words or script_args is not empty: usage error "usage: daedalus --path " print absolute path of lookup(--path value) # file need not exist return 0 prefix = leading words entries while is_category_label(entry) rest = remaining words entries if prefix and rest is empty: scripts = scripts having every label in prefix if none: usage error "no scripts for categories" list(scripts); return 0 if rest: script = lookup_in(prefix, rest[0]) when prefix else lookup(rest[0]) return run(script, rest[1:] + script_args) ``` With argparse, options are parsed wherever argparse sees them before the positionals start (the old first-token-only rule is gone), but everything after the first positional word that argparse cannot bind to `words` is captured by `script_args` (REMAINDER) and passed through (SPEC item 3.1): `daedalus --help` still shows the **script's** help. - **3.11** Error messages: parser errors carry the argparse message, registry errors keep their exact texts; each is printed as `daedalus: ` on stderr with exit code 2: | Case | Message | | --- | --- | | `--path` without a value | `argument --path: expected one argument` | | `--path` with extra words | `usage: daedalus --path ` | | Unknown option | `unrecognized arguments: ` | | Unknown script, close matches exist | `unknown script ''; did you mean: , ` | | Unknown script, no close match | `unknown script ''; run 'daedalus --list'` | | Categories match no script | `no scripts for categories: , ` | | Unknown script after a category prefix | `unknown script '' for ''; did you mean: …` or `…; run 'daedalus '` | | Script lacks a prefix category | `script '' has categories '', not []; run 'daedalus ' or pick another prefix` | - **3.12** Close matches are up to 3 names with similarity ratio at least 0.6 (Python `difflib.get_close_matches` defaults). After a category prefix, only scripts in those categories are candidates. - **3.13** Shell completion for the parser above (SPEC item 3.10) comes from argcomplete (SPEC item 1.5): - **3.13.1** `main` calls `argparse` completion via `argcomplete.autocomplete(parser)` before `parse_args`, when argcomplete is importable. Without argcomplete the CLI runs unchanged, with completion off. - **3.13.2** Activation (bash): `eval "$(register-python-argcomplete daedalus)"` in `~/.bashrc`; `register-python-argcomplete` ships with argcomplete. Other shells argcomplete supports (zsh, fish, tcsh, powershell) register the same way. - **3.13.3** Completing a `words` entry (SPEC item 3.10): `daedalus/completions.py` offers every registered script name and every category label in use, narrowed by prefix; category labels already typed are not offered again, and script candidates narrow to the scripts that have every typed label (SPEC item 3.4): `daedalus test h` completes `hello`. Candidates are sorted. - **3.13.4** `--path ` completes script names. - **3.13.5** After a registered script name has been typed (completed, before the word being completed), the rest of the line belongs to the script (SPEC item 3.1): daedalus offers nothing of its own — not its options, and never the working-directory file listing (the `script_args` action keeps its empty completer, SPEC 3.10). - **3.13.5.1** A `.py` script is asked to complete its own arguments: daedalus re-execs the interpreter command of its runner (SPEC item 5.8) with the argument words as the script's argv, `COMP_LINE` rewritten to start at the script name, `COMP_POINT` adjusted, the completion environment passed through, and the completion channel (fd 8) inherited. The script completes its arguments (SPEC item 6.9); quoting in the words is not preserved in the rewrite. - **3.13.5.2** A `.sh` script that implements the interface (SPEC item 6.10) completes the help words `--help`, `-h`, and `help`, filtered by the word being typed; daedalus writes them itself on the completion channel — no script runs on TAB. A `.sh` script without the interface, and `.ps1` / `.bat` scripts, get no candidates: the shell default (file names) applies. - **3.13.6** The completion hook re-runs the `daedalus` command on `PATH`: the program that runs on TAB must import argcomplete (installed dependency, or the dev venv, or the system package) and must reach `autocomplete` before parsing. - **3.13.7** `bin/daedalus` carries a `# PYTHON_ARGCOMPLETE_OK` comment in its first kilobyte: argcomplete versions that scan for the marker require it. ## 4. Registry `daedalus/registry.py` holds one dictionary. In this template checkout it is empty until the first script is added: ```python SCRIPTS: dict[str, Script] = { "": Script( path="python/src//.py", description="One-line summary", categories="general", ), "": Script( path="bash/.sh", description="One-line summary", categories=("category_a", "category_b"), ), } ``` - **4.1** `Script` is a frozen (immutable) record: - **4.1.1** `path` is relative to `LIBRARY_ROOT`, with forward slashes. - **4.1.2** `description` is one line. - **4.1.3** `categories` is one or more labels, default `general`. A string becomes a one-item tuple, a list becomes a tuple, and an empty list or tuple is rejected with `ValueError`. - **4.1.4** `absolute_path` is `LIBRARY_ROOT / path`. - **4.1.5** `categories_display` is the labels joined with a comma and a space. - **4.2** The key is the command name and matches `^[a-z][a-z0-9_-]*$`. - **4.3** Each category label uses the same pattern as script names. No script name may equal any label in `used_categories()` (so `daedalus media` is unambiguous). - **4.4** Helpers: - **4.4.1** `used_categories()`: the set of every label of every script. - **4.4.2** `is_category_label(token)`: false when `token` is a script name; otherwise true when it is in `used_categories()`. - **4.4.3** `scripts_matching_categories(labels)`: scripts that have every label (AND), sorted by name; all scripts when `labels` is empty. - **4.5** Leading argv tokens that are category labels form a prefix; the script must include **every** prefix label in `categories`. - **4.6** Names that start with `-` are reserved for daedalus options. - **4.7** The runner is chosen from the suffix of `path`. No other field selects it. - **4.8** Tests enforce, for every entry: - **4.8.1** The name matches the pattern. - **4.8.2** The file exists, and `path` has no backslash, does not start with `/`, and resolves inside `LIBRARY_ROOT`. - **4.8.3** The suffix has a runner. - **4.8.4** The description is non-empty and has no newline. - **4.8.5** Categories are non-empty and every label matches the pattern; no script name equals a label. - **4.8.6** `README.md` contains ``| `` |``. ## 5. Runners | Suffix | Command | Platforms | | --- | --- | --- | | `.py` | ` /run_python_script.py args...` | All | | `.sh` | ` args...` | All with bash | | `.ps1` | ` -NoProfile -ExecutionPolicy Bypass -File args...` | All with PowerShell | | `.bat` | ` /c args...` | Windows only | - **5.1** Building the command, in order: - **5.1.1** Look up the runner by the lowercased suffix. None found: error `unsupported script type '': `. - **5.1.2** The file must exist: else error `script not found: `. - **5.1.3** Find the interpreter (SPEC items 5.3 to 5.6), then append the script arguments unchanged. - **5.2** `` is `DAEDALUS_PYTHON` when set and non-empty, else the interpreter running daedalus. Set it to a virtual-environment interpreter when a script needs packages that are not in the pipx environment daedalus was installed into. - **5.3** bash lookup order: - **5.3.1** `DAEDALUS_BASH` when set and non-empty. - **5.3.2** On Windows only: resolve `git` on `PATH`, then use `/bin/bash.exe` when that file exists (`git` lives in `/cmd/`). - **5.3.3** `bash` on `PATH`. On Windows, `bash` on `PATH` is often the WSL launcher, which cannot open Windows paths, so Git Bash comes first. - **5.3.4** None: error `bash not found; install it or set DAEDALUS_BASH`. - **5.4** PowerShell lookup order: `pwsh`, then `powershell` on `PATH`. None: error `PowerShell not found; install pwsh`. - **5.5** `.bat` on a non-Windows host: error `: .bat scripts run on Windows only`. - **5.6** Every error above exits daedalus with code 2 (SPEC item 3.10), never a silent skip. - **5.7** Running: - **5.7.1** The child gets the caller's environment, with `REPO_ROOT` (the folder that contains the `daedalus` package) prepended to `PYTHONPATH` using the platform path separator. This applies to every script type, so Python code started from a shell script can also import `daedalus.*` (section 10). - **5.7.2** The child inherits the current directory and the terminal (stdin, stdout, stderr are not redirected). - **5.7.3** daedalus waits for the child and returns its exit code. When Ctrl+C interrupts the wait, it waits again and returns the child's exit code. - **5.8** `run_python_script.py [args...]` runs in the child process: - **5.8.1** No arguments: print `usage: run_python_script.py [args...]` to stderr, exit 2. - **5.8.2** Script path (resolved) is not a file: print `script not found: ` to stderr, exit 2. - **5.8.3** Put the parent of its own folder and its own folder at the front of `sys.path` (when missing), so `import daedalus` works. - **5.8.4** Unless `DAEDALUS_NO_LOGGING` is non-empty, configure logging (section 11) with the console level from `DAEDALUS_LOGLEVEL` (default `INFO`). - **5.8.5** Set `sys.argv` to `[