@withone/cli 1.39.0 → 1.40.0

package/README.md

@@ -312,9 +312,9 @@ one sync install && one sync doctor
 ```
 
 ```bash
-# Discover → init (one command: infer + auto-resolve key + auto-test) → run
+# Discover → init (one command: infer + late-bound connection + auto-test) → run
 one sync models stripe
-one sync init stripe balanceTransactions    # connectionKey auto-resolved, test auto-run
+one sync init stripe balanceTransactions    # connection: { platform } baked in, test auto-run
 one sync run stripe --since 90d
 
 # Query, search, SQL
@@ -332,6 +332,8 @@ one sync run stripe --full-refresh
 
 > **Sync uses passthrough actions only.** Profiles referencing a custom/composer action are rejected at runtime. `sync models` already filters to passthrough-only; if a model has no passthrough list endpoint, compose a flow instead of syncing.
 
+> **Connections are late-bound.** Profiles use `"connection": { "platform": "<name>", "tag"?: "..." }` instead of literal `connectionKey` strings. The key is resolved at sync time, so `one add <platform>` (re-auth) doesn't break the profile. `tag` only needed for multi-account platforms (e.g. two Gmail accounts).
+
 | Subcommand | What it does |
 |------------|-------------|
 | `install` / `doctor` | Install + verify the SQLite engine |

package/dist/{chunk-MNJJE4PJ.js → chunk-SSEDFOVV.js}

@@ -98,6 +98,42 @@ var OneApi = class {
   async deleteConnection(id) {
     await this.requestFull({ path: `/vault/connections/${id}`, method: "DELETE" });
   }
+  /**
+   * Resolve a late-bound `ConnectionRef` to a current `Connection`. Pass
+   * `cache` (a pre-fetched connection list) when resolving many refs in a
+   * loop, so each resolve doesn't repeat the listConnections round-trip.
+   *
+   * Errors are deliberately verbose: a sync profile or flow that fails to
+   * resolve a connection should surface *why* (no match / wrong tag /
+   * ambiguous) so the agent can fix the ref without trial and error.
+   */
+  async resolveConnection(ref, cache) {
+    const all = cache ?? await this.listConnections();
+    const platformLower = ref.platform.toLowerCase();
+    const candidates = all.filter((c) => c.platform.toLowerCase() === platformLower);
+    if (candidates.length === 0) {
+      throw new Error(
+        `No connection found for platform "${ref.platform}". Run 'one add ${ref.platform}' to connect.`
+      );
+    }
+    let matches = candidates;
+    if (ref.tag) {
+      matches = candidates.filter((c) => c.tags?.includes(ref.tag));
+      if (matches.length === 0) {
+        const availableTags = candidates.flatMap((c) => c.tags ?? []);
+        throw new Error(
+          `No "${ref.platform}" connection has tag "${ref.tag}". Available tags: ${availableTags.length > 0 ? availableTags.join(", ") : "(none)"}.`
+        );
+      }
+    }
+    if (matches.length > 1) {
+      const tagList = matches.map((c) => c.tags?.length ? c.tags.join(",") : "(no tag)").join("; ");
+      throw new Error(
+        `Multiple "${ref.platform}" connections found (tags: ${tagList}). Add a "tag" field to the connection ref to disambiguate.`
+      );
+    }
+    return matches[0];
+  }
   async listPlatforms() {
     const allPlatforms = [];
     let page = 1;
@@ -1079,7 +1115,7 @@ async function executeSubflowStep(step, context, api, permissions, allowedAction
   if (flowStack.includes(resolvedKey)) {
     throw new Error(`Circular flow detected: ${[...flowStack, resolvedKey].join(" \u2192 ")}`);
   }
-  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-OVOGDXNR.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-2KVAPP6E.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,

package/dist/{flow-runner-OVOGDXNR.js → flow-runner-2KVAPP6E.js}

@@ -11,7 +11,7 @@ import {
   saveFlow,
   summarizeFlowInputs,
   walkSteps
-} from "./chunk-MNJJE4PJ.js";
+} from "./chunk-SSEDFOVV.js";
 export {
   FlowRunner,
   collectStepTypes,

package/dist/index.js

@@ -19,7 +19,7 @@ import {
   resolveFlowPath,
   saveFlow,
   validateActionInput
-} from "./chunk-MNJJE4PJ.js";
+} from "./chunk-SSEDFOVV.js";
 
 // src/index.ts
 import { createRequire as createRequire2 } from "module";
@@ -4732,12 +4732,24 @@ function readProfile(platform, model) {
   }
 }
 function writeProfile(profile) {
-  const required = ["platform", "model", "connectionKey", "actionId", "idField", "pagination"];
+  const required = ["platform", "model", "actionId", "idField", "pagination"];
   for (const field of required) {
     if (!profile[field]) {
       throw new Error(`Missing required field: ${field}`);
     }
   }
+  const hasKey = !!profile.connectionKey;
+  const hasRef = !!profile.connection?.platform;
+  if (hasKey && hasRef) {
+    throw new Error(
+      "Profile has both `connectionKey` and `connection` \u2014 set exactly one. Prefer `connection: { platform, tag? }` so re-auth doesn't break the profile."
+    );
+  }
+  if (!hasKey && !hasRef) {
+    throw new Error(
+      'Missing connection: set `connection: { platform: "<name>" }` (or legacy `connectionKey: "<key>"`).'
+    );
+  }
   if (profile.resultsPath === void 0) {
     throw new Error('Missing required field: resultsPath (use "" or "$" for root-array responses)');
   }
@@ -4748,6 +4760,16 @@ function writeProfile(profile) {
   const filePath = profilePath(profile.platform, profile.model);
   fs8.writeFileSync(filePath, JSON.stringify(profile, null, 2));
 }
+async function resolveProfileConnectionKey(api, profile, cache2) {
+  if (profile.connectionKey) return profile.connectionKey;
+  if (!profile.connection?.platform) {
+    throw new Error(
+      `Profile ${profile.platform}/${profile.model} has no connectionKey or connection ref.`
+    );
+  }
+  const conn = await api.resolveConnection(profile.connection, cache2);
+  return conn.key;
+}
 function writeDraftProfile(platform, model, draft) {
   fs8.mkdirSync(PROFILES_DIR, { recursive: true });
   const filePath = profilePath(platform, model);
@@ -4773,7 +4795,9 @@ function generateTemplate(platform, model, actionId) {
   return {
     platform,
     model,
-    connectionKey: "FILL_IN",
+    // Late-bound ref — survives re-auth. Use { platform, tag } when the
+    // platform has multiple connections (e.g. multiple Gmail accounts).
+    connection: { platform },
     actionId: actionId ?? "FILL_IN",
     resultsPath: "FILL_IN",
     idField: "FILL_IN",
@@ -5833,6 +5857,7 @@ async function syncModel(api, profile, options) {
       "--full-refresh and --since cannot be used together. --full-refresh always fetches the whole collection."
     );
   }
+  const connectionKey = await resolveProfileConnectionKey(api, profile);
   const lock = options.dryRun ? null : acquireSyncLock(platform, model);
   const existingState = getModelState(platform, model);
   if (existingState?.status === "syncing" && !options.dryRun && !isAgentMode()) {
@@ -5960,7 +5985,7 @@ async function syncModel(api, profile, options) {
           const result = await api.executePassthroughRequest({
             platform,
             actionId: profile.actionId,
-            connectionKey: profile.connectionKey,
+            connectionKey,
             pathVariables: profile.pathVars,
             queryParams: currentPageQueryParams,
             headers: currentPageHeaders,
@@ -6169,7 +6194,7 @@ async function syncModel(api, profile, options) {
         profile.enrich,
         model,
         profile.idField,
-        profile.connectionKey,
+        connectionKey,
         platform,
         {
           transform: profile.transform,
@@ -6275,6 +6300,18 @@ async function testSyncProfile(api, profile) {
     if (limitLocation === "body") bodyParams[limitParam] = pageSize;
     else queryParams[limitParam] = pageSize;
   }
+  let connectionKey;
+  try {
+    connectionKey = await resolveProfileConnectionKey(api, profile);
+    checks.push({ name: "connection resolves", ok: true });
+  } catch (err) {
+    checks.push({
+      name: "connection resolves",
+      ok: false,
+      detail: err instanceof Error ? err.message : String(err)
+    });
+    return report;
+  }
   let actionDetails;
   try {
     actionDetails = await api.getActionDetails(profile.actionId);
@@ -6287,12 +6324,20 @@ async function testSyncProfile(api, profile) {
     });
     return report;
   }
+  if (actionDetails.tags?.includes("custom")) {
+    checks.push({
+      name: "action is passthrough (not custom)",
+      ok: false,
+      detail: `Action ${profile.actionId} is tagged "custom". Sync only supports passthrough actions. Run 'one actions search ${profile.platform} "${profile.model}"' to find one.`
+    });
+    return report;
+  }
   let responseData;
   try {
     const result = await api.executePassthroughRequest({
       platform: profile.platform,
       actionId: profile.actionId,
-      connectionKey: profile.connectionKey,
+      connectionKey,
       pathVariables: profile.pathVars,
       queryParams,
       data: Object.keys(bodyParams).length > 0 ? bodyParams : void 0
@@ -7451,11 +7496,11 @@ async function syncInitCommand(platform, model, options) {
           (c) => c.platform === platform
         );
         if (platformConns.length === 1) {
-          template.connectionKey = platformConns[0].key;
-          inferred?.reasoning.push(`connectionKey: auto-resolved (only one ${platform} connection)`);
+          inferred?.reasoning.push(`connection: { platform: "${platform}" } resolves to the single available connection`);
         } else if (platformConns.length > 1) {
+          const tags = platformConns.map((c) => c.tags?.join(",") ?? "(no tag)").join("; ");
           inferred?.reasoning.push(
-            `connectionKey: ${platformConns.length} connections found \u2014 pick one from \`one list\``
+            `connection: ${platformConns.length} ${platform} connections found (tags: ${tags}). Add a \`tag\` field to the connection ref to disambiguate.`
           );
         }
       } catch {
@@ -7539,6 +7584,11 @@ Run with --config to save:
       ...patch.pagination ?? {}
     }
   };
+  if (patch.connection && !patch.connectionKey) {
+    delete profile.connectionKey;
+  } else if (patch.connectionKey && !patch.connection) {
+    delete profile.connection;
+  }
   try {
     writeProfile(profile);
     if (isAgentMode()) {
@@ -8630,12 +8680,12 @@ one --agent sync models stripe
 # 2. Init \u2014 one command does everything:
 #    - resolves action ID
 #    - infers pagination, resultsPath, idField, pathVars from knowledge
-#    - auto-resolves connectionKey (when only one connection exists)
+#    - sets connection: { platform } so the profile survives re-auth
 #    - auto-runs sync test if profile is complete
 one --agent sync init stripe balanceTransactions
 # Response includes _complete:true and _test results when fully resolved.
-# If connectionKey wasn't auto-resolved (multiple connections), patch it:
-one --agent sync init stripe balanceTransactions --config '{"connectionKey":"<from one list>"}'
+# Multi-account platforms (e.g. two Gmail connections) need a tag:
+one --agent sync init gmail gmailThreads --config '{"connection":{"platform":"gmail","tag":"work@example.com"}}'
 
 # 3. Sync
 one --agent sync run stripe
@@ -8646,10 +8696,29 @@ one --agent sync search "refund" --platform stripe
 one --agent sync sql stripe "SELECT count(*) FROM balanceTransactions"
 \`\`\`
 
+## Connection Resolution \u2014 late-bound by default
+
+Sync profiles use a late-bound connection ref instead of a hardcoded key, so re-auth (which always mints a new key) doesn't break the profile:
+
+\`\`\`json
+// recommended \u2014 survives re-auth
+"connection": { "platform": "gmail" }
+
+// multi-account: disambiguate with the connection's tag
+"connection": { "platform": "gmail", "tag": "work@example.com" }
+
+// legacy \u2014 still works for backwards compat, but breaks on re-auth
+"connectionKey": "live::gmail::default::abc123..."
+\`\`\`
+
+The resolver runs at \`sync test\` and \`sync run\` time. Resolution errors (no connection, ambiguous tag, missing tag with multiple connections) surface as the first check in the test report, before any HTTP call.
+
+To migrate an existing profile: replace the \`connectionKey\` field with \`connection: { platform: "<platform>" }\`. Tags only needed when more than one connection exists for the platform.
+
 ## Auto-Inference
 
 \`sync init\` without \`--config\` does all of this automatically:
-- **connectionKey** \u2014 auto-resolved when there's exactly one connection for the platform
+- **connection** \u2014 defaults to \`{ platform: "<platform>" }\` (late-bound). When multiple connections exist, init surfaces the available tags so the agent can add one to the ref.
 - **Pagination** \u2014 Stripe id-pagination, Notion body-cursor, HubSpot/Google token, offset, link. Inapplicable fields stripped (no nextPath for offset, no passAs for none)
 - **resultsPath** \u2014 generic keys (data, results, items) + platform-specific (model name stripped of platform prefix: attioCompanies \u2192 companies). Use \`""\`, \`"$"\`, or \`"."\` for responses that return a bare array at the root (e.g. Hacker News \`/v0/topstories.json\`); primitive array elements are auto-wrapped as \`{ [idField]: value }\`.
 - **idField** \u2014 id, _id, uuid

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/profiles/attio/attioCompanies.json

@@ -2,7 +2,7 @@
   "description": "Attio companies — CRM company records with domains, industry, and custom attributes",
   "platform": "attio",
   "model": "attioCompanies",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "attio" },
   "actionId": "conn_mod_def::GJt0lFZ6kpk::attio-companies-list",
   "resultsPath": "companies",
   "idField": "id",

package/profiles/attio/attioPeople.json

@@ -2,7 +2,7 @@
   "description": "Attio people — CRM contact records with emails, phone numbers, and custom attributes",
   "platform": "attio",
   "model": "attioPeople",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "attio" },
   "identityKey": "primary_email_address",
   "actionId": "conn_mod_def::GJt0lFZ6kpk::attio-people-list",
   "resultsPath": "people",

package/profiles/fathom/meetings.json

@@ -2,7 +2,7 @@
   "description": "Fathom meetings — recorded meetings with transcripts, summaries, action items, and attendees",
   "platform": "fathom",
   "model": "meetings",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "fathom" },
   "actionId": "conn_mod_def::fathom::meetings-list",
   "resultsPath": "items",
   "idField": "recording_id",

package/profiles/gmail/gmailThreads.json

@@ -2,7 +2,7 @@
   "description": "Gmail email threads — primary inbox with full message bodies (no attachments)",
   "platform": "gmail",
   "model": "gmailThreads",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "gmail" },
   "actionId": "conn_mod_def::GJ3ok-Q0D40::oLWNlcx4QDORaL_18z-MsQ",
   "resultsPath": "threads",
   "idField": "id",

package/profiles/google-calendar/events.json

@@ -2,7 +2,7 @@
   "description": "Google Calendar events — meetings, appointments, and all-day events with attendees and location",
   "platform": "google-calendar",
   "model": "events",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "google-calendar" },
   "actionId": "conn_mod_def::GJ5x5pOh2TU::gcal-events-list",
   "resultsPath": "items",
   "idField": "id",

package/profiles/hacker-news/topStories.json

@@ -2,7 +2,7 @@
   "description": "Hacker News top story IDs — up to 500 item IDs at /v0/topstories.json (root-array response, primitives wrapped as { id })",
   "platform": "hacker-news",
   "model": "topStories",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "hacker-news" },
   "actionId": "conn_mod_def::GJ3108Dwmm4::avAMAq7HQtW6PT8JhPg5vA",
   "resultsPath": "",
   "idField": "id",

package/profiles/notion/search.json

@@ -2,7 +2,7 @@
   "description": "Notion pages and databases — full workspace search with titles, properties, and metadata",
   "platform": "notion",
   "model": "search",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "notion" },
   "actionId": "conn_mod_def::GJ5En67fz04::-CJAS419SVWm7L2l6brp6A",
   "resultsPath": "results",
   "idField": "id",

package/profiles/stripe/balanceTransactions.json

@@ -2,7 +2,7 @@
   "description": "Stripe balance transactions — payments, refunds, payouts, and fees with amount, currency, and status",
   "platform": "stripe",
   "model": "balanceTransactions",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "stripe" },
   "actionId": "conn_mod_def::GGx6clhYjSQ::3kEaM3HQTA2JRfW3DzXC4g",
   "resultsPath": "data",
   "idField": "id",

package/profiles/stripe/customers.json

@@ -2,7 +2,7 @@
   "description": "Stripe customers — customer records with email, name, payment methods, and subscription status",
   "platform": "stripe",
   "model": "customers",
-  "connectionKey": "AUTO",
+  "connection": { "platform": "stripe" },
   "actionId": "conn_mod_def::GGx6clhYjSQ::customers-list",
   "resultsPath": "data",
   "idField": "id",

package/skills/one/SKILL.md

@@ -175,6 +175,8 @@ one sync schedule add stripe --every 1h
 
 **Sync rejects custom actions** — profiles must use passthrough. `sync init` only surfaces passthrough models; `sync run` aborts if the list or enrich action is tagged `custom`. If no passthrough exists, compose a flow instead.
 
+**Connections are late-bound** — profiles use `"connection": { "platform": "<name>" }`, not literal `connectionKey` strings. The key is resolved at sync time, so `one add <platform>` (re-auth) doesn't break the profile. For multi-account platforms, add `"tag": "<connection-tag>"` to disambiguate. Don't hardcode connection keys in profiles.
+
 **Advanced features** (enrich, transform, exclude, identityKey, hooks, --full-refresh, --where-sql delete, cursor resume): run `one guide sync` for the full reference.
 
 ## Beyond Single Actions