@zackbart/connecta 0.34.1 → 0.36.0

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

@@ -1,87 +0,0 @@
-import { renderFixPrompt } from "../fix-prompt.js";
-const CATALOGUE = {
-    connector_unavailable: {
-        problem: "A connector is unavailable: its status check or catalog load failed, or did not finish before the operator page's deadline.",
-        steps: [
-            "Confirm the connector's downstream URL or API base in the deployment config, and that the deployment can reach it from where it runs.",
-            "Check the credentials or headers the connector sends; a rejected credential often surfaces as a failed status rather than as an authorization prompt.",
-            "If the downstream is slow rather than down, review the connector's timeouts and the deployment's discovery.probeTimeoutMs.",
-        ],
-    },
-    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 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.",
-        ],
-    },
-    credential_required: {
-        problem: "A connector with an operator-managed credential slot has no usable credential stored.",
-        steps: [
-            "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.",
-        ],
-    },
-    auth_required: {
-        problem: "A connector reports that it needs authorization, and its secret lives in deployment configuration rather than in an operator-managed slot.",
-        steps: [
-            "Find where the connector's secret is read (usually an environment variable or Worker secret passed into the connector config) and confirm it is set in the running environment.",
-            "Rotate the secret at the provider if it expired or was revoked, then update the deployment's environment, not its source.",
-            "If operators should manage this secret from the page instead, declare a credential slot on the connector and configure a credential vault.",
-        ],
-    },
-    credential_mismatch: {
-        problem: "The credential stored for a connector does not match the fields the connector currently declares, so it cannot be used.",
-        steps: [
-            "If the connector's credential fields changed on purpose, re-enter the credential on the operator page so the stored fields match.",
-            "If they changed by accident, restore the previous field names in the connector's credential declaration.",
-        ],
-    },
-    credential_unreadable: {
-        problem: "A stored credential exists but could not be read or decrypted.",
-        steps: [
-            "Check that the credential vault's encryption key in the deployment environment is the one the credential was stored with; a rotated or missing key makes every stored value unreadable.",
-            "Check the storage adapter backing the vault is reachable from the deployment.",
-            "If the key was lost, remove and re-add the credential on the operator page; the old value cannot be recovered.",
-        ],
-    },
-    credential_test_failed: {
-        problem: "The test for a stored connector credential failed: the downstream rejected it, or the test could not reach the downstream.",
-        steps: [
-            "Confirm the stored value is current at the provider (not rotated, revoked, or scoped too narrowly), and replace it on the operator page if not.",
-            "Check that the connector's credential test targets the same API base and auth scheme its tool calls use.",
-        ],
-    },
-    oauth_action_failed: {
-        problem: "Restarting or disconnecting a connector's downstream OAuth from the operator page failed.",
-        steps: [
-            "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 person is a maintainer for shared auth, or a member of a pool containing the connector for personal auth.",
-        ],
-    },
-    catalog_failed: {
-        problem: "A connector reports itself connected, but loading its tool catalog failed, so none of its tools are being served.",
-        steps: [
-            "Check that the downstream still serves a complete tools list; connecta refuses a partial catalog rather than serving part of it.",
-            "Check for tools the connector cannot accept: invalid schemas, missing descriptions, or names that collide.",
-            "Pin or upgrade the @zackbart/connecta version if a maintained provider's catalog changed shape underneath it.",
-        ],
-    },
-    catalog_drift: {
-        problem: "A hosted provider's live catalog differs from the reviewed manifest shipped with connecta: new unclassified tools, unserved tools, annotation conflicts, or schema changes.",
-        steps: [
-            "Unclassified tools are withheld until a release classifies them. Check whether a newer @zackbart/connecta release has, and upgrade if so.",
-            "If a tool the deployment depends on is now unserved or changed shape, review callers of it before upgrading.",
-            "Report drift the release does not cover as an issue on the connecta repository, naming the provider and the kinds of drift but no tool data.",
-        ],
-    },
-};
-/** The clipboard text for one failure. Fixed by kind; see `CATALOGUE`. */
-export function fixPrompt(kind, connectorId) {
-    return renderFixPrompt(CATALOGUE[kind], connectorId);
-}
-/** Every kind, so a test can walk the whole catalogue. */
-export const FIX_PROMPT_KINDS = Object.keys(CATALOGUE);

package/dist/operator-ui/health.js

@@ -1,52 +0,0 @@
-/**
- * The next steady evidence. A settled connector takes its current row; one
- * being read again keeps its previous evidence when this identity has any.
- * Returns `previous` itself when nothing changed, so it can live in React
- * state. A new identity starts empty.
- */
-export function steadyHealth(state, previous) {
-    const same = previous?.generation === state.generation ? previous : null;
-    const contract = state.contract?.role === "maintainer" && state.data ? state.contract : null;
-    // No contract on screen: keep what was shown until the next one arrives.
-    if (!contract || !state.data)
-        return same ?? { generation: state.generation, rows: Object.create(null) };
-    const reading = new Set(state.data.connectors.filter((c) => c.status === "loading").map((c) => c.id));
-    const held = same?.rows ?? Object.create(null);
-    const rows = Object.create(null);
-    let changed = !same || Object.keys(held).length !== contract.live.connectors.length;
-    for (const live of contract.live.connectors) {
-        const before = Object.hasOwn(held, live.id) ? held[live.id] : undefined;
-        if (before && reading.has(live.id)) {
-            rows[live.id] = before;
-            continue;
-        }
-        const failed = Object.hasOwn(state.connectorFailures, live.id) && Boolean(state.connectorFailures[live.id]);
-        if (before?.live === live && before.failed === failed)
-            rows[live.id] = before;
-        else {
-            rows[live.id] = { live, failed };
-            changed = true;
-        }
-    }
-    return changed ? { generation: state.generation, rows } : same;
-}
-/** The contract each view renders health from, with every live row replaced by its steady evidence. */
-export function shownHealth(contract, health) {
-    const signals = Object.create(null);
-    if (!contract)
-        return { contract, signals };
-    let replaced = false;
-    const connectors = contract.live.connectors.map((live) => {
-        const row = Object.hasOwn(health.rows, live.id) ? health.rows[live.id] : undefined;
-        if (row?.failed)
-            signals[live.id] = { failed: true };
-        if (!row || row.live === live)
-            return live;
-        replaced = true;
-        return row.live;
-    });
-    return {
-        contract: replaced ? { ...contract, live: { ...contract.live, connectors } } : contract,
-        signals,
-    };
-}

package/dist/operator-ui/member-page.js

@@ -1,97 +0,0 @@
-import { connectorStatusLabel, connectorStatusTone } from "./view.js";
-/**
- * Whether the member's own partition holds a credential, read from `actions`
- * alone (P6b): `clear` is listed only when a value is stored. Connection
- * state says whether it works, never whether it exists.
- */
-function credentialStored(manage) {
-    return manage.actions.includes("clear");
-}
-function controlsFor(manage, connection) {
-    const can = (action) => (manage.kind === "none" ? false : manage.actions.includes(action));
-    if (manage.kind === "oauth") {
-        const connected = connection.state === "ok";
-        const controls = [];
-        if (!connected && can("connect")) {
-            controls.push({ kind: "connect", label: connection.state === "auth_required" ? "Connect" : "Reconnect" });
-        }
-        if (connected && can("restart"))
-            controls.push({ kind: "restart", label: "Reconnect" });
-        if (connection.state !== "auth_required" && can("disconnect")) {
-            controls.push({ kind: "disconnect", label: "Disconnect" });
-        }
-        return controls;
-    }
-    if (manage.kind === "credential") {
-        // `save` without `clear`: nothing stored yet. `test` is listed only for a stored value.
-        const stored = credentialStored(manage);
-        return [
-            ...(can("save")
-                ? [{ kind: "save", label: stored ? "Replace" : "Add credential" }]
-                : []),
-            ...(can("test") ? [{ kind: "test", label: "Test" }] : []),
-            ...(can("clear") ? [{ kind: "clear", label: "Clear" }] : []),
-        ];
-    }
-    return [];
-}
-/**
- * A few words under the account's name, only where the badge alone would
- * leave something out: a saved credential that no longer fits, or one saved
- * but not working.
- */
-function summaryFor(manage, connection) {
-    if (manage.kind !== "credential" || !credentialStored(manage))
-        return null;
-    if (connection.problem === "credential_mismatch")
-        return "Saved credential no longer fits";
-    return connection.state === "ok" ? null : "Saved, but not working";
-}
-const toolCount = (connector) => connector.tools.length;
-export function memberPage(contract) {
-    if (contract?.role !== "member")
-        return { endpoints: [], accounts: [], shared: [] };
-    return {
-        endpoints: contract.pools.map((pool) => ({ pool: pool.name, path: pool.humanPath })),
-        accounts: contract.connectors
-            .filter((connector) => connector.authScope === "personal")
-            .map((connector) => {
-            const connection = connector.connection ?? { state: "auth_required" };
-            return {
-                id: connector.id,
-                title: connector.title || connector.id,
-                toolCount: toolCount(connector),
-                badge: connector.connection
-                    ? {
-                        label: connectorStatusLabel(connection.state, connection.problem),
-                        tone: connectorStatusTone(connection.state),
-                    }
-                    : null,
-                summary: summaryFor(connector.manage, connection),
-                manage: connector.manage,
-                controls: controlsFor(connector.manage, connection),
-            };
-        }),
-        // Names and counts only: a shared connector's state is not the member's to see.
-        shared: contract.connectors
-            .filter((connector) => connector.authScope === "shared")
-            .map((connector) => ({
-            id: connector.id,
-            title: connector.title || connector.id,
-            toolCount: toolCount(connector),
-        })),
-    };
-}
-export function toolCountLabel(count) {
-    return `${count} ${count === 1 ? "tool" : "tools"}`;
-}
-/** The in-page question before a member's action that takes something away. */
-export function memberConfirmCopy(action, name) {
-    if (action === "oauth_restart") {
-        return { question: `Reconnect ${name}? It stops working until you finish in the new tab.`, confirm: "Reconnect" };
-    }
-    if (action === "oauth_disconnect") {
-        return { question: `Disconnect your ${name} account? Its tools stop working for you.`, confirm: "Disconnect" };
-    }
-    return { question: `Clear your ${name} credential? Its tools stop working for you.`, confirm: "Clear" };
-}

package/dist/operator-ui/overview.js

@@ -1,123 +0,0 @@
-import { endpointRows } from "./endpoints.js";
-import { joinList } from "./connection-map.js";
-import { connectorVerdict } from "./view.js";
-const PROBLEM_TITLE = {
-    connector_unavailable: "is unavailable",
-    oauth_required: "needs authorization",
-    credential_required: "needs a credential",
-    auth_required: "needs a secret in the deployment",
-    credential_mismatch: "can't use its saved credential",
-    catalog_failed: "couldn't load its tools",
-};
-function affects(paths) {
-    return paths.length ? `Affects ${joinList(paths)}` : "No endpoint serves it";
-}
-/**
- * One row per connector that is not healthy, in config order, then one per
- * agent that sits in an endpoint without a working token. Each row carries
- * the fix the rest of the UI already offers for it.
- */
-export function attentionItems(contract, options = {}) {
-    if (contract.role !== "maintainer")
-        return [];
-    const rows = endpointRows(contract);
-    const connectors = [];
-    for (const config of contract.config?.connectors ?? []) {
-        const live = contract.live.connectors.find((c) => c.id === config.id);
-        if (!live)
-            continue;
-        const signals = options.signals && Object.hasOwn(options.signals, config.id) ? options.signals[config.id] : {};
-        const verdict = connectorVerdict(live, signals);
-        if ((verdict.tone !== "warn" && verdict.tone !== "danger") || !verdict.action)
-            continue;
-        const title = config.title ?? config.id;
-        const id = encodeURIComponent(config.id);
-        const paths = rows.filter((row) => row.groups.some((group) => group.config.id === config.id)).map((r) => r.path);
-        const connection = `/connectors/${id}#connection`;
-        const base = {
-            key: `connector:${config.id}`,
-            kind: "connector",
-            tone: verdict.tone,
-            subject: title,
-            action: { label: verdict.action, href: connection, ariaLabel: `${verdict.action} ${title}` },
-            href: connection,
-        };
-        // The server's problem code outranks a failed read on this page: the row
-        // keeps its fix prompt and says the details didn't load. "Unavailable"
-        // beside a failed read is the page's own (see connectorVerdict).
-        const reported = live.problem ?? (live.status === "error" ? "connector_unavailable" : undefined);
-        const problem = signals.failed && reported === "connector_unavailable" ? undefined : reported;
-        if (problem) {
-            connectors.push({
-                ...base,
-                problem: PROBLEM_TITLE[problem],
-                body: signals.failed ? `Details didn't load · ${affects(paths)}` : affects(paths),
-                fix: { kind: problem, connectorId: config.id },
-            });
-        }
-        else if (signals.failed) {
-            connectors.push({
-                ...base,
-                problem: "didn't load on this page",
-                body: affects(paths),
-                fix: null,
-            });
-        }
-        else if (live.status !== "ok") {
-            connectors.push({
-                ...base,
-                problem: verdict.label === "Authorization needed" ? "needs authorization" : "isn't connected",
-                body: affects(paths),
-                fix: null,
-            });
-        }
-    }
-    const agents = contract.agents
-        .filter((agent) => agent.pools.length && agent.token.state !== "issued")
-        .map((agent) => {
-        // An agent connects only at a pool's agent URL.
-        const paths = agent.pools.map((name) => contract.pools.find((pool) => pool.name === name)?.agentPath ?? `/agent/${name}`);
-        const revoked = agent.token.state === "revoked";
-        return {
-            key: `agent:${agent.name}`,
-            kind: "agent",
-            tone: "warn",
-            subject: agent.name,
-            problem: revoked ? "has a revoked token" : "has no token",
-            body: `Can't connect at ${joinList(paths)}`,
-            action: options.tokensPage
-                ? { label: "Issue token", href: "/tokens", ariaLabel: `Issue a token for ${agent.name}` }
-                : null,
-            href: options.tokensPage ? "/tokens" : null,
-            fix: null,
-        };
-    });
-    // Severity changes as individual details settle. Config order keeps surviving
-    // rows in place without waiting for the slowest connector's read.
-    return [...connectors, ...agents];
-}
-/** The numbers above the list, counted from the same map the page draws. */
-export function overviewHeadline(contract, map, items, signals = {}) {
-    const bar = (contract.config?.connectors ?? []).flatMap((config) => {
-        const live = contract.live.connectors.find((c) => c.id === config.id);
-        if (!live)
-            return [];
-        const health = connectorVerdict(live, Object.hasOwn(signals, config.id) ? signals[config.id] : undefined);
-        return [{ id: config.id, title: config.title ?? config.id, tone: health.tone, label: health.label }];
-    });
-    const healthy = bar.filter((entry) => entry.tone === "ok").length;
-    const warn = bar.filter((entry) => entry.tone === "warn").length;
-    const danger = bar.filter((entry) => entry.tone === "danger").length;
-    const count = (kind) => map.nodes.filter((node) => node.kind === kind).length;
-    return {
-        connectors: bar.length,
-        healthy,
-        warn,
-        danger,
-        bar,
-        endpoints: count("endpoint"),
-        readOnlyEndpoints: map.nodes.filter((node) => node.kind === "endpoint" && node.readOnly).length,
-        people: count("person"),
-        agents: contract.agents.length,
-    };
-}

package/dist/operator-ui/setup-commands.js

@@ -1,51 +0,0 @@
-/**
- * Client setup snippets for one MCP endpoint: the deployment's `/mcp` or a
- * `/mcp/<pool>`. Three formats and no more — Claude Code's CLI, Codex's CLI,
- * and the `mcpServers` JSON most other clients read — because a longer list
- * is a list to keep current.
- *
- * None of them carries a credential. A client authenticates through the
- * deployment's inbound auth — OAuth discovery where that is configured — and
- * a token pasted into a snippet on this page would be one rendered by it.
- */
-/**
- * The name a client files this server under. Derived from the deployment's
- * configured server name, reduced to the characters every client CLI accepts
- * unquoted, with the pool appended so two endpoints never collide.
- */
-export function clientServerName(serverName, pool) {
-    const base = (serverName ?? "")
-        .toLowerCase()
-        .replace(/[^a-z0-9_-]+/g, "-")
-        .replace(/-{2,}/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 48) || "connecta";
-    return pool ? `${base}-${pool}` : base;
-}
-/** The URL for a pool: `/mcp` plus its name, which config limits to `[a-z0-9_-]`. */
-export function poolEndpointUrl(mcpUrl, pool) {
-    return `${mcpUrl.replace(/\/+$/, "")}/${encodeURIComponent(pool)}`;
-}
-/** POSIX single-quoting, only when the value needs it. */
-function shellWord(value) {
-    return /^[A-Za-z0-9_./:@%+=,~-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
-}
-export function clientSetupCommands(name, url) {
-    return [
-        {
-            id: "claude",
-            label: "Claude Code",
-            text: `claude mcp add --transport http ${shellWord(name)} ${shellWord(url)}`,
-        },
-        {
-            id: "codex",
-            label: "Codex",
-            text: `codex mcp add ${shellWord(name)} --url ${shellWord(url)}`,
-        },
-        {
-            id: "json",
-            label: "JSON config",
-            text: JSON.stringify({ mcpServers: { [name]: { type: "http", url } } }, null, 2),
-        },
-    ];
-}