myceliumail 1.0.2 → 1.0.3

package/docs/DASHBOARD_AGENT_HANDOFF.md

@@ -0,0 +1,429 @@
+# 🍄 Myceliumail Web Dashboard - Agent Handoff Brief
+
+> **For a fresh Gemini agent to build the web dashboard**
+
+---
+
+## Your Mission
+
+Build a **local web dashboard** (http://localhost:3737) to view Myceliumail messages with:
+- Unified inbox (local JSON + Supabase)
+- Auto-decrypt encrypted messages
+- Mark as read/archive
+- Beautiful, clean UI
+
+**Estimated time:** 4-6 hours  
+**Complexity:** Medium-Low
+
+---
+
+## What's Already Built (You Can Use)
+
+### Existing Modules in `src/`
+
+| Module | Path | What It Does |
+|--------|------|--------------|
+| **Storage** | `storage/local.ts` | Read/write local JSON messages |
+| **Storage** | `storage/supabase.ts` | Read/write Supabase messages |
+| **Crypto** | `lib/crypto.ts` | Encrypt/decrypt with NaCl |
+| **Config** | `lib/config.ts` | Load agent ID, credentials |
+| **Types** | `types/index.ts` | TypeScript interfaces |
+
+**Key functions you'll use:**
+```typescript
+// From storage/local.ts or storage/supabase.ts
+import { getInbox, getMessage, markAsRead, archiveMessage } from '../storage/supabase.js';
+
+// From crypto.ts
+import { loadKeyPair, decryptMessage } from '../lib/crypto.js';
+
+// From config.ts
+import { loadConfig } from '../lib/config.js';
+```
+
+---
+
+## Project Structure (Create These)
+
+```
+src/dashboard/
+├── server.ts           # Fastify HTTP server
+├── routes.ts           # API endpoints
+└── public/
+    ├── index.html      # Dashboard UI
+    ├── app.js          # Frontend logic
+    └── styles.css      # Styling
+```
+
+---
+
+## Roadmap: Step-by-Step
+
+### Step 1: Install Dependencies (15 min)
+
+```bash
+cd myceliumail  # or your project directory
+npm install fastify @fastify/static @fastify/cors
+```
+
+### Step 2: Create Basic Server (30 min)
+
+**File:** `src/dashboard/server.ts`
+
+```typescript
+import Fastify from 'fastify';
+import fastifyStatic from '@fastify/static';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function startDashboard(port = 3737) {
+    const fastify = Fastify({ logger: true });
+
+    // Serve static files
+    await fastify.register(fastifyStatic, {
+        root: join(__dirname, 'public'),
+        prefix: '/'
+    });
+
+    // Start server
+    await fastify.listen({ port, host: '127.0.0.1' });
+    console.log(`🍄 Dashboard running on http://localhost:${port}`);
+    
+    return fastify;
+}
+```
+
+**Test:** Run `node -r esbuild-register src/dashboard/server.ts` → should start server
+
+### Step 3: Create API Routes (1-2 hours)
+
+**File:** `src/dashboard/routes.ts`
+
+```typescript
+import type { FastifyInstance } from 'fastify';
+import { loadConfig } from '../lib/config.js';
+import * as storage from '../storage/supabase.js';
+import { loadKeyPair, decryptMessage } from '../lib/crypto.js';
+
+export async function registerRoutes(fastify: FastifyInstance) {
+    const config = loadConfig();
+    const agentId = config.agentId;
+
+    // GET /api/inbox
+    fastify.get('/api/inbox', async (request, reply) => {
+        const messages = await storage.getInbox(agentId, { limit: 100 });
+        
+        // Decrypt encrypted messages
+        const keyPair = loadKeyPair(agentId);
+        const decrypted = messages.map(msg => {
+            if (msg.encrypted && keyPair && msg.ciphertext) {
+                try {
+                    const decryptedText = decryptMessage({
+                        ciphertext: msg.ciphertext,
+                        nonce: msg.nonce!,
+                        senderPublicKey: msg.senderPublicKey!
+                    }, keyPair);
+                    
+                    if (decryptedText) {
+                        const parsed = JSON.parse(decryptedText);
+                        return { ...msg, subject: parsed.subject, body: parsed.body, decrypted: true };
+                    }
+                } catch {}
+            }
+            return msg;
+        });
+
+        return { messages: decrypted, total: decrypted.length };
+    });
+
+    // GET /api/message/:id
+    fastify.get('/api/message/:id', async (request, reply) => {
+        const { id } = request.params as { id: string };
+        const message = await storage.getMessage(id);
+        
+        if (!message) {
+            return reply.code(404).send({ error: 'Message not found' });
+        }
+
+        // Decrypt if needed
+        const keyPair = loadKeyPair(agentId);
+        if (message.encrypted && keyPair && message.ciphertext) {
+            try {
+                const decryptedText = decryptMessage({
+                    ciphertext: message.ciphertext,
+                    nonce: message.nonce!,
+                    senderPublicKey: message.senderPublicKey!
+                }, keyPair);
+                
+                if (decryptedText) {
+                    const parsed = JSON.parse(decryptedText);
+                    return { ...message, subject: parsed.subject, body: parsed.body, decrypted: true };
+                }
+            } catch {}
+        }
+
+        return message;
+    });
+
+    // POST /api/message/:id/read
+    fastify.post('/api/message/:id/read', async (request, reply) => {
+        const { id } = request.params as { id: string };
+        await storage.markAsRead(id);
+        return { success: true };
+    });
+
+    // POST /api/message/:id/archive
+    fastify.post('/api/message/:id/archive', async (request, reply) => {
+        const { id } = request.params as { id: string };
+        await storage.archiveMessage(id);
+        return { success: true };
+    });
+
+    // GET /api/stats
+    fastify.get('/api/stats', async (request, reply) => {
+        const messages = await storage.getInbox(agentId);
+        const unread = messages.filter(m => !m.read).length;
+        return {
+            total: messages.length,
+            unread,
+            encrypted: messages.filter(m => m.encrypted).length
+        };
+    });
+}
+```
+
+**Update server.ts to use routes:**
+```typescript
+import { registerRoutes } from './routes.js';
+
+// After creating fastify instance:
+await registerRoutes(fastify);
+```
+
+### Step 4: Create Frontend UI (2-3 hours)
+
+**File:** `src/dashboard/public/index.html`
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>🍄 Myceliumail Dashboard</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link rel="stylesheet" href="/styles.css">
+</head>
+<body class="bg-gray-900 text-gray-100">
+    <div class="container mx-auto p-6">
+        <!-- Header -->
+        <header class="flex justify-between items-center mb-8">
+            <h1 class="text-3xl font-bold">🍄 Myceliumail Dashboard</h1>
+            <div id="stats" class="text-sm text-gray-400"></div>
+        </header>
+
+        <!-- Inbox List -->
+        <div class="grid grid-cols-3 gap-6">
+            <div class="col-span-1 bg-gray-800 rounded-lg p-4">
+                <h2 class="text-xl font-semibold mb-4">Inbox</h2>
+                <div id="inbox-list" class="space-y-2"></div>
+            </div>
+
+            <!-- Message Detail -->
+            <div class="col-span-2 bg-gray-800 rounded-lg p-6">
+                <div id="message-detail">
+                    <p class="text-gray-500">Select a message to view</p>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script src="/app.js"></script>
+</body>
+</html>
+```
+
+**File:** `src/dashboard/public/app.js`
+
+```javascript
+// Load inbox on page load
+async function loadInbox() {
+    const res = await fetch('/api/inbox');
+    const data = await res.json();
+    
+    const list = document.getElementById('inbox-list');
+    list.innerHTML = data.messages.map(msg => `
+        <div class="message-item p-3 rounded cursor-pointer hover:bg-gray-700 ${msg.read ? '' : 'font-bold'}"
+             onclick="viewMessage('${msg.id}')">
+            <div class="flex items-center gap-2">
+                ${msg.encrypted ? '🔐' : '📨'}
+                ${!msg.read ? '●' : ''}
+                <span class="text-sm">${msg.sender}</span>
+            </div>
+            <div class="text-sm text-gray-400 truncate">${msg.subject || '(no subject)'}</div>
+        </div>
+    `).join('');
+
+    updateStats(data);
+}
+
+async function viewMessage(id) {
+    const res = await fetch(`/api/message/${id}`);
+    const msg = await res.json();
+    
+    const detail = document.getElementById('message-detail');
+    detail.innerHTML = `
+        <div class="mb-4">
+            <div class="text-sm text-gray-400">From: ${msg.sender}</div>
+            <h2 class="text-2xl font-bold">${msg.subject}</h2>
+            <div class="text-sm text-gray-400">${new Date(msg.createdAt).toLocaleString()}</div>
+            ${msg.encrypted ? '<div class="text-sm text-green-400">🔐 Encrypted (decrypted ✅)</div>' : ''}
+        </div>
+        <div class="prose prose-invert max-w-none">
+            <p class="whitespace-pre-wrap">${msg.body}</p>
+        </div>
+        <div class="mt-6 flex gap-4">
+            <button onclick="archiveMessage('${msg.id}')" 
+                    class="px-4 py-2 bg-gray-700 rounded hover:bg-gray-600">
+                Archive
+            </button>
+        </div>
+    `;
+
+    // Mark as read
+    await fetch(`/api/message/${id}/read`, { method: 'POST' });
+    loadInbox(); // Refresh
+}
+
+async function archiveMessage(id) {
+    await fetch(`/api/message/${id}/archive`, { method: 'POST' });
+    loadInbox();
+    document.getElementById('message-detail').innerHTML = '<p class="text-gray-500">Select a message to view</p>';
+}
+
+function updateStats(data) {
+    document.getElementById('stats').innerHTML = `
+        Total: ${data.total} | Unread: ${data.messages.filter(m => !m.read).length}
+    `;
+}
+
+// Load on page load
+loadInbox();
+
+// Auto-refresh every 10 seconds
+setInterval(loadInbox, 10000);
+```
+
+**File:** `src/dashboard/public/styles.css`
+
+```css
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+}
+
+.message-item {
+    transition: all 0.2s;
+}
+
+.message-item:hover {
+    transform: translateX(4px);
+}
+```
+
+### Step 5: Add CLI Command (30 min)
+
+**File:** `src/commands/dashboard.ts`
+
+```typescript
+import { Command } from 'commander';
+import { startDashboard } from '../dashboard/server.js';
+
+export function createDashboardCommand(): Command {
+    return new Command('dashboard')
+        .description('Start web dashboard on localhost:3737')
+        .option('-p, --port <port>', 'Port to run on', '3737')
+        .action(async (options) => {
+            const port = parseInt(options.port, 10);
+            await startDashboard(port);
+            console.log(`\n🍄 Dashboard running: http://localhost:${port}\n`);
+            console.log('Press Ctrl+C to stop\n');
+        });
+}
+```
+
+**Add to** `src/bin/myceliumail.ts`:
+```typescript
+import { createDashboardCommand } from '../commands/dashboard.js';
+
+// Register with other commands
+program.addCommand(createDashboardCommand());
+```
+
+### Step 6: Build & Test (30 min)
+
+```bash
+# Build
+npm run build
+
+# Test
+mycmail dashboard
+
+# Open browser
+open http://localhost:3737
+```
+
+---
+
+## Acceptance Criteria
+
+✅ Dashboard loads on http://localhost:3737  
+✅ Shows all messages from inbox  
+✅ Encrypted messages are decrypted automatically  
+✅ Clicking message shows full content  
+✅ Mark as read works  
+✅ Archive works  
+✅ Stats show correct counts  
+✅ Auto-refresh every 10 seconds  
+✅ Dark mode, clean UI
+
+---
+
+## Testing Scenarios
+
+1. **Empty inbox** → Shows "No messages"
+2. **Encrypted message** → Decrypts and displays ✅
+3. **Unread message** → Shows bold, has ● indicator
+4. **Archive** → Message disappears from list
+5. **Multiple agents** → All messages visible
+
+---
+
+## Troubleshooting
+
+**Port already in use:**
+```bash
+mycmail dashboard --port 3738
+```
+
+**Build errors:**
+```bash
+npm install @types/node fastify @fastify/static
+```
+
+**Messages not showing:**
+- Check storage: `cat ~/.myceliumail/data/messages.json`
+- Check config: `echo $MYCELIUMAIL_AGENT_ID`
+- Check logs in terminal
+
+---
+
+## Resources
+
+- **Fastify docs:** https://fastify.dev/
+- **Tailwind CSS:** https://tailwindcss.com/docs
+- **Existing code:** `src/`
+
+---
+
+**Ready to build! Start with Step 1.** 🍄

package/docs/DASHBOARD_AGENT_PROMPT.md

@@ -0,0 +1,32 @@
+# Quick Start Prompt for Fresh Agent
+
+**Copy-paste this to a new Gemini agent:**
+
+---
+
+Hi! I need you to build a web dashboard for Myceliumail.
+
+**Context:**
+- Project: `./` (clone from GitHub)
+- Read this first: `docs/DASHBOARD_AGENT_HANDOFF.md`
+- Follow roadmap: `docs/DASHBOARD_BUILD_ROADMAP.md`
+
+**Your mission:**
+Build a local web dashboard (http://localhost:3737) to view Myceliumail messages.
+
+**Key requirements:**
+1. Use existing modules in `src/storage/`, `src/lib/crypto.ts`, `src/lib/config.ts`
+2. Build with Fastify + Tailwind CSS
+3. Auto-decrypt encrypted messages
+4. Dark mode UI, clean design
+5. Add `mycmail dashboard` CLI command
+
+**Time estimate:** 4-6 hours
+
+**Acceptance criteria:** User can run `mycmail dashboard`, open browser, see all messages (encrypted ones decrypted), archive/mark as read.
+
+Start with Phase 1 in the roadmap!
+
+---
+
+**That's it! Hand this to a new agent and they're ready to build.**

package/docs/DASHBOARD_BUILD_ROADMAP.md

@@ -0,0 +1,61 @@
+# Dashboard Build Roadmap
+
+> Quick reference for agent building the web dashboard
+
+## Phase 1: Setup (15 min)
+- [ ] Install: `npm install fastify @fastify/static @fastify/cors`
+- [ ] Create: `src/dashboard/` directory
+- [ ] Create: `src/dashboard/public/` directory
+
+## Phase 2: Backend (2 hours)
+- [ ] Create `src/dashboard/server.ts` (Fastify server)
+- [ ] Create `src/dashboard/routes.ts` (5 API endpoints)
+- [ ] Test: `GET /api/inbox` returns messages
+- [ ] Test: `GET /api/message/:id` decrypts encrypted messages
+- [ ] Test: `POST /api/message/:id/read` marks as read
+
+## Phase 3: Frontend (2-3 hours)
+- [ ] Create `src/dashboard/public/index.html` (layout + Tailwind)
+- [ ] Create `src/dashboard/public/app.js` (fetch API, render messages)
+- [ ] Create `src/dashboard/public/styles.css` (custom styles)
+- [ ] Test: Messages load in browser
+- [ ] Test: Click message → shows detail
+- [ ] Test: Archive button works
+
+## Phase 4: CLI Integration (30 min)
+- [ ] Create `src/commands/dashboard.ts`
+- [ ] Register in `src/bin/myceliumail.ts`
+- [ ] Build: `npm run build`
+- [ ] Test: `mycmail dashboard` starts server
+
+## Phase 5: Polish (1 hour)
+- [ ] Add auto-refresh (10 sec interval)
+- [ ] Add unread indicators (bold + ●)
+- [ ] Add stats header (total, unread)
+- [ ] Add keyboard shortcuts (optional)
+- [ ] Dark mode polish
+
+## Acceptance Tests
+- [ ] Can view all local messages
+- [ ] Can view Supabase messages (if configured)
+- [ ] Encrypted messages decrypt automatically
+- [ ] Mark as read updates UI
+- [ ] Archive removes from inbox
+- [ ] UI is responsive and clean
+
+## Time Budget
+- Setup: 15 min
+- Backend: 2 hours
+- Frontend: 2-3 hours
+- CLI: 30 min
+- Polish: 1 hour
+**Total: 4-6 hours**
+
+## Key Files to Reference
+- Storage API: `src/storage/supabase.ts`
+- Crypto: `src/lib/crypto.ts`
+- Config: `src/lib/config.ts`
+- Types: `src/types/index.ts`
+
+## Success = 
+User runs `mycmail dashboard`, opens browser, sees beautiful inbox with all messages (encrypted ones decrypted), can archive/read, feels 🍄 magical!

package/docs/DEPLOYMENT.md

@@ -0,0 +1,59 @@
+# Myceliumail Deployment Checklist
+
+## Pre-Deployment
+
+### 1. Environment Setup
+- [ ] Set `MYCELIUMAIL_STORAGE=supabase` in `.env`
+- [ ] Set production Supabase credentials:
+  ```bash
+  SUPABASE_URL=https://your-project.supabase.co
+  SUPABASE_ANON_KEY=your-production-key
+  ```
+- [ ] Verify agent ID: `MYCELIUMAIL_AGENT_ID=your-agent`
+
+### 2. Database
+- [ ] Run migrations on production Supabase
+- [ ] Verify `agent_messages` table exists with correct schema
+- [ ] Check RLS policies are enabled
+
+### 3. Build & Test
+- [ ] Run `npm run build` - no errors
+- [ ] Test send: `mycmail send test-agent "Test" -m "Hello"`
+- [ ] Test inbox: `mycmail inbox`
+- [ ] Test dashboard: `mycmail dashboard`
+
+### 4. Security
+- [ ] Ensure `.env` is in `.gitignore`
+- [ ] No secrets committed to git
+- [ ] Review public keys in `docs/AGENT_STARTER_KIT.md`
+
+---
+
+## Post-Deployment
+
+### 1. Verify
+- [ ] Send test message to known agent
+- [ ] Check message appears in Supabase dashboard
+- [ ] Verify encryption works: `mycmail send agent "Test" -m "Secret" --encrypt`
+
+### 2. Update Agents
+- [ ] Notify agents of production URL
+- [ ] Share updated MCP config with Supabase credentials
+- [ ] Confirm agents can send/receive
+
+### 3. Monitor
+- [ ] Check Supabase logs for errors
+- [ ] Monitor message table growth
+- [ ] Review API usage/limits
+
+---
+
+## Rollback
+If issues occur:
+```bash
+# Switch back to local storage
+MYCELIUMAIL_STORAGE=local mycmail inbox
+
+# Or switch to staging
+SUPABASE_URL=https://staging-project.supabase.co
+```

package/docs/LESSONS_LEARNED.md

@@ -0,0 +1,127 @@
+# Lessons Learned: MCP Supabase Connection Debugging
+
+## Date
+December 17-18, 2025
+
+## Issue Summary
+Watson (Claude Desktop MCP user) could not see Supabase messages. The MCP server only showed locally cached messages instead of fetching from the cloud.
+
+---
+
+## Root Causes Identified
+
+### 1. Schema Mismatch (Code Bug)
+**Problem:** The MCP server's `storage.ts` was using incorrect column names when querying Supabase:
+- Used `recipient` instead of `to_agent`
+- Used `sender` instead of `from_agent`  
+- Used `body` instead of `message`
+
+**Symptom:** Supabase queries returned empty results because the columns didn't exist.
+
+**Fix:** Updated all Supabase queries in `storage.ts` to use the correct column names matching the actual `agent_messages` table schema.
+
+**Lesson:** Always verify that code column names match the actual database schema. Consider using generated types from Supabase to catch these mismatches at compile time.
+
+---
+
+### 2. Silent Error Swallowing (Bad Pattern)
+**Problem:** All Supabase operations had empty `catch` blocks:
+```typescript
+} catch {
+    // Fall through to local
+}
+```
+
+**Symptom:** Errors were completely hidden. When Supabase failed, the code silently fell back to local storage without any indication of why.
+
+**Fix:** Added proper error logging to all catch blocks:
+```typescript
+} catch (err) {
+    console.error('getInbox failed, falling back to local:', err);
+    // Fall through to local
+}
+```
+
+**Lesson:** Never use empty catch blocks. Always log errors, even when recovering gracefully. Silent failures are debugging nightmares.
+
+---
+
+### 3. NPX Caching (Deployment Issue)
+**Problem:** `npx myceliumail-mcp` was aggressively caching old versions of the package, even after publishing fixes to npm.
+
+**Symptom:** Even after publishing v1.0.6 with fixes, Claude Desktop kept running the broken old version.
+
+**Attempted Solutions:**
+- `npx -y myceliumail-mcp@1.0.6` - Did not reliably bust cache
+- `npm cache clean --force` - Not effective for npx cache
+
+**Final Fix:** Configured Claude Desktop to run the local build directly:
+```json
+{
+  "command": "node",
+  "args": ["/path/to/dist/server.js"]
+}
+```
+
+**Lesson:** For development and debugging, always use local builds with direct paths. Don't trust `npx` caching behavior during active development. For production users, consider adding version-specific instructions: `npx myceliumail-mcp@latest`.
+
+---
+
+### 4. Missing Global Config Support (Feature Gap)
+**Problem:** The MCP server only read Supabase credentials from environment variables, but Claude Desktop's MCP config doesn't support complex env var setup easily.
+
+**Fix:** Added fallback to read from `~/.myceliumail/config.json`, same as the CLI tool.
+
+**Lesson:** MCP servers should support multiple config sources (env vars, config files) for flexibility across different deployment contexts.
+
+---
+
+## Debugging Techniques Used
+
+### 1. File-Based Debug Logging
+When console output was being swallowed by the MCP runtime, we added file-based logging:
+```typescript
+const LOG_FILE = join(homedir(), '.myceliumail', 'debug.log');
+appendFileSync(LOG_FILE, `[${timestamp}] ${msg}\n`);
+```
+
+This proved essential for diagnosing issues in environments where stderr isn't visible.
+
+### 2. Reproduction Script
+Created `debug-mcp-connection.js` to test the Supabase connection outside of the MCP context:
+```javascript
+const { hasSupabase } = require('./dist/lib/config.js');
+const { getInbox } = require('./dist/lib/storage.js');
+// Test directly
+```
+
+This isolated whether the issue was in the code or the MCP runtime environment.
+
+### 3. Direct Supabase Verification
+Used the Supabase MCP tool to verify data existed:
+```sql
+SELECT * FROM agent_messages WHERE to_agent = 'watson';
+```
+
+This confirmed the data was in the cloud and the issue was in fetching, not storage.
+
+---
+
+## Prevention Guidelines
+
+1. **Schema Validation:** Use TypeScript generated types from Supabase CLI to catch column name mismatches at compile time.
+
+2. **Error Visibility:** Always log errors, never swallow them silently. Use a consistent error logging pattern.
+
+3. **Multiple Config Sources:** Support env vars AND config files for flexibility.
+
+4. **Local Development:** Always test with local builds during debugging. Don't rely on npm/npx for rapid iteration.
+
+5. **Integration Tests:** Add tests that actually hit Supabase (in a test project) to catch schema drift.
+
+---
+
+## Related Files Modified
+- `mcp-server/src/lib/config.ts` - Added config file support
+- `mcp-server/src/lib/storage.ts` - Fixed column names, added error logging
+- `mcp-server/package.json` - Version bumps