109 lines
3.5 KiB
Markdown
109 lines
3.5 KiB
Markdown
|
# SPEC: fix-install-update-flow
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Five issues in the install/update flow need fixing: hardcoded git URL, `.venv` cwd bug, Windows venv path, hook copy-vs-symlink inconsistency, and missing `--version` smoke test.
|
||
|
|
|
||
|
|
## Non-Goals (deferred)
|
||
|
|
|
||
|
|
- Windows `schtasks` schedule installation testing -> v1.1 (needs Windows CI)
|
||
|
|
- `register-guards.sh` changes -> not in scope (guards work correctly)
|
||
|
|
- Automated update of copied hooks -> v1.1 (documented as "re-run install-hooks.sh")
|
||
|
|
|
||
|
|
## Requirements
|
||
|
|
|
||
|
|
### R1 -- User-supplied git URL (D11)
|
||
|
|
|
||
|
|
`install.sh` must accept the git URL as `$1` and refuse if absent:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
GIT_URL="${1:-}"
|
||
|
|
if [ -z "$GIT_URL" ]; then
|
||
|
|
echo "ERROR: Git URL required."
|
||
|
|
echo "Usage: ./install.sh <git-url>"
|
||
|
|
echo "Example: ./install.sh https://github.com/user/automaton.git"
|
||
|
|
echo ""
|
||
|
|
echo "The framework is cloned to ~/.automaton. Choose your URL carefully"
|
||
|
|
echo "as it cannot be changed later without reinstalling."
|
||
|
|
exit 1
|
||
|
|
fi
|
||
|
|
git clone "$GIT_URL" "$FRAMEWORK_DIR"
|
||
|
|
```
|
||
|
|
|
||
|
|
Remove the hardcoded `http://10.37.0.86:3003/hermes/automaton` URL.
|
||
|
|
|
||
|
|
### R2 -- Fix `.venv` cwd bug
|
||
|
|
|
||
|
|
Move the venv setup inside the `else` block (after clone), using `$FRAMEWORK_DIR`:
|
||
|
|
```bash
|
||
|
|
# --- Python deps (idempotent, in framework dir) ---
|
||
|
|
if [ ! -d "$FRAMEWORK_DIR/.venv" ]; then
|
||
|
|
python3 -m venv "$FRAMEWORK_DIR/.venv"
|
||
|
|
fi
|
||
|
|
```
|
||
|
|
|
||
|
|
Use the venv's Python directly with `-m pip` (platform-aware path, see R3).
|
||
|
|
|
||
|
|
### R3 -- Windows venv path
|
||
|
|
|
||
|
|
Detect the venv Python path based on platform:
|
||
|
|
```bash
|
||
|
|
if [ -f "$FRAMEWORK_DIR/.venv/bin/python3" ]; then
|
||
|
|
VENV_PY="$FRAMEWORK_DIR/.venv/bin/python3"
|
||
|
|
elif [ -f "$FRAMEWORK_DIR/.venv/Scripts/python.exe" ]; then
|
||
|
|
VENV_PY="$FRAMEWORK_DIR/.venv/Scripts/python.exe"
|
||
|
|
else
|
||
|
|
VENV_PY="python3"
|
||
|
|
fi
|
||
|
|
"$VENV_PY" -m pip install --quiet --upgrade pip
|
||
|
|
"$VENV_PY" -m pip install --quiet -r "$FRAMEWORK_DIR/requirements.txt"
|
||
|
|
```
|
||
|
|
|
||
|
|
### R4 -- Hook copy-vs-symlink consistency
|
||
|
|
|
||
|
|
Change `update.sh` and `upgrade.sh` to use `cp` instead of `ln -sf`, matching `install-hooks.sh`:
|
||
|
|
|
||
|
|
In `update.sh`, replace:
|
||
|
|
```bash
|
||
|
|
ln -sf "$HOOK_SRC" "$HOOK_DST"
|
||
|
|
```
|
||
|
|
with:
|
||
|
|
```bash
|
||
|
|
cp "$HOOK_SRC" "$HOOK_DST"
|
||
|
|
chmod +x "$HOOK_DST"
|
||
|
|
```
|
||
|
|
|
||
|
|
In `upgrade.sh`, replace all `ln -sf` for hooks with `cp` + `chmod +x`.
|
||
|
|
|
||
|
|
### R5 -- `--version` smoke test
|
||
|
|
|
||
|
|
Add at the end of `install.sh` (inside the `else` block, after all setup):
|
||
|
|
```bash
|
||
|
|
# Verify framework is working
|
||
|
|
python3 "$FRAMEWORK_DIR/scripts/status.py" --version || echo "WARNING: status.py --version failed"
|
||
|
|
```
|
||
|
|
|
||
|
|
### R6 -- Tests
|
||
|
|
|
||
|
|
Write `tests/test_install_update_flow.py` with:
|
||
|
|
|
||
|
|
1. `test_install_sh_requires_git_url` -- verify install.sh checks for `$1` and refuses if empty
|
||
|
|
2. `test_install_sh_no_hardcoded_url` -- verify the hardcoded IP URL is gone
|
||
|
|
3. `test_install_sh_venv_in_framework_dir` -- verify `.venv` setup uses `$FRAMEWORK_DIR`
|
||
|
|
4. `test_install_sh_has_version_check` -- verify install.sh calls `status.py --version`
|
||
|
|
5. `test_install_sh_windows_venv_path` -- verify install.sh handles `.venv/Scripts/python.exe`
|
||
|
|
6. `test_update_sh_uses_cp_for_hooks` -- verify update.sh uses `cp` not `ln -sf`
|
||
|
|
7. `test_upgrade_sh_uses_cp_for_hooks` -- verify upgrade.sh uses `cp` not `ln -sf`
|
||
|
|
8. `test_install_hooks_sh_uses_cp` -- verify install-hooks.sh still uses `cp` (regression guard)
|
||
|
|
|
||
|
|
### R7 -- Documentation
|
||
|
|
|
||
|
|
- `CHANGELOG.md` under `[unreleased]`
|
||
|
|
- `README.md` -- update install instructions to show `./install.sh <git-url>`
|
||
|
|
|
||
|
|
## Verification
|
||
|
|
|
||
|
|
- `bash -n scripts/install.sh scripts/update.sh scripts/upgrade.sh` -- syntax check
|
||
|
|
- `python3 -m pytest tests/test_install_update_flow.py -v`
|
||
|
|
- `python3 -m pytest tests/ -q` -- full suite must remain green
|