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

RESEARCH: fix-install-update-flow

Objective

Fix 5 issues in the install/update flow identified in the loop v1 design plan.

Issues

Issue 1: Hardcoded git URL (D11)

install.sh line 11: git clone http://10.37.0.86:3003/hermes/automaton "$FRAMEWORK_DIR"

D11: "Install requires user-supplied git URL; refuse with irreversibility warning if absent."

The URL is a private Gitea instance. Public users cannot clone from it. The install script should accept a URL as $1 and refuse if not provided.

Issue 2: .venv cwd bug

install.sh lines 87-91:

if [ ! -d ".venv" ]; then
  python3 -m venv .venv
fi
.venv/bin/pip install --quiet --upgrade pip
.venv/bin/pip install --quiet -r requirements.txt

This runs in whatever directory the user is in when they run install.sh, not in $FRAMEWORK_DIR. The .venv is created in the wrong directory and requirements.txt is not found (it's in $FRAMEWORK_DIR).

Fix: cd "$FRAMEWORK_DIR" before the venv setup, or use absolute paths.

Issue 3: Windows venv path

.venv/bin/pip is Unix-specific. On Windows, the path is .venv/Scripts/pip.exe.

Fix: detect platform and use the correct path. Or use python3 -m pip which works on all platforms.

Issue 4: Hook copy-vs-symlink inconsistency

• install-hooks.sh: uses cp (copy)
• update.sh: uses ln -sf (symlink)
• upgrade.sh: uses ln -sf (symlink)

Copy is safer (works on Windows, survives framework deletion) but doesn't auto-update. Symlink auto-updates but may not work on Windows (Git Bash with MSYS).

Fix: standardize on copy (matching install-hooks.sh). Update update.sh and upgrade.sh to use cp instead of ln -sf. This is simpler and more portable. The downside (hooks don't auto-update) is already documented in install-hooks.sh: "To reinstall after automaton update, re-run this script."

Issue 5: Missing --version check

install.sh doesn't verify the framework is working after install. Adding status.py --version as a smoke test catches Python issues, missing files, etc.

Fix: add python3 "$FRAMEWORK_DIR/scripts/status.py" --version at the end of install.sh.

Current File States

install.sh

• Hardcoded URL on line 11
• .venv setup at lines 87-91 runs in CWD
• No platform detection for venv paths
• No version check

update.sh

• Uses ln -sf for hooks at lines 67-73
• No venv handling (doesn't touch .venv)

upgrade.sh

• Uses ln -sf for hooks at lines 78-98
• Has more sophisticated hook handling (checks for existing symlinks)

install-hooks.sh

• Uses cp for hooks at line 37
• Already the correct approach

Design Decisions

D1: Git URL argument

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 and cannot be auto-updated"
  echo "from a different URL later. Choose your URL carefully."
  exit 1
fi
git clone "$GIT_URL" "$FRAMEWORK_DIR"

D2: Fix .venv cwd

Move the venv setup inside the else block (after clone), or use cd "$FRAMEWORK_DIR" before it. Also use $FRAMEWORK_DIR/requirements.txt.

D3: Use python3 -m pip instead of .venv/bin/pip

python3 -m pip works on all platforms. The venv's python3 is at .venv/bin/python3 (Unix) or .venv/Scripts/python.exe (Windows). But if we activate the venv first, python3 -m pip uses the venv's pip. Simpler: use the venv's python directly with -m pip.

Actually, the simplest fix: use $FRAMEWORK_DIR/.venv/bin/python3 -m pip on Unix and $FRAMEWORK_DIR/.venv/Scripts/python.exe -m pip on Windows. Or detect the platform.

Even simpler: just detect the venv python path:

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

D4: Standardize hooks on copy

Change update.sh and upgrade.sh to use cp instead of ln -sf, matching install-hooks.sh.

D5: Version check

Add at the end of install.sh:

python3 "$FRAMEWORK_DIR/scripts/status.py" --version || echo "WARNING: status.py --version failed"