gsd-agent 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Core type definitions for GSD Agent
+ *
+ * These types define the data structures used throughout the agent for
+ * workspace management, file change tracking, and synchronization.
+ */
+/**
+ * Workspace represents a discovered GSD project
+ *
+ * Each workspace corresponds to a directory containing a .planning/ folder.
+ * The agent tracks multiple workspaces and syncs their files independently.
+ */
+export interface Workspace {
+    /** Unique identifier for the workspace */
+    id: string;
+    /** Absolute path to the workspace root directory */
+    root_path: string;
+    /** Human-readable name (derived from directory name) */
+    name: string;
+    /** Current workspace status */
+    status: 'active' | 'paused' | 'archived';
+    /** ISO timestamp of last successful sync */
+    last_sync: string;
+    /** ISO timestamp when workspace was first discovered */
+    discovered_at: string;
+}
+/**
+ * FileChangeEvent represents a single file system change
+ *
+ * Events are generated by the filesystem watcher and queued for sync to Supabase.
+ * Each event captures the file state at the time of change.
+ */
+export interface FileChangeEvent {
+    /** Unique identifier for this event */
+    id: string;
+    /** Reference to the workspace this file belongs to */
+    workspace_id: string;
+    /** File path relative to workspace root (e.g., ".planning/STATE.md") */
+    file_path: string;
+    /** Type of filesystem event */
+    event_type: 'add' | 'change' | 'unlink';
+    /** SHA-256 hash of file content (for deduplication) */
+    content_hash: string;
+    /** File content (null for unlink events) */
+    content?: string;
+    /** Source of the change */
+    source: 'cli' | 'web' | 'sync';
+    /** ISO timestamp when event occurred */
+    timestamp: string;
+    /** Additional metadata about the file */
+    metadata: {
+        /** File size in bytes */
+        size: number;
+        /** ISO timestamp of file modification time */
+        mtime: string;
+        /** Agent version that generated this event */
+        agent_version: string;
+    };
+}
+/**
+ * SyncConfig defines agent configuration
+ *
+ * Configuration is loaded from ~/.gsd-agent/config.json with fallback to defaults.
+ * All paths are expanded (~ becomes home directory).
+ */
+export interface SyncConfig {
+    /** Supabase project URL */
+    supabase_url: string;
+    /** Supabase service role key (stored securely) */
+    supabase_key: string;
+    /** Parent directories to watch for .planning/ folders */
+    watch_dirs: string[];
+    /** Glob patterns to ignore during watching */
+    ignored_patterns: string[];
+    /** Debounce delay in milliseconds (default: 300) */
+    debounce_ms: number;
+    /** Maximum files per batch sync (default: 50) */
+    batch_size: number;
+    /** Logging level */
+    log_level: 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';
+    /** Path to log file */
+    log_file: string;
+    /** Number of days to keep log files (default: 7) */
+    log_rotation_days: number;
+}
+/**
+ * AgentState represents the runtime state of the agent
+ *
+ * This is the in-memory state maintained during agent execution.
+ * Not persisted to disk (workspaces are persisted separately).
+ */
+export interface AgentState {
+    /** Map of workspace ID to workspace metadata */
+    workspaces: Map<string, Workspace>;
+    /** Queue of pending file change events awaiting sync */
+    sync_queue: FileChangeEvent[];
+    /** Whether a sync operation is currently in progress */
+    is_syncing: boolean;
+    /** ISO timestamp of last heartbeat sent to Supabase */
+    last_heartbeat: string;
+}
+/**
+ * RemoteChangeEvent represents a file change from Supabase Realtime
+ *
+ * These events come from the web UI or other agents modifying files.
+ * The agent must apply these changes to the local filesystem.
+ */
+export interface RemoteChangeEvent {
+    /** Database record ID */
+    id: string;
+    /** Reference to the workspace this file belongs to */
+    workspace_id: string;
+    /** File path relative to workspace root */
+    file_path: string;
+    /** File content (null for large files in Storage) */
+    content: string | null;
+    /** SHA-256 hash of file content */
+    content_hash: string;
+    /** File size in bytes */
+    size: number;
+    /** ISO timestamp when remote change occurred */
+    updated_at: string;
+    /** Storage URL for large files (>200KB) */
+    storage_url?: string;
+}
+/**
+ * ConflictEvent represents a detected conflict between local and remote versions
+ *
+ * Conflict occurs when both local and remote versions changed since last sync.
+ * Agent creates git-style conflict markers and commits the conflicted file.
+ */
+export interface ConflictEvent {
+    /** Reference to the workspace */
+    workspace_id: string;
+    /** File path relative to workspace root */
+    file_path: string;
+    /** SHA-256 hash of local version */
+    local_hash: string;
+    /** SHA-256 hash of remote version */
+    remote_hash: string;
+    /** Local file content */
+    local_content: string;
+    /** Remote file content */
+    remote_content: string;
+    /** ISO timestamp when conflict detected */
+    detected_at: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core type definitions for GSD Agent
+ *
+ * These types define the data structures used throughout the agent for
+ * workspace management, file change tracking, and synchronization.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for type definitions
+ *
+ * Validates that new types compile correctly and have expected structure.
+ */
+export {};
+//# sourceMappingURL=types.test.d.ts.map

package/dist/types.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test.d.ts","sourceRoot":"","sources":["../src/types.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/types.test.js

@@ -0,0 +1,73 @@
+/**
+ * Tests for type definitions
+ *
+ * Validates that new types compile correctly and have expected structure.
+ */
+import { describe, it, expect } from 'vitest';
+describe('RemoteChangeEvent type', () => {
+    it('should compile with all required fields', () => {
+        const event = {
+            id: 'evt_123',
+            workspace_id: 'ws_456',
+            file_path: '.planning/STATE.md',
+            content: '# State content',
+            content_hash: 'abc123',
+            size: 1024,
+            updated_at: '2026-03-27T01:00:00Z'
+        };
+        expect(event.id).toBe('evt_123');
+        expect(event.workspace_id).toBe('ws_456');
+        expect(event.file_path).toBe('.planning/STATE.md');
+        expect(event.content).toBe('# State content');
+        expect(event.content_hash).toBe('abc123');
+        expect(event.size).toBe(1024);
+        expect(event.updated_at).toBe('2026-03-27T01:00:00Z');
+    });
+    it('should allow null content for large files', () => {
+        const event = {
+            id: 'evt_789',
+            workspace_id: 'ws_456',
+            file_path: '.planning/large-file.md',
+            content: null,
+            content_hash: 'def456',
+            size: 300000,
+            updated_at: '2026-03-27T01:00:00Z',
+            storage_url: 'https://storage.supabase.co/bucket/file.md'
+        };
+        expect(event.content).toBeNull();
+        expect(event.storage_url).toBe('https://storage.supabase.co/bucket/file.md');
+    });
+    it('should allow optional storage_url', () => {
+        const event = {
+            id: 'evt_999',
+            workspace_id: 'ws_456',
+            file_path: '.planning/small.md',
+            content: 'small content',
+            content_hash: 'ghi789',
+            size: 100,
+            updated_at: '2026-03-27T01:00:00Z'
+        };
+        expect(event.storage_url).toBeUndefined();
+    });
+});
+describe('ConflictEvent type', () => {
+    it('should compile with all required fields', () => {
+        const conflict = {
+            workspace_id: 'ws_456',
+            file_path: '.planning/PROJECT.md',
+            local_hash: 'local_abc',
+            remote_hash: 'remote_def',
+            local_content: 'Local version',
+            remote_content: 'Remote version',
+            detected_at: '2026-03-27T01:30:00Z'
+        };
+        expect(conflict.workspace_id).toBe('ws_456');
+        expect(conflict.file_path).toBe('.planning/PROJECT.md');
+        expect(conflict.local_hash).toBe('local_abc');
+        expect(conflict.remote_hash).toBe('remote_def');
+        expect(conflict.local_content).toBe('Local version');
+        expect(conflict.remote_content).toBe('Remote version');
+        expect(conflict.detected_at).toBe('2026-03-27T01:30:00Z');
+    });
+});
+//# sourceMappingURL=types.test.js.map

package/dist/types.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.test.js","sourceRoot":"","sources":["../src/types.test.ts"],"names":[],"mappings":"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"}

package/dist/watcher.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Filesystem watcher for GSD Agent
+ *
+ * Watches .planning/ directories for file changes using chokidar.
+ * Handles atomic writes, debouncing, and ignored patterns per research findings.
+ */
+import { EventEmitter } from 'events';
+import { Workspace, SyncConfig } from './types.js';
+import { Logger } from './logger.js';
+/**
+ * FileWatcher class monitors .planning/ directories for changes
+ */
+export declare class FileWatcher extends EventEmitter {
+    private workspaces;
+    private config;
+    private logger;
+    private watcher;
+    private debounceTimers;
+    constructor(workspaces: Workspace[], config: SyncConfig, logger: Logger);
+    /**
+     * Start watching all workspace .planning/ directories
+     */
+    start(): void;
+    /**
+     * Stop watching and clean up
+     */
+    stop(): void;
+    /**
+     * Handle file system events with debouncing
+     * @param filePath Absolute path to changed file
+     * @param eventType Type of change event
+     */
+    private handleFileEvent;
+    /**
+     * Process a file event and emit FileChangeEvent
+     * @param filePath Absolute path to changed file
+     * @param eventType Type of change event
+     */
+    private processFileEvent;
+    /**
+     * Find workspace that contains the given file path
+     * @param filePath Absolute path to file
+     * @returns Workspace object or null if not found
+     */
+    private findWorkspaceForFile;
+}
+/**
+ * Create and start a filesystem watcher
+ * @param workspaces Array of workspaces to watch
+ * @param config SyncConfig with watch settings
+ * @param logger Logger instance
+ * @returns FileWatcher instance
+ */
+export declare function createWatcher(workspaces: Workspace[], config: SyncConfig, logger: Logger): FileWatcher;
+//# sourceMappingURL=watcher.d.ts.map

package/dist/watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC;;GAEG;AACH,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,cAAc,CAAyC;gBAEnD,UAAU,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM;IAOvE;;OAEG;IACH,KAAK,IAAI,IAAI;IA2Db;;OAEG;IACH,IAAI,IAAI,IAAI;IAeZ;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;;OAIG;YACW,gBAAgB;IAmE9B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;CAQ7B;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,SAAS,EAAE,EACvB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,WAAW,CAIb"}

package/dist/watcher.js

@@ -0,0 +1,214 @@
+/**
+ * Filesystem watcher for GSD Agent
+ *
+ * Watches .planning/ directories for file changes using chokidar.
+ * Handles atomic writes, debouncing, and ignored patterns per research findings.
+ */
+import chokidar from 'chokidar';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import { EventEmitter } from 'events';
+import { hashFile } from './hash.js';
+/**
+ * FileWatcher class monitors .planning/ directories for changes
+ */
+export class FileWatcher extends EventEmitter {
+    workspaces;
+    config;
+    logger;
+    watcher = null;
+    debounceTimers = new Map();
+    constructor(workspaces, config, logger) {
+        super();
+        this.workspaces = workspaces;
+        this.config = config;
+        this.logger = logger;
+    }
+    /**
+     * Start watching all workspace .planning/ directories
+     */
+    start() {
+        if (this.watcher) {
+            this.logger.warn('Watcher already started');
+            return;
+        }
+        // Build list of paths to watch
+        const watchPaths = this.workspaces.map(ws => path.join(ws.root_path, '.planning'));
+        // Filter out non-existent paths
+        const existingPaths = watchPaths.filter(p => {
+            if (!fs.existsSync(p)) {
+                this.logger.warn(`Watch path does not exist: ${p}`);
+                return false;
+            }
+            return true;
+        });
+        if (existingPaths.length === 0) {
+            this.logger.warn('No valid watch paths found');
+            return;
+        }
+        // Configure chokidar with atomic write handling and ignored patterns
+        this.watcher = chokidar.watch(existingPaths, {
+            ignored: [
+                /node_modules/,
+                /\.git/,
+                /dist/,
+                /build/,
+                /\.log$/,
+                /\.DS_Store$/
+            ],
+            persistent: true,
+            ignoreInitial: false, // emit events for existing files on startup
+            awaitWriteFinish: {
+                stabilityThreshold: 300, // wait 300ms for file size to stabilize
+                pollInterval: 100
+            },
+            atomic: true, // filter atomic write temp files
+            depth: 5 // limit recursion depth
+        });
+        // Set up event handlers
+        this.watcher
+            .on('add', (filePath) => this.handleFileEvent(filePath, 'add'))
+            .on('change', (filePath) => this.handleFileEvent(filePath, 'change'))
+            .on('unlink', (filePath) => this.handleFileEvent(filePath, 'unlink'))
+            .on('error', (error) => {
+            this.logger.error('Watcher error', { error });
+        })
+            .on('ready', () => {
+            this.logger.info('Filesystem watcher ready', {
+                paths: existingPaths,
+                workspaces: this.workspaces.length
+            });
+        });
+    }
+    /**
+     * Stop watching and clean up
+     */
+    stop() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        // Clear all pending debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        this.logger.info('Filesystem watcher stopped');
+    }
+    /**
+     * Handle file system events with debouncing
+     * @param filePath Absolute path to changed file
+     * @param eventType Type of change event
+     */
+    handleFileEvent(filePath, eventType) {
+        // For unlink events, emit immediately (no debounce)
+        if (eventType === 'unlink') {
+            void this.processFileEvent(filePath, eventType);
+            return;
+        }
+        // For add/change events, debounce to handle rapid changes
+        const existingTimer = this.debounceTimers.get(filePath);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+        const timer = setTimeout(() => {
+            this.debounceTimers.delete(filePath);
+            void this.processFileEvent(filePath, eventType);
+        }, this.config.debounce_ms);
+        this.debounceTimers.set(filePath, timer);
+    }
+    /**
+     * Process a file event and emit FileChangeEvent
+     * @param filePath Absolute path to changed file
+     * @param eventType Type of change event
+     */
+    async processFileEvent(filePath, eventType) {
+        try {
+            // Find workspace for this file
+            const workspace = this.findWorkspaceForFile(filePath);
+            if (!workspace) {
+                this.logger.warn(`No workspace found for file: ${filePath}`);
+                return;
+            }
+            // Compute relative path from workspace root
+            const relativePath = path.relative(workspace.root_path, filePath);
+            // Build FileChangeEvent
+            let contentHash = '';
+            let content;
+            let metadata;
+            if (eventType !== 'unlink') {
+                try {
+                    // Read file content and compute hash
+                    content = fs.readFileSync(filePath, 'utf-8');
+                    contentHash = await hashFile(filePath);
+                    // Get file stats
+                    const stats = fs.statSync(filePath);
+                    metadata = {
+                        size: stats.size,
+                        mtime: stats.mtime.toISOString(),
+                        agent_version: '0.1.0'
+                    };
+                }
+                catch (error) {
+                    this.logger.error(`Failed to read file: ${filePath}`, { error });
+                    return;
+                }
+            }
+            else {
+                // For unlink events, no content or metadata
+                metadata = {
+                    size: 0,
+                    mtime: new Date().toISOString(),
+                    agent_version: '0.1.0'
+                };
+            }
+            const event = {
+                id: randomUUID(),
+                workspace_id: workspace.id,
+                file_path: relativePath,
+                event_type: eventType,
+                content_hash: contentHash,
+                content,
+                source: 'cli',
+                timestamp: new Date().toISOString(),
+                metadata
+            };
+            // Emit the event
+            this.emit('change', event);
+            this.logger.debug(`File event processed: ${eventType} ${relativePath}`, {
+                workspace_id: workspace.id,
+                content_hash: contentHash
+            });
+        }
+        catch (error) {
+            this.logger.error(`Error processing file event: ${filePath}`, { error });
+        }
+    }
+    /**
+     * Find workspace that contains the given file path
+     * @param filePath Absolute path to file
+     * @returns Workspace object or null if not found
+     */
+    findWorkspaceForFile(filePath) {
+        for (const workspace of this.workspaces) {
+            if (filePath.startsWith(workspace.root_path)) {
+                return workspace;
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Create and start a filesystem watcher
+ * @param workspaces Array of workspaces to watch
+ * @param config SyncConfig with watch settings
+ * @param logger Logger instance
+ * @returns FileWatcher instance
+ */
+export function createWatcher(workspaces, config, logger) {
+    const watcher = new FileWatcher(workspaces, config, logger);
+    watcher.start();
+    return watcher;
+}
+//# sourceMappingURL=watcher.js.map

package/dist/watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../src/watcher.ts"],"names":[],"mappings":"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"}

package/dist/watcher.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for filesystem watcher
+ *
+ * Verifies that the watcher detects file changes, debounces events,
+ * handles atomic writes, and ignores excluded patterns.
+ */
+export {};
+//# sourceMappingURL=watcher.test.d.ts.map

package/dist/watcher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher.test.d.ts","sourceRoot":"","sources":["../src/watcher.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}