bede

docs/superpowers/specs/2026-04-18-macos-to-linux-migration-design.md

@@ -0,0 +1,224 @@
+# macOS → Linux Ubuntu Migration Design
+
+**Date:** 2026-04-18  
+**Status:** Design Approved  
+**Approach:** A (Minimal Linux Migration - Remove macOS-specific code)
+
+---
+
+## 1. Overview
+
+The TFM aInventory codebase was originally developed on macOS with hardcoded paths and platform-specific commands. The user has migrated development to Ubuntu Linux and requires all shell scripts and documentation to reflect this new platform.
+
+**Goal:** Remove all macOS-specific code (git paths, Homebrew references, `ipconfig` commands) and replace with Linux-native equivalents.
+
+**Scope:** 7 files (5 shell scripts + 3 documentation files)  
+**Risk:** Low (all changes are platform-agnostic Linux compatibility)  
+**Deployment:** Local development + Docker testing + standalone bare-metal support
+
+---
+
+## 2. Files & Changes
+
+### 2.1 `.git_path`
+
+**Current:**
+```
+/Library/Developer/CommandLineTools/usr/bin/git
+```
+
+**Change:**
+```
+git
+```
+
+**Why:** Linux uses standard `git` in system PATH via package manager. No custom location needed. The `save_version.py` script already handles fallback to `git` if `.git_path` doesn't exist, so this change is backwards-compatible.
+
+---
+
+### 2.2 `start_server.sh`
+
+**Change 1 - Line 19 (Remove Homebrew PATH):**
+
+Current:
+```bash
+export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
+```
+
+Remove this line entirely. On Linux, npm/node are installed system-wide or via Node Version Manager (nvm), not Homebrew.
+
+**Change 2 - Line 41 (Fix IP Detection):**
+
+Current:
+```bash
+LOCAL_IP=$(ipconfig getifaddr en0 || ipconfig getifaddr en1 || echo "localhost")
+```
+
+New:
+```bash
+LOCAL_IP=$(hostname -I | awk '{print $1}')
+```
+
+**Why:** 
+- `ipconfig` is macOS-only command
+- `hostname -I` returns all IPv4 addresses on Linux; `awk '{print $1}'` extracts the first one (primary interface)
+- Fallback to `localhost` removed; on Linux, the primary interface is always available
+
+---
+
+### 2.3 `run_standalone.sh`
+
+**Change - Line 61 (Fix IP Detection):**
+
+Current:
+```bash
+else
+    LOCAL_IP=$(hostname -I | awk '{print $1}')
+fi
+```
+
+✅ **No change needed** — this branch already correctly uses Linux commands. The non-Darwin path is correct; we just ensure it's the only path used going forward.
+
+---
+
+### 2.4 `AI_RULES.md`
+
+**Change - Remove Section 7.5 "Git Infrastructure Hardening (v1.7.0)"**
+
+Current Section 7.5 (lines 106-109):
+```markdown
+### 7.5 Git Infrastructure Hardening (v1.7.0)
+To ensure deployment stability on macOS environments with potentially broken developer tool links (`xcode-select` errors):
+- **Direct Binary Mapping:** The system bypasses path resolution by using a hardcoded direct link to the Git binary in `.git_path` (`/Library/Developer/CommandLineTools/usr/bin/git`).
+- **Persistence Mandate:** This path is protected by mandatory AI rules and must never be removed or modified to ensure `save-version` and automated deployment scripts remain functional.
+```
+
+**Delete entirely.** This section is no longer applicable on Linux where `git` in system PATH is reliable.
+
+---
+
+### 2.5 `PROJECT_ARCHITECTURE.md`
+
+**Change - Remove macOS reference in Section 7.5**
+
+Current text (lines 106-109):
+```markdown
+### 7.5 Git Infrastructure Hardening (v1.7.0)
+To ensure deployment stability on macOS environments with potentially broken developer tool links (`xcode-select` errors):
+...
+```
+
+**Delete this entire subsection.** Replace Section 7.5 heading with a note:
+
+```markdown
+### 7.5 Git Infrastructure (Linux Native)
+
+All git operations use the standard `git` command available in system PATH. On Linux systems, this is reliably provided by the git package via the system package manager.
+```
+
+---
+
+### 2.6 `SESSION_STATE.md`
+
+**Change - Update System State section (lines 84-85)**
+
+Current:
+```markdown
+**Active AI Tools:**
+- **Git Binary:** `/Library/Developer/CommandLineTools/usr/bin/git`
+- **Environment:** Use `./backend/venv/` for python tasks.
+```
+
+New:
+```markdown
+**Active AI Tools:**
+- **Git Binary:** `git` (system PATH, Linux native)
+- **Environment:** Use `./backend/venv/` for python tasks.
+```
+
+---
+
+## 3. Impact Analysis
+
+### 3.1 Development Workflow
+- ✅ Local `./start_server.sh` execution → detects IP, starts services
+- ✅ Git commands via `save_version.py` → uses system `git`
+- ✅ Shell script portability → scripts now run on any Linux system
+
+### 3.2 Docker Testing
+- ✅ No impact. Docker containers have their own git binary and PATH
+- ✅ `docker compose` commands unchanged
+
+### 3.3 Standalone Deployment (Bare-Metal)
+- ✅ `export_prod.sh` → generates bundles correctly
+- ✅ `./deploy.sh` (in bundle) → runs on Linux servers
+- ✅ `./start_server.sh` (in bundle) → detects local IP correctly on any Linux system
+
+### 3.4 Git Operations
+- ✅ `save_version.py` reads `.git_path`; falls back to `git` if file missing
+- ✅ All git commands (`commit`, `branch`, `merge`) work via system PATH
+
+---
+
+## 4. Testing Plan
+
+After implementation:
+
+1. **Local Development:**
+   - Run `./start_server.sh` → Should detect local IP (e.g., `192.168.x.x` or `localhost`), start backend + frontend + proxies
+   - Access `https://<detected-ip>:8909` in browser → Verify app loads
+
+2. **Git Operations:**
+   - Run `git log` → Verify git works system-wide
+   - Run `python3 scripts/save_version.py --minor` → Should increment version, create branch, merge to master
+
+3. **Docker Testing:**
+   - Run `docker compose build && docker compose up -d` → Should build and run without errors
+   - Access `https://<your-ip>:8909` → Verify Docker deployment
+
+4. **Standalone Bundle:**
+   - Run `./export_prod.sh` → Should generate `.zip` bundle
+   - Extract bundle and run `./start_server.sh` → Should work on a clean Ubuntu system
+
+---
+
+## 5. Files Modified Summary
+
+| File | Lines | Type | Risk |
+|------|-------|------|------|
+| `.git_path` | 1 | Config | 🟢 Low |
+| `start_server.sh` | 2 | Script | 🟢 Low |
+| `run_standalone.sh` | 0 | Script | 🟢 Low (verify only) |
+| `AI_RULES.md` | Delete 7.5 | Docs | 🟢 Low |
+| `PROJECT_ARCHITECTURE.md` | Rewrite 7.5 | Docs | 🟢 Low |
+| `SESSION_STATE.md` | Update 1 line | Docs | 🟢 Low |
+
+**Total:** 6 files, ~15 line changes (mostly deletions/rewrites)
+
+---
+
+## 6. Rollback Plan
+
+If needed, restore from git history:
+```bash
+git checkout HEAD~N -- .git_path start_server.sh AI_RULES.md PROJECT_ARCHITECTURE.md SESSION_STATE.md
+```
+
+All changes are isolated to platform configuration; no core logic is affected.
+
+---
+
+## 7. Next Steps (Writing-Plans)
+
+1. Implement all 6 file changes
+2. Test local development workflow
+3. Test git operations
+4. Test Docker deployment
+5. Verify standalone bundle generation
+6. Commit with message: "chore: migrate from macOS to Linux Ubuntu"
+7. Update VERSION.json via `save-version` command
+
+---
+
+**Approval:** Design approved by user (2026-04-18)  
+**Ready for implementation:** YES