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

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:

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:

LOCAL_IP=$(ipconfig getifaddr en0 || ipconfig getifaddr en1 || echo "localhost")

New:

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:

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

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

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

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

**Active AI Tools:**
- **Git Binary:** `/Library/Developer/CommandLineTools/usr/bin/git`
- **Environment:** Use `./backend/venv/` for python tasks.

New:

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

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