@dench.com/cli 2.2.5 → 2.2.6

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/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.6",
   "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": {