@interactive-inc/claude-funnel 0.52.0 → 0.55.0

package/dist/funnel-diagnostics-BpKYrMSu.js

@@ -0,0 +1,300 @@
+import { t as ConnectorDiagnosticSqlReader } from "./diagnostic-sql-reader-CzYgZpq2.js";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+//#region lib/services/diagnostics/diagnostic-event.ts
+const stringOrNull = (value) => typeof value === "string" && value.length > 0 ? value : null;
+const numberOrNull = (value) => typeof value === "number" ? value : null;
+const stringOr = (value, fallback) => typeof value === "string" ? value : fallback;
+const isStringKeyedObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const parsePayloadObject = (payload) => {
+	if (payload === null) return null;
+	try {
+		const parsed = JSON.parse(payload);
+		if (isStringKeyedObject(parsed)) return parsed;
+	} catch {
+		return null;
+	}
+	return null;
+};
+const truncate = (text, max) => text.length <= max ? text : `${text.slice(0, max)}…`;
+const previewOf = (payload) => {
+	if (typeof payload !== "string" || payload.length === 0) return null;
+	const parsed = parsePayloadObject(payload);
+	if (parsed !== null && "text" in parsed) return truncate(String(parsed.text), 60);
+	return truncate(payload, 60);
+};
+const toDiagnosticEvent = (row) => {
+	const payload = stringOrNull(row.payload);
+	return {
+		seq: numberOrNull(row.seq),
+		ts: numberOrNull(row.ts),
+		type: stringOr(row.type, "?"),
+		outcome: stringOr(row.outcome, "?"),
+		eventId: stringOrNull(row.event_id),
+		payload,
+		payloadParsed: parsePayloadObject(payload),
+		preview: previewOf(row.payload)
+	};
+};
+const toDiagnosticConnectionError = (row) => ({
+	seq: numberOrNull(row.seq),
+	ts: numberOrNull(row.ts),
+	type: stringOr(row.type, "?"),
+	status: stringOr(row.status, "?"),
+	detail: stringOrNull(row.detail)
+});
+const queryRows = (reader, sql, params) => {
+	try {
+		return reader.query(sql, params);
+	} finally {
+		reader.close();
+	}
+};
+//#endregion
+//#region lib/services/diagnostics/funnel-diagnostics.ts
+const isGatewayStatusResponse = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	if (!("clients" in value) || !Array.isArray(value.clients)) return false;
+	if (!("listeners" in value) || !Array.isArray(value.listeners)) return false;
+	return true;
+};
+const connectorOf = (channel, connectorId) => {
+	if (connectorId === null) return void 0;
+	return channel.connectors?.find((connector) => connector.id === connectorId)?.name;
+};
+const buildDiagnosis = (report) => {
+	const rootCause = (report.connectionErrors[report.connectionErrors.length - 1] ?? null)?.detail ?? null;
+	if (!report.gateway.running) return {
+		status: "error",
+		message: "gateway is not running",
+		nextActions: ["fnl gateway start"],
+		rootCause: null
+	};
+	const channel = report.channel;
+	if (!(report.listeners.length > 0)) return {
+		status: "warn",
+		message: "no connectors configured on this channel",
+		nextActions: [`fnl channels ${channel} connectors add <name> --type=slack ...`],
+		rootCause: null
+	};
+	const allDead = report.listeners.every((l) => !l.alive);
+	const someDead = report.listeners.some((l) => !l.alive);
+	if (allDead) return {
+		status: "error",
+		message: "all listeners are dead",
+		nextActions: ["fnl doctor --fix", "fnl doctor --fix --aggressive"],
+		rootCause
+	};
+	if (someDead) return {
+		status: "warn",
+		message: "some listeners are dead",
+		nextActions: ["fnl doctor --fix"],
+		rootCause
+	};
+	if (report.claudeClients === 0) return {
+		status: "warn",
+		message: "no Claude connected to this channel",
+		nextActions: [`fnl claude --channel ${channel}`],
+		rootCause: null
+	};
+	if (report.listeners.some((l) => l.errors > 0)) return {
+		status: "warn",
+		message: "listeners have errors",
+		nextActions: ["fnl gateway logs"],
+		rootCause
+	};
+	return {
+		status: "ok",
+		message: "everything looks healthy",
+		nextActions: [],
+		rootCause: null
+	};
+};
+/**
+* Programmable diagnostics surface — used by both the CLI (fnl debug …) and
+* the MCP tools (fnl_debug, fnl_recent_events, …). Pure read-side, no
+* mutation; pair with FunnelRecovery for self-healing actions.
+*/
+var FunnelDiagnostics = class {
+	constructor(props) {
+		this.props = props;
+		Object.freeze(this);
+	}
+	async diagnose(channelName) {
+		const channels = this.props.channels.list();
+		const target = channelName ? channels.find((ch) => ch.name === channelName) ?? null : channels[0] ?? null;
+		if (!target) return null;
+		const gatewayBody = await this.fetchGatewayStatus();
+		const store = this.resolveStore();
+		return this.buildChannelDiagnosis(target, gatewayBody, store, 5);
+	}
+	async diagnoseAll() {
+		const channels = this.props.channels.list();
+		const gatewayBody = await this.fetchGatewayStatus();
+		const store = this.resolveStore();
+		const reports = await Promise.all(channels.map((ch) => this.buildChannelDiagnosis(ch, gatewayBody, store, 5)));
+		const errorChannels = reports.filter((r) => r.diagnosis.status === "error").map((r) => r.channel);
+		const warnChannels = reports.filter((r) => r.diagnosis.status === "warn").map((r) => r.channel);
+		const okChannels = reports.filter((r) => r.diagnosis.status === "ok").map((r) => r.channel);
+		const uniqueActions = [...new Set(reports.flatMap((r) => r.diagnosis.nextActions))];
+		return {
+			summary: {
+				total: reports.length,
+				ok: okChannels.length,
+				warn: warnChannels.length,
+				error: errorChannels.length,
+				criticalChannels: errorChannels,
+				warnChannels,
+				suggestedActions: uniqueActions
+			},
+			channels: reports
+		};
+	}
+	async recentEvents(channelName, limit = 20) {
+		const store = this.resolveStore();
+		if (!store) return [];
+		const channelId = this.resolveChannelId(channelName);
+		if (channelName && !channelId) return [];
+		const reader = new ConnectorDiagnosticSqlReader(store);
+		const rows = channelId ? queryRows(reader, "SELECT seq, ts, type, outcome, payload FROM processed WHERE channel_id = ? ORDER BY seq DESC LIMIT ?", [channelId, limit]) : queryRows(reader, "SELECT seq, ts, type, outcome, payload FROM processed ORDER BY seq DESC LIMIT ?", [limit]);
+		if (rows instanceof Error) return [];
+		return rows.reverse().map(toDiagnosticEvent);
+	}
+	async droppedEvents(channelName, limit = 20) {
+		const store = this.resolveStore();
+		if (!store) return [];
+		const channelId = this.resolveChannelId(channelName);
+		if (channelName && !channelId) return [];
+		const reader = new ConnectorDiagnosticSqlReader(store);
+		const rows = channelId ? queryRows(reader, "SELECT seq, ts, type, outcome, payload, event_id FROM processed WHERE channel_id = ? AND outcome LIKE 'skip:%' ORDER BY seq DESC LIMIT ?", [channelId, limit]) : queryRows(reader, "SELECT seq, ts, type, outcome, payload, event_id FROM processed WHERE outcome LIKE 'skip:%' ORDER BY seq DESC LIMIT ?", [limit]);
+		if (rows instanceof Error) return [];
+		return rows.reverse().map(toDiagnosticEvent);
+	}
+	async connectionErrors(channelName, limit = 20) {
+		const store = this.resolveStore();
+		if (!store) return [];
+		const channelId = this.resolveChannelId(channelName);
+		if (channelName && !channelId) return [];
+		const reader = new ConnectorDiagnosticSqlReader(store);
+		const rows = channelId ? queryRows(reader, "SELECT seq, ts, type, status, detail FROM connection WHERE channel_id = ? AND status IN ('auth-failed','error') ORDER BY seq DESC LIMIT ?", [channelId, limit]) : queryRows(reader, "SELECT seq, ts, type, status, detail FROM connection WHERE status IN ('auth-failed','error') ORDER BY seq DESC LIMIT ?", [limit]);
+		if (rows instanceof Error) return [];
+		return rows.reverse().map(toDiagnosticConnectionError);
+	}
+	async replay(channelName, seq) {
+		const channel = this.props.channels.list().find((ch) => ch.name === channelName);
+		if (!channel) return { state: "not-found" };
+		const store = this.resolveStore();
+		if (!store) return {
+			state: "error",
+			reason: "no diagnostic store yet"
+		};
+		const reader = new ConnectorDiagnosticSqlReader(store);
+		const rows = seq !== void 0 ? queryRows(reader, "SELECT seq, event_id, type, payload, connector_id, channel_id FROM processed WHERE channel_id = ? AND seq = ? LIMIT 1", [channel.id, seq]) : queryRows(reader, "SELECT seq, event_id, type, payload, connector_id, channel_id FROM processed WHERE channel_id = ? AND outcome LIKE 'emitted%' ORDER BY seq DESC LIMIT 1", [channel.id]);
+		if (rows instanceof Error) return {
+			state: "error",
+			reason: rows.message
+		};
+		const firstRow = rows[0];
+		if (!firstRow) return { state: "not-found" };
+		const replaySeq = typeof firstRow.seq === "number" ? firstRow.seq : null;
+		const eventId = typeof firstRow.event_id === "string" ? firstRow.event_id : null;
+		const connectorId = typeof firstRow.connector_id === "string" ? firstRow.connector_id : null;
+		let content = typeof firstRow.payload === "string" ? firstRow.payload : null;
+		if ((!content || content.length === 0) && eventId) {
+			const rawRows = queryRows(new ConnectorDiagnosticSqlReader(store), "SELECT payload FROM raw WHERE event_id = ? LIMIT 1", [eventId]);
+			const rawRow = rawRows instanceof Error ? null : rawRows[0];
+			if (rawRow) content = typeof rawRow.payload === "string" ? rawRow.payload : null;
+		}
+		if (!content) return {
+			state: "error",
+			reason: "event has no payload to replay"
+		};
+		const connectorName = connectorOf(channel, connectorId);
+		const result = await this.props.publisher.publish(channel.name, {
+			content,
+			connector: connectorName
+		});
+		if (result.state === "offline") return { state: "offline" };
+		if (result.state === "error") return {
+			state: "error",
+			reason: result.reason
+		};
+		return {
+			state: "ok",
+			seq: replaySeq,
+			offset: result.offset,
+			preview: content.slice(0, 60)
+		};
+	}
+	resolveStore() {
+		const tmpDir = this.props.tmpDir;
+		const rawPath = join(tmpDir, "connector-raw.db");
+		const processedPath = join(tmpDir, "connector-processed.db");
+		const connectionPath = join(tmpDir, "connector-connection.db");
+		if (!existsSync(rawPath) || !existsSync(processedPath) || !existsSync(connectionPath)) return null;
+		return {
+			rawPath,
+			processedPath,
+			connectionPath
+		};
+	}
+	resolveChannelId(channelName) {
+		if (!channelName) return null;
+		return this.props.channels.list().find((ch) => ch.name === channelName)?.id ?? null;
+	}
+	async fetchGatewayStatus() {
+		const gatewayStatus = this.props.gateway.getStatus();
+		if (!gatewayStatus.running) return null;
+		const token = this.props.gatewayToken.read();
+		const headers = token ? { Authorization: `Bearer ${token}` } : {};
+		const res = await fetch(`http://127.0.0.1:${gatewayStatus.port}/status`, { headers }).catch(() => null);
+		if (!res || !res.ok) return null;
+		const body = await res.json();
+		return isGatewayStatusResponse(body) ? body : null;
+	}
+	async buildChannelDiagnosis(target, gatewayBody, store, eventLimit) {
+		const gatewayStatus = this.props.gateway.getStatus();
+		const targetName = target.name;
+		const baseReport = {
+			channel: targetName,
+			channelId: target.id,
+			gateway: {
+				running: gatewayStatus.running,
+				pid: gatewayStatus.pid,
+				port: gatewayStatus.running ? gatewayStatus.port : null,
+				uptimeMs: gatewayBody?.uptimeMs ?? null
+			},
+			listeners: [],
+			claudeClients: 0,
+			recentEvents: [],
+			connectionErrors: []
+		};
+		if (gatewayBody) {
+			baseReport.listeners = gatewayBody.listeners.filter((l) => l.channelName === targetName).map((l) => ({
+				name: l.name,
+				type: l.type,
+				alive: l.alive,
+				events: l.events,
+				errors: l.errors,
+				lastEventAt: l.lastEventAt
+			}));
+			baseReport.claudeClients = gatewayBody.clients.filter((cl) => cl.channelName === targetName).length;
+		}
+		if (store) {
+			const evRows = queryRows(new ConnectorDiagnosticSqlReader(store), "SELECT seq, ts, type, outcome, payload FROM processed WHERE channel_id = ? ORDER BY seq DESC LIMIT ?", [target.id, eventLimit]);
+			if (!(evRows instanceof Error)) baseReport.recentEvents = evRows.reverse().map(toDiagnosticEvent);
+			const hasDeadListeners = baseReport.listeners.some((l) => !l.alive);
+			const hasListenerErrors = baseReport.listeners.some((l) => l.errors > 0);
+			if (hasDeadListeners || hasListenerErrors) {
+				const errRows = queryRows(new ConnectorDiagnosticSqlReader(store), "SELECT ts, type, status, detail FROM connection WHERE channel_id = ? AND status IN ('auth-failed','error') ORDER BY seq DESC LIMIT 3", [target.id]);
+				if (!(errRows instanceof Error)) baseReport.connectionErrors = errRows.reverse().map(toDiagnosticConnectionError);
+			}
+		}
+		return {
+			...baseReport,
+			diagnosis: buildDiagnosis(baseReport)
+		};
+	}
+};
+//#endregion
+export { toDiagnosticEvent as a, toDiagnosticConnectionError as i, previewOf as n, queryRows as r, FunnelDiagnostics as t };

package/dist/funnel-diagnostics-qWy5tPSq.d.ts

@@ -0,0 +1,176 @@
+import { t as ChannelConfig } from "./settings-schema-zhnMIa8I.js";
+
+//#region lib/gateway/diagnostic-log/diagnostic-sql-reader.d.ts
+type Props$1 = {
+  /** SQLite file holding the raw (pre-filter) table. */rawPath: string; /** SQLite file holding the processed (verdict) table. */
+  processedPath: string; /** SQLite file holding the connection (lifecycle) table. */
+  connectionPath: string;
+};
+type Row = Record<string, unknown>;
+/**
+ * Read-only SQL surface over the three diagnostic tables, for Claude to query
+ * the log with arbitrary `SELECT`s. It opens all files read-only and exposes
+ * three views — `raw`, `processed`, `connection` — that hide the storage
+ * details (the physical table is `leuco_log` and each row's columns live
+ * inside a JSON `event` blob): the views surface the columns as plain fields,
+ * with `payload` already pulled out of the nested JSON.
+ *
+ * The tables are separate files. `raw` and `processed` share an `event_id`,
+ * so a `JOIN` answers "the event arrived, but what verdict did it get?";
+ * `connection` answers the other half — "did the listener ever connect at
+ * all?". Writes are impossible: the connection is read-only and `query`
+ * rejects anything but a single `SELECT`.
+ */
+declare class ConnectorDiagnosticSqlReader {
+  private readonly db;
+  constructor(props: Props$1);
+  /**
+   * Run one read-only `SELECT` and return the rows. Returns an `Error` (rather
+   * than throwing) for a non-SELECT statement or a SQL error, so the caller
+   * can surface the message without a stack trace.
+   */
+  query(sql: string, params?: (string | number | null)[]): Row[] | Error;
+  close(): void;
+}
+//#endregion
+//#region lib/services/diagnostics/diagnostic-event.d.ts
+type DiagnosticEvent = {
+  seq: number | null;
+  ts: number | null;
+  type: string;
+  outcome: string;
+  eventId: string | null;
+  payload: string | null;
+  payloadParsed: Record<string, unknown> | null;
+  preview: string | null;
+};
+type DiagnosticConnectionError = {
+  seq: number | null;
+  ts: number | null;
+  type: string;
+  status: string;
+  detail: string | null;
+};
+declare const previewOf: (payload: unknown) => string | null;
+declare const toDiagnosticEvent: (row: Record<string, unknown>) => DiagnosticEvent;
+declare const toDiagnosticConnectionError: (row: Record<string, unknown>) => DiagnosticConnectionError;
+declare const queryRows: (reader: ConnectorDiagnosticSqlReader, sql: string, params: (string | number | null)[]) => Record<string, unknown>[] | Error;
+//#endregion
+//#region lib/services/diagnostics/funnel-diagnostics.d.ts
+/** Narrow channel registry — only `list()` is needed. */
+type DiagnosticsChannelSource = {
+  list(): ChannelConfig[];
+};
+/** Narrow gateway probe — only the daemon status is needed. */
+type DiagnosticsGatewayProbe = {
+  getStatus(): {
+    running: boolean;
+    pid: number | null;
+    port: number;
+  };
+};
+/** Narrow token reader — diagnostics only needs to read the token, never to mint or rotate it. */
+type DiagnosticsTokenReader = {
+  read(): string | null;
+};
+/** Narrow publisher used only for replay. */
+type DiagnosticsPublisher = {
+  publish(channelName: string, request: {
+    content: string;
+    connector?: string;
+  }): Promise<{
+    state: "ok";
+    offset: number;
+  } | {
+    state: "offline";
+  } | {
+    state: "error";
+    reason: string;
+  }>;
+};
+type Props = {
+  gateway: DiagnosticsGatewayProbe;
+  gatewayToken: DiagnosticsTokenReader;
+  channels: DiagnosticsChannelSource;
+  publisher: DiagnosticsPublisher;
+  tmpDir: string;
+};
+type DiagnosisStatus = "ok" | "warn" | "error";
+type ChannelDiagnosis = {
+  channel: string;
+  channelId: string;
+  gateway: {
+    running: boolean;
+    pid: number | null;
+    port: number | null;
+    uptimeMs: number | null;
+  };
+  listeners: Array<{
+    name: string;
+    type: string;
+    alive: boolean;
+    events: number;
+    errors: number;
+    lastEventAt: string | null;
+  }>;
+  claudeClients: number;
+  recentEvents: DiagnosticEvent[];
+  connectionErrors: DiagnosticConnectionError[];
+  diagnosis: {
+    status: DiagnosisStatus;
+    message: string;
+    nextActions: string[];
+    rootCause: string | null;
+  };
+};
+type DiagnoseAllReport = {
+  summary: {
+    total: number;
+    ok: number;
+    warn: number;
+    error: number;
+    criticalChannels: string[];
+    warnChannels: string[];
+    suggestedActions: string[];
+  };
+  channels: ChannelDiagnosis[];
+};
+type ReplayResult = {
+  state: "ok";
+  seq: number | null;
+  offset: number;
+  preview: string | null;
+} | {
+  state: "offline";
+} | {
+  state: "error";
+  reason: string;
+} | {
+  state: "not-found";
+};
+type StorePaths = {
+  rawPath: string;
+  processedPath: string;
+  connectionPath: string;
+};
+/**
+ * Programmable diagnostics surface — used by both the CLI (fnl debug …) and
+ * the MCP tools (fnl_debug, fnl_recent_events, …). Pure read-side, no
+ * mutation; pair with FunnelRecovery for self-healing actions.
+ */
+declare class FunnelDiagnostics {
+  private readonly props;
+  constructor(props: Props);
+  diagnose(channelName?: string): Promise<ChannelDiagnosis | null>;
+  diagnoseAll(): Promise<DiagnoseAllReport>;
+  recentEvents(channelName: string | null, limit?: number): Promise<DiagnosticEvent[]>;
+  droppedEvents(channelName: string | null, limit?: number): Promise<DiagnosticEvent[]>;
+  connectionErrors(channelName: string | null, limit?: number): Promise<DiagnosticConnectionError[]>;
+  replay(channelName: string, seq?: number): Promise<ReplayResult>;
+  resolveStore(): StorePaths | null;
+  private resolveChannelId;
+  private fetchGatewayStatus;
+  private buildChannelDiagnosis;
+}
+//#endregion
+export { DiagnosticsGatewayProbe as a, FunnelDiagnostics as c, DiagnosticEvent as d, previewOf as f, ConnectorDiagnosticSqlReader as g, toDiagnosticEvent as h, DiagnosticsChannelSource as i, ReplayResult as l, toDiagnosticConnectionError as m, DiagnoseAllReport as n, DiagnosticsPublisher as o, queryRows as p, DiagnosisStatus as r, DiagnosticsTokenReader as s, ChannelDiagnosis as t, DiagnosticConnectionError as u };

package/dist/funnel-docs-dXPokzr5.d.ts

@@ -0,0 +1,18 @@
+//#region lib/services/docs/funnel-docs.d.ts
+type DocsTopicListing = {
+  name: string;
+  summary: string;
+};
+/**
+ * Programmable docs surface — used by both the CLI (fnl docs <topic>) and the
+ * MCP / SDK consumers. Docs are embedded into the build so a Claude session
+ * can self-discover funnel's vocabulary without external network access.
+ */
+declare class FunnelDocs {
+  constructor();
+  list(): DocsTopicListing[];
+  get(topic: string): string | null;
+  topics(): string[];
+}
+//#endregion
+export { FunnelDocs as n, DocsTopicListing as t };