daedalus 0.4.0: bash script interface (help() dispatch) + hello_bash

- bash/daedalus_common.sh (new): the shared interface for bash scripts
  (SPEC item 6.10) - a script sources its sibling helper, defines help()
  (usage) and main(), and ends with daedalus_bash_dispatch "$@" which
  routes help/-h/--help to help() and everything else to main()
  unchanged (clear fallback errors when a script forgets either)
- completion for bash scripts (SPEC item 3.13.5.2): after a completed
  script name daedalus offers --help, -h, help, prefix-filtered, written
  itself on the fd-8 argcomplete protocol - no script runs on TAB;
  scripts without the interface get the shell default
- bash/hello_bash.sh (new, category test): sample script through the
  interface, the bash twin of hello, with tests; registry entry, README
  row, CHANGELOG bullet
- tests: bash/tests/test_bash_interface.py (helper behavior, bash -n,
  enforcement of the interface for every registered .sh),
  test_hello_bash.py (direct and daedalus runs, help routing, SPEC 3.1
  pass-through, completion probes including the user's
  daedalus hello_bash<TAB><TAB> case), completions units + e2e harness
- README/INSTALL/SPEC updated (6.10, 3.13.5.2, tree, boilerplate with
  shellcheck directive); autotest green (212 tests)

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
2026-11-18 22:35:11 +01:00
parent c210e17661
commit ec9848b169
14 changed files with 433 additions and 20 deletions
+35
View File
@@ -0,0 +1,35 @@
#!/usr/bin/env bash
# Shared interface for daedalus bash scripts (SPEC.md item 6.10).
#
# A registered bash script sources this sibling file once and ends with:
# daedalus_bash_dispatch "$@"
# The script defines help() (its usage text) and main() (its body).
# daedalus completes the help words for the script (SPEC item 3.13.5.2);
# this helper runs them: help, -h, and --help print help(), everything
# else goes to main() with the arguments unchanged.
help() {
echo "bash script error: help() is not defined (SPEC item 6.10.2)" >&2
return 2
}
main() {
echo "bash script error: main() is not defined (SPEC item 6.10.3)" >&2
return 2
}
daedalus_is_help_request() {
case "${1-}" in
help|-h|--help) return 0 ;;
*) return 1 ;;
esac
}
daedalus_bash_dispatch() {
if daedalus_is_help_request "${1:-}"; then
help
local status=$?
exit "$status"
fi
main "$@"
}
+27
View File
@@ -0,0 +1,27 @@
#!/usr/bin/env bash
# hello_bash: sample bash script for the shared interface (SPEC item 6.10).
#
# Run via daedalus: daedalus hello_bash [name...]
# It exists to exercise help() routing, main() dispatch, and the
# completion of the help words (SPEC item 3.13.5.2) end to end.
# shellcheck source=/dev/null
. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/daedalus_common.sh"
help() {
cat <<'EOF'
usage: hello_bash [name...]
Prints a hello line, once per name, default "world".
EOF
}
main() {
local names=("$@")
((${#names[@]})) || names=("world")
local name
for name in "${names[@]}"; do
echo "hello, ${name} (from daedalus bash)"
done
}
daedalus_bash_dispatch "$@"
+82
View File
@@ -0,0 +1,82 @@
"""Tests for the daedalus bash script interface (SPEC item 6.10).
`bash/daedalus_common.sh` routes the help words to the script's help()
and everything else to its main(); every registered .sh script must
implement the interface.
"""
import re
import subprocess
import pytest
from daedalus import REPO_ROOT
from daedalus import registry
COMMON = REPO_ROOT / "bash" / "daedalus_common.sh"
SCRIPT_TEMPLATE = """#!/usr/bin/env bash
. "{common}"
help() {{
echo "usage: sample [args...] (help from help)"
}}
main() {{
echo "main $*"
echo "count $#"
return 3
}}
daedalus_bash_dispatch "$@"
"""
@pytest.fixture
def sample(tmp_path):
"""A minimal script that implements the interface (SPEC items 6.10.1-6.10.4)."""
path = tmp_path / "sample.sh"
path.write_text(SCRIPT_TEMPLATE.format(common=COMMON))
path.chmod(0o755)
return path
def run(script, *args):
"""Run a script with bash and capture everything."""
return subprocess.run(["bash", str(script), *args], capture_output=True,
text=True, check=False)
@pytest.mark.parametrize("word", ["help", "-h", "--help"])
def test_help_words_route_to_help(sample, word):
"""help, -h, and --help print help() and exit with its status (SPEC item 6.10.4)."""
result = run(sample, word)
assert result.returncode == 0
assert result.stdout == "usage: sample [args...] (help from help)\n"
@pytest.mark.parametrize("args, count", [(("build", "--x", "y z"), 3), ((), 0)])
def test_main_receives_the_arguments(sample, args, count):
"""Everything except the help words goes to main() unchanged (SPEC item 6.10.4)."""
result = run(sample, *args)
assert result.returncode == 3
assert result.stdout.splitlines() == [f"main {' '.join(args)}", f"count {count}"]
def test_common_script_parses():
"""bash -n accepts the shared helper itself."""
assert subprocess.run(["bash", "-n", str(COMMON)], check=False).returncode == 0
def test_every_registered_bash_script_implements_the_interface():
"""Every .sh entry in SCRIPTS: source line, help(), main(), dispatch."""
for name, script in sorted(registry.SCRIPTS.items()):
path = script.absolute_path
if path.suffix != ".sh":
continue
assert path.is_file(), f"{name}: {path} does not exist"
text = path.read_text(encoding="utf-8")
assert "daedalus_common.sh" in text, \
f"{name} must source the shared helper (SPEC item 6.10.1)"
assert re.search(r"^help\s*\(\s*\)", text, re.MULTILINE), \
f"{name} must define help() (SPEC item 6.10.2)"
assert re.search(r"^main\s*\(\s*\)", text, re.MULTILINE), \
f"{name} must define main() (SPEC item 6.10.3)"
assert 'daedalus_bash_dispatch "$@"' in text, \
f"{name} must end with the dispatch call (SPEC item 6.10.4)"
+102
View File
@@ -0,0 +1,102 @@
"""Tests for hello_bash: the shared bash interface end to end (SPEC item 6.10).
Direct runs, daedalus runs, help routing, and the completion of the help
words after the script name (SPEC item 3.13.5.2).
"""
import os
import shlex
import subprocess
import sys
import pytest
from daedalus import REPO_ROOT
from daedalus import registry
SCRIPT = registry.SCRIPTS["hello_bash"].absolute_path
def run_script(*args):
"""Run the script directly with bash."""
return subprocess.run(["bash", str(SCRIPT), *args], capture_output=True,
text=True, check=False)
def run_daedalus(*args):
"""Run python -m daedalus from the checkout, like the installed CLI."""
env = {**os.environ, "PYTHONPATH": str(REPO_ROOT)}
return subprocess.run([sys.executable, "-m", "daedalus", *args],
capture_output=True, text=True, check=False,
cwd=REPO_ROOT.parent, env=env)
def test_main_defaults_to_world():
"""No arguments: one hello line for the default name."""
result = run_script()
assert result.returncode == 0
assert result.stdout == "hello, world (from daedalus bash)\n"
def test_main_prints_one_line_per_name():
"""Every name gets its hello line, arguments unchanged."""
result = run_script("me", "you too")
assert result.returncode == 0
assert result.stdout == ("hello, me (from daedalus bash)\n"
"hello, you too (from daedalus bash)\n")
@pytest.mark.parametrize("word", ["help", "-h", "--help"])
def test_help_words_print_the_usage(word):
"""The help words route to hello_bash's help() (SPEC item 6.10.4)."""
result = run_script(word)
assert result.returncode == 0
assert result.stdout.startswith("usage: hello_bash [name...]")
assert "Prints a hello line" in result.stdout
def test_daedalus_runs_it():
"""daedalus hello_bash runs through the bash runner (SPEC item 5.3)."""
result = run_daedalus("hello_bash", "pi")
assert result.returncode == 0, result.stderr
assert result.stdout == "hello, pi (from daedalus bash)\n"
def test_daedalus_category_prefix_runs_it():
"""daedalus test hello_bash runs it through the category prefix."""
result = run_daedalus("test", "hello_bash")
assert result.returncode == 0, result.stderr
assert result.stdout == "hello, world (from daedalus bash)\n"
def test_daedalus_help_word_passes_through():
"""daedalus hello_bash --help shows the script's help, not daedalus's (SPEC item 3.1)."""
result = run_daedalus("hello_bash", "--help")
assert result.returncode == 0, result.stderr
assert result.stdout.startswith("usage: hello_bash [name...]")
def _probe(comp_line):
"""Replay the argcomplete hook and return the candidates (fd 8)."""
env = {**os.environ, "_ARGCOMPLETE": "1", "COMP_LINE": comp_line,
"COMP_POINT": str(len(comp_line)), "_ARGCOMPLETE_IFS": "\n",
"_ARGCOMPLETE_SHELL": "bash", "PYTHONPATH": str(REPO_ROOT),
"NO_COLOR": "1"}
command = (f"exec 8>&1; exec 1>/dev/null; exec 2>/dev/null; "
f"{shlex.quote(sys.executable)} -m daedalus")
result = subprocess.run(["bash", "-c", command], env=env, cwd=REPO_ROOT,
capture_output=True, text=True, check=False)
return [line.strip() for line in result.stdout.splitlines() if line.strip()]
@pytest.mark.skipif(os.name == "nt", reason="bash completion harness")
def test_completion_offers_the_script_name():
"""daedalus hello_ba<TAB> completes hello_bash."""
assert _probe("daedalus hello_ba") == ["hello_bash"]
@pytest.mark.skipif(os.name == "nt", reason="bash completion harness")
def test_completion_offers_the_help_words():
"""After the script name: only the help words (SPEC item 3.13.5.2)."""
assert _probe("daedalus hello_bash ") == ["--help", "-h", "help"]
assert _probe("daedalus hello_bash --") == ["--help"]
assert _probe("daedalus test hello_bash ") == ["--help", "-h", "help"]