@withone/cli 1.37.3 → 1.39.0

package/README.md

@@ -330,6 +330,8 @@ one sync init stripe balanceTransactions --config '{"onInsert":"one flow execute
 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.
+
 | Subcommand | What it does |
 |------------|-------------|
 | `install` / `doctor` | Install + verify the SQLite engine |
@@ -343,7 +345,7 @@ one sync run stripe --full-refresh
 | `schedule add/list/status/remove/repair` | Cron-backed scheduled syncs with drift detection |
 | `remove <platform>` | Delete local data (`--dry-run` to preview) |
 
-Change hooks (`onInsert`, `onUpdate`, `onChange`) fire per-page during sync — pipe to a shell command, a flow, or an event log. Run `one guide sync` for the full reference.
+Change hooks (`onInsert`, `onUpdate`, `onChange`) fire per-page during sync — pipe to a shell command, a flow, or an event log. Root-array responses (e.g. Hacker News `/v0/topstories.json` → `[9129911, 9129199, ...]`) are supported by setting `resultsPath` to `""`, `"$"`, or `"."`; primitive elements are auto-wrapped as `{ [idField]: value }`. Run `one guide sync` for the full reference.
 
 ### `one guide [topic]`
 

package/dist/index.js

@@ -4666,6 +4666,9 @@ function parseActionType(actionKey) {
   if (parts.length < 5) return null;
   return parts[4];
 }
+function isCustomAction(tags) {
+  return !!tags && tags.includes("custom");
+}
 async function discoverModels(api, platform) {
   const actions2 = await api.listAvailableActions(platform);
   const listActionTypes = /* @__PURE__ */ new Set(["get_many", "list", "get_all"]);
@@ -4674,6 +4677,7 @@ async function discoverModels(api, platform) {
     const actionType = parseActionType(action.key);
     if (!actionType) continue;
     if (!listActionTypes.has(actionType)) continue;
+    if (isCustomAction(action.tags)) continue;
     const modelName = action.modelName;
     if (!modelName) continue;
     if (modelMap.has(modelName)) {
@@ -4697,7 +4701,7 @@ async function discoverModels(api, platform) {
       try {
         const searchResults = await api.searchActions(platform, model.displayName, "execute");
         const resolved = searchResults.find(
-          (a) => a.path === model.listAction.path && a.method === model.listAction.method
+          (a) => a.path === model.listAction.path && a.method === model.listAction.method && !isCustomAction(a.tags)
         );
         if (resolved?.systemId) {
           model.listAction.actionId = resolved.systemId;
@@ -4706,7 +4710,8 @@ async function discoverModels(api, platform) {
       }
     })
   );
-  return models.sort((a, b) => a.name.localeCompare(b.name));
+  const syncable = models.filter((m) => m.listAction.actionId.startsWith("conn_mod_def::"));
+  return syncable.sort((a, b) => a.name.localeCompare(b.name));
 }
 
 // src/lib/sync/profile.ts
@@ -4727,12 +4732,15 @@ function readProfile(platform, model) {
   }
 }
 function writeProfile(profile) {
-  const required = ["platform", "model", "connectionKey", "actionId", "resultsPath", "idField", "pagination"];
+  const required = ["platform", "model", "connectionKey", "actionId", "idField", "pagination"];
   for (const field of required) {
     if (!profile[field]) {
       throw new Error(`Missing required field: ${field}`);
     }
   }
+  if (profile.resultsPath === void 0) {
+    throw new Error('Missing required field: resultsPath (use "" or "$" for root-array responses)');
+  }
   if (!profile.pagination.type) {
     throw new Error("Missing required field: pagination.type");
   }
@@ -5521,6 +5529,11 @@ async function enrichPhase(api, db, config2, model, idField, connectionKey, plat
       `Enrich: could not load action ${config2.actionId}: ${err instanceof Error ? err.message : String(err)}`
     );
   }
+  if (detailAction.tags?.includes("custom")) {
+    throw new Error(
+      `Enrich does not support custom actions. Action ${config2.actionId} is tagged "custom". Use a passthrough detail endpoint \u2014 run 'one actions search ${platform} "<model> get"' to find one.`
+    );
+  }
   let concurrency = config2.concurrency ?? DEFAULT_CONCURRENCY;
   let enriched = 0;
   let skipped = 0;
@@ -5694,6 +5707,50 @@ function detectColumnType2(value) {
   return "TEXT";
 }
 
+// src/lib/sync/extract.ts
+var ROOT_PATH_TOKENS = /* @__PURE__ */ new Set(["", "$", "."]);
+function isRootPath(resultsPath) {
+  return resultsPath === void 0 || resultsPath === null || ROOT_PATH_TOKENS.has(resultsPath);
+}
+function isPrimitive(value) {
+  const t = typeof value;
+  return t === "string" || t === "number" || t === "boolean";
+}
+function describeType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function extractRecords(responseData, resultsPath, idField, profileLabel) {
+  let candidate;
+  if (isRootPath(resultsPath)) {
+    candidate = responseData;
+  } else {
+    candidate = getByDotPath(responseData, resultsPath);
+  }
+  if (!Array.isArray(candidate)) {
+    const topKeys = typeof responseData === "object" && responseData !== null && !Array.isArray(responseData) ? Object.keys(responseData).slice(0, 10) : [];
+    const pathLabel = isRootPath(resultsPath) ? "<root>" : `'${resultsPath}'`;
+    const typeLabel = describeType(responseData);
+    const keyHint = topKeys.length > 0 ? ` Top-level keys: [${topKeys.join(", ")}].` : "";
+    throw new Error(
+      `Could not find results at path ${pathLabel} for profile ${profileLabel}. Response top-level type is ${typeLabel}.${keyHint} Set resultsPath to the array field, or use "" / "$" / "." for root arrays.`
+    );
+  }
+  if (candidate.length === 0) {
+    return { records: [], wrappedPrimitives: false };
+  }
+  if (isPrimitive(candidate[0])) {
+    const wrapped = [];
+    for (const value of candidate) {
+      if (!isPrimitive(value)) continue;
+      wrapped.push({ [idField]: String(value) });
+    }
+    return { records: wrapped, wrappedPrimitives: true };
+  }
+  return { records: candidate, wrappedPrimitives: false };
+}
+
 // src/lib/sync/runner.ts
 var MAX_RETRIES_PER_PAGE = 3;
 var DEFAULT_SINCE_DAYS = 90;
@@ -5866,6 +5923,11 @@ async function syncModel(api, profile, options) {
       }
     }
     const actionDetails = await api.getActionDetails(profile.actionId);
+    if (actionDetails.tags?.includes("custom")) {
+      throw new Error(
+        `Sync does not support custom actions. Action ${profile.actionId} is tagged "custom". Use a passthrough action \u2014 run 'one actions search ${platform} "${model}"' to find one, or compose a flow that chains passthrough calls if the logic is complex.`
+      );
+    }
     const maxPages = options.maxPages ?? Infinity;
     let tableCreated = tableExists(db, model);
     let currentPageQueryParams = { ...queryParams };
@@ -5938,13 +6000,13 @@ async function syncModel(api, profile, options) {
           throw err;
         }
       }
-      const records = getByDotPath(responseData, profile.resultsPath);
-      if (!Array.isArray(records)) {
-        const topKeys = typeof responseData === "object" && responseData !== null ? Object.keys(responseData) : [];
-        throw new Error(
-          `Could not find results at path '${profile.resultsPath}' in API response. Check your sync profile. Response keys: [${topKeys.join(", ")}]`
-        );
-      }
+      const extraction = extractRecords(
+        responseData,
+        profile.resultsPath,
+        profile.idField,
+        `${platform}/${model}`
+      );
+      const records = extraction.records;
       if (records.length === 0 && page === 0) {
         if (!isAgentMode()) {
           process.stderr.write(`No records found for ${model} with the given filters.
@@ -6243,23 +6305,36 @@ async function testSyncProfile(api, profile) {
     return report;
   }
   let resolvedResultsPath = profile.resultsPath;
-  let records = getByDotPath(responseData, resolvedResultsPath);
-  if (!Array.isArray(records) && typeof responseData === "object" && responseData !== null) {
-    const topObj = responseData;
-    const arrayKey = Object.keys(topObj).find((k) => Array.isArray(topObj[k]));
-    if (arrayKey) {
-      resolvedResultsPath = arrayKey;
-      records = topObj[arrayKey];
+  const rawCandidate = isRootPath(resolvedResultsPath) ? responseData : getByDotPath(responseData, resolvedResultsPath);
+  let records = Array.isArray(rawCandidate) ? rawCandidate : null;
+  if (records === null) {
+    if (Array.isArray(responseData)) {
+      resolvedResultsPath = "";
+      records = responseData;
       report.autoFixed = report.autoFixed ?? {};
-      report.autoFixed.resultsPath = arrayKey;
+      report.autoFixed.resultsPath = "";
       checks.push({
-        name: `resultsPath auto-discovered \u2192 "${arrayKey}"`,
+        name: `resultsPath auto-discovered \u2192 <root>`,
         ok: true,
-        detail: `Profile had "${profile.resultsPath}" which didn't resolve; found "${arrayKey}" in response`
+        detail: `Response is a root-level array \u2014 profile had "${profile.resultsPath}"`
       });
+    } else if (typeof responseData === "object" && responseData !== null) {
+      const topObj = responseData;
+      const arrayKey = Object.keys(topObj).find((k) => Array.isArray(topObj[k]));
+      if (arrayKey) {
+        resolvedResultsPath = arrayKey;
+        records = topObj[arrayKey];
+        report.autoFixed = report.autoFixed ?? {};
+        report.autoFixed.resultsPath = arrayKey;
+        checks.push({
+          name: `resultsPath auto-discovered \u2192 "${arrayKey}"`,
+          ok: true,
+          detail: `Profile had "${profile.resultsPath}" which didn't resolve; found "${arrayKey}" in response`
+        });
+      }
     }
   }
-  if (!Array.isArray(records)) {
+  if (records === null) {
     const topKeys = typeof responseData === "object" && responseData !== null ? Object.keys(responseData) : [];
     checks.push({
       name: `resultsPath "${resolvedResultsPath}" \u2192 array`,
@@ -6268,10 +6343,22 @@ async function testSyncProfile(api, profile) {
     });
     return report;
   }
+  let wrappedPrimitives = false;
+  if (records.length > 0 && typeof records[0] !== "object") {
+    const idField = profile.idField || "id";
+    const wrapped = [];
+    for (const v of records) {
+      if (typeof v === "object") continue;
+      wrapped.push({ [idField]: String(v) });
+    }
+    records = wrapped;
+    wrappedPrimitives = true;
+  }
+  const pathLabel = isRootPath(resolvedResultsPath) ? "<root>" : `"${resolvedResultsPath}"`;
   checks.push({
-    name: `resultsPath "${resolvedResultsPath}" \u2192 array`,
+    name: `resultsPath ${pathLabel} \u2192 array`,
     ok: true,
-    detail: `${records.length} records`
+    detail: wrappedPrimitives ? `${records.length} primitive records (wrapped as { ${profile.idField || "id"}: value })` : `${records.length} records`
   });
   if (records.length === 0) {
     checks.push({ name: "sample record available", ok: false, detail: "empty result set" });
@@ -8510,23 +8597,29 @@ one --agent sync profiles stripe       # filter by platform
 
 When a built-in exists, \`sync init\` uses it automatically \u2014 no inference needed, no manual config. The agent just needs to match the user's intent to a profile description.
 
-## Action Resolution
+## Action Resolution \u2014 custom actions are hard-blocked
 
-Sync profiles MUST prefer passthrough actions over custom actions.
-Custom actions add server-side fan-out and transformation that causes timeouts
-and payload size failures at scale. The sync engine handles pagination, retries,
-rate limiting, and enrichment locally \u2014 a server-side middleware layer on top
-of that creates problems, not value.
+Sync refuses to run against custom/composer actions (tag \`custom\`). Both
+the list action and any enrich detail action in a profile MUST be passthrough.
+\`sync run\` loads the action's knowledge, checks for the \`custom\` tag, and
+aborts with a clear error pointing at the passthrough alternative.
 
-When resolving actions for sync profiles:
-1. Search with knowledge mode (not execute mode) to include passthrough actions
-2. Prefer GET passthrough endpoints (e.g. /gmail/v1/users/{userId}/threads)
-   over POST custom endpoints (e.g. /gmail/get-threads)
-3. Use enrich config for per-record detail fetching instead of relying on
-   custom actions that fan out server-side
-4. Only fall back to custom actions when no passthrough equivalent exists
+Why the block:
+- Custom actions run on a small shared fleet that collapses under sync-scale load
+- Custom list endpoints often expect filters in the body and silently return
+  unfiltered or empty results (sync sends params as query/path only by design)
+- The sync engine already handles pagination, retry, rate limiting, and per-record
+  enrichment locally \u2014 server-side fan-out on top of that creates 5xx, not value
 
-This applies to sync models discovery, sync init, and enrich action selection.
+How to build a profile:
+1. \`one actions search <platform> "<model>"\` surfaces passthrough actions.
+   \`sync init\`'s auto-infer also drops customs before offering choices.
+2. Prefer GET passthrough endpoints (e.g. /gmail/v1/users/{userId}/threads)
+   over POST custom endpoints (e.g. /gmail/get-threads).
+3. If no passthrough list action exists for a model, that model can't be
+   synced. Compose a flow that chains passthrough calls instead. Custom
+   actions are for one-off agent use only \u2014 never sync, never flow.
+4. The enrich \`actionId\` is held to the same rule: must be passthrough.
 
 ## Workflow: init \u2192 run \u2192 query
 
@@ -8558,7 +8651,7 @@ one --agent sync sql stripe "SELECT count(*) FROM balanceTransactions"
 \`sync init\` without \`--config\` does all of this automatically:
 - **connectionKey** \u2014 auto-resolved when there's exactly one connection for the platform
 - **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)
+- **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
 - **pathVars** \u2014 extracted from URL template with smart defaults (calendarId="primary", userId="me"). Internal keys (INTERNAL_SIGNING_KEY) and record-level IDs (record_id) are stripped automatically
 - **dateFilter** \u2014 updated_since, created_after, etc.
@@ -8723,7 +8816,7 @@ Fetches ALL records and deletes local rows whose IDs are no longer in the source
 |-------|----------|-------------|
 | connectionKey | yes | From \`one list\` |
 | actionId | yes | Auto-resolved by \`sync init\` |
-| resultsPath | yes | Auto-inferred or auto-discovered by \`sync test\` |
+| resultsPath | yes | Auto-inferred or auto-discovered by \`sync test\`. Use \`""\` / \`"$"\` / \`"."\` for root-array responses |
 | idField | yes | Auto-inferred or auto-discovered by \`sync test\` |
 | pagination | yes | Auto-inferred (cursor/token/offset/id/link/none) |
 | pathVars | no | Auto-extracted from URL template |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.37.3",
+  "version": "1.39.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [
@@ -16,7 +16,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "start": "node bin/cli.js",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test \"src/**/*.test.ts\""
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",

package/profiles/hacker-news/topStories.json

@@ -0,0 +1,11 @@
+{
+  "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",
+  "actionId": "conn_mod_def::GJ3108Dwmm4::avAMAq7HQtW6PT8JhPg5vA",
+  "resultsPath": "",
+  "idField": "id",
+  "pagination": { "type": "none" },
+  "limitParam": ""
+}

package/skills/one/SKILL.md

@@ -173,6 +173,8 @@ one --agent sync list stripe                     # progress + freshness
 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.
+
 **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