@zackbart/connecta 0.28.1 → 0.29.0

package/documentation/operator-tests.md

@@ -0,0 +1,93 @@
+# Operator UI tests
+
+`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
+their corresponding browser types. `test/operator-visual-fixtures.test.ts`
+validates contract versions, connector IDs, granted tools, classification,
+permissions, provenance, and secret exclusion on Node and Workers. A fixture's
+config cannot silently become a stale copy of the server serializer.
+
+`test/browser/operator-visual.spec.ts` intercepts API reads and serves the real
+hashed assets and HTML with the production CSP. Loading responses wait on an
+explicit gate. Error responses use fixed HTTP failures. Screenshots use a fixed
+clock, UTC, en-US, locally hosted fonts, disabled animations, hidden carets,
+and a 1280 × 900 viewport. Narrow fixtures use 390 × 844. Every test waits for
+its state and fonts before capturing.
+
+## Page and state matrix
+
+Each row runs empty, loading, error, populated, and restricted-viewer fixtures
+in both light and dark themes, for 120 screenshots.
+
+| Page or tab           | Empty state                          | Loading/error request | Restricted viewer                                   |
+| --------------------- | ------------------------------------ | --------------------- | --------------------------------------------------- |
+| Overview              | No connectors or attention items     | Config                | Scoped connectors, no privileged navigation         |
+| Connectors            | No connectors                        | Config                | Read grant and credential slot, no other connectors |
+| Connector Config      | Zero-tool connector                  | Config                | Scoped connector snapshot                           |
+| Connector Tools       | Empty catalog                        | Config                | Read tool only                                      |
+| Connector Auth        | Deployment-managed auth              | Config                | Visible slot, deployment-managed auth               |
+| Connector Activity    | No calls                             | Activity              | Unavailable                                         |
+| Connector Diagnostics | No observed drift/call               | Config                | Scoped diagnostics                                  |
+| Tools                 | Empty catalog                        | Config                | Read tool only                                      |
+| Access                | No pools or client tokens            | Config                | No token management                                 |
+| Access tokens         | No client tokens                     | Token list            | No token management                                 |
+| Activity              | No calls                             | Activity              | Unavailable                                         |
+| Config                | Snapshot without connectors or pools | Config                | Scoped snapshot                                     |
+
+Another 36 screenshots cover configured, mismatched, unreadable and multifield
+credentials; all three OAuth client mechanisms; clean and unobserved drift;
+historical Activity; client setup; schema dialog; read/write filters; expanded
+config provenance; narrow sign-in and Auth; and deployment branding. The base
+populated Activity fixture includes grouped calls, an ungrouped legacy row,
+classification/result size/client facts, and a catalog-change event.
+
+Screenshots cover presentation. Keep unit and server tests for INV-6 sentinels,
+secret disclosure, auth and grant boundaries, CSRF, identity fences, cancellation,
+request lifetime, and error sanitization. Keep browser tests for keyboard/focus,
+XSS, real CSP enforcement, and popup lifetimes. A screenshot
+cannot prove these rules.
+
+## Updating Linux snapshots
+
+The source of truth is `*-linux.png`, produced on `ubuntu-latest` with the
+lockfile's Playwright Chromium. Both CI workflows use the same runner, Node 22,
+and `npm run test:browser:install -- --with-deps`. macOS runs fixture routing and
+readiness checks but omits screenshot comparison. The update script refuses
+non-Linux hosts. Do not commit Darwin baselines.
+
+When Docker is unavailable, use the **Operator snapshots** workflow:
+
+```sh
+git push --force-with-lease origin feat/p4-ui-tests
+gh workflow run operator-snapshots.yml --ref feat/p4-ui-tests
+# Read the completed run ID from the Actions page or gh run list.
+gh run download RUN_ID --name operator-linux-snapshots \
+  --dir test/browser/operator-visual.spec.ts-snapshots
+```
+
+The workflow uploads all generated baselines and never commits them. Review the
+images and changed files, commit the intentional changes, and push again. The
+normal CI browser job must compare and pass against that commit. Opening the
+initial PR also runs the update workflow, so the first baselines can be generated
+before the workflow reaches main. Later updates use `workflow_dispatch`.
+
+On a matching Linux runner, `npm ci`, install Chromium with the command above,
+then run `npm run test:browser:snapshots`. The normal command is
+`npm run test:browser`. Missing baselines fail CI; retries cannot bless them.
+Set `OPERATOR_VISUAL_INSPECT=1` to retain local screenshots under ignored
+`test-results/` for inspection, without updating committed baselines.
+
+## Real-server flows
+
+`test/browser/operator-flows.spec.ts` uses `listen()` from `src/node.ts` with
+loopback TCP servers. It intercepts only Clerk provider traffic with a test
+publishable key; server identity uses the existing `fakeClerkAuth` seam. The
+OAuth provider validates the code exchange and PKCE. Credential Test calls a
+loopback downstream endpoint. Operator APIs, cookie/bearer admission, CSRF,
+assets, handoffs, callbacks, and encrypted storage use production code.
+
+The flows cover Clerk sign-in/reload/sign-out; OAuth connect/consent/callback/
+connected reread/reload; and credential save/test/replace/remove. They collect
+CSP violations across every document and popup, and fail on unexpected network
+traffic. No credentials enter visual fixtures or screenshot baselines.

package/documentation/provider-migration-0.29.md

@@ -0,0 +1,60 @@
+# Notion, Vercel and Cloudflare migration for 0.29
+
+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
+connector ids must be checked in deployment configuration before that release.
+The provider audit establishes available auth modes, not production OAuth grants.
+
+All three providers now default to hosted MCP. `surface: "api"` explicitly
+selects a REST complement and accepts only its API-specific options. The old
+Vercel/Cloudflare API modes are no longer complete alternatives; Notion retains
+all operations required by its distinct integration identity. Adding `surface: "api"` keeps
+REST reads/gaps but does not restore removed duplicates. For both sets of
+capabilities, configure both connectors under distinct ids and authorize each.
+
+```ts
+connectors: [
+  notion("notion", { purpose: "Workspace content" }),
+  notion("notion_rest", { surface: "api", purpose: "Internal integration content and exact REST operations" }),
+  cloudflare("cloudflare", { purpose: "Estate mutations", auth: { type: "credential" } }),
+  cloudflare("cloudflare_rest", { surface: "api", purpose: "Estate reads and byte/header operations", accountId: "account-id", zoneId: "zone-id" }),
+]
+```
+
+Notion preserves headless/internal-integration capabilities. Add explicit
+`surface: "api"` to retain that identity and migrate old REST names to
+`integration_*`, for example `search` to `integration_search`, `create_page`
+to `integration_create_page`, and `query_data_source` to
+`integration_query_data_source`. Its token/sharing boundary stays intact.
+Hosted MCP acts as an OAuth user, has its own grant, and cannot adopt an internal
+token. Use it for user-owned work and hosted-only capabilities; authorize it
+explicitly if those are needed. Do not replace a bot with a user as an auth fix.
+All REST pagination, exact JSON blocks/properties, trash/restore and bot-owned
+content writes remain available.
+
+For Cloudflare, migrate ordinary JSON writes to hosted `search` then `execute`.
+A scoped API token can authorize hosted MCP without interactive OAuth; configure
+that credential independently even if it has the same value as the REST token.
+Keep REST reads in read-only programs. Global API Key/email and R2 jurisdiction/storage-class
+JSON mutations, plus byte/header-compatible uploads, stay in the explicit REST
+complement. Replace `update_r2_bucket` with `cloudflare_api_mutate` using
+`PATCH /accounts/{accountId}/r2/buckets/{bucketName}` and the header
+`cf-r2-storage-class` set to `Standard` or `InfrequentAccess`. Omit the body;
+include `cf-r2-jurisdiction` only when the bucket needs it. This remains a write.
+`execute` remains a write even when its program only calls GET.
+Trusted pools may execute writes; read-only pools use direct host-approved writes.
+
+For Vercel, authorize the owning teams in hosted OAuth, migrate discovery/logs,
+domain listing/adding, deployment cancellation and file uploads to live MCP
+schemas, and keep the independently authorized REST complement for value-safe
+project environment variables (including `upsert: false` create-only writes), domain verification/removal and deployment
+deletion. Promotion now uses hosted `request_promote` from the rolling-releases
+category. Raw hatches refuse all published REST counterparts, including project
+creation/update. Do not copy REST argument
+shapes into vendor tools, even when a tool name is unchanged.
+
+The per-provider tables map every removed name and explain retained API tools:
+[Notion](https://github.com/zackbart/connecta/blob/main/src/providers/notion/reconciliation.md),
+[Vercel](https://github.com/zackbart/connecta/blob/main/src/providers/vercel/reconciliation.md), and
+[Cloudflare](https://github.com/zackbart/connecta/blob/main/src/providers/cloudflare/reconciliation.md).

package/examples/worker/AGENTS.md

@@ -2,12 +2,18 @@
 
 This repository is deployment configuration, not a copy of Connecta itself.
 
-- Edit `src/index.ts` for connectors, authentication, storage, and public URL.
-- Keep `cloudflareAccessAuth()` as the inbound auth provider. Cloudflare Access
-  authenticates the request before the Worker runs; do not add JWT parsing or a
-  second Worker-side identity gate.
+- Edit `src/connecta.config.ts` for connectors, authentication, storage, public
+  URL, and optional modules. `src/index.ts` only starts it. Set plain vars
+  `CONNECTA_ACTIVITY="on"` for preserved activity.
+- Keep `cloudflareAccessAuth()` for human identity and `accessTokens(storage)`
+  always installed over the same `CONNECTA_DB` for machines. Cloudflare Access
+  admits the request before the Worker runs; a service identity alone is
+  refused inside connecta. Do not add JWT parsing or another identity gate.
+  Grant `identity.accessTokenManagement` explicitly to interactive operators;
+  this example permits every signed-in human to manage connectors and tokens.
 - Attach Access to the Worker itself, not only its hostname. Enable Managed
-  OAuth and Dynamic Client Registration on that Access application.
+  OAuth on that Access application. CIMD is the spec's preferred client
+  registration; enable DCR as the fallback Access currently requires.
 - Managed OAuth's **Allowed redirect URIs** must contain all three entries
   below. This is application configuration under
   `oauth_configuration.dynamic_client_registration.allowed_uris`, not an
@@ -25,24 +31,40 @@ This repository is deployment configuration, not a copy of Connecta itself.
   allowed. If a client presents a different callback, copy that exact URI from
   its registration attempt and add the narrowest matching entry rather than
   broadening the allowlist to an entire origin.
-- Keep `new DynamicWorkerExecutor({ loader: env.LOADER })` loader-only. Do not
+
+- Keep `workerExecutor({ loader: env.LOADER })` loader-only. Do not
   add bindings, modules, or outbound access to generated code.
+  Import it from `@zackbart/connecta/worker`; direct upstream
+  `new DynamicWorkerExecutor()` construction throws at boot. Keep the
+  `@cloudflare/codemode` optional peer installed.
 - Keep credentials in Worker secrets. Never commit credential values, Access
   service-token secrets, or `CREDENTIAL_ENCRYPTION_KEY`.
+- All state lives in the one D1 database bound as `CONNECTA_DB`, through
+  `d1Storage` (and `d1ActivityStore`) from `@zackbart/connecta/d1`. Do not add
+  a KV namespace, a second database, or a copied storage adapter; connecta
+  creates its own tables. The only KV binding is in `kv-to-d1.wrangler.jsonc`,
+  which is never deployed. It exists for the one-shot copy from a 0.28 Workers
+  KV deployment (README.md § "Upgrading from 0.28"). Back up, block traffic
+  and background writers, drain, wait for stable KV, copy and verify, deploy
+  while maintenance remains, then mark cutover before reopening traffic. Never
+  rerun stale KV after cutover. Retain backups before removing KV.
 - Add application logic only inside deliberate `api()` connector handlers.
   Do not copy or modify Connecta package internals here.
 - Prefer `api()` when the agent must see an exact reviewed capability set;
   `remoteMcp()` follows the downstream server's evolving tool catalog.
-- Use Access service credentials for `connecta doctor` and unattended clients.
-  A configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
-  tokens are removed. UI, vault, and activity use explicit optional imports;
+- Unattended clients and `connecta doctor` need Access service credentials
+  plus a stored `cta_` bearer. Set `CF_ACCESS_CLIENT_ID`,
+  `CF_ACCESS_CLIENT_SECRET`, and `CONNECTA_TOKEN` together for doctor.
+  Bootstrap tokens through the Access-authenticated operator page or trusted
+  `AccessTokenManager.create` tooling against this same D1 storage, as README
+  "Machine tokens" describes. Never configure a static bearer or open startup.
+  UI, vault, and activity use explicit optional imports;
   auth changes require code-derived shared or personal management permissions.
 - Brand the operator UI in `operatorUi({ branding })`: product and owner names,
   description, favicon, and `theme` (`accent`, `radius`, `fontFamily`,
   `monoFamily`, `colorScheme`). Ask the deployment's owner for their brand
-  rather than leaving the default. The commented block above
-  `ui: operatorUi()` in `src/index.ts` shows the shape; README "UI and
-  encrypted credentials" covers the rest.
+  rather than leaving the default. README "UI and encrypted credentials" shows
+  the shape.
 - After configuration changes, typecheck: inside the connecta repository that
   is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and