gsd-agent 1.0.0

package/README.md

@@ -0,0 +1,221 @@
+# GSD Agent - Local Filesystem Sync Daemon
+
+The GSD Agent is a lightweight Node.js daemon that runs on your local machine, automatically discovering GSD projects and synchronizing their planning files to the cloud for real-time web UI updates.
+
+## Features
+
+- **Real-time Sync**: Changes to your `.planning/` directories sync to the cloud within seconds
+- **Multi-user Support**: Secure authentication and data isolation for each user
+- **Automatic Discovery**: Finds GSD projects in your configured watch directories
+- **Conflict Resolution**: Handles concurrent changes between local and web UI
+- **Large File Support**: Files >200KB automatically uploaded to secure storage
+- **Secure Authentication**: Device flow authentication with encrypted credentials
+
+## Prerequisites
+
+- Node.js 20+ installed
+- Git installed on your system
+- Active GSD account (sign up at your GSD web UI)
+
+## Installation
+
+### Public npm Package (Recommended)
+
+```bash
+npm install -g gsd-agent
+```
+
+This installs the agent globally on your system.
+
+### Run Without Installing
+
+```bash
+npx gsd-agent@latest auth
+npx gsd-agent@latest start
+```
+
+This runs the agent without installing it permanently.
+
+## Quick Start
+
+### 1. Authenticate with your account
+
+```bash
+gsd-agent auth
+```
+
+This will:
+- Generate a device code
+- Display instructions to visit the web UI
+- Prompt you to enter the code
+- Complete authentication flow
+
+### 2. Start the agent daemon
+
+```bash
+gsd-agent start
+```
+
+### 3. Verify status
+
+```bash
+gsd-agent status
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gsd-agent auth` | Authenticate with web account |
+| `gsd-agent start` | Start the agent daemon |
+| `gsd-agent status` | Show sync status |
+| `gsd-agent disconnect` | Revoke credentials |
+| `gsd-agent logs` | Tail agent logs |
+| `gsd-agent version` | Show version |
+
+## Configuration
+
+Configuration is stored in `~/.gsd-agent/config.json`:
+
+```json
+{
+  "watch_dirs": [
+    "~/Projects",
+    "~/Code",
+    "~/workspace"
+  ],
+  "ignored_patterns": [
+    "node_modules/",
+    ".git/",
+    "dist/",
+    "build/",
+    "*.log"
+  ],
+  "log_level": "INFO",
+  "batch_size": 50,
+  "debounce_ms": 300
+}
+```
+
+## How It Works
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  Local Files    │    │  GSD Agent      │    │  Cloud (Web UI) │
+│  (.planning/)   │◄──►│  (Node.js)      │◄──►│  (Supabase)     │
+│                 │    │  - FileWatcher  │    │  - Database     │
+│  MyProject/     │    │  - SyncEngine   │    │  - Storage      │
+│  └─ .planning/  │    │  - Realtime     │    │  - Realtime     │
+│     ├─ PLAN.md  │    │  - Auth Flow    │    │                 │
+│     ├─ STATE.md │    │                 │    │                 │
+│     └─ etc...   │    │                 │    │                 │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+1. **File Watching**: Agent monitors `.planning/` directories for changes
+2. **Local Processing**: Changes batched and processed locally
+3. **Cloud Sync**: Changes securely transmitted to Supabase
+4. **Real-time Updates**: Web UI receives updates via Supabase Realtime
+5. **Web Changes**: UI changes pushed back to local files
+
+## Security
+
+- **End-to-End Encryption**: All data encrypted in transit
+- **Secure Storage**: Credentials stored with restricted permissions (0600)
+- **User Isolation**: Row-level security ensures data isolation
+- **Token Management**: Automatic refresh and secure storage
+- **Audit Trail**: All operations logged for security review
+
+## Troubleshooting
+
+### Agent won't start
+- Check authentication: `gsd-agent status`
+- Verify credentials file exists: `~/.gsd-agent/credentials.json`
+- Check logs: `gsd-agent logs`
+
+### Files not syncing
+- Ensure `.planning/` directory exists in your project
+- Verify watch directories in config
+- Check network connectivity to Supabase
+
+### Authentication issues
+- Run `gsd-agent disconnect` then `gsd-agent auth`
+- Clear credentials: `rm -rf ~/.gsd-agent/credentials.json`
+- Re-authenticate
+
+## Auto-start
+
+### Linux (systemd)
+```bash
+# Create systemd user service
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/gsd-agent.service << EOF
+[Unit]
+Description=GSD Agent
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=$(which gsd-agent) start
+Restart=always
+
+[Install]
+WantedBy=default.target
+EOF
+
+systemctl --user enable gsd-agent
+systemctl --user start gsd-agent
+```
+
+### macOS (launchd)
+```bash
+cat > ~/Library/LaunchAgents/com.gsd.agent.plist << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.gsd.agent</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$(which gsd-agent)</string>
+        <string>start</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+</dict>
+</plist>
+EOF
+
+launchctl load ~/Library/LaunchAgents/com.gsd.agent.plist
+```
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/your-org/gsd-agent.git
+cd gsd-agent
+npm install
+
+# Build
+npm run build
+
+# Development mode
+npm run dev
+
+# Run tests
+npm test
+```
+
+## Support
+
+- Documentation: https://gsd.fahad.ink/docs
+- Issues: https://github.com/your-org/gsd-agent/issues
+- Community: https://discord.gg/your-server
+
+---
+
+**Note**: This agent requires an active internet connection to sync with the cloud. All data is encrypted and secured according to industry standards.

package/bin/cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+
+/**
+ * GSD Agent CLI
+ *
+ * Commands:
+ *   gsd-agent auth       - Authenticate with web account
+ *   gsd-agent start      - Start the agent daemon
+ *   gsd-agent status     - Show sync status
+ *   gsd-agent disconnect - Revoke credentials
+ *   gsd-agent logs       - Tail agent logs
+ *   gsd-agent version    - Show version
+ */
+
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const AGENT_DIST = path.join(__dirname, '..', 'dist', 'index.js');
+const CREDENTIALS_PATH = path.join(os.homedir(), '.gsd-agent', 'credentials.json');
+const LOG_FILE = path.join(os.homedir(), '.gsd-agent', 'logs', 'agent.log');
+const VERSION = '1.0.0';
+
+/**
+ * Check if agent is authenticated
+ */
+function isAuthenticated() {
+  try {
+    if (!fs.existsSync(CREDENTIALS_PATH)) {
+      return false;
+    }
+    const credentials = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf-8'));
+    return !!(credentials.access_token && credentials.user_id);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  console.log(`
+GSD Agent v${VERSION}
+Local filesystem sync daemon for GSD projects
+
+Usage:
+  gsd-agent <command> [options]
+
+Commands:
+  auth          Authenticate with your web account
+  start         Start the agent daemon (requires auth)
+  status        Show sync status and connection info
+  disconnect    Revoke credentials and stop agent
+  logs          Tail agent logs
+  version       Show version
+
+Examples:
+  gsd-agent auth              # Start authentication flow
+  gsd-agent start             # Start syncing
+  gsd-agent status            # Check sync status
+  gsd-agent logs --lines 50   # Show last 50 log lines
+
+Documentation:
+  https://gsd-webui-domain.com/docs/agent-setup
+`);
+}
+
+/**
+ * Run authentication flow
+ */
+async function runAuth() {
+  console.log('Starting GSD Agent authentication...\n');
+
+  try {
+    // Import and run the auth flow
+    const { authenticateAgent } = await import('../dist/auth-flow.js');
+    const success = await authenticateAgent();
+
+    if (success) {
+      console.log('\n✓ Authentication successful!');
+      console.log('You can now run: gsd-agent start\n');
+      process.exit(0);
+    } else {
+      console.log('\n✗ Authentication failed. Please try again.\n');
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('Authentication error:', error.message);
+    console.log('\nMake sure the agent is built: npm run build\n');
+    process.exit(1);
+  }
+}
+
+/**
+ * Start the agent daemon
+ */
+function startAgent() {
+  if (!isAuthenticated()) {
+    console.log('Not authenticated. Please run: gsd-agent auth\n');
+    process.exit(1);
+  }
+
+  console.log('Starting GSD Agent daemon...\n');
+
+  if (!fs.existsSync(AGENT_DIST)) {
+    console.log('Agent not built. Running build...\n');
+    try {
+      execSync('npm run build', { stdio: 'inherit', cwd: path.join(__dirname, '..') });
+    } catch (error) {
+      console.error('Build failed. Please run: npm run build\n');
+      process.exit(1);
+    }
+  }
+
+  // Start the agent
+  const agent = spawn('node', [AGENT_DIST], {
+    stdio: 'inherit',
+    env: { ...process.env }
+  });
+
+  agent.on('error', (error) => {
+    console.error('Failed to start agent:', error.message);
+    process.exit(1);
+  });
+
+  agent.on('exit', (code) => {
+    if (code !== 0) {
+      console.error(`Agent exited with code ${code}`);
+      process.exit(code);
+    }
+  });
+}
+
+/**
+ * Show agent status
+ */
+function showStatus() {
+  console.log('GSD Agent Status\n');
+  console.log('================\n');
+
+  // Check authentication
+  if (isAuthenticated()) {
+    const credentials = JSON.parse(fs.readFileSync(CREDENTIALS_PATH, 'utf-8'));
+    console.log('Authentication: ✓ Connected');
+    console.log(`User ID: ${credentials.user_id}`);
+    console.log(`Token expires: ${credentials.expires_at}`);
+  } else {
+    console.log('Authentication: ✗ Not authenticated');
+    console.log('Run: gsd-agent auth\n');
+  }
+
+  console.log('');
+
+  // Check if agent process is running
+  try {
+    const result = execSync('pgrep -f "gsd-agent" || true', { encoding: 'utf-8' });
+    if (result.trim()) {
+      console.log('Agent Process: ✓ Running');
+      console.log(`PID: ${result.trim().split('\n').join(', ')}`);
+    } else {
+      console.log('Agent Process: ✗ Not running');
+      console.log('Run: gsd-agent start\n');
+    }
+  } catch {
+    console.log('Agent Process: ✗ Not running');
+    console.log('Run: gsd-agent start\n');
+  }
+
+  console.log('');
+
+  // Check log file
+  if (fs.existsSync(LOG_FILE)) {
+    const stats = fs.statSync(LOG_FILE);
+    console.log(`Log File: ${LOG_FILE}`);
+    console.log(`Last modified: ${stats.mtime.toISOString()}`);
+    console.log('View logs: gsd-agent logs\n');
+  }
+
+  console.log('================\n');
+}
+
+/**
+ * Disconnect and clear credentials
+ */
+function disconnect() {
+  console.log('Disconnecting GSD Agent...\n');
+
+  try {
+    // Stop running agent process
+    try {
+      execSync('pkill -f "gsd-agent" || true', { stdio: 'ignore' });
+      console.log('✓ Agent process stopped');
+    } catch {
+      // Process wasn't running
+    }
+
+    // Clear credentials
+    if (fs.existsSync(CREDENTIALS_PATH)) {
+      fs.unlinkSync(CREDENTIALS_PATH);
+      console.log('✓ Credentials cleared');
+    } else {
+      console.log('✓ No credentials found');
+    }
+
+    console.log('\nAgent disconnected. Run "gsd-agent auth" to reconnect.\n');
+  } catch (error) {
+    console.error('Disconnect error:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Tail agent logs
+ */
+function showLogs(options = {}) {
+  const lines = options.lines || 50;
+
+  if (!fs.existsSync(LOG_FILE)) {
+    console.log('No log file found. Agent may not have been started yet.\n');
+    console.log(`Expected location: ${LOG_FILE}\n`);
+    process.exit(1);
+  }
+
+  console.log(`Tailing agent logs (last ${lines} lines)...\n`);
+  console.log('Press Ctrl+C to stop\n');
+
+  try {
+    // Use tail -f to follow logs
+    const tail = spawn('tail', ['-f', '-n', String(lines), LOG_FILE], {
+      stdio: 'inherit'
+    });
+
+    tail.on('error', (error) => {
+      console.error('Failed to tail logs:', error.message);
+      process.exit(1);
+    });
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Show version
+ */
+function showVersion() {
+  console.log(`gsd-agent v${VERSION}`);
+}
+
+/**
+ * Main CLI entry point
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  // Parse options
+  const options = {};
+  for (let i = 1; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const value = args[i + 1];
+      if (value && !value.startsWith('--')) {
+        options[key] = value;
+        i++;
+      } else {
+        options[key] = true;
+      }
+    }
+  }
+
+  switch (command) {
+    case 'auth':
+      await runAuth();
+      break;
+    case 'start':
+      startAgent();
+      break;
+    case 'status':
+      showStatus();
+      break;
+    case 'disconnect':
+      disconnect();
+      break;
+    case 'logs':
+      showLogs(options);
+      break;
+    case 'version':
+      showVersion();
+      break;
+    case '--help':
+    case '-h':
+    case 'help':
+      showHelp();
+      break;
+    default:
+      if (!command) {
+        showHelp();
+      } else {
+        console.log(`Unknown command: ${command}\n`);
+        showHelp();
+      }
+      process.exit(1);
+  }
+}
+
+// Run CLI
+main().catch((error) => {
+  console.error('Fatal error:', error.message);
+  process.exit(1);
+});

package/dist/auth-flow.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Device flow authentication for GSD Agent
+ *
+ * Implements device code flow similar to GitHub CLI:
+ * 1. Agent generates device code and user code
+ * 2. Agent displays instructions to visit web UI with user code
+ * 3. User enters code on web UI and authorizes the agent
+ * 4. Agent polls for authorization status
+ * 5. Agent exchanges device code for user tokens
+ * 6. Agent stores credentials and starts syncing
+ */
+export declare class DeviceAuthFlow {
+    private config;
+    private logger;
+    private supabase;
+    constructor();
+    /**
+     * Generate a random device code (8 characters)
+     */
+    private generateDeviceCode;
+    /**
+     * Generate a user-friendly code (formatted as XXXX-YYYY)
+     */
+    private generateUserCode;
+    /**
+     * Start the device authorization flow
+     */
+    startAuthFlow(): Promise<boolean>;
+    /**
+     * Poll for authorization status
+     */
+    private pollForAuthorization;
+    /**
+     * Generate tokens for authorized user
+     */
+    private generateUserTokens;
+    /**
+     * Check if agent is already authenticated
+     */
+    static isAuthenticated(): boolean;
+    /**
+     * Clear authentication credentials
+     */
+    static clearAuth(): Promise<boolean>;
+}
+/**
+ * Main function to handle authentication command
+ */
+export declare function authenticateAgent(): Promise<boolean>;
+//# sourceMappingURL=auth-flow.d.ts.map

package/dist/auth-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-flow.d.ts","sourceRoot":"","sources":["../src/auth-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyBH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,QAAQ,CAAM;;IAetB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAiFvC;;OAEG;YACW,oBAAoB;IAyClC;;OAEG;YACW,kBAAkB;IAqBhC;;OAEG;IACH,MAAM,CAAC,eAAe,IAAI,OAAO;IAwBjC;;OAEG;WACU,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAY3C;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC,CAG1D"}