watch-tail 0.9.0 → 0.10.1

package/dist/cli/mcp/agents.js

@@ -0,0 +1,344 @@
+/**
+ * The agents watch-tail knows how to configure, how to tell whether they are
+ * installed, and how to merge a `watch-tail` server entry into their files.
+ *
+ * Everything is a pure function of the paths and text it is handed: detection
+ * takes an `exists`, planning takes the current file contents, so the whole
+ * module can be tested against fabricated home directories. Writing files is the
+ * caller's job, which keeps this module free of side effects.
+ *
+ * The registry only lists agents whose configuration format is stable and
+ * documented. An agent that is not listed can still be wired up by hand; run
+ * `watch-tail mcp init --print` to see the exact entry.
+ */
+import { join } from 'node:path';
+/** Name the server is registered under in every agent. */
+const MCP_SERVER_NAME = 'watch-tail';
+/** `$XDG_CONFIG_HOME`, or the platform default. */
+function xdgConfig(ctx) {
+    return ctx.env.XDG_CONFIG_HOME?.trim() || join(ctx.home, '.config');
+}
+/** `%APPDATA%` on Windows. */
+function appData(ctx) {
+    return ctx.env.APPDATA?.trim() || join(ctx.home, 'AppData', 'Roaming');
+}
+/** macOS application support directory. */
+function macSupport(ctx) {
+    return join(ctx.home, 'Library', 'Application Support');
+}
+/** VS Code's per-user data directory. */
+function vscodeData(ctx) {
+    if (ctx.platform === 'darwin')
+        return join(macSupport(ctx), 'Code');
+    if (ctx.platform === 'win32')
+        return join(appData(ctx), 'Code');
+    return join(xdgConfig(ctx), 'Code');
+}
+/** Claude Desktop's data directory. */
+function claudeDesktopData(ctx) {
+    if (ctx.platform === 'darwin')
+        return join(macSupport(ctx), 'Claude');
+    if (ctx.platform === 'win32')
+        return join(appData(ctx), 'Claude');
+    return join(xdgConfig(ctx), 'Claude');
+}
+/** Every agent this build configures, in the order they are offered. */
+export const AGENTS = [
+    {
+        id: 'claude-desktop',
+        name: 'Claude Desktop',
+        format: 'json',
+        serverKey: 'mcpServers',
+        userPath: (ctx) => join(claudeDesktopData(ctx), 'claude_desktop_config.json'),
+        detect: (ctx) => [claudeDesktopData(ctx)],
+    },
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        format: 'json',
+        serverKey: 'mcpServers',
+        userPath: (ctx) => join(ctx.home, '.claude.json'),
+        projectPath: (ctx) => join(ctx.cwd, '.mcp.json'),
+        detect: (ctx) => [join(ctx.home, '.claude'), join(ctx.home, '.claude.json')],
+        binary: 'claude',
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        format: 'json',
+        serverKey: 'mcpServers',
+        userPath: (ctx) => join(ctx.home, '.cursor', 'mcp.json'),
+        projectPath: (ctx) => join(ctx.cwd, '.cursor', 'mcp.json'),
+        detect: (ctx) => [join(ctx.home, '.cursor')],
+        binary: 'cursor',
+    },
+    {
+        id: 'windsurf',
+        name: 'Windsurf',
+        format: 'json',
+        serverKey: 'mcpServers',
+        userPath: (ctx) => join(ctx.home, '.codeium', 'windsurf', 'mcp_config.json'),
+        detect: (ctx) => [join(ctx.home, '.codeium', 'windsurf')],
+        binary: 'windsurf',
+    },
+    {
+        id: 'vscode',
+        name: 'VS Code',
+        format: 'json',
+        serverKey: 'servers',
+        userPath: (ctx) => join(vscodeData(ctx), 'User', 'mcp.json'),
+        projectPath: (ctx) => join(ctx.cwd, '.vscode', 'mcp.json'),
+        detect: (ctx) => [vscodeData(ctx)],
+        binary: 'code',
+        entryExtras: { type: 'stdio' },
+    },
+    {
+        id: 'gemini',
+        name: 'Gemini CLI',
+        format: 'json',
+        serverKey: 'mcpServers',
+        userPath: (ctx) => join(ctx.home, '.gemini', 'settings.json'),
+        detect: (ctx) => [join(ctx.home, '.gemini')],
+        binary: 'gemini',
+    },
+    {
+        id: 'codex',
+        name: 'Codex CLI',
+        format: 'toml',
+        serverKey: 'mcp_servers',
+        userPath: (ctx) => join(ctx.home, '.codex', 'config.toml'),
+        detect: (ctx) => [join(ctx.home, '.codex')],
+        binary: 'codex',
+    },
+];
+/** Looks up an agent by id. */
+export function findAgent(id) {
+    return AGENTS.find((agent) => agent.id === id) ?? null;
+}
+/** Checks every known agent against the filesystem and the PATH. */
+export function detectAgents(ctx, io) {
+    return AGENTS.map((agent) => {
+        const paths = agent.detect(ctx);
+        const installed = paths.some((path) => io.exists(path)) ||
+            (agent.binary !== undefined && io.commandExists?.(agent.binary) === true);
+        return { agent, paths, installed };
+    });
+}
+/**
+ * Builds the launch command written into every agent config.
+ *
+ * The default goes through `npx`, so the agent keeps working after watch-tail is
+ * upgraded; the version is pinned so the config is reproducible. `--command`
+ * and `--args` replace either half for a local build.
+ */
+export function mcpServerCommand(input) {
+    const command = input.command?.trim() ?? '';
+    return {
+        command: command.length > 0 ? command : 'npx',
+        args: [
+            ...(input.args && input.args.length > 0 ? input.args : ['-y', `watch-tail@${input.version}`]),
+            'mcp',
+        ],
+    };
+}
+/** A config file that could not be merged safely. */
+export class AgentConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentConfigError';
+    }
+}
+/** Canonical JSON with object keys sorted, for order-independent comparison. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value).toSorted(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/** The entry stored for watch-tail, including any agent-specific extras. */
+function serverEntry(agent, command) {
+    return { ...agent.entryExtras, command: command.command, args: command.args };
+}
+/** True for a JSON object (not an array or null). */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Merges the entry into a JSON config file. */
+function planJsonConfig(agent, existing, command) {
+    const trimmed = existing.trim();
+    let root;
+    if (trimmed.length === 0) {
+        root = {};
+    }
+    else {
+        try {
+            const decoded = JSON.parse(trimmed);
+            if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) {
+                throw new AgentConfigError('the config file does not hold a JSON object');
+            }
+            root = decoded;
+        }
+        catch (error) {
+            if (error instanceof AgentConfigError)
+                throw error;
+            throw new AgentConfigError(`the existing config is not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    const mapValue = root[agent.serverKey];
+    const map = isRecord(mapValue) ? mapValue : {};
+    // Only the launch fields are ours: anything the user added to the entry (an
+    // `env` with AWS_PROFILE, a timeout) survives a re-run.
+    const current = map[MCP_SERVER_NAME];
+    const entry = { ...(isRecord(current) ? current : {}), ...serverEntry(agent, command) };
+    const changed = canonical(current) !== canonical(entry);
+    root[agent.serverKey] = { ...map, [MCP_SERVER_NAME]: entry };
+    return { contents: `${JSON.stringify(root, null, 2)}\n`, changed };
+}
+/** Renders a TOML basic string using JSON's own escaping, which TOML shares. */
+function quoteToml(value) {
+    return JSON.stringify(value);
+}
+/** The TOML keys watch-tail owns in the Codex `[mcp_servers.watch-tail]` section. */
+function tomlEntries(command) {
+    return [
+        ['command', quoteToml(command.command)],
+        ['args', `[${command.args.map(quoteToml).join(', ')}]`],
+    ];
+}
+/** Renders the Codex `[mcp_servers.watch-tail]` section. */
+function tomlSection(agent, command) {
+    return [
+        `[${agent.serverKey}.${MCP_SERVER_NAME}]`,
+        ...tomlEntries(command).map(([key, value]) => `${key} = ${value}`),
+    ];
+}
+/** A table header's dotted name with quotes and spaces removed, or `null`. */
+function tomlHeaderName(line) {
+    const match = /^\s*\[([^[\]]+)\]\s*(?:#.*)?$/.exec(line);
+    if (match === null)
+        return null;
+    return match[1]
+        .split('.')
+        .map((part) => part
+        .trim()
+        .replace(/^"(.*)"$/, '$1')
+        .replace(/^'(.*)'$/, '$1'))
+        .join('.');
+}
+/**
+ * How far a line moves the depth of open `[` arrays, ignoring brackets inside
+ * strings and comments, so a multi-line `args = [` is read as one value.
+ */
+function bracketDelta(line) {
+    let delta = 0;
+    let quote = null;
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (quote !== null) {
+            if (char === '\\' && quote === '"')
+                index += 1;
+            else if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === '#')
+            break;
+        if (char === '"' || char === "'")
+            quote = char;
+        else if (char === '[')
+            delta += 1;
+        else if (char === ']')
+            delta -= 1;
+    }
+    return delta;
+}
+/** The key a `key = value` line assigns, or `null`. */
+function tomlKey(line) {
+    const match = /^\s*("[^"]*"|'[^']*'|[A-Za-z0-9_-]+)\s*=/.exec(line);
+    return match === null ? null : match[1].replace(/^["'](.*)["']$/, '$1');
+}
+/**
+ * Sets `entries` in the `[section]` table, or appends the table when the file
+ * does not have one.
+ *
+ * Only the named keys are rewritten (a multi-line value is replaced whole);
+ * every other key the user put in the table, such as an `env`, is kept.
+ */
+export function upsertTomlSection(text, section, entries) {
+    const lines = text.length === 0 ? [] : text.replace(/\n$/, '').split('\n');
+    const start = lines.findIndex((line) => tomlHeaderName(line) === section);
+    if (start < 0) {
+        const block = [`[${section}]`, ...entries.map(([key, value]) => `${key} = ${value}`)];
+        const body = lines.length > 0 ? [...lines, '', ...block] : block;
+        return body.join('\n') + '\n';
+    }
+    // The table runs to the next header (`[t]` or `[[t]]`). Values are read whole,
+    // so a line of a multi-line array is never mistaken for one.
+    const body = [];
+    let end = start + 1;
+    while (end < lines.length) {
+        if (lines[end].trimStart().startsWith('['))
+            break;
+        const value = [lines[end]];
+        let depth = bracketDelta(lines[end]);
+        end += 1;
+        while (depth > 0 && end < lines.length) {
+            value.push(lines[end]);
+            depth += bracketDelta(lines[end]);
+            end += 1;
+        }
+        body.push({ lines: value, key: tomlKey(value[0]) });
+    }
+    const pending = new Map(entries);
+    const rewritten = [];
+    for (const item of body) {
+        const replacement = item.key === null ? undefined : pending.get(item.key);
+        if (replacement === undefined || item.key === null) {
+            rewritten.push(...item.lines);
+            continue;
+        }
+        rewritten.push(`${item.key} = ${replacement}`);
+        pending.delete(item.key);
+    }
+    // Keys the table did not have go after its last non-blank line.
+    let insertAt = rewritten.length;
+    while (insertAt > 0 && rewritten[insertAt - 1].trim().length === 0)
+        insertAt -= 1;
+    rewritten.splice(insertAt, 0, ...[...pending].map(([key, value]) => `${key} = ${value}`));
+    return [...lines.slice(0, start + 1), ...rewritten, ...lines.slice(end)].join('\n') + '\n';
+}
+/** Merges the entry into a TOML config file (Codex CLI). */
+function planTomlConfig(agent, existing, command) {
+    const section = `${agent.serverKey}.${MCP_SERVER_NAME}`;
+    const contents = upsertTomlSection(existing, section, tomlEntries(command));
+    const normalized = existing.length === 0 || existing.endsWith('\n') ? existing : `${existing}\n`;
+    return { contents, changed: contents !== normalized };
+}
+/**
+ * Plans one file write without touching the filesystem.
+ *
+ * Throws {@link AgentConfigError} when an existing file cannot be merged safely,
+ * so a hand-written config is never clobbered.
+ */
+export function planAgentConfig(input) {
+    const { agent, existing, command } = input;
+    return agent.format === 'toml'
+        ? planTomlConfig(agent, existing, command)
+        : planJsonConfig(agent, existing, command);
+}
+/** The config file to write for a scope, or `null` when the scope is unsupported. */
+export function agentConfigPath(agent, ctx, scope) {
+    if (scope === 'project')
+        return agent.projectPath?.(ctx) ?? null;
+    return agent.userPath(ctx);
+}
+/** A copy-pasteable snippet for an agent that is configured by hand. */
+export function agentConfigSnippet(agent, command) {
+    const entry = serverEntry(agent, command);
+    if (agent.format === 'toml')
+        return `${tomlSection(agent, command).join('\n')}\n`;
+    return JSON.stringify({ [agent.serverKey]: { [MCP_SERVER_NAME]: entry } }, null, 2) + '\n';
+}

package/dist/cli/mcp/backend.js

@@ -0,0 +1,235 @@
+/** A failed request, carrying the API's own error code when there is one. */
+export class ApiRequestError extends Error {
+    code;
+    status;
+    constructor(message, status, code) {
+        super(message);
+        this.name = 'ApiRequestError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Parses one SSE frame (the text between blank lines) into an event and payload. */
+export function parseSseFrame(raw) {
+    let event = 'message';
+    const dataLines = [];
+    for (const line of raw.split('\n')) {
+        if (line.length === 0 || line.startsWith(':'))
+            continue;
+        if (line.startsWith('event:')) {
+            event = line.slice('event:'.length).trim();
+            continue;
+        }
+        if (line.startsWith('data:')) {
+            const value = line.slice('data:'.length);
+            dataLines.push(value.startsWith(' ') ? value.slice(1) : value);
+        }
+    }
+    if (dataLines.length === 0)
+        return null;
+    const text = dataLines.join('\n');
+    let data = text;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        // A non-JSON payload is passed through as its raw text.
+    }
+    return { event, data };
+}
+/** Parses every complete frame in `text`. */
+export function parseSseFrames(text) {
+    const frames = [];
+    for (const block of text.replaceAll('\r\n', '\n').split('\n\n')) {
+        const frame = parseSseFrame(block);
+        if (frame !== null)
+            frames.push(frame);
+    }
+    return frames;
+}
+/** Folds one parsed frame into the outcome being collected. */
+function applyFrame(outcome, frame) {
+    const data = frame.data;
+    if (frame.event === 'ready' && data !== null) {
+        if (typeof data.region === 'string')
+            outcome.region = data.region;
+        if (typeof data.source === 'string')
+            outcome.source = data.source;
+        if (Array.isArray(data.groups))
+            outcome.groups = data.groups.filter((group) => typeof group === 'string');
+        return;
+    }
+    if (frame.event === 'log' && data !== null && Array.isArray(data.events)) {
+        for (const event of data.events)
+            outcome.events.push(event);
+        return;
+    }
+    if (frame.event === 'error' && data !== null) {
+        const message = typeof data.message === 'string' ? data.message : 'unknown stream error';
+        outcome.error = message;
+        return;
+    }
+    if (frame.event === 'end' && data !== null && typeof data.reason === 'string') {
+        outcome.reason = data.reason;
+    }
+}
+/**
+ * Reads a `/api/stream` response to completion.
+ *
+ * The route always ends an archive or historic window on its own, and its `end`
+ * frame says why, so the reader never has to guess when to stop.
+ */
+export async function collectStream(response) {
+    const outcome = {
+        region: null,
+        source: 'cloudwatch',
+        groups: [],
+        events: [],
+        reason: null,
+        error: null,
+    };
+    const body = response.body;
+    if (body === null) {
+        for (const frame of parseSseFrames(await response.text()))
+            applyFrame(outcome, frame);
+        return outcome;
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let boundary = buffer.indexOf('\n\n');
+            while (boundary >= 0) {
+                const block = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary + 2);
+                const frame = parseSseFrame(block.replaceAll('\r\n', '\n'));
+                if (frame !== null)
+                    applyFrame(outcome, frame);
+                boundary = buffer.indexOf('\n\n');
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    buffer += decoder.decode();
+    const rest = parseSseFrame(buffer.replaceAll('\r\n', '\n'));
+    if (rest !== null)
+        applyFrame(outcome, rest);
+    return outcome;
+}
+/** Reads the API error envelope from a failed response, if it holds one. */
+async function readApiError(response) {
+    let body = null;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        body = null;
+    }
+    const message = body?.error ?? `watch-tail answered HTTP ${response.status}`;
+    return new ApiRequestError(message, response.status, body?.code);
+}
+/** Builds a URL with only the parameters that have a value. */
+function buildUrl(baseUrl, path, params) {
+    const url = new URL(path, baseUrl);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== null && value !== '')
+            url.searchParams.set(key, value);
+    }
+    return url;
+}
+/** True when a window bound was actually supplied. */
+function isSet(value) {
+    return value !== null && value !== undefined && value.trim().length > 0;
+}
+/** An HTTP implementation of {@link McpBackend}. */
+export function createHttpBackend(input) {
+    const { baseUrl, fetchImpl = fetch } = input;
+    async function getJson(url, signal) {
+        const response = await fetchImpl(url, { signal });
+        if (!response.ok)
+            throw await readApiError(response);
+        return (await response.json());
+    }
+    return {
+        async archiveStatus({ region, signal }) {
+            return getJson(buildUrl(baseUrl, '/api/archive', { region }), signal);
+        },
+        async listLogGroups({ region, prefix, limit, source, signal }) {
+            return getJson(buildUrl(baseUrl, '/api/log-groups', {
+                region,
+                prefix: prefix ?? null,
+                limit: limit === null || limit === undefined ? null : String(limit),
+                source,
+            }), signal);
+        },
+        async identity({ region, signal }) {
+            return getJson(buildUrl(baseUrl, '/api/identity', { region }), signal);
+        },
+        async search(request) {
+            const groups = request.groups;
+            // A tool search is always a bounded window. Saying so explicitly matters
+            // for `source=cloudwatch`: without `mode=historic` the route would tail
+            // live, which never ends (the call would hang) and skips the archive.
+            const customWindow = isSet(request.from) && isSet(request.to);
+            const url = buildUrl(baseUrl, '/api/stream', {
+                region: request.region,
+                source: request.source,
+                mode: 'historic',
+                ...(groups.length === 1 ? { group: groups[0] } : { groups: groups.join(',') }),
+                ...(request.source === 'archive'
+                    ? {
+                        search: request.search ?? null,
+                        level: request.levels && request.levels.length > 0 ? request.levels.join(',') : null,
+                        pageSize: request.pageSize === null || request.pageSize === undefined
+                            ? null
+                            : String(request.pageSize),
+                    }
+                    : { filterPattern: request.filterPattern ?? null }),
+                from: request.from ?? null,
+                to: request.to ?? null,
+                range: customWindow ? null : (request.range ?? null),
+                max: request.max === null || request.max === undefined ? null : String(request.max),
+            });
+            const response = await fetchImpl(url, { signal: request.signal });
+            if (!response.ok)
+                throw await readApiError(response);
+            const outcome = await collectStream(response);
+            return {
+                region: outcome.region,
+                source: outcome.source,
+                groups: outcome.groups.length > 0 ? outcome.groups : groups,
+                // Several groups, and the archived and CloudWatch parts of one window,
+                // stream side by side, so batches arrive interleaved. The sort is
+                // stable: events with one timestamp keep the order they arrived in.
+                events: outcome.events.toSorted((a, b) => a.timestamp - b.timestamp),
+                truncated: outcome.reason === 'event-limit',
+                reason: outcome.reason,
+                error: outcome.error,
+            };
+        },
+        async count(request) {
+            const groups = request.groups;
+            const customWindow = isSet(request.from) && isSet(request.to);
+            const url = buildUrl(baseUrl, '/api/series', {
+                region: request.region,
+                source: 'archive',
+                ...(groups.length === 1 ? { group: groups[0] } : { groups: groups.join(',') }),
+                from: request.from ?? null,
+                to: request.to ?? null,
+                range: customWindow ? null : (request.range ?? null),
+                level: request.levels && request.levels.length > 0 ? request.levels.join(',') : null,
+                bucket: request.bucket ?? null,
+                by: request.by ?? null,
+                metric: request.metric ?? null,
+            });
+            return getJson(url, request.signal);
+        },
+    };
+}