diff-easy 0.1.0

package/dist/server/file-watcher.d.ts

@@ -0,0 +1,33 @@
+import { type Response } from 'express';
+import { DiffMode, type WatchEvent } from '../types/watch.js';
+export declare class FileWatcherService {
+    private subscriptions;
+    private clients;
+    private debounceTimer;
+    private config;
+    private git;
+    constructor();
+    start(diffMode: DiffMode, watchPath: string, debounceMs?: number, onCacheInvalidate?: () => void): Promise<void>;
+    private setupWatchers;
+    /**
+     * Resolve the actual git directory path, handling git worktrees.
+     * Uses git rev-parse --git-dir which correctly handles both normal repos and worktrees.
+     */
+    private resolveGitDir;
+    private shouldIgnoreEvent;
+    private matchesPattern;
+    private isRelevantGitFile;
+    private debouncedBroadcast;
+    stop(): Promise<void>;
+    addClient(res: Response): void;
+    removeClient(res: Response): void;
+    broadcast(event: WatchEvent): void;
+    private broadcastChange;
+    private sendToClient;
+    private determineChangeType;
+    /**
+     * Return the subset of the given absolute paths that git ignores, using a
+     * single `git check-ignore` invocation rather than one process per path.
+     */
+    private getGitignoredPaths;
+}

package/dist/server/file-watcher.js

@@ -0,0 +1,340 @@
+import { join, resolve } from 'path';
+import { subscribe } from '@parcel/watcher';
+import { simpleGit } from 'simple-git';
+import { DiffMode } from '../types/watch.js';
+// Heavy/generated working-tree directories that are virtually always gitignored.
+// Pre-ignoring them keeps the recursive watcher from registering thousands of
+// watches and from running `git check-ignore` per event when another dev server
+// (e.g. `rails server`, webpack) churns these paths. They're gitignored, so they
+// never appear in diffs anyway — losing live-reload detection for them is moot.
+const COMMON_WORKTREE_IGNORES = [
+    'node_modules/**',
+    'dist/**',
+    'build/**',
+    'out/**',
+    'coverage/**',
+    '.next/**',
+    '.nuxt/**',
+    '.svelte-kit/**',
+    '.turbo/**',
+    '.cache/**',
+    '.parcel-cache/**',
+    'tmp/**',
+    'log/**',
+    'logs/**',
+    'vendor/bundle/**',
+    '.bundle/**',
+    'public/assets/**',
+    'public/packs/**',
+    'public/packs-test/**',
+    'storage/**',
+    'target/**',
+    '__pycache__/**',
+    '.venv/**',
+    'venv/**',
+    '.pytest_cache/**',
+    '.mypy_cache/**',
+];
+const GIT_IGNORES = ['.git/objects/**', '.git/refs/**'];
+const MODE_WATCH_CONFIGS = {
+    [DiffMode.DEFAULT]: {
+        watchPaths: ['.git'],
+        ignore: [...GIT_IGNORES, 'node_modules/**'],
+    },
+    [DiffMode.WORKING]: {
+        watchPaths: ['.', '.git'],
+        ignore: [...GIT_IGNORES, ...COMMON_WORKTREE_IGNORES],
+    },
+    [DiffMode.STAGED]: {
+        watchPaths: ['.git'],
+        ignore: [...GIT_IGNORES],
+    },
+    [DiffMode.DOT]: {
+        watchPaths: ['.', '.git'],
+        // Ignore noisy per-ref reflogs but NOT `.git/logs/HEAD`: it's appended on
+        // every HEAD move (commit / reset / checkout / merge), which is exactly what
+        // must invalidate a `HEAD..'.'` (working-tree / current-branch) diff. Without
+        // it, a commit produced no watch event and the diff went stale.
+        ignore: [
+            ...GIT_IGNORES,
+            '.git/FETCH_HEAD',
+            '.git/ORIG_HEAD',
+            '.git/logs/refs/**',
+            ...COMMON_WORKTREE_IGNORES,
+        ],
+    },
+    [DiffMode.SPECIFIC]: {
+        watchPaths: [], // No watching for specific commits
+        ignore: [],
+    },
+};
+export class FileWatcherService {
+    subscriptions = [];
+    clients = [];
+    debounceTimer = null;
+    config = null;
+    git = null;
+    constructor() { }
+    async start(diffMode, watchPath, debounceMs = 300, onCacheInvalidate) {
+        this.config = { watchPath, diffMode, debounceMs, onCacheInvalidate };
+        // Stop existing watchers
+        await this.stop();
+        // No watching for specific commit comparisons
+        if (diffMode === DiffMode.SPECIFIC) {
+            console.log('🔍 File watching disabled (specific commit comparison)');
+            return;
+        }
+        const modeConfig = MODE_WATCH_CONFIGS[diffMode];
+        // Initialize git instance for .gitignore checking
+        this.git = simpleGit(watchPath);
+        try {
+            await this.setupWatchers(modeConfig, watchPath);
+        }
+        catch (error) {
+            console.error('❌ Failed to start file watcher:', error);
+            throw error;
+        }
+    }
+    async setupWatchers(modeConfig, basePath) {
+        for (const watchPath of modeConfig.watchPaths) {
+            let fullPath = join(basePath, watchPath);
+            // Resolve git worktree path for .git directory
+            if (watchPath === '.git') {
+                fullPath = await this.resolveGitDir(basePath);
+            }
+            // The working-tree ('.') watch must not process .git internals. A repo with
+            // git's fsmonitor daemon enabled churns .git/fsmonitor--daemon/cookies/*
+            // continuously; those events aren't gitignored, so they'd stream into the
+            // handler and perpetually reset the debounce timer — starving the broadcast
+            // so auto-reload never fires (the "stale until restart" bug in large repos).
+            // The dedicated '.git' watch already covers the git-dir files we care about
+            // (HEAD / index / logs/HEAD), so the working-tree watch can ignore .git wholesale.
+            const effectiveIgnore = watchPath === '.' ? [...modeConfig.ignore, '.git/**'] : modeConfig.ignore;
+            try {
+                const subscription = (await subscribe(fullPath, async (err, events) => {
+                    if (err) {
+                        console.error(`Watch error for ${watchPath}:`, err);
+                        return;
+                    }
+                    // First pass: drop events matching the static ignore patterns.
+                    const candidates = events.filter((event) => !this.shouldIgnoreEvent(event.path, effectiveIgnore));
+                    if (candidates.length === 0) {
+                        return;
+                    }
+                    let relevantEvents = candidates;
+                    if (watchPath === '.') {
+                        // Working-tree watch: apply .gitignore with ONE `git check-ignore`
+                        // for all paths, instead of spawning a git process per event —
+                        // otherwise a file-churning build or dev server makes diff-easy
+                        // fork git once per changed file.
+                        const ignored = await this.getGitignoredPaths(candidates.map((event) => event.path), basePath);
+                        relevantEvents = candidates.filter((event) => !ignored.has(event.path));
+                    }
+                    else if (watchPath === '.git') {
+                        // Git-dir watch: only specific files (HEAD/index) matter.
+                        relevantEvents = candidates.filter((event) => {
+                            const fileName = event.path.replace(/.*[/\\]/, '');
+                            return this.isRelevantGitFile(fileName, this.config?.diffMode);
+                        });
+                    }
+                    if (relevantEvents.length > 0) {
+                        this.debouncedBroadcast();
+                    }
+                }, {
+                    ignore: effectiveIgnore,
+                }));
+                this.subscriptions.push(subscription);
+            }
+            catch (error) {
+                console.warn(`⚠️  Could not watch ${fullPath}:`, error);
+                // Continue with other watchers even if one fails
+            }
+        }
+    }
+    /**
+     * Resolve the actual git directory path, handling git worktrees.
+     * Uses git rev-parse --git-dir which correctly handles both normal repos and worktrees.
+     */
+    async resolveGitDir(basePath) {
+        try {
+            const git = simpleGit(basePath);
+            const gitDir = await git.revparse(['--git-dir']);
+            return resolve(basePath, gitDir.trim());
+        }
+        catch {
+            // Fallback to default .git path
+            return join(basePath, '.git');
+        }
+    }
+    shouldIgnoreEvent(filePath, ignorePatterns) {
+        return ignorePatterns.some((pattern) => {
+            // Handle negation patterns (e.g., "!.git/index")
+            if (pattern.startsWith('!')) {
+                const positivePattern = pattern.slice(1);
+                return !this.matchesPattern(filePath, positivePattern);
+            }
+            return this.matchesPattern(filePath, pattern);
+        });
+    }
+    matchesPattern(filePath, pattern) {
+        // Simple glob pattern matching
+        const regex = pattern.replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*');
+        return new RegExp(regex).test(filePath);
+    }
+    isRelevantGitFile(fileName, diffMode) {
+        if (!diffMode)
+            return false;
+        switch (diffMode) {
+            case DiffMode.DEFAULT:
+            case DiffMode.DOT:
+                return fileName === 'HEAD';
+            case DiffMode.WORKING:
+            case DiffMode.STAGED:
+                return fileName === 'index' || fileName === 'HEAD';
+            default:
+                return false;
+        }
+    }
+    debouncedBroadcast() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        const debounceMs = this.config?.debounceMs || 300;
+        this.debounceTimer = setTimeout(() => {
+            // Invalidate cache before broadcasting change
+            if (this.config?.onCacheInvalidate) {
+                this.config.onCacheInvalidate();
+            }
+            this.broadcastChange();
+        }, debounceMs);
+    }
+    async stop() {
+        // Clear debounce timer
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        // Unsubscribe from all watchers
+        await Promise.all(this.subscriptions.map(async (subscription) => {
+            try {
+                await subscription.unsubscribe();
+            }
+            catch (error) {
+                console.warn('Error unsubscribing from file watcher:', error);
+            }
+        }));
+        this.subscriptions = [];
+        // NOTE: do NOT clear `this.clients` here. SSE clients are connection-scoped
+        // — they register in `addClient` on `/api/watch` and are removed in
+        // `removeClient` when that request closes. `stop()` only tears down the
+        // filesystem watchers; it is also called by `start()` on every hub workspace
+        // switch. Clearing clients there would drop the browser's live EventSource
+        // from the broadcast list without closing its stream, so it never gets an
+        // error, never reconnects, and silently stops receiving turn-complete/reload
+        // events — i.e. the agent-turn timeline would stop updating after the first
+        // workspace open. On full shutdown the process exits right after stop(), so
+        // there is nothing to clean up.
+    }
+    addClient(res) {
+        this.clients.push(res);
+        // Send initial connection event
+        this.sendToClient(res, {
+            type: 'connected',
+            diffMode: this.config?.diffMode || DiffMode.DEFAULT,
+            changeType: 'file',
+            timestamp: new Date().toISOString(),
+            message: `Connected to file watcher (${this.config?.diffMode} mode)`,
+        });
+    }
+    removeClient(res) {
+        const index = this.clients.indexOf(res);
+        if (index > -1) {
+            this.clients.splice(index, 1);
+        }
+    }
+    broadcast(event) {
+        if (this.clients.length === 0) {
+            return;
+        }
+        this.clients.forEach((client) => {
+            this.sendToClient(client, event);
+        });
+    }
+    broadcastChange() {
+        if (this.clients.length === 0 || !this.config) {
+            return;
+        }
+        const changeType = this.determineChangeType();
+        const event = {
+            type: 'reload',
+            diffMode: this.config.diffMode,
+            changeType,
+            timestamp: new Date().toISOString(),
+            message: `Changes detected in ${this.config.diffMode} mode`,
+        };
+        this.broadcast(event);
+    }
+    sendToClient(client, event) {
+        try {
+            client.write(`data: ${JSON.stringify(event)}\n\n`);
+        }
+        catch (error) {
+            console.error('Failed to send event to client:', error);
+            this.removeClient(client);
+        }
+    }
+    determineChangeType() {
+        if (!this.config)
+            return 'file';
+        switch (this.config.diffMode) {
+            case DiffMode.DEFAULT:
+            case DiffMode.DOT:
+                return 'commit'; // .git/HEAD changes indicate new commits
+            case DiffMode.STAGED:
+                return 'staging'; // .git/index changes
+            case DiffMode.WORKING:
+                return 'file'; // Both file and staging changes, default to file
+            default:
+                return 'file';
+        }
+    }
+    /**
+     * Return the subset of the given absolute paths that git ignores, using a
+     * single `git check-ignore` invocation rather than one process per path.
+     */
+    async getGitignoredPaths(filePaths, basePath) {
+        const ignored = new Set();
+        if (!this.git || filePaths.length === 0)
+            return ignored;
+        const prefix = `${basePath}/`;
+        const relToAbs = new Map();
+        for (const abs of filePaths) {
+            const rel = abs.startsWith(prefix) ? abs.slice(prefix.length) : abs;
+            relToAbs.set(rel, abs);
+        }
+        const rels = [...relToAbs.keys()];
+        // Chunk the paths so the argv stays well under the OS limit (ARG_MAX): a
+        // single `git check-ignore` with tens of thousands of args (e.g. a branch
+        // switch) would throw E2BIG and we'd lose ignore filtering for the batch.
+        // This still collapses N git spawns to ceil(N / CHUNK).
+        const CHUNK = 1000;
+        for (let i = 0; i < rels.length; i += CHUNK) {
+            const batch = rels.slice(i, i + CHUNK);
+            try {
+                // checkIgnore returns the subset of inputs that are ignored; it throws
+                // (git exits 1) when NONE are ignored — handled as "none" below.
+                const result = await this.git.checkIgnore(batch);
+                for (const rel of result) {
+                    // git may quote paths with special chars (core.quotePath); strip them.
+                    const abs = relToAbs.get(rel) ?? relToAbs.get(rel.replace(/^"(.*)"$/u, '$1'));
+                    if (abs)
+                        ignored.add(abs);
+                }
+            }
+            catch {
+                // None ignored in this batch (or a git error) — treat as not ignored.
+            }
+        }
+        return ignored;
+    }
+}

package/dist/server/generated-file-check.d.ts

@@ -0,0 +1,17 @@
+interface GeneratedCheckResult {
+    isGenerated: boolean;
+    reason?: 'path' | 'universal' | 'language-specific';
+    matchedPattern?: string;
+}
+/**
+ * Checks if a file is generated.
+ * Uses a 3-layer approach:
+ * 1. Path/Filename patterns (fastest, no reading)
+ * 2. Universal header patterns (checks first 20 lines)
+ * 3. Language-specific header patterns (checks first 20 lines)
+ *
+ * @param parsedPath The decoded git path of the file
+ * @param getHeaderLines A function that lazily provides the first 20 lines of the file content
+ */
+export declare function isGeneratedFile(parsedPath: string, getHeaderLines?: () => string[]): GeneratedCheckResult;
+export {};

package/dist/server/generated-file-check.js

@@ -0,0 +1,280 @@
+const EXACT_FILENAMES = new Set([
+    'package-lock.json',
+    'pnpm-lock.yaml',
+    'yarn.lock',
+    'Gemfile.lock',
+    'Pipfile.lock',
+    'composer.lock',
+    'Cargo.lock',
+    'poetry.lock',
+    'go.sum',
+    'go.mod',
+    'pubspec.lock',
+    'flake.lock',
+    'Package.resolved',
+    'packages.lock.json',
+    '.terraform.lock.hcl',
+    'bun.lockb',
+    'gradle.lockfile',
+    'uv.lock',
+    'pdm.lock',
+]);
+const FILENAME_SUFFIXES = [
+    '.min.js',
+    '.min.css',
+    '.bundle.js',
+    '.bundle.css',
+    '-min.js',
+    '.map',
+    '.pb.go',
+    '.pb.rb',
+    '.pb.py',
+    '.pb.js',
+    '.pb.cc',
+    '.pb.h',
+    '.pb2.py',
+    '_pb2.py',
+    '.grpc.pb.go',
+    '_string.go',
+    '.graphql.ts',
+    '.graphql.js',
+    '.openapi.ts',
+    '.openapi.js',
+    '.msw.ts',
+    '.zod.ts',
+    '.api.ts',
+    '.g.dart',
+    '.freezed.dart',
+    '.g.cs',
+    '.designer.cs',
+    '_ide_helper.php',
+];
+const ROOT_PATH_PREFIXES = ['vendor/', 'node_modules/', 'dist/', 'build/', 'out/'];
+const PATH_SEGMENTS = ['/generated/', '/gen/', '/__generated__/'];
+function matchesAnySuffix(fileName, suffixes) {
+    return suffixes.some((suffix) => fileName.endsWith(suffix));
+}
+function isWordCharacter(char) {
+    const code = char.charCodeAt(0);
+    return ((code >= 48 && code <= 57) ||
+        (code >= 65 && code <= 90) ||
+        (code >= 97 && code <= 122) ||
+        code === 95);
+}
+function isWordString(text) {
+    if (text.length === 0) {
+        return false;
+    }
+    for (const char of text) {
+        if (!isWordCharacter(char)) {
+            return false;
+        }
+    }
+    return true;
+}
+function hasGeneratedSuffix(fileName, marker) {
+    const markerIndex = fileName.lastIndexOf(marker);
+    if (markerIndex === -1) {
+        return false;
+    }
+    return isWordString(fileName.slice(markerIndex + marker.length));
+}
+// Layer 1: Path/Filename Patterns
+const PATH_MATCHERS = [
+    {
+        description: 'exact-filename',
+        matches: (_parsedPath, fileName) => EXACT_FILENAMES.has(fileName),
+    },
+    {
+        description: 'minified-or-generated-suffix',
+        matches: (_parsedPath, fileName) => matchesAnySuffix(fileName, FILENAME_SUFFIXES),
+    },
+    {
+        description: 'generated-extension',
+        matches: (_parsedPath, fileName) => hasGeneratedSuffix(fileName, '.generated.') || hasGeneratedSuffix(fileName, '.gen.'),
+    },
+    {
+        description: 'mockgen-go',
+        matches: (_parsedPath, fileName) => fileName.startsWith('mock_') && fileName.endsWith('.go'),
+    },
+    {
+        description: 'mocks-go-directory',
+        matches: (parsedPath, fileName) => parsedPath.includes('mocks/') && fileName.endsWith('.go'),
+    },
+    {
+        description: 'root-generated-directory',
+        matches: (parsedPath) => ROOT_PATH_PREFIXES.some((prefix) => parsedPath.startsWith(prefix)),
+    },
+    {
+        description: 'generated-path-segment',
+        matches: (parsedPath) => PATH_SEGMENTS.some((segment) => parsedPath.includes(segment)),
+    },
+];
+// Layer 2: Universal Header Patterns
+const UNIVERSAL_PATTERNS = [
+    // Most common markers
+    /@generated\b/,
+    /\bDO NOT EDIT\b/i,
+    /\bDO NOT MODIFY\b/i,
+    /\bAUTO[- ]?GENERATED\b/i,
+    /\bTHIS FILE IS GENERATED\b/i,
+    /\bGENERATED CODE\b/i,
+    /\bMACHINE GENERATED\b/i,
+    // Common tool output phrases
+    /Generated by\b/i,
+    /Autogenerated by\b/i,
+    /Created by .* - DO NOT EDIT/i,
+    /This file was generated/i,
+    /This is a generated file/i,
+    // XML/HTML style
+    /<auto-generated\s*\/?>/i,
+    /<!-- Generated by/i,
+];
+const LANGUAGE_SPECIFIC = [
+    {
+        extensions: ['.go'],
+        patterns: [
+            // Go official specification (https://golang.org/s/generatedcode)
+            /^\/\/ Code generated .* DO NOT EDIT\.$/m,
+            /Code generated by protoc-gen-go/,
+            /Code generated by Wire/,
+            /Code generated by ent/,
+            /Code generated by sqlc/,
+            /Code generated by MockGen/,
+            /Code generated by go-swagger/,
+            /Code generated by "stringer"/,
+        ],
+    },
+    {
+        extensions: ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'],
+        patterns: [
+            /generated using openapi-typescript-codegen/i,
+            /This file was auto-generated by openapi/i,
+            /Generated by orval/i,
+            /THIS FILE WAS GENERATED/,
+            /Generated by graphql-codegen/i,
+            /Prisma Client JS/,
+            /Generated by the protocol buffer/,
+            /GENERATED CODE -- DO NOT EDIT/,
+            /@generated SignedSource/,
+            /Generated by Apollo/,
+        ],
+    },
+    {
+        extensions: ['.rb'],
+        patterns: [
+            /This file is auto-generated from the current state of the database/,
+            /This file is autogenerated/,
+            /Generated by the protocol buffer/,
+            /Autogenerated by Thrift/,
+            /DO NOT MODIFY.*schema/i,
+        ],
+    },
+    {
+        extensions: ['.php'],
+        patterns: [
+            /This class was generated by/i,
+            /Doctrine .* Generated/i,
+            /Generated by the protocol buffer/,
+            /auto-generated by Symfony/i,
+        ],
+    },
+    {
+        extensions: ['.py'],
+        patterns: [
+            /Generated by the protocol buffer compiler/,
+            /@generated by mypy-protobuf/,
+            /Generated by the gRPC/,
+            /Autogenerated by Thrift/,
+            /# Generated by Django/,
+            /autogenerated by sqlacodegen/i,
+            /generated by datamodel-codegen/,
+        ],
+    },
+    {
+        extensions: ['.java', '.kt'],
+        patterns: [
+            /Generated by the protocol buffer/,
+            /@javax\.annotation\.Generated/,
+            /@Generated\(/,
+            /Generated by the gRPC/,
+            /Generated by Dagger/,
+            /generated at.*by JAXB/i,
+            /OpenAPI Generator/,
+        ],
+    },
+    {
+        extensions: ['.cs'],
+        patterns: [
+            /<auto-generated>/,
+            /<autogenerated>/,
+            /Generated by the protocol buffer/,
+            /auto-generated by EF/i,
+            /This code was generated by a tool/,
+        ],
+    },
+];
+/**
+ * Checks if a file is generated.
+ * Uses a 3-layer approach:
+ * 1. Path/Filename patterns (fastest, no reading)
+ * 2. Universal header patterns (checks first 20 lines)
+ * 3. Language-specific header patterns (checks first 20 lines)
+ *
+ * @param parsedPath The decoded git path of the file
+ * @param getHeaderLines A function that lazily provides the first 20 lines of the file content
+ */
+export function isGeneratedFile(parsedPath, getHeaderLines) {
+    // Layer 1: Path-based check (no file read)
+    // We check if the filename matches any known generated patterns
+    // or if the path is in a known generated directory
+    const fileName = parsedPath.split('/').pop() || '';
+    for (const matcher of PATH_MATCHERS) {
+        if (matcher.matches(parsedPath, fileName)) {
+            return {
+                isGenerated: true,
+                reason: 'path',
+                matchedPattern: matcher.description,
+            };
+        }
+    }
+    // Optimization: Skip content checks for markdown files as they are documentation
+    // and often contain examples of generated headers which trigger false positives.
+    if (/\.(md|markdown)$/i.test(fileName)) {
+        return { isGenerated: false };
+    }
+    // If no content provider is available, we can't check further
+    if (!getHeaderLines) {
+        return { isGenerated: false };
+    }
+    // Layer 2 & 3: Header-based check
+    const lines = getHeaderLines();
+    const header = lines.join('\n');
+    // Universal patterns
+    for (const pattern of UNIVERSAL_PATTERNS) {
+        if (pattern.test(header)) {
+            return {
+                isGenerated: true,
+                reason: 'universal',
+                matchedPattern: pattern.source,
+            };
+        }
+    }
+    // Language-specific patterns
+    // Simple extension extraction
+    const extMatch = parsedPath.match(/\.[a-zA-Z0-9]+$/);
+    const ext = extMatch ? extMatch[0] : '';
+    const langPatterns = LANGUAGE_SPECIFIC.find((lang) => lang.extensions.includes(ext));
+    if (langPatterns) {
+        for (const pattern of langPatterns.patterns) {
+            if (pattern.test(header)) {
+                return {
+                    isGenerated: true,
+                    reason: 'language-specific',
+                    matchedPattern: pattern.source,
+                };
+            }
+        }
+    }
+    return { isGenerated: false };
+}