@dench.com/cli 2.2.5 → 2.2.7

package/README.md

@@ -99,9 +99,10 @@ memory only when the human asks or when saving a stable workspace fact.
 
 Tasks live as CRM `task` entries — there is no separate `dench tasks`,
 `dench task`, `dench claim`, or `dench log` command. Create one via
-`dench crm entries create task --cells '{"Name":"…","Status":"Open"}'`
+`dench crm entries create task --data '{"Name":"…","Status":"To Do"}'`
 only when the human assigns durable work or coordination benefits from
-a tracked entry. For ad-hoc requests, work directly.
+a tracked entry (confirm field names with `dench crm fields list task`
+first — unknown fields are rejected). For ad-hoc requests, work directly.
 
 Use `dench context` when you need to know who you are, which workspace you
 are using, pending approvals you requested, connected apps, and the best

package/crm.ts

@@ -289,6 +289,7 @@ async function applyBatchOpsInChunks(
   ctx: CrmCliContext,
   ops: CrmBatchOp[],
   idempotencyKey: string | undefined,
+  allowUnknown = false,
 ): Promise<number> {
   const chunks = chunkArray(ops, CRM_BATCH_CHUNK_SIZE);
   for (const [chunkIndex, chunk] of chunks.entries()) {
@@ -296,11 +297,110 @@ async function applyBatchOpsInChunks(
     await callMutation(ctx, api.batch.apply, {
       ops: chunk,
       ...(chunkKey ? { idempotencyKey: chunkKey } : {}),
+      ...(allowUnknown ? { allowUnknown: true } : {}),
     });
   }
   return chunks.length;
 }
 
+/**
+ * Fetch the canonical field names for an object. Best-effort: returns
+ * `null` (rather than throwing) on any failure so the caller falls back
+ * to the server's own unknown-field validation instead of blocking a
+ * write on a transient read error.
+ */
+async function fetchFieldNames(
+  ctx: CrmCliContext,
+  objectName: string,
+): Promise<string[] | null> {
+  try {
+    const fields = (await callQuery(ctx, api.fields.list, { objectName })) as
+      | Array<{ name?: unknown }>
+      | null
+      | undefined;
+    if (!Array.isArray(fields)) return null;
+    const names = fields
+      .map((field) => (typeof field?.name === "string" ? field.name : null))
+      .filter((name): name is string => Boolean(name));
+    return names.length > 0 ? names : null;
+  } catch {
+    return null;
+  }
+}
+
+function levenshteinDistance(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let curr = new Array<number>(b.length + 1);
+  for (let i = 1; i <= a.length; i += 1) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+function suggestKnownField(name: string, validNames: string[]): string | null {
+  const lower = name.toLowerCase();
+  const caseMatch = validNames.find((valid) => valid.toLowerCase() === lower);
+  if (caseMatch) return caseMatch;
+  let best: string | null = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const valid of validNames) {
+    const distance = levenshteinDistance(lower, valid.toLowerCase());
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = valid;
+    }
+  }
+  const threshold = Math.max(2, Math.floor(name.length / 2));
+  return best !== null && bestDistance <= threshold ? best : null;
+}
+
+/**
+ * Pre-flight check for `--data` keys against the object's real field
+ * schema, so a typo'd field name (e.g. `Name` on a `Title`-shaped task,
+ * or `Owner` instead of `Assignee`) fails fast with a "did you mean …"
+ * hint instead of silently dropping the value. The server enforces the
+ * same rule; this just gives a faster, friendlier local error. No-op
+ * when `--allow-unknown` is set or the schema can't be read.
+ */
+async function assertKnownDataKeys(
+  ctx: CrmCliContext,
+  objectName: string,
+  rows: Array<Record<string, unknown>>,
+  allowUnknown: boolean,
+): Promise<void> {
+  if (allowUnknown) return;
+  const validNames = await fetchFieldNames(ctx, objectName);
+  if (!validNames) return;
+  const validSet = new Set(validNames);
+  const unknown = new Set<string>();
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (!validSet.has(key)) unknown.add(key);
+    }
+  }
+  if (unknown.size === 0) return;
+  const parts = Array.from(unknown).map((name) => {
+    const suggestion = suggestKnownField(name, validNames);
+    return suggestion
+      ? `"${name}" (did you mean "${suggestion}"?)`
+      : `"${name}"`;
+  });
+  throw new CrmCliError(
+    `Unknown field${unknown.size > 1 ? "s" : ""} for "${objectName}": ` +
+      `${parts.join(", ")}. Valid fields: ${validNames.join(", ")}. ` +
+      `Run \`dench crm fields list ${objectName}\` to check the schema, ` +
+      `or pass --allow-unknown to write the raw value anyway.`,
+  );
+}
+
 async function callQuery(
   ctx: CrmCliContext,
   fn: Parameters<ConvexHttpClient["query"]>[0],
@@ -1209,6 +1309,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     case "create": {
       const objectName = shift(ctx.args, "object name");
       const dataRaw = getDataFlag(ctx.args);
+      const allowUnknown = hasFlag(ctx.args, "--allow-unknown");
       assertNoUnknownFlags(ctx.args, "crm entries create");
       // Refuse silent blank-row creation. The agent that triggered this
       // refactor passed `--fields` (which used to be silently dropped),
@@ -1226,9 +1327,16 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           'dench crm entries create: --data must include at least one field. Pass --data \'{"Name":"…"}\' or use cells set after creation.',
         );
       }
+      // Single-row writes rely on the server's schema validation (which
+      // returns the same "did you mean …" hint the CLI would). No local
+      // pre-fetch — that would add a round-trip to every create.
       out(
         ctx,
-        await callMutation(ctx, api.entries.create, { objectName, data }),
+        await callMutation(ctx, api.entries.create, {
+          objectName,
+          data,
+          ...(allowUnknown ? { allowUnknown: true } : {}),
+        }),
       );
       return;
     }
@@ -1236,6 +1344,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       const objectName = shift(ctx.args, "object name");
       const dataRaw = getDataFlag(ctx.args);
       const idempotencyKey = getFlag(ctx.args, "--idempotency-key");
+      const allowUnknown = hasFlag(ctx.args, "--allow-unknown");
       const rows = parseCreateManyRows(
         await readJsonArrayInput({
           args: ctx.args,
@@ -1244,6 +1353,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           inlineValue: dataRaw,
         }),
       );
+      await assertKnownDataKeys(ctx, objectName, rows, allowUnknown);
       const chunks = await applyBatchOpsInChunks(
         ctx,
         rows.map((data) => ({
@@ -1252,6 +1362,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           data,
         })),
         idempotencyKey,
+        allowUnknown,
       );
       out(ctx, { created: rows.length, chunks });
       return;
@@ -1260,6 +1371,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       const objectName = shift(ctx.args, "object name");
       const entryId = shift(ctx.args, "entry id");
       const dataRaw = getDataFlag(ctx.args);
+      const allowUnknown = hasFlag(ctx.args, "--allow-unknown");
       assertNoUnknownFlags(ctx.args, "crm entries update");
       if (dataRaw === undefined) {
         throw new CrmCliError(
@@ -1272,20 +1384,24 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           'dench crm entries update: --data must include at least one field to change. Pass --data \'{"Field":"…"}\'.',
         );
       }
+      // Single-row writes rely on the server's schema validation (same
+      // "did you mean …" hint, no extra round-trip).
       out(
         ctx,
         await callMutation(ctx, api.entries.update, {
           objectName,
           entryId: entryId as any,
           data,
+          ...(allowUnknown ? { allowUnknown: true } : {}),
         }),
       );
       return;
     }
     case "update-many": {
-      const _objectName = shift(ctx.args, "object name");
+      const objectName = shift(ctx.args, "object name");
       const updatesRaw = getUpdatesFlag(ctx.args);
       const idempotencyKey = getFlag(ctx.args, "--idempotency-key");
+      const allowUnknown = hasFlag(ctx.args, "--allow-unknown");
       const updates = parseUpdateManyRows(
         await readJsonArrayInput({
           args: ctx.args,
@@ -1294,6 +1410,12 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           inlineValue: updatesRaw,
         }),
       );
+      await assertKnownDataKeys(
+        ctx,
+        objectName,
+        updates.map((update) => update.data),
+        allowUnknown,
+      );
       const chunks = await applyBatchOpsInChunks(
         ctx,
         updates.map((update) => ({
@@ -1302,6 +1424,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           data: update.data,
         })),
         idempotencyKey,
+        allowUnknown,
       );
       out(ctx, { updated: updates.length, chunks });
       return;
@@ -2772,15 +2895,21 @@ Fields (columns):
 Entries (rows):
   dench crm entries list <object> [--limit N] [--with-meta] [--json]
   dench crm entries get <object> <entryId>
-  dench crm entries create <object> --data '{"Field":"Value",...}'    (alias: --fields)
-  dench crm entries create-many <object> --data '[{"Field":"Value",...}]' [--file rows.json] [--idempotency-key <key>]
-  dench crm entries update <object> <entryId> --data '{...}'           (alias: --fields)
-  dench crm entries update-many <object> --updates '[{"id":"...","data":{...}}]' [--file updates.json] [--idempotency-key <key>]
+  dench crm entries create <object> --data '{"Field":"Value",...}'    (alias: --fields) [--allow-unknown]
+  dench crm entries create-many <object> --data '[{"Field":"Value",...}]' [--file rows.json] [--idempotency-key <key>] [--allow-unknown]
+  dench crm entries update <object> <entryId> --data '{...}'           (alias: --fields) [--allow-unknown]
+  dench crm entries update-many <object> --updates '[{"id":"...","data":{...}}]' [--file updates.json] [--idempotency-key <key>] [--allow-unknown]
   dench crm entries delete <object> <entryId>
   dench crm entries bulk-delete <object> --ids id1,id2,id3
   Note: --data is REQUIRED on create/update and must include >=1 field.
         An empty --data '{}' is rejected — use 'crm cells set' for
         single-field tweaks instead of creating a placeholder blank row.
+        Field names are validated against the object schema: an unknown
+        field (e.g. "Name" on a task that uses "Title", or "Owner" instead
+        of "Assignee") is REJECTED with a "did you mean …" hint instead of
+        being silently dropped. Verify names with 'crm fields list <object>'
+        first. Pass --allow-unknown to write the raw value anyway, and on
+        create the object's required fields must be present.
 
 Cells (single-field updates):
   dench crm cells get <object> <entryId> <field>
@@ -2806,9 +2935,12 @@ Workspace members (for user-type fields):
       List \`{ userId, role, name, email }\` for every member of the
       current org. Use the userIds when setting \`Owner\`, \`Assignee\`,
       or any other \`user\`-type field so the UI shows a real linked
-      avatar instead of an unlinked literal-string badge:
-        dench crm cells set task --entry <id> --field Owner --value <userId>
-        dench crm entries create task --data '{"Name":"X","Owner":"<userId>"}'
+      avatar instead of an unlinked literal-string badge. Check the
+      object's actual field names first (\`crm fields list <object>\`) —
+      the \`task\` object uses \`Assignee\`, not \`Owner\`, and some
+      workspaces rename \`Name\` to \`Title\`:
+        dench crm cells set task <entryId> Assignee '"<userId>"'
+        dench crm entries create task --data '{"Name":"X","Assignee":"<userId>"}'
 
 Batch:
   dench crm batch --file ops.jsonl [--idempotency-key <key>]

package/cron.ts

@@ -33,6 +33,7 @@
  *   enable <jobId>                       Re-arm a paused cron.
  *   disable <jobId>                      Soft-pause without delete.
  *   run <jobId> [--wait]                 Manual fire; --wait blocks.
+ *   secret <jobId>                       Mint/rotate a signing secret (any type).
  *   runs <jobId> [--limit N] [--status]  Run history per trigger.
  *   history [--limit N]                  Flat history across all crons.
  *   help                                 Print this help.
@@ -196,7 +197,9 @@ export type CronScheduleSpec =
  *
  * `--at` implicitly drops `--every` / `--cron` if both are passed.
  */
-export function consumeScheduleFlags(args: string[]): CronScheduleSpec | undefined {
+export function consumeScheduleFlags(
+  args: string[],
+): CronScheduleSpec | undefined {
   const at = getFlag(args, "--at");
   if (at) {
     const ts = new Date(at).getTime();
@@ -335,10 +338,15 @@ async function runGet(ctx: CronCliContext): Promise<void> {
 }
 
 async function runCreate(ctx: CronCliContext): Promise<void> {
-  const name = shift(ctx.args, "name (positional, e.g. dench cron create \"Daily standup digest\" --prompt … --every 1d)");
+  const name = shift(
+    ctx.args,
+    'name (positional, e.g. dench cron create "Daily standup digest" --prompt … --every 1d)',
+  );
   const prompt = getFlag(ctx.args, "--prompt");
   if (!prompt || !prompt.trim()) {
-    throw new CronCliError("--prompt is required (becomes the user message of each cron-fired chat thread)");
+    throw new CronCliError(
+      "--prompt is required (becomes the user message of each cron-fired chat thread)",
+    );
   }
   const description = getFlag(ctx.args, "--description");
   const overlapPolicy = getFlag(ctx.args, "--overlap") as
@@ -346,10 +354,7 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
     | "queue"
     | "kill_old"
     | undefined;
-  if (
-    overlapPolicy &&
-    !["skip", "queue", "kill_old"].includes(overlapPolicy)
-  ) {
+  if (overlapPolicy && !["skip", "queue", "kill_old"].includes(overlapPolicy)) {
     throw new CronCliError(
       `--overlap must be one of skip|queue|kill_old (got "${overlapPolicy}")`,
     );
@@ -360,26 +365,86 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
   if (target && target !== "chat_turn") {
     throw new CronCliError(`--target must be chat_turn (got "${target}")`);
   }
-  const schedule = consumeScheduleFlags(ctx.args);
-  if (!schedule) {
+  const triggerType = (getFlag(ctx.args, "--type") ?? "schedule") as
+    | "schedule"
+    | "webhook";
+  if (triggerType !== "schedule" && triggerType !== "webhook") {
     throw new CronCliError(
-      "One of --every / --cron / --at is required. Examples:\n" +
-        "  dench cron create \"Hourly health check\" --prompt 'Check uptime…' --every 1h\n" +
-        '  dench cron create "Weekday digest" --prompt \'Pull yesterday…\' --cron "0 9 * * 1-5"\n' +
-        '  dench cron create "May 4 launch" --prompt \'Send launch tweet\' --at 2026-05-04T09:00:00Z',
+      `--type must be schedule|webhook (got "${triggerType}"). app-event / CRM automations are created from the dashboard.`,
     );
   }
-  const result = await callMutation(ctx, createCronTriggerRef, {
+  const isWebhook = triggerType === "webhook";
+
+  let schedule: CronScheduleSpec | undefined;
+  if (isWebhook) {
+    // Webhook automations fire on demand / via their signed URL — no schedule.
+    if (consumeScheduleFlags(ctx.args)) {
+      throw new CronCliError(
+        "Webhook automations don't take a schedule. Omit --every/--cron/--at.",
+      );
+    }
+  } else {
+    schedule = consumeScheduleFlags(ctx.args);
+    if (!schedule) {
+      throw new CronCliError(
+        "One of --every / --cron / --at is required for schedule automations. Examples:\n" +
+          "  dench cron create \"Hourly health check\" --prompt 'Check uptime…' --every 1h\n" +
+          '  dench cron create "Weekday digest" --prompt \'Pull yesterday…\' --cron "0 9 * * 1-5"\n' +
+          "  dench cron create \"Inbound lead\" --prompt 'Triage the lead…' --type webhook",
+      );
+    }
+  }
+  const created = (await callMutation(ctx, createCronTriggerRef, {
     name,
     prompt,
+    triggerType,
     schedule,
     description,
     overlapPolicy,
     enabled: disabled ? false : undefined,
     deleteAfterRun: deleteAfterRun ? true : undefined,
     target,
+  })) as { jobId?: string };
+
+  // Webhook automations need a signing secret to be externally callable. Mint
+  // one now (unless --no-secret) so `create` hands back a working URL+secret.
+  if (isWebhook && !hasFlag(ctx.args, "--no-secret") && created.jobId) {
+    const secret = await mintAutomationSecret(ctx, created.jobId);
+    out(ctx, { ...created, ...secret });
+    return;
+  }
+  out(ctx, created);
+}
+
+/**
+ * Mint (or rotate) a signing secret for an automation via the Next REST route
+ * (secret encryption runs in the Node route, not Convex's V8 runtime). Returns
+ * the plaintext secret + callable URL — shown once.
+ */
+async function mintAutomationSecret(
+  ctx: CronCliContext,
+  jobId: string,
+): Promise<{ webhookUrl: string | null; webhookSecret: string | null }> {
+  const url = `${getApiBase()}/api/cron/jobs/${encodeURIComponent(jobId)}/regenerate-secret`;
+  const res = (await postJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+    {},
+  )) as { webhookUrl?: string | null; webhookSecret?: string | null };
+  return {
+    webhookUrl: res.webhookUrl ?? null,
+    webhookSecret: res.webhookSecret ?? null,
+  };
+}
+
+async function runSecret(ctx: CronCliContext): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const secret = await mintAutomationSecret(ctx, jobId);
+  out(ctx, {
+    jobId,
+    ...secret,
+    note: "Secret shown once — store it now. Re-running rotates it (invalidates the old one).",
   });
-  out(ctx, result);
 }
 
 async function runUpdate(ctx: CronCliContext): Promise<void> {
@@ -458,7 +523,11 @@ async function runRunNow(ctx: CronCliContext): Promise<void> {
     })) as { entries: Array<{ ts: number; status?: string }> };
     const matching = runs.entries.find(() => true);
     if (matching && matching.status) {
-      out(ctx, { ...fired, finalStatus: matching.status, durationMs: Date.now() - start });
+      out(ctx, {
+        ...fired,
+        finalStatus: matching.status,
+        durationMs: Date.now() - start,
+      });
       return;
     }
     await new Promise((resolve) => setTimeout(resolve, 3000));
@@ -510,9 +579,10 @@ Browse:
   dench cron history [--limit 50] [--status ok|error|skipped] [--json]
   dench cron runs <jobId> [--limit 50] [--status ok|error|skipped] [--json]
 
-Create / update (one of --every / --cron / --at is required for create):
+Create / update:
   dench cron create "Daily standup digest" \\
       --prompt "Pull yesterday's commits + Slack #standup msgs and post a summary…" \\
+      --type schedule                     # default; or --type webhook (no schedule)
       --every 1d                          # or --cron "0 9 * * 1-5"  or --at 2026-05-04T09:00:00Z
       [--description "..."]               # human-readable note shown in dashboard / list
       [--overlap skip|queue|kill_old]     # default: skip
@@ -521,6 +591,10 @@ Create / update (one of --every / --cron / --at is required for create):
       [--target chat_turn]                # default: chat_turn (fires a fresh chat thread)
       [--json]
 
+  # Webhook automation (fires on demand or via a signed URL). Mints + prints a
+  # signing secret unless --no-secret. The secret is shown ONCE.
+  dench cron create "Inbound lead triage" --prompt "Triage the lead…" --type webhook
+
   dench cron update <jobId> [--name N] [--prompt P] [--description D] \\
       [--every X | --cron EXPR | --at ISO] [--enabled true|false] [--overlap …]
 
@@ -529,6 +603,7 @@ Lifecycle:
   dench cron disable <jobId>
   dench cron delete  <jobId>
   dench cron run     <jobId> [--wait] [--json]   # manual fire; --wait blocks until run finishes
+  dench cron secret  <jobId> [--json]            # mint/rotate a signing secret → callable signed URL (any automation type)
 
 Schedule formats:
   --every <duration>   Repeat every N. Accepts 30s, 5m, 2h, 1d, 12h, etc.
@@ -599,6 +674,8 @@ export async function runCronCommand(opts: {
       return await runEnable(ctx, false);
     case "run":
       return await runRunNow(ctx);
+    case "secret":
+      return await runSecret(ctx);
     case "runs":
       return await runRuns(ctx);
     case "history":

package/members.ts

@@ -181,12 +181,15 @@ Alias:
       Same surface, dispatched from inside the \`dench crm\` namespace
       since the canonical use case is assigning CRM \`user\` fields.
 
-After picking a userId:
-  dench crm cells set task --entry <entryId> --field Owner --value <userId>
-  dench crm entries create task --data '{"Name":"Ship CRM","Owner":"<userId>"}'
+After picking a userId (confirm field names with
+\`dench crm fields list <object>\` — the default \`task\` uses
+\`Assignee\`, not \`Owner\`, and some workspaces rename \`Name\` to \`Title\`):
+  dench crm cells set task <entryId> Assignee '"<userId>"'
+  dench crm entries create task --data '{"Name":"Ship CRM","Assignee":"<userId>"}'
 
 The server best-effort-resolves a name / email passed to a \`user\`
 field when the match against the roster is unique, but the explicit
-lookup via \`dench members list\` is the correct pattern.
+lookup via \`dench members list\` is the correct pattern. Unknown field
+names are rejected on write (pass --allow-unknown to bypass).
 `);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "description": "Dench agent workspace CLI. v2 unifies auth behind `dench signin`; the legacy `dench login` / `dench onboard` / `dench setup` / `dench what-can-i-do` / `dench register` commands now error with a redirect.",
   "type": "module",
   "bin": {