From 792beca2c5b2e4a40540d57b3676281d21313a1d Mon Sep 17 00:00:00 2001 From: nvaldez Date: Wed, 11 Nov 2026 18:55:05 +0100 Subject: [PATCH] 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. --- .editorconfig | 12 + .gitattributes | 9 + .gitea/workflows/ci.yml | 30 +++ .gitignore | 34 +++ AGENTS.md | 450 +++++++++++++++++++++++++++++++ CHANGELOG.md | 18 ++ INSTALL.md | 135 ++++++++++ README.md | 33 +++ SPEC.md | 227 ++++++++++++++++ autotest.py | 90 +++++++ bash/tests/.gitkeep | 0 batch/.gitkeep | 0 bin/daedalus | 6 + bin/daedalus.bat | 6 + ci/__init__.py | 4 + ci/checks.py | 150 +++++++++++ ci/sanity.py | 64 +++++ ci/tests/test_checks.py | 161 +++++++++++ ci/tests/test_sanity.py | 90 +++++++ daedalus/__init__.py | 17 ++ daedalus/__main__.py | 9 + daedalus/cli.py | 87 ++++++ daedalus/registry.py | 32 +++ daedalus/runners.py | 119 ++++++++ daedalus/tests/test_cli.py | 125 +++++++++ daedalus/tests/test_packaging.py | 102 +++++++ daedalus/tests/test_registry.py | 50 ++++ daedalus/tests/test_runners.py | 181 +++++++++++++ powershell/.gitkeep | 0 pyproject.toml | 47 ++++ python/src/.gitkeep | 0 python/tests/.gitkeep | 0 requirements.txt | 7 + 33 files changed, 2295 insertions(+) create mode 100644 .editorconfig create mode 100644 .gitattributes create mode 100644 .gitea/workflows/ci.yml create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 CHANGELOG.md create mode 100644 INSTALL.md create mode 100644 README.md create mode 100644 SPEC.md create mode 100644 autotest.py create mode 100644 bash/tests/.gitkeep create mode 100644 batch/.gitkeep create mode 100755 bin/daedalus create mode 100644 bin/daedalus.bat create mode 100644 ci/__init__.py create mode 100644 ci/checks.py create mode 100644 ci/sanity.py create mode 100644 ci/tests/test_checks.py create mode 100644 ci/tests/test_sanity.py create mode 100644 daedalus/__init__.py create mode 100644 daedalus/__main__.py create mode 100644 daedalus/cli.py create mode 100644 daedalus/registry.py create mode 100644 daedalus/runners.py create mode 100644 daedalus/tests/test_cli.py create mode 100644 daedalus/tests/test_packaging.py create mode 100644 daedalus/tests/test_registry.py create mode 100644 daedalus/tests/test_runners.py create mode 100644 powershell/.gitkeep create mode 100644 pyproject.toml create mode 100644 python/src/.gitkeep create mode 100644 python/tests/.gitkeep create mode 100644 requirements.txt 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