dsh-cursor-dev 0.0.0-stage → 0.11.1

package/lib/changes.js

@@ -0,0 +1,192 @@
+/**
+ * Independent change evidence for a Cursor run.
+ *
+ * The ACP stream already reports diffs for edits Cursor performs through its own
+ * edit tools. This module adds a *second, independent* source of truth: a cheap
+ * filesystem fingerprint taken before and after the turn. That catches anything
+ * the stream omits — shell commands that write files, moves, deletes — so the
+ * parent model can verify the child's work instead of trusting its summary.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+
+/** Directories never worth fingerprinting in a source workspace. */
+const SKIP_DIRS = new Set([
+    '.git', 'node_modules', '__pycache__', '.venv', 'venv', 'env',
+    '.mypy_cache', '.pytest_cache', '.ruff_cache', 'dist', 'build',
+    '.next', '.nuxt', '.turbo', '.cache', '.idea', '.vscode',
+    'game', 'cache', 'saves', 'log',
+]);
+
+/**
+ * Normalize a path for cross-platform comparison.
+ * @param path - absolute or relative path.
+ */
+export function normalizePath(path) {
+    return path.split(sep).join('/');
+}
+
+/**
+ * Whether a directory name is excluded from fingerprinting.
+ * @param name - directory basename.
+ */
+function isSkippedDir(name) {
+    return SKIP_DIRS.has(name) || name.startsWith('.');
+}
+
+/**
+ * Fingerprint a workspace tree: path -> mtime+size.
+ *
+ * Bounded on purpose: a huge tree costs a few hundred ms and the cap keeps a
+ * pathological workspace from stalling a tool call.
+ *
+ * @param root - absolute workspace directory.
+ * @param maxFiles - stop after this many files.
+ */
+export async function fingerprint(root, maxFiles = 20_000) {
+    const files = new Map();
+    let truncated = false;
+
+    /** @param dir - directory to walk. */
+    async function walk(dir) {
+        if (truncated)
+            return;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (files.size >= maxFiles) {
+                truncated = true;
+                return;
+            }
+            if (entry.isDirectory()) {
+                if (isSkippedDir(entry.name))
+                    continue;
+                await walk(join(dir, entry.name));
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const full = join(dir, entry.name);
+            try {
+                const info = await stat(full);
+                files.set(normalizePath(relative(root, full)), `${info.mtimeMs}|${info.size}`);
+            }
+            catch {
+                // Racing deletes are not interesting to the diff.
+            }
+        }
+    }
+
+    await walk(root);
+    return { files, truncated };
+}
+
+/**
+ * Compare two fingerprints.
+ *
+ * @param before - fingerprint captured before the turn.
+ * @param after - fingerprint captured after the turn.
+ * @returns added / modified / removed relative paths.
+ */
+export function compareFingerprints(before, after) {
+    const added = [];
+    const modified = [];
+    const removed = [];
+
+    for (const [path, stamp] of after.files) {
+        const previous = before.files.get(path);
+        if (previous === undefined)
+            added.push(path);
+        else if (previous !== stamp)
+            modified.push(path);
+    }
+    for (const path of before.files.keys()) {
+        if (!after.files.has(path))
+            removed.push(path);
+    }
+    added.sort();
+    modified.sort();
+    removed.sort();
+    return { added, modified, removed };
+}
+
+/**
+ * Count added/removed lines in a unified-ish diff pair.
+ *
+ * @param oldText - previous content (`null` when the file is new).
+ * @param newText - new content.
+ */
+export function diffStats(oldText, newText) {
+    const before = oldText === null ? [] : oldText.split('\n');
+    const after = newText.split('\n');
+    let added = 0;
+    let removed = 0;
+    if (oldText === null) {
+        added = after.length;
+        return { added, removed, isNew: true };
+    }
+    // Line-set comparison: exact enough for a summary, cheap on large files.
+    const beforeSet = new Map();
+    for (const line of before)
+        beforeSet.set(line, (beforeSet.get(line) ?? 0) + 1);
+    for (const line of after) {
+        const count = beforeSet.get(line);
+        if (count === undefined || count === 0)
+            added += 1;
+        else
+            beforeSet.set(line, count - 1);
+    }
+    for (const count of beforeSet.values())
+        removed += count;
+    return { added, removed, isNew: before.length === 0 };
+}
+
+/**
+ * Merge ACP-reported diffs with the filesystem comparison into one change set.
+ *
+ * ACP diffs win when both describe the same path: they carry real text.
+ *
+ * @param diffs - `FileDiff[]` observed on the ACP stream.
+ * @param comparison - result of {@link compareFingerprints}.
+ * @param root - workspace root, used to relativize absolute ACP paths.
+ */
+export function mergeChanges(diffs, comparison, root) {
+    const byPath = new Map();
+    const prefix = normalizePath(root.endsWith(sep) ? root : `${root}${sep}`);
+
+    for (const diff of diffs) {
+        const normalized = normalizePath(diff.path);
+        const key = normalized.startsWith(prefix) ? normalized.slice(prefix.length) : normalized;
+        const stats = diffStats(diff.oldText, diff.newText);
+        byPath.set(key, {
+            path: key,
+            absolutePath: diff.path,
+            operation: stats.isNew ? 'created' : 'modified',
+            added: stats.added,
+            removed: stats.removed,
+            source: 'acp',
+            diff,
+        });
+    }
+
+    for (const path of comparison.added) {
+        if (!byPath.has(path)) {
+            byPath.set(path, { path, operation: 'created', added: 0, removed: 0, source: 'fs' });
+        }
+    }
+    for (const path of comparison.modified) {
+        if (!byPath.has(path)) {
+            byPath.set(path, { path, operation: 'modified', added: 0, removed: 0, source: 'fs' });
+        }
+    }
+    for (const path of comparison.removed) {
+        byPath.set(path, { path, operation: 'deleted', added: 0, removed: 0, source: 'fs' });
+    }
+
+    return [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path));
+}

package/lib/cli.js

@@ -0,0 +1,237 @@
+/**
+ * One-shot questions to the Cursor CLI.
+ *
+ * A new user hits the same two walls before this plugin can do anything: the CLI
+ * is not installed, or it is installed but not signed in. Both look identical
+ * from inside the panel (dashes, an empty model picker), so they are answered
+ * here explicitly — with the commands that fix them — instead of being left for
+ * the user to guess.
+ *
+ * This module also owns the one-shot spawn helper the model listing uses: the
+ * ACP session owns a long-lived child, while these queries ask a question,
+ * print, and exit.
+ *
+ * @module dsh-cursor-dev/cli
+ */
+
+/** Largest output accepted from a one-shot CLI query. */
+const MAX_OUTPUT_BYTES = 512 * 1024;
+
+/** How long a one-shot query may take before it is killed. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** How long an authentication answer is reused. */
+export const AUTH_CACHE_MS = 60 * 1000;
+
+/**
+ * What a user runs by hand when something is missing.
+ *
+ * Kept in one place because three surfaces quote it: the panel's setup card,
+ * the `cursor_code` error, and the README.
+ */
+export const CLI_SETUP = {
+    install: {
+        win32: "irm 'https://cursor.com/install?win32=true' | iex",
+        unix: 'curl https://cursor.com/install -fsS | bash',
+    },
+    login: 'agent login',
+    verify: 'agent status --format json',
+    docs: 'https://cursor.com/docs/cli',
+};
+
+/** Last authentication answer, keyed by the CLI it came from. */
+let cache = { at: 0, key: '', value: undefined };
+
+/**
+ * Describe the resolved CLI for the panel.
+ *
+ * `found` is the field the panel branches on; the rest is what a user needs in
+ * order to see *which* CLI the plugin is actually talking to.
+ *
+ * @param resolved - result of `resolveAgent`, or undefined.
+ */
+export function describeAgent(resolved) {
+    if (resolved === undefined || resolved === null)
+        return { found: false, command: '', entry: '', source: '' };
+    return {
+        found: true,
+        command: typeof resolved.command === 'string' ? resolved.command : '',
+        entry: typeof resolved.entry === 'string' ? resolved.entry : '',
+        source: typeof resolved.source === 'string' ? resolved.source : '',
+    };
+}
+
+/**
+ * Parse `agent status --format json`.
+ *
+ * The CLI answers with `{ status, isAuthenticated, hasAccessToken, userInfo }`.
+ * Anything that is not that shape is reported as "no answer" rather than being
+ * guessed at: a signed-out CLI prints a human sentence, and treating that as
+ * signed-in would send the user hunting in the wrong place.
+ *
+ * @param stdout - raw command output.
+ * @returns the parsed status, or undefined when the output is not that JSON.
+ */
+export function parseAuthStatus(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(String(stdout ?? '').trim());
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const user = parsed.userInfo !== null && typeof parsed.userInfo === 'object' ? parsed.userInfo : {};
+    return {
+        authenticated: parsed.isAuthenticated === true || parsed.status === 'authenticated',
+        status: typeof parsed.status === 'string' ? parsed.status : '',
+        email: typeof user.email === 'string' ? user.email : '',
+        userId: typeof user.userId === 'number' ? user.userId : 0,
+    };
+}
+
+/**
+ * Ask the CLI whether this machine is signed in.
+ *
+ * Never throws: the answer is exactly what the panel renders, and a throwing
+ * "is it set up?" check is useless to a user who is already stuck. A failed
+ * check keeps the CLI path and reports the reason instead.
+ *
+ * @param deps - `spawn`, resolved agent, cwd, env, plus optional `force`.
+ */
+export async function authStatus(deps) {
+    const key = deps?.resolved?.command ?? '';
+    if (deps?.force !== true && cache.value !== undefined && cache.key === key && Date.now() - cache.at < AUTH_CACHE_MS)
+        return cache.value;
+    const value = await probeAuth(deps);
+    cache = { at: Date.now(), key, value };
+    return value;
+}
+
+/** Drop the cached authentication answer (tests, and a config change). */
+export function forgetAuthStatus() {
+    cache = { at: 0, key: '', value: undefined };
+}
+
+/**
+ * Run one short-lived CLI command and collect its output.
+ *
+ * stdin is closed immediately so a CLI that waits on input cannot hang the
+ * panel, and the process is terminated when the deadline passes.
+ *
+ * @param deps - `spawn`, resolved agent, cwd, env (an object, or a function that
+ *               answers the current one or a promise for it), argv `tail`,
+ *               optional `timeoutMs`.
+ */
+export async function runOnce(deps) {
+    const { spawn, resolved, tail } = deps;
+    if (spawn === undefined || resolved === undefined)
+        throw new Error('the Cursor CLI is not available');
+    const argv = [resolved.command, ...(resolved.entry === undefined ? [] : [resolved.entry]), ...tail];
+    const handle = spawn({
+        argv,
+        cwd: deps.cwd,
+        // A function is asked per spawn: `--list-models` is exactly the call
+        // whose answer depends on the proxy, so it must never read a stale one —
+        // and it awaits, so a listing that races the first lookup still gets it.
+        env: typeof deps.env === 'function' ? await deps.env() : deps.env,
+        stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' },
+        graceMs: 2000,
+    });
+    let stdout = '';
+    let stderr = '';
+    handle.stdout?.on('data', (chunk) => {
+        if (stdout.length < MAX_OUTPUT_BYTES)
+            stdout += String(chunk);
+    });
+    handle.stderr?.on('data', (chunk) => {
+        if (stderr.length < MAX_OUTPUT_BYTES)
+            stderr += String(chunk);
+    });
+    try {
+        handle.stdin?.end();
+    }
+    catch {
+        // A CLI that already exited has nothing to close.
+    }
+
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        // Deliberately ref'd: this deadline is the only thing that settles the
+        // call when the CLI hangs, so it has to be able to fire on its own. An
+        // unref'd timer is silently disabled whenever the awaited work holds no
+        // live handle of its own — which is exactly the hung case it exists for,
+        // and it left the call pending until the process drained instead of
+        // reporting the timeout. `finally` below is what releases the handle.
+        timer = setTimeout(() => reject(new Error(`the CLI did not answer within ${Math.round(timeoutMs / 1000)}s`)), timeoutMs);
+    });
+    try {
+        await Promise.race([Promise.resolve(handle.done).catch(() => undefined), deadline]);
+    }
+    catch (error) {
+        try {
+            handle.terminate?.();
+        }
+        catch {
+            // Already gone.
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return { stdout, stderr };
+}
+
+/**
+ * The uncached half of {@link authStatus}.
+ *
+ * @param deps - spawn/agent dependencies.
+ */
+async function probeAuth(deps) {
+    const checkedAt = Date.now();
+    const resolved = deps?.resolved;
+    if (resolved === undefined)
+        return {
+            ok: false,
+            installed: false,
+            authenticated: false,
+            email: '',
+            checkedAt,
+            error: 'the Cursor CLI was not found',
+        };
+    try {
+        const result = await runOnce({ ...deps, tail: ['status', '--format', 'json'] });
+        const parsed = parseAuthStatus(result.stdout);
+        if (parsed === undefined) {
+            const detail = lastLine(result.stderr) || lastLine(result.stdout) || 'the CLI did not report a sign-in status';
+            return { ok: false, installed: true, authenticated: false, email: '', checkedAt, error: detail };
+        }
+        return {
+            ok: true,
+            installed: true,
+            authenticated: parsed.authenticated,
+            status: parsed.status,
+            email: parsed.email,
+            checkedAt,
+            error: null,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            installed: true,
+            authenticated: false,
+            email: '',
+            checkedAt,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+
+/** The last non-empty line of a command's output. */
+function lastLine(text) {
+    return String(text ?? '').split(/\r?\n/).map(line => line.trim()).filter(Boolean).slice(-1)[0] ?? '';
+}