watch-tail 0.8.0 → 0.10.0

package/dist/cli/mcp/run.js

@@ -0,0 +1,245 @@
+/**
+ * Orchestration for the two MCP entry points.
+ *
+ * `runMcpServer` owns the lifetime of a private watch-tail server: it starts one
+ * on a free port (or attaches to a URL), serves MCP over stdio, and stops the
+ * server when stdin closes or a signal arrives. `runMcpInit` detects installed
+ * agents, asks which ones to configure, and writes the merge plan from
+ * `agents.ts`. Both take their side effects as arguments, so they can be driven
+ * in a test without a process, a terminal or a filesystem.
+ */
+import { dirname } from 'node:path';
+import { healthUrl, uiUrl } from "../server.js";
+import { createWatchTailServer } from "./tools.js";
+import { AGENTS, AgentConfigError, agentConfigPath, agentConfigSnippet, detectAgents, findAgent, mcpServerCommand, planAgentConfig, } from "./agents.js";
+/** Subscribes to the signals that should stop the server. */
+function defaultSignals(handler) {
+    const events = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    for (const event of events)
+        process.on(event, handler);
+    return () => {
+        for (const event of events)
+            process.off(event, handler);
+    };
+}
+/** Renders a thrown value as a message. */
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Placeholder for the stop resolver until a promise installs the real one. */
+const noop = () => undefined;
+/**
+ * Serves MCP over stdio until the agent closes the connection.
+ *
+ * Nothing but protocol responses is written to `output`: the headless server is
+ * started with its own stdout hidden, and every diagnostic goes to `stderr`.
+ */
+export async function runMcpServer(input, deps) {
+    let child = null;
+    let url = input.url;
+    if (url === null) {
+        if (input.appRoot === null) {
+            input.stderr('Could not find the built app (build/index.js). Run `pnpm build` first.');
+            return 1;
+        }
+        let port;
+        try {
+            port = input.port ?? (await deps.findFreePort());
+        }
+        catch (error) {
+            input.stderr(`could not find a free port for the headless server: ${describe(error)}`);
+            return 1;
+        }
+        url = uiUrl(input.host, port);
+        child = deps.startServer({
+            appRoot: input.appRoot,
+            env: input.childEnv,
+            port,
+            host: input.host,
+            verbose: false,
+        });
+        const ready = await deps.waitForHealth(healthUrl(url), { fetchImpl: deps.fetchImpl });
+        if (!ready) {
+            input.stderr(`the headless watch-tail server did not answer on ${url}`);
+            await deps.stopServer(child);
+            return 1;
+        }
+    }
+    else {
+        const ready = await deps.waitForHealth(healthUrl(url), {
+            fetchImpl: deps.fetchImpl,
+            timeoutMs: 3000,
+        });
+        if (!ready) {
+            input.stderr(`no watch-tail server answered at ${url}`);
+            return 1;
+        }
+    }
+    const backend = deps.createBackend({ baseUrl: url, fetchImpl: deps.fetchImpl });
+    const server = createWatchTailServer({
+        backend,
+        version: input.version,
+        region: input.region,
+    });
+    let releaseStop = noop;
+    const stopped = new Promise((resolve) => {
+        releaseStop = resolve;
+    });
+    const onSignal = () => {
+        input.input.destroy?.();
+        releaseStop();
+    };
+    const unsubscribe = (deps.subscribeSignals ?? defaultSignals)(onSignal);
+    try {
+        await Promise.race([
+            deps.serve({
+                input: input.input,
+                output: input.output,
+                server,
+                onError: (error) => input.stderr(`watch-tail mcp: ${describe(error)}`),
+            }),
+            stopped,
+        ]);
+    }
+    finally {
+        unsubscribe();
+        if (child !== null)
+            await deps.stopServer(child);
+    }
+    return 0;
+}
+/** Resolves the agents named by `--agent`, reporting unknown ids. */
+function namedTargets(ids, ctx, scope, warn) {
+    const targets = [];
+    for (const id of ids) {
+        const agent = findAgent(id);
+        if (agent === null) {
+            warn(`unknown agent "${id}" (known: ${AGENTS.map((entry) => entry.id).join(', ')})`);
+            return null;
+        }
+        const path = agentConfigPath(agent, ctx, scope);
+        if (path === null) {
+            warn(`${agent.name} has no ${scope} configuration`);
+            continue;
+        }
+        targets.push({ agent, path });
+    }
+    return targets;
+}
+/** Resolves every detected agent, at the requested scope. */
+function detectedTargets(ctx, scope, deps) {
+    const targets = [];
+    for (const detected of detectAgents(ctx, deps)) {
+        if (!detected.installed)
+            continue;
+        const path = agentConfigPath(detected.agent, ctx, scope);
+        if (path === null)
+            continue;
+        targets.push({ agent: detected.agent, path });
+    }
+    return targets;
+}
+/** Reads a config file, treating a missing one as empty. */
+function readExisting(path, deps) {
+    try {
+        return deps.readFile(path);
+    }
+    catch {
+        return '';
+    }
+}
+/** Writes the merge plan for one agent, returning whether anything changed. */
+function applyTarget(target, command, deps) {
+    const existing = readExisting(target.path, deps);
+    let plan;
+    try {
+        plan = planAgentConfig({ agent: target.agent, existing, command });
+    }
+    catch (error) {
+        if (error instanceof AgentConfigError) {
+            deps.warn(`could not update ${target.agent.name}: ${error.message}`);
+            return 'failed';
+        }
+        throw error;
+    }
+    if (!plan.changed) {
+        deps.log(`${target.agent.name} already has watch-tail configured (${target.path})`);
+        return 'unchanged';
+    }
+    try {
+        deps.ensureDir(dirname(target.path));
+        deps.writeFile(target.path, plan.contents);
+    }
+    catch (error) {
+        deps.warn(`could not write ${target.path}: ${describe(error)}`);
+        return 'failed';
+    }
+    deps.log(`configured ${target.agent.name} (${target.path})`);
+    return 'written';
+}
+/**
+ * `watch-tail mcp init`: detect installed agents, ask which to configure, and
+ * write the `watch-tail` MCP server into their configuration.
+ *
+ * Exit codes: 0 when every selected agent is configured (or already was), 1 when
+ * nothing was detected or a write failed, 2 for an unknown `--agent` id.
+ */
+export async function runMcpInit(input, deps) {
+    const command = mcpServerCommand({
+        version: input.version,
+        command: input.options.command,
+        args: input.options.args,
+    });
+    const { ctx } = deps;
+    let targets;
+    if (input.options.agents.length > 0) {
+        const resolved = namedTargets(input.options.agents, ctx, input.options.scope, deps.warn);
+        if (resolved === null)
+            return 2;
+        targets = resolved;
+    }
+    else {
+        targets = detectedTargets(ctx, input.options.scope, deps);
+        if (targets.length === 0) {
+            deps.log('No supported AI agents were found on this machine.');
+            deps.log(`Known agents: ${AGENTS.map((agent) => agent.id).join(', ')}.`);
+            deps.log('Pass --agent <id> to configure one anyway, or --print to see the config.');
+            return 1;
+        }
+        deps.log(`Found ${targets.length} agent${targets.length === 1 ? '' : 's'}:`);
+        for (const target of targets)
+            deps.log(`  - ${target.agent.name} (${target.path})`);
+    }
+    if (input.options.print) {
+        for (const target of targets) {
+            deps.log(`\n# ${target.agent.name} - ${target.path}`);
+            deps.log(agentConfigSnippet(target.agent, command).trimEnd());
+        }
+        return 0;
+    }
+    let chosen;
+    if (input.options.yes) {
+        chosen = targets;
+    }
+    else {
+        const ids = await deps.chooseAgents('Which agents should watch-tail be configured in?', targets.map((target) => ({ value: target.agent.id, label: target.agent.name })), targets.map((target) => target.agent.id));
+        const selected = new Set(ids);
+        chosen = targets.filter((target) => selected.has(target.agent.id));
+        if (chosen.length === 0) {
+            deps.warn('nothing selected: no agent was configured (pass --yes to skip the question)');
+            return 1;
+        }
+    }
+    let failures = 0;
+    for (const target of chosen) {
+        if (applyTarget(target, command, deps) === 'failed')
+            failures += 1;
+    }
+    if (failures > 0) {
+        deps.warn(`${failures} agent${failures === 1 ? '' : 's'} could not be configured`);
+        return 1;
+    }
+    const executable = [command.command, ...command.args].join(' ');
+    deps.log(`\nRestart the configured agent so it picks up watch-tail (${executable}).`);
+    return 0;
+}

package/dist/cli/mcp/stdio.js

@@ -0,0 +1,103 @@
+/**
+ * The stdio transport loop for the MCP server.
+ *
+ * tmcp owns the protocol (initialization, capabilities, argument validation,
+ * tool dispatch); this loop only frames messages: newline-delimited JSON-RPC in,
+ * one JSON response line out. It is written here rather than using
+ * `@tmcp/transport-stdio` because that transport calls `process.exit()` itself,
+ * which would tear the process down before the private watch-tail server it
+ * proxies could be stopped gracefully.
+ *
+ * stdout carries the protocol and nothing else; diagnostics go to stderr, which
+ * the caller owns.
+ */
+/** A JSON-RPC parse error, sent for a line that is not JSON. */
+const PARSE_ERROR_RESPONSE = JSON.stringify({
+    jsonrpc: '2.0',
+    id: null,
+    error: { code: -32_700, message: 'Parse error' },
+});
+/**
+ * The fields the protocol defines for an `InitializeResult`.
+ *
+ * tmcp builds the initialize result by spreading the server options it was
+ * constructed with, so its own `adapter` (a class instance) is carried along and
+ * serialised as `{}`. It is an internal detail, not part of the protocol, so a
+ * response to `initialize` is narrowed to the fields a client may expect.
+ */
+const INITIALIZE_RESULT_KEYS = [
+    'protocolVersion',
+    'capabilities',
+    'serverInfo',
+    'instructions',
+    '_meta',
+];
+/** True for a JSON object (not an array or null). */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Narrows an `initialize` response to its protocol fields.
+ *
+ * Any other response is returned untouched; this exists only because tmcp leaks
+ * its own options into that one result.
+ */
+export function sanitizeInitializeResponse(response) {
+    if (!isRecord(response) || !isRecord(response.result))
+        return response;
+    const result = {};
+    for (const key of INITIALIZE_RESULT_KEYS) {
+        if (key in response.result)
+            result[key] = response.result[key];
+    }
+    return { ...response, result };
+}
+/** Writes one line, waiting for the stream to drain when it is backed up. */
+async function write(output, text) {
+    const accepted = output.write(text);
+    if (accepted === false && typeof output.once === 'function') {
+        await new Promise((resolveDrain) => output.once?.('drain', resolveDrain));
+    }
+}
+/** Decodes and answers one line. */
+async function handleLine(line, options) {
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        await write(options.output, `${PARSE_ERROR_RESPONSE}\n`);
+        return;
+    }
+    const response = await options.server.receive(message, { sessionInfo: {} });
+    if (response === undefined || response === null)
+        return;
+    const isInitialize = isRecord(message) && message.method === 'initialize';
+    await write(options.output, `${JSON.stringify(isInitialize ? sanitizeInitializeResponse(response) : response)}\n`);
+}
+/**
+ * Serves MCP messages until the input closes.
+ *
+ * Messages are handled in order, so replies come back in the order the client
+ * sent the calls.
+ */
+export async function serveMcp(options) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for await (const chunk of options.input) {
+        buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+        let newline = buffer.indexOf('\n');
+        while (newline >= 0) {
+            const line = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            if (line.length > 0) {
+                await handleLine(line, options).catch((error) => options.onError?.(error));
+            }
+            newline = buffer.indexOf('\n');
+        }
+    }
+    buffer += decoder.decode();
+    const rest = buffer.trim();
+    if (rest.length > 0)
+        await handleLine(rest, options).catch((error) => options.onError?.(error));
+}

package/dist/cli/mcp/tools.js

@@ -0,0 +1,245 @@
+/**
+ * The MCP tool catalogue, built on `tmcp`.
+ *
+ * tmcp owns the protocol: it negotiates the client's protocol revision (including
+ * the latest `2026-07-28`), advertises capabilities, validates arguments against
+ * the valibot schemas below and frames the responses. This module only says what
+ * watch-tail can do and how a tool call maps onto the backend.
+ *
+ * The schemas are the contract an agent sees, so every field carries a
+ * description; validation failures are reported by tmcp as tool errors rather
+ * than reaching the handlers.
+ */
+import { McpServer } from 'tmcp';
+import { defineTool } from 'tmcp/tool';
+import { tool } from 'tmcp/utils';
+import { ValibotJsonSchemaAdapter } from '@tmcp/adapter-valibot';
+import * as v from 'valibot';
+/** Guidance sent to the agent when it connects. */
+const MCP_INSTRUCTIONS = `watch-tail serves CloudWatch Logs and its local DuckDB archive.
+Every search is a bounded, historic window, like the UI's Historic mode. source="cloudwatch" is the
+default and is archive-first: it reads the archive for the ranges it holds and only calls AWS for
+the gaps, so it is fast and complete. Use source="archive" to stay entirely on this machine (no AWS
+calls, and no 14-day limit - the archive keeps history CloudWatch has already dropped). Start with
+archive_status to see what is stored and which regions it covers, then list_log_groups to find a
+group, then search_logs or count_logs. CloudWatch has no level field, so use filterPattern with
+source="cloudwatch". Timestamps are epoch milliseconds in JSON, and every event also carries an ISO
+8601 time.`;
+/** Shared property descriptions. */
+const REGION = 'AWS region. Defaults to the region the server resolved (profile or AWS_REGION).';
+const GROUPS = 'One or more log group names. Call list_log_groups first; a comma-separated string is accepted too.';
+const SOURCE = 'Where to read: "cloudwatch" (AWS, the default; reads the archive first for historic windows) or "archive" (local DuckDB only, no AWS calls).';
+/** Source used when a tool call does not name one. */
+const DEFAULT_SOURCE = 'cloudwatch';
+const FROM = 'Window start: a duration ("30m", "2h"), epoch milliseconds, or an ISO 8601 timestamp.';
+const TO = 'Window end, in the same forms as from. Defaults to now.';
+const RANGE = 'Preset window when from/to are absent: 15m, 1h, 3h, 12h, 24h or 5d.';
+const LEVELS = 'Archive only: comma-separated levels to keep: error, warn, info, debug.';
+/** A field that is optional and documented. */
+function described(schema, description) {
+    return v.optional(v.pipe(schema, v.description(description)));
+}
+const regionField = described(v.string(), REGION);
+const sourceField = v.optional(v.pipe(v.picklist(['archive', 'cloudwatch']), v.description(SOURCE)));
+const windowFields = {
+    from: described(v.string(), FROM),
+    to: described(v.string(), TO),
+    range: described(v.string(), RANGE),
+};
+/** Normalises a comma-separated string or an array into a de-duplicated list. */
+function toList(value) {
+    if (value === undefined)
+        return [];
+    const items = Array.isArray(value) ? value : value.split(',');
+    const list = [];
+    for (const item of items) {
+        const trimmed = item.trim();
+        if (trimmed.length > 0)
+            list.push(trimmed);
+    }
+    return [...new Set(list)];
+}
+/** Formats one event for the agent. */
+export function formatEvent(event) {
+    return {
+        timestamp: event.timestamp,
+        time: new Date(event.timestamp).toISOString(),
+        group: event.group ?? null,
+        stream: event.streamName ?? null,
+        level: event.level ?? null,
+        requestId: event.requestId ?? null,
+        message: event.message,
+    };
+}
+/** Renders a value as pretty JSON for the MCP text content. */
+function json(value) {
+    return JSON.stringify(value, null, 2);
+}
+/** A short, readable message for a backend failure. */
+/**
+ * Turns a thrown value into the text of a tool error.
+ *
+ * A failed CloudWatch search is the common case on a machine without working
+ * AWS credentials, so it says how to get an answer from the local archive
+ * instead.
+ */
+function failureText(error, source) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error.code;
+    const base = typeof code === 'string' && code.length > 0
+        ? `watch-tail error: ${message} (code: ${code})`
+        : `watch-tail error: ${message}`;
+    return source === 'cloudwatch'
+        ? `${base}. If these events are already stored locally, retry with source="archive".`
+        : base;
+}
+/**
+ * Builds the tmcp server with the watch-tail tools registered.
+ *
+ * The valibot adapter turns each schema into the JSON Schema the client validates
+ * against, and validates the arguments before the handler runs.
+ */
+export function createWatchTailServer(input) {
+    const { backend } = input;
+    const defaultRegion = input.region ?? null;
+    const server = new McpServer({
+        name: 'watch-tail',
+        version: input.version,
+        description: 'Search CloudWatch Logs and the local watch-tail archive.',
+    }, {
+        adapter: new ValibotJsonSchemaAdapter(),
+        capabilities: { tools: {} },
+        instructions: MCP_INSTRUCTIONS,
+    });
+    server.tools([
+        defineTool({
+            name: 'archive_status',
+            description: 'Report what the local watch-tail archive holds: database path, availability, event count, distinct log groups and regions, and the oldest and newest event. Use it to decide whether a search can run offline.',
+            schema: v.object({ region: regionField }),
+        }, async ({ region }) => {
+            try {
+                const status = await backend.archiveStatus({ region: region ?? defaultRegion });
+                return tool.text(json(status));
+            }
+            catch (error) {
+                return tool.error(failureText(error));
+            }
+        }),
+        defineTool({
+            name: 'list_log_groups',
+            description: 'List log group names visible to watch-tail, either from the local archive or from CloudWatch Logs. Archive listings also carry how many events are stored for each group.',
+            schema: v.object({
+                region: regionField,
+                prefix: described(v.string(), 'Only groups whose name starts with this.'),
+                limit: described(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(1000)), 'Maximum groups to return (1-1000).'),
+                source: sourceField,
+            }),
+        }, async ({ region, prefix, limit, source }) => {
+            try {
+                const result = await backend.listLogGroups({
+                    region: region ?? defaultRegion,
+                    prefix: prefix ?? null,
+                    limit: limit ?? null,
+                    source: source ?? DEFAULT_SOURCE,
+                });
+                return tool.text(json({
+                    region: result.region,
+                    source: result.source,
+                    endpoint: result.endpoint,
+                    count: result.groups.length,
+                    groups: result.groups,
+                }));
+            }
+            catch (error) {
+                return tool.error(failureText(error));
+            }
+        }),
+        defineTool({
+            name: 'search_logs',
+            description: 'Search log events over a time window and return them, oldest first. Defaults to source="cloudwatch", which reads the local archive first and only calls AWS for ranges it does not already hold; source="archive" stays entirely local. Archive searches also accept a case-insensitive substring (search) and level filters; CloudWatch searches accept a filterPattern. The result says whether it was truncated at the event limit.',
+            schema: v.object({
+                groups: v.pipe(v.union([v.string(), v.array(v.string())]), v.description(GROUPS)),
+                region: regionField,
+                source: sourceField,
+                search: described(v.string(), 'Archive only: case-insensitive substring of the message.'),
+                level: described(v.union([v.string(), v.array(v.string())]), LEVELS),
+                ...windowFields,
+                filterPattern: described(v.string(), 'CloudWatch only: a CloudWatch Logs filter pattern.'),
+                limit: described(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100_000)), 'Maximum events to return (1-100000).'),
+            }),
+        }, async ({ groups, region, source, search, level, from, to, range, filterPattern, limit }) => {
+            const resolvedSource = source ?? DEFAULT_SOURCE;
+            try {
+                const result = await backend.search({
+                    region: region ?? defaultRegion,
+                    groups: toList(groups),
+                    source: resolvedSource,
+                    search: search ?? null,
+                    levels: resolvedSource === 'archive' ? toList(level) : null,
+                    from: from ?? null,
+                    to: to ?? null,
+                    range: range ?? null,
+                    filterPattern: resolvedSource === 'cloudwatch' ? (filterPattern ?? null) : null,
+                    max: limit ?? 500,
+                });
+                const text = json({
+                    region: result.region,
+                    source: result.source,
+                    groups: result.groups,
+                    count: result.events.length,
+                    truncated: result.truncated,
+                    reason: result.reason,
+                    error: result.error,
+                    events: result.events.map(formatEvent),
+                });
+                return result.error === null ? tool.text(text) : tool.error(text);
+            }
+            catch (error) {
+                return tool.error(failureText(error, resolvedSource));
+            }
+        }),
+        defineTool({
+            name: 'count_logs',
+            description: 'Count archived events per time bucket, per log group and level, without returning the events. Use it to find a spike (or to size a window) before a search. Archive only.',
+            schema: v.object({
+                groups: v.pipe(v.union([v.string(), v.array(v.string())]), v.description(GROUPS)),
+                region: regionField,
+                ...windowFields,
+                level: described(v.union([v.string(), v.array(v.string())]), LEVELS),
+                bucket: described(v.string(), 'Bucket width as a duration or milliseconds. Chosen automatically when omitted.'),
+                by: v.optional(v.pipe(v.picklist(['event', 'request']), v.description('Count lines (event) or requests (request).'))),
+            }),
+        }, async ({ groups, region, from, to, range, level, bucket, by }) => {
+            try {
+                const points = await backend.count({
+                    region: region ?? defaultRegion,
+                    groups: toList(groups),
+                    from: from ?? null,
+                    to: to ?? null,
+                    range: range ?? null,
+                    levels: toList(level),
+                    bucket: bucket ?? null,
+                    by: by ?? null,
+                });
+                return tool.text(json({ count: points.length, points }));
+            }
+            catch (error) {
+                return tool.error(failureText(error));
+            }
+        }),
+        defineTool({
+            name: 'get_identity',
+            description: 'Call STS GetCallerIdentity and report the account and ARN the ambient credentials belong to. Useful before a CloudWatch search, or to confirm which account an archive belongs to.',
+            schema: v.object({ region: regionField }),
+        }, async ({ region }) => {
+            try {
+                const identity = await backend.identity({ region: region ?? defaultRegion });
+                return tool.text(json(identity));
+            }
+            catch (error) {
+                return tool.error(failureText(error));
+            }
+        }),
+    ]);
+    return server;
+}