@withone/cli 1.28.0 → 1.31.0

package/README.md

@@ -124,15 +124,22 @@ Set up your API key and install the MCP server into your AI agents.
 one init
 ```
 
-Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro. Installs globally by default, or per-project with `-p` so your team can share configs (each person uses their own API key).
+Supports Claude Code, Claude Desktop, Cursor, Windsurf, Codex, and Kiro.
 
-If you've already set up, `one init` shows your current status and lets you update your key, install to more agents, or reconfigure.
+**Global vs. project scope.** `one init` is interactive and asks where the setup should live:
+
+- **Global** (`~/.one/config.json`) — applies to every folder. Best when you only need one workspace / API key.
+- **Project** (`~/.one/projects/<slug>/config.json`) — scoped to the current project, stored under your home directory so secrets never land in git. Use this when different projects need different API keys, connections, or access control.
+
+When you run `one` in a project, it uses the project config if one exists and falls back to the global config otherwise. Use `one config path` to see which config is active and the full resolution order.
+
+If you've already set up, `one init` shows your current status for the active scope and lets you update your key, install to more agents, or reconfigure.
 
 | Flag | What it does |
 |------|-------------|
 | `-y` | Skip confirmations |
-| `-g` | Install globally (default) |
-| `-p` | Install for current project only |
+| `-g` | Non-interactive: write the One config globally (`~/.one/config.json`) |
+| `-p` | Non-interactive: write the One config for this project (`~/.one/projects/<slug>/config.json`) |
 
 ### `one add <platform>`
 
@@ -239,6 +246,30 @@ one actions execute stripe <actionId> <connectionKey> \
 | `--form-data` | Send as multipart/form-data |
 | `--form-url-encoded` | Send as application/x-www-form-urlencoded |
 | `--dry-run` | Show the request without executing it |
+| `--mock` | Return example response without making an API call |
+| `--skip-validation` | Skip input validation against the action schema |
+
+The CLI validates required parameters (path variables, query params, body fields) against the action schema before executing. Missing params return a clear error with the flag name and description. Pass `--skip-validation` to bypass.
+
+#### Parallel execution
+
+Execute multiple actions concurrently with `--parallel`, separating each action with `--`:
+
+```bash
+one --agent actions execute --parallel \
+  gmail send-email conn123 -d '{"to":"a@b.com","subject":"Hi","body":"Hello"}' \
+  -- slack post-message conn456 -d '{"channel":"#general","text":"Done"}' \
+  -- google-sheets append-row conn789 -d '{"values":["x","y"]}'
+```
+
+Each segment follows the same format: `<platform> <actionId> <connectionKey> [-d ...] [--path-vars ...] [--query-params ...]`. All segments are validated upfront before any execution starts. Results are collected via `Promise.allSettled` — if one fails, the rest still complete.
+
+| Option | What it does |
+|--------|-------------|
+| `--parallel` | Enable parallel mode |
+| `--max-concurrency <n>` | Max concurrent actions per batch (default: 5) |
+
+Agent-mode output includes `parallel: true`, per-action `status`/`durationMs`/`response`, plus `totalDurationMs`, `succeeded`, and `failed` counts.
 
 ### `one cache`
 
@@ -264,6 +295,48 @@ Default TTL is 1 hour. Configure via `ONE_CACHE_TTL` environment variable or `ca
 
 Note: `actions execute` is never cached — it always hits the API fresh.
 
+### `one sync`
+
+Sync platform data into local SQLite for instant queries, full-text search, scheduled refresh, and change-driven automation. The sync engine (`better-sqlite3`) is an optional dependency — install it once per machine:
+
+```bash
+one sync install && one sync doctor
+```
+
+```bash
+# Discover → init (one command: infer + auto-resolve key + auto-test) → run
+one sync models stripe
+one sync init stripe balanceTransactions    # connectionKey auto-resolved, test auto-run
+one sync run stripe --since 90d
+
+# Query, search, SQL
+one sync query stripe/balanceTransactions --where "status=available" --limit 20
+one sync search "refund"
+one sync sql stripe "SELECT count(*) FROM balanceTransactions"
+
+# Schedule unattended syncs + change hooks
+one sync schedule add stripe --every 1h
+one sync init stripe balanceTransactions --config '{"onInsert":"one flow execute handle-new-txn"}'
+
+# Deletion detection
+one sync run stripe --full-refresh
+```
+
+| Subcommand | What it does |
+|------------|-------------|
+| `install` / `doctor` | Install + verify the SQLite engine |
+| `models <platform>` | Discover available data models |
+| `init <platform> <model>` | Create profile (auto-infers all fields, auto-resolves key, auto-runs test) |
+| `test <platform>/<model>` | Validate + auto-fix profile from real API response (also runs inside init) |
+| `run <platform>` | Sync data (`--full-refresh`, `--since`, `--dry-run`) |
+| `query <platform>/<model>` | Query with `--where`, `--after/before`, `--refresh` |
+| `search <query>` | FTS5 across all synced data |
+| `sql <platform> <sql>` | Raw SELECT queries |
+| `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.
+
 ### `one guide [topic]`
 
 Get the full CLI usage guide, designed for AI agents that only have the binary (no MCP, no IDE skills).
@@ -278,7 +351,7 @@ one --agent guide         # full guide as structured JSON
 one --agent guide flows   # single topic as JSON
 ```
 
-Topics: `overview`, `actions`, `flows`, `relay`, `cache`, `all` (default).
+Topics: `overview`, `actions`, `flows`, `relay`, `cache`, `sync`, `all` (default).
 
 In agent mode (`--agent`), the JSON response includes the guide content and an `availableTopics` array so agents can discover what sections exist.
 
@@ -326,7 +399,8 @@ Press Ctrl+C during execution to pause - the run can be resumed later with `one
 |--------|-------------|
 | `-i, --input <name=value>` | Input parameter (repeatable) |
 | `--dry-run` | Validate and show execution plan without running |
-| `--mock` | With `--dry-run`: execute transforms/code with mock API responses |
+| `--mock` | With `--dry-run`: execute transforms/code with realistic mock API responses |
+| `--skip-validation` | Skip input validation against action schemas |
 | `--allow-bash` | Allow bash step execution (disabled by default for security) |
 | `-v, --verbose` | Show full request/response for each step |
 

package/dist/{chunk-AZV4EGKT.js → chunk-645Z3ARQ.js}

@@ -12,12 +12,24 @@ import { promisify } from "util";
 
 // src/lib/api.ts
 var ApiError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, retryAfterSeconds) {
     super(message);
     this.status = status;
+    this.retryAfterSeconds = retryAfterSeconds;
     this.name = "ApiError";
   }
 };
+function parseRetryAfter(value) {
+  if (!value) return void 0;
+  const seconds = parseInt(value, 10);
+  if (!isNaN(seconds)) return seconds;
+  const dateMs = Date.parse(value);
+  if (!isNaN(dateMs)) {
+    const delta = Math.ceil((dateMs - Date.now()) / 1e3);
+    return delta > 0 ? delta : 0;
+  }
+  return void 0;
+}
 var OneApi = class {
   constructor(apiKey, apiBase) {
     this.apiKey = apiKey;
@@ -92,6 +104,10 @@ var OneApi = class {
     } while (page <= totalPages);
     return allPlatforms;
   }
+  async listAvailableActions(platform, limit = 500) {
+    const response = await this.request(`/available-actions/${platform}?limit=${limit}`);
+    return response.rows || [];
+  }
   async searchActions(platform, query, agentType) {
     const isKnowledgeAgent = agentType === "knowledge";
     const queryParams = {
@@ -160,7 +176,8 @@ var OneApi = class {
     }
     if (!response.ok) {
       const text2 = await response.text();
-      throw new ApiError(response.status, text2 || `HTTP ${response.status}`);
+      const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+      throw new ApiError(response.status, text2 || `HTTP ${response.status}`, retryAfter);
     }
     const etag = response.headers.get("etag") ?? null;
     const text = await response.text();
@@ -443,6 +460,73 @@ Read the API documentation below to identify which parameters are path variables
 ${knowledge}`;
 }
 
+// src/lib/validate.ts
+var SCHEMA_GROUP_TO_FLAG = {
+  path: "--path-vars",
+  query: "--query-params",
+  body: "-d"
+};
+function validateActionInput(action, args) {
+  const inputSchema = action.ioSchema?.inputSchema;
+  if (!inputSchema?.properties) return { valid: true };
+  const argMap = {
+    path: args.pathVariables,
+    query: args.queryParams,
+    body: args.data
+  };
+  const missing = [];
+  for (const [group, flag] of Object.entries(SCHEMA_GROUP_TO_FLAG)) {
+    const groupSchema = inputSchema.properties[group];
+    if (!groupSchema?.required?.length) continue;
+    const provided = argMap[group] ?? {};
+    for (const param of groupSchema.required) {
+      if (provided[param] === void 0 || provided[param] === null || provided[param] === "") {
+        missing.push({
+          flag,
+          param,
+          description: groupSchema.properties?.[param]?.description
+        });
+      }
+    }
+  }
+  if (missing.length === 0) return { valid: true };
+  return { valid: false, missing };
+}
+
+// src/lib/dot-path.ts
+function getByDotPath(obj, dotPath) {
+  const parts = dotPath.split(".").flatMap((part) => {
+    const bracketMatch = part.match(/^([^[]+)\[(\d+)\]$/);
+    if (bracketMatch) {
+      return [bracketMatch[1], bracketMatch[2]];
+    }
+    return [part];
+  });
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === void 0) return void 0;
+    if (Array.isArray(current) && /^\d+$/.test(part)) {
+      current = current[parseInt(part, 10)];
+    } else if (typeof current === "object") {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function setByDotPath(obj, dotPath, value) {
+  const parts = dotPath.split(".");
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (current[parts[i]] === void 0 || current[parts[i]] === null) {
+      current[parts[i]] = {};
+    }
+    current = current[parts[i]];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
 // src/lib/flow-engine.ts
 var execAsync = promisify(exec);
 function sleep2(ms) {
@@ -609,30 +693,6 @@ function evaluateExpression(expr, context) {
   const fn = new Function("$", `return (${expr})`);
   return fn(context);
 }
-function getByDotPath(obj, dotPath) {
-  const parts = dotPath.split(".");
-  let current = obj;
-  for (const part of parts) {
-    if (current === null || current === void 0) return void 0;
-    if (typeof current === "object") {
-      current = current[part];
-    } else {
-      return void 0;
-    }
-  }
-  return current;
-}
-function setByDotPath(obj, dotPath, value) {
-  const parts = dotPath.split(".");
-  let current = obj;
-  for (let i = 0; i < parts.length - 1; i++) {
-    if (current[parts[i]] === void 0 || current[parts[i]] === null) {
-      current[parts[i]] = {};
-    }
-    current = current[parts[i]];
-  }
-  current[parts[parts.length - 1]] = value;
-}
 var ALLOWED_MODULES = {
   buffer: () => import("buffer"),
   crypto: () => import("crypto"),
@@ -672,7 +732,7 @@ function stripCodeFences(text) {
   const match = trimmed.match(/^```(?:\w*)\s*\n([\s\S]*?)\n\s*```\s*$/);
   return match ? match[1].trim() : trimmed;
 }
-async function executeActionStep(step, context, api, permissions, allowedActionIds) {
+async function executeActionStep(step, context, api, permissions, allowedActionIds, options) {
   const action = step.action;
   const platform = resolveValue(action.platform, context);
   const actionId = resolveValue(action.actionId, context);
@@ -688,6 +748,13 @@ async function executeActionStep(step, context, api, permissions, allowedActionI
   if (!isMethodAllowed(actionDetails.method, permissions)) {
     throw new Error(`Method "${actionDetails.method}" is not allowed under "${permissions}" permission level`);
   }
+  if (!options.skipValidation) {
+    const validation = validateActionInput(actionDetails, { data, pathVariables: pathVars, queryParams });
+    if (!validation.valid) {
+      const details = validation.missing.map((m) => `${m.flag} is missing "${m.param}"`).join("; ");
+      throw new Error(`Validation failed for step "${step.id}": ${details}. Pass --skip-validation to bypass.`);
+    }
+  }
   const result = await api.executePassthroughRequest({
     platform,
     actionId,
@@ -973,7 +1040,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-AK5W4GLF.js");
+  const { loadFlowWithMeta: loadFlowWithMeta2 } = await import("./flow-runner-HT74FKPD.js");
   const { flow: subFlow, rootDir: subRootDir } = loadFlowWithMeta2(resolvedKey);
   const subContext = await executeFlow(
     subFlow,
@@ -1033,7 +1100,7 @@ async function executePaginateStep(step, context, api, permissions, allowedActio
         type: "action",
         action: resolved
       };
-      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds);
+      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds, options);
       const response = result.response;
       const pageResults = getByDotPath(response, config.resultsField);
       if (Array.isArray(pageResults)) allResults.push(...pageResults);
@@ -1049,7 +1116,7 @@ async function executePaginateStep(step, context, api, permissions, allowedActio
         type: "action",
         action: resolvedAction
       };
-      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds);
+      const result = await executeActionStep(syntheticStep, context, api, permissions, allowedActionIds, options);
       const response = result.response;
       const pageResults = getByDotPath(response, config.resultsField);
       if (Array.isArray(pageResults)) allResults.push(...pageResults);
@@ -1204,10 +1271,32 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
       checkRequires(step, context);
       if (options.mock && (step.type === "action" || step.type === "paginate" || step.type === "bash")) {
         const resolvedConfig = step[step.type] ? resolveValue(step[step.type], context) : {};
+        let mockOutput = { _mock: true, ...resolvedConfig };
+        if (step.type === "action" && step.action) {
+          const actionId = resolveValue(step.action.actionId, context);
+          try {
+            const actionDetails = await api.getActionDetails(actionId);
+            if (!options.skipValidation) {
+              const data = step.action.data ? resolveValue(step.action.data, context) : void 0;
+              const pathVars = step.action.pathVars ? resolveValue(step.action.pathVars, context) : void 0;
+              const queryParams = step.action.queryParams ? resolveValue(step.action.queryParams, context) : void 0;
+              const validation = validateActionInput(actionDetails, { data, pathVariables: pathVars, queryParams });
+              if (!validation.valid) {
+                const details = validation.missing.map((m) => `${m.flag} is missing "${m.param}"`).join("; ");
+                throw new Error(`Validation failed for step "${step.id}": ${details}. Pass --skip-validation to bypass.`);
+              }
+            }
+            if (actionDetails.ioSchema?.ioExample?.output) {
+              mockOutput = actionDetails.ioSchema.ioExample.output;
+            }
+          } catch (e) {
+            if (e instanceof Error && e.message.startsWith("Validation failed")) throw e;
+          }
+        }
         options.onEvent?.({ event: "step:mock", stepId: step.id, type: step.type, config: resolvedConfig });
         const result2 = {
           status: "success",
-          output: { _mock: true, ...resolvedConfig },
+          output: mockOutput,
           response: { _mock: true },
           durationMs: Date.now() - startTime
         };
@@ -1217,7 +1306,7 @@ async function executeSingleStep(step, context, api, permissions, allowedActionI
       const dispatch = async () => {
         switch (step.type) {
           case "action":
-            return await executeActionStep(step, context, api, permissions, allowedActionIds);
+            return await executeActionStep(step, context, api, permissions, allowedActionIds, options);
           case "transform":
             return executeTransformStep(step, context);
           case "code":
@@ -2538,16 +2627,19 @@ function saveFlow(flow, outputPath) {
 }
 
 export {
+  ApiError,
   OneApi,
   TimeoutError,
   filterByPermissions,
   isMethodAllowed,
   isActionAllowed,
   buildActionKnowledgeWithGuidance,
+  validateActionInput,
   FLOW_SCHEMA,
   getStepTypeDescriptor,
   getNestedStepsKeys,
   generateFlowGuide,
+  getByDotPath,
   FlowRunner,
   resolveFlowPath,
   getFlowRootDir,

package/dist/{flow-runner-AK5W4GLF.js → flow-runner-HT74FKPD.js}

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