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:
nvaldez
2026-11-11 18:55:05 +01:00
commit 792beca2c5
33 changed files with 2295 additions and 0 deletions
+12
View File
@@ -0,0 +1,12 @@
root = true
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 4
[*.{yml,yaml,json,md}]
indent_size = 2
+9
View File
@@ -0,0 +1,9 @@
* text=auto eol=lf
*.bat text eol=crlf
*.png binary
*.jpg binary
*.gif binary
*.zip binary
*.gz binary
*.pdf binary
+30
View File
@@ -0,0 +1,30 @@
name: CI
# Run autotest.py, the same checks as a local run.
on:
push:
branches: [main]
pull_request:
jobs:
autotest:
runs-on: ubuntu-latest
container: python:3.11
steps:
- name: Install git and shellcheck for the checks
run: apt-get update && apt-get install -y --no-install-recommends git shellcheck
- name: Check out the repository
uses: actions/checkout@v4
with:
# Full history so ci/sanity.py can diff against the target branch.
fetch-depth: 0
- name: Install dependencies
run: |
python --version
python -m pip install --upgrade pip --retries 10 --timeout 120
python -m pip install -r requirements.txt --retries 10 --timeout 120
- name: Run autotest
run: python autotest.py
env:
# Set on pull requests: the sanity diff base for changed-file checks.
SANITY_DIFF_BASE: ${{ github.event.pull_request.base.sha }}
+34
View File
@@ -0,0 +1,34 @@
# Python
__pycache__/
*.py[cod]
*.egg-info/
build/
dist/
# Virtual environments
.venv/
venv/
.env
# Test and lint output
.pytest_cache/
.ruff_cache/
.coverage
.coverage.*
coverage.xml
htmlcov/
report.xml
# CI caches
.cache/
# Editors and OS
.vscode/
.idea/
*.swp
.DS_Store
Thumbs.db
# Local scratch output
*.log
temp_*/
+450
View File
@@ -0,0 +1,450 @@
---
name: daedalus-agent-rules
version: 1.0.0
type: summary
created: 2026-11-11
updated: 2026-11-11
tags: [agents, rules, scripts, cli]
---
# daedalus Agent Rules
- [1. Overview](#1-overview)
- [1.1 Rule References](#11-rule-references)
- [1.2 Sources of Truth](#12-sources-of-truth)
- [2. Basic Rules (MANDATORY)](#2-basic-rules-mandatory)
- [2.1 Change Lifecycle](#21-change-lifecycle)
- [2.2 Testing](#22-testing)
- [2.3 Commit](#23-commit)
- [3. Environment Setup](#3-environment-setup)
- [4. Repository Structure](#4-repository-structure)
- [5. Integrating a Script](#5-integrating-a-script)
- [5.1 Inputs and Checklist](#51-inputs-and-checklist)
- [5.2 Integration Contract](#52-integration-contract)
- [5.3 Choosing the Name and Type](#53-choosing-the-name-and-type)
- [5.4 File Templates](#54-file-templates)
- [5.5 Register and Document](#55-register-and-document)
- [5.6 Tests](#56-tests)
- [5.7 Importing an Existing Script](#57-importing-an-existing-script)
- [6. Code Conventions](#6-code-conventions)
- [6.1 All Files](#61-all-files)
- [6.2 Python](#62-python)
- [6.3 Shell, PowerShell, Batch](#63-shell-powershell-batch)
- [7. Quality Gates](#7-quality-gates)
- [8. Anti-Patterns](#8-anti-patterns)
- [9. Quick Reference](#9-quick-reference)
## 1. Overview
daedalus keeps loose personal scripts in one repository, each with tests,
and runs any of them with `daedalus <name> [args...]`. The same checkout
runs on a Windows workstation and on a Linux host.
This file tells an agent what must hold before it changes the repository,
and how to integrate a new script.
### 1.1 Rule References
Refer to rules in this file as `daedalus agent rule N.M` (for example
`daedalus agent rule 5.2`) to keep them apart from other `AGENTS.md` files
in the workspace.
### 1.2 Sources of Truth
| Topic | File |
| --- | --- |
| Behavior, layout, registry, runners, packaging | [SPEC](./SPEC.md) |
| Script catalog shown to users | [README](./README.md) |
| Install, usage, development setup | [INSTALL](./INSTALL.md) |
When this file and [SPEC](./SPEC.md) disagree, SPEC wins. Fix this file.
## 2. Basic Rules (MANDATORY)
### 2.1 Change Lifecycle
Every change that alters behavior follows these steps, in order:
- **Spec.** Read the [SPEC](./SPEC.md) section for the area. When the
change is not described there, update SPEC first.
- **Tests.** Add or change tests that fail without the change.
- **Code.** Make the smallest change that makes them pass.
- **Docs.** Update [README](./README.md) and [INSTALL](./INSTALL.md) when
user-facing behavior changed.
- **Version.** Bump `version` in `pyproject.toml` when a script or the CLI
changed: patch for a fix, minor for a new script, major for a breaking
CLI change. Without the bump, `pipx upgrade daedalus` does not pick up
the change.
- **Verify.** Run `python autotest.py` (daedalus agent rule 2.2). When a
check fails, read its output, fix the cause, and run it again; never
disable a check. Check `daedalus <name> --help` for a new script.
- **Report.** Tell the user the command name, the files added or changed,
the test result, and how to run the result (`daedalus <name> ...`).
Adding a script that fits [SPEC](./SPEC.md) section 6 needs no SPEC change.
### 2.2 Testing
- Run `python autotest.py` from the repository root before finishing any
task that changes files. CI runs the same command.
- Run a subset while iterating: `python autotest.py pytest markdown`.
- Never lower `MIN_COVERAGE_PERCENT` in `autotest.py`. Raise it when new
tests push coverage up.
### 2.3 Commit
- Commit only when the user asks.
- Print the commit message at the end of the reply.
## 3. Environment Setup
```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 3.11 or newer.
- On Windows the workspace shell is PowerShell: chain commands with `;`,
not `&&`.
- Without an install, run the CLI with `python -m daedalus` from the
repository root.
## 4. Repository Structure
```text
daedalus/
├── bin/ # Launchers: daedalus (bash), daedalus.bat
├── daedalus/ # CLI package: cli.py, registry.py, runners.py, tests/
├── python/
│ ├── src/<name>/ # One folder per Python script
│ └── tests/ # pytest tests for python/src (and .ps1/.bat scripts)
├── bash/ # *.sh scripts; tests/ holds their pytest tests
├── powershell/ # *.ps1 scripts
├── batch/ # *.bat scripts (CRLF)
├── ci/ # sanity and lint checks used by autotest.py
├── autotest.py # Every check, local and CI
├── pyproject.toml # Package, version, script folders as package data
├── README.md # Script catalog
├── INSTALL.md # Install and development
└── SPEC.md # Repository specification
```
- Only `python/src/`, `bash/`, `powershell/`, and `batch/` are shipped in
the wheel (under `daedalus/_library/`). A script anywhere else is not
installed.
- Tests under `*/tests/` are not packaged.
## 5. Integrating a Script
### 5.1 Inputs and Checklist
Before writing anything, know:
- The script: a file path, a paste, or a description of what to build.
- The command name. Default to the file stem in `snake_case`. It must
match `^[a-z][a-z0-9_-]*$` and not already be in `SCRIPTS`.
- The type: Python, bash, PowerShell, or batch. Prefer Python when the
script must run on both Windows and Linux.
- A one-line description for `daedalus --list`.
Ask the user only when the name or the type cannot be inferred. Track the
work with this checklist:
```text
- [ ] File placed and runs on its own
- [ ] Entry added to SCRIPTS in daedalus/registry.py
- [ ] README row and usage section
- [ ] Tests written and passing
- [ ] version bumped in pyproject.toml
- [ ] python autotest.py passes
- [ ] daedalus <name> --help works
```
### 5.2 Integration Contract
A script is integrated when all of these hold. Tests enforce the ones
marked "test".
| Rule | Enforced by |
| --- | --- |
| File is in the folder for its type (daedalus agent rule 5.3) | Packaging test |
| File runs on its own, without daedalus | Review |
| One entry in `SCRIPTS` in `daedalus/registry.py` | Registry test |
| Name matches `^[a-z][a-z0-9_-]*$` | Registry test |
| `path` is repo-relative with forward slashes | Registry test |
| `description` is one non-empty line | Registry test |
| File suffix has a runner (`.py`, `.sh`, `.ps1`, `.bat`) | Registry test |
| A row for the name in the README "Available scripts" table | Registry test |
| Own tests for the script's logic | Review, coverage |
| `version` in `pyproject.toml` bumped | Review |
| `python autotest.py` passes | CI |
### 5.3 Choosing the Name and Type
| Type | Location | Runner |
| --- | --- | --- |
| Python | `python/src/<name>/<name>.py` | Current Python, `python/src` on `PYTHONPATH` |
| bash | `bash/<name>.sh` | `DAEDALUS_BASH`, Git Bash, then `bash` |
| PowerShell | `powershell/<name>.ps1` | `pwsh`, then `powershell` |
| Batch | `batch/<name>.bat` | `cmd /c`, Windows only |
- Prefer Python for anything that must work on both Windows and Linux.
- The command name, the file stem, and (for Python) the folder name are the
same string.
- Choose a name that says what the script does (`backup_configs`, not
`tool1`). Check `daedalus --list` for clashes.
### 5.4 File Templates
| Type | Path |
| --- | --- |
| Python | `python/src/<name>/<name>.py` |
| bash | `bash/<name>.sh` |
| PowerShell | `powershell/<name>.ps1` |
| Batch | `batch/<name>.bat` (CRLF, Windows only) |
Python template:
```python
"""<One line: what the script does.>
Run via daedalus: ``daedalus <name> [args]`` (see daedalus README).
"""
from __future__ import annotations
import argparse
import logging
import sys
LOGGER = logging.getLogger(__name__)
def parse_args(argv: list[str] | None) -> argparse.Namespace:
"""Parse <name> command-line arguments."""
parser = argparse.ArgumentParser(prog="<name>", description=__doc__.splitlines()[0])
parser.add_argument("-q", "--quiet", action="store_true", help="only log warnings and errors")
return parser.parse_args(argv)
def main(argv: list[str] | None = None) -> int:
"""CLI entry point; return the exit code."""
args = parse_args(argv)
logging.basicConfig(level=logging.WARNING if args.quiet else logging.INFO,
format="%(levelname)-5s %(message)s")
return 0
if __name__ == "__main__":
sys.exit(main())
```
- `prog="<name>"` makes `--help` show the daedalus command name.
- Shared helpers go in their own package under `python/src/`; scripts
import them directly because `python/src` is on `PYTHONPATH`.
- Standard library only. Lazy `%` logging. Type hints in every docstring.
bash template:
```bash
#!/usr/bin/env bash
# <One line: what the script does.>
set -euo pipefail
usage() {
echo "usage: <name> [-h] <args>"
}
main() {
if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
usage
return 0
fi
}
main "$@"
```
Stage it executable: `git add --chmod=+x bash/<name>.sh`.
PowerShell template:
```powershell
<#
.SYNOPSIS
<One line: what the script does.>
#>
param(
[switch]$Quiet
)
$ErrorActionPreference = 'Stop'
```
### 5.5 Register and Document
Add one entry to `SCRIPTS` in `daedalus/registry.py`, keeping keys
sorted:
```python
"<name>": Script(
path="python/src/<name>/<name>.py",
description="<one line, same as README>",
),
```
Do not edit `cli.py` or `runners.py`. The suffix picks the runner.
In `README.md`:
- Add a row to the "Available scripts" table, sorted by name:
`` | `<name>` | Python | <description> | ``. The registry test looks
for the exact text `` | `<name>` | ``.
- When the script takes arguments, add a `### <name>` section after the
table: what it does, example `daedalus <name> ...` calls in a `bash`
block, and an argument table. Follow the existing sections, if any.
### 5.6 Tests
| Type | Test file | How |
| --- | --- | --- |
| Python | `python/tests/test_<name>.py` | `from <name> import <name>`, call functions and `main([...])` |
| bash | `bash/tests/test_<name>.py` | `subprocess.run` with `runners.find_bash()`; skip when bash is missing |
| PowerShell, batch | `python/tests/test_<name>.py` | `subprocess.run` via `runners.build_command`; skip when the interpreter or Windows is missing |
Cover the pure logic and `main` with argument lists. Use `tmp_path` for
files and `monkeypatch` for environment variables. Tests must not need
another machine, the network, or an interactive terminal.
Python test skeleton:
```python
"""Tests for <name>.
<what the tests cover>.
"""
from <name> import <name>
def test_main_returns_zero():
"""Default run succeeds."""
assert <name>.main([]) == 0
```
Shell-out skeleton for bash:
```python
"""Tests for bash/<name>.sh.
<what the tests cover>.
"""
import subprocess
import pytest
from daedalus import REPO_ROOT
from daedalus import runners
SCRIPT = REPO_ROOT / "bash" / "<name>.sh"
@pytest.fixture(name="bash")
def fixture_bash() -> str:
"""bash interpreter, or skip."""
try:
return runners.find_bash()
except runners.RunnerError:
pytest.skip("bash not available")
def test_help(bash):
"""--help exits 0 and prints usage."""
result = subprocess.run([bash, str(SCRIPT), "--help"], capture_output=True, text=True, check=False)
assert result.returncode == 0
assert "usage" in result.stdout
```
### 5.7 Importing an Existing Script
When the user brings a script from elsewhere (another repo, another
machine, a paste):
- Keep its behavior. Restructure only as far as the contract needs: a
`main(argv)` entry point for Python, no hard-coded absolute paths, no
secrets.
- Move hard-coded hosts, passwords, and paths to arguments or environment
variables. Never commit credentials.
- Split pure logic (parsing, formatting, computing) from I/O, so it can be
tested without a terminal, the network, or a specific machine.
- Mention the origin in the module docstring, not in a comment per line.
## 6. Code Conventions
### 6.1 All Files
- LF line endings everywhere except `*.bat`, which must be CRLF.
`.gitattributes` enforces both on checkout.
- Markdown lists use dashes. markdownlint runs with MD013 and MD033 off.
- No file over 2 MB, no private keys.
### 6.2 Python
- Target Python 3.11. PEP 8 (pycodestyle with the repo ignore list).
- Standard library imports use `import module`.
- Logging uses lazy `%` formatting: `LOGGER.info("wrote %s", path)`.
- Type hints and a docstring on every function.
- No runtime dependencies outside the standard library. The wheel declares
`dependencies = []`; a script that needs a package must say so in its
`--help` and fail with a clear message when it is missing.
### 6.3 Shell, PowerShell, Batch
- bash scripts start with `#!/usr/bin/env bash` and `set -euo pipefail`,
pass shellcheck, and are committed executable:
`git add --chmod=+x bash/<name>.sh`.
- PowerShell scripts declare a `param()` block and run under `pwsh` on
Linux unless they are Windows-only by nature.
- Batch scripts are Windows-only and CRLF.
## 7. Quality Gates
`python autotest.py` runs these checks in parallel:
| Check | Rule |
| --- | --- |
| `sanity` | Changed files: line endings, no private keys, under 2 MB |
| `python_syntax` | Every `*.py` parses |
| `pycodestyle` | PEP 8 with the repo ignore list |
| `shellcheck` | Every shell script, including suffixless launchers |
| `json`, `yaml` | Every file loads |
| `markdown` | markdownlint |
| `pytest` | All tests pass; coverage of `ci`, `daedalus`, `python/src` at least `MIN_COVERAGE_PERCENT` |
A failing check is reported to the user with its output. Never skip or
disable a check to make a run pass.
## 8. Anti-Patterns
- A script outside `python/src/`, `bash/`, `powershell/`, or `batch/`.
- Registry `path` with backslashes or an absolute path.
- A runner chosen by anything other than the file suffix.
- A script that only works through daedalus (imports from `daedalus`,
reads `LIBRARY_ROOT`).
- Tests that need another machine, the network, or an interactive terminal without a
skip condition.
- Editing `daedalus/cli.py` or `daedalus/runners.py` to add a script.
Adding a script touches only the script, its tests, `registry.py`,
`README.md`, and `pyproject.toml`.
- Lowering `MIN_COVERAGE_PERCENT`.
## 9. Quick Reference
| Task | Action |
| --- | --- |
| Add or import a script | Follow [section 5](#5-integrating-a-script) (daedalus agent rule 5.1) |
| Change CLI or runner behavior | Update [SPEC](./SPEC.md) first (daedalus agent rule 2.1) |
| Register a script | One `Script(...)` entry in `daedalus/registry.py` |
| Document a script | Row and usage section in [README](./README.md) |
| Before finishing | `python autotest.py` |
| Ship a change | Bump `version` in `pyproject.toml` |
| Commit | Only when asked |
+18
View File
@@ -0,0 +1,18 @@
# Changelog
Notable changes are listed here. Release numbers match
[`pyproject.toml`](./pyproject.toml). Newest entries are first.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
- Nothing yet.
## [0.0.0] - 2026-11-11
### Added in 0.0.0
- Empty template: CLI, CI, packaging, and script-integration guide with no
registered scripts.
+135
View File
@@ -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.
+33
View File
@@ -0,0 +1,33 @@
# daedalus (template)
Starter repository for daedalus:
one CLI, many small scripts, each with tests.
```bash
daedalus <name> [args...]
```
**[Install, usage, and development](./INSTALL.md)** ·
[SPEC](./SPEC.md) (how the repo is maintained) ·
[CHANGELOG](./CHANGELOG.md)
## Available scripts
| Script | Type | What it does |
| --- | --- | --- |
| *(none yet)* | — | Add scripts per [AGENTS section 5](./AGENTS.md#5-integrating-a-script) or [SPEC section 6](./SPEC.md#6-adding-a-script). |
`daedalus --list` prints every registered name for the version you have
installed.
## Getting started
1. Clone or copy this template and name the Git remote for your team.
2. Add a script under `python/src/`, `bash/`, `powershell/`, or `batch/`
(see [SPEC layout](./SPEC.md#2-layout)).
3. Register it in `daedalus/registry.py`, add a row to the table above,
write tests, bump `version` in `pyproject.toml`, and run
`python autotest.py`.
Until the registry has at least one script, `daedalus --list` prints an
empty catalog and unknown names exit with code 2.
+227
View File
@@ -0,0 +1,227 @@
# 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 |
+90
View File
@@ -0,0 +1,90 @@
"""Run every daedalus check: sanity, syntax, lint, and pytest with coverage.
Single entry point for local runs and CI.
Usage:
python autotest.py # every check
python autotest.py pytest json # only the named checks
"""
import argparse
import concurrent.futures
import functools
import logging
import subprocess
import sys
import time
from ci import checks
from ci import sanity
logger = logging.getLogger(__name__)
MIN_COVERAGE_PERCENT = 75
COVERAGE_SOURCES = ["ci", "daedalus", "python/src"]
def run_each(check, suffixes: tuple[str, ...]) -> int:
"""Apply a per-file check to every repo file with a suffix."""
return sum(check(path) for path in checks.iter_files(checks.REPO_ROOT, suffixes))
def run_shellcheck() -> int:
"""shellcheck every shell script, including suffixless launchers."""
candidates = checks.iter_files(checks.REPO_ROOT, (*checks.SHELL_SUFFIXES, ""))
return sum(checks.check_shell(path) for path in candidates if checks.is_shell_script(path))
def run_on_all(check, suffixes: tuple[str, ...]) -> int:
"""Apply a list check to every repo file with a suffix."""
return check(checks.iter_files(checks.REPO_ROOT, suffixes))
def run_pytest() -> int:
"""Run pytest in a subprocess so coverage is not skewed by imports here."""
cmd = [sys.executable, "-m", "pytest", "--cov-report=term-missing:skip-covered",
f"--cov-fail-under={MIN_COVERAGE_PERCENT}"]
cmd += [f"--cov={source}" for source in COVERAGE_SOURCES]
return subprocess.run(cmd, cwd=checks.REPO_ROOT, check=False).returncode
CHECKS = {
"sanity": sanity.main,
"python_syntax": functools.partial(run_each, checks.check_python_syntax, (".py",)),
"pycodestyle": functools.partial(run_on_all, checks.check_pycodestyle, (".py",)),
"shellcheck": run_shellcheck,
"json": functools.partial(run_each, checks.check_json, (".json",)),
"yaml": functools.partial(run_each, checks.check_yaml, checks.YAML_SUFFIXES),
"markdown": functools.partial(run_on_all, checks.check_markdown, (".md",)),
"pytest": run_pytest,
}
def timed(check) -> tuple[int, float]:
"""Run a check and return its error count and elapsed seconds."""
start = time.monotonic()
return check(), time.monotonic() - start
def main(names: list[str]) -> int:
"""Run the named checks in parallel, print a summary, return 1 on any failure."""
with concurrent.futures.ThreadPoolExecutor() as executor:
futures = {name: executor.submit(timed, CHECKS[name]) for name in names}
results = {name: future.result() for name, future in futures.items()}
print("\n########################################")
print("autotest results")
print("########################################")
for name, (errors, elapsed) in results.items():
print(f"[ {'PASS' if errors == 0 else 'FAIL'} ] {elapsed:6.2f}s {name}")
return int(any(errors != 0 for errors, _ in results.values()))
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("checks", nargs="*", metavar="CHECK",
help=f"checks to run (default: all): {', '.join(CHECKS)}")
selected = parser.parse_args().checks or list(CHECKS)
unknown = sorted(set(selected) - set(CHECKS))
if unknown:
parser.error(f"unknown check(s): {', '.join(unknown)}")
logging.basicConfig(level=logging.INFO, format="%(levelname)-5s %(message)s")
sys.exit(main(selected))
View File
View File
Executable
+6
View File
@@ -0,0 +1,6 @@
#!/usr/bin/env bash
# Run the daedalus CLI from this checkout without installing it.
set -euo pipefail
repo_root="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/.." && pwd)"
export PYTHONPATH="${repo_root}${PYTHONPATH:+:${PYTHONPATH}}"
exec python3 -m daedalus "$@"
+6
View File
@@ -0,0 +1,6 @@
@echo off
rem Run the daedalus CLI from this checkout without installing it.
setlocal
set "PYTHONPATH=%~dp0..;%PYTHONPATH%"
python -m daedalus %*
exit /b %ERRORLEVEL%
+4
View File
@@ -0,0 +1,4 @@
"""CI checks for daedalus.
Package for the sanity, syntax, and lint checks.
"""
+150
View File
@@ -0,0 +1,150 @@
"""File checks shared by autotest.py and the sanity job.
Syntax, lint, and format checks; each returns an error count.
"""
import ast
import json
import logging
import os
import pathlib
import re
import shutil
import subprocess
import pycodestyle
import yaml
from pymarkdown.api import PyMarkdownApi
logger = logging.getLogger(__name__)
REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
SKIP_DIRS = frozenset({
".git", ".venv", "venv", ".cache", ".pytest_cache", ".ruff_cache",
"__pycache__", "htmlcov", "node_modules", "build", "dist",
})
SHELL_SUFFIXES = (".sh", ".bash")
CRLF_SUFFIXES = (".bat",)
SHELL_SHEBANG = re.compile(rb"^#!.*\b(ba|da|k|z)?sh\b")
YAML_SUFFIXES = (".yaml", ".yml")
PYCODESTYLE_IGNORE = ["E501", "E121", "E123", "E126", "E226", "E24", "E704", "W503", "W504"]
MARKDOWN_IGNORE = frozenset({"md013", "md033"})
MAX_FILE_SIZE = 2_000_000
PRIVATE_KEY = re.compile(rb"-----BEGIN [A-Z ]*PRIVATE KEY-----")
def iter_files(root: pathlib.Path, suffixes: tuple[str, ...]) -> list[pathlib.Path]:
"""List files under root with a suffix, skipping SKIP_DIRS."""
found = []
for dirpath, dirnames, filenames in os.walk(root):
dirnames[:] = [name for name in dirnames if name not in SKIP_DIRS]
found.extend(pathlib.Path(dirpath, name) for name in filenames if pathlib.Path(name).suffix in suffixes)
return sorted(found)
def is_shell_script(path: pathlib.Path) -> bool:
"""A *.sh / *.bash file, or a suffixless file with a shell shebang."""
if path.suffix in SHELL_SUFFIXES:
return True
if path.suffix:
return False
with path.open("rb") as stream:
return SHELL_SHEBANG.match(stream.readline()) is not None
def check_python_syntax(path: pathlib.Path) -> int:
"""Return 1 when the Python file does not parse."""
try:
ast.parse(path.read_bytes(), filename=str(path))
except (SyntaxError, ValueError) as error:
logger.error(" [FAIL] python syntax %s: %s", path, error)
return 1
return 0
def check_pycodestyle(paths: list[pathlib.Path]) -> int:
"""Return the number of PEP 8 violations in paths."""
style_guide = pycodestyle.StyleGuide(ignore=PYCODESTYLE_IGNORE, show_source=True)
return style_guide.check_files([str(path) for path in paths]).total_errors
def check_shell(path: pathlib.Path) -> int:
"""Return 1 when shellcheck reports a problem or is missing."""
shellcheck = shutil.which("shellcheck")
if shellcheck is None:
logger.error(" [FAIL] shellcheck not found; run: pip install -r requirements.txt")
return 1
result = subprocess.run(
[shellcheck, "--external-sources", str(path)],
capture_output=True, text=True, check=False,
)
if result.returncode != 0:
logger.error(" [FAIL] shellcheck %s\n%s%s", path, result.stdout, result.stderr)
return 1
return 0
def check_json(path: pathlib.Path) -> int:
"""Return 1 when the file is not valid UTF-8 JSON."""
try:
json.loads(path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, UnicodeDecodeError) as error:
logger.error(" [FAIL] json %s: %s", path, error)
return 1
return 0
def check_yaml(path: pathlib.Path) -> int:
"""Return 1 when any YAML document in the file does not load."""
try:
list(yaml.safe_load_all(path.read_text(encoding="utf-8")))
except (yaml.YAMLError, UnicodeDecodeError) as error:
logger.error(" [FAIL] yaml %s: %s", path, error)
return 1
return 0
def check_markdown(paths: list[pathlib.Path]) -> int:
"""Markdownlint failure count, minus MARKDOWN_IGNORE; YAML front matter allowed."""
errors = 0
for path in paths:
api = PyMarkdownApi().enable_extension_by_identifier("front-matter")
for failure in api.scan_path(str(path)).scan_failures:
if failure.rule_id.lower() in MARKDOWN_IGNORE:
continue
errors += 1
logger.error(" [FAIL] markdown %s:%s [%s] %s", path, failure.line_number,
failure.rule_id, failure.rule_description)
return errors
def check_line_ending(path: pathlib.Path) -> int:
"""Text files must be LF, CRLF_SUFFIXES files CRLF; binary files are skipped."""
data = path.read_bytes()
if b"\0" in data:
return 0
if path.suffix.lower() in CRLF_SUFFIXES:
if b"\n" not in data.replace(b"\r\n", b""):
return 0
logger.error(" [FAIL] %s needs CRLF line endings (cmd.exe)", path)
return 1
if b"\r" not in data:
return 0
logger.error(" [FAIL] CRLF line endings: %s", path)
return 1
def check_private_key(path: pathlib.Path) -> int:
"""Return 1 when the file contains a PEM or OpenSSH private key."""
if PRIVATE_KEY.search(path.read_bytes()) is None:
return 0
logger.error(" [FAIL] private key must not be committed: %s", path)
return 1
def check_file_size(path: pathlib.Path) -> int:
"""Return 1 when the file is larger than MAX_FILE_SIZE bytes."""
size = path.stat().st_size
if size <= MAX_FILE_SIZE:
return 0
logger.error(" [FAIL] %s is %d bytes (limit %d)", path, size, MAX_FILE_SIZE)
return 1
+64
View File
@@ -0,0 +1,64 @@
"""Sanity checks on the files changed against the target branch.
Line endings, private keys, and file size on git changes.
"""
import logging
import os
import pathlib
import subprocess
import sys
from ci import checks
logger = logging.getLogger(__name__)
CHANGE_CHECKS = (checks.check_line_ending, checks.check_private_key, checks.check_file_size)
def git(*args: str) -> subprocess.CompletedProcess:
"""Run git in the repository root and capture its output."""
return subprocess.run(
["git", "-c", "core.quotepath=off", *args],
cwd=checks.REPO_ROOT, capture_output=True, text=True, check=False,
)
def base_ref() -> str | None:
"""Return the first ref that exists to diff against, or None."""
target = os.environ.get("SANITY_TARGET_BRANCH") or os.environ.get("GITHUB_BASE_REF")
candidates = [
os.environ.get("SANITY_DIFF_BASE"),
f"origin/{target}" if target else None,
"origin/main",
"origin/master",
]
for ref in candidates:
if ref and git("rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}").returncode == 0:
return ref
return None
def changed_files() -> list[pathlib.Path]:
"""Files changed against base_ref plus untracked; all files when no base exists."""
ref = base_ref()
if ref is None:
logger.info("No base branch found; checking every tracked and untracked file")
names = git("ls-files", "--cached", "--others", "--exclude-standard").stdout.splitlines()
else:
logger.info("Checking changes against %s", ref)
names = git("diff", "--name-only", "--diff-filter=ACMR", ref).stdout.splitlines()
names += git("ls-files", "--others", "--exclude-standard").stdout.splitlines()
paths = {checks.REPO_ROOT / name for name in names if name}
return sorted(path for path in paths if path.is_file())
def main() -> int:
"""Run CHANGE_CHECKS on every changed file and return the error count."""
files = changed_files()
logger.info("Sanity on %d changed file(s)", len(files))
return sum(check(path) for path in files for check in CHANGE_CHECKS)
if __name__ == "__main__":
logging.basicConfig(level=logging.INFO, format="%(levelname)-5s %(message)s")
sys.exit(main())
+161
View File
@@ -0,0 +1,161 @@
"""Tests for ci.checks.
Pass and fail cases for each file check.
"""
import shutil
import pytest
from ci import checks
needs_shellcheck = pytest.mark.skipif(shutil.which("shellcheck") is None, reason="shellcheck not installed")
def test_iter_files_filters_suffix_and_skips_dirs(tmp_path):
"""Only matching suffixes outside SKIP_DIRS are listed."""
(tmp_path / "keep.py").write_text("", encoding="utf-8")
(tmp_path / "other.txt").write_text("", encoding="utf-8")
(tmp_path / ".venv").mkdir()
(tmp_path / ".venv" / "skip.py").write_text("", encoding="utf-8")
assert checks.iter_files(tmp_path, (".py",)) == [tmp_path / "keep.py"]
@pytest.mark.parametrize("source, expected", [("x = 1\n", 0), ("def broken(:\n", 1)])
def test_check_python_syntax(tmp_path, source, expected):
"""Invalid Python fails, valid Python passes."""
path = tmp_path / "script.py"
path.write_text(source, encoding="utf-8")
assert checks.check_python_syntax(path) == expected
def test_check_pycodestyle_counts_violations(tmp_path):
"""PEP 8 violations are counted."""
clean = tmp_path / "clean.py"
clean.write_text("x = 1\n", encoding="utf-8")
dirty = tmp_path / "dirty.py"
dirty.write_text("x=1 \n", encoding="utf-8")
assert checks.check_pycodestyle([clean]) == 0
assert checks.check_pycodestyle([dirty]) > 0
@needs_shellcheck
@pytest.mark.parametrize("source, expected", [
('#!/bin/bash\necho "$1"\n', 0),
("#!/bin/bash\necho $1\n", 1),
])
def test_check_shell(tmp_path, source, expected):
"""shellcheck warnings fail, clean scripts pass."""
path = tmp_path / "script.sh"
path.write_bytes(source.encode("utf-8"))
assert checks.check_shell(path) == expected
def test_check_shell_fails_without_shellcheck(tmp_path, monkeypatch):
"""A missing shellcheck is an error, not a silent pass."""
monkeypatch.setattr(checks.shutil, "which", lambda _name: None)
assert checks.check_shell(tmp_path / "script.sh") == 1
@pytest.mark.parametrize("source, expected", [('{"a": 1}', 0), ('{"a": }', 1)])
def test_check_json(tmp_path, source, expected):
"""Invalid JSON fails, valid JSON passes."""
path = tmp_path / "data.json"
path.write_text(source, encoding="utf-8")
assert checks.check_json(path) == expected
@pytest.mark.parametrize("source, expected", [("a: 1\n---\nb: 2\n", 0), ("a: [1\n", 1)])
def test_check_yaml(tmp_path, source, expected):
"""Invalid YAML fails, multi-document YAML passes."""
path = tmp_path / "data.yaml"
path.write_text(source, encoding="utf-8")
assert checks.check_yaml(path) == expected
@pytest.mark.parametrize("source, fails", [
("# Title\n\n- item\n", False),
("# Title\n# Title again\n", True),
])
def test_check_markdown(tmp_path, source, fails):
"""markdownlint failures are counted."""
path = tmp_path / "doc.md"
path.write_bytes(source.encode("utf-8"))
assert (checks.check_markdown([path]) > 0) == fails
def test_check_markdown_allows_front_matter(tmp_path):
"""YAML front matter before the first heading is not reported."""
path = tmp_path / "SKILL.md"
path.write_bytes(b"---\nname: demo\nversion: 1.0.0\n---\n\n# Title\n\nText.\n")
assert checks.check_markdown([path]) == 0
def test_check_markdown_ignores_line_length(tmp_path):
"""MD013 long lines are not reported."""
path = tmp_path / "doc.md"
path.write_bytes(("# Title\n\n" + "word " * 60).strip().encode("utf-8") + b"\n")
assert checks.check_markdown([path]) == 0
@pytest.mark.parametrize("data, expected", [
(b"a\nb\n", 0),
(b"a\r\nb\r\n", 1),
(b"\x89PNG\r\n\x00\x00", 0),
])
def test_check_line_ending(tmp_path, data, expected):
"""CRLF in text fails; LF and binary files pass."""
path = tmp_path / "file"
path.write_bytes(data)
assert checks.check_line_ending(path) == expected
@pytest.mark.parametrize("data, expected", [
(b"@echo off\r\nexit /b 0\r\n", 0),
(b"@echo off\nexit /b 0\n", 1),
(b"@echo off\r\nexit /b 0\n", 1),
])
def test_check_line_ending_bat_needs_crlf(tmp_path, data, expected):
""".bat files must be CRLF; any bare LF fails."""
path = tmp_path / "run.bat"
path.write_bytes(data)
assert checks.check_line_ending(path) == expected
@pytest.mark.parametrize("name, first_line, expected", [
("run.sh", b"echo hi\n", True),
("launcher", b"#!/usr/bin/env bash\n", True),
("launcher", b"#!/bin/sh\n", True),
("tool", b"#!/usr/bin/env python3\n", False),
("notes", b"plain text\n", False),
("data.txt", b"#!/bin/bash\n", False),
])
def test_is_shell_script(tmp_path, name, first_line, expected):
"""Shell suffixes and suffixless shell shebangs are shell scripts."""
path = tmp_path / name
path.write_bytes(first_line)
assert checks.is_shell_script(path) == expected
@pytest.mark.parametrize("kind", ["RSA ", "OPENSSH ", ""])
def test_check_private_key_detects_keys(tmp_path, kind):
"""PEM and OpenSSH private key headers fail."""
path = tmp_path / "id_key"
path.write_bytes(b"x\n-----BEGIN " + kind.encode() + b"PRIVATE KEY-----\nabc\n")
assert checks.check_private_key(path) == 1
def test_check_private_key_allows_public_key(tmp_path):
"""Public keys and normal files pass."""
path = tmp_path / "key.pub"
path.write_bytes(b"-----BEGIN PUBLIC KEY-----\nabc\n")
assert checks.check_private_key(path) == 0
def test_check_file_size(tmp_path, monkeypatch):
"""Files above MAX_FILE_SIZE fail."""
monkeypatch.setattr(checks, "MAX_FILE_SIZE", 4)
path = tmp_path / "file"
path.write_bytes(b"1234")
assert checks.check_file_size(path) == 0
path.write_bytes(b"12345")
assert checks.check_file_size(path) == 1
+90
View File
@@ -0,0 +1,90 @@
"""Tests for ci.sanity.
Base ref selection and changed-file listing with git stubbed.
"""
import subprocess
import pytest
from ci import checks
from ci import sanity
def fake_git(existing_refs: set[str], outputs: dict[str, str]):
"""Build a git stub: rev-parse succeeds for existing_refs, other commands return outputs."""
def run(*args: str) -> subprocess.CompletedProcess:
if args[0] == "rev-parse":
ref = args[-1].removesuffix("^{commit}")
return subprocess.CompletedProcess(args, 0 if ref in existing_refs else 1, "", "")
return subprocess.CompletedProcess(args, 0, outputs.get(" ".join(args), ""), "")
return run
@pytest.fixture(autouse=True)
def clear_ci_env(monkeypatch):
"""Tests start without CI merge request variables."""
for name in ("SANITY_DIFF_BASE", "SANITY_TARGET_BRANCH", "GITHUB_BASE_REF"):
monkeypatch.delenv(name, raising=False)
def test_base_ref_prefers_merge_request_base(monkeypatch):
"""The PR diff base SHA wins over branch names."""
monkeypatch.setenv("SANITY_DIFF_BASE", "abc123")
monkeypatch.setattr(sanity, "git", fake_git({"abc123", "origin/main"}, {}))
assert sanity.base_ref() == "abc123"
def test_base_ref_uses_target_branch(monkeypatch):
"""The PR target branch is used when there is no base SHA."""
monkeypatch.setenv("GITHUB_BASE_REF", "develop")
monkeypatch.setattr(sanity, "git", fake_git({"origin/develop", "origin/main"}, {}))
assert sanity.base_ref() == "origin/develop"
def test_base_ref_falls_back_to_master(monkeypatch):
"""origin/master is used when origin/main is missing."""
monkeypatch.setattr(sanity, "git", fake_git({"origin/master"}, {}))
assert sanity.base_ref() == "origin/master"
def test_base_ref_none_without_remote_branch(monkeypatch):
"""No base ref exists in a fresh repository."""
monkeypatch.setattr(sanity, "git", fake_git(set(), {}))
assert sanity.base_ref() is None
def test_changed_files_diffs_against_base(tmp_path, monkeypatch):
"""Diffed and untracked files are listed; deleted paths are dropped."""
for name in ("changed.py", "new.sh"):
(tmp_path / name).write_text("", encoding="utf-8")
monkeypatch.setattr(checks, "REPO_ROOT", tmp_path)
monkeypatch.setattr(sanity, "git", fake_git({"origin/main"}, {
"diff --name-only --diff-filter=ACMR origin/main": "changed.py\ngone.py\n",
"ls-files --others --exclude-standard": "new.sh\n",
}))
assert sanity.changed_files() == [tmp_path / "changed.py", tmp_path / "new.sh"]
def test_changed_files_lists_everything_without_base(tmp_path, monkeypatch):
"""Every tracked and untracked file is checked when no base exists."""
(tmp_path / "a.md").write_text("", encoding="utf-8")
monkeypatch.setattr(checks, "REPO_ROOT", tmp_path)
monkeypatch.setattr(sanity, "git", fake_git(set(), {
"ls-files --cached --others --exclude-standard": "a.md\n",
}))
assert sanity.changed_files() == [tmp_path / "a.md"]
def test_main_counts_errors(tmp_path, monkeypatch):
"""main sums the errors of every check over every changed file."""
good = tmp_path / "good.txt"
good.write_bytes(b"ok\n")
bad = tmp_path / "bad.txt"
bad.write_bytes(b"crlf\r\n")
monkeypatch.setattr(sanity, "changed_files", lambda: [good, bad])
assert sanity.main() == 1
def test_git_runs_in_repo_root():
"""The real git helper returns a completed process."""
assert sanity.git("--version").returncode == 0
+17
View File
@@ -0,0 +1,17 @@
"""daedalus: run any registered script with ``daedalus <name> [args...]``.
CLI package; see SPEC.md.
"""
import pathlib
PACKAGE_DIR = pathlib.Path(__file__).resolve().parent
REPO_ROOT = PACKAGE_DIR.parent
def library_root(package_dir: pathlib.Path = PACKAGE_DIR) -> pathlib.Path:
"""Bundled _library of an installed wheel, else the checkout root."""
installed = package_dir / "_library"
return installed if installed.is_dir() else package_dir.parent
LIBRARY_ROOT = library_root()
+9
View File
@@ -0,0 +1,9 @@
"""Allow ``python -m daedalus``.
Module entry point.
"""
import sys
from daedalus import cli
sys.exit(cli.main())
+87
View File
@@ -0,0 +1,87 @@
"""daedalus command line: list, locate, and run registered scripts.
Entry point for ``daedalus <name> [args...]``; see SPEC.md section 3.
"""
from __future__ import annotations
import difflib
import importlib.metadata
import sys
import tomllib
from daedalus import REPO_ROOT
from daedalus import registry
from daedalus import runners
USAGE = """usage: daedalus <name> [args...] run a script; args go to the script
daedalus [-l | --list] list registered scripts
daedalus --path <name> print the path of a script
daedalus --version print the installed version
daedalus -h | --help show this help"""
class UsageError(Exception):
"""Bad daedalus arguments or an unknown script name."""
def format_list(scripts: dict[str, registry.Script]) -> str:
"""One aligned line per script: name, type, description."""
width = max((len(name) for name in scripts), default=0)
return "\n".join(
f"{name:<{width}} {script.absolute_path.suffix.lstrip('.'):<3} {script.description}"
for name, script in sorted(scripts.items())
)
def version() -> str:
"""Installed metadata, else version from checkout pyproject.toml."""
try:
return importlib.metadata.version("daedalus")
except importlib.metadata.PackageNotFoundError:
pyproject = REPO_ROOT / "pyproject.toml"
if pyproject.is_file():
project = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("project", {})
checkout_version = project.get("version")
if isinstance(checkout_version, str) and checkout_version:
return checkout_version
return "unknown"
def lookup(name: str) -> registry.Script:
"""Registered script by name; UsageError with close matches otherwise."""
script = registry.SCRIPTS.get(name)
if script is not None:
return script
matches = difflib.get_close_matches(name, registry.SCRIPTS, n=3)
hint = f"did you mean: {', '.join(matches)}" if matches else "run 'daedalus --list'"
raise UsageError(f"unknown script {name!r}; {hint}")
def dispatch(argv: list[str]) -> int:
"""Handle daedalus options, or run the named script with the rest of argv."""
if not argv or argv[0] in ("-l", "--list"):
print(format_list(registry.SCRIPTS))
return 0
if argv[0] in ("-h", "--help"):
print(USAGE)
return 0
if argv[0] == "--version":
print(f"daedalus {version()}")
return 0
if argv[0] == "--path":
if len(argv) != 2:
raise UsageError("usage: daedalus --path <name>")
print(lookup(argv[1]).absolute_path)
return 0
if argv[0].startswith("-"):
raise UsageError(f"unknown option {argv[0]!r}; run 'daedalus --help'")
return runners.run(lookup(argv[0]).absolute_path, argv[1:])
def main(argv: list[str] | None = None) -> int:
"""CLI entry point; daedalus errors exit with 2."""
try:
return dispatch(sys.argv[1:] if argv is None else argv)
except (UsageError, runners.RunnerError) as error:
print(f"daedalus: {error}", file=sys.stderr)
return 2
+32
View File
@@ -0,0 +1,32 @@
"""Registry of the scripts daedalus can run.
Empty template registry; add entries when integrating scripts (SPEC.md section 4).
Add a script by adding one entry to SCRIPTS. The suffix of ``path`` picks
the runner (daedalus/runners.py).
"""
from __future__ import annotations
import dataclasses
import pathlib
import re
from daedalus import LIBRARY_ROOT
NAME_PATTERN = re.compile(r"^[a-z][a-z0-9_-]*$")
@dataclasses.dataclass(frozen=True)
class Script:
"""One registered script: repo-relative path and a one-line description."""
path: str
description: str
@property
def absolute_path(self) -> pathlib.Path:
"""Absolute path in the checkout or the installed _library."""
return LIBRARY_ROOT / self.path
SCRIPTS: dict[str, Script] = {}
+119
View File
@@ -0,0 +1,119 @@
"""Build and run the interpreter command for a script file.
Suffix to interpreter table for py, sh, ps1, and bat; see SPEC.md section 5.
"""
from __future__ import annotations
import os
import pathlib
import shutil
import subprocess
import sys
from daedalus import LIBRARY_ROOT
PYTHON_SRC = LIBRARY_ROOT / "python" / "src"
class RunnerError(RuntimeError):
"""A script cannot start: missing file, interpreter, or platform."""
def is_windows() -> bool:
"""True on Windows."""
return os.name == "nt"
def find_bash() -> str:
"""DAEDALUS_BASH, then Git Bash on Windows, then bash on PATH."""
override = os.environ.get("DAEDALUS_BASH")
if override:
return override
if is_windows():
git = shutil.which("git")
if git is not None:
# <git root>/cmd/git.exe -> <git root>/bin/bash.exe; PATH bash is often the WSL launcher.
git_bash = pathlib.Path(git).resolve().parent.parent / "bin" / "bash.exe"
if git_bash.is_file():
return str(git_bash)
bash = shutil.which("bash")
if bash is None:
raise RunnerError("bash not found; install it or set DAEDALUS_BASH")
return bash
def find_powershell() -> str:
"""pwsh, then Windows PowerShell."""
for name in ("pwsh", "powershell"):
found = shutil.which(name)
if found is not None:
return found
raise RunnerError("PowerShell not found; install pwsh")
def python_executable() -> str:
"""Return DAEDALUS_PYTHON when set, else the interpreter running daedalus.
DAEDALUS_PYTHON can point at a venv with packages the pipx environment lacks.
"""
override = os.environ.get("DAEDALUS_PYTHON")
if override:
return override
return sys.executable
def python_command(path: pathlib.Path) -> list[str]:
"""Run a .py file with python_executable()."""
return [python_executable(), str(path)]
def bash_command(path: pathlib.Path) -> list[str]:
"""Run a .sh file with bash."""
return [find_bash(), str(path)]
def powershell_command(path: pathlib.Path) -> list[str]:
"""Run a .ps1 file without the user profile or execution policy prompts."""
return [find_powershell(), "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(path)]
def batch_command(path: pathlib.Path) -> list[str]:
"""Run a .bat file with cmd; Windows only."""
if not is_windows():
raise RunnerError(f"{path.name}: .bat scripts run on Windows only")
return [os.environ.get("COMSPEC", "cmd.exe"), "/c", str(path)]
RUNNERS = {
".py": python_command,
".sh": bash_command,
".ps1": powershell_command,
".bat": batch_command,
}
def build_command(path: pathlib.Path, args: list[str]) -> list[str]:
"""Full command line for a script and its arguments."""
runner = RUNNERS.get(path.suffix.lower())
if runner is None:
raise RunnerError(f"unsupported script type {path.suffix!r}: {path}")
if not path.is_file():
raise RunnerError(f"script not found: {path}")
return [*runner(path), *args]
def script_env() -> dict[str, str]:
"""Caller environment with python/src prepended to PYTHONPATH."""
env = dict(os.environ)
env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(PYTHON_SRC), env.get("PYTHONPATH")]))
return env
def run(path: pathlib.Path, args: list[str]) -> int:
"""Run the script attached to this terminal and return its exit code."""
process = subprocess.Popen(build_command(path, args), env=script_env())
try:
return process.wait()
except KeyboardInterrupt:
# Ctrl+C also reaches the child; let it finish its own cleanup.
return process.wait()
+125
View File
@@ -0,0 +1,125 @@
"""Tests for daedalus.cli and the launchers.
Options, errors, dispatch, and end-to-end runs (SPEC.md section 3).
"""
import os
import subprocess
import sys
import pytest
from daedalus import LIBRARY_ROOT
from daedalus import REPO_ROOT
from daedalus import cli
from daedalus import registry
from daedalus import runners
FAKE_SCRIPTS = {
"alpha": registry.Script("python/src/alpha/alpha.py", "First tool"),
"beta_tool": registry.Script("bash/beta_tool.sh", "Second tool"),
}
@pytest.fixture
def fake_registry(monkeypatch):
"""Replace SCRIPTS with a fixed two-entry registry."""
monkeypatch.setattr(registry, "SCRIPTS", FAKE_SCRIPTS)
@pytest.mark.parametrize("argv", [[], ["-l"], ["--list"]])
def test_list(fake_registry, capsys, argv):
"""No arguments or --list prints name, type, and description."""
assert cli.main(argv) == 0
assert capsys.readouterr().out.splitlines() == [
"alpha py First tool",
"beta_tool sh Second tool",
]
@pytest.mark.parametrize("argv", [["-h"], ["--help"]])
def test_help(capsys, argv):
"""--help prints usage."""
assert cli.main(argv) == 0
assert capsys.readouterr().out.startswith("usage: daedalus <name>")
def test_path(fake_registry, capsys):
"""--path prints the absolute script path."""
assert cli.main(["--path", "alpha"]) == 0
assert capsys.readouterr().out.strip() == str(LIBRARY_ROOT / "python/src/alpha/alpha.py")
@pytest.mark.parametrize("installed, expected", [(True, "daedalus 1.2.3"), (False, "daedalus 0.0.0")])
def test_version(monkeypatch, capsys, installed, expected):
"""--version uses metadata or pyproject.toml in a checkout."""
def fake_version(_name):
if not installed:
raise cli.importlib.metadata.PackageNotFoundError(_name)
return "1.2.3"
monkeypatch.setattr(cli.importlib.metadata, "version", fake_version)
assert cli.main(["--version"]) == 0
assert capsys.readouterr().out.strip() == expected
@pytest.mark.parametrize("argv, message", [
(["--path"], "usage: daedalus --path"),
(["--bogus"], "unknown option '--bogus'"),
(["alpah"], "unknown script 'alpah'; did you mean: alpha"),
(["zzz"], "unknown script 'zzz'; run 'daedalus --list'"),
])
def test_usage_errors_exit_2(fake_registry, capsys, argv, message):
"""Bad options and unknown names exit 2 with a message on stderr."""
assert cli.main(argv) == 2
assert message in capsys.readouterr().err
def test_dispatch_passes_args_through(fake_registry, monkeypatch):
"""Everything after the name, including --help, goes to the script."""
calls = []
monkeypatch.setattr(runners, "run", lambda path, args: calls.append((path, args)) or 7)
assert cli.main(["alpha", "--help", "x"]) == 7
assert calls == [(LIBRARY_ROOT / "python/src/alpha/alpha.py", ["--help", "x"])]
def test_runner_error_exits_2(fake_registry, capsys):
"""A missing script file exits 2 instead of a traceback."""
assert cli.main(["alpha"]) == 2
assert "script not found" in capsys.readouterr().err
def test_main_reads_sys_argv(fake_registry, monkeypatch, capsys):
"""Without argv, main uses sys.argv."""
monkeypatch.setattr(sys, "argv", ["daedalus", "--list"])
assert cli.main() == 0
assert "alpha" in capsys.readouterr().out
def run_cli(*command: str) -> subprocess.CompletedProcess:
"""Run a daedalus command from a directory outside the repo."""
env = {**os.environ, "PYTHONPATH": str(REPO_ROOT)}
return subprocess.run(command, capture_output=True, text=True, check=False,
cwd=REPO_ROOT.parent, env=env)
def test_module_runs_list():
"""python -m daedalus --list runs with an empty registry."""
result = run_cli(sys.executable, "-m", "daedalus", "--list")
assert result.returncode == 0, result.stderr
assert result.stdout.strip() == ""
@pytest.mark.skipif(os.name != "nt", reason="cmd.exe is Windows only")
def test_bat_launcher():
"""bin/daedalus.bat runs the CLI and passes the exit code."""
launcher = str(REPO_ROOT / "bin" / "daedalus.bat")
assert run_cli(launcher, "--list").returncode == 0
assert run_cli(launcher, "no_such_script").returncode == 2
@pytest.mark.skipif(os.name == "nt", reason="bash launcher is for Linux")
def test_bash_launcher():
"""bin/daedalus runs the CLI and passes the exit code."""
launcher = str(REPO_ROOT / "bin" / "daedalus")
assert run_cli("bash", launcher, "--list").returncode == 0
assert run_cli("bash", launcher, "no_such_script").returncode == 2
+102
View File
@@ -0,0 +1,102 @@
"""Packaging tests: the wheel bundles every registered script and runs from an install.
SPEC.md section 9; builds the wheel from a copy of the checkout.
"""
import os
import shutil
import subprocess
import sys
import zipfile
import pytest
import daedalus
from daedalus import REPO_ROOT
from daedalus import registry
pytest.importorskip("setuptools")
COPY_IGNORE = shutil.ignore_patterns(
".git", ".venv", "venv", "build", "dist", "*.egg-info", "__pycache__",
".pytest_cache", ".ruff_cache", "htmlcov", ".coverage", ".cache",
)
@pytest.fixture(scope="module")
def wheel(tmp_path_factory):
"""Build the wheel from a copy so no build/ folder lands in the checkout."""
work = tmp_path_factory.mktemp("wheel")
source = work / "src"
shutil.copytree(REPO_ROOT, source, ignore=COPY_IGNORE)
result = subprocess.run(
[sys.executable, "-m", "pip", "wheel", str(source), "--no-deps", "--no-build-isolation",
"-w", str(work / "dist"), "-q"],
capture_output=True, text=True, check=False,
)
assert result.returncode == 0, result.stderr
return next((work / "dist").glob("daedalus-*.whl"))
@pytest.fixture(scope="module")
def installed(wheel, tmp_path_factory):
"""Unpack the wheel as site-packages would hold it."""
site = tmp_path_factory.mktemp("site")
with zipfile.ZipFile(wheel) as archive:
archive.extractall(site)
return site
def wheel_names(wheel) -> list[str]:
"""File names inside the wheel."""
with zipfile.ZipFile(wheel) as archive:
return archive.namelist()
@pytest.mark.parametrize("name, script", sorted(registry.SCRIPTS.items()))
def test_wheel_contains_registered_script(wheel, name, script):
"""Every registered script is bundled under daedalus/_library."""
assert f"daedalus/_library/{script.path}" in wheel_names(wheel), name
def test_wheel_has_no_tests_or_caches(wheel):
"""Tests, bytecode, and placeholders stay out of the wheel."""
bad = [name for name in wheel_names(wheel)
if "/tests/" in name or name.endswith((".pyc", ".gitkeep"))]
assert bad == []
def test_wheel_declares_console_command(wheel):
"""pip creates a daedalus command from the entry point."""
with zipfile.ZipFile(wheel) as archive:
entry_points = next(n for n in archive.namelist() if n.endswith("entry_points.txt"))
assert "daedalus = daedalus.cli:main" in archive.read(entry_points).decode()
def run_installed(installed, *args: str) -> subprocess.CompletedProcess:
"""Run the unpacked CLI from outside the checkout."""
env = {**os.environ, "PYTHONPATH": str(installed)}
return subprocess.run([sys.executable, "-m", "daedalus", *args], capture_output=True,
text=True, check=False, cwd=installed, env=env)
def test_installed_cli_lists_empty(installed):
"""The installed CLI lists nothing when SCRIPTS is empty."""
result = run_installed(installed, "--list")
assert result.returncode == 0, result.stderr
assert result.stdout.strip() == ""
def test_installed_cli_version(installed):
"""The installed CLI reports the packaged version."""
result = run_installed(installed, "--version")
assert result.returncode == 0, result.stderr
assert result.stdout.strip().startswith("daedalus ")
def test_library_root_prefers_installed_library(tmp_path):
"""_library next to the package wins; otherwise the checkout root."""
package = tmp_path / "daedalus"
package.mkdir()
assert daedalus.library_root(package) == tmp_path
(package / "_library").mkdir()
assert daedalus.library_root(package) == package / "_library"
+50
View File
@@ -0,0 +1,50 @@
"""Consistency tests for daedalus.registry.SCRIPTS.
Every registered script is valid, present, and runnable (SPEC.md section 4).
"""
import pytest
from daedalus import LIBRARY_ROOT
from daedalus import REPO_ROOT
from daedalus import registry
from daedalus import runners
ENTRIES = sorted(registry.SCRIPTS.items())
@pytest.mark.parametrize("name, script", ENTRIES)
def test_name_is_valid(name, script):
"""Names are lowercase, start with a letter, and never with '-'."""
assert registry.NAME_PATTERN.match(name), name
@pytest.mark.parametrize("name, script", ENTRIES)
def test_script_file_exists(name, script):
"""The registered path is a file in this checkout."""
assert script.absolute_path.is_file(), f"{name}: {script.path}"
@pytest.mark.parametrize("name, script", ENTRIES)
def test_path_is_repo_relative_posix(name, script):
"""Paths are relative and use forward slashes."""
assert "\\" not in script.path and not script.path.startswith("/"), f"{name}: {script.path}"
assert script.absolute_path.resolve().is_relative_to(LIBRARY_ROOT)
@pytest.mark.parametrize("name, script", ENTRIES)
def test_suffix_has_runner(name, script):
"""The file suffix maps to a runner."""
assert script.absolute_path.suffix.lower() in runners.RUNNERS, f"{name}: {script.path}"
@pytest.mark.parametrize("name, script", ENTRIES)
def test_listed_in_readme(name, script):
"""README "Available scripts" has a row for every registered script."""
readme = (REPO_ROOT / "README.md").read_text(encoding="utf-8")
assert f"| `{name}` |" in readme, f"add {name} to README.md Available scripts"
@pytest.mark.parametrize("name, script", ENTRIES)
def test_description_is_one_line(name, script):
"""Descriptions are non-empty single lines."""
assert script.description.strip() and "\n" not in script.description, name
+181
View File
@@ -0,0 +1,181 @@
"""Tests for daedalus.runners.
Command building per suffix, interpreter lookup, and exit codes.
"""
import os
import subprocess
import sys
import pytest
from daedalus import runners
@pytest.fixture
def script(tmp_path):
"""Factory for an empty script file with a given suffix."""
def make(suffix: str):
path = tmp_path / f"tool{suffix}"
path.write_text("", encoding="utf-8")
return path
return make
def test_python_command(script, monkeypatch):
""".py runs with the current interpreter, args appended."""
monkeypatch.delenv("DAEDALUS_PYTHON", raising=False)
path = script(".py")
assert runners.build_command(path, ["-x", "a b"]) == [sys.executable, str(path), "-x", "a b"]
def test_python_command_honors_daedalus_python(script, monkeypatch):
"""DAEDALUS_PYTHON overrides the pipx interpreter."""
monkeypatch.setenv("DAEDALUS_PYTHON", "/opt/daedalus-venv/bin/python")
path = script(".py")
assert runners.build_command(path, []) == ["/opt/daedalus-venv/bin/python", str(path)]
def test_bash_command(script, monkeypatch):
""".sh runs with the bash found by find_bash."""
monkeypatch.setattr(runners, "find_bash", lambda: "/bin/bash")
path = script(".sh")
assert runners.build_command(path, ["1"]) == ["/bin/bash", str(path), "1"]
def test_powershell_command(script, monkeypatch):
""".ps1 runs with -NoProfile -ExecutionPolicy Bypass -File."""
monkeypatch.setattr(runners, "find_powershell", lambda: "pwsh")
path = script(".ps1")
assert runners.build_command(path, []) == [
"pwsh", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(path),
]
def test_batch_command_on_windows(script, monkeypatch):
""".bat runs with COMSPEC /c on Windows."""
monkeypatch.setattr(runners, "is_windows", lambda: True)
monkeypatch.setenv("COMSPEC", "cmd.exe")
path = script(".BAT")
assert runners.build_command(path, ["x"]) == ["cmd.exe", "/c", str(path), "x"]
def test_batch_command_off_windows(script, monkeypatch):
""".bat on a non-Windows host is an error."""
monkeypatch.setattr(runners, "is_windows", lambda: False)
with pytest.raises(runners.RunnerError, match="Windows only"):
runners.build_command(script(".bat"), [])
def test_unsupported_suffix(script):
"""Unknown suffixes are rejected."""
with pytest.raises(runners.RunnerError, match="unsupported"):
runners.build_command(script(".rb"), [])
def test_missing_file(tmp_path):
"""A registered path that does not exist is an error."""
with pytest.raises(runners.RunnerError, match="not found"):
runners.build_command(tmp_path / "gone.py", [])
def test_find_bash_override(monkeypatch):
"""DAEDALUS_BASH wins."""
monkeypatch.setenv("DAEDALUS_BASH", "/opt/bash")
assert runners.find_bash() == "/opt/bash"
def test_find_bash_prefers_git_bash_on_windows(tmp_path, monkeypatch):
"""On Windows, bash.exe next to git is used before PATH bash."""
(tmp_path / "cmd").mkdir()
(tmp_path / "bin").mkdir()
(tmp_path / "cmd" / "git.exe").write_text("", encoding="utf-8")
(tmp_path / "bin" / "bash.exe").write_text("", encoding="utf-8")
monkeypatch.delenv("DAEDALUS_BASH", raising=False)
monkeypatch.setattr(runners, "is_windows", lambda: True)
monkeypatch.setattr(runners.shutil, "which", {"git": str(tmp_path / "cmd" / "git.exe")}.get)
assert runners.find_bash() == str((tmp_path / "bin" / "bash.exe").resolve())
def test_find_bash_falls_back_to_path(monkeypatch):
"""Without git, bash on PATH is used."""
monkeypatch.delenv("DAEDALUS_BASH", raising=False)
monkeypatch.setattr(runners, "is_windows", lambda: True)
monkeypatch.setattr(runners.shutil, "which", {"bash": "/usr/bin/bash"}.get)
assert runners.find_bash() == "/usr/bin/bash"
def test_find_bash_missing(monkeypatch):
"""No bash anywhere is an error."""
monkeypatch.delenv("DAEDALUS_BASH", raising=False)
monkeypatch.setattr(runners, "is_windows", lambda: False)
monkeypatch.setattr(runners.shutil, "which", lambda _name: None)
with pytest.raises(runners.RunnerError, match="bash not found"):
runners.find_bash()
@pytest.mark.parametrize("available, expected", [
({"pwsh": "pwsh", "powershell": "powershell"}, "pwsh"),
({"powershell": "powershell"}, "powershell"),
])
def test_find_powershell(monkeypatch, available, expected):
"""pwsh is preferred over Windows PowerShell."""
monkeypatch.setattr(runners.shutil, "which", available.get)
assert runners.find_powershell() == expected
def test_find_powershell_missing(monkeypatch):
"""No PowerShell is an error."""
monkeypatch.setattr(runners.shutil, "which", lambda _name: None)
with pytest.raises(runners.RunnerError, match="PowerShell not found"):
runners.find_powershell()
def test_script_env_prepends_python_src(monkeypatch):
"""python/src comes first on PYTHONPATH; the caller's path is kept."""
monkeypatch.setenv("PYTHONPATH", "existing")
assert runners.script_env()["PYTHONPATH"] == os.pathsep.join([str(runners.PYTHON_SRC), "existing"])
def test_run_returns_exit_code(tmp_path):
"""The script's exit code and arguments pass through."""
path = tmp_path / "exit.py"
path.write_text("import sys\nsys.exit(int(sys.argv[1]))\n", encoding="utf-8")
assert runners.run(path, ["3"]) == 3
def test_run_waits_after_ctrl_c(tmp_path, monkeypatch):
"""Ctrl+C in daedalus waits for the script and returns its code."""
class FakeProcess:
calls = 0
def wait(self):
FakeProcess.calls += 1
if FakeProcess.calls == 1:
raise KeyboardInterrupt
return 130
path = tmp_path / "tool.py"
path.write_text("", encoding="utf-8")
monkeypatch.setattr(runners.subprocess, "Popen", lambda *_args, **_kwargs: FakeProcess())
assert runners.run(path, []) == 130
@pytest.mark.skipif(os.name != "nt", reason="cmd.exe is Windows only")
def test_run_batch_end_to_end(tmp_path):
"""A real .bat file runs and returns its exit code."""
path = tmp_path / "exit.bat"
path.write_bytes(b"@echo off\r\nexit /b %1\r\n")
assert runners.run(path, ["4"]) == 4
def test_run_bash_end_to_end(tmp_path):
"""A real .sh file runs and returns its exit code."""
try:
bash = runners.find_bash()
except runners.RunnerError:
pytest.skip("bash not installed")
if subprocess.run([bash, "-c", "exit 0"], capture_output=True, check=False).returncode != 0:
pytest.skip(f"{bash} cannot run scripts")
path = tmp_path / "exit.sh"
path.write_bytes(b'exit "$1"\n')
assert runners.run(path, ["5"]) == 5
View File
+47
View File
@@ -0,0 +1,47 @@
[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"
[project]
name = "daedalus"
version = "0.0.0"
description = "Template for daedalus: loose scripts in one repo, run with: daedalus <name> [args...]"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []
[project.scripts]
daedalus = "daedalus.cli:main"
# The script folders are installed under daedalus/_library/ with their
# repository-relative paths, so registry paths resolve the same way (SPEC.md 9).
[tool.setuptools]
packages = [
"daedalus",
"daedalus._library.python.src",
"daedalus._library.bash",
"daedalus._library.powershell",
"daedalus._library.batch",
]
[tool.setuptools.package-dir]
"daedalus._library.python.src" = "python/src"
"daedalus._library.bash" = "bash"
"daedalus._library.powershell" = "powershell"
"daedalus._library.batch" = "batch"
[tool.setuptools.package-data]
"daedalus._library.python.src" = ["**/*"]
"daedalus._library.bash" = ["*.sh"]
"daedalus._library.powershell" = ["*.ps1"]
"daedalus._library.batch" = ["*.bat"]
[tool.setuptools.exclude-package-data]
"*" = ["*.pyc", "__pycache__/*", "**/__pycache__/*", ".gitkeep"]
[tool.pytest.ini_options]
testpaths = ["ci/tests", "daedalus/tests", "python/tests", "bash/tests"]
pythonpath = [".", "python/src"]
[tool.coverage.run]
omit = ["*/tests/*", "*/__main__.py"]
View File
View File
+7
View File
@@ -0,0 +1,7 @@
pytest>=8.0
pytest-cov>=5.0
pycodestyle>=2.11
pymarkdownlnt>=0.9.20
pyyaml>=6.0
shellcheck-py>=0.10
setuptools>=68