@zackbart/connecta 0.32.0 → 0.34.0

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

@@ -0,0 +1,97 @@
+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/model.d.ts

@@ -1,4 +1,5 @@
-import type { OperatorConnectorOverlay, OperatorTool, OperatorUiContract, OperatorViewer } from "./contract.js";
+import type { ConnectaConfigDescription } from "../describe-config.js";
+import type { OperatorConnectorOverlay, OperatorTool } from "./contract.js";
 import type { CatalogAccessObservation, CatalogDriftReport, ResourceTemplateRefusalCode } from "../types.js";
 /** Tool verdicts, independent of whether the selected pool is read-only. */
 export type UiToolSafety = "runs_in_programs" | "needs_approval";
@@ -28,7 +29,8 @@ interface UiCredentialField {
     description?: string;
     placeholder?: string;
     inputType: "email" | "password" | "text";
-    configured: boolean;
+    /** null when metadata could not be read. */
+    configured: boolean | null;
     lastFour?: string;
     updatedAt?: string;
 }
@@ -37,7 +39,8 @@ interface UiCredential {
     description?: string;
     placeholder?: string;
     fields?: UiCredentialField[];
-    configured: boolean;
+    /** null when metadata could not be read. */
+    configured: boolean | null;
     /** A stored value exists and may be deleted even if it cannot be decrypted. */
     removable?: boolean;
     lastFour?: string;
@@ -60,7 +63,12 @@ export interface UiConnector {
     title?: string;
     description?: string;
     status: "loading" | OperatorConnectorOverlay["status"];
-    permissions?: Omit<OperatorViewer["permissions"]["connectors"][number], "id">;
+    /** What this maintainer may do with the connector. */
+    permissions?: {
+        use: boolean;
+        manageSharedAuth: boolean;
+        connectPersonal: boolean;
+    };
     /**
      * Why this connector is not usable, when it is not. See `UiProblem`. The
      * only failure detail the payload carries; the status message behind it is
@@ -91,9 +99,9 @@ export interface UiConnector {
 export type CredentialManagementCapability = "available" | "requires_operator" | "vault_not_configured" | "no_slots";
 export interface UiData {
     accessTokenManagement?: "available" | "requires_operator";
-    serverInfo: Pick<OperatorUiContract["config"]["server"], "name" | "version">;
+    serverInfo: Pick<ConnectaConfigDescription["server"], "name" | "version">;
     /** Version of the installed @zackbart/connecta package. */
-    connectaVersion: OperatorUiContract["config"]["connectaVersion"];
+    connectaVersion: ConnectaConfigDescription["connectaVersion"];
     connectors: UiConnector[];
     activityEnabled: boolean;
     credentialManagement: CredentialManagementCapability;

package/dist/operator-ui/overview.js

@@ -0,0 +1,134 @@
+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, failing first, 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?.[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,
+            });
+        }
+        else {
+            // Healthy but drifted: the live tool list differs from the reviewed one.
+            connectors.push({
+                ...base,
+                problem: "has a changed tool list",
+                body: affects(paths),
+                fix: { kind: "catalog_drift", connectorId: config.id },
+            });
+        }
+    }
+    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,
+        };
+    });
+    return [
+        ...connectors.filter((item) => item.tone === "danger"),
+        ...connectors.filter((item) => item.tone === "warn"),
+        ...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, signals[config.id]);
+        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/view.d.ts

@@ -1,30 +1,29 @@
-import type { OperatorUiContract } from "./contract.js";
+import type { OperatorRole, OperatorUiContractV2 } from "./contract.js";
 import type { CatalogDriftReport } from "../types.js";
 import type { CredentialManagementCapability, UiConnector, UiData, UiProblem } from "./model.js";
 import type { FixPromptKind } from "./fix-prompts.js";
+import type { AgentSlot } from "./agents.js";
 export declare function registrationPathLabel(path: NonNullable<UiConnector["registrationPath"]>): string;
-/**
- * A connector's source column: the maintained provider with the
- * implementation it uses, since a dual provider's `auth` selects either the
- * vendor's hosted MCP server or Connecta's REST connector.
- */
-export declare function connectorSourceLabel(source: {
-    kind: string;
-    provider?: string;
-}): string;
-export type OperatorPage = "overview" | "tools" | "access" | "config" | "connector" | "tokens" | "connections" | "activity";
-/** Pages the nav lists. */
+export type OperatorPage = "overview" | "endpoints" | "settings" | "connector" | "tokens" | "connections" | "activity";
+/** Pages the nav lists, in dashboard order. */
 export declare const OPERATOR_PAGES: readonly OperatorPage[];
 export declare const PAGE_META: Readonly<Record<OperatorPage, {
     path: string;
     label: string;
 }>>;
+/** Legacy links remain valid, with the browser replacing their URL. */
+export declare function canonicalOperatorPath(path: string): string;
 /**
  * What each page is for, in one line under its heading — on the gate as well
  * as once signed in, so the page an operator lands on reads the same before
  * and after the session is checked.
  */
 export declare function pageDescription(page: OperatorPage, productDescription: string): string;
+/**
+ * Signed in, but neither a maintainer nor a member of any endpoint: who to
+ * ask, and that this is not an error to retry.
+ */
+export declare function noAccessCopy(kind: string, productName: string): string;
 /** What the gate says while the session is checked, page by page. */
 export declare function checkingCopy(): string;
 export declare function pageForPath(path: string): OperatorPage;
@@ -83,12 +82,16 @@ export declare function failure(message: string, fix?: NoticeFix): Notice;
  *   mutation that is a permission, not an expired session, so it stays inline.
  * - `network` — the browser could not reach the deployment at all.
  * - `refused` — the route answered, and said no.
+ * - `stale` — never sent: what the action was checked against changed before
+ *   dispatch (a refreshed slot list or member contract).
  */
-export type RequestFailureKind = "session" | "forbidden" | "network" | "refused";
+export type RequestFailureKind = "session" | "forbidden" | "network" | "refused" | "stale";
 export interface RequestFailureFacts {
     kind: RequestFailureKind;
     status?: number | undefined;
     problem?: unknown;
+    /** A refusal's machine `code` from a closed set, such as `slot_changed`; checked, never shown. */
+    code?: unknown;
 }
 /**
  * What the notices for an OAuth action and a credential Test say. Each of
@@ -121,6 +124,8 @@ export declare function credentialTestNotice(connectorId: string, answer: {
  * checked, not trusted.
  */
 export declare function refusedNotice(action: DownstreamAction, connectorId: string, problem?: unknown): Notice;
+/** An action whose permission or target changed before it was sent. */
+export declare const STALE_COPY = "This changed before sending, so nothing was sent. Try again.";
 /**
  * Every row action's failure, in one voice. The page's own failures — a
  * lapsed session, a denied identity, a dropped connection — read the same for
@@ -133,7 +138,7 @@ export declare function actionFailedNotice(action: RowAction, connectorId: strin
  * server's `connector_unavailable` and keeps its own copy and fix prompt;
  * these two have nothing for a coding agent to fix.
  */
-export type ConnectorLoadFailure = "session" | "network";
+export type ConnectorLoadFailure = "session" | "network" | "unavailable";
 export declare function connectorLoadFailureCopy(failure: ConnectorLoadFailure, productName: string): string;
 /** The signed-in page's answer when `/ui/data` could not be read. */
 export declare function loadFailureCopy(failure: "server" | "network", productName: string): {
@@ -158,20 +163,27 @@ export declare function confirmCopy(action: PendingConfirm["action"], name: stri
  * page fetch again after an identity change.
  */
 type LoadPhase = "idle" | "loading" | "ready" | "error";
-export interface UiAccessToken {
-    id: string;
-    name: string;
-    tokenPrefix: string;
-    createdAt: string;
-    revokedAt?: string;
-}
 export declare function accessTokenUnavailableCopy(capability?: string): string;
 export interface OperatorState {
     tokenPhase: LoadPhase;
     tokenNotice: Notice | null;
-    tokens: UiAccessToken[];
+    /** One slot per declared agent, from `/ui/access-tokens`. */
+    tokens: AgentSlot[];
+    /** A just-issued secret, shown once in its dialog and dropped when that closes. */
     createdToken: string | null;
-    tokenRenaming: string | null;
+    /** The agent `createdToken` belongs to. */
+    createdTokenFor: string | null;
+    /** A rotation or revocation waiting on its in-row confirmation. */
+    tokenConfirm: {
+        name: string;
+        action: "rotate" | "revoke";
+    } | null;
+    /**
+     * Agents whose last token operation ended with an unknown outcome (503,
+     * 499, or a dropped connection). Their actions stay off until a slot list
+     * read that started after the failure succeeds.
+     */
+    unresolvedSlots: string[];
     tokenBusy: boolean;
     page: OperatorPage;
     /**
@@ -180,11 +192,17 @@ export interface OperatorState {
      * the fence that keeps one identity's data off another identity's screen.
      */
     generation: number;
-    /** `loading` until the first /ui/data answer decides gated or ready. */
-    session: "loading" | "gated" | "ready";
+    /**
+     * `loading` until `/ui/api/config` answers (and, for a maintainer,
+     * `/ui/data` too). `denied` is signed in as someone who is neither a
+     * maintainer nor a pool member.
+     */
+    session: "loading" | "gated" | "ready" | "denied";
     gate: Notice | null;
     /** True while a signed-in operator's /ui/data is in flight. */
     refreshing: boolean;
+    /** A bounded admission recovery is pending; Retry can supersede it. */
+    recoveryPending: boolean;
     /**
      * Why the last /ui/data read failed when the session itself was not the
      * reason: the page stays signed in, with its chrome, and offers a retry.
@@ -204,7 +222,14 @@ export interface OperatorState {
      */
     focusIfLost: string | null;
     data: UiData | null;
-    contract: OperatorUiContract | null;
+    /** Operator contract v2, for either role; null until `/ui/api/config` answers. */
+    contract: OperatorUiContractV2 | null;
+    /**
+     * The role the last good contract confirmed. It outlives a failed refresh
+     * that clears `contract`, so the next answer with a different role is
+     * still recognized as a different viewer. Only an identity reset clears it.
+     */
+    role: OperatorRole | null;
     contractPhase: LoadPhase;
     health: "loading" | "ok" | "unavailable";
     connectorFilter: string;
@@ -218,6 +243,11 @@ export interface OperatorState {
      * new tab: its row offers the link instead of the button.
      */
     oauthBlocked: string | null;
+    /**
+     * The authorization link the route returned for `oauthBlocked`. A member has
+     * no `/ui/data` connector to keep it on, so it is held here.
+     */
+    oauthBlockedUrl: string | null;
     /** A row action waiting for its in-page confirmation. */
     confirming: PendingConfirm | null;
     /** Connectors whose details failed on this side of the deployment. */
@@ -235,6 +265,31 @@ export interface OperatorState {
     activityCursor: string | null;
     activitySearch: string;
 }
+/** Who the contract says this viewer is, or null before it loads. */
+export declare function operatorRole(state: Pick<OperatorState, "contract">): OperatorRole | null;
+/**
+ * The role pages and navigation render for. The contract's, or, while a
+ * refresh that failed has left no contract on screen, maintainer when the
+ * last good contract confirmed one and that maintainer's data is still here:
+ * their page stays mounted on its own retry state instead of being torn down
+ * mid-recovery. Never a request's permission; the store sends maintainer
+ * reads only while the contract itself says maintainer.
+ */
+export declare function displayRole(state: Pick<OperatorState, "contract" | "role" | "data">): OperatorRole | null;
+/**
+ * A confirmed maintainer's page is mounted without a contract behind it: a
+ * refresh failed, or its read ran past the deadline. The shell shows one
+ * recovery banner with Retry above whichever page is open, and that page is
+ * stale until a contract confirms the role again.
+ */
+export declare function contractRecovering(state: Pick<OperatorState, "contract" | "role" | "data">): boolean;
+/**
+ * Whether Activity is open to this viewer: maintainers only, on a deployment
+ * that records history. Members always read "forbidden".
+ */
+export declare function activityReadable(state: Pick<OperatorState, "contract" | "data">): boolean;
+/** The contract's half of `activityReadable`: a maintainer, on a deployment that records. */
+export declare function activityAllowed(state: Pick<OperatorState, "contract">): boolean;
 export declare function initialState(page: OperatorPage): OperatorState;
 /**
  * Drop to the gate and forget the previous operator. Bumping the generation is
@@ -254,7 +309,7 @@ export declare function credentialUnavailableCopy(capability?: CredentialManagem
  */
 export declare function connectorStatusLabel(status: string, problem?: UiProblem): string;
 /** The tone a status carries wherever it is rendered as a badge or a tile. */
-export type Tone = "ok" | "warn" | "danger" | "neutral";
+export type Tone = "ok" | "warn" | "danger" | "neutral" | "accent";
 export declare function connectorStatusTone(status: string): Tone;
 export declare function problemCopy(problem: UiProblem | undefined): string | null;
 /**
@@ -263,12 +318,31 @@ export declare function problemCopy(problem: UiProblem | undefined): string | nu
  * error. The two used to share the red box, so the row contradicted itself.
  */
 export declare function problemTone(problem: UiProblem): "warn" | "danger";
+/** What the page knows about a connector beyond its live status: catalog drift and a failed detail read. */
+export interface ConnectorSignals {
+    drift?: boolean;
+    failed?: boolean;
+}
+/** One connector's health everywhere it is shown: badge tone, status word, and the one action beside it. */
+export interface ConnectorVerdict {
+    tone: "ok" | "warn" | "danger" | "neutral";
+    label: string;
+    /** The link to the Connection tab, or null when the connector is fine. */
+    action: "Connect" | "Replace key" | "Inspect" | "Review" | null;
+}
 /**
- * What this identity may do with a connector, in one line. Being able to use it
- * is implied by seeing it at all, so the sentence covers authentication, which
- * is the part that differs between operators.
+ * The verdict the Connectors list, the Overview, Endpoints and a connector's
+ * page all show. The server's problem code comes first, then a failed detail
+ * read on this page, then a non-ok status, then catalog drift. A problem
+ * outranks the status, so a connector whose catalog failed is never
+ * "Connected". A failed read marks its connector `connector_unavailable` in
+ * the store, so that one code beside a failed read is the page's own and
+ * reads "Couldn't load" instead of blaming the downstream.
  */
-export declare function permissionLabel(connector: UiConnector): string;
+export declare function connectorVerdict(live: {
+    status: string;
+    problem?: UiProblem;
+}, signals?: ConnectorSignals): ConnectorVerdict;
 /**
  * Hosted-provider catalog drift, as an operator reads it
  * ([#343](https://github.com/zackbart/connecta/issues/343)).
@@ -314,6 +388,8 @@ export declare function activityOutcomeBadge(outcome: string): {
     label: string;
     tone: Tone;
 };
+/** Why a call stalled or failed, in words; "" when nothing was recorded. */
+export declare function activityReason(event: UiActivityEvent): string;
 /** The one-line detail under an address: where it ran, retries, and why it stalled. */
 export declare function activityDetail(event: UiActivityEvent): string;
 /**
@@ -321,12 +397,6 @@ export declare function activityDetail(event: UiActivityEvent): string;
  * beside it is not shown: it can carry a vault's own words.
  */
 export declare function credentialProblemCopy(problem: string | undefined): string;
-export declare function credentialStateLabel(credential: {
-    configured: boolean;
-    fields?: unknown[];
-    lastFour?: string;
-    updatedAt?: string;
-}): string;
 /** Gate copy for each browser-auth shape, so the sign-in state is never a blank page. */
 export declare function gateCopy(kind: string, signedIn: boolean): string;
 export {};