@zackbart/connecta 0.28.1 → 0.29.0

package/dist/operator-ui/model.d.ts

@@ -1,25 +1,8 @@
-import type { CatalogAccessObservation, CatalogDriftReport } from "../types.js";
-/**
- * Which call path a tool takes, decided on the server by the same
- * `isExplicitlyReadOnly` predicate discovery and invocation use
- * (`src/tool-safety.ts`) and never re-derived in the browser: a second copy of
- * the rule is a second place for it to be wrong.
- *
- * - `runs_in_programs` — explicitly read-only, so `execute_code` may call it.
- * - `exempt` — not read-only, but the deployment's `execute.approval` lets a
- *   program call it without asking (#566). Still approval-required
- *   everywhere else.
- * - `needs_approval` — everything else: a program refuses it, and it crosses
- *   `call_destructive_tool`, where the host asks.
- *
- * The badge renders from a table keyed by this union, so each value is one
- * entry, not a branch.
- */
-export type UiToolSafety = "runs_in_programs" | "exempt" | "needs_approval";
-export interface UiTool {
-    name: string;
-    address: string;
-    description?: string;
+import type { OperatorConnectorOverlay, OperatorTool, OperatorUiContract, OperatorViewer } from "./contract.js";
+import type { CatalogAccessObservation, CatalogDriftReport, ResourceTemplateRefusalCode } from "../types.js";
+/** Tool verdicts, independent of the selected pool's trust. */
+export type UiToolSafety = "runs_in_programs" | "needs_approval";
+export interface UiTool extends Pick<OperatorTool, "name" | "address" | "description"> {
     /** Absent only in payloads older than the field; the page then shows no badge. */
     safety?: UiToolSafety;
 }
@@ -76,12 +59,8 @@ export interface UiConnector {
     authScope?: "shared" | "personal";
     title?: string;
     description?: string;
-    status: "loading" | "ok" | "auth_required" | "error";
-    permissions?: {
-        use: boolean;
-        manageSharedAuth: boolean;
-        connectPersonal: boolean;
-    };
+    status: "loading" | OperatorConnectorOverlay["status"];
+    permissions?: Omit<OperatorViewer["permissions"]["connectors"][number], "id">;
     /**
      * 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
@@ -93,6 +72,8 @@ export interface UiConnector {
     tools: UiTool[];
     /** This connector exposes manageable downstream OAuth lifecycle hooks. */
     oauth?: boolean;
+    /** Selected downstream client identity mechanism; never a client ID or secret. */
+    registrationPath?: "cimd" | "dcr" | "static";
     credential?: UiCredential;
     /**
      * Drift the last catalog refresh saw *in this runtime*
@@ -105,16 +86,14 @@ export interface UiConnector {
     catalogDrift?: CatalogDriftReport;
     /** Last agent-facing catalog read in this runtime; never persisted. */
     catalogAccess?: CatalogAccessObservation;
+    resourceTemplateRefusals?: ResourceTemplateRefusalCode[];
 }
 export type CredentialManagementCapability = "available" | "requires_operator" | "vault_not_configured" | "no_slots";
 export interface UiData {
     accessTokenManagement?: "available" | "requires_operator";
-    serverInfo: {
-        name: string;
-        version: string;
-    };
+    serverInfo: Pick<OperatorUiContract["config"]["server"], "name" | "version">;
     /** Version of the installed @zackbart/connecta package. */
-    connectaVersion: string;
+    connectaVersion: OperatorUiContract["config"]["connectaVersion"];
     connectors: UiConnector[];
     activityEnabled: boolean;
     credentialManagement: CredentialManagementCapability;
@@ -126,60 +105,6 @@ export interface UiData {
      * it with a 404, so the page never enumerates a pool its reader cannot open.
      */
     pools?: string[];
-    /** True when artifact pages are mounted and this identity may open them. */
-    artifactsEnabled?: boolean;
-}
-/**
- * One row of the artifact library. Every field is a fact the store keeps or
- * an enum; nothing here is a message, a log line, or a downstream's words.
- */
-export interface UiArtifactRow {
-    id: string;
-    title: string;
-    kind: "html" | "markdown";
-    viewVersion: number;
-    updatedAt: string;
-    updatedBy: {
-        label: string;
-    };
-    archived: boolean;
-    freshness?: UiArtifactFreshness;
-}
-interface UiArtifactFreshness {
-    state: "unconfigured" | "current" | "stale";
-    schedule?: "manual" | "daily" | "weekly";
-    document?: string;
-    dueAt?: string;
-    last?: {
-        at: string;
-        status: "succeeded" | "unchanged" | "failed" | "superseded";
-    };
-    running?: boolean;
-}
-/** The viewer's payload: the page's facts and the one document its frame loads. */
-export interface UiArtifactView {
-    id: string;
-    title: string;
-    kind: "html" | "markdown";
-    archived: boolean;
-    snapshot: boolean;
-    latestViewVersion: number;
-    view: {
-        version: number;
-        at: string;
-        by: {
-            label: string;
-        };
-    };
-    documents: {
-        name: string;
-        version: number;
-        updatedAt: string;
-    }[];
-    url: string;
-    snapshotUrl: string;
-    document: string;
-    freshness?: UiArtifactFreshness;
 }
 export interface FilteredUiConnector {
     connector: UiConnector;

package/dist/operator-ui/model.js

@@ -7,18 +7,11 @@ export function filterUiConnectors(connectors, query) {
     const q = query.trim().toLowerCase();
     const filtered = [];
     for (const connector of connectors) {
-        const connectorText = [
-            connector.id,
-            connector.title,
-            connector.description,
-            connector.status,
-        ]
+        const connectorText = [connector.id, connector.title, connector.description, connector.status]
             .join(" ")
             .toLowerCase();
         const connectorMatches = Boolean(q && connectorText.includes(q));
-        const tools = connector.tools.filter((tool) => !q ||
-            connectorMatches ||
-            `${tool.name} ${tool.description ?? ""}`.toLowerCase().includes(q));
+        const tools = connector.tools.filter((tool) => !q || connectorMatches || `${tool.name} ${tool.description ?? ""}`.toLowerCase().includes(q));
         if (q && tools.length === 0 && !connectorMatches)
             continue;
         filtered.push({ connector, tools });

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

@@ -28,9 +28,7 @@ export function poolEndpointUrl(mcpUrl, pool) {
 }
 /** POSIX single-quoting, only when the value needs it. */
 function shellWord(value) {
-    return /^[A-Za-z0-9_./:@%+=,~-]+$/.test(value)
-        ? value
-        : `'${value.replace(/'/g, `'"'"'`)}'`;
+    return /^[A-Za-z0-9_./:@%+=,~-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`;
 }
 export function clientSetupCommands(name, url) {
     return [

package/dist/operator-ui/view.d.ts

@@ -0,0 +1,323 @@
+import type { OperatorUiContract } 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";
+export declare function registrationPathLabel(path: NonNullable<UiConnector["registrationPath"]>): string;
+export type OperatorPage = "overview" | "tools" | "access" | "config" | "connector" | "tokens" | "connections" | "activity";
+/** Pages the nav lists. */
+export declare const OPERATOR_PAGES: readonly OperatorPage[];
+export declare const PAGE_META: Readonly<Record<OperatorPage, {
+    path: string;
+    label: 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;
+/** What the gate says while the session is checked, page by page. */
+export declare function checkingCopy(): string;
+export declare function pageForPath(path: string): OperatorPage;
+export interface UiActivityActor {
+    kind?: string;
+    id?: string;
+    namespace?: string;
+    label?: string;
+}
+export interface UiActivityEvent {
+    kind?: "catalog_drift";
+    drift?: import("../activity.js").ActivityCatalogChange;
+    id?: string;
+    requestId?: string;
+    classification?: "read" | "write";
+    resultBytes?: number;
+    occurredAt: string;
+    actor?: UiActivityActor;
+    connectorId: string;
+    toolName: string;
+    address: string;
+    source: string;
+    outcome: string;
+    durationMs: number;
+    attempts: number;
+    errorCode?: string;
+    friction?: string;
+    approval?: string;
+    packageVersion?: string;
+    clientName?: string;
+    clientVersion?: string;
+}
+/**
+ * Which fix prompt a failure offers. A kind and a configured connector id —
+ * the message beside it never travels with it.
+ */
+export interface NoticeFix {
+    kind: FixPromptKind;
+    connectorId: string;
+}
+/** A message with the tone that decides its live region: status or alert. */
+export interface Notice {
+    message: string;
+    tone: "info" | "error";
+    fix?: NoticeFix;
+}
+export declare function info(message: string): Notice;
+export declare function failure(message: string, fix?: NoticeFix): Notice;
+/**
+ * Why a request the page made did not land, as the store classifies it. Only
+ * this kind, a status code, and a closed `problem` enum ever reach a notice;
+ * the route's `error` text never does.
+ *
+ * - `session` — no usable session, or the route answered 401.
+ * - `forbidden` — the route answered 403: this identity may not do that. On a
+ *   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.
+ */
+export type RequestFailureKind = "session" | "forbidden" | "network" | "refused";
+export interface RequestFailureFacts {
+    kind: RequestFailureKind;
+    status?: number | undefined;
+    problem?: unknown;
+}
+/**
+ * What the notices for an OAuth action and a credential Test say. Each of
+ * those actions reaches a downstream, and a downstream's refusal can quote the
+ * secret it was sent — so these notices are fixed sentences chosen by outcome,
+ * and no text the server sent back is ever one of them. The route logs the
+ * downstream's words on the host; the fix prompt beside a failure is keyed off
+ * the same outcome.
+ */
+export type DownstreamAction = "oauth_disconnect" | "oauth_reconnect" | "credential_test";
+/** Every action a connector row can start, downstream or not. */
+export type RowAction = DownstreamAction | "credential_save" | "credential_remove";
+/**
+ * The route's answer to a finished OAuth action. Its state picks the sentence;
+ * `opened` says whether the authorization page is already in a new tab.
+ */
+export declare function oauthDoneNotice(action: "oauth_disconnect" | "oauth_reconnect", answer: {
+    state?: unknown;
+    code?: unknown;
+} | null, opened?: boolean): Notice;
+/** A credential Test's result. `ok` is the only part of the answer it reads. */
+export declare function credentialTestNotice(connectorId: string, answer: {
+    ok?: unknown;
+} | null): Notice;
+/**
+ * A route that refused one of these actions. A credential Test that found
+ * nothing usable to test names the problem, which picks the same copy and fix
+ * prompt the Connections page uses for it; every other refusal gets the
+ * action's one sentence. `problem` is whatever the response carried, so it is
+ * checked, not trusted.
+ */
+export declare function refusedNotice(action: DownstreamAction, connectorId: string, problem?: unknown): Notice;
+/**
+ * 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
+ * every action; a route's refusal picks the action's fixed sentence.
+ */
+export declare function actionFailedNotice(action: RowAction, connectorId: string, facts: RequestFailureFacts, productName: string): Notice;
+/**
+ * Why one connector's details did not load, when the reason is on this side
+ * of the deployment rather than the downstream's. A downstream failure is the
+ * 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 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): {
+    title: string;
+    body: string;
+};
+/** A collection page's load failure: fixed words, whatever the route said. */
+export declare function collectionFailureCopy(_collection: "activity", facts: RequestFailureFacts, productName: string): string;
+/** A destructive or disruptive row action waiting for a second, in-page click. */
+export interface PendingConfirm {
+    connectorId: string;
+    action: "oauth_disconnect" | "oauth_restart" | "credential_remove";
+}
+/** The confirm's question, naming the connector by its title. */
+export declare function confirmCopy(action: PendingConfirm["action"], name: string): {
+    question: string;
+    confirm: string;
+};
+/**
+ * A remote collection's four states, named once so every page spells them the
+ * same way. `idle` is "nobody has asked yet" and is what makes a re-entered
+ * 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[];
+    createdToken: string | null;
+    tokenRenaming: string | null;
+    tokenBusy: boolean;
+    page: OperatorPage;
+    /**
+     * Bumped by every identity change. Async work captures it before awaiting and
+     * throws its result away if the operator is no longer the one who asked —
+     * 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";
+    gate: Notice | null;
+    /** True while a signed-in operator's /ui/data is in flight. */
+    refreshing: 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.
+     * Only a 401 or 403 on that read returns to the gate.
+     */
+    loadFailure: "server" | "network" | null;
+    /**
+     * Element id the next render should focus. A rebuilt page has no stable node
+     * to hand focus to from an event handler, so the request travels through
+     * state and the shell spends it once the new markup exists.
+     */
+    pendingFocus: string | null;
+    /**
+     * Like `pendingFocus`, but spent only when focus has nowhere to be — the
+     * control that had it is gone. An action that lands next to its own control
+     * announces through its live region and leaves focus where the operator is.
+     */
+    focusIfLost: string | null;
+    data: UiData | null;
+    contract: OperatorUiContract | null;
+    contractPhase: LoadPhase;
+    health: "loading" | "ok" | "unavailable";
+    connectorFilter: string;
+    oauthNotice: Notice | null;
+    /** The connector row `oauthNotice` answers, which is where it renders. */
+    oauthNoticeFor: string | null;
+    /** Connector id whose OAuth mutation is in flight. */
+    oauthBusy: string | null;
+    /**
+     * Connector id whose authorization started while the browser refused the
+     * new tab: its row offers the link instead of the button.
+     */
+    oauthBlocked: string | null;
+    /** A row action waiting for its in-page confirmation. */
+    confirming: PendingConfirm | null;
+    /** Connectors whose details failed on this side of the deployment. */
+    connectorFailures: Readonly<Record<string, ConnectorLoadFailure>>;
+    credentialNotice: Notice | null;
+    /** The connector row `credentialNotice` answers. */
+    credentialNoticeFor: string | null;
+    /** Connector id whose credential form is open. */
+    credentialEditing: string | null;
+    /** Connector id whose credential mutation is in flight. */
+    credentialBusy: string | null;
+    activityPhase: LoadPhase;
+    activityNotice: Notice | null;
+    activityEvents: UiActivityEvent[];
+    activityCursor: string | null;
+    activitySearch: string;
+}
+export declare function initialState(page: OperatorPage): OperatorState;
+/**
+ * Drop to the gate and forget the previous operator. Bumping the generation is
+ * what makes the drop stick: work already in flight for the old identity
+ * resolves into a state that no longer accepts it.
+ */
+export declare function resetIdentity(state: OperatorState, gate?: Notice | null): OperatorState;
+/**
+ * Leaving a page closes what should not survive it: a one-time secret, a half
+ * typed credential, and the notices that answered the page just left.
+ */
+export declare function withPage(state: OperatorState, page: OperatorPage): OperatorState;
+export declare function credentialUnavailableCopy(capability?: CredentialManagementCapability): string;
+/**
+ * The status badge. An auth-needed connector is named by what it needs, so a
+ * row whose fix is "Add credential" does not say "Authorization needed".
+ */
+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 declare function connectorStatusTone(status: string): Tone;
+export declare function problemCopy(problem: UiProblem | undefined): string | null;
+/**
+ * A problem someone can fix by authorizing is a warning, matching the amber
+ * "Authorization needed" badge above it; one where something broke is an
+ * error. The two used to share the red box, so the row contradicted itself.
+ */
+export declare function problemTone(problem: UiProblem): "warn" | "danger";
+/**
+ * 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.
+ */
+export declare function permissionLabel(connector: UiConnector): string;
+/**
+ * Hosted-provider catalog drift, as an operator reads it
+ * ([#343](https://github.com/zackbart/connecta/issues/343)).
+ *
+ * - `unavailable` — no refresh has been observed in this runtime, so there is
+ *   nothing to report. Deliberately not `clean`: "we have not looked" and "we
+ *   looked and it matches" are different answers, and only one of them is a
+ *   reason to stop worrying.
+ * - `clean` — a refresh happened and every category counted zero.
+ * - `warning` — a refresh happened and at least one category did not.
+ */
+export type DriftState = "clean" | "warning" | "unavailable";
+export declare function driftState(drift?: CatalogDriftReport): DriftState;
+/** Every category with its count, so a clean report still shows its zeros. */
+export declare function driftCounts(drift?: CatalogDriftReport): Array<{
+    key: string;
+    label: string;
+    count: number;
+}>;
+/** One line naming the state and when it was observed. Never what drifted. */
+export declare function driftSummary(drift?: CatalogDriftReport): string;
+/**
+ * Only http/https may become a clickable href — the browser half of the gate
+ * `src/ui.ts` applies before an authorizationUrl is ever serialized. A hostile
+ * downstream that gets a `javascript:` URL past one of them still meets the
+ * other, and the caller renders inert text instead of a link.
+ */
+export declare function safeHttpHref(url: string | undefined): string | null;
+/** Locale timestamp, or "" for anything that is not a readable date. */
+export declare function formatDate(value?: string): string;
+/** Who made a call: their name when there is one, and how they signed in. */
+export declare function actorLabel(actor?: UiActivityActor): string;
+/**
+ * The stable id behind a friendly label, shown only when a label or namespace
+ * could otherwise make two different people look like one.
+ */
+export declare function actorStableId(actor?: UiActivityActor): string | null;
+export declare function filterActivity(events: UiActivityEvent[], query: string): UiActivityEvent[];
+/** Counts only. What the deployment ran, never what it sent or received. */
+export declare function activitySummary(events: UiActivityEvent[]): string;
+export declare function activityOutcomeClass(outcome: string): string;
+export declare function activityOutcomeBadge(outcome: string): {
+    label: string;
+    tone: Tone;
+};
+/** The one-line detail under an address: where it ran, retries, and why it stalled. */
+export declare function activityDetail(event: UiActivityEvent): string;
+/**
+ * A stored credential that cannot be used, by cause. The payload's `error`
+ * 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 {};