commit 792beca2c5b2e4a40540d57b3676281d21313a1d Author: nvaldez Date: Wed Nov 11 18:55:05 2026 +0100 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. diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..c933e12 --- /dev/null +++ b/.editorconfig @@ -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 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..0fc908f --- /dev/null +++ b/.gitattributes @@ -0,0 +1,9 @@ +* text=auto eol=lf +*.bat text eol=crlf + +*.png binary +*.jpg binary +*.gif binary +*.zip binary +*.gz binary +*.pdf binary diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..fbb797d --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -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 }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..28a0110 --- /dev/null +++ b/.gitignore @@ -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_*/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d1f098f --- /dev/null +++ b/AGENTS.md @@ -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 [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 --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 ...`). + +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// # 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 --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//.py` | Current Python, `python/src` on `PYTHONPATH` | +| bash | `bash/.sh` | `DAEDALUS_BASH`, Git Bash, then `bash` | +| PowerShell | `powershell/.ps1` | `pwsh`, then `powershell` | +| Batch | `batch/.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//.py` | +| bash | `bash/.sh` | +| PowerShell | `powershell/.ps1` | +| Batch | `batch/.bat` (CRLF, Windows only) | + +Python template: + +```python +""" + +Run via daedalus: ``daedalus [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 command-line arguments.""" + parser = argparse.ArgumentParser(prog="", 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=""` 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 +# +set -euo pipefail + +usage() { + echo "usage: [-h] " +} + +main() { + if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then + usage + return 0 + fi +} + +main "$@" +``` + +Stage it executable: `git add --chmod=+x bash/.sh`. + +PowerShell template: + +```powershell +<# +.SYNOPSIS + +#> +param( + [switch]$Quiet +) +$ErrorActionPreference = 'Stop' +``` + +### 5.5 Register and Document + +Add one entry to `SCRIPTS` in `daedalus/registry.py`, keeping keys +sorted: + +```python + "": Script( + path="python/src//.py", + description="", + ), +``` + +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: + `` | `` | Python | | ``. The registry test looks + for the exact text `` | `` | ``. +- When the script takes arguments, add a `### ` section after the + table: what it does, example `daedalus ...` 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_.py` | `from import `, call functions and `main([...])` | +| bash | `bash/tests/test_.py` | `subprocess.run` with `runners.find_bash()`; skip when bash is missing | +| PowerShell, batch | `python/tests/test_.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 . + +. +""" +from import + + +def test_main_returns_zero(): + """Default run succeeds.""" + assert .main([]) == 0 +``` + +Shell-out skeleton for bash: + +```python +"""Tests for bash/.sh. + +. +""" +import subprocess + +import pytest + +from daedalus import REPO_ROOT +from daedalus import runners + +SCRIPT = REPO_ROOT / "bash" / ".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/.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 | diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8b85fa0 --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..d45b3fb --- /dev/null +++ b/INSTALL.md @@ -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 `\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//.py` | + | bash | `bash/.sh` | + | PowerShell | `powershell/.ps1` | + | Batch | `batch/.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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..fc03b4d --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# daedalus (template) + +Starter repository for daedalus: +one CLI, many small scripts, each with tests. + +```bash +daedalus [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. diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 0000000..b19faf8 --- /dev/null +++ b/SPEC.md @@ -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 [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// # 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 [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 ` | 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 `` 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` | ` args...` (`DAEDALUS_PYTHON` or daedalus's interpreter) | All | +| `.sh` | ` args...` | All with bash | +| `.ps1` | ` -NoProfile -ExecutionPolicy Bypass -File args...` | All with PowerShell | +| `.bat` | `cmd /c 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 (`/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//.py`. +- The script must run on its own (`python python/src//.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_.py`, importing with + `from import `. + - bash: `bash/tests/test_.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 `. +- `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 | diff --git a/autotest.py b/autotest.py new file mode 100644 index 0000000..04ec9b5 --- /dev/null +++ b/autotest.py @@ -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)) diff --git a/bash/tests/.gitkeep b/bash/tests/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/batch/.gitkeep b/batch/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/bin/daedalus b/bin/daedalus new file mode 100755 index 0000000..e5d2901 --- /dev/null +++ b/bin/daedalus @@ -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 "$@" diff --git a/bin/daedalus.bat b/bin/daedalus.bat new file mode 100644 index 0000000..43652ca --- /dev/null +++ b/bin/daedalus.bat @@ -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% diff --git a/ci/__init__.py b/ci/__init__.py new file mode 100644 index 0000000..dbfd987 --- /dev/null +++ b/ci/__init__.py @@ -0,0 +1,4 @@ +"""CI checks for daedalus. + +Package for the sanity, syntax, and lint checks. +""" diff --git a/ci/checks.py b/ci/checks.py new file mode 100644 index 0000000..0ee49fa --- /dev/null +++ b/ci/checks.py @@ -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 diff --git a/ci/sanity.py b/ci/sanity.py new file mode 100644 index 0000000..f8f1c4d --- /dev/null +++ b/ci/sanity.py @@ -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()) diff --git a/ci/tests/test_checks.py b/ci/tests/test_checks.py new file mode 100644 index 0000000..0191d1b --- /dev/null +++ b/ci/tests/test_checks.py @@ -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 diff --git a/ci/tests/test_sanity.py b/ci/tests/test_sanity.py new file mode 100644 index 0000000..cfa2cf9 --- /dev/null +++ b/ci/tests/test_sanity.py @@ -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 diff --git a/daedalus/__init__.py b/daedalus/__init__.py new file mode 100644 index 0000000..897dc9c --- /dev/null +++ b/daedalus/__init__.py @@ -0,0 +1,17 @@ +"""daedalus: run any registered script with ``daedalus [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() diff --git a/daedalus/__main__.py b/daedalus/__main__.py new file mode 100644 index 0000000..02b5813 --- /dev/null +++ b/daedalus/__main__.py @@ -0,0 +1,9 @@ +"""Allow ``python -m daedalus``. + +Module entry point. +""" +import sys + +from daedalus import cli + +sys.exit(cli.main()) diff --git a/daedalus/cli.py b/daedalus/cli.py new file mode 100644 index 0000000..b7a95d1 --- /dev/null +++ b/daedalus/cli.py @@ -0,0 +1,87 @@ +"""daedalus command line: list, locate, and run registered scripts. + +Entry point for ``daedalus [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 [args...] run a script; args go to the script + daedalus [-l | --list] list registered scripts + daedalus --path 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 ") + 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 diff --git a/daedalus/registry.py b/daedalus/registry.py new file mode 100644 index 0000000..b59ff42 --- /dev/null +++ b/daedalus/registry.py @@ -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] = {} diff --git a/daedalus/runners.py b/daedalus/runners.py new file mode 100644 index 0000000..d0f8c94 --- /dev/null +++ b/daedalus/runners.py @@ -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: + # /cmd/git.exe -> /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() diff --git a/daedalus/tests/test_cli.py b/daedalus/tests/test_cli.py new file mode 100644 index 0000000..2744666 --- /dev/null +++ b/daedalus/tests/test_cli.py @@ -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 ") + + +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 diff --git a/daedalus/tests/test_packaging.py b/daedalus/tests/test_packaging.py new file mode 100644 index 0000000..cfd1a47 --- /dev/null +++ b/daedalus/tests/test_packaging.py @@ -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" diff --git a/daedalus/tests/test_registry.py b/daedalus/tests/test_registry.py new file mode 100644 index 0000000..5cdb373 --- /dev/null +++ b/daedalus/tests/test_registry.py @@ -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 diff --git a/daedalus/tests/test_runners.py b/daedalus/tests/test_runners.py new file mode 100644 index 0000000..39858cb --- /dev/null +++ b/daedalus/tests/test_runners.py @@ -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 diff --git a/powershell/.gitkeep b/powershell/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..7101d37 --- /dev/null +++ b/pyproject.toml @@ -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 [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"] diff --git a/python/src/.gitkeep b/python/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/python/tests/.gitkeep b/python/tests/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..76b40fb --- /dev/null +++ b/requirements.txt @@ -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