diff-easy 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+import { spawn } from 'child_process';
+import { Command } from 'commander';
+import { simpleGit } from 'simple-git';
+import pkg from '../../package.json' with { type: 'json' };
+import { startServer } from '../server/server.js';
+import { createDiffSelection } from '../utils/diffSelection.js';
+import { DiffMode } from '../types/watch.js';
+import { shouldReadStdin, findUntrackedFiles, markFilesIntentToAdd, promptUser, parseCommentOptions, validateDiffArguments, getGitRoot, readStdin, } from './utils.js';
+import { createCommentCommand } from './comment.js';
+import { getPrPatch, getPrCommentImports, getPrDetails } from './github.js';
+import { createSnapshotCommand, createInitCommand } from './turns.js';
+import { createCmuxCommand } from './cmux.js';
+import { addHubRoots } from '../utils/hubConfig.js';
+function createHubCommand() {
+    return new Command('hub')
+        .description('Run an always-on diff-easy; pick a folder or PR to review from the UI')
+        .option('--port <port>', 'preferred port (default 4966)', parseInt)
+        .option('--host <host>', 'host address to bind', '')
+        .option('--no-open', 'do not automatically open the browser')
+        .option('--root <path>', 'workspace root to scan for repos (repeatable)', (value, previous) => [...previous, value], [])
+        .action(async (options) => {
+        if (options.root.length > 0) {
+            addHubRoots(options.root);
+        }
+        try {
+            const { url } = await startServer({
+                hub: true,
+                keepAlive: true,
+                preferredPort: options.port ?? 4966,
+                host: options.host || undefined,
+                openBrowser: options.open !== false,
+            });
+            console.log(`\n🗂️  diff-easy hub running at ${url}`);
+            console.log('   Pick a folder or paste a PR URL in the UI. Press Ctrl+C to stop.\n');
+        }
+        catch (error) {
+            console.error(`Error starting hub: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            process.exit(1);
+        }
+    });
+}
+function isSpecialArg(arg) {
+    return arg === 'working' || arg === 'staged' || arg === '.';
+}
+function resolveDiffSelection(commitish, compareWith, mergeBase) {
+    let baseCommitish;
+    if (compareWith) {
+        baseCommitish = compareWith;
+    }
+    else if (commitish === 'working') {
+        baseCommitish = 'staged';
+    }
+    else if (isSpecialArg(commitish)) {
+        baseCommitish = 'HEAD';
+    }
+    else {
+        baseCommitish = commitish + '^';
+    }
+    return createDiffSelection(baseCommitish, commitish, mergeBase ? 'merge-base' : undefined);
+}
+function determineDiffMode(selection, compareWith) {
+    const { targetCommitish } = selection;
+    // If comparing specific commits/branches (not involving HEAD), no watching needed
+    // Exception: allow watching when targetCommitish is '.' even with compareWith
+    if (compareWith && targetCommitish !== 'HEAD' && targetCommitish !== '.') {
+        return DiffMode.SPECIFIC;
+    }
+    if (targetCommitish === 'working') {
+        return DiffMode.WORKING;
+    }
+    if (targetCommitish === 'staged') {
+        return DiffMode.STAGED;
+    }
+    if (targetCommitish === '.') {
+        return DiffMode.DOT;
+    }
+    // Default mode: HEAD^ vs HEAD or HEAD vs other commits (watch for HEAD changes)
+    return DiffMode.DEFAULT;
+}
+async function startBackgroundProcess() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        throw new Error('Unable to determine diff-easy entrypoint for background process');
+    }
+    const childArgs = process.argv.slice(2).filter((arg) => arg !== '--background');
+    if (!childArgs.includes('--keep-alive')) {
+        childArgs.push('--keep-alive');
+    }
+    if (!childArgs.includes('--no-open')) {
+        childArgs.push('--no-open');
+    }
+    const child = spawn(process.execPath, [scriptPath, ...childArgs], {
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: {
+            ...process.env,
+            [BACKGROUND_CHILD_ENV]: '1',
+        },
+    });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new Error('Timed out while starting background diff-easy server'));
+        }, 10_000);
+        let stderr = '';
+        let settled = false;
+        const finish = (callback) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            callback();
+        };
+        child.stdout.on('data', (chunk) => {
+            const line = chunk
+                .split(/\r?\n/u)
+                .map((value) => value.trim())
+                .find((value) => value.length > 0);
+            if (!line) {
+                return;
+            }
+            finish(() => {
+                console.log(line);
+                child.unref();
+                resolve();
+            });
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.once('error', (error) => {
+            finish(() => {
+                reject(error);
+            });
+        });
+        child.once('exit', (code) => {
+            finish(() => {
+                const trimmedStderr = stderr.trim();
+                reject(new Error(trimmedStderr || `Background diff-easy server exited early (code ${code ?? 'unknown'})`));
+            });
+        });
+    });
+}
+const BACKGROUND_CHILD_ENV = 'DIFIT_BACKGROUND_CHILD';
+const program = new Command();
+program
+    .name('diff-easy')
+    .description('A lightweight Git diff viewer with GitHub-like interface')
+    .version(pkg.version, '-v, --version', 'output the version number')
+    .enablePositionalOptions()
+    .addCommand(createCommentCommand())
+    .addCommand(createSnapshotCommand())
+    .addCommand(createInitCommand())
+    .addCommand(createCmuxCommand())
+    .addCommand(createHubCommand())
+    .argument('[commit-ish]', 'Git commit, tag, branch, HEAD~n reference, or "working"/"staged"/"." (default "." = all uncommitted changes)', '.')
+    .argument('[compare-with]', 'Optional: Compare with this commit/branch (shows diff between commit-ish and compare-with)')
+    .option('--port <port>', 'preferred port (auto-assigned if occupied)', parseInt)
+    .option('--host <host>', 'host address to bind', '')
+    .option('--no-open', 'do not automatically open browser')
+    .option('--comment <json>', 'inject initial review comments (repeatable, accepts a JSON object or array)', (value, previous) => [...previous, value], [])
+    .option('--pr <url>', 'GitHub PR URL to review (e.g., https://github.com/owner/repo/pull/123)')
+    .option('--clean', 'start with a clean slate by clearing all existing comments')
+    .option('--include-untracked', 'automatically include untracked files in diff')
+    .option('--keep-alive', 'keep server running even after browser disconnects')
+    .option('--background', 'keep the server running in the background and output JSON info')
+    .option('--context <lines>', 'number of context lines shown around each change', parseInt)
+    .option('--merge-base', 'resolve the base revision with git merge-base before diffing (Git revision mode only)')
+    .action(async (commitish, compareWith, options) => {
+    try {
+        const isBackgroundChild = process.env[BACKGROUND_CHILD_ENV] === '1';
+        const backgroundMode = options.background || isBackgroundChild;
+        let stdinDiff;
+        let stdinReviewLabel = 'diff from stdin';
+        let manualCommentImports = [];
+        let commentImports = [];
+        let prTitle;
+        let prBody;
+        if (options.context !== undefined &&
+            (!Number.isInteger(options.context) || options.context < 0)) {
+            console.error('Error: --context must be a non-negative integer');
+            process.exit(1);
+        }
+        if (options.background && !isBackgroundChild) {
+            await startBackgroundProcess();
+            return;
+        }
+        try {
+            manualCommentImports = parseCommentOptions(options.comment);
+            commentImports = manualCommentImports;
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : 'Invalid --comment value'}`);
+            process.exit(1);
+        }
+        if (backgroundMode) {
+            options.keepAlive = true;
+            options.open = false;
+        }
+        if (options.pr) {
+            if (program.args.length > 0) {
+                console.error('Error: --pr option cannot be used with positional arguments');
+                process.exit(1);
+            }
+            if (options.mergeBase) {
+                console.error('Error: --merge-base option cannot be used with --pr');
+                process.exit(1);
+            }
+            if (options.context !== undefined) {
+                console.error('Error: --context option cannot be used with --pr');
+                process.exit(1);
+            }
+            try {
+                stdinDiff = getPrPatch(options.pr);
+                stdinReviewLabel = options.pr;
+            }
+            catch (error) {
+                console.error(`Error resolving PR: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                process.exit(1);
+            }
+            try {
+                const prCommentImports = await getPrCommentImports(options.pr);
+                commentImports = [...prCommentImports, ...manualCommentImports];
+            }
+            catch (error) {
+                console.warn(`Warning: Failed to load PR review comments: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+            try {
+                const prDetails = await getPrDetails(options.pr);
+                prTitle = prDetails?.title || undefined;
+                prBody = prDetails?.body || undefined;
+            }
+            catch (error) {
+                console.warn(`Warning: Failed to load PR title/body: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        else {
+            // Check if we should read from stdin
+            const readFromStdin = shouldReadStdin({
+                commitish,
+                hasPositionalArgs: program.args.length > 0,
+                hasPrOption: false,
+            });
+            if (readFromStdin) {
+                if (options.context !== undefined) {
+                    console.error('Error: --context option cannot be used with stdin diff');
+                    process.exit(1);
+                }
+                if (options.mergeBase) {
+                    console.error('Error: --merge-base option cannot be used with stdin diff');
+                    process.exit(1);
+                }
+                // Read unified diff from stdin
+                stdinDiff = await readStdin();
+                if (!stdinDiff.trim()) {
+                    console.error('Error: No diff content received from stdin');
+                    process.exit(1);
+                }
+            }
+        }
+        if (stdinDiff) {
+            // Start server with stdin diff (including --pr patch)
+            const { url, port } = await startServer({
+                stdinDiff,
+                preferredPort: options.port,
+                host: options.host,
+                openBrowser: options.open,
+                clearComments: options.clean,
+                keepAlive: options.keepAlive,
+                ...(commentImports.length > 0 ? { commentImports } : {}),
+                prTitle,
+                prBody,
+            });
+            if (backgroundMode) {
+                console.log(JSON.stringify({ port, url, pid: process.pid }));
+                return;
+            }
+            console.log(`\n🚀 diff-easy server started on ${url}`);
+            console.log(`📋 Reviewing: ${stdinReviewLabel}`);
+            if (options.keepAlive) {
+                console.log('🔒 Keep-alive mode: server will stay running after browser disconnects');
+            }
+            console.log('\nPress Ctrl+C to stop the server');
+            return;
+        }
+        // Detect git root
+        let repoPath;
+        try {
+            repoPath = getGitRoot();
+        }
+        catch {
+            // If not in a git repository, fall back to process.cwd()
+            repoPath = undefined;
+        }
+        const selection = resolveDiffSelection(commitish, compareWith, options.mergeBase);
+        if (options.mergeBase && isSpecialArg(selection.baseCommitish)) {
+            console.error(`Error: --merge-base requires a commit-ish base, but resolved base was "${selection.baseCommitish}"`);
+            process.exit(1);
+        }
+        if (selection.targetCommitish === 'working' || selection.targetCommitish === '.') {
+            const git = simpleGit(repoPath);
+            if (isBackgroundChild && !options.includeUntracked) {
+                // Skip interactive prompts in detached background mode.
+            }
+            else {
+                await handleUntrackedFiles(git, options.includeUntracked);
+            }
+        }
+        const validation = validateDiffArguments(selection.targetCommitish, compareWith);
+        if (!validation.valid) {
+            console.error(`Error: ${validation.error}`);
+            process.exit(1);
+        }
+        const { url, port, isEmpty } = await startServer({
+            selection,
+            preferredPort: options.port,
+            host: options.host,
+            openBrowser: options.open,
+            clearComments: options.clean,
+            keepAlive: options.keepAlive,
+            contextLines: options.context,
+            diffMode: determineDiffMode(selection, compareWith),
+            repoPath,
+            ...(commentImports.length > 0 ? { commentImports } : {}),
+        });
+        if (backgroundMode) {
+            console.log(JSON.stringify({ port, url, pid: process.pid }));
+            return;
+        }
+        console.log(`\n🚀 diff-easy server started on ${url}`);
+        console.log(`📋 Reviewing: ${selection.targetCommitish}`);
+        if (options.keepAlive) {
+            console.log('🔒 Keep-alive mode: server will stay running after browser disconnects');
+        }
+        if (options.clean) {
+            console.log('🧹 Starting with a clean slate - all existing comments will be cleared');
+        }
+        if (isEmpty) {
+            console.log('\n! \x1b[33mNo differences found. Browser will not open automatically.\x1b[0m');
+            console.log(`   Server is running at ${url} if you want to check manually.\n`);
+        }
+        else if (options.open) {
+            console.log('🌐 Opening browser...\n');
+        }
+        else {
+            console.log('💡 Use --open to automatically open browser\n');
+        }
+        process.on('SIGINT', async () => {
+            console.log('\n👋 Shutting down diff-easy server...');
+            // Try to fetch comments before shutting down
+            try {
+                const response = await fetch(`http://localhost:${port}/api/comments-output`);
+                if (response.ok) {
+                    const data = await response.text();
+                    if (data.trim()) {
+                        console.log(data);
+                    }
+                }
+            }
+            catch {
+                // Silently ignore fetch errors during shutdown
+            }
+            process.exit(0);
+        });
+    }
+    catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
+});
+void program.parseAsync();
+async function handleUntrackedFiles(git, addAutomatically) {
+    const files = await findUntrackedFiles(git);
+    if (files.length === 0) {
+        return;
+    }
+    const shouldAdd = addAutomatically || (await promptUserToIncludeUntracked(files));
+    if (shouldAdd) {
+        await markFilesIntentToAdd(git, files);
+        console.log('✅ Files added with --intent-to-add');
+        const filesAsArgs = files.join(' ');
+        console.log(`   💡 To undo this, run \`git reset -- ${filesAsArgs}\``);
+    }
+    else {
+        console.log('i Untracked files will not be shown in diff');
+    }
+}
+async function promptUserToIncludeUntracked(files) {
+    console.log(`\n📝 Found ${files.length} untracked file(s):`);
+    for (const file of files) {
+        console.log(`    - ${file}`);
+    }
+    return await promptUser('\n❓ Would you like to include these untracked files in the diff review? (Y/n): ');
+}

package/dist/cli/turns.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+/**
+ * Best-effort live-refresh ping. Capped so it never slows the agent's turn.
+ *
+ * A viewer advertises itself in one of two ways: a per-repo `server.json` (a
+ * standalone `difit` opened on this repo) or the global `hub.json` (the
+ * always-on hub, which serves many repos and never writes a per-repo file).
+ * Ping every live advertisement so the timeline refreshes regardless of which
+ * one the user has open — without this, hub users only saw new turns after a
+ * manual refresh.
+ */
+export declare function notifyServer(repoRoot: string): Promise<void>;
+export declare function createSnapshotCommand(): Command;
+export declare function createInitCommand(): Command;