From 8b61f6616a1ed116c1c340a27e96ee5057075f26 Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Sat, 18 Apr 2026 14:19:33 +0000 Subject: [PATCH] bede --- .claude/settings.local.json | 4 +- .../2026-04-18-macos-to-linux-migration.md | 337 ++++++++++++++++++ ...6-04-18-macos-to-linux-migration-design.md | 224 ++++++++++++ frontend/public/network.json | 2 +- inventory.env | 4 +- 5 files changed, 567 insertions(+), 4 deletions(-) create mode 100644 docs/superpowers/plans/2026-04-18-macos-to-linux-migration.md create mode 100644 docs/superpowers/specs/2026-04-18-macos-to-linux-migration-design.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 2507aa09..62b0584b 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -42,7 +42,9 @@ "Bash(cat)", "Read(//tmp/**)", "Bash(save-version --help)", - "Bash(git --version)" + "Bash(git --version)", + "mcp__plugin_context-mode_context-mode__ctx_stats", + "mcp__plugin_context-mode_context-mode__ctx_execute_file" ] } } diff --git a/docs/superpowers/plans/2026-04-18-macos-to-linux-migration.md b/docs/superpowers/plans/2026-04-18-macos-to-linux-migration.md new file mode 100644 index 00000000..05b896be --- /dev/null +++ b/docs/superpowers/plans/2026-04-18-macos-to-linux-migration.md @@ -0,0 +1,337 @@ +# macOS → Linux Ubuntu Migration Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Remove all macOS-specific code and paths, replacing them with Linux-native equivalents for Ubuntu development. + +**Architecture:** Straightforward configuration updates across 6 files. No code logic changes — only platform-specific command/path replacements and documentation updates. Changes are isolated and independent. + +**Tech Stack:** Bash shell scripts, Python (git path resolution), plain text documentation. + +--- + +## Task 1: Update `.git_path` for Linux + +**Files:** +- Modify: `.git_path` + +- [ ] **Step 1: Read current `.git_path`** + +Run: `cat .git_path` + +Expected output: +``` +/Library/Developer/CommandLineTools/usr/bin/git +``` + +- [ ] **Step 2: Replace with Linux standard git path** + +```bash +echo "git" > .git_path +``` + +- [ ] **Step 3: Verify the change** + +Run: `cat .git_path` + +Expected output: +``` +git +``` + +- [ ] **Step 4: Commit** + +```bash +git add .git_path +git commit -m "chore: update git path for Linux (use system git)" +``` + +--- + +## Task 2: Fix IP Detection in `start_server.sh` + +**Files:** +- Modify: `start_server.sh:19,41` + +- [ ] **Step 1: Remove Homebrew PATH (line 19)** + +Read the file and locate line 19: +```bash +export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH" +``` + +Delete this entire line. New file context (lines 17-22): +```bash +fi + +echo "🚀 Starting TFM aInventory Stack with Dual Proxy..." + +# 1. Kill potentially hanging processes +``` + +- [ ] **Step 2: Fix IP detection (line 41)** + +Locate line 41: +```bash +LOCAL_IP=$(ipconfig getifaddr en0 || ipconfig getifaddr en1 || echo "localhost") +``` + +Replace with: +```bash +LOCAL_IP=$(hostname -I | awk '{print $1}') +``` + +- [ ] **Step 3: Verify the updated lines** + +Run: `sed -n '17,22p; 39,43p' start_server.sh` + +Expected output shows: +- Lines 17-22: No export PATH line +- Lines 39-43: `hostname -I | awk '{print $1}'` instead of `ipconfig` + +- [ ] **Step 4: Test the IP detection locally** + +Run: `bash -c "LOCAL_IP=\$(hostname -I | awk '{print \$1}'); echo \"Detected IP: \$LOCAL_IP\""` + +Expected: Outputs your Ubuntu system's primary IP address (e.g., `192.168.x.x`, `10.x.x.x`, or `127.0.0.1`) + +- [ ] **Step 5: Commit** + +```bash +git add start_server.sh +git commit -m "chore: replace macOS commands with Linux equivalents in start_server.sh + +- Remove /opt/homebrew/bin PATH injection (macOS Homebrew specific) +- Replace ipconfig with hostname -I for IP detection (Linux native)" +``` + +--- + +## Task 3: Update `AI_RULES.md` — Remove macOS Git Infrastructure Section + +**Files:** +- Modify: `AI_RULES.md:106-109` + +- [ ] **Step 1: Locate Section 7.5** + +Run: `grep -n "Git Infrastructure Hardening" AI_RULES.md` + +Expected: Line number showing where Section 7.5 starts (should be around line 106) + +- [ ] **Step 2: Read the section to verify content** + +Run: `sed -n '106,109p' AI_RULES.md` + +Expected output shows the 4-line macOS git hardening section: +```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. +``` + +- [ ] **Step 3: Delete Section 7.5** + +Using Edit tool, remove lines 106-109 entirely. The file should now go from Section 7.4 directly to the end (EOF). + +- [ ] **Step 4: Verify deletion** + +Run: `tail -20 AI_RULES.md` + +Expected: File ends with Section 7.4 or earlier section (no Section 7.5 visible) + +- [ ] **Step 5: Commit** + +```bash +git add AI_RULES.md +git commit -m "chore: remove macOS-specific Git Infrastructure Hardening section + +Section 7.5 no longer applies to Linux environment where git is available in system PATH." +``` + +--- + +## Task 4: Update `PROJECT_ARCHITECTURE.md` — Rewrite Section 7.5 + +**Files:** +- Modify: `PROJECT_ARCHITECTURE.md:106-109` + +- [ ] **Step 1: Locate Section 7.5** + +Run: `grep -n "Git Infrastructure Hardening" PROJECT_ARCHITECTURE.md` + +Expected: Line number showing Section 7.5 start (should be around line 106) + +- [ ] **Step 2: Read current Section 7.5** + +Run: `sed -n '106,109p' PROJECT_ARCHITECTURE.md` + +Expected: Same macOS hardening section as in AI_RULES.md + +- [ ] **Step 3: Replace Section 7.5 with Linux-native note** + +Using Edit tool, replace lines 106-109 with: +```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. +``` + +- [ ] **Step 4: Verify replacement** + +Run: `sed -n '106,109p' PROJECT_ARCHITECTURE.md` + +Expected output: +```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. +``` + +- [ ] **Step 5: Commit** + +```bash +git add PROJECT_ARCHITECTURE.md +git commit -m "chore: update Git Infrastructure section for Linux environment + +Replaced macOS-specific hardening (xcode-select workarounds) with Linux-native approach using system git in PATH." +``` + +--- + +## Task 5: Update `SESSION_STATE.md` — Reflect Linux git binary + +**Files:** +- Modify: `SESSION_STATE.md:85` + +- [ ] **Step 1: Locate the Git Binary line** + +Run: `grep -n "Git Binary" SESSION_STATE.md` + +Expected: Line ~85 showing the git binary reference + +- [ ] **Step 2: Read the current line** + +Run: `sed -n '84,86p' SESSION_STATE.md` + +Expected output: +```markdown +**Active AI Tools:** +- **Git Binary:** `/Library/Developer/CommandLineTools/usr/bin/git` +- **Environment:** Use `./backend/venv/` for python tasks. +``` + +- [ ] **Step 3: Replace git binary line** + +Using Edit tool, replace: +``` +- **Git Binary:** `/Library/Developer/CommandLineTools/usr/bin/git` +``` + +With: +``` +- **Git Binary:** `git` (system PATH, Linux native) +``` + +- [ ] **Step 4: Verify the change** + +Run: `sed -n '84,86p' SESSION_STATE.md` + +Expected output: +```markdown +**Active AI Tools:** +- **Git Binary:** `git` (system PATH, Linux native) +- **Environment:** Use `./backend/venv/` for python tasks. +``` + +- [ ] **Step 5: Commit** + +```bash +git add SESSION_STATE.md +git commit -m "chore: update handover note to reflect Linux git binary" +``` + +--- + +## Task 6: Integration Test — Verify All Changes + +**Files:** +- Test: All modified files + functional verification + +- [ ] **Step 1: Verify all files committed** + +Run: `git status` + +Expected: Clean working directory (no uncommitted changes) + +- [ ] **Step 2: Verify `.git_path` is correct** + +Run: `cat .git_path` + +Expected: `git` (single line, no path) + +- [ ] **Step 3: Verify git operations work** + +Run: `git log --oneline | head -5` + +Expected: Shows recent commits without errors (proves git in PATH works) + +- [ ] **Step 4: Test `save_version.py` reads git path** + +Run: `python3 scripts/save_version.py --help 2>&1 || echo "Script executed or errored as expected"` + +Expected: Script runs or shows usage (proves git path resolution works; won't actually save version without full context) + +- [ ] **Step 5: Verify IP detection logic** + +Run: `bash -c "LOCAL_IP=\$(hostname -I | awk '{print \$1}'); echo \"Primary IP detected: \$LOCAL_IP\""` + +Expected: Outputs Ubuntu system's primary IP address + +- [ ] **Step 6: Verify documentation is accurate** + +Run: `grep -c "macOS\|ipconfig\|homebrew\|xcode" AI_RULES.md PROJECT_ARCHITECTURE.md SESSION_STATE.md || echo "No macOS references found"` + +Expected: Exit code 0 or message "No macOS references found" (no macOS-specific references remain in these docs) + +- [ ] **Step 7: View final commit log** + +Run: `git log --oneline | head -6` + +Expected: Shows 5 migration commits: +1. `chore: update handover note to reflect Linux git binary` +2. `chore: remove macOS-specific Git Infrastructure Hardening section` +3. `chore: update Git Infrastructure section for Linux environment` +4. `chore: replace macOS commands with Linux equivalents in start_server.sh` +5. `chore: update git path for Linux (use system git)` + +- [ ] **Step 8: Final commit (integration verification)** + +```bash +git add -A +git commit -m "chore: macOS to Linux migration complete + +All platform-specific paths and commands replaced with Linux equivalents: +- .git_path: Use system git instead of /Library/Developer/CommandLineTools +- start_server.sh: Use hostname -I instead of ipconfig +- AI_RULES.md, PROJECT_ARCHITECTURE.md: Remove macOS git hardening docs +- SESSION_STATE.md: Update git binary reference to Linux native + +Ready for Ubuntu development, Docker testing, and standalone deployment." +``` + +--- + +## Summary + +| Task | Files | Changes | +|------|-------|---------| +| 1 | `.git_path` | Replace path with `git` | +| 2 | `start_server.sh` | Remove Homebrew PATH, fix IP detection | +| 3 | `AI_RULES.md` | Delete Section 7.5 | +| 4 | `PROJECT_ARCHITECTURE.md` | Rewrite Section 7.5 | +| 5 | `SESSION_STATE.md` | Update git binary note | +| 6 | All | Integration testing + final commit | + +**Total commits:** 6 (including final integration verification) +**Estimated time:** 15-20 minutes diff --git a/docs/superpowers/specs/2026-04-18-macos-to-linux-migration-design.md b/docs/superpowers/specs/2026-04-18-macos-to-linux-migration-design.md new file mode 100644 index 00000000..40d396dc --- /dev/null +++ b/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://: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://: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 diff --git a/frontend/public/network.json b/frontend/public/network.json index 86620d17..b70a710b 100644 --- a/frontend/public/network.json +++ b/frontend/public/network.json @@ -1,5 +1,5 @@ { - "SERVER_IP": "192.168.84.140", + "SERVER_IP": "192.168.84.131", "BACKEND_PORT": 8916, "BACKEND_SSL_PORT": 8918, "FRONTEND_PORT": 8917, diff --git a/inventory.env b/inventory.env index f9214a63..58392a2a 100644 --- a/inventory.env +++ b/inventory.env @@ -5,7 +5,7 @@ # It should match the values in config/network_config.env # ============================================================================= -SERVER_IP=192.168.84.140 +SERVER_IP=192.168.84.131 # Backend Ports BACKEND_PORT=8916 @@ -24,4 +24,4 @@ CLAUDE_API_KEY=sk-ant-api03-13S9Ge3ai43Ia89yfxwwdkoodhddLV1ByVfdmpccqfA-zF-27BLF # External Access (CORS) # Comma-separated list of extra IPs or FQDNs allowed to connect (e.g. Tailscale, VPN) -EXTRA_ALLOWED_ORIGINS=100.78.182.27 +EXTRA_ALLOWED_ORIGINS=100.78.182.27,192.168.84.131