daedalus 0.0.0: empty template - one CLI, many small scripts, each with tests
Sanitized open-source starter: renamed to daedalus, Norse-free of internal references, AI attribution stripped, skill merged into AGENTS.md, CI converted to Gitea Actions. No registered scripts yet.
This commit is contained in:
@@ -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
|
||||
@@ -0,0 +1,9 @@
|
||||
* text=auto eol=lf
|
||||
*.bat text eol=crlf
|
||||
|
||||
*.png binary
|
||||
*.jpg binary
|
||||
*.gif binary
|
||||
*.zip binary
|
||||
*.gz binary
|
||||
*.pdf binary
|
||||
@@ -0,0 +1,30 @@
|
||||
name: CI
|
||||
# Run autotest.py, the same checks as a local run.
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
|
||||
jobs:
|
||||
autotest:
|
||||
runs-on: ubuntu-latest
|
||||
container: python:3.11
|
||||
steps:
|
||||
- name: Install git and shellcheck for the checks
|
||||
run: apt-get update && apt-get install -y --no-install-recommends git shellcheck
|
||||
- name: Check out the repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
# Full history so ci/sanity.py can diff against the target branch.
|
||||
fetch-depth: 0
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
python --version
|
||||
python -m pip install --upgrade pip --retries 10 --timeout 120
|
||||
python -m pip install -r requirements.txt --retries 10 --timeout 120
|
||||
- name: Run autotest
|
||||
run: python autotest.py
|
||||
env:
|
||||
# Set on pull requests: the sanity diff base for changed-file checks.
|
||||
SANITY_DIFF_BASE: ${{ github.event.pull_request.base.sha }}
|
||||
+34
@@ -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_*/
|
||||
@@ -0,0 +1,450 @@
|
||||
---
|
||||
name: daedalus-agent-rules
|
||||
version: 1.0.0
|
||||
type: summary
|
||||
created: 2026-11-11
|
||||
updated: 2026-11-11
|
||||
tags: [agents, rules, scripts, cli]
|
||||
---
|
||||
|
||||
# daedalus Agent Rules
|
||||
|
||||
- [1. Overview](#1-overview)
|
||||
- [1.1 Rule References](#11-rule-references)
|
||||
- [1.2 Sources of Truth](#12-sources-of-truth)
|
||||
- [2. Basic Rules (MANDATORY)](#2-basic-rules-mandatory)
|
||||
- [2.1 Change Lifecycle](#21-change-lifecycle)
|
||||
- [2.2 Testing](#22-testing)
|
||||
- [2.3 Commit](#23-commit)
|
||||
- [3. Environment Setup](#3-environment-setup)
|
||||
- [4. Repository Structure](#4-repository-structure)
|
||||
- [5. Integrating a Script](#5-integrating-a-script)
|
||||
- [5.1 Inputs and Checklist](#51-inputs-and-checklist)
|
||||
- [5.2 Integration Contract](#52-integration-contract)
|
||||
- [5.3 Choosing the Name and Type](#53-choosing-the-name-and-type)
|
||||
- [5.4 File Templates](#54-file-templates)
|
||||
- [5.5 Register and Document](#55-register-and-document)
|
||||
- [5.6 Tests](#56-tests)
|
||||
- [5.7 Importing an Existing Script](#57-importing-an-existing-script)
|
||||
- [6. Code Conventions](#6-code-conventions)
|
||||
- [6.1 All Files](#61-all-files)
|
||||
- [6.2 Python](#62-python)
|
||||
- [6.3 Shell, PowerShell, Batch](#63-shell-powershell-batch)
|
||||
- [7. Quality Gates](#7-quality-gates)
|
||||
- [8. Anti-Patterns](#8-anti-patterns)
|
||||
- [9. Quick Reference](#9-quick-reference)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
daedalus keeps loose personal scripts in one repository, each with tests,
|
||||
and runs any of them with `daedalus <name> [args...]`. The same checkout
|
||||
runs on a Windows workstation and on a Linux host.
|
||||
|
||||
This file tells an agent what must hold before it changes the repository,
|
||||
and how to integrate a new script.
|
||||
|
||||
### 1.1 Rule References
|
||||
|
||||
Refer to rules in this file as `daedalus agent rule N.M` (for example
|
||||
`daedalus agent rule 5.2`) to keep them apart from other `AGENTS.md` files
|
||||
in the workspace.
|
||||
|
||||
### 1.2 Sources of Truth
|
||||
|
||||
| Topic | File |
|
||||
| --- | --- |
|
||||
| Behavior, layout, registry, runners, packaging | [SPEC](./SPEC.md) |
|
||||
| Script catalog shown to users | [README](./README.md) |
|
||||
| Install, usage, development setup | [INSTALL](./INSTALL.md) |
|
||||
|
||||
When this file and [SPEC](./SPEC.md) disagree, SPEC wins. Fix this file.
|
||||
|
||||
## 2. Basic Rules (MANDATORY)
|
||||
|
||||
### 2.1 Change Lifecycle
|
||||
|
||||
Every change that alters behavior follows these steps, in order:
|
||||
|
||||
- **Spec.** Read the [SPEC](./SPEC.md) section for the area. When the
|
||||
change is not described there, update SPEC first.
|
||||
- **Tests.** Add or change tests that fail without the change.
|
||||
- **Code.** Make the smallest change that makes them pass.
|
||||
- **Docs.** Update [README](./README.md) and [INSTALL](./INSTALL.md) when
|
||||
user-facing behavior changed.
|
||||
- **Version.** Bump `version` in `pyproject.toml` when a script or the CLI
|
||||
changed: patch for a fix, minor for a new script, major for a breaking
|
||||
CLI change. Without the bump, `pipx upgrade daedalus` does not pick up
|
||||
the change.
|
||||
- **Verify.** Run `python autotest.py` (daedalus agent rule 2.2). When a
|
||||
check fails, read its output, fix the cause, and run it again; never
|
||||
disable a check. Check `daedalus <name> --help` for a new script.
|
||||
- **Report.** Tell the user the command name, the files added or changed,
|
||||
the test result, and how to run the result (`daedalus <name> ...`).
|
||||
|
||||
Adding a script that fits [SPEC](./SPEC.md) section 6 needs no SPEC change.
|
||||
|
||||
### 2.2 Testing
|
||||
|
||||
- Run `python autotest.py` from the repository root before finishing any
|
||||
task that changes files. CI runs the same command.
|
||||
- Run a subset while iterating: `python autotest.py pytest markdown`.
|
||||
- Never lower `MIN_COVERAGE_PERCENT` in `autotest.py`. Raise it when new
|
||||
tests push coverage up.
|
||||
|
||||
### 2.3 Commit
|
||||
|
||||
- Commit only when the user asks.
|
||||
- Print the commit message at the end of the reply.
|
||||
|
||||
## 3. Environment Setup
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
|
||||
python -m pip install -r requirements.txt
|
||||
pip install -e . # daedalus command runs the checkout
|
||||
```
|
||||
|
||||
- Python 3.11 or newer.
|
||||
- On Windows the workspace shell is PowerShell: chain commands with `;`,
|
||||
not `&&`.
|
||||
- Without an install, run the CLI with `python -m daedalus` from the
|
||||
repository root.
|
||||
|
||||
## 4. Repository Structure
|
||||
|
||||
```text
|
||||
daedalus/
|
||||
├── bin/ # Launchers: daedalus (bash), daedalus.bat
|
||||
├── daedalus/ # CLI package: cli.py, registry.py, runners.py, tests/
|
||||
├── python/
|
||||
│ ├── src/<name>/ # One folder per Python script
|
||||
│ └── tests/ # pytest tests for python/src (and .ps1/.bat scripts)
|
||||
├── bash/ # *.sh scripts; tests/ holds their pytest tests
|
||||
├── powershell/ # *.ps1 scripts
|
||||
├── batch/ # *.bat scripts (CRLF)
|
||||
├── ci/ # sanity and lint checks used by autotest.py
|
||||
├── autotest.py # Every check, local and CI
|
||||
├── pyproject.toml # Package, version, script folders as package data
|
||||
├── README.md # Script catalog
|
||||
├── INSTALL.md # Install and development
|
||||
└── SPEC.md # Repository specification
|
||||
```
|
||||
|
||||
- Only `python/src/`, `bash/`, `powershell/`, and `batch/` are shipped in
|
||||
the wheel (under `daedalus/_library/`). A script anywhere else is not
|
||||
installed.
|
||||
- Tests under `*/tests/` are not packaged.
|
||||
|
||||
## 5. Integrating a Script
|
||||
|
||||
### 5.1 Inputs and Checklist
|
||||
|
||||
Before writing anything, know:
|
||||
|
||||
- The script: a file path, a paste, or a description of what to build.
|
||||
- The command name. Default to the file stem in `snake_case`. It must
|
||||
match `^[a-z][a-z0-9_-]*$` and not already be in `SCRIPTS`.
|
||||
- The type: Python, bash, PowerShell, or batch. Prefer Python when the
|
||||
script must run on both Windows and Linux.
|
||||
- A one-line description for `daedalus --list`.
|
||||
|
||||
Ask the user only when the name or the type cannot be inferred. Track the
|
||||
work with this checklist:
|
||||
|
||||
```text
|
||||
- [ ] File placed and runs on its own
|
||||
- [ ] Entry added to SCRIPTS in daedalus/registry.py
|
||||
- [ ] README row and usage section
|
||||
- [ ] Tests written and passing
|
||||
- [ ] version bumped in pyproject.toml
|
||||
- [ ] python autotest.py passes
|
||||
- [ ] daedalus <name> --help works
|
||||
```
|
||||
|
||||
### 5.2 Integration Contract
|
||||
|
||||
A script is integrated when all of these hold. Tests enforce the ones
|
||||
marked "test".
|
||||
|
||||
| Rule | Enforced by |
|
||||
| --- | --- |
|
||||
| File is in the folder for its type (daedalus agent rule 5.3) | Packaging test |
|
||||
| File runs on its own, without daedalus | Review |
|
||||
| One entry in `SCRIPTS` in `daedalus/registry.py` | Registry test |
|
||||
| Name matches `^[a-z][a-z0-9_-]*$` | Registry test |
|
||||
| `path` is repo-relative with forward slashes | Registry test |
|
||||
| `description` is one non-empty line | Registry test |
|
||||
| File suffix has a runner (`.py`, `.sh`, `.ps1`, `.bat`) | Registry test |
|
||||
| A row for the name in the README "Available scripts" table | Registry test |
|
||||
| Own tests for the script's logic | Review, coverage |
|
||||
| `version` in `pyproject.toml` bumped | Review |
|
||||
| `python autotest.py` passes | CI |
|
||||
|
||||
### 5.3 Choosing the Name and Type
|
||||
|
||||
| Type | Location | Runner |
|
||||
| --- | --- | --- |
|
||||
| Python | `python/src/<name>/<name>.py` | Current Python, `python/src` on `PYTHONPATH` |
|
||||
| bash | `bash/<name>.sh` | `DAEDALUS_BASH`, Git Bash, then `bash` |
|
||||
| PowerShell | `powershell/<name>.ps1` | `pwsh`, then `powershell` |
|
||||
| Batch | `batch/<name>.bat` | `cmd /c`, Windows only |
|
||||
|
||||
- Prefer Python for anything that must work on both Windows and Linux.
|
||||
- The command name, the file stem, and (for Python) the folder name are the
|
||||
same string.
|
||||
- Choose a name that says what the script does (`backup_configs`, not
|
||||
`tool1`). Check `daedalus --list` for clashes.
|
||||
|
||||
### 5.4 File Templates
|
||||
|
||||
| Type | Path |
|
||||
| --- | --- |
|
||||
| Python | `python/src/<name>/<name>.py` |
|
||||
| bash | `bash/<name>.sh` |
|
||||
| PowerShell | `powershell/<name>.ps1` |
|
||||
| Batch | `batch/<name>.bat` (CRLF, Windows only) |
|
||||
|
||||
Python template:
|
||||
|
||||
```python
|
||||
"""<One line: what the script does.>
|
||||
|
||||
Run via daedalus: ``daedalus <name> [args]`` (see daedalus README).
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import logging
|
||||
import sys
|
||||
|
||||
LOGGER = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def parse_args(argv: list[str] | None) -> argparse.Namespace:
|
||||
"""Parse <name> command-line arguments."""
|
||||
parser = argparse.ArgumentParser(prog="<name>", description=__doc__.splitlines()[0])
|
||||
parser.add_argument("-q", "--quiet", action="store_true", help="only log warnings and errors")
|
||||
return parser.parse_args(argv)
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
"""CLI entry point; return the exit code."""
|
||||
args = parse_args(argv)
|
||||
logging.basicConfig(level=logging.WARNING if args.quiet else logging.INFO,
|
||||
format="%(levelname)-5s %(message)s")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
```
|
||||
|
||||
- `prog="<name>"` makes `--help` show the daedalus command name.
|
||||
- Shared helpers go in their own package under `python/src/`; scripts
|
||||
import them directly because `python/src` is on `PYTHONPATH`.
|
||||
- Standard library only. Lazy `%` logging. Type hints in every docstring.
|
||||
|
||||
bash template:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# <One line: what the script does.>
|
||||
set -euo pipefail
|
||||
|
||||
usage() {
|
||||
echo "usage: <name> [-h] <args>"
|
||||
}
|
||||
|
||||
main() {
|
||||
if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
|
||||
usage
|
||||
return 0
|
||||
fi
|
||||
}
|
||||
|
||||
main "$@"
|
||||
```
|
||||
|
||||
Stage it executable: `git add --chmod=+x bash/<name>.sh`.
|
||||
|
||||
PowerShell template:
|
||||
|
||||
```powershell
|
||||
<#
|
||||
.SYNOPSIS
|
||||
<One line: what the script does.>
|
||||
#>
|
||||
param(
|
||||
[switch]$Quiet
|
||||
)
|
||||
$ErrorActionPreference = 'Stop'
|
||||
```
|
||||
|
||||
### 5.5 Register and Document
|
||||
|
||||
Add one entry to `SCRIPTS` in `daedalus/registry.py`, keeping keys
|
||||
sorted:
|
||||
|
||||
```python
|
||||
"<name>": Script(
|
||||
path="python/src/<name>/<name>.py",
|
||||
description="<one line, same as README>",
|
||||
),
|
||||
```
|
||||
|
||||
Do not edit `cli.py` or `runners.py`. The suffix picks the runner.
|
||||
|
||||
In `README.md`:
|
||||
|
||||
- Add a row to the "Available scripts" table, sorted by name:
|
||||
`` | `<name>` | Python | <description> | ``. The registry test looks
|
||||
for the exact text `` | `<name>` | ``.
|
||||
- When the script takes arguments, add a `### <name>` section after the
|
||||
table: what it does, example `daedalus <name> ...` calls in a `bash`
|
||||
block, and an argument table. Follow the existing sections, if any.
|
||||
|
||||
### 5.6 Tests
|
||||
|
||||
| Type | Test file | How |
|
||||
| --- | --- | --- |
|
||||
| Python | `python/tests/test_<name>.py` | `from <name> import <name>`, call functions and `main([...])` |
|
||||
| bash | `bash/tests/test_<name>.py` | `subprocess.run` with `runners.find_bash()`; skip when bash is missing |
|
||||
| PowerShell, batch | `python/tests/test_<name>.py` | `subprocess.run` via `runners.build_command`; skip when the interpreter or Windows is missing |
|
||||
|
||||
Cover the pure logic and `main` with argument lists. Use `tmp_path` for
|
||||
files and `monkeypatch` for environment variables. Tests must not need
|
||||
another machine, the network, or an interactive terminal.
|
||||
|
||||
Python test skeleton:
|
||||
|
||||
```python
|
||||
"""Tests for <name>.
|
||||
|
||||
<what the tests cover>.
|
||||
"""
|
||||
from <name> import <name>
|
||||
|
||||
|
||||
def test_main_returns_zero():
|
||||
"""Default run succeeds."""
|
||||
assert <name>.main([]) == 0
|
||||
```
|
||||
|
||||
Shell-out skeleton for bash:
|
||||
|
||||
```python
|
||||
"""Tests for bash/<name>.sh.
|
||||
|
||||
<what the tests cover>.
|
||||
"""
|
||||
import subprocess
|
||||
|
||||
import pytest
|
||||
|
||||
from daedalus import REPO_ROOT
|
||||
from daedalus import runners
|
||||
|
||||
SCRIPT = REPO_ROOT / "bash" / "<name>.sh"
|
||||
|
||||
|
||||
@pytest.fixture(name="bash")
|
||||
def fixture_bash() -> str:
|
||||
"""bash interpreter, or skip."""
|
||||
try:
|
||||
return runners.find_bash()
|
||||
except runners.RunnerError:
|
||||
pytest.skip("bash not available")
|
||||
|
||||
|
||||
def test_help(bash):
|
||||
"""--help exits 0 and prints usage."""
|
||||
result = subprocess.run([bash, str(SCRIPT), "--help"], capture_output=True, text=True, check=False)
|
||||
assert result.returncode == 0
|
||||
assert "usage" in result.stdout
|
||||
```
|
||||
|
||||
### 5.7 Importing an Existing Script
|
||||
|
||||
When the user brings a script from elsewhere (another repo, another
|
||||
machine, a paste):
|
||||
|
||||
- Keep its behavior. Restructure only as far as the contract needs: a
|
||||
`main(argv)` entry point for Python, no hard-coded absolute paths, no
|
||||
secrets.
|
||||
- Move hard-coded hosts, passwords, and paths to arguments or environment
|
||||
variables. Never commit credentials.
|
||||
- Split pure logic (parsing, formatting, computing) from I/O, so it can be
|
||||
tested without a terminal, the network, or a specific machine.
|
||||
- Mention the origin in the module docstring, not in a comment per line.
|
||||
|
||||
## 6. Code Conventions
|
||||
|
||||
### 6.1 All Files
|
||||
|
||||
- LF line endings everywhere except `*.bat`, which must be CRLF.
|
||||
`.gitattributes` enforces both on checkout.
|
||||
- Markdown lists use dashes. markdownlint runs with MD013 and MD033 off.
|
||||
- No file over 2 MB, no private keys.
|
||||
|
||||
### 6.2 Python
|
||||
|
||||
- Target Python 3.11. PEP 8 (pycodestyle with the repo ignore list).
|
||||
- Standard library imports use `import module`.
|
||||
- Logging uses lazy `%` formatting: `LOGGER.info("wrote %s", path)`.
|
||||
- Type hints and a docstring on every function.
|
||||
- No runtime dependencies outside the standard library. The wheel declares
|
||||
`dependencies = []`; a script that needs a package must say so in its
|
||||
`--help` and fail with a clear message when it is missing.
|
||||
|
||||
### 6.3 Shell, PowerShell, Batch
|
||||
|
||||
- bash scripts start with `#!/usr/bin/env bash` and `set -euo pipefail`,
|
||||
pass shellcheck, and are committed executable:
|
||||
`git add --chmod=+x bash/<name>.sh`.
|
||||
- PowerShell scripts declare a `param()` block and run under `pwsh` on
|
||||
Linux unless they are Windows-only by nature.
|
||||
- Batch scripts are Windows-only and CRLF.
|
||||
|
||||
## 7. Quality Gates
|
||||
|
||||
`python autotest.py` runs these checks in parallel:
|
||||
|
||||
| Check | Rule |
|
||||
| --- | --- |
|
||||
| `sanity` | Changed files: line endings, no private keys, under 2 MB |
|
||||
| `python_syntax` | Every `*.py` parses |
|
||||
| `pycodestyle` | PEP 8 with the repo ignore list |
|
||||
| `shellcheck` | Every shell script, including suffixless launchers |
|
||||
| `json`, `yaml` | Every file loads |
|
||||
| `markdown` | markdownlint |
|
||||
| `pytest` | All tests pass; coverage of `ci`, `daedalus`, `python/src` at least `MIN_COVERAGE_PERCENT` |
|
||||
|
||||
A failing check is reported to the user with its output. Never skip or
|
||||
disable a check to make a run pass.
|
||||
|
||||
## 8. Anti-Patterns
|
||||
|
||||
- A script outside `python/src/`, `bash/`, `powershell/`, or `batch/`.
|
||||
- Registry `path` with backslashes or an absolute path.
|
||||
- A runner chosen by anything other than the file suffix.
|
||||
- A script that only works through daedalus (imports from `daedalus`,
|
||||
reads `LIBRARY_ROOT`).
|
||||
- Tests that need another machine, the network, or an interactive terminal without a
|
||||
skip condition.
|
||||
- Editing `daedalus/cli.py` or `daedalus/runners.py` to add a script.
|
||||
Adding a script touches only the script, its tests, `registry.py`,
|
||||
`README.md`, and `pyproject.toml`.
|
||||
- Lowering `MIN_COVERAGE_PERCENT`.
|
||||
|
||||
## 9. Quick Reference
|
||||
|
||||
| Task | Action |
|
||||
| --- | --- |
|
||||
| Add or import a script | Follow [section 5](#5-integrating-a-script) (daedalus agent rule 5.1) |
|
||||
| Change CLI or runner behavior | Update [SPEC](./SPEC.md) first (daedalus agent rule 2.1) |
|
||||
| Register a script | One `Script(...)` entry in `daedalus/registry.py` |
|
||||
| Document a script | Row and usage section in [README](./README.md) |
|
||||
| Before finishing | `python autotest.py` |
|
||||
| Ship a change | Bump `version` in `pyproject.toml` |
|
||||
| Commit | Only when asked |
|
||||
@@ -0,0 +1,18 @@
|
||||
# Changelog
|
||||
|
||||
Notable changes are listed here. Release numbers match
|
||||
[`pyproject.toml`](./pyproject.toml). Newest entries are first.
|
||||
|
||||
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
|
||||
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
- Nothing yet.
|
||||
|
||||
## [0.0.0] - 2026-11-11
|
||||
|
||||
### Added in 0.0.0
|
||||
|
||||
- Empty template: CLI, CI, packaging, and script-integration guide with no
|
||||
registered scripts.
|
||||
+135
@@ -0,0 +1,135 @@
|
||||
# Installing and using daedalus
|
||||
|
||||
Python 3.11 or newer. This checkout is an **empty template** (no scripts in
|
||||
`SCRIPTS` yet). Once you add scripts, the installed `daedalus` command
|
||||
bundles every registered one and works from any directory.
|
||||
|
||||
- [Install](#install)
|
||||
- [Usage](#usage)
|
||||
- [Add a script](#add-a-script)
|
||||
- [Development](#development)
|
||||
|
||||
Back to the [script list](./README.md#available-scripts). Repository rules:
|
||||
[SPEC](./SPEC.md).
|
||||
|
||||
## Install
|
||||
|
||||
### With pipx (recommended)
|
||||
|
||||
[pipx](https://pipx.pypa.io/) installs daedalus into its own environment
|
||||
and puts the `daedalus` command on `PATH`.
|
||||
|
||||
Linux (Debian 12): paste once; open a new shell if `pipx` was just
|
||||
installed. Run the same block again to refresh from Git (`main`); do **not**
|
||||
use `pipx upgrade daedalus` for Git installs — it does not pull the repo.
|
||||
|
||||
```bash
|
||||
daedalus_pipx_install() {
|
||||
r="${1:-git+ssh://git@example.com/your-org/daedalus.git@main}"
|
||||
command -v pipx >/dev/null || sudo apt install -y pipx
|
||||
pipx ensurepath 2>/dev/null || pipx ensurepath --force
|
||||
if pipx list --short 2>/dev/null | grep -qE '^daedalus '; then
|
||||
pipx install --force "$r"
|
||||
else
|
||||
pipx install "$r"
|
||||
fi
|
||||
daedalus --version
|
||||
}; daedalus_pipx_install
|
||||
```
|
||||
|
||||
No SSH key on the Git host: `daedalus_pipx_install git+https://example.com/your-org/daedalus.git`
|
||||
|
||||
Windows (PowerShell):
|
||||
|
||||
```powershell
|
||||
python -m pip install --user pipx
|
||||
python -m pipx ensurepath # once; then open a new terminal
|
||||
pipx install git+ssh://git@example.com/your-org/daedalus.git
|
||||
```
|
||||
|
||||
Without an SSH key for the Git host, use
|
||||
`git+https://example.com/your-org/daedalus.git` instead.
|
||||
|
||||
### From a checkout
|
||||
|
||||
```bash
|
||||
git clone git@example.com:your-org/daedalus.git
|
||||
cd daedalus
|
||||
pipx install . # or, inside a virtual environment: pip install .
|
||||
```
|
||||
|
||||
On Debian 12, `pip install` into the system Python is blocked
|
||||
(externally managed environment). Use pipx or a virtual environment.
|
||||
|
||||
### Without installing
|
||||
|
||||
Linux: add to `~/.bashrc`, call `daedalus_checkout` (clone once,
|
||||
then `git pull --ff-only`).
|
||||
|
||||
```bash
|
||||
daedalus_checkout() {
|
||||
d="${1:-$HOME/daedalus}"
|
||||
[[ -d "$d/.git" ]] && git -C "$d" pull --ff-only \
|
||||
|| git clone git@example.com:your-org/daedalus.git "$d"
|
||||
export PATH="$d/bin:$PATH"
|
||||
}; daedalus_checkout
|
||||
```
|
||||
|
||||
Windows: add `<checkout>\bin` to `PATH` (`bin\daedalus.bat`).
|
||||
|
||||
### Check, upgrade, remove
|
||||
|
||||
```bash
|
||||
daedalus --version # confirm the install
|
||||
daedalus_pipx_install # reinstall from Git (same as first paste block)
|
||||
pipx uninstall daedalus
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
daedalus --help # usage
|
||||
daedalus --list # list the available scripts
|
||||
daedalus NAME [args...] # run a script; every argument after NAME goes to it
|
||||
daedalus --path NAME # print where the script file is
|
||||
daedalus --version # print the installed version
|
||||
```
|
||||
|
||||
- `daedalus NAME --help` shows the help of the script, not of daedalus.
|
||||
- The exit code is the script's exit code. daedalus's own errors, such as
|
||||
an unknown name, exit with 2 and suggest close matches.
|
||||
|
||||
## Add a script
|
||||
|
||||
- Put the file in the folder for its type:
|
||||
| Type | Folder |
|
||||
| --- | --- |
|
||||
| Python | `python/src/<name>/<name>.py` |
|
||||
| bash | `bash/<name>.sh` |
|
||||
| PowerShell | `powershell/<name>.ps1` |
|
||||
| Batch | `batch/<name>.bat` (CRLF line endings, Windows only) |
|
||||
- Register it in `SCRIPTS` in `daedalus/registry.py`.
|
||||
- Add a row to the [Available scripts](./README.md#available-scripts)
|
||||
table in `README.md`. A test fails when a registered script is missing
|
||||
from that table.
|
||||
- Add tests under `python/tests/` or `bash/tests/`.
|
||||
- Bump `version` in `pyproject.toml`, then run `daedalus_pipx_install`
|
||||
(or `pipx install --force` from the Git URL) so pipx picks up the change.
|
||||
- Run `python autotest.py`.
|
||||
|
||||
Details: [SPEC section 6](./SPEC.md#6-adding-a-script).
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
|
||||
python -m pip install -r requirements.txt
|
||||
pip install -e . # daedalus command runs the checkout
|
||||
python autotest.py # every check; CI runs the same
|
||||
python autotest.py pytest # only some checks
|
||||
```
|
||||
|
||||
`autotest.py` runs sanity (line endings, private keys, file size),
|
||||
Python syntax, pycodestyle, shellcheck, JSON, YAML, markdown lint, and
|
||||
pytest with coverage.
|
||||
@@ -0,0 +1,33 @@
|
||||
# daedalus (template)
|
||||
|
||||
Starter repository for daedalus:
|
||||
one CLI, many small scripts, each with tests.
|
||||
|
||||
```bash
|
||||
daedalus <name> [args...]
|
||||
```
|
||||
|
||||
**[Install, usage, and development](./INSTALL.md)** ·
|
||||
[SPEC](./SPEC.md) (how the repo is maintained) ·
|
||||
[CHANGELOG](./CHANGELOG.md)
|
||||
|
||||
## Available scripts
|
||||
|
||||
| Script | Type | What it does |
|
||||
| --- | --- | --- |
|
||||
| *(none yet)* | — | Add scripts per [AGENTS section 5](./AGENTS.md#5-integrating-a-script) or [SPEC section 6](./SPEC.md#6-adding-a-script). |
|
||||
|
||||
`daedalus --list` prints every registered name for the version you have
|
||||
installed.
|
||||
|
||||
## Getting started
|
||||
|
||||
1. Clone or copy this template and name the Git remote for your team.
|
||||
2. Add a script under `python/src/`, `bash/`, `powershell/`, or `batch/`
|
||||
(see [SPEC layout](./SPEC.md#2-layout)).
|
||||
3. Register it in `daedalus/registry.py`, add a row to the table above,
|
||||
write tests, bump `version` in `pyproject.toml`, and run
|
||||
`python autotest.py`.
|
||||
|
||||
Until the registry has at least one script, `daedalus --list` prints an
|
||||
empty catalog and unknown names exit with code 2.
|
||||
@@ -0,0 +1,227 @@
|
||||
# daedalus specification
|
||||
|
||||
How this repository is laid out, how scripts are registered and run, and
|
||||
the rules for maintaining it. Change this file first when the behavior
|
||||
changes, then change the code and tests to match.
|
||||
|
||||
- [1. Purpose](#1-purpose)
|
||||
- [2. Layout](#2-layout)
|
||||
- [3. Command line](#3-command-line)
|
||||
- [4. Registry](#4-registry)
|
||||
- [5. Runners](#5-runners)
|
||||
- [6. Adding a script](#6-adding-a-script)
|
||||
- [7. Quality gates](#7-quality-gates)
|
||||
- [8. Conventions](#8-conventions)
|
||||
- [9. Packaging](#9-packaging)
|
||||
- [10. Implementation plan](#10-implementation-plan)
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This repository is an **empty template**: the CLI and quality gates are
|
||||
ready; add scripts per section 6. A filled checkout keeps loose scripts in
|
||||
one repository, each with tests, and runs any of them through one command:
|
||||
|
||||
```text
|
||||
daedalus <name> [args...]
|
||||
```
|
||||
|
||||
The same checkout is used on a Windows workstation and on a Linux host.
|
||||
|
||||
## 2. Layout
|
||||
|
||||
```text
|
||||
daedalus/
|
||||
├── bin/
|
||||
│ ├── daedalus # Linux launcher (bash), no install needed
|
||||
│ └── daedalus.bat # Windows launcher (cmd / PowerShell)
|
||||
├── daedalus/ # The CLI package
|
||||
│ ├── __main__.py # python -m daedalus
|
||||
│ ├── cli.py # Argument handling, list, path, dispatch
|
||||
│ ├── registry.py # SCRIPTS: name -> Script
|
||||
│ ├── runners.py # Suffix -> interpreter command
|
||||
│ └── tests/
|
||||
├── python/
|
||||
│ ├── src/<name>/ # Python scripts, one folder per script
|
||||
│ └── tests/ # pytest tests for python/src
|
||||
├── bash/ # *.sh scripts
|
||||
│ └── tests/ # pytest tests that run them
|
||||
├── powershell/ # *.ps1 scripts
|
||||
├── batch/ # *.bat scripts
|
||||
├── ci/ # Sanity, syntax, and lint checks, with tests
|
||||
├── autotest.py # Runs every check (local and CI)
|
||||
├── README.md # Script catalog (user-facing)
|
||||
├── INSTALL.md # Install, usage, development
|
||||
└── SPEC.md # This file
|
||||
```
|
||||
|
||||
## 3. Command line
|
||||
|
||||
| Call | Result | Exit code |
|
||||
| --- | --- | --- |
|
||||
| `daedalus <name> [args...]` | Runs the registered script with `args` passed through unchanged | The script's exit code |
|
||||
| `daedalus`, `daedalus -l`, `daedalus --list` | Prints every registered name, its type, and description | 0 |
|
||||
| `daedalus -h`, `daedalus --help` | Prints usage | 0 |
|
||||
| `daedalus --path <name>` | Prints the absolute path of the script | 0 |
|
||||
| `daedalus --version` | Prints the installed version, or `project.version` from `pyproject.toml` in a checkout | 0 |
|
||||
| Unknown name | Prints an error and close matches to stderr | 2 |
|
||||
| Script file missing, or no interpreter found | Prints the reason to stderr | 2 |
|
||||
|
||||
- Everything after `<name>` belongs to the script, including `--help`:
|
||||
`daedalus my_tool --help` shows the help of `my_tool`.
|
||||
- The script runs in the caller's current directory, with the caller's
|
||||
stdin, stdout, and stderr, so interactive scripts work.
|
||||
- Ctrl+C reaches the script. daedalus waits for it to exit and returns its
|
||||
exit code.
|
||||
|
||||
Ways to run the CLI:
|
||||
|
||||
- Install it with pip (section 9). `daedalus` is then on `PATH`
|
||||
everywhere, with every registered script bundled.
|
||||
- `bin/daedalus` (Linux) or `bin\daedalus.bat` (Windows). Add `bin/` to
|
||||
`PATH` to call plain `daedalus`. Needs no install.
|
||||
- `python -m daedalus` from the repository root.
|
||||
|
||||
## 4. Registry
|
||||
|
||||
`daedalus/registry.py` holds one dictionary:
|
||||
|
||||
```python
|
||||
SCRIPTS: dict[str, Script] = {
|
||||
"my_tool": Script(
|
||||
path="python/src/my_tool/my_tool.py",
|
||||
description="One-line summary for daedalus --list",
|
||||
),
|
||||
}
|
||||
```
|
||||
|
||||
In this template checkout, `SCRIPTS` is empty until you add the first
|
||||
script.
|
||||
|
||||
- `Script` is a frozen dataclass with `path` (repo-relative, forward
|
||||
slashes) and `description` (one line).
|
||||
- The key is the command name: lowercase letters, digits, `_`, and `-`,
|
||||
starting with a letter.
|
||||
- Names that start with `-` are reserved for daedalus options.
|
||||
- The runner is chosen from the suffix of `path`. No other field selects it.
|
||||
- Tests enforce, for every entry: the name is valid, the file exists, the
|
||||
suffix has a runner, and the description is not empty.
|
||||
|
||||
## 5. Runners
|
||||
|
||||
| Suffix | Command | Platforms |
|
||||
| --- | --- | --- |
|
||||
| `.py` | `<python> <path> args...` (`DAEDALUS_PYTHON` or daedalus's interpreter) | All |
|
||||
| `.sh` | `<bash> <path> args...` | All with bash |
|
||||
| `.ps1` | `<pwsh or powershell> -NoProfile -ExecutionPolicy Bypass -File <path> args...` | All with PowerShell |
|
||||
| `.bat` | `cmd /c <path> args...` | Windows only |
|
||||
|
||||
- Python scripts get `python/src` prepended to `PYTHONPATH`, so they can
|
||||
import shared modules from there.
|
||||
- Set `DAEDALUS_PYTHON` to a virtual-environment interpreter when a
|
||||
script needs packages that are not in the pipx venv.
|
||||
- bash lookup order: `DAEDALUS_BASH`, then Git Bash next to `git` on
|
||||
Windows (`<git root>/bin/bash.exe`), then `bash` on `PATH`. On Windows,
|
||||
`bash` on `PATH` is often the WSL launcher, which cannot open Windows
|
||||
paths, so Git Bash comes first.
|
||||
- PowerShell lookup order: `pwsh`, then `powershell`.
|
||||
- A missing interpreter or a `.bat` on a non-Windows host is an error with a
|
||||
clear message (exit code 2), never a silent skip.
|
||||
|
||||
## 6. Adding a script
|
||||
|
||||
- Put the file in the folder for its type (section 2). A Python script gets
|
||||
its own folder: `python/src/<name>/<name>.py`.
|
||||
- The script must run on its own (`python python/src/<name>/<name>.py`)
|
||||
without daedalus. Python scripts expose `main(argv: list[str] | None)`
|
||||
and end with `if __name__ == "__main__": sys.exit(main())`.
|
||||
- Add one entry to `SCRIPTS` in `daedalus/registry.py`.
|
||||
- Add a row to the "Available scripts" table in `README.md`, and a short
|
||||
section with usage when the script takes arguments. A test fails when a
|
||||
registered name has no row.
|
||||
- Add tests:
|
||||
- Python: `python/tests/test_<name>.py`, importing with
|
||||
`from <name> import <name>`.
|
||||
- bash: `bash/tests/test_<name>.py`, running the script with
|
||||
`subprocess` and skipping when bash is missing.
|
||||
- PowerShell and batch: a test under `python/tests/` that runs the
|
||||
script, skipped when the interpreter or Windows is missing.
|
||||
- Run `python autotest.py`. It must pass before pushing.
|
||||
|
||||
## 7. Quality gates
|
||||
|
||||
`python autotest.py` runs every check; CI runs the same command.
|
||||
|
||||
| Check | Rule |
|
||||
| --- | --- |
|
||||
| `sanity` | Changed files: line endings (section 8), no private keys, under 2 MB |
|
||||
| `python_syntax` | Every `*.py` parses |
|
||||
| `pycodestyle` | PEP 8 with the repository's ignore list (`PYCODESTYLE_IGNORE` in `ci/checks.py`) |
|
||||
| `shellcheck` | Every `*.sh`, `*.bash`, and suffixless file with a shell shebang |
|
||||
| `json`, `yaml` | Every file loads |
|
||||
| `markdown` | markdownlint, MD013 and MD033 disabled |
|
||||
| `pytest` | All tests pass; coverage of `ci`, `daedalus`, and `python/src` at least `MIN_COVERAGE_PERCENT` |
|
||||
|
||||
## 8. Conventions
|
||||
|
||||
- Line endings are LF everywhere except `*.bat`, which must be CRLF:
|
||||
cmd.exe mishandles labels and `goto` in LF-only batch files.
|
||||
`.gitattributes` enforces both on checkout.
|
||||
- Python targets 3.11. Standard library imports use `import module`.
|
||||
Logging uses lazy `%` formatting.
|
||||
- Markdown lists use dashes.
|
||||
- `bin/daedalus` and every `*.sh` are committed executable:
|
||||
`git add --chmod=+x <file>`.
|
||||
- `MIN_COVERAGE_PERCENT` in `autotest.py` only goes up. Raise it when
|
||||
tests are added.
|
||||
|
||||
## 9. Packaging
|
||||
|
||||
`pyproject.toml` builds one wheel that holds the CLI and every script.
|
||||
|
||||
| Command | Use |
|
||||
| --- | --- |
|
||||
| `pipx install git+ssh://git@example.com/your-org/daedalus.git` | Own isolated environment, `daedalus` on `PATH` (recommended; works on Debian 12, where plain `pip install` is blocked) |
|
||||
| `pip install --user .` | From a checkout, into the user site |
|
||||
| `pip install -e .` | Development: the installed command runs the scripts in the checkout |
|
||||
| `pipx upgrade daedalus` / `pip install --upgrade .` | Pick up new scripts |
|
||||
|
||||
The script folders are copied into the wheel under
|
||||
`daedalus/_library/`, with the same relative paths as in the repository:
|
||||
|
||||
| Repository folder | Installed folder | Files |
|
||||
| --- | --- | --- |
|
||||
| `python/src/` | `daedalus/_library/python/src/` | Everything except `__pycache__` and `*.pyc` |
|
||||
| `bash/` | `daedalus/_library/bash/` | `*.sh` |
|
||||
| `powershell/` | `daedalus/_library/powershell/` | `*.ps1` |
|
||||
| `batch/` | `daedalus/_library/batch/` | `*.bat` |
|
||||
|
||||
- `LIBRARY_ROOT` in `daedalus/__init__.py` is `daedalus/_library` when
|
||||
that folder exists (a normal install), otherwise the repository root (a
|
||||
checkout or an editable install). Registry paths resolve against it, so
|
||||
`SCRIPTS` entries are the same in both cases.
|
||||
- Tests under `*/tests/` are not packaged.
|
||||
- The CLI has no runtime dependencies. Test and lint tools stay in
|
||||
`requirements.txt`.
|
||||
- A test builds the wheel and fails when any registered script is missing
|
||||
from it.
|
||||
- Bump `version` in `pyproject.toml` when scripts or the CLI change, so
|
||||
`pipx upgrade` picks them up.
|
||||
|
||||
## 10. Implementation plan
|
||||
|
||||
| Step | Work | Status |
|
||||
| --- | --- | --- |
|
||||
| 1 | This SPEC | Done |
|
||||
| 2 | `daedalus/registry.py` with `Script` and `SCRIPTS` (empty in template) | Done |
|
||||
| 3 | `daedalus/runners.py`: suffix table, interpreter lookup, `build_command`, `run` | Done |
|
||||
| 4 | `daedalus/cli.py` and `__main__.py`: list, help, `--path`, dispatch, close-match errors | Done |
|
||||
| 5 | `bin/daedalus`, `bin/daedalus.bat`, `[project.scripts]` in `pyproject.toml` | Done |
|
||||
| 6 | Tests: registry consistency, every runner, CLI paths, launchers | Done |
|
||||
| 7 | Per-script tests under `python/tests/` or `bash/tests/` when scripts exist | Template |
|
||||
| 8 | CI: CRLF rule for `*.bat`, shellcheck on suffixless shell files, `daedalus` in coverage | Done |
|
||||
| 9 | README: how to call `daedalus` | Done |
|
||||
| 10 | `pyproject.toml`: map the script folders into `daedalus/_library` as package data | Done |
|
||||
| 11 | `LIBRARY_ROOT` in `daedalus/__init__.py`; registry and runners resolve against it | Done |
|
||||
| 12 | `daedalus --version` | Done |
|
||||
| 13 | Tests: `LIBRARY_ROOT` selection, wheel contains every registered script, installed CLI | Done |
|
||||
| 14 | README: install with pipx or pip | Done |
|
||||
+90
@@ -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))
|
||||
Executable
+6
@@ -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 "$@"
|
||||
@@ -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%
|
||||
@@ -0,0 +1,4 @@
|
||||
"""CI checks for daedalus.
|
||||
|
||||
Package for the sanity, syntax, and lint checks.
|
||||
"""
|
||||
+150
@@ -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
|
||||
@@ -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())
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -0,0 +1,17 @@
|
||||
"""daedalus: run any registered script with ``daedalus <name> [args...]``.
|
||||
|
||||
CLI package; see SPEC.md.
|
||||
"""
|
||||
import pathlib
|
||||
|
||||
PACKAGE_DIR = pathlib.Path(__file__).resolve().parent
|
||||
REPO_ROOT = PACKAGE_DIR.parent
|
||||
|
||||
|
||||
def library_root(package_dir: pathlib.Path = PACKAGE_DIR) -> pathlib.Path:
|
||||
"""Bundled _library of an installed wheel, else the checkout root."""
|
||||
installed = package_dir / "_library"
|
||||
return installed if installed.is_dir() else package_dir.parent
|
||||
|
||||
|
||||
LIBRARY_ROOT = library_root()
|
||||
@@ -0,0 +1,9 @@
|
||||
"""Allow ``python -m daedalus``.
|
||||
|
||||
Module entry point.
|
||||
"""
|
||||
import sys
|
||||
|
||||
from daedalus import cli
|
||||
|
||||
sys.exit(cli.main())
|
||||
@@ -0,0 +1,87 @@
|
||||
"""daedalus command line: list, locate, and run registered scripts.
|
||||
|
||||
Entry point for ``daedalus <name> [args...]``; see SPEC.md section 3.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import difflib
|
||||
import importlib.metadata
|
||||
import sys
|
||||
import tomllib
|
||||
|
||||
from daedalus import REPO_ROOT
|
||||
from daedalus import registry
|
||||
from daedalus import runners
|
||||
|
||||
USAGE = """usage: daedalus <name> [args...] run a script; args go to the script
|
||||
daedalus [-l | --list] list registered scripts
|
||||
daedalus --path <name> print the path of a script
|
||||
daedalus --version print the installed version
|
||||
daedalus -h | --help show this help"""
|
||||
|
||||
|
||||
class UsageError(Exception):
|
||||
"""Bad daedalus arguments or an unknown script name."""
|
||||
|
||||
|
||||
def format_list(scripts: dict[str, registry.Script]) -> str:
|
||||
"""One aligned line per script: name, type, description."""
|
||||
width = max((len(name) for name in scripts), default=0)
|
||||
return "\n".join(
|
||||
f"{name:<{width}} {script.absolute_path.suffix.lstrip('.'):<3} {script.description}"
|
||||
for name, script in sorted(scripts.items())
|
||||
)
|
||||
|
||||
|
||||
def version() -> str:
|
||||
"""Installed metadata, else version from checkout pyproject.toml."""
|
||||
try:
|
||||
return importlib.metadata.version("daedalus")
|
||||
except importlib.metadata.PackageNotFoundError:
|
||||
pyproject = REPO_ROOT / "pyproject.toml"
|
||||
if pyproject.is_file():
|
||||
project = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("project", {})
|
||||
checkout_version = project.get("version")
|
||||
if isinstance(checkout_version, str) and checkout_version:
|
||||
return checkout_version
|
||||
return "unknown"
|
||||
|
||||
|
||||
def lookup(name: str) -> registry.Script:
|
||||
"""Registered script by name; UsageError with close matches otherwise."""
|
||||
script = registry.SCRIPTS.get(name)
|
||||
if script is not None:
|
||||
return script
|
||||
matches = difflib.get_close_matches(name, registry.SCRIPTS, n=3)
|
||||
hint = f"did you mean: {', '.join(matches)}" if matches else "run 'daedalus --list'"
|
||||
raise UsageError(f"unknown script {name!r}; {hint}")
|
||||
|
||||
|
||||
def dispatch(argv: list[str]) -> int:
|
||||
"""Handle daedalus options, or run the named script with the rest of argv."""
|
||||
if not argv or argv[0] in ("-l", "--list"):
|
||||
print(format_list(registry.SCRIPTS))
|
||||
return 0
|
||||
if argv[0] in ("-h", "--help"):
|
||||
print(USAGE)
|
||||
return 0
|
||||
if argv[0] == "--version":
|
||||
print(f"daedalus {version()}")
|
||||
return 0
|
||||
if argv[0] == "--path":
|
||||
if len(argv) != 2:
|
||||
raise UsageError("usage: daedalus --path <name>")
|
||||
print(lookup(argv[1]).absolute_path)
|
||||
return 0
|
||||
if argv[0].startswith("-"):
|
||||
raise UsageError(f"unknown option {argv[0]!r}; run 'daedalus --help'")
|
||||
return runners.run(lookup(argv[0]).absolute_path, argv[1:])
|
||||
|
||||
|
||||
def main(argv: list[str] | None = None) -> int:
|
||||
"""CLI entry point; daedalus errors exit with 2."""
|
||||
try:
|
||||
return dispatch(sys.argv[1:] if argv is None else argv)
|
||||
except (UsageError, runners.RunnerError) as error:
|
||||
print(f"daedalus: {error}", file=sys.stderr)
|
||||
return 2
|
||||
@@ -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] = {}
|
||||
@@ -0,0 +1,119 @@
|
||||
"""Build and run the interpreter command for a script file.
|
||||
|
||||
Suffix to interpreter table for py, sh, ps1, and bat; see SPEC.md section 5.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import pathlib
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
from daedalus import LIBRARY_ROOT
|
||||
|
||||
PYTHON_SRC = LIBRARY_ROOT / "python" / "src"
|
||||
|
||||
|
||||
class RunnerError(RuntimeError):
|
||||
"""A script cannot start: missing file, interpreter, or platform."""
|
||||
|
||||
|
||||
def is_windows() -> bool:
|
||||
"""True on Windows."""
|
||||
return os.name == "nt"
|
||||
|
||||
|
||||
def find_bash() -> str:
|
||||
"""DAEDALUS_BASH, then Git Bash on Windows, then bash on PATH."""
|
||||
override = os.environ.get("DAEDALUS_BASH")
|
||||
if override:
|
||||
return override
|
||||
if is_windows():
|
||||
git = shutil.which("git")
|
||||
if git is not None:
|
||||
# <git root>/cmd/git.exe -> <git root>/bin/bash.exe; PATH bash is often the WSL launcher.
|
||||
git_bash = pathlib.Path(git).resolve().parent.parent / "bin" / "bash.exe"
|
||||
if git_bash.is_file():
|
||||
return str(git_bash)
|
||||
bash = shutil.which("bash")
|
||||
if bash is None:
|
||||
raise RunnerError("bash not found; install it or set DAEDALUS_BASH")
|
||||
return bash
|
||||
|
||||
|
||||
def find_powershell() -> str:
|
||||
"""pwsh, then Windows PowerShell."""
|
||||
for name in ("pwsh", "powershell"):
|
||||
found = shutil.which(name)
|
||||
if found is not None:
|
||||
return found
|
||||
raise RunnerError("PowerShell not found; install pwsh")
|
||||
|
||||
|
||||
def python_executable() -> str:
|
||||
"""Return DAEDALUS_PYTHON when set, else the interpreter running daedalus.
|
||||
|
||||
DAEDALUS_PYTHON can point at a venv with packages the pipx environment lacks.
|
||||
"""
|
||||
override = os.environ.get("DAEDALUS_PYTHON")
|
||||
if override:
|
||||
return override
|
||||
return sys.executable
|
||||
|
||||
|
||||
def python_command(path: pathlib.Path) -> list[str]:
|
||||
"""Run a .py file with python_executable()."""
|
||||
return [python_executable(), str(path)]
|
||||
|
||||
|
||||
def bash_command(path: pathlib.Path) -> list[str]:
|
||||
"""Run a .sh file with bash."""
|
||||
return [find_bash(), str(path)]
|
||||
|
||||
|
||||
def powershell_command(path: pathlib.Path) -> list[str]:
|
||||
"""Run a .ps1 file without the user profile or execution policy prompts."""
|
||||
return [find_powershell(), "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(path)]
|
||||
|
||||
|
||||
def batch_command(path: pathlib.Path) -> list[str]:
|
||||
"""Run a .bat file with cmd; Windows only."""
|
||||
if not is_windows():
|
||||
raise RunnerError(f"{path.name}: .bat scripts run on Windows only")
|
||||
return [os.environ.get("COMSPEC", "cmd.exe"), "/c", str(path)]
|
||||
|
||||
|
||||
RUNNERS = {
|
||||
".py": python_command,
|
||||
".sh": bash_command,
|
||||
".ps1": powershell_command,
|
||||
".bat": batch_command,
|
||||
}
|
||||
|
||||
|
||||
def build_command(path: pathlib.Path, args: list[str]) -> list[str]:
|
||||
"""Full command line for a script and its arguments."""
|
||||
runner = RUNNERS.get(path.suffix.lower())
|
||||
if runner is None:
|
||||
raise RunnerError(f"unsupported script type {path.suffix!r}: {path}")
|
||||
if not path.is_file():
|
||||
raise RunnerError(f"script not found: {path}")
|
||||
return [*runner(path), *args]
|
||||
|
||||
|
||||
def script_env() -> dict[str, str]:
|
||||
"""Caller environment with python/src prepended to PYTHONPATH."""
|
||||
env = dict(os.environ)
|
||||
env["PYTHONPATH"] = os.pathsep.join(filter(None, [str(PYTHON_SRC), env.get("PYTHONPATH")]))
|
||||
return env
|
||||
|
||||
|
||||
def run(path: pathlib.Path, args: list[str]) -> int:
|
||||
"""Run the script attached to this terminal and return its exit code."""
|
||||
process = subprocess.Popen(build_command(path, args), env=script_env())
|
||||
try:
|
||||
return process.wait()
|
||||
except KeyboardInterrupt:
|
||||
# Ctrl+C also reaches the child; let it finish its own cleanup.
|
||||
return process.wait()
|
||||
@@ -0,0 +1,125 @@
|
||||
"""Tests for daedalus.cli and the launchers.
|
||||
|
||||
Options, errors, dispatch, and end-to-end runs (SPEC.md section 3).
|
||||
"""
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
|
||||
import pytest
|
||||
|
||||
from daedalus import LIBRARY_ROOT
|
||||
from daedalus import REPO_ROOT
|
||||
from daedalus import cli
|
||||
from daedalus import registry
|
||||
from daedalus import runners
|
||||
|
||||
FAKE_SCRIPTS = {
|
||||
"alpha": registry.Script("python/src/alpha/alpha.py", "First tool"),
|
||||
"beta_tool": registry.Script("bash/beta_tool.sh", "Second tool"),
|
||||
}
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def fake_registry(monkeypatch):
|
||||
"""Replace SCRIPTS with a fixed two-entry registry."""
|
||||
monkeypatch.setattr(registry, "SCRIPTS", FAKE_SCRIPTS)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("argv", [[], ["-l"], ["--list"]])
|
||||
def test_list(fake_registry, capsys, argv):
|
||||
"""No arguments or --list prints name, type, and description."""
|
||||
assert cli.main(argv) == 0
|
||||
assert capsys.readouterr().out.splitlines() == [
|
||||
"alpha py First tool",
|
||||
"beta_tool sh Second tool",
|
||||
]
|
||||
|
||||
|
||||
@pytest.mark.parametrize("argv", [["-h"], ["--help"]])
|
||||
def test_help(capsys, argv):
|
||||
"""--help prints usage."""
|
||||
assert cli.main(argv) == 0
|
||||
assert capsys.readouterr().out.startswith("usage: daedalus <name>")
|
||||
|
||||
|
||||
def test_path(fake_registry, capsys):
|
||||
"""--path prints the absolute script path."""
|
||||
assert cli.main(["--path", "alpha"]) == 0
|
||||
assert capsys.readouterr().out.strip() == str(LIBRARY_ROOT / "python/src/alpha/alpha.py")
|
||||
|
||||
|
||||
@pytest.mark.parametrize("installed, expected", [(True, "daedalus 1.2.3"), (False, "daedalus 0.0.0")])
|
||||
def test_version(monkeypatch, capsys, installed, expected):
|
||||
"""--version uses metadata or pyproject.toml in a checkout."""
|
||||
def fake_version(_name):
|
||||
if not installed:
|
||||
raise cli.importlib.metadata.PackageNotFoundError(_name)
|
||||
return "1.2.3"
|
||||
|
||||
monkeypatch.setattr(cli.importlib.metadata, "version", fake_version)
|
||||
assert cli.main(["--version"]) == 0
|
||||
assert capsys.readouterr().out.strip() == expected
|
||||
|
||||
|
||||
@pytest.mark.parametrize("argv, message", [
|
||||
(["--path"], "usage: daedalus --path"),
|
||||
(["--bogus"], "unknown option '--bogus'"),
|
||||
(["alpah"], "unknown script 'alpah'; did you mean: alpha"),
|
||||
(["zzz"], "unknown script 'zzz'; run 'daedalus --list'"),
|
||||
])
|
||||
def test_usage_errors_exit_2(fake_registry, capsys, argv, message):
|
||||
"""Bad options and unknown names exit 2 with a message on stderr."""
|
||||
assert cli.main(argv) == 2
|
||||
assert message in capsys.readouterr().err
|
||||
|
||||
|
||||
def test_dispatch_passes_args_through(fake_registry, monkeypatch):
|
||||
"""Everything after the name, including --help, goes to the script."""
|
||||
calls = []
|
||||
monkeypatch.setattr(runners, "run", lambda path, args: calls.append((path, args)) or 7)
|
||||
assert cli.main(["alpha", "--help", "x"]) == 7
|
||||
assert calls == [(LIBRARY_ROOT / "python/src/alpha/alpha.py", ["--help", "x"])]
|
||||
|
||||
|
||||
def test_runner_error_exits_2(fake_registry, capsys):
|
||||
"""A missing script file exits 2 instead of a traceback."""
|
||||
assert cli.main(["alpha"]) == 2
|
||||
assert "script not found" in capsys.readouterr().err
|
||||
|
||||
|
||||
def test_main_reads_sys_argv(fake_registry, monkeypatch, capsys):
|
||||
"""Without argv, main uses sys.argv."""
|
||||
monkeypatch.setattr(sys, "argv", ["daedalus", "--list"])
|
||||
assert cli.main() == 0
|
||||
assert "alpha" in capsys.readouterr().out
|
||||
|
||||
|
||||
def run_cli(*command: str) -> subprocess.CompletedProcess:
|
||||
"""Run a daedalus command from a directory outside the repo."""
|
||||
env = {**os.environ, "PYTHONPATH": str(REPO_ROOT)}
|
||||
return subprocess.run(command, capture_output=True, text=True, check=False,
|
||||
cwd=REPO_ROOT.parent, env=env)
|
||||
|
||||
|
||||
def test_module_runs_list():
|
||||
"""python -m daedalus --list runs with an empty registry."""
|
||||
result = run_cli(sys.executable, "-m", "daedalus", "--list")
|
||||
assert result.returncode == 0, result.stderr
|
||||
assert result.stdout.strip() == ""
|
||||
|
||||
|
||||
@pytest.mark.skipif(os.name != "nt", reason="cmd.exe is Windows only")
|
||||
def test_bat_launcher():
|
||||
"""bin/daedalus.bat runs the CLI and passes the exit code."""
|
||||
launcher = str(REPO_ROOT / "bin" / "daedalus.bat")
|
||||
assert run_cli(launcher, "--list").returncode == 0
|
||||
assert run_cli(launcher, "no_such_script").returncode == 2
|
||||
|
||||
|
||||
@pytest.mark.skipif(os.name == "nt", reason="bash launcher is for Linux")
|
||||
def test_bash_launcher():
|
||||
"""bin/daedalus runs the CLI and passes the exit code."""
|
||||
launcher = str(REPO_ROOT / "bin" / "daedalus")
|
||||
assert run_cli("bash", launcher, "--list").returncode == 0
|
||||
assert run_cli("bash", launcher, "no_such_script").returncode == 2
|
||||
@@ -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"
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -0,0 +1,47 @@
|
||||
[build-system]
|
||||
requires = ["setuptools>=68"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "daedalus"
|
||||
version = "0.0.0"
|
||||
description = "Template for daedalus: loose scripts in one repo, run with: daedalus <name> [args...]"
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.11"
|
||||
dependencies = []
|
||||
|
||||
[project.scripts]
|
||||
daedalus = "daedalus.cli:main"
|
||||
|
||||
# The script folders are installed under daedalus/_library/ with their
|
||||
# repository-relative paths, so registry paths resolve the same way (SPEC.md 9).
|
||||
[tool.setuptools]
|
||||
packages = [
|
||||
"daedalus",
|
||||
"daedalus._library.python.src",
|
||||
"daedalus._library.bash",
|
||||
"daedalus._library.powershell",
|
||||
"daedalus._library.batch",
|
||||
]
|
||||
|
||||
[tool.setuptools.package-dir]
|
||||
"daedalus._library.python.src" = "python/src"
|
||||
"daedalus._library.bash" = "bash"
|
||||
"daedalus._library.powershell" = "powershell"
|
||||
"daedalus._library.batch" = "batch"
|
||||
|
||||
[tool.setuptools.package-data]
|
||||
"daedalus._library.python.src" = ["**/*"]
|
||||
"daedalus._library.bash" = ["*.sh"]
|
||||
"daedalus._library.powershell" = ["*.ps1"]
|
||||
"daedalus._library.batch" = ["*.bat"]
|
||||
|
||||
[tool.setuptools.exclude-package-data]
|
||||
"*" = ["*.pyc", "__pycache__/*", "**/__pycache__/*", ".gitkeep"]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["ci/tests", "daedalus/tests", "python/tests", "bash/tests"]
|
||||
pythonpath = [".", "python/src"]
|
||||
|
||||
[tool.coverage.run]
|
||||
omit = ["*/tests/*", "*/__main__.py"]
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user