automaton/tasks/fix-install-update-flow/SPEC.md

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:

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:

# --- 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:

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:

ln -sf "$HOOK_SRC" "$HOOK_DST"

with:

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):

# 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