@eddacraft/anvil-runtime 0.1.0

package/dist/watch/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Watch Module
+ *
+ * File watching functionality for real-time validation and gating.
+ */
+export { WatchConfigSchema, WatchGitConfigSchema, parseWatchConfig, getDefaultWatchConfig, DEFAULT_WATCH_PATTERNS, DEFAULT_EXCLUDE_PATTERNS, } from './types.js';
+export type { WatchConfig, WatchGitConfig, GitFileStatus, WatchChangeEvent, DebouncedChanges, WatchStatusEvent, WatchStatusEventType, WatchActionResult, WatchOrchestratorOptions, MultiAgentConfig, } from './types.js';
+export { GitStatusChecker, createGitStatusChecker, getChangedFiles } from './git-status.js';
+export type { GetChangedFilesOptions } from './git-status.js';
+export { ChangeDebouncer, createDebouncer } from './debouncer.js';
+export type { DebouncerFlushCallback } from './debouncer.js';
+export { FileWatcher, createFileWatcher } from './file-watcher.js';
+export type { FileWatcherOptions, FileWatcherEvents } from './file-watcher.js';
+export { WatchOrchestrator, createWatchOrchestrator } from './orchestrator.js';
+export type { ActionHandler } from './orchestrator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/watch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/watch/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,WAAW,EACX,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC5F,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACnE,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG/E,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/watch/index.js

@@ -0,0 +1,15 @@
+/**
+ * Watch Module
+ *
+ * File watching functionality for real-time validation and gating.
+ */
+// Types and schemas
+export { WatchConfigSchema, WatchGitConfigSchema, parseWatchConfig, getDefaultWatchConfig, DEFAULT_WATCH_PATTERNS, DEFAULT_EXCLUDE_PATTERNS, } from './types.js';
+// Git status checker
+export { GitStatusChecker, createGitStatusChecker, getChangedFiles } from './git-status.js';
+// Debouncer
+export { ChangeDebouncer, createDebouncer } from './debouncer.js';
+// File watcher
+export { FileWatcher, createFileWatcher } from './file-watcher.js';
+// Orchestrator
+export { WatchOrchestrator, createWatchOrchestrator } from './orchestrator.js';

package/dist/watch/orchestrator.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Watch Orchestrator
+ *
+ * Coordinates file watching, git filtering, debouncing, and action dispatch.
+ * This is the main entry point for watch mode functionality.
+ *
+ * Multi-Agent Support:
+ * - Acquires workspace-level watch lock to prevent multiple watchers
+ * - Coordinates action execution through lock manager
+ * - Registers agent and maintains heartbeat
+ */
+import type { WatchOrchestratorOptions, WatchActionResult } from './types.js';
+/**
+ * Action handler type
+ */
+export type ActionHandler = (files: string[]) => Promise<WatchActionResult>;
+/**
+ * Watch orchestrator
+ *
+ * Coordinates all watch components and dispatches actions.
+ * Supports multi-agent coordination with distributed locking.
+ */
+export declare class WatchOrchestrator {
+    private fileWatcher;
+    private gitChecker;
+    private debouncer;
+    private config;
+    private workspaceRoot;
+    private onEvent?;
+    private verbose;
+    private isRunning;
+    private isGitRepo;
+    private multiAgentConfig;
+    private concurrencyContext;
+    private validateHandler?;
+    private gateHandler?;
+    private checkHandler?;
+    private stats;
+    constructor(options: WatchOrchestratorOptions);
+    /**
+     * Set the validate action handler
+     */
+    setValidateHandler(handler: ActionHandler): void;
+    /**
+     * Set the gate action handler
+     */
+    setGateHandler(handler: ActionHandler): void;
+    /**
+     * Set the check action handler (for source file analysis)
+     */
+    setCheckHandler(handler: ActionHandler): void;
+    /**
+     * Start watching
+     */
+    start(): Promise<void>;
+    /**
+     * Initialize multi-agent coordination
+     */
+    private initializeMultiAgent;
+    /**
+     * Stop watching
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the agent ID (if multi-agent is enabled)
+     */
+    getAgentId(): string | undefined;
+    /**
+     * Get current statistics
+     */
+    getStats(): typeof this.stats;
+    /**
+     * Check if orchestrator is running
+     */
+    get running(): boolean;
+    /**
+     * Handle file change event from watcher
+     */
+    private handleFileChange;
+    /**
+     * Handle debounced batch of changes
+     */
+    private handleDebouncedChanges;
+    /**
+     * Run the configured action
+     */
+    private runAction;
+    /**
+     * Run action with multi-agent coordination (locking/queuing)
+     */
+    private runCoordinatedAction;
+    /**
+     * Run action directly without coordination
+     */
+    private runDirectAction;
+    /**
+     * Handle watcher ready event
+     */
+    private handleReady;
+    /**
+     * Handle watcher error
+     */
+    private handleError;
+    /**
+     * Emit status event
+     */
+    private emitEvent;
+}
+/**
+ * Create a watch orchestrator
+ */
+export declare function createWatchOrchestrator(options: WatchOrchestratorOptions): WatchOrchestrator;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/watch/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/watch/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAEV,wBAAwB,EAExB,iBAAiB,EAIlB,MAAM,YAAY,CAAC;AAUpB;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAc5E;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAC,CAAoC;IACpD,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,kBAAkB,CAAmC;IAG7D,OAAO,CAAC,eAAe,CAAC,CAAgB;IACxC,OAAO,CAAC,WAAW,CAAC,CAAgB;IACpC,OAAO,CAAC,YAAY,CAAC,CAAgB;IAGrC,OAAO,CAAC,KAAK,CAQX;gBAEU,OAAO,EAAE,wBAAwB;IAkB7C;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAIhD;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAI5C;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI;IAI7C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqC5B;;OAEG;YACW,oBAAoB;IAyElC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B;;OAEG;IACH,UAAU,IAAI,MAAM,GAAG,SAAS;IAIhC;;OAEG;IACH,QAAQ,IAAI,OAAO,IAAI,CAAC,KAAK;IAI7B;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;OAEG;YACW,sBAAsB;IAiCpC;;OAEG;YACW,SAAS;IAkCvB;;OAEG;YACW,oBAAoB;IAgDlC;;OAEG;YACW,eAAe;IA8C7B;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,OAAO,CAAC,SAAS;CAGlB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAE5F"}

package/dist/watch/orchestrator.js

@@ -0,0 +1,409 @@
+/**
+ * Watch Orchestrator
+ *
+ * Coordinates file watching, git filtering, debouncing, and action dispatch.
+ * This is the main entry point for watch mode functionality.
+ *
+ * Multi-Agent Support:
+ * - Acquires workspace-level watch lock to prevent multiple watchers
+ * - Coordinates action execution through lock manager
+ * - Registers agent and maintains heartbeat
+ */
+import { FileWatcher } from './file-watcher.js';
+import { GitStatusChecker } from './git-status.js';
+import { ChangeDebouncer } from './debouncer.js';
+import { createConcurrencyContext, createAgentInfo, } from '../concurrency/index.js';
+import { createDebugger } from '@eddacraft/anvil-core';
+const debug = createDebugger('watch');
+/**
+ * Default multi-agent configuration
+ */
+const DEFAULT_MULTI_AGENT_CONFIG = {
+    enabled: true,
+    exclusiveWatch: true,
+    coordinatedActions: true,
+    agentId: '',
+    waitForLock: true,
+    lockWaitTimeoutMs: 30000,
+};
+/**
+ * Watch orchestrator
+ *
+ * Coordinates all watch components and dispatches actions.
+ * Supports multi-agent coordination with distributed locking.
+ */
+export class WatchOrchestrator {
+    fileWatcher;
+    gitChecker;
+    debouncer;
+    config;
+    workspaceRoot;
+    onEvent;
+    verbose;
+    isRunning = false;
+    isGitRepo = false;
+    // Multi-agent support
+    multiAgentConfig;
+    concurrencyContext = null;
+    // Action handlers
+    validateHandler;
+    gateHandler;
+    checkHandler;
+    // Statistics
+    stats = {
+        changesDetected: 0,
+        changesFiltered: 0,
+        actionsRun: 0,
+        actionsPassed: 0,
+        actionsFailed: 0,
+        actionsQueued: 0,
+        lockWaits: 0,
+    };
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.config = options.config;
+        this.onEvent = options.onEvent;
+        this.verbose = options.verbose ?? false;
+        this.multiAgentConfig = {
+            ...DEFAULT_MULTI_AGENT_CONFIG,
+            ...options.multiAgent,
+        };
+        this.fileWatcher = new FileWatcher();
+        this.gitChecker = new GitStatusChecker(options.workspaceRoot);
+        this.debouncer = new ChangeDebouncer(options.config.debounceMs, this.handleDebouncedChanges.bind(this));
+    }
+    /**
+     * Set the validate action handler
+     */
+    setValidateHandler(handler) {
+        this.validateHandler = handler;
+    }
+    /**
+     * Set the gate action handler
+     */
+    setGateHandler(handler) {
+        this.gateHandler = handler;
+    }
+    /**
+     * Set the check action handler (for source file analysis)
+     */
+    setCheckHandler(handler) {
+        this.checkHandler = handler;
+    }
+    /**
+     * Start watching
+     */
+    async start() {
+        debug(`orchestrator start`, { workspace: this.workspaceRoot, action: this.config.action });
+        if (this.isRunning) {
+            throw new Error('Watch orchestrator is already running');
+        }
+        // Initialize multi-agent coordination if enabled
+        if (this.multiAgentConfig.enabled) {
+            debug('orchestrator start: initializing multi-agent coordination');
+            await this.initializeMultiAgent();
+        }
+        // Check if we're in a git repository
+        this.isGitRepo = await this.gitChecker.isGitRepository();
+        debug(`orchestrator start: isGitRepo=${this.isGitRepo}`);
+        if (!this.isGitRepo && this.config.git.unstagedOnly) {
+            console.warn('Warning: Not a git repository. Git filtering disabled, watching all file changes.');
+        }
+        // Set up file watcher events
+        this.fileWatcher.on('change', this.handleFileChange.bind(this));
+        this.fileWatcher.on('error', this.handleError.bind(this));
+        this.fileWatcher.on('ready', this.handleReady.bind(this));
+        // Start watching
+        await this.fileWatcher.start({
+            patterns: this.config.patterns,
+            exclude: this.config.exclude,
+            cwd: this.workspaceRoot,
+        });
+        this.isRunning = true;
+    }
+    /**
+     * Initialize multi-agent coordination
+     */
+    async initializeMultiAgent() {
+        try {
+            // Create concurrency context, honouring custom agent ID if provided
+            this.concurrencyContext = await createConcurrencyContext({
+                workspaceRoot: this.workspaceRoot,
+                autoRegister: true,
+                autoHeartbeat: true,
+                ...(this.multiAgentConfig.agentId
+                    ? { agentInfo: createAgentInfo({ id: this.multiAgentConfig.agentId }) }
+                    : {}),
+            });
+            // Acquire exclusive watch lock if configured
+            if (this.multiAgentConfig.exclusiveWatch) {
+                const lockResult = await this.concurrencyContext.queue.waitForLock({
+                    type: 'watch',
+                    resource: 'workspace',
+                    reason: 'Starting file watch mode',
+                    maxWaitMs: this.multiAgentConfig.waitForLock
+                        ? this.multiAgentConfig.lockWaitTimeoutMs
+                        : 0,
+                    onPositionChange: (position, _total) => {
+                        this.stats.lockWaits++;
+                        this.emitEvent({
+                            type: 'lock:waiting',
+                            resource: 'watch:workspace',
+                            heldBy: 'another-agent',
+                            queuePosition: position,
+                        });
+                    },
+                });
+                if (!lockResult.acquired) {
+                    // Clean up context
+                    await this.concurrencyContext.cleanup();
+                    this.concurrencyContext = null;
+                    const error = `Cannot start watch mode: ${lockResult.error || 'Lock held by another agent'}`;
+                    if (lockResult.heldBy) {
+                        this.emitEvent({
+                            type: 'lock:denied',
+                            resource: 'watch:workspace',
+                            heldBy: lockResult.heldBy.agentId,
+                            reason: `Lock expires at ${lockResult.heldBy.expiresAt}`,
+                        });
+                    }
+                    throw new Error(error);
+                }
+                // Start auto-renewal for watch lock
+                this.concurrencyContext.locks.startAutoRenewal('watch', 'workspace');
+                this.emitEvent({
+                    type: 'lock:acquired',
+                    resource: 'watch:workspace',
+                    agentId: this.concurrencyContext.agent.getAgentId(),
+                });
+            }
+            // Update agent operation
+            await this.concurrencyContext.agent.setOperation('watching');
+        }
+        catch (error) {
+            // Clean up on error
+            if (this.concurrencyContext) {
+                await this.concurrencyContext.cleanup();
+                this.concurrencyContext = null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Stop watching
+     */
+    async stop() {
+        debug(`orchestrator stop: running=${this.isRunning}`);
+        if (!this.isRunning) {
+            return;
+        }
+        this.debouncer.cancel();
+        await this.fileWatcher.stop();
+        // Clean up multi-agent coordination
+        if (this.concurrencyContext) {
+            await this.concurrencyContext.cleanup();
+            this.concurrencyContext = null;
+        }
+        this.isRunning = false;
+        this.emitEvent({ type: 'stopped' });
+    }
+    /**
+     * Get the agent ID (if multi-agent is enabled)
+     */
+    getAgentId() {
+        return this.concurrencyContext?.agent.getAgentId();
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Check if orchestrator is running
+     */
+    get running() {
+        return this.isRunning;
+    }
+    /**
+     * Handle file change event from watcher
+     */
+    handleFileChange(event) {
+        // Only process add and change events (not unlink)
+        if (event.type === 'unlink') {
+            debug(`orchestrator: ignoring unlink event for ${event.path}`);
+            return;
+        }
+        debug(`orchestrator: file ${event.type} ${event.path}`);
+        this.stats.changesDetected++;
+        this.debouncer.add(event.path);
+    }
+    /**
+     * Handle debounced batch of changes
+     */
+    async handleDebouncedChanges(changes) {
+        debug(`orchestrator: debounced batch of ${changes.files.length} files`);
+        let filesToProcess = changes.files;
+        // Apply git filter if enabled and in git repo
+        if (this.isGitRepo && this.config.git.unstagedOnly) {
+            filesToProcess = await this.gitChecker.filterUnstaged(changes.files, this.config.git.includeUntracked);
+        }
+        this.stats.changesFiltered += changes.files.length - filesToProcess.length;
+        // Emit change event
+        this.emitEvent({
+            type: 'change',
+            files: changes.files,
+            filtered: filesToProcess,
+        });
+        // Skip if all files were filtered out
+        if (filesToProcess.length === 0) {
+            if (this.verbose) {
+                console.warn('All changed files were filtered out (staged or excluded)');
+            }
+            return;
+        }
+        // Run the configured action
+        await this.runAction(filesToProcess);
+    }
+    /**
+     * Run the configured action
+     */
+    async runAction(files) {
+        const action = this.config.action;
+        debug(`orchestrator runAction`, { action, files: files.length });
+        let handler;
+        switch (action) {
+            case 'validate':
+                handler = this.validateHandler;
+                break;
+            case 'gate':
+                handler = this.gateHandler;
+                break;
+            case 'check':
+                handler = this.checkHandler;
+                break;
+        }
+        if (!handler) {
+            console.warn(`No handler registered for action: ${action}`);
+            return;
+        }
+        // Use coordinated action execution if enabled
+        if (this.multiAgentConfig.enabled &&
+            this.multiAgentConfig.coordinatedActions &&
+            this.concurrencyContext) {
+            await this.runCoordinatedAction(action, handler, files);
+        }
+        else {
+            await this.runDirectAction(action, handler, files);
+        }
+    }
+    /**
+     * Run action with multi-agent coordination (locking/queuing)
+     */
+    async runCoordinatedAction(action, handler, files) {
+        if (!this.concurrencyContext) {
+            return this.runDirectAction(action, handler, files);
+        }
+        const resource = `action:${action}`;
+        // Try to acquire action lock with queuing
+        const lockResult = await this.concurrencyContext.queue.waitForLock({
+            type: 'action',
+            resource,
+            reason: `Running ${action} on ${files.length} files`,
+            maxWaitMs: 60000, // Wait up to 60s for action lock
+            onPositionChange: (position, _total) => {
+                this.stats.actionsQueued++;
+                this.emitEvent({
+                    type: 'action:queued',
+                    action,
+                    position,
+                    files,
+                });
+            },
+        });
+        if (!lockResult.acquired) {
+            this.emitEvent({
+                type: 'action:error',
+                error: new Error(`Could not acquire action lock: ${lockResult.error}`),
+                files,
+            });
+            return;
+        }
+        try {
+            // Update agent operation
+            await this.concurrencyContext.agent.setOperation(`running:${action}`);
+            await this.runDirectAction(action, handler, files);
+        }
+        finally {
+            await this.concurrencyContext.locks.release('action', resource);
+            await this.concurrencyContext.agent.setOperation('watching');
+        }
+    }
+    /**
+     * Run action directly without coordination
+     */
+    async runDirectAction(action, handler, files) {
+        debug(`orchestrator runDirectAction`, { action, files: files.length });
+        this.stats.actionsRun++;
+        this.emitEvent({
+            type: 'action:start',
+            action,
+            files,
+        });
+        try {
+            const startTime = Date.now();
+            const result = await handler(files);
+            result.executionTimeMs = Date.now() - startTime;
+            if (result.success) {
+                this.stats.actionsPassed++;
+                debug(`orchestrator action passed`, { action, elapsed: result.executionTimeMs });
+            }
+            else {
+                this.stats.actionsFailed++;
+                debug(`orchestrator action failed`, { action, elapsed: result.executionTimeMs });
+            }
+            this.emitEvent({
+                type: 'action:complete',
+                result,
+            });
+        }
+        catch (error) {
+            this.stats.actionsFailed++;
+            debug(`orchestrator action error: action=${action}`, error instanceof Error ? error : String(error));
+            this.emitEvent({
+                type: 'action:error',
+                error: error instanceof Error ? error : new Error(String(error)),
+                files,
+            });
+        }
+    }
+    /**
+     * Handle watcher ready event
+     */
+    handleReady() {
+        this.emitEvent({
+            type: 'ready',
+            patterns: this.config.patterns,
+            gitFilter: this.isGitRepo && this.config.git.unstagedOnly,
+            agentId: this.concurrencyContext?.agent.getAgentId(),
+        });
+    }
+    /**
+     * Handle watcher error
+     */
+    handleError(error) {
+        console.error('Watch error:', error.message);
+    }
+    /**
+     * Emit status event
+     */
+    emitEvent(event) {
+        this.onEvent?.(event);
+    }
+}
+/**
+ * Create a watch orchestrator
+ */
+export function createWatchOrchestrator(options) {
+    return new WatchOrchestrator(options);
+}