@zackbart/connecta 0.29.0 → 0.30.0

package/documentation/operating.md

@@ -0,0 +1,135 @@
+# Operating an endpoint
+
+Use this guide as an agent connected to an existing Connecta endpoint. Setup
+and credentials are the deployment operator's responsibility; use
+[Deploying Connecta](./deploying.md) if you are that operator.
+[All agent routes](./README.md) are in the index.
+
+## Choose the call path
+
+Connecta exposes six top-level tools. Read [the tool table](./meta-tools.md#the-six-tools)
+for exact arguments and result envelopes. Follow the endpoint's supplied
+instructions and `skills` usage guide for deployment-specific context.
+
+| Work                                                               | Use                                                       |
+| ------------------------------------------------------------------ | --------------------------------------------------------- |
+| One known read, with usable arguments and a small result           | `call_tool`                                               |
+| Discover a tool, chain calls, combine services, or reduce a result | `execute_code`                                            |
+| One write on a read-only endpoint                                  | `call_destructive_tool`                                   |
+| Obtain connector instructions                                      | `skills` with the returned guide name                     |
+| Start a required authentication handoff                            | `authorize_connector`, using the returned recovery action |
+
+The endpoint's trust is part of its tool descriptions. On a `trusted` endpoint,
+programs may write within the caller's grants, and `execute_code` is annotated
+as a write. On `read-only`, every write is a separate top-level call. The host
+controls approval. Never change pool, identity, or trust to work around a refusal.
+[Routing between the call surfaces](./meta-tools.md#routing-between-the-call-surfaces)
+owns the full decision rules.
+
+## Discover before guessing
+
+Use two to four distinctive action/object terms for each operation, and name
+the connector when it is obvious. Read `catalogErrors`, `absence`, classification,
+and required inputs before selecting a result. An empty search may mean a
+failed catalog or a service outside the caller's grants.
+
+For normal reads, keep discovery, calls, and reduction in one program when the
+schemas suffice; return the answer rather than catalog matches. Use top-level
+`search_tools` for catalog inspection or to discover a write on a read-only
+endpoint, then dispatch each write with `call_destructive_tool`. An unfamiliar
+read result may return a bounded sample for inspection before the next program.
+
+Use the exact returned `address`, including punctuation. A TypeScript signature
+is guidance for writing JavaScript; do not paste types into executable code.
+If a schema is truncated or exact constraints matter, describe the address with
+`format: "json"`. Read a returned `guide` through `skills` or
+`connecta.skill` before relying on provider-specific conventions.
+[Discovery context](./meta-tools.md#discovery-context) and
+[guest search](./code-mode.md#connectasearch) define these results.
+
+## Call, combine, and reduce
+
+A program is one JavaScript `async` arrow expression. It has the `connecta`
+guest API and captured console output, with no portable imports, filesystem,
+network access, or credentials. Downstream calls return an envelope; read its
+`data` rather than treating the envelope as the provider's result.
+
+This illustrative tracker has a `list_issues` read accepting `state` and
+returning `data.nodes`. Discover its address, call it, and group the identifiers
+in one program:
+
+```js
+async () => {
+  const page = await connecta.search({
+    connector: "tracker",
+    query: "list issues",
+    safety: "readOnly",
+  });
+  if (page.catalogErrors.length || page.absence) {
+    return { gap: page.catalogErrors, absence: page.absence };
+  }
+  const tool = page.tools.find(t => t.name === "list_issues");
+  if (!tool) return { gap: "list_issues unavailable" };
+  const { data, format } = await connecta.call(tool.address, {
+    state: "started",
+  });
+  if (format !== "json" || !Array.isArray(data?.nodes)) {
+    return { gap: "Expected a JSON issues collection" };
+  }
+  const byOwner = Object.create(null);
+  for (const issue of data.nodes) {
+    const owner = issue.assignee?.name ?? "unassigned";
+    (byOwner[owner] ??= []).push(issue.identifier);
+  }
+  return byOwner;
+}
+```
+
+`tracker.list_issues` is illustrative, not a built-in address. Discover the real
+connector's schemas and pagination before adapting this program. Keep loops and
+parallel work bounded. [Parallel calls](./code-mode.md#parallel-calls),
+[results and projection](./code-mode.md#results-and-projection), and
+[cancellation and limits](./code-mode.md#cancellation-and-limits) own those rules.
+
+Discovery may label an output schema `observed`. It records field names and
+broad types from successful reads in bounded runtime memory, with no scalar
+values. Treat it as evidence, not a provider contract; handle missing fields.
+
+## Large results and resources
+
+Direct calls may return a preview and a result handle. Page the handle through
+`connecta.result` in a program using the returned offset and byte limits, or
+reduce the data in the original program. Handles are short-lived and bound to
+the admitted caller, endpoint/pool, and current grants. Never invent one or pass
+it between identities. [Paging](./meta-tools.md#paging-with-connectaresult)
+owns the envelope and expiry rules.
+
+For resources, use the exposed resource inventory and `connecta.read`; do not
+fetch an arbitrary URL. [Resource reads](./code-mode.md#connectaread) describe
+which URIs may be read. Connector guides and native skills are described in
+[skills](./meta-tools.md#connector-guides-and-skills).
+
+## Recover without replaying a write
+
+Read typed failures and their `nextAction`. Authorization recovery can point
+to consent, operator credential setup, or deployment configuration. Discovery
+and status do not begin consent on their own. Follow
+[authorization recovery](./meta-tools.md#authorization-recovery),
+[routing recovery](./meta-tools.md#routing-recovery), and
+[argument recovery](./meta-tools.md#argument-recovery) for the specific failure.
+
+A dispatched write is never automatically replayed. An ambiguous timeout may
+mean the provider applied it; inspect state or ask for the missing decision
+before issuing it again. [Retry semantics](./code-mode.md#retry-semantics) and
+[writes](./code-mode.md#writes) describe program outcomes and write accounting.
+
+## Implementation and evidence
+
+The endpoint's built-in [usage skill](https://github.com/zackbart/connecta/blob/main/src/skills.ts)
+is maintained alongside [meta-tools](https://github.com/zackbart/connecta/blob/main/src/meta-tools.ts)
+and [execution](https://github.com/zackbart/connecta/blob/main/src/execute.ts).
+[Usage-guide tests](https://github.com/zackbart/connecta/blob/main/test/usage-guide.test.ts),
+[direct-call tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-call.test.ts),
+and [guest-contract tests](https://github.com/zackbart/connecta/blob/main/test/guest-api-contract.test.ts)
+check the contracts. Executor-specific evidence is indexed in
+[code-mode verification](./code-mode.md#verification).

package/documentation/operator-tests.md

@@ -1,5 +1,9 @@
 # Operator UI tests
 
+Use this repository-maintenance guide when changing operator pages, data routes,
+or browser evidence. Read the [operator UI contract](./operator-ui.md) first.
+[The agent index](./README.md) routes deployment and endpoint tasks.
+
 `test/fixtures/operator-visual.ts` owns the visual data. It builds the config,
 live overlay, viewer, and legacy auth details through the current server routes,
 using the types in `src/operator-ui/contract.ts` and `model.ts`. Collections use

package/documentation/operator-ui.md

@@ -0,0 +1,132 @@
+# Operator UI
+
+Use this guide to enable or maintain the optional operator interface. For
+client tool calls use [Operating an endpoint](./operating.md); for identities,
+credential ownership, and grants use [Auth](./auth.md).
+[All agent routes](./README.md) are in the index.
+
+## Task routes
+
+| Task                                            | Read                                                                                                             |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Enable UI, vault, or history in a deployment    | [Setup](#setup), then the platform template                                                                      |
+| Consume config, provenance, status, or activity | [Operator data contract](#operator-data-contract)                                                                |
+| Change a UI page or data route                  | [Source and tests](#source-and-tests), [browser verification](./operator-tests.md)                               |
+| Diagnose permission refusals                    | [Management permissions](./auth.md#management-permissions), [activity disclosure below](#operator-data-contract) |
+
+## Setup
+
+Set `ui: operatorUi()` using `@zackbart/connecta/ui`. Branding belongs in
+`operatorUi({ branding })`; the [Node template](../templates/node/README.md#select-optional-modules)
+and [Worker example](../examples/worker/README.md#select-optional-modules)
+own the runnable configuration, variables, and branding shape. The UI is an
+explicit optional import and stays outside the root package import graph.
+
+Overview, Connectors, Tools, Access, Activity, and Config show only what the
+caller may inspect. Connector detail tabs cover configuration, schemas,
+authentication, activity, and diagnostics. Config labels values as default or
+configured. Deployment code owns connectors, grants, pools, and classification;
+the UI changes only authorized authentication material.
+
+Install the vault for declared credential slots and activity history for
+persisted call records. Neither module grants permission to manage or read
+it. Credential administration, personal connection, access-token management,
+and activity access are separate identity decisions, denied by default where
+specified in [auth](./auth.md#management-permissions). Machine tokens never
+grant interactive credential or token management authority.
+
+## Operator data contract
+
+`GET /ui/api/config`, owned by `operatorUi()`, returns `OperatorUiContract`
+from `connecta/ui`. `src/operator-ui/contract.ts` is also the browser's type
+source. The response has `schemaVersion: 1`, `config`, `configSources`, `live`, and `you`.
+`config` is the construction-time `describeConfig()` snapshot, filtered to
+visible connectors, granted tools, classification overrides, and admitted
+pools. Pool tools are the intersection with the caller's identity grants.
+`configSources` labels each serialized leaf as `default` or `config`, based on
+option presence rather than equality with the default. Factory descriptions carry
+relative `optionSources` paths so resolved module and transport defaults retain
+their provenance. The snapshot copies only resolved values; the UI consumes
+these presence facts separately. Its paths use connector
+ids and pool names and are filtered after disclosure; hidden values leave no
+provenance keys. It contains no source code or credential material.
+Every response is private, `no-store` JSON. Only GET is allowed, with the
+same auth gate and identity partition as `/ui/data` and `/ui/connectors/:id`.
+
+`live.connectors` carries status and problem codes, complete registry tools
+with their final read/write classification, catalog age in milliseconds, and
+last-call time/outcome. Catalog descriptions and schemas are allowed for an
+authenticated reader; grammar-failing names and addresses become `<withheld>`.
+`auth.registrationPath` reports the selected downstream OAuth client mechanism when known.
+Status prose, error text, credential values or suffixes, arguments, results,
+and code are excluded. Static and unobserved catalogs have a null age;
+persisted catalogs retain their original fetch time. Probes run with bounded
+concurrency and the configured probe deadline, and release their scopes.
+
+Last-call lookup requires the existing activity permission and read gate. It
+scans up to 1,000 recent rows, filters connector/tool grants, and restricts
+personal connectors to the caller's activity identity. Each retained fact
+copies a validated timestamp and outcome only. A null call means unknown or
+absent in that window, not proof of no calls. `live.activity` distinguishes
+available, unconfigured, forbidden, and unavailable history. `you` names no
+identity or auth material; it reports grants, root and admitted-pool trust,
+and effective activity, token, and per-connector auth permissions.
+
+`connecta doctor --config` fetches this authenticated contract and prints only
+`config` as indented JSON. It requires the UI module and the existing doctor
+authentication environment variables; it runs no diagnostic program, follows
+no redirects, and prints no raw HTTP failure body.
+
+The operator shell uses React, TanStack Router/Query/Table, Radix, cmdk and
+Tailwind v4. Inter, CSS, JavaScript and dependency notices are hashed assets
+under `/ui/assets/*`, served identically with immutable cache headers on Node
+and Workers. HTML contains only mount points and escaped inert configuration;
+it remains uncached. `generated.ts` is ignored and generated before build and
+test; `check:operator-ui` detects stale assets and shared page styles. The UI
+stays behind `./ui`, outside the root import graph. The identity-fenced store
+owns authenticated reads and existing mutations. Overview, Connectors, connector
+detail, Tools, Access and Config consume the typed contract. Activity retains
+its authenticated data routes. Connector detail tabs live
+in the URL hash; Activity filters live in the query string and apply to loaded
+history. Both `/ui/activity` and `/ui/api/activity` require Activity access and
+pass the optional activity `readGate`. Interactive operators and machine callers
+admitted by `identity.activityAccess` share the same history disclosure rules.
+Connector/tool grants and grants for the recorded pool filter each event. Shared
+connector history can include other principals' events, with recorded request
+IDs, validated client name/version and package version, and actor kind, ID and
+namespace. Interactive reads may also add directory actor labels; machine reads
+never add them. Personal connector history is owner-only: the event must have a
+checked `principal` actor basis and actor ID/namespace matching the reader's
+admitted principal. Rows without a provable personal owner are withheld. Activity
+carries no arguments, results, code or raw downstream errors. The last-call
+overlay uses the same event filter but returns only timestamp and outcome.
+Calls group only by recorded request ids, with missing ids shown as
+separate calls. Classification and result size are shown only when recorded. The verdict is
+captured after registry resolution, and result size counts UTF-8 bytes of the
+downstream value before paging or truncation. Nullable SQL columns preserve old
+rows. Catalog changes use the same paging envelope with `kind: "catalog_drift"`,
+`source: "catalog_refresh"` and a checked `catalog_changed` fact containing only
+added, removed and changed tool counts. The first complete catalog is a baseline;
+one refresh-publication hook emits each later change. It includes the request's
+id and typed actor when available, otherwise a fresh id and system actor. No
+names, descriptions or schemas enter the event. Private catalog changes require
+a matching principal owner even when the connector uses shared auth. Empty credential declarations
+report `credential_required` before running a connector status or catalog probe.
+The Access adapter reports inbound provider kinds, admitted pools, grants, trust
+and endpoint setup; token controls retain their existing permission gate.
+Configuration remains in deployment code. The UI mutates only credentials,
+OAuth connections and client tokens through the existing routes.
+
+## Source and tests
+
+The contract type is [contract.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/contract.ts).
+[UI routes](https://github.com/zackbart/connecta/blob/main/src/routes/ui.ts) and
+[UI implementation](https://github.com/zackbart/connecta/blob/main/src/ui.ts)
+serve the authenticated shell and data. The browser lives in
+[src/operator-ui](https://github.com/zackbart/connecta/tree/main/src/operator-ui).
+[UI tests](https://github.com/zackbart/connecta/blob/main/test/ui.test.ts),
+[credential-route tests](https://github.com/zackbart/connecta/blob/main/test/ui-credentials.test.ts),
+[config snapshot tests](https://github.com/zackbart/connecta/blob/main/test/describe-config.test.ts),
+and [browser flows](https://github.com/zackbart/connecta/blob/main/test/browser/operator-ui.spec.ts)
+defend filtering and behavior. Use [Operator UI tests](./operator-tests.md)
+for the browser state matrix and Linux snapshot procedure.

package/documentation/provider-migration-0.29.md

@@ -1,5 +1,10 @@
 # Notion, Vercel and Cloudflare migration for 0.29
 
+Use this upgrade guide for an existing deployment.
+[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
+version changes; [integrating services](./integrating.md) covers new connectors.
+[The agent index](./README.md) routes package maintenance separately.
+
 This is the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709).
 Deploy it with the consolidated 0.29 release, not while the rework is in progress.
 BePresent and One&Many use Notion and Cloudflare; their actual grants and

package/examples/worker/README.md

@@ -1,5 +1,12 @@
 # connecta — Cloudflare Worker example
 
+Agent setup guide for the Worker deployment.
+For deployment choices and upgrades, use [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md).
+For connector changes, use [Integrating services](https://github.com/zackbart/connecta/blob/main/documentation/integrating.md).
+The [agent index](https://github.com/zackbart/connecta/blob/main/documentation/README.md) routes endpoint use and package
+maintenance. This README and [local agent instructions](./AGENTS.md) own the
+runnable Worker steps.
+
 A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
 API connector, guarded by Cloudflare Access. It uses three Cloudflare resources
 and nothing else: one D1 database (`CONNECTA_DB`) for every piece of state, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",
@@ -109,6 +109,10 @@
       "types": "./dist/providers/gmail/index.d.ts",
       "import": "./dist/providers/gmail/index.js"
     },
+    "./providers/infisical": {
+      "types": "./dist/providers/infisical/index.d.ts",
+      "import": "./dist/providers/infisical/index.js"
+    },
     "./providers/linear": {
       "types": "./dist/providers/linear/index.d.ts",
       "import": "./dist/providers/linear/index.js"
@@ -221,6 +225,7 @@
     "precheck:bundle": "npm run build:operator-ui",
     "precheck:fast": "npm run check:operator-ui",
     "eval:regrade": "tsx eval/regrade.ts",
+    "eval:compare": "tsx eval/compare.ts",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check ."
   },
@@ -267,6 +272,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "cmdk": "^1.1.1",
+    "commonmark": "^0.31.2",
     "esbuild": "^0.28.0",
     "knip": "^6.29.0",
     "oxfmt": "0.72.0",

package/templates/node/README.md

@@ -1,5 +1,12 @@
 # Connecta deployment
 
+Agent setup guide for the Node deployment and its Docker packaging.
+For cross-platform setup and upgrades, use [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md).
+For connector changes, use [Integrating services](https://github.com/zackbart/connecta/blob/main/documentation/integrating.md).
+The [agent index](https://github.com/zackbart/connecta/blob/main/documentation/README.md) routes endpoint use and package
+maintenance. This README and [local agent instructions](./AGENTS.md) own the
+runnable steps for a copied Node deployment.
+
 This is the prescribed Node deployment. It runs locally from source and as
 a container. Install, provision a machine token, then start it:
 

package/templates/node/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.29.0",
+    "@zackbart/connecta": "0.30.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {