@agilemonster/mcp-server 1.0.16 → 1.0.21

package/dist/runtime.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Runtime plumbing shared by the pulse daemon and the stdio MCP server:
+ *  - where Agile Monster keeps its machine-local state,
+ *  - a PATH that matches what the developer has in their own terminal,
+ *  - non-blocking command execution (so heartbeats keep ticking during long deploys),
+ *  - a structured log that is never written to stdout in stdio mode (stdout is the MCP protocol channel).
+ */
+export declare function agileMonsterHome(): string;
+/** Daemon mode may echo to stdout (captured by launchd); stdio mode must never do that. */
+export declare function configureLogger(options: {
+    echo: boolean;
+}): void;
+export declare const log: {
+    info: (event: string, data?: Record<string, unknown>) => void;
+    warn: (event: string, data?: Record<string, unknown>) => void;
+    error: (event: string, data?: Record<string, unknown>) => void;
+};
+export declare function errorMessage(err: unknown): string;
+/**
+ * Merge PATH lists, keeping the order of `current` and appending entries from `extra` that are new.
+ * Pure so it can be unit tested.
+ */
+export declare function mergePathEntries(current: string, extra: string[], delimiter?: ";" | ":"): string;
+/**
+ * Cheap, synchronous half of PATH repair: add the well-known tool directories that exist on this machine
+ * (Homebrew, ~/.docker/bin, OrbStack, ~/.local/bin, …). Safe to call at startup; it only stats a few folders.
+ */
+export declare function addWellKnownToolDirs(): string[];
+/**
+ * A launchd/systemd daemon (or an IDE-spawned MCP server) starts with a minimal PATH, so tools that work in
+ * the developer's terminal (docker in ~/.docker/bin, fly, pnpm, nvm-managed node, …) are "command not found".
+ * This asks the login shell for its PATH once — without blocking the event loop — and merges it in together
+ * with the well-known tool directories. Resolves to the directories that were added.
+ */
+export declare function ensureUserPath(force?: boolean): Promise<string[]>;
+/** Locate an executable on the current PATH without spawning a shell. */
+export declare function which(bin: string): string | null;
+export interface ExecResult {
+    ok: boolean;
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** Combined, trimmed tail of stderr + stdout: what a human needs to see when it failed. */
+    tail: string;
+}
+export interface ExecOptions {
+    cwd?: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    /** Run `command` through the shell (needed for user-supplied deploy commands). */
+    shell?: boolean;
+}
+/**
+ * Run a command without blocking the event loop. Never rejects: failures come back as `ok: false`.
+ * With `shell: false` (the default) `args` are passed verbatim, so paths and titles need no quoting.
+ */
+export declare function exec(command: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+/** Run a user-supplied command line through the shell. */
+export declare function execShell(commandLine: string, options?: ExecOptions): Promise<ExecResult>;
+export declare function sleep(ms: number): Promise<void>;
+/** Write JSON atomically so a crash mid-write never leaves a truncated state file. */
+export declare function writeJsonAtomic(file: string, data: unknown): void;
+export declare function readJson<T>(file: string): T | null;

package/dist/runtime.js

@@ -0,0 +1,293 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+/**
+ * Runtime plumbing shared by the pulse daemon and the stdio MCP server:
+ *  - where Agile Monster keeps its machine-local state,
+ *  - a PATH that matches what the developer has in their own terminal,
+ *  - non-blocking command execution (so heartbeats keep ticking during long deploys),
+ *  - a structured log that is never written to stdout in stdio mode (stdout is the MCP protocol channel).
+ */
+export function agileMonsterHome() {
+    const override = (process.env.AGILEMONSTER_HOME || '').trim();
+    const dir = override || path.join(os.homedir(), '.agilemonster');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch { }
+    return dir;
+}
+let echoToStdout = false;
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+/** Daemon mode may echo to stdout (captured by launchd); stdio mode must never do that. */
+export function configureLogger(options) {
+    echoToStdout = options.echo;
+}
+function writeLog(level, event, data) {
+    const entry = { at: new Date().toISOString(), level, event, pid: process.pid, ...(data || {}) };
+    let line = '';
+    try {
+        line = JSON.stringify(entry);
+    }
+    catch {
+        line = JSON.stringify({ at: entry.at, level, event, pid: process.pid, note: 'unserializable log data' });
+    }
+    try {
+        const dir = path.join(agileMonsterHome(), 'logs');
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, 'daemon.jsonl');
+        try {
+            if (fs.statSync(file).size > MAX_LOG_BYTES) {
+                fs.renameSync(file, `${file}.1`);
+            }
+        }
+        catch { }
+        fs.appendFileSync(file, line + '\n', 'utf8');
+    }
+    catch { }
+    if (echoToStdout) {
+        try {
+            console.log(line);
+        }
+        catch { }
+    }
+}
+export const log = {
+    info: (event, data) => writeLog('info', event, data),
+    warn: (event, data) => writeLog('warn', event, data),
+    error: (event, data) => writeLog('error', event, data),
+};
+export function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+// ---------------------------------------------------------------------------
+// PATH hydration
+// ---------------------------------------------------------------------------
+/**
+ * Merge PATH lists, keeping the order of `current` and appending entries from `extra` that are new.
+ * Pure so it can be unit tested.
+ */
+export function mergePathEntries(current, extra, delimiter = path.delimiter) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of [...current.split(delimiter), ...extra]) {
+        const clean = entry.trim();
+        if (!clean || seen.has(clean))
+            continue;
+        seen.add(clean);
+        out.push(clean);
+    }
+    return out.join(delimiter);
+}
+function wellKnownToolDirs() {
+    const home = os.homedir();
+    return [
+        '/opt/homebrew/bin',
+        '/opt/homebrew/sbin',
+        '/usr/local/bin',
+        path.join(home, '.docker', 'bin'),
+        path.join(home, '.orbstack', 'bin'),
+        '/Applications/Docker.app/Contents/Resources/bin',
+        path.join(home, '.local', 'bin'),
+        path.join(home, 'bin'),
+        path.join(home, '.fly', 'bin'),
+        path.join(home, '.bun', 'bin'),
+        path.join(home, '.volta', 'bin'),
+        path.join(home, '.cargo', 'bin'),
+        path.join(home, '.pub-cache', 'bin'),
+        path.join(home, 'go', 'bin'),
+        '/snap/bin',
+    ];
+}
+function applyExtraPath(extra) {
+    const before = process.env.PATH || '';
+    const merged = mergePathEntries(before, extra);
+    process.env.PATH = merged;
+    const beforeSet = new Set(before.split(path.delimiter));
+    return merged.split(path.delimiter).filter((p) => !beforeSet.has(p));
+}
+/**
+ * Cheap, synchronous half of PATH repair: add the well-known tool directories that exist on this machine
+ * (Homebrew, ~/.docker/bin, OrbStack, ~/.local/bin, …). Safe to call at startup; it only stats a few folders.
+ */
+export function addWellKnownToolDirs() {
+    if (process.platform === 'win32')
+        return [];
+    const extra = [];
+    for (const dir of wellKnownToolDirs()) {
+        try {
+            if (fs.existsSync(dir))
+                extra.push(dir);
+        }
+        catch { }
+    }
+    return applyExtraPath(extra);
+}
+let shellPathPromise = null;
+/**
+ * A launchd/systemd daemon (or an IDE-spawned MCP server) starts with a minimal PATH, so tools that work in
+ * the developer's terminal (docker in ~/.docker/bin, fly, pnpm, nvm-managed node, …) are "command not found".
+ * This asks the login shell for its PATH once — without blocking the event loop — and merges it in together
+ * with the well-known tool directories. Resolves to the directories that were added.
+ */
+export function ensureUserPath(force = false) {
+    if (shellPathPromise && !force)
+        return shellPathPromise;
+    shellPathPromise = (async () => {
+        const added = addWellKnownToolDirs();
+        if (process.platform === 'win32')
+            return added;
+        try {
+            const shell = process.env.SHELL && fs.existsSync(process.env.SHELL) ? process.env.SHELL : '/bin/sh';
+            const res = await exec(shell, ['-ilc', 'printf "__AM_PATH__%s__AM_END__" "$PATH"'], { timeoutMs: 8000 });
+            const match = res.stdout.match(/__AM_PATH__(.*?)__AM_END__/s);
+            if (match && match[1]) {
+                added.push(...applyExtraPath(match[1].split(path.delimiter).filter((d) => d && fs.existsSync(d))));
+            }
+        }
+        catch {
+            // A shell that refuses -i or takes too long must never stop a deployment; the well-known dirs still apply.
+        }
+        return added;
+    })();
+    return shellPathPromise;
+}
+/** Locate an executable on the current PATH without spawning a shell. */
+export function which(bin) {
+    const exts = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+    for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, bin + ext);
+            try {
+                fs.accessSync(candidate, fs.constants.X_OK);
+                if (fs.statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch { }
+        }
+    }
+    return null;
+}
+const MAX_CAPTURE = 256 * 1024;
+function summarizeTail(stdout, stderr) {
+    return (stderr + '\n' + stdout)
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .slice(-8)
+        .join(' | ')
+        .slice(0, 900);
+}
+/**
+ * Run a command without blocking the event loop. Never rejects: failures come back as `ok: false`.
+ * With `shell: false` (the default) `args` are passed verbatim, so paths and titles need no quoting.
+ */
+export function exec(command, args = [], options = {}) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        const useGroup = process.platform !== 'win32';
+        let child;
+        try {
+            child = spawn(command, options.shell ? [] : args, {
+                cwd: options.cwd,
+                env: options.env || process.env,
+                shell: options.shell ? true : false,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                detached: useGroup,
+            });
+        }
+        catch (err) {
+            resolve({ ok: false, code: null, stdout: '', stderr: errorMessage(err), timedOut: false, tail: errorMessage(err) });
+            return;
+        }
+        const killTree = (signal) => {
+            try {
+                if (useGroup && child.pid) {
+                    process.kill(-child.pid, signal);
+                }
+                else {
+                    child.kill(signal);
+                }
+            }
+            catch { }
+        };
+        const timer = options.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                killTree('SIGTERM');
+                setTimeout(() => {
+                    killTree('SIGKILL');
+                    // A grandchild that detached itself can keep the pipes open forever: never wait on it.
+                    setTimeout(() => finish(null), 2000);
+                }, 4000);
+            }, options.timeoutMs)
+            : null;
+        const finish = (code, extraErr = '') => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            // Stop listening so a lingering background process cannot keep this call (or the event loop) alive
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            const errText = extraErr ? `${stderr}\n${extraErr}` : stderr;
+            const fullErr = timedOut
+                ? `${errText}\nTimed out after ${Math.round((options.timeoutMs || 0) / 1000)}s`
+                : errText;
+            resolve({
+                ok: code === 0 && !timedOut,
+                code,
+                stdout,
+                stderr: fullErr,
+                timedOut,
+                tail: summarizeTail(stdout, fullErr),
+            });
+        };
+        child.stdout?.on('data', (d) => {
+            stdout = (stdout + d.toString('utf8')).slice(-MAX_CAPTURE);
+        });
+        child.stderr?.on('data', (d) => {
+            stderr = (stderr + d.toString('utf8')).slice(-MAX_CAPTURE);
+        });
+        child.on('error', (err) => finish(null, errorMessage(err)));
+        child.on('close', (code) => finish(code));
+        // The command is done when its process exits. A background process it started (`nohup server &`) may hold the
+        // output pipes open indefinitely, so give the pipes a moment to drain and then report — without killing it.
+        child.on('exit', (code) => {
+            setTimeout(() => finish(code), 400);
+        });
+    });
+}
+/** Run a user-supplied command line through the shell. */
+export function execShell(commandLine, options = {}) {
+    return exec(commandLine, [], { ...options, shell: true });
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Write JSON atomically so a crash mid-write never leaves a truncated state file. */
+export function writeJsonAtomic(file, data) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+    fs.renameSync(tmp, file);
+}
+export function readJson(file) {
+    try {
+        if (!fs.existsSync(file))
+            return null;
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server.d.ts

@@ -35,11 +35,24 @@ export declare function createServer(client?: AgileMonsterClient): Server<{
         } | undefined;
     } | undefined;
 }>;
+export declare function collectProjectSourceFiles(projectPath: string, keywords: string[]): string[];
+/**
+ * Roll back edits left behind by a worker that died mid-card. A file is only restored if it still holds
+ * exactly what that worker wrote — anything the developer touched since is left alone.
+ */
+export declare function recoverEditJournals(): number;
+/**
+ * A card whose TITLE is an operations request ("Restart the container", "Redeploy production").
+ * Anchored to the start of the title so "Add a restart button to the server page" is not one.
+ */
+export declare function isRedeployOnlyCard(card: Pick<Card, 'title'>): boolean;
 export declare function executeQueuedCardAutonomously(client: AgileMonsterClient, card: Card, projectPath: string): Promise<boolean>;
 /**
- * Deploy a card the human approved into Done (or flagged as `deploying`).
- * Idempotent: keyed on card ID only (never on `updated_at`, which changes whenever we post a comment),
- * so a card is deployed at most once unless the human explicitly re-triggers it into `deploying`.
+ * Finish a card the human approved into Done (or flagged as `deploying`).
+ * Idempotent: keyed on card ID only (never on `updated_at`, which changes whenever we post a comment).
+ *
+ * Approving a card that was already deployed and verified at review time only CONFIRMS it — it no longer
+ * triggers a second deployment (or an empty "redeploy" commit) for every approval.
  */
 export declare function deployApprovedCardIfNeeded(client: AgileMonsterClient, card: Card, projectPath: string): Promise<boolean>;
 export declare function acquireWorkerLock(role: 'daemon' | 'stdio'): boolean;