@zackbart/connecta 0.28.1 → 0.29.0

package/README.md

@@ -10,7 +10,7 @@ writing code instead of loading a thousand tool definitions.
 You ask your agent a question that touches a service — Linear, Stripe, an
 internal API, anything you have connected. Here is what happens:
 
-1. The agent talks to one endpoint, yours, and sees seven tools. Always seven,
+1. The agent talks to one endpoint, yours, and sees six tools. Always six,
    no matter how many services sit behind it.
 2. It writes a short JavaScript program. Connecta runs it in a sandbox next to
    your integrations. The program can search for tools, call them, chain the
@@ -18,10 +18,9 @@ internal API, anything you have connected. Here is what happens:
 3. Only the answer comes back into the agent's context — not raw pages of
    API output.
 4. If the agent wants to change something — create, update, delete — it
-   cannot do that from a program, unless your config exempts that tool. The
-   program refuses the write before anything is sent and hands back the exact
-   call; the agent makes it through `call_destructive_tool`, one visible call
-   your MCP client can put in front of you first.
+   can do that from a program in a `trusted` pool. A `read-only` pool
+   routes each write through `call_destructive_tool`. The host controls approval; trusted endpoints annotate `execute_code` as a
+   write. Pool trust defaults to `read-only`.
 
 Credentials never leave the server. The program never sees them, and neither
 does the agent.
@@ -30,8 +29,8 @@ does the agent.
 flowchart TB
     Client["Your MCP client<br/>Claude, Cursor, …"]
 
-    subgraph Connecta["Connecta — one endpoint, seven tools, your credentials"]
-        Sandbox["execute_code<br/>the agent's program runs here<br/>read-only tools, plus writes<br/>your config exempts"]
+    subgraph Connecta["Connecta — one endpoint, six tools, your credentials"]
+        Sandbox["execute_code<br/>the agent's program runs here<br/>reads, plus writes<br/>in trusted pools"]
         Explicit["call_destructive_tool<br/>one visible call per write<br/>your client can ask you first"]
     end
 
@@ -47,7 +46,7 @@ This is the kind of thing the agent writes, not you:
 
 ```js
 async () => {
-  const { nodes } = await connecta.call("tracker.list_issues", { state: "started" });
+  const { data: { nodes } } = await connecta.call("tracker.list_issues", { state: "started" });
   const byOwner = {};
   for (const issue of nodes) {
     (byOwner[issue.assignee?.name ?? "unassigned"] ??= []).push(issue.identifier);
@@ -64,14 +63,19 @@ Fifty issues in, one small object out. Your context window notices.
   services in a config file; your client never changes.
 - **Wrap any HTTP API by hand.** A few lines per tool. No OpenAPI conversion —
   generated tool sprawl is the problem, not the fix.
-- **Use maintained connections** for Basecamp, Breeze ChMS, Church Community
-  Builder, Cloudflare, Linear, Mixpanel, Notion, Overflow, Planning Center,
-  RevenueCat, Stripe, Tithe.ly, and Vercel: known endpoints, auth defaults, and
-  vetted read/write classifications, imported one at a time. Cloudflare,
-  Notion, and Vercel each let the deployment choose their hand-written API
-  interface or official hosted MCP. Planning Center, Overflow, Tithe.ly,
-  Breeze, and Church Community Builder are hand-written over their whole APIs,
-  with every money-moving write behind approval.
+- **Use maintained connections** for <!-- providers:start -->Basecamp, Breeze ChMS, Church Community Builder, Cloudflare, GitHub, Gmail, Google Docs, Google Drive, Google Forms, Google Sheets, Google Slides, Linear, Mixpanel, Notion, Overflow, Planning Center, RevenueCat, Stripe, Tithe.ly, and Vercel<!-- providers:end -->: known endpoints, auth defaults, and
+  vetted read/write classifications, imported one at a time.
+  Cloudflare, Notion, and Vercel each let the deployment choose their
+  hand-written API interface or official hosted MCP. Planning Center, Overflow,
+  Tithe.ly, Breeze, and Church Community Builder are hand-written over their
+  whole APIs, with every money-moving write behind approval. Gmail reads mail
+  and writes drafts — never sends — and Google Drive reads, writes, and shares
+  files — never deletes one for good — as each signed-in Workspace user through
+  domain-wide delegation, with no per-user consent step; Google Docs reads and
+  edits documents, and Google Sheets reads and writes spreadsheets, the same
+  way. Google Slides reads, creates, edits, and comments on each user's decks the
+  same way.
+  Google Forms reads and edits forms and reads their responses the same way.
 - **Let the agent work in code.** Search, chain, filter, join, and reduce
   inside the sandbox instead of round-tripping every call through the model.
 - **Teach undeclared result shapes by using them.** Successful read-only calls
@@ -83,45 +87,61 @@ Fifty issues in, one small object out. Your context window notices.
   notice also points the agent to reduce or search the result inside a
   program. Discovery can show compact schemas, exact JSON Schema, or a
   TypeScript signature to read while writing JavaScript.
-- **Keep writes deliberate.** Only tools marked read-only run in a program.
-  Every other write is a separate, visible `call_destructive_tool` call your
-  client can gate, so the host's permission prompt is the one approval there
-  is. Config — and only config — can exempt a cheap, reversible write from
-  asking, per tool or per connector, and then a program may make it.
+- **Keep writes deliberate.** The registry classifies tools as reads or writes.
+  Read-only pools route writes through `call_destructive_tool`; trusted pools
+  let programs write and annotate `execute_code` as a write. The host controls
+  approval. Exact deployment classification overrides beat provider review
+  and downstream annotations.
 - **Run it on Node or Cloudflare Workers.** The core is shared; each deployment
-  supplies its platform's executor and storage. The Node template also runs
-  unchanged in Docker.
+  supplies its platform's executor and one store: a D1 database on Workers
+  (`@zackbart/connecta/d1`), a SQLite file on Node (`@zackbart/connecta/sqlite`).
+  The Node template also runs unchanged in Docker.
 
 Deployments explicitly compose optional features: `operatorUi()` from
 `@zackbart/connecta/ui`, `encryptedCredentialVault()` from `/credentials`,
-`activityHistory()` from `/activity`, `artifacts()` from `/artifacts`, and
+`activityHistory()` from `/activity`, and
 inbound authentication adapters from `/auth/*`. Omit a module and its implementation does no runtime work. Core
 keeps connector discovery, execution, invocation, and enforcement together.
-
-The optional UI shows each person's connections and effective permissions.
-Authentication controls live inside each connection, with optional activity
-history. The configured connection list loads before downstream checks finish;
-a slow provider does not hold up the page. Connector selection and access rules
-remain in deployment code. It also explains which tools can run in programs or
-need approval, offers a fixed repair prompt for classified failures, and shows
-client setup commands for the endpoints the signed-in person can use.
+Both deployment shapes write configuration as `defineConfig((env) => …)`, with
+each optional module a type-checked expression the environment switches on.
+`createConnecta` validates it against one schema — an unknown option or an
+unusable value refuses to boot — and `connecta.describeConfig()` returns a
+secret-free snapshot of what the deployment runs with. With `operatorUi()` enabled,
+`GET /ui/api/config` returns that snapshot scoped to the caller, live connector
+facts, and the caller's grants and permissions. `CONNECTA_TOKEN=<bearer> connecta
+doctor --config --url https://connecta.example` prints only the scoped snapshot
+as JSON, using the same serializer. It does not run the diagnostic program.
+
+The optional UI has Overview, Connectors, Tools, Access, Activity and
+Config pages. Connector detail separates configuration, schemas, authentication,
+activity and diagnostics into tabs. Overview shows health, attention items and
+endpoint setup in a drawer; Config marks each snapshot value as default or
+configured. Catalog descriptions and schemas render as text. Activity filters
+stay in the URL and calls group by recorded request id. Authentication, history,
+and token controls use the signed-in person's existing permissions.
+Connector selection and access rules remain in deployment code.
 
 One deployment may serve several authenticated people inside the same tenant.
-Cloudflare Access supplies Worker identity; Node can use Clerk or the optional
-configured bearer adapter. Connecta owns no accounts or groups and issues no
-client access tokens. Shared-credential administration and personal connection
+Cloudflare Access supplies Worker identity; Node uses Clerk for human auth. Machine clients use connecta-issued `cta_`
+access tokens. Static bearer secrets are retired. Connecta owns no accounts or groups. Shared-credential administration and personal connection
 setup require separate explicit permissions, both denied by default. See
 [inbound auth](./documentation/auth.md#principals-visibility-and-operators).
+Clerk deployments enable `aud_claim_enabled` and use resource-bound JWT or
+opaque OAuth tokens by default. An explicit `allowedOAuthClientIds` list is a
+fallback for unbound tokens from dedicated clients. Clerk session
+tokens authenticate operator routes only; [Clerk auth](./documentation/auth.md#clerk-oauth-tokens-and-operator-sessions)
+describes endpoint audience validation and the configuration migration.
 
 Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
-service. Those are decisions, and the [ethos](./ethos.md) records each one
-and why.
+service. The [principles](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md)
+state the goals and invariants; [decision records](https://github.com/zackbart/connecta/tree/main/decisions)
+explain past choices.
 
 ## Getting started
 
-Setup is written for an agent. Point yours at [`AGENTS.md`](./AGENTS.md) and
+Setup is written for an agent. Point yours at [`AGENTS.md`](https://github.com/zackbart/connecta/blob/main/AGENTS.md) and
 ask it to set up a Connecta deployment; the
-[documentation](./documentation/) covers the architecture, the seven tools,
+[documentation](./documentation/) covers the architecture, the six tools,
 code mode, and inbound auth if you want to go deeper. When upgrading an
 existing deployment, each [changelog](./CHANGELOG.md) release opens with what
 breaks and what a deployment can ignore.
@@ -139,6 +159,6 @@ Upgrading from v0.23 does not require rotating managed `cta_…` tokens. Import
 `accessTokens: true` with `accessTokens: accessTokens(storage)`, and keep the
 same persistent storage namespace and identity/tool/pool grant rules. Enable
 `identity.accessTokenManagement` only for the interactive operators who should
-manage tokens. New issuance needs storage with atomic `compareAndSet`; older
-storage adapters can still verify existing tokens. See the package's
-`documentation/auth.md` for the migration and storage requirements.
+manage tokens. Records written by v0.23 and later move with the store: a 0.28
+JSON state file migrates with `connecta migrate-state`, and a D1 table is
+read as is. See the package's `documentation/auth.md` for the migration.

package/bin/connecta.mjs

@@ -1,18 +1,10 @@
 #!/usr/bin/env node
 
-import {
-  copyFile,
-  cp,
-  lstat,
-  mkdtemp,
-  readFile,
-  rename,
-  rm,
-  symlink,
-  writeFile,
-} from "node:fs/promises";
+import { copyFile, cp, lstat, mkdtemp, readFile, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { CONNECTA_VERSION } from "./version.mjs";
+import { META_TOOL_NAMES } from "./meta-tool-names.mjs";
 import { basename, dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const [command, ...args] = process.argv.slice(2);
@@ -27,7 +19,8 @@ function shellCd(path) {
 function usage() {
   console.log(`Usage:
   connecta init [directory]
-  CONNECTA_TOKEN=<bearer> connecta doctor [--url http://localhost:8787]
+  connecta migrate-state <state.json> <connecta.sqlite>
+  CONNECTA_TOKEN=<bearer> connecta doctor [--config] [--url http://localhost:8787]
   CF_ACCESS_CLIENT_ID=<id> CF_ACCESS_CLIENT_SECRET=<secret> connecta doctor --url https://worker.example`);
 }
 
@@ -44,18 +37,13 @@ async function init() {
     await lstat(target);
     throw new Error(`Refusing to overwrite existing path: ${target}`);
   } catch (error) {
-    const code =
-      error && typeof error === "object" && "code" in error
-        ? String(error.code)
-        : "";
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
     if (code !== "ENOENT") throw error;
   }
 
   // Build beside the destination, then rename once complete. A failed copy or
   // rewrite leaves no partial destination that blocks a clean retry.
-  let stage = await mkdtemp(
-    join(parent, `.${basename(target)}.connecta-init-`),
-  );
+  let stage = await mkdtemp(join(parent, `.${basename(target)}.connecta-init-`));
   try {
     await cp(join(packageRoot, "templates", "node"), stage, {
       recursive: true,
@@ -63,10 +51,7 @@ async function init() {
 
     // npm excludes .gitignore files and symlinks from packed dependencies.
     // Restore both conventions explicitly in the generated project.
-    await writeFile(
-      join(stage, ".gitignore"),
-      ".connecta-state.json\n.connecta-activity.jsonl\n.env\nnode_modules/\n",
-    );
+    await writeFile(join(stage, ".gitignore"), ".connecta.sqlite*\n.env\nnode_modules/\n");
     await rm(join(stage, "CLAUDE.md"), { force: true });
     try {
       await symlink("AGENTS.md", join(stage, "CLAUDE.md"));
@@ -76,18 +61,11 @@ async function init() {
       await copyFile(join(stage, "AGENTS.md"), join(stage, "CLAUDE.md"));
     }
 
-    const rootPackage = JSON.parse(
-      await readFile(join(packageRoot, "package.json"), "utf8"),
-    );
+    const rootPackage = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
     const deploymentPath = join(stage, "package.json");
-    const deploymentPackage = JSON.parse(
-      await readFile(deploymentPath, "utf8"),
-    );
+    const deploymentPackage = JSON.parse(await readFile(deploymentPath, "utf8"));
     deploymentPackage.dependencies["@zackbart/connecta"] = rootPackage.version;
-    await writeFile(
-      deploymentPath,
-      JSON.stringify(deploymentPackage, null, 2) + "\n",
-    );
+    await writeFile(deploymentPath, JSON.stringify(deploymentPackage, null, 2) + "\n");
 
     await rename(stage, target);
     stage = "";
@@ -99,7 +77,10 @@ async function init() {
   console.log("Next:");
   console.log(`  ${shellCd(target)}`);
   console.log("  npm install");
-  console.log("  CONNECTA_TOKEN=dev-token npm start");
+  console.log('  npm run --silent provision-token -- "local-machine"');
+  console.log("  # Save the returned cta_ token privately for your MCP client and doctor.");
+  console.log("  npm start");
+  console.log("  # README.md covers database paths and Docker provisioning.");
 }
 
 function option(name, fallback) {
@@ -135,7 +116,7 @@ async function doctorFetch(url, init = {}) {
     const response = await fetch(url, {
       ...init,
       redirect: "manual",
-      signal: AbortSignal.timeout(DOCTOR_TIMEOUT_MS),
+      signal: AbortSignal.any([AbortSignal.timeout(DOCTOR_TIMEOUT_MS), ...(init.signal ? [init.signal] : [])]),
     });
     if ([301, 302, 303, 307, 308].includes(response.status)) {
       await response.body?.cancel().catch(() => {});
@@ -145,10 +126,7 @@ async function doctorFetch(url, init = {}) {
     }
     return response;
   } catch (error) {
-    if (
-      error instanceof Error &&
-      (error.name === "TimeoutError" || error.name === "AbortError")
-    ) {
+    if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
       throw new Error(`Timed out after ${DOCTOR_TIMEOUT_MS}ms contacting ${url}`);
     }
     throw error;
@@ -156,9 +134,9 @@ async function doctorFetch(url, init = {}) {
 }
 
 async function doctor() {
-  const known = new Set(["--url"]);
-  for (let index = 0; index < args.length; index += 2) {
-    if (!known.has(args[index]) || !args[index + 1]) {
+  for (let index = 0; index < args.length; index++) {
+    if (args[index] === "--config") continue;
+    if (args[index] !== "--url" || !args[++index] || args[index].startsWith("--")) {
       usage();
       process.exitCode = 1;
       return;
@@ -173,22 +151,15 @@ async function doctor() {
     throw new Error("Doctor URL must use http or https.");
   }
   const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
-  if (
-    parsedUrl.protocol === "http:" &&
-    !loopbackHosts.has(parsedUrl.hostname)
-  ) {
-    throw new Error(
-      "Refusing to send authentication credentials over remote plaintext HTTP. Use HTTPS.",
-    );
+  if (parsedUrl.protocol === "http:" && !loopbackHosts.has(parsedUrl.hostname)) {
+    throw new Error("Refusing to send authentication credentials over remote plaintext HTTP. Use HTTPS.");
   }
   const baseUrl = requestedUrl.replace(/\/+$/, "");
   const token = process.env.CONNECTA_TOKEN;
   const accessClientId = process.env.CF_ACCESS_CLIENT_ID;
   const accessClientSecret = process.env.CF_ACCESS_CLIENT_SECRET;
   if (Boolean(accessClientId) !== Boolean(accessClientSecret)) {
-    throw new Error(
-      "Set both CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET.",
-    );
+    throw new Error("Set both CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET.");
   }
   if (!token && !accessClientId) {
     throw new Error(
@@ -205,9 +176,28 @@ async function doctor() {
       : {}),
   };
 
-  const health = await jsonResponse(
-    await doctorFetch(`${baseUrl}/health`, { headers: authHeaders }),
-  );
+  if (args.includes("--config")) {
+    const response = await doctorFetch(`${baseUrl}/ui/api/config`, { headers: authHeaders });
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => {});
+      throw new Error(`HTTP ${response.status}: config snapshot unavailable.`);
+    }
+    let contract;
+    try {
+      contract = await response.json();
+    } catch {
+      throw new Error("Deployment returned an invalid config contract.");
+    }
+    if (contract?.schemaVersion !== 1 || contract.config?.schemaVersion !== 1) {
+      throw new Error("Deployment returned an unsupported config contract.");
+    }
+    // The server builds this with describeConfig's allowlist; do not print
+    // the overlay, identity, health deploymentInfo, or a raw error body.
+    console.log(JSON.stringify(contract.config, null, 2));
+    return;
+  }
+
+  const health = await jsonResponse(await doctorFetch(`${baseUrl}/health`, { headers: authHeaders }));
   if (health.status !== "ok") {
     throw new Error(`Unexpected health status: ${String(health.status)}`);
   }
@@ -225,107 +215,88 @@ async function doctor() {
           .slice(0, 40)
           .trim()
       : "";
-  let requestId = 0;
-  const mcp = async (method, params) =>
-    jsonResponse(
-      await doctorFetch(`${baseUrl}/mcp`, {
-      method: "POST",
-      headers: {
-        ...authHeaders,
-        "Content-Type": "application/json",
-        Accept: "application/json, text/event-stream",
-      },
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-          id: ++requestId,
-          method,
-          params,
-      }),
-      }),
-    );
-
-  const listed = await mcp("tools/list", {});
-  if (listed.error) {
-    throw new Error(`tools/list failed: ${JSON.stringify(listed.error)}`);
-  }
-  const actual = listed.result?.tools
-    ?.map((tool) => tool.name)
-    .sort();
-  const expected = [
-    "authorize_connector",
-    "call_destructive_tool",
-    "call_tool",
-    "execute_code",
-    "get_result",
-    "search_tools",
-    "skills",
-  ];
-  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
-    throw new Error(
-      `Unexpected MCP surface. Expected ${expected.join(", ")}; received ` +
-      `${Array.isArray(actual) ? actual.join(", ") : "no tool list"}.`,
-    );
-  }
-
-  const executed = await mcp("tools/call", {
-    name: "execute_code",
-    arguments: { code: "async () => 42" },
+  const { Client, StreamableHTTPClientTransport } = await import("@modelcontextprotocol/client");
+  const client = new Client(
+    { name: "connecta-doctor", version: CONNECTA_VERSION },
+    { versionNegotiation: { mode: "auto", probe: { timeoutMs: DOCTOR_TIMEOUT_MS } } },
+  );
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/mcp`), {
+    requestInit: { headers: authHeaders },
+    fetch: doctorFetch,
   });
-  if (executed.error) {
-    throw new Error(`execute_code failed: ${JSON.stringify(executed.error)}`);
-  }
-  const executionResult =
-    executed.result?.structuredContent ??
-    JSON.parse(executed.result?.content?.[0]?.text ?? "null");
-  if (executed.result?.isError || executionResult?.result !== 42) {
-    throw new Error(
-      `${executorName ? `${executorName} execution` : "execute_code"} check ` +
-        `failed: ${JSON.stringify(executed.result)}`,
-    );
-  }
+  let negotiatedVersion;
+  try {
+    await client.connect(transport);
+    negotiatedVersion = client.getNegotiatedProtocolVersion();
+    const listed = await client.listTools({}, { timeout: DOCTOR_TIMEOUT_MS });
+    const actual = listed.tools.map((tool) => tool.name).sort();
+    const expected = [...META_TOOL_NAMES].sort();
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+      throw new Error(
+        `Unexpected MCP surface. Expected ${expected.join(", ")}; received ` +
+          `${Array.isArray(actual) ? actual.join(", ") : "no tool list"}.`,
+      );
+    }
 
-  // Drift is reported, never failed on. A downstream that grew a tool nobody
-  // has classified is a maintainer's next task, not a broken deployment: the
-  // unclassified tool already fails closed onto call_destructive_tool. These
-  // counts come from refreshes the deployment already served, so a deployment
-  // that has answered no catalog request yet reports nothing here (#343).
-  const drifted = Object.entries(health.catalogDrift ?? {}).filter(
-    ([, report]) =>
-      report.unclassifiedTools ||
-      report.unservedTools ||
-      report.annotationConflicts ||
-      report.schemaChanges,
-  );
-  for (const [connectorId, report] of drifted) {
-    console.warn(
-      `[connecta] catalog drift on "${connectorId}" (observed ` +
-        `${report.observedAt}): ${report.unclassifiedTools} unclassified, ` +
-        `${report.unservedTools} no longer served, ` +
-        `${report.annotationConflicts} annotation conflict(s), ` +
-        `${report.schemaChanges} schema change(s).`,
+    const executed = await client.callTool(
+      {
+        name: "execute_code",
+        arguments: { code: "async () => 42" },
+      },
+      undefined,
+      { timeout: DOCTOR_TIMEOUT_MS },
     );
+    const executionResult = executed.structuredContent ?? JSON.parse(executed.content?.[0]?.text ?? "null");
+    if (executed.isError || executionResult?.result !== 42) {
+      throw new Error(
+        `${executorName ? `${executorName} execution` : "execute_code"} check ` + `failed: ${JSON.stringify(executed)}`,
+      );
+    }
+  } finally {
+    await client.close();
   }
 
   console.log(
     `Connecta doctor passed: ${health.connectors} connector(s), ` +
       `${executorName ? `${executorName} executed` : "code executed"}, ` +
-      "prescribed seven-tool surface" +
-      (drifted.length > 0
-        ? `, catalog drift on ${drifted.length} connector(s).`
-        : "."),
+      `prescribed ${META_TOOL_NAMES.length}-tool surface, MCP ${negotiatedVersion}, package ${CONNECTA_VERSION}.`,
   );
 }
 
+/**
+ * One-shot copy of a 0.28 `fileStorage` JSON state file into the SQLite
+ * database 0.29 stores everything in. Stop the old deployment first; the file
+ * is read, never changed.
+ */
+async function migrateState() {
+  if (args.length !== 2 || args.some((arg) => arg.startsWith("--"))) {
+    usage();
+    process.exitCode = 1;
+    return;
+  }
+  const [statePath, databasePath] = args.map((arg) => resolve(process.cwd(), arg));
+  const { importStateFile, openSqlite } = await import(pathToFileURL(join(packageRoot, "dist", "sqlite.js")).href);
+  const database = openSqlite(databasePath);
+  try {
+    const result = importStateFile(database, statePath);
+    console.log(
+      `Imported ${result.imported} entries from ${statePath} into ${databasePath}` +
+        ` (${result.kept} already present, ${result.expired} expired).`,
+    );
+  } finally {
+    database.close();
+  }
+}
+
 try {
   if (command === "init") await init();
   else if (command === "doctor") await doctor();
+  else if (command === "migrate-state") await migrateState();
   else {
     usage();
     process.exitCode = command === "--help" || command === "-h" ? 0 : 1;
   }
 } catch (error) {
-  console.error(
-    `[connecta] ${error instanceof Error ? error.message : String(error)}`,
-  );
+  console.error(`[connecta] ${error instanceof Error ? error.message : String(error)}`);
   process.exitCode = 1;
 }

package/bin/meta-tool-names.d.mts

@@ -0,0 +1,2 @@
+/** The complete upward meta-tool set, shared by discovery checks and doctor. */
+export declare const META_TOOL_NAMES: readonly string[];

package/bin/meta-tool-names.mjs

@@ -0,0 +1,9 @@
+/** The complete upward meta-tool set, shared by discovery checks and doctor. */
+export const META_TOOL_NAMES = Object.freeze([
+  "authorize_connector",
+  "call_destructive_tool",
+  "call_tool",
+  "execute_code",
+  "search_tools",
+  "skills",
+]);

package/bin/version.mjs

@@ -0,0 +1,3 @@
+// Generated from package.json by scripts/generate-version.mjs.
+// Workers-safe: no runtime filesystem read or deployment override.
+export const CONNECTA_VERSION = "0.29.0";