@zackbart/connecta 0.32.0 → 0.34.0

package/dist/operator-ui/endpoints.js

@@ -0,0 +1,221 @@
+/** How many chips an endpoint row shows before "+N more". */
+const ACCESS_CHIP_LIMIT = 4;
+/** 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._@-]+/)
+        .filter(Boolean);
+    const letters = words.length > 1 ? words[0][0] + words[1][0] : (words[0] ?? text).slice(0, 2);
+    return letters.toUpperCase();
+}
+/** 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;
+    return hash % 6;
+}
+/** A member as a chip. Labels are null on Access deployments, where the raw id shows instead. */
+function accessChip(member) {
+    if (member.kind === "agent") {
+        const key = `agent:${member.name}`;
+        return { key, kind: "agent", text: member.name, initials: "", hue: hueOf(key) };
+    }
+    const key = `${member.namespace}:${member.id}`;
+    const text = member.label ?? member.id;
+    return { key, kind: "human", text, initials: initialsOf(text), hue: hueOf(key) };
+}
+/** Chips for one endpoint in contract order, people first, without repeats. */
+export function accessChips(members) {
+    const unique = new Map();
+    for (const chip of members.map(accessChip))
+        if (!unique.has(chip.key))
+            unique.set(chip.key, chip);
+    const chips = [...unique.values()];
+    return [...chips.filter((chip) => chip.kind === "human"), ...chips.filter((chip) => chip.kind === "agent")];
+}
+/** The chips a collapsed row shows, and how many the "+N more" button holds back. */
+export function visibleChips(chips, expanded) {
+    if (expanded || chips.length <= ACCESS_CHIP_LIMIT)
+        return { shown: chips, hidden: 0 };
+    return { shown: chips.slice(0, ACCESS_CHIP_LIMIT), hidden: chips.length - ACCESS_CHIP_LIMIT };
+}
+/** Matrix cells for one endpoint, keyed by connector id. */
+function cellsFor(contract, pool) {
+    return new Map(contract.matrix.filter((cell) => cell.pool === pool).map((cell) => [cell.connectorId, cell]));
+}
+/** Plain /mcp declares no tool list; its matrix cells are its grants. */
+function rootGrants(contract) {
+    return contract.matrix
+        .filter((cell) => cell.pool === null)
+        .map((cell) => ({
+        connectorId: cell.connectorId,
+        tools: cell.tools === "all" ? "all" : cell.tools.map((name) => ({ name, requireReadOnly: false })),
+    }));
+}
+/** Intersect declared grants with final live verdicts, in config order. */
+function endpointGroups(contract, grants, readOnly, pool) {
+    const cells = cellsFor(contract, pool);
+    return (contract.config?.connectors ?? []).flatMap((config) => {
+        const live = contract.live.connectors.find((c) => c.id === config.id);
+        const grant = grants.find((g) => g.connectorId === config.id);
+        if (!live || !grant)
+            return [];
+        const tools = live.tools.filter((tool) => {
+            if (readOnly && tool.classification !== "read")
+                return false;
+            return (grant.tools === "all" ||
+                grant.tools.some((g) => g.name === tool.name && (!g.requireReadOnly || tool.classification === "read")));
+        });
+        // A granted connector with no complete catalog still needs a visible fix.
+        return [{ config, live, tools, runsAs: cells.get(config.id)?.runsAs ?? null }];
+    });
+}
+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")
+        return [];
+    const rows = [];
+    if (contract.root) {
+        const groups = endpointGroups(contract, rootGrants(contract), contract.root.readOnly, null);
+        rows.push({
+            pool: null,
+            label: "Default",
+            path: contract.root.path,
+            agentPath: null,
+            readOnly: contract.root.readOnly,
+            toolCount: toolCount(groups),
+            groups,
+            access: accessChips(contract.root.maintainers),
+        });
+    }
+    for (const pool of contract.pools) {
+        const groups = endpointGroups(contract, pool.tools, pool.readOnly, pool.name);
+        rows.push({
+            pool: pool.name,
+            label: pool.name,
+            path: pool.humanPath,
+            agentPath: pool.members.some((member) => member.kind === "agent") ? pool.agentPath : null,
+            readOnly: pool.readOnly,
+            toolCount: toolCount(groups),
+            groups,
+            access: accessChips(pool.members),
+        });
+    }
+    return rows;
+}
+/** A calendar day, without the time: when a shared credential was saved. */
+function formatDay(value) {
+    const date = new Date(value);
+    return Number.isNaN(date.valueOf()) ? "" : date.toLocaleDateString(undefined, { dateStyle: "medium" });
+}
+/** Where a shared credential lives; a vault or OAuth date when the contract has one. */
+function sharedSourceLabel(source, date) {
+    switch (source) {
+        case "vault":
+            return date ? `saved ${date}` : "saved";
+        case "oauth":
+            return date ? `connected ${date}` : "connected";
+        case "missing":
+            return "not configured";
+        case "config":
+            return "set in deployment";
+        case "unauthenticated":
+            return "no credential needed";
+    }
+}
+/** Whose account a connector acts with on one endpoint, in one line. */
+export function runsAsLabel(runsAs, day = formatDay) {
+    switch (runsAs.kind) {
+        case "shared":
+            return `Shared · ${sharedSourceLabel(runsAs.source, runsAs.savedAt ? day(runsAs.savedAt) : "")}`;
+        case "personal":
+            return `Personal · ${runsAs.connectedMembers} of ${runsAs.members} connected`;
+        case "workspace":
+            return `Workspace · people: self · agents: ${runsAs.agents ?? "none"}`;
+        case "workspaceFixed":
+            return `Everyone acts as ${runsAs.subject}`;
+    }
+}
+export function matrixColumns(contract) {
+    if (contract.role !== "maintainer")
+        return [];
+    return [
+        ...(contract.root ? [{ pool: null, path: contract.root.path, readOnly: contract.root.readOnly }] : []),
+        ...contract.pools.map((pool) => ({ pool: pool.name, path: pool.humanPath, readOnly: pool.readOnly })),
+    ];
+}
+/** What one connector × endpoint cell holds, straight from the contract's matrix. */
+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 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 }));
+    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 "—";
+    if (!cell.coverage)
+        return "?";
+    return cell.kind === "all" ? "all" : String(cell.coverage.granted);
+}
+/** 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.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. */
+export function connectorRunsAs(contract, connectorId) {
+    const cells = contract.matrix.filter((cell) => cell.connectorId === connectorId);
+    const root = cells.find((cell) => cell.pool === null);
+    if (root)
+        return root.runsAs;
+    for (const pool of contract.pools) {
+        const cell = cells.find((c) => c.pool === pool.name);
+        if (cell)
+            return cell.runsAs;
+    }
+    return null;
+}

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.",
         ],
@@ -19,8 +19,8 @@ const CATALOGUE = {
     credential_required: {
         problem: "A connector with an operator-managed credential slot has no usable credential stored.",
         steps: [
-            "An operator with credential administration can add the credential on the operator page; that needs no code change.",
-            "If nobody can, grant credential administration through the deployment's identity config (credentialAdministration for shared auth, personalConnection for personal auth), which is denied by default.",
+            "With a credential vault configured, a maintainer adds a shared credential on the operator page, and a pool member saves their own personal one from their view of it; neither needs a code change. Without a vault, configure one first.",
+            "If nobody can, list the person in the deployment's maintainers for shared auth, or in the members of a pool containing the connector for personal auth.",
             "Check that the connector's credential declaration (label and fields) matches what the downstream actually needs.",
         ],
     },
@@ -57,9 +57,9 @@ const CATALOGUE = {
     oauth_action_failed: {
         problem: "Restarting or disconnecting a connector's downstream OAuth from the operator page failed.",
         steps: [
-            "Check that the connector implements startAuth and disconnectAuth, and that the storage holding its OAuth state is writable.",
+            "Check that the connector implements the hooks the action needs (startAuth, finishAuth, and verifyState to connect; disconnectAuth to disconnect), and that the storage holding its OAuth state is writable.",
             "Check the connector's OAuth client configuration, including the authorization server it discovers or is given.",
-            "Confirm the operator has the config-derived permission for this action (credentialAdministration for shared auth, personalConnection for personal auth).",
+            "Confirm the person is a maintainer for shared auth, or a member of a pool containing the connector for personal auth.",
         ],
     },
     catalog_failed: {