15 KiB

Raw Blame History

MASTER PROMPT: Monorepo Migration, Fix, Test & Deploy

Role: Senior DevOps & Full-Stack Architect with QA Automation

Current State

Backend: /root/second-brain-backend
Frontend: /root/client
Target Monorepo: /root/second-brain
Remote: https://forgejo.dffm.it/giuseppe/second-brain.git
Production URL: https://ai.dffm.it

Objective

Consolidate into monorepo, inject frontend logic, test via remote browser on ai.dffm.it, fix issues, push to Forgejo.

PHASE 1: FILE SYSTEM MIGRATION

# Create monorepo structure
mkdir -p /root/second-brain/{server,client}

# Copy backend (preserve hidden files, exclude heavy dirs)
rsync -av --exclude 'node_modules' --exclude '.git' \
  /root/second-brain-backend/ /root/second-brain/server/

# Copy frontend (preserve hidden files, exclude heavy dirs)
rsync -av --exclude 'node_modules' --exclude '.git' --exclude 'dist' \
  /root/client/ /root/second-brain/client/

# Verify structure
tree -L 2 /root/second-brain

PHASE 2: FRONTEND LOGIC INJECTION

2.1 MainLayout.tsx (client/src/components/layout/MainLayout.tsx)

const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);

return (
  <>
    <Header 
      onMenuToggle={() => setIsMobileMenuOpen(!isMobileMenuOpen)}
    />
    <Sidebar 
      isOpen={isMobileMenuOpen}
      onClose={() => setIsMobileMenuOpen(false)}
    />
  </>
);

2.2 Header.tsx

Requirements:

Fetch GET /api/me on mount, display user avatar/name
Add Hamburger button (visible md:hidden) → triggers onMenuToggle
Avatar dropdown with "Sign out" → POST /auth/logout → redirect to /login

const handleLogout = async () => {
  await fetch('/auth/logout', { method: 'POST', credentials: 'include' });
  window.location.href = '/login';
};

2.3 Sidebar.tsx

Requirements:

Mobile drawer: Fixed position with transform -translate-x-full when closed
Overlay backdrop: fixed inset-0 bg-black/50 z-40 (visible only when isOpen)
Close on backdrop click and on ESC key
"+ New Note" button → POST /api/ingest with current workspaceId

PHASE 3: BACKEND CONFIGURATION

File: server/src/server.ts (or app.ts)

// Serve frontend static files in production
if (process.env.NODE_ENV === 'production') {
  app.use(express.static(path.join(__dirname, '../../client/dist')));
  app.get('*', (req, res) => {
    res.sendFile(path.join(__dirname, '../../client/dist/index.html'));
  });
}

Ensure: CORS is configured to allow frontend origin:

app.use(cors({ origin: 'https://ai.dffm.it', credentials: true }));

PHASE 4: INSTALL DEPENDENCIES & BUILD

# Install server dependencies
cd /root/second-brain/server
npm install

# Install client dependencies
cd /root/second-brain/client
npm install

# Build client for production
npm run build

PHASE 5: REMOTE BROWSER TESTING & AUTO-FIX

Objective: Deploy to production, test via https://ai.dffm.it, identify issues, fix autonomously.

5.1 Deploy to Production Server

# Build frontend for production
cd /root/second-brain/client
npm run build

# Start backend (serving frontend static files)
cd /root/second-brain/server
NODE_ENV=production npm start
# Or use PM2 for persistent process:
# pm2 restart second-brain || pm2 start npm --name "second-brain" -- start

Verify the app is accessible at https://ai.dffm.it before proceeding.

5.2 Browser Testing Protocol (Remote via Chrome)

Use Antigravity's browser automation/preview to navigate to https://ai.dffm.it.

Chrome Configuration: Already authenticated with Giuseppe's Google account.

Test Sequence

1. Authentication & Session Verification

Navigate to https://ai.dffm.it
Check if already logged in (session cookie valid)
If redirected to /login:
- Verify Google SSO button is present
- Click "Sign in with Google"
- Verify redirect to Google (should auto-authenticate)
- Verify redirect back to https://ai.dffm.it/dashboard
Verify GET /api/me returns correct user data
Check Header displays: Avatar + "Giuseppe" (or your name)

2. Desktop Layout Testing (viewport: 1920x1080)

Header:

✅ Logo visible
✅ Navigation links present
✅ Avatar dropdown opens on click
✅ "Sign out" option visible in dropdown

Sidebar:

✅ Always visible (not hidden on desktop)
✅ Navigation items clickable
✅ "+ New Note" button visible

Main Content:

✅ Dashboard loads without errors
✅ No layout overflow or broken grids

3. Mobile Layout Testing (viewport: 375x667)

Resize browser to mobile viewport or use DevTools device emulation

Header:

✅ Hamburger icon visible (replaces full nav)
✅ Click hamburger → Sidebar slides in from left
✅ Overlay backdrop appears (semi-transparent black)

Sidebar behavior:

✅ Sidebar has transform -translate-x-full when closed
✅ Sidebar slides to transform-none when open
✅ Click overlay → Sidebar closes
✅ Press ESC key → Sidebar closes
✅ Navigation links work on mobile

Mobile navigation:

✅ No horizontal scroll
✅ Touch targets >= 44px (mobile-friendly)

4. Responsive Breakpoints (test at each):

640px (sm) - Mobile landscape
768px (md) - Tablet portrait (hamburger should disappear, sidebar always visible)
1024px (lg) - Tablet landscape
1280px (xl) - Desktop

Verify at each breakpoint:

No layout breaks
No content overflow
Smooth transitions
Sidebar visibility toggles correctly at md breakpoint

5. Functional Testing

5a. "+ New Note" Upload

Click "+ New Note" button
File picker should open
Select a test file (e.g., .txt, .md, .pdf)
Verify upload via DevTools Network tab:
- Request: POST /api/ingest
- Body includes workspaceId (current workspace)
- Response: 200 OK or appropriate success code
Verify success feedback (toast/notification)
Verify new note appears in notes list

5b. Sign Out Flow

Open avatar dropdown
Click "Sign out"
Verify:
- Request: POST /auth/logout
- Response: Clears session cookie
- Redirect to /login
Verify session is cleared (no auto-login on page reload)

6. Console & Network Monitoring

Open Chrome DevTools and monitor:

Console: No errors (red messages)

Network:

All API calls return 200/201/204 (no 4xx/5xx)
No failed asset loads (CSS, JS, images)

Performance:

Initial load < 3s
No memory leaks during navigation
Lighthouse score > 80 (optional but recommended)

5.3 Issue Detection & Auto-Fix Loop

For each issue discovered:

Capture Evidence:

Screenshot of the issue
Browser console errors (copy full stack trace)
Network tab errors (request/response details)
Exact steps to reproduce

Diagnose Root Cause:

Identify which component/file is responsible
Check if it's frontend (client code) or backend (API) issue
Review recent changes that might have introduced it

Propose Fix:

Determine exact code change needed
Consider side effects of the fix
Prefer minimal changes (surgical fixes)

Apply Fix:

Edit the relevant file in /root/second-brain/
If frontend change: rebuild with cd /root/second-brain/client && npm run build
If backend change: restart server with pm2 restart second-brain

Re-Test:

Navigate back to https://ai.dffm.it
Reproduce the exact steps
Verify issue is resolved
Check no new issues introduced

Document Fix:

Add entry to TESTING_REPORT.md (format below)

Iteration Limit: Max 3 attempts per issue. If unresolved after 3 attempts, document as "Needs Human Review" and proceed.

5.4 Common Issues & Solutions

Issue: Mobile menu doesn't close on backdrop click

Fix: Add onClick={() => onClose()} to overlay div
File: client/src/components/layout/Sidebar.tsx

Issue: API calls fail with CORS error

Fix: Add CORS middleware in backend:

app.use(cors({ origin: 'https://ai.dffm.it', credentials: true }));

File: server/src/server.ts

Issue: Avatar dropdown doesn't show user name

Fix: Verify GET /api/me is called and state is updated
File: client/src/components/layout/Header.tsx

Issue: Sidebar overlaps content on tablet

Fix: Check Tailwind breakpoint classes (should be md:translate-x-0)
File: client/src/components/layout/Sidebar.tsx

Issue: Sign out doesn't clear session

Fix: Verify /auth/logout clears cookies with correct domain
File: server/src/routes/auth.ts

5.5 Testing Report Generation

Create /root/second-brain/TESTING_REPORT.md:

# Testing Report - Second Brain (ai.dffm.it)

**Test Date**: [Current timestamp]
**Tested URL**: https://ai.dffm.it  
**Browser**: Chrome (authenticated with giuseppe@dffm.it)  
**Tester**: Antigravity Agent

---

## Test Environment
- Backend: Node.js v[X] on Ubuntu
- Frontend: Vite + React + Tailwind CSS
- Server: ai.dffm.it (production)

---

## Issues Found & Fixed

### Issue 1: [Title]
- **Severity**: 🔴 Critical / 🟡 High / 🟢 Medium / ⚪ Low
- **Component**: `client/src/components/...`
- **Description**: [What was wrong]
- **Steps to Reproduce**:
  1. [Step 1]
  2. [Step 2]
- **Root Cause**: [Why it happened]
- **Fix Applied**: 
  ```typescript
  // Before
  [old code]
  
  // After
  [new code]

Files Modified:
- client/src/components/layout/Header.tsx
Status: ✅ Resolved / ⏳ In Progress / ❌ Needs Review

[Repeat for each issue]

Test Results Summary

Authentication ✅

✅ Google SSO login works
✅ Session persists on refresh
✅ User data loads in Header
✅ Sign out clears session

Desktop Layout (1920x1080) ✅

✅ Header displays correctly
✅ Sidebar always visible
✅ Navigation works
✅ Avatar dropdown functional

Mobile Layout (375x667) ✅

✅ Hamburger menu visible
✅ Sidebar slides in/out
✅ Overlay backdrop works
✅ ESC key closes menu
✅ No horizontal scroll

Responsive Breakpoints ✅

✅ 640px (sm)
✅ 768px (md) - Sidebar transition
✅ 1024px (lg)
✅ 1280px (xl)

Functional Features ✅

✅ New note upload works
✅ Workspace selection
✅ Sign out flow

Console & Network ✅

✅ No console errors
✅ All API calls succeed
✅ No failed asset loads

Performance Metrics

Initial Load: ms
Time to Interactive: ms
Bundle Size: KB
Lighthouse Score: /100

Browser Compatibility

✅ Chrome 120+ (primary)
⚠️ Firefox (not tested)
⚠️ Safari (not tested)

Recommendations

[Any improvements or optimizations suggested]
[Security considerations]
[Performance optimizations]

Sign-off

All critical and high-priority issues resolved. App is production-ready on https://ai.dffm.it.

Ready for Git Push: ✅ Yes / ❌ No (reason: ...)


---

### 5.6 Execution Checklist

- [ ] App deployed to `https://ai.dffm.it`
- [ ] Chrome browser opened (authenticated session)
- [ ] Authentication flow tested
- [ ] Desktop layout verified (all breakpoints)
- [ ] Mobile layout verified (all interactions)
- [ ] Responsive transitions tested
- [ ] New note upload functional
- [ ] Sign out flow works
- [ ] Console clean (no errors)
- [ ] Network clean (no failed requests)
- [ ] All issues documented and fixed
- [ ] `TESTING_REPORT.md` created
- [ ] Ready for git commit

**Only proceed to PHASE 6 when this checklist is 100% complete.**

---

## PHASE 6: GIT COMMIT & PUSH

### 6.1 Root .gitignore (`/root/second-brain/.gitignore`)

node_modules/ dist/ .env .env.local *.log .DS_Store coverage/ .vscode/ .idea/


### 6.2 Git Commands

```bash
cd /root/second-brain

# Initialize repo
git init

# Add all files
git add .

# Commit with testing report reference
git commit -m "refactor: monorepo migration with frontend v2 logic + browser testing fixes

- Migrated backend and frontend into monorepo structure
- Implemented mobile menu with slide-in drawer
- Added user authentication with Google SSO
- Fixed responsive breakpoints and layout issues
- All browser tests passed on ai.dffm.it
- See TESTING_REPORT.md for details"

# Set main branch
git branch -M main

# Add remote (with token)
git remote add origin https://giuseppe:ef6966ed330def9b412f584f80a5e8a6c471ed5a@forgejo.dffm.it/giuseppe/second-brain.git

# Force push (overwrites remote)
git push -u origin main --force

VALIDATION CHECKLIST

After execution:

✅ Monorepo structure created (server/, client/)
✅ Frontend logic injected (mobile menu, auth, etc.)
✅ Dependencies installed for both projects
✅ Production build successful
✅ App accessible at https://ai.dffm.it
✅ All browser tests pass
✅ All identified issues fixed and documented
✅ TESTING_REPORT.md created with all green checkmarks
✅ Code committed to git
✅ Code pushed to Forgejo successfully
✅ Remote repo accessible at https://forgejo.dffm.it/giuseppe/second-brain

EXECUTION INSTRUCTIONS FOR ANTIGRAVITY

Execute PHASE 1-4 sequentially without pausing
In PHASE 5:
- Use your browser automation to navigate to https://ai.dffm.it
- Chrome is already authenticated → leverage for testing auth flows
- Take screenshots at each test step for documentation
- Use Chrome DevTools to capture console/network issues
- For each fix:
  - Rebuild frontend: cd /root/second-brain/client && npm run build
  - Restart backend: pm2 restart second-brain
  - Wait 5s for server restart
  - Clear browser cache (Ctrl+Shift+R) before re-testing
- Document everything in TESTING_REPORT.md as you go
- If a fix breaks something else → rollback and try alternative
- Only proceed to PHASE 6 when TESTING_REPORT.md shows all checkmarks green

Success Criteria:

Zero console errors
All features work on desktop + mobile
TESTING_REPORT.md complete with all tests passing
"Ready for Git Push: ✅ Yes" in testing report

Fail-safe Rules:

Maximum 3 fix iterations per issue before escalating
If critical blocker found → stop and request human review
If any PHASE fails → stop and report the failure state
Never proceed to git push if testing report shows failures

Final Deliverables:

Working monorepo at /root/second-brain/
Fully tested app at https://ai.dffm.it
Complete TESTING_REPORT.md with all issues documented
Git repo pushed to Forgejo with all changes

POST-EXECUTION NOTES

After successful push:

Verify remote repo: Visit https://forgejo.dffm.it/giuseppe/second-brain and confirm files are there
Monitor production: Check https://ai.dffm.it still works after push
Update documentation: Add setup instructions to README.md
Security review: Remove token from git remote URL (switch to SSH keys)
Backup: Create backup of /root/second-brain/ before cleanup
Cleanup (optional):

# After confirming everything works
rm -rf /root/second-brain-backend
rm -rf /root/client

END OF PROMPT

15 KiB Raw Blame History