@zackbart/connecta 0.33.0 → 0.34.0

package/dist/operator-ui/connection-map.js

@@ -0,0 +1,375 @@
+import { endpointRows, hueOf, initialsOf } from "./endpoints.js";
+import { connectorVerdict } from "./view.js";
+/* Layout. One coordinate system, scaled by the SVG's viewBox. */
+const MAP_WIDTH = 1000;
+const COLUMN_X = [16, 280, 544];
+const COLUMN_WIDTH = [196, 196, 196];
+/** Each connector's read and write tools sit in a fourth column, joined by a straight link. */
+const TOOLS_X = 808;
+const TOOLS_WIDTH = 176;
+const NODE_HEIGHT = 54;
+const NODE_GAP = 12;
+const HEAD = 40;
+const FOOT = 12;
+/** Characters a node's name keeps before it is cut with an ellipsis. */
+const LABEL_LIMIT = [18, 17, 17];
+/** A read-only endpoint's name shares its row with the read-only chip. */
+const READ_ONLY_LABEL_LIMIT = 12;
+/** "a", "a and b", "a, b and c". */
+export function joinList(items) {
+    if (items.length <= 1)
+        return items[0] ?? "";
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function plural(count, one, many = `${one}s`) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/** Cut a name to `limit` characters, ending in an ellipsis when it was longer. */
+export function truncate(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit - 1).trimEnd()}…`;
+}
+/** Where an endpoint's row opens on the Endpoints page. */
+export function endpointHref(path) {
+    return `/endpoints#${path.replace(/^\//, "")}`;
+}
+/** The endpoint path an Endpoints page hash names, or null. */
+export function endpointFromHash(hash) {
+    const value = hash.replace(/^#/, "");
+    return value.startsWith("mcp") ? `/${value}` : null;
+}
+function connectorHref(id, healthy) {
+    return `/connectors/${encodeURIComponent(id)}#${healthy ? "tools" : "connection"}`;
+}
+function tokenWorks(agent) {
+    return agent?.token.state === "issued";
+}
+/**
+ * People in the order the contract first lists them (plain /mcp's
+ * maintainers, then each pool's members), then every declared agent, then any
+ * agent a pool lists that is not declared. Plain /mcp admits no agents.
+ */
+function callersOf(contract, rows) {
+    const people = new Map();
+    const agents = new Map();
+    for (const agent of contract.agents) {
+        agents.set(agent.name, { id: `agent:${agent.name}`, kind: "agent", name: agent.name, agent, endpoints: [] });
+    }
+    const memberLists = rows.map((row) => [
+        row,
+        row.pool === null
+            ? (contract.root?.maintainers ?? [])
+            : (contract.pools.find((pool) => pool.name === row.pool)?.members ?? []),
+    ]);
+    for (const [row, members] of memberLists) {
+        for (const member of members) {
+            if (member.kind === "agent") {
+                if (row.pool === null)
+                    continue;
+                let caller = agents.get(member.name);
+                if (!caller) {
+                    caller = { id: `agent:${member.name}`, kind: "agent", name: member.name, agent: null, endpoints: [] };
+                    agents.set(member.name, caller);
+                }
+                if (!caller.endpoints.includes(row))
+                    caller.endpoints.push(row);
+                continue;
+            }
+            const id = `person:${member.namespace}:${member.id}`;
+            let caller = people.get(id);
+            if (!caller) {
+                caller = { id, kind: "person", name: member.label ?? member.id, agent: null, endpoints: [] };
+                people.set(id, caller);
+            }
+            if (!caller.endpoints.includes(row))
+                caller.endpoints.push(row);
+        }
+    }
+    return [...people.values(), ...agents.values()];
+}
+/** Unique live tools a set of endpoints serves, by address. */
+function servedTools(rows) {
+    const connectors = new Set();
+    const tools = new Map();
+    for (const row of rows) {
+        for (const group of row.groups) {
+            connectors.add(group.config.id);
+            for (const tool of group.tools)
+                tools.set(tool.address, tool.classification);
+        }
+    }
+    const write = [...tools.values()].filter((value) => value === "write").length;
+    return { connectors, tools: tools.size, write };
+}
+export function toolsPhrase(tools, write) {
+    if (!tools)
+        return "no tools";
+    return write ? `${plural(tools, "tool")}, ${write} write` : `${plural(tools, "tool")}, all read`;
+}
+function callerSummary(caller) {
+    const name = caller.name;
+    if (!caller.endpoints.length) {
+        return caller.kind === "agent" ? `${name} is in no endpoint, so it reaches nothing.` : `${name} reaches nothing.`;
+    }
+    const served = servedTools(caller.endpoints);
+    // An agent connects only at a pool's agent URL, never the people's one.
+    const through = joinList(caller.endpoints.map((row) => (caller.kind === "agent" ? (row.agentPath ?? row.path) : row.path)));
+    const reach = served.connectors.size
+        ? `${name} reaches ${plural(served.connectors.size, "connector")} through ${through}: ${toolsPhrase(served.tools, served.write)}.`
+        : `${name} uses ${through}, which serves no connectors.`;
+    if (caller.kind !== "agent" || tokenWorks(caller.agent))
+        return reach;
+    const state = caller.agent?.token.state;
+    return `${reach} ${state === "revoked" ? "Its token is revoked" : "It has no token"}, so it can't connect.`;
+}
+function callerDetail(caller, maintainers) {
+    if (caller.kind === "person")
+        return maintainers.has(caller.id) ? "maintainer" : "member";
+    const state = caller.agent?.token.state;
+    return state === "issued"
+        ? "agent · token issued"
+        : state === "revoked"
+            ? "agent · token revoked"
+            : "agent · no token";
+}
+function endpointSummary(row, callers) {
+    const listed = callers.filter((caller) => caller.endpoints.includes(row));
+    const people = listed.filter((caller) => caller.kind === "person").length;
+    const agents = listed.length - people;
+    const who = row.pool === null ? plural(people, "maintainer") : plural(people, "person", "people");
+    const users = agents ? `${who} and ${plural(agents, "agent")}` : who;
+    const served = servedTools([row]);
+    const mode = row.readOnly ? `${row.path} is read-only and serves ${users}` : `${row.path} serves ${users}`;
+    if (!served.connectors.size)
+        return `${mode}. It has no connectors.`;
+    return `${mode} with ${plural(served.connectors.size, "connector")}: ${toolsPhrase(served.tools, served.write)}.`;
+}
+const STATUS_SENTENCE = {
+    ok: "",
+    neutral: "",
+    warn: " It needs attention.",
+    danger: " It is failing.",
+};
+function connectorSummary(title, id, health, rows, callers) {
+    const on = rows.filter((row) => row.groups.some((group) => group.config.id === id));
+    const status = STATUS_SENTENCE[health.tone];
+    if (!on.length)
+        return `No endpoint serves ${title}, so nobody reaches it.${status}`;
+    const reaching = callers.filter((caller) => caller.endpoints.some((row) => on.includes(row)));
+    const people = reaching.filter((caller) => caller.kind === "person").length;
+    const agents = reaching.length - people;
+    const who = agents
+        ? `${plural(people, "person", "people")} and ${plural(agents, "agent")}`
+        : plural(people, "person", "people");
+    const verb = reaching.length === 1 ? "reaches" : "reach";
+    return `${who} ${verb} ${title} through ${joinList(on.map((row) => row.path))}.${status}`;
+}
+function edgePath(from, to) {
+    const x1 = from.x + from.width;
+    const y1 = from.y + from.height / 2;
+    const x2 = to.x;
+    const y2 = to.y + to.height / 2;
+    const dx = (x2 - x1) / 2;
+    return `M${x1},${y1} C${x1 + dx},${y1} ${x2 - dx},${y2} ${x2},${y2}`;
+}
+/** Each column's nodes stacked from the top, the shorter columns centered on the tallest. */
+function place(nodes) {
+    const columns = [0, 1, 2].map((column) => nodes.filter((node) => node.column === column));
+    const tallest = Math.max(1, ...columns.map((column) => column.length));
+    const body = tallest * (NODE_HEIGHT + NODE_GAP) - NODE_GAP;
+    columns.forEach((column, index) => {
+        const height = column.length * (NODE_HEIGHT + NODE_GAP) - NODE_GAP;
+        const top = HEAD + Math.max(0, (body - height) / 2);
+        column.forEach((node, position) => {
+            node.x = COLUMN_X[index];
+            node.width = COLUMN_WIDTH[index];
+            node.height = NODE_HEIGHT;
+            node.y = top + position * (NODE_HEIGHT + NODE_GAP);
+            if (node.kind === "connector")
+                node.toolsBox = { x: TOOLS_X, y: node.y, width: TOOLS_WIDTH, height: NODE_HEIGHT };
+        });
+    });
+    return HEAD + body + FOOT;
+}
+function node(fields, limit) {
+    return { hue: 0, ...fields, label: truncate(fields.name, limit), toolsBox: null, x: 0, y: 0, width: 0, height: 0 };
+}
+/** A connector's tile: two words' initials, a camel-case title's two capitals, or one letter. */
+export function monogram(title) {
+    const words = title.split(/[\s._-]+/).filter(Boolean);
+    if (words.length > 1)
+        return (words[0][0] + words[1][0]).toUpperCase();
+    const capitals = title.match(/[A-Z]/g) ?? [];
+    if (capitals.length >= 2)
+        return capitals[0] + capitals[1];
+    return (words[0] ?? title).charAt(0).toUpperCase();
+}
+/** The whole map for a maintainer's contract; an empty map for anyone else. */
+export function connectionMap(contract, options = {}) {
+    const rows = contract.role === "maintainer" ? endpointRows(contract) : [];
+    const callers = callersOf(contract, rows);
+    const maintainers = new Set((contract.root?.maintainers ?? []).flatMap((member) => member.kind === "human" ? [`person:${member.namespace}:${member.id}`] : []));
+    const connectors = (contract.role === "maintainer" ? (contract.config?.connectors ?? []) : []).flatMap((config) => {
+        const live = contract.live.connectors.find((c) => c.id === config.id);
+        return live ? [{ config, live, health: connectorVerdict(live, options.signals?.[config.id]) }] : [];
+    });
+    const health = new Map(connectors.map(({ config, health }) => [config.id, health]));
+    const nodes = [];
+    for (const caller of callers) {
+        const works = caller.kind === "person" || tokenWorks(caller.agent);
+        nodes.push(node({
+            id: caller.id,
+            kind: caller.kind,
+            column: 0,
+            name: caller.name,
+            detail: callerDetail(caller, maintainers),
+            href: caller.kind === "agent"
+                ? options.tokensPage
+                    ? "/tokens"
+                    : null
+                : caller.endpoints[0]
+                    ? endpointHref(caller.endpoints[0].path)
+                    : null,
+            tone: works ? "neutral" : "warn",
+            readOnly: false,
+            tools: null,
+            initials: caller.kind === "person" ? initialsOf(caller.name) : "",
+            hue: caller.kind === "person" ? hueOf(caller.id.slice("person:".length)) : 0,
+            summary: callerSummary(caller),
+        }, LABEL_LIMIT[0]));
+    }
+    for (const row of rows) {
+        const listed = callers.filter((caller) => caller.endpoints.includes(row)).length;
+        nodes.push(node({
+            id: `endpoint:${row.path}`,
+            kind: "endpoint",
+            column: 1,
+            name: row.path,
+            detail: `${row.pool === null ? "maintainers" : plural(listed, "caller")} · ${plural(row.groups.length, "connector")}`,
+            href: endpointHref(row.path),
+            tone: "neutral",
+            readOnly: row.readOnly,
+            tools: null,
+            initials: "",
+            summary: endpointSummary(row, callers),
+        }, row.readOnly ? READ_ONLY_LABEL_LIMIT : LABEL_LIMIT[1]));
+    }
+    for (const { config, live, health: verdict } of connectors) {
+        const title = config.title ?? config.id;
+        const read = live.tools.filter((tool) => tool.classification === "read").length;
+        const scope = config.authScope === "personal" ? "personal" : "shared";
+        // A failed or unobserved catalog has no tools to count, which is not zero tools.
+        const known = live.tools.length > 0 || (live.status === "ok" && !live.problem);
+        nodes.push(node({
+            id: `connector:${config.id}`,
+            kind: "connector",
+            column: 2,
+            name: title,
+            detail: verdict.tone === "ok" ? `${scope} · ${plural(live.tools.length, "tool")}` : verdict.label,
+            href: connectorHref(config.id, verdict.tone === "ok"),
+            tone: verdict.tone,
+            readOnly: false,
+            tools: known ? { read, write: live.tools.length - read } : null,
+            initials: monogram(title),
+            summary: connectorSummary(title, config.id, verdict, rows, callers),
+        }, LABEL_LIMIT[2]));
+    }
+    const height = place(nodes);
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const edges = [];
+    for (const caller of callers) {
+        for (const row of caller.endpoints) {
+            const from = byId.get(caller.id);
+            const to = byId.get(`endpoint:${row.path}`);
+            edges.push({
+                id: `${from.id}>${to.id}`,
+                from: from.id,
+                to: to.id,
+                kind: "access",
+                tone: "neutral",
+                readOnly: false,
+                noToken: caller.kind === "agent" && !tokenWorks(caller.agent),
+                served: null,
+                path: edgePath(from, to),
+            });
+        }
+    }
+    for (const row of rows) {
+        for (const group of row.groups) {
+            const from = byId.get(`endpoint:${row.path}`);
+            const to = byId.get(`connector:${group.config.id}`);
+            if (!to)
+                continue;
+            edges.push({
+                id: `${from.id}>${to.id}`,
+                from: from.id,
+                to: to.id,
+                kind: "grant",
+                tone: health.get(group.config.id)?.tone ?? "neutral",
+                readOnly: row.readOnly,
+                noToken: false,
+                served: {
+                    tools: group.tools.length,
+                    write: group.tools.filter((tool) => tool.classification === "write").length,
+                },
+                path: edgePath(from, to),
+            });
+        }
+    }
+    return {
+        nodes,
+        edges,
+        width: MAP_WIDTH,
+        height,
+        columns: [
+            { label: "Callers", count: callers.length, x: COLUMN_X[0] },
+            { label: "Endpoints", count: rows.length, x: COLUMN_X[1] },
+            { label: "Connectors", count: connectors.length, x: COLUMN_X[2] },
+            { label: "Tools", count: connectors.reduce((n, { live }) => n + live.tools.length, 0), x: TOOLS_X },
+        ],
+    };
+}
+/**
+ * What hovering a node lights up: every node and link on a path through it.
+ * Links are walked forward from the node and backward to it, never both ways
+ * from a neighbor, so a caller lights only what it reaches and a connector
+ * lights only who reaches it.
+ */
+export function mapHighlight(map, id) {
+    const nodes = new Set([id]);
+    const edges = new Set();
+    const walk = (forward) => {
+        const queue = [id];
+        const seen = new Set([id]);
+        while (queue.length) {
+            const current = queue.shift();
+            for (const edge of map.edges) {
+                if ((forward ? edge.from : edge.to) !== current)
+                    continue;
+                const target = forward ? edge.to : edge.from;
+                edges.add(edge.id);
+                nodes.add(target);
+                if (!seen.has(target)) {
+                    seen.add(target);
+                    queue.push(target);
+                }
+            }
+        }
+    };
+    walk(true);
+    walk(false);
+    return { nodes, edges };
+}
+export function mapList(map) {
+    const byId = new Map(map.nodes.map((n) => [n.id, n]));
+    return map.nodes
+        .filter((n) => n.kind === "endpoint")
+        .map((endpoint) => ({
+        endpoint,
+        callers: map.edges
+            .filter((edge) => edge.to === endpoint.id)
+            .map((edge) => ({ node: byId.get(edge.from), noToken: edge.noToken })),
+        connectors: map.edges
+            .filter((edge) => edge.from === endpoint.id)
+            .map((edge) => ({ node: byId.get(edge.to), served: edge.served ?? { tools: 0, write: 0 } })),
+    }));
+}

package/dist/operator-ui/endpoints.js

@@ -1,6 +1,7 @@
 /** How many chips an endpoint row shows before "+N more". */
 const ACCESS_CHIP_LIMIT = 4;
-function initialsOf(text) {
+/** Up to two letters for a person's avatar, from their label or raw id. */
+export function initialsOf(text) {
     const words = text
         .replace(/^user_/, "")
         .split(/[\s._@-]+/)
@@ -8,7 +9,8 @@ function initialsOf(text) {
     const letters = words.length > 1 ? words[0][0] + words[1][0] : (words[0] ?? text).slice(0, 2);
     return letters.toUpperCase();
 }
-function hueOf(key) {
+/** A stable tint bucket for a member key, shared by chips and the Overview map. */
+export function hueOf(key) {
     let hash = 0;
     for (const char of key)
         hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
@@ -18,7 +20,7 @@ function hueOf(key) {
 function accessChip(member) {
     if (member.kind === "agent") {
         const key = `agent:${member.name}`;
-        return { key, kind: "agent", text: key, initials: "", hue: hueOf(key) };
+        return { key, kind: "agent", text: member.name, initials: "", hue: hueOf(key) };
     }
     const key = `${member.namespace}:${member.id}`;
     const text = member.label ?? member.id;
@@ -71,6 +73,18 @@ function endpointGroups(contract, grants, readOnly, pool) {
     });
 }
 const toolCount = (groups) => groups.reduce((n, group) => n + group.tools.length, 0);
+/** How many of these tools read and how many write; an unclassified tool counts as neither. */
+export function toolSplit(tools) {
+    let read = 0;
+    let write = 0;
+    for (const tool of tools) {
+        if (tool.classification === "read")
+            read++;
+        else if (tool.classification === "write")
+            write++;
+    }
+    return { read, write };
+}
 /** One row for plain /mcp, then one per pool, in contract order. Maintainer view only. */
 export function endpointRows(contract) {
     if (contract.role !== "maintainer")
@@ -150,24 +164,46 @@ export function matrixCell(contract, connectorId, column) {
     const cell = contract.matrix.find((c) => c.connectorId === connectorId && c.pool === column.pool);
     if (!cell)
         return { kind: "none" };
-    const live = contract.live.connectors.find((c) => c.id === connectorId)?.tools ?? [];
+    const overlay = contract.live.connectors.find((c) => c.id === connectorId);
+    const live = overlay?.tools ?? [];
     const tools = cell.tools === "all"
         ? live.map(({ name, classification }) => ({ name, classification }))
         : cell.tools.map((name) => ({ name, classification: live.find((t) => t.name === name)?.classification ?? null }));
-    return { kind: cell.tools === "all" ? "all" : "some", tools, runsAs: cell.runsAs };
+    const known = overlay && (live.length > 0 || (overlay.status === "ok" && !overlay.problem));
+    const granted = cell.tools === "all" ? live : live.filter((tool) => cell.tools.includes(tool.name));
+    return {
+        kind: cell.tools === "all" ? "all" : "some",
+        tools,
+        runsAs: cell.runsAs,
+        coverage: known ? { granted: granted.length, total: live.length } : null,
+    };
+}
+/** The live grant fraction, or null when no complete catalog is available. */
+export function matrixCellShare(cell) {
+    if (cell.kind === "none")
+        return 0;
+    if (!cell.coverage)
+        return null;
+    return cell.coverage.total ? cell.coverage.granted / cell.coverage.total : 0;
 }
 /** The cell's visible text: "all", a count, or a dash. */
 export function matrixCellText(cell) {
     if (cell.kind === "none")
         return "—";
-    return cell.kind === "all" ? "all" : String(cell.tools.length);
+    if (!cell.coverage)
+        return "?";
+    return cell.kind === "all" ? "all" : String(cell.coverage.granted);
 }
-/** The cell's accessible name, e.g. "GitHub on /support: 3 tools". */
+/** The cell's accessible name, e.g. "GitHub on /mcp/support: 1 of 2 live tools". */
 export function matrixCellLabel(connector, column, cell) {
     const where = `${connector} on ${column.path}`;
     if (cell.kind === "none")
         return `${where}: no tools`;
-    const what = cell.kind === "all" ? "all tools" : `${cell.tools.length} ${cell.tools.length === 1 ? "tool" : "tools"}`;
+    const what = !cell.coverage
+        ? "unknown live tool coverage"
+        : cell.kind === "all"
+            ? `all ${cell.coverage.total} tools`
+            : `${cell.coverage.granted} of ${cell.coverage.total} live tools`;
     return `${where}: ${what}${column.readOnly ? ", read-only" : ""}`;
 }
 /** The connector's subject for the matrix's Runs as column: the /mcp cell, else its first pool's. */
@@ -183,10 +219,3 @@ export function connectorRunsAs(contract, connectorId) {
     }
     return null;
 }
-/** Who may use plain /mcp, for Settings: each maintainer by label, else by raw id. */
-export function rootAccessSentence(root) {
-    const names = root.maintainers.map((member) => (member.kind === "human" ? (member.label ?? member.id) : member.name));
-    return names.length
-        ? `Only maintainers can use ${root.path}: ${names.join(", ")}.`
-        : `Only maintainers can use ${root.path}, and none are listed.`;
-}

package/dist/operator-ui/fix-prompts.js

@@ -11,7 +11,7 @@ const CATALOGUE = {
     oauth_required: {
         problem: "A downstream OAuth connector needs authorization: no grant is stored, or the stored grant expired or was revoked and could not be refreshed.",
         steps: [
-            "Reauthorize from the operator page (Connect account or Reconnect OAuth) or with authorize_connector; this needs no code change if the grant simply lapsed.",
+            "Reauthorize from the connector's Connection tab (Connect or Reconnect) or with authorize_connector. A lapsed grant needs no code change.",
             "If it needs reauthorizing again soon after, check that the OAuth client requests offline access or a refresh token, and that the storage holding OAuth tokens persists across restarts and is shared by every instance.",
             "If authorization cannot start at all, check the connector's OAuth client configuration and the deployment's publicUrl, which forms the /oauth/callback/<connector id> redirect URI.",
         ],