@slack/radar-mcp 1.3.0 → 1.5.0

package/dist/web/spec.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dashboard spec model. A "spec" is the declarative description of one dashboard
+ * tab: which device stream to read, how to filter it, and which widgets to show.
+ * The web client polls `/spec`, the server persists the active spec via `/setspec`,
+ * and the same validate/coerce pass runs on every push so a malformed spec surfaces
+ * an error instead of rendering silent zeros.
+ *
+ * Most sources are live STREAMS (network/rtm/clog/log/all). `db` is the odd one out:
+ * a read-only, point-in-time SQLite BROWSER over the on-device databases, with no viz /
+ * series / match (it has its own list -> tables -> query-grid view). The coerce and
+ * validate passes short-circuit for `db` accordingly.
+ */
+/**
+ * Sources the dashboard can read. The first five are live streams; "all" is their unified
+ * timeline. "db" is a read-only on-device SQLite browser (a point-in-time snapshot, not a
+ * stream) and is handled as a distinct view.
+ */
+export declare const SOURCES: readonly ["rtm", "network", "clog", "log", "all", "db"];
+export type Source = (typeof SOURCES)[number];
+/** Widgets a spec may compose. */
+export declare const VIZ: readonly ["counter", "rate", "sparkline", "feed", "inspector", "graph"];
+export type Viz = (typeof VIZ)[number];
+/** Metrics a graph series can plot. */
+export declare const SERIES_METRICS: readonly ["ratePerSec", "count", "avg", "errorRate"];
+export type SeriesMetric = (typeof SERIES_METRICS)[number];
+declare const HIGHLIGHT_OPS: readonly [">", ">=", "<", "<=", "=="];
+export type HighlightOp = (typeof HIGHLIGHT_OPS)[number];
+export interface GraphSeries {
+    label?: string;
+    metric: SeriesMetric;
+    field?: string;
+    unit?: string;
+}
+export interface Highlight {
+    field: string;
+    op?: HighlightOp;
+    value: number;
+    label?: string;
+}
+export interface Extract {
+    kind?: Source;
+    parse?: "response_body" | "request_body" | "data";
+    field: string;
+    label?: string;
+}
+export interface Alert {
+    sound?: boolean;
+    flash?: boolean;
+    say?: string;
+    at?: number;
+}
+/**
+ * A dashboard spec. `blank: true` is the valid empty state (nothing rendered yet).
+ * `match` is a case-insensitive substring filter keyed on summary fields of the
+ * chosen source.
+ */
+export interface Spec {
+    title?: string;
+    summary?: string;
+    blank?: boolean;
+    source?: Source;
+    match?: Record<string, string>;
+    bodyContains?: string;
+    viz?: Viz[];
+    rateWindowSec?: number;
+    series?: GraphSeries[];
+    extract?: Extract;
+    highlight?: Highlight;
+    alert?: Alert;
+    db?: string;
+    table?: string;
+    sql?: string;
+    [key: string]: unknown;
+}
+/** The empty dashboard. Rendered until a spec is pushed. */
+export declare const BLANK_SPEC: Spec;
+/**
+ * Repair a spec into a renderable shape where the intent is recoverable, rather
+ * than rejecting it outright. The interpreter (and hand edits) sometimes emit
+ * `match` as a bare string instead of a `{field: value}` object, or a `graph`
+ * viz without a `series` array; coerce those into the natural form so the
+ * dashboard degrades gracefully. Returns the same object (mutated) for parity
+ * with the PoC; callers pass a throwaway parse result.
+ */
+export declare function coerceSpec(input: unknown): Spec;
+/**
+ * Validate a (coerced) spec. Returns null when valid, or a human-readable reason
+ * string when not. A bad spec must surface as an error, never as silent zeros.
+ */
+export declare function validateSpec(s: unknown): string | null;
+export {};

package/dist/web/spec.js

@@ -0,0 +1,153 @@
+/**
+ * Dashboard spec model. A "spec" is the declarative description of one dashboard
+ * tab: which device stream to read, how to filter it, and which widgets to show.
+ * The web client polls `/spec`, the server persists the active spec via `/setspec`,
+ * and the same validate/coerce pass runs on every push so a malformed spec surfaces
+ * an error instead of rendering silent zeros.
+ *
+ * Most sources are live STREAMS (network/rtm/clog/log/all). `db` is the odd one out:
+ * a read-only, point-in-time SQLite BROWSER over the on-device databases, with no viz /
+ * series / match (it has its own list -> tables -> query-grid view). The coerce and
+ * validate passes short-circuit for `db` accordingly.
+ */
+/**
+ * Sources the dashboard can read. The first five are live streams; "all" is their unified
+ * timeline. "db" is a read-only on-device SQLite browser (a point-in-time snapshot, not a
+ * stream) and is handled as a distinct view.
+ */
+export const SOURCES = ["rtm", "network", "clog", "log", "all", "db"];
+/** Widgets a spec may compose. */
+export const VIZ = [
+    "counter",
+    "rate",
+    "sparkline",
+    "feed",
+    "inspector",
+    "graph",
+];
+/** Metrics a graph series can plot. */
+export const SERIES_METRICS = [
+    "ratePerSec",
+    "count",
+    "avg",
+    "errorRate",
+];
+const HIGHLIGHT_OPS = [">", ">=", "<", "<=", "=="];
+/** The empty dashboard. Rendered until a spec is pushed. */
+export const BLANK_SPEC = { title: "", blank: true, viz: [] };
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Repair a spec into a renderable shape where the intent is recoverable, rather
+ * than rejecting it outright. The interpreter (and hand edits) sometimes emit
+ * `match` as a bare string instead of a `{field: value}` object, or a `graph`
+ * viz without a `series` array; coerce those into the natural form so the
+ * dashboard degrades gracefully. Returns the same object (mutated) for parity
+ * with the PoC; callers pass a throwaway parse result.
+ */
+export function coerceSpec(input) {
+    if (!isRecord(input))
+        return BLANK_SPEC;
+    const s = input;
+    // The DB browser has no match/viz/series to repair; leave its db/table/sql untouched.
+    if (s.source === "db")
+        return s;
+    if (typeof s.match === "string") {
+        // "all" mixes types whose summary fields differ, so a single field guess
+        // would wrongly exclude other types; treat a bare-string match on "all"
+        // as no filter.
+        if (s.source === "all") {
+            delete s.match;
+        }
+        else {
+            const field = s.source === "rtm"
+                ? "event_type"
+                : s.source === "clog"
+                    ? "event_name"
+                    : "url";
+            s.match = { [field]: s.match };
+        }
+    }
+    // graph series repair: fill if missing/empty, trim to the validator's 1-2 cap,
+    // and drop entries with an unusable metric so the dashboard never hard-rejects.
+    if (Array.isArray(s.viz) && s.viz.includes("graph")) {
+        if (Array.isArray(s.series)) {
+            s.series = s.series.filter((x) => isRecord(x) &&
+                SERIES_METRICS.includes(x.metric) &&
+                !(x.metric === "avg" && !x.field));
+            if (s.series.length > 2)
+                s.series = s.series.slice(0, 2);
+        }
+        if (!Array.isArray(s.series) || s.series.length === 0) {
+            s.series = [{ label: "per second", metric: "ratePerSec", unit: "/s" }];
+        }
+    }
+    return s;
+}
+/**
+ * Validate a (coerced) spec. Returns null when valid, or a human-readable reason
+ * string when not. A bad spec must surface as an error, never as silent zeros.
+ */
+export function validateSpec(s) {
+    if (!isRecord(s))
+        return "not an object";
+    const spec = s;
+    if (spec.blank === true)
+        return null; // empty state is valid
+    if (!spec.source || !SOURCES.includes(spec.source)) {
+        return `source must be one of ${SOURCES.join("|")}`;
+    }
+    // The DB browser is a distinct view: no viz/series/match. Only its optional deep-link
+    // fields are constrained (each must be a string when present).
+    if (spec.source === "db") {
+        for (const k of ["db", "table", "sql"]) {
+            if (spec[k] !== undefined && typeof spec[k] !== "string") {
+                return `${k} must be a string`;
+            }
+        }
+        return null;
+    }
+    if (spec.match !== undefined && !isRecord(spec.match)) {
+        return "match must be an object";
+    }
+    if (!Array.isArray(spec.viz) ||
+        spec.viz.length === 0 ||
+        spec.viz.some((v) => !VIZ.includes(v))) {
+        return `viz must be a non-empty subset of ${VIZ.join("|")}`;
+    }
+    if (spec.extract !== undefined && (!isRecord(spec.extract) || !spec.extract.field)) {
+        return "extract needs a field";
+    }
+    if (spec.alert !== undefined && !isRecord(spec.alert)) {
+        return "alert must be an object";
+    }
+    if (spec.bodyContains !== undefined && typeof spec.bodyContains !== "string") {
+        return "bodyContains must be a string";
+    }
+    if (spec.highlight !== undefined) {
+        const h = spec.highlight;
+        if (!isRecord(h) || !h.field || typeof h.value !== "number") {
+            return "highlight needs field + numeric value";
+        }
+        if (!HIGHLIGHT_OPS.includes((h.op ?? ">"))) {
+            return "highlight op invalid";
+        }
+    }
+    if (spec.viz.includes("graph")) {
+        if (!Array.isArray(spec.series) ||
+            spec.series.length < 1 ||
+            spec.series.length > 2) {
+            return "graph needs a series array of 1-2 entries";
+        }
+        for (const ser of spec.series) {
+            if (!ser || !SERIES_METRICS.includes(ser.metric)) {
+                return `series metric must be one of ${SERIES_METRICS.join("|")}`;
+            }
+            if (ser.metric === "avg" && !ser.field) {
+                return "avg series needs a field";
+            }
+        }
+    }
+    return null;
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@slack/radar-mcp",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "MCP server and web dashboard for on-device debugging of the Slack Android app via ADB",
   "type": "module",
   "main": "dist/mcp/index.js",
   "bin": {
     "radar-mcp": "dist/mcp/index.js",
     "slack-radar-mcp": "dist/mcp/index.js",
+    "slack-radar": "dist/mcp/index.js",
     "slack-radar-web": "dist/web/bin.js"
   },
   "files": [