@dench.com/cli 2.8.3 → 2.8.5-staging.175

package/crm.ts

@@ -35,7 +35,9 @@ import {
   getFlag,
   getFlagWithAliases,
   hasFlag,
+  type ParsedLimit,
   parseJson as parseJsonRaw,
+  parseLimit as parseLimitRaw,
   shift as shiftRaw,
 } from "./lib/cli-args";
 import {
@@ -57,6 +59,7 @@ import {
   enrichCompany,
   enrichPerson,
 } from "./lib/enrichment-gateway";
+import { closestMatch, levenshteinDistance } from "./lib/levenshtein";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -175,9 +178,18 @@ function withCrmEntryDeepLinks(
     objectName,
     entryId,
   });
+  const record = value as JsonRecord;
   return {
-    ...(value as JsonRecord),
+    ...record,
+    // Alias `id` ↔ `entryId`: server responses expose `entryId`, but
+    // agents overwhelmingly `jq .id` (the shape `entries list` returns).
+    // A null there caused retry-loops that created duplicate rows.
+    ...(typeof record.id === "string" && record.id.trim()
+      ? {}
+      : { id: entryId }),
     href: links.href,
+    // `url` stays conditional on host+workspaceSlug being known — an
+    // absolute link with a guessed origin is worse than none.
     ...(links.url ? { url: links.url } : {}),
   };
 }
@@ -221,6 +233,71 @@ function shift(args: string[], expected: string): string {
   }
 }
 
+/**
+ * shift() for name-bearing positionals (object/field/group names). A
+ * value starting with `--` is always a mis-ordered flag, never a real
+ * name — `dench crm fields create lead --name "Fit Score"` used to
+ * create a literal field named "--name" in production CRMs. Fail fast
+ * with the correct usage instead of writing the flag as data.
+ */
+function shiftName(args: string[], expected: string, usage: string): string {
+  const value = shift(args, expected);
+  if (value.startsWith("--")) {
+    const label = expected.charAt(0).toUpperCase() + expected.slice(1);
+    throw new CrmCliError(
+      `${label} cannot start with "--". The name is positional: ${usage}`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Parse `--limit` against a server-side cap and make any clamping LOUD.
+ * The server clamps silently, which historically let agents dedupe /
+ * count over a subset believing it was the full dataset. The warning
+ * always goes to stderr so `--json` stdout stays valid JSON; callers
+ * whose output is a JSON object should also surface `limitClamped`.
+ */
+function resolveLimitFlag(
+  args: string[],
+  opts: {
+    defaultValue: number;
+    cap: number;
+    command: string;
+    fullDatasetHint?: string;
+  },
+): ParsedLimit {
+  const raw = getFlag(args, "--limit");
+  let parsed: ParsedLimit;
+  try {
+    parsed = parseLimitRaw(raw, opts);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    throw error;
+  }
+  if (parsed.clamped) {
+    process.stderr.write(
+      `warning: --limit ${parsed.requested} exceeds the ${opts.cap}-row cap for ` +
+        `${opts.command}; returned rows are the newest ${parsed.effective}. ` +
+        `${opts.fullDatasetHint ?? "Use 'dench crm export' for full datasets."}\n`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Reject curl-style `--data @rows.json`. The CLI never reads files off
+ * an `@` prefix — the literal string "@rows.json" would be parsed as
+ * (invalid) JSON, or worse, silently written as a value.
+ */
+function rejectAtFileValue(raw: string | undefined, flag: string): void {
+  if (raw !== undefined && raw.trimStart().startsWith("@")) {
+    throw new CrmCliError(
+      `${flag}: "@file" syntax is not supported. Use --file <path>.`,
+    );
+  }
+}
+
 function parseJson(value: string | undefined): unknown {
   try {
     return parseJsonRaw(value);
@@ -281,6 +358,7 @@ async function readJsonArrayInput(opts: {
       `${opts.command} requires ${opts.inlineFlag} '<json-array>' or --file <path>`,
     );
   }
+  rejectAtFileValue(opts.inlineValue, opts.inlineFlag);
 
   let raw: string;
   if (filePath) {
@@ -306,6 +384,71 @@ function parseCreateManyRows(items: unknown[]): JsonRecord[] {
   );
 }
 
+/**
+ * Stable per-row dedupe key derived from a named column. Values are
+ * normalized (String → trim → lowercase) so `" Jane@X.com"` and
+ * `"jane@x.com"` collapse onto the same key. Throws when a row has no
+ * usable value — a blank dedupe cell would silently merge unrelated rows.
+ */
+function dedupeKeyFromColumn(opts: {
+  prefix: string;
+  column: string;
+  row: JsonRecord;
+  rowIndex: number; // 0-based
+  command: string;
+}): string {
+  const raw = opts.row[opts.column];
+  const normalized =
+    raw === null || raw === undefined ? "" : String(raw).trim().toLowerCase();
+  if (!normalized) {
+    throw new CrmCliError(
+      `${opts.command}: row ${opts.rowIndex + 1} has no value for --dedupe-key column "${opts.column}"`,
+    );
+  }
+  return `${opts.prefix}:${normalized}`;
+}
+
+/**
+ * Deterministic JSON stringification (recursively sorted object keys).
+ * Used to derive content-hash dedupe keys for `crm import`: the same
+ * source row must map to the same key on every run — the previous
+ * implementation keyed on `Date.now()`, which made every re-run of an
+ * import duplicate all rows (a 42-row CSV became 84 rows).
+ */
+export function stableJsonStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJsonStringify).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const record = value as JsonRecord;
+    const entries = Object.keys(record)
+      .sort()
+      .map(
+        (key) => `${JSON.stringify(key)}:${stableJsonStringify(record[key])}`,
+      );
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+/** Count batch.apply result statuses (created / already_existed / updated). */
+function countResultStatuses(results: unknown[]): {
+  created: number;
+  alreadyExisted: number;
+  updated: number;
+} {
+  let created = 0;
+  let alreadyExisted = 0;
+  let updated = 0;
+  for (const result of results) {
+    const status = isJsonRecord(result) ? result.status : undefined;
+    if (status === "already_existed") alreadyExisted += 1;
+    else if (status === "updated") updated += 1;
+    else created += 1;
+  }
+  return { created, alreadyExisted, updated };
+}
+
 function parseUpdateManyRows(items: unknown[]): Array<{
   id: string;
   data: JsonRecord;
@@ -356,9 +499,29 @@ function parseCellSetManyRows(items: unknown[]): Array<{
 }
 
 type CrmBatchOp =
-  | { type: "entries.create"; objectName: string; data: JsonRecord }
+  | {
+      type: "entries.create";
+      objectName: string;
+      data: JsonRecord;
+      /** Stable per-row dedupe key (server upserts on conflict). */
+      seedKey?: string;
+      /** 1-based source row for server-side error messages. */
+      rowIndex?: number;
+    }
   | { type: "entries.update"; entryId: string; data: JsonRecord };
 
+type CrmOnConflictPolicy = "skip" | "update" | "error";
+
+function parseOnConflictFlag(raw: string | undefined): CrmOnConflictPolicy {
+  const value = raw ?? "skip";
+  if (value === "skip" || value === "update" || value === "error") {
+    return value;
+  }
+  throw new CrmCliError(
+    `--on-conflict must be skip, update, or error (got "${raw}")`,
+  );
+}
+
 function chunkArray<T>(items: T[], size: number): T[][] {
   const chunks: T[][] = [];
   for (let index = 0; index < items.length; index += size) {
@@ -381,6 +544,7 @@ async function applyBatchOpsInChunks(
   ops: CrmBatchOp[],
   idempotencyKey: string | undefined,
   allowUnknown = false,
+  onConflict?: CrmOnConflictPolicy,
 ): Promise<{ chunks: number; results: unknown[] }> {
   const chunks = chunkArray(ops, CRM_BATCH_CHUNK_SIZE);
   const results: unknown[] = [];
@@ -391,6 +555,7 @@ async function applyBatchOpsInChunks(
       ...runContextArgs(ctx),
       ...(chunkKey ? { idempotencyKey: chunkKey } : {}),
       ...(allowUnknown ? { allowUnknown: true } : {}),
+      ...(onConflict ? { onConflict } : {}),
     })) as { results?: unknown[] } | null | undefined;
     if (Array.isArray(batchResult?.results)) {
       results.push(...batchResult.results);
@@ -428,22 +593,8 @@ async function fetchFieldNames(
   }
 }
 
-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];
-}
+// levenshteinDistance now lives in cli/lib/levenshtein.ts (shared with
+// the `dench apps` dispatcher's "did you mean" suggestions).
 
 function suggestKnownField(name: string, validNames: string[]): string | null {
   const lower = name.toLowerCase();
@@ -719,6 +870,7 @@ const api = {
   },
   entries: {
     list: makeFunctionReference<"query">("functions/crm/entries:list"),
+    listPage: makeFunctionReference<"query">("functions/crm/entries:listPage"),
     get: makeFunctionReference<"query">("functions/crm/entries:get"),
     create: makeFunctionReference<"mutation">("functions/crm/entries:create"),
     update: makeFunctionReference<"mutation">("functions/crm/entries:update"),
@@ -874,11 +1026,48 @@ export async function runCrmCommand(opts: {
       // on. Delegates to the shared implementation in cli/members.ts
       // so payload formatting + flag handling stay in lockstep.
       return await runCrmMembersCommand(ctx);
-    default:
-      throw new CrmCliError(`Unknown crm subcommand: ${subcommand}`);
+    default: {
+      const suggestion = closestMatch(subcommand, CRM_SUBCOMMANDS);
+      throw new CrmCliError(
+        `Unknown crm subcommand: ${subcommand}` +
+          `${suggestion ? `. Did you mean "${suggestion}"?` : ""}` +
+          " Run `dench crm help` for the full list.",
+      );
+    }
   }
 }
 
+/** Every verb the `runCrmCommand` switch accepts (for "did you mean"). */
+const CRM_SUBCOMMANDS = [
+  "objects",
+  "views",
+  "sidebar",
+  "fields",
+  "entries",
+  "history",
+  "cells",
+  "query",
+  "sql",
+  "aggregate",
+  "search",
+  "statuses",
+  "batch",
+  "import",
+  "export",
+  "transaction",
+  "people",
+  "companies",
+  "enrich",
+  "reports",
+  "docs",
+  "documents",
+  "actions",
+  "automations",
+  "templates",
+  "members",
+  "help",
+] as const;
+
 /**
  * `dench crm automations …` — deterministic CRM rules (installed by
  * templates, e.g. "qualified prospect → opportunity"). These fire inside
@@ -1026,7 +1215,11 @@ async function runSidebarCommand(ctx: CrmCliContext): Promise<void> {
       const groupVerb = ctx.args.shift();
       switch (groupVerb) {
         case "create": {
-          const name = shift(ctx.args, "group name");
+          const name = shiftName(
+            ctx.args,
+            "group name",
+            'dench crm sidebar group create "<name>"',
+          );
           assertNoUnknownFlags(ctx.args, "crm sidebar group create");
           out(ctx, await callMutation(ctx, api.sidebar.createGroup, { name }));
           return;
@@ -1105,7 +1298,11 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
       return;
     }
     case "create": {
-      const name = shift(ctx.args, "object name");
+      const name = shiftName(
+        ctx.args,
+        "object name",
+        'dench crm objects create "<name>" [--description …] [--icon …]',
+      );
       const description = getFlag(ctx.args, "--description");
       const defaultView = getFlag(ctx.args, "--default-view") as any;
       const icon = getFlag(ctx.args, "--icon");
@@ -1147,7 +1344,11 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "rename": {
       const from = shift(ctx.args, "current name");
-      const to = shift(ctx.args, "new name");
+      const to = shiftName(
+        ctx.args,
+        "new name",
+        'dench crm objects rename <from> "<to>"',
+      );
       assertNoUnknownFlags(ctx.args, "crm objects rename");
       out(ctx, await callMutation(ctx, api.objects.rename, { from, to }));
       return;
@@ -1630,7 +1831,13 @@ async function runViewsCommand(ctx: CrmCliContext): Promise<void> {
     case "rename": {
       const objectName = shift(ctx.args, "object name");
       const viewName = shift(ctx.args, "view name");
-      const newName = getFlag(ctx.args, "--to") ?? shift(ctx.args, "new name");
+      const newName =
+        getFlag(ctx.args, "--to") ??
+        shiftName(
+          ctx.args,
+          "new name",
+          'dench crm views rename <object> "<view>" "<new name>"',
+        );
       assertNoUnknownFlags(ctx.args, "crm views rename");
       if (!newName.trim()) {
         throw new CrmCliError(
@@ -1709,7 +1916,11 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "create": {
       const objectName = shift(ctx.args, "object name");
-      const name = shift(ctx.args, "field name");
+      const name = shiftName(
+        ctx.args,
+        "field name",
+        'dench crm fields create <object> "<Name>" --type <type>',
+      );
       const type = (getFlag(ctx.args, "--type") ?? "text") as any;
       const required = hasFlag(ctx.args, "--required");
       const description = getFlag(ctx.args, "--description");
@@ -1919,14 +2130,20 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
   switch (verb) {
     case "list": {
       const objectName = shift(ctx.args, "object name");
-      const limit = parseInt(getFlag(ctx.args, "--limit") ?? "100", 10);
+      const limit = resolveLimitFlag(ctx.args, {
+        defaultValue: 100,
+        cap: 1000,
+        command: "crm entries list",
+      });
       const withMeta = hasFlag(ctx.args, "--with-meta");
       assertNoUnknownFlags(ctx.args, "crm entries list");
       const entries = await callQuery(ctx, api.entries.list, {
         objectName,
-        limit,
+        limit: limit.effective,
       });
       if (!withMeta) {
+        // Bare-array output: the clamp warning already went to stderr
+        // (stdout must stay a valid JSON array in --json mode).
         out(ctx, entries);
         return;
       }
@@ -1942,7 +2159,15 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         objectName,
         totalCount,
         returnedCount,
-        limit,
+        limit: limit.effective,
+        ...(limit.clamped
+          ? {
+              limitClamped: {
+                requested: limit.requested,
+                effective: limit.effective,
+              },
+            }
+          : {}),
         hasMore: totalCount > returnedCount,
         entries,
       });
@@ -1968,6 +2193,11 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     case "create": {
       const objectName = shift(ctx.args, "object name");
       const dataRaw = getDataFlag(ctx.args);
+      // Optional idempotency: the server upserts on (object, key), so a
+      // retried create (agent saw a null `.id`, ran the command again)
+      // returns the existing row with `alreadyExisted: true` instead of
+      // duplicating it.
+      const idempotencyKey = getFlag(ctx.args, "--idempotency-key");
       const allowUnknown = hasFlag(ctx.args, "--allow-unknown");
       assertNoUnknownFlags(ctx.args, "crm entries create");
       // Refuse silent blank-row creation. The agent that triggered this
@@ -1980,12 +2210,18 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           'dench crm entries create requires --data \'{"Field":"Value",...}\' (alias: --fields)',
         );
       }
+      rejectAtFileValue(dataRaw, "--data");
       const data = (parseJson(dataRaw) as JsonRecord | undefined) ?? {};
       if (!data || Object.keys(data).length === 0) {
         throw new CrmCliError(
           'dench crm entries create: --data must include at least one field. Pass --data \'{"Name":"…"}\' or use cells set after creation.',
         );
       }
+      if (idempotencyKey !== undefined && !idempotencyKey.trim()) {
+        throw new CrmCliError(
+          "dench crm entries create: --idempotency-key must be a non-empty string",
+        );
+      }
       // 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.
@@ -1999,6 +2235,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
             data,
             ...runContextArgs(ctx),
             ...(allowUnknown ? { allowUnknown: true } : {}),
+            ...(idempotencyKey ? { seedKey: idempotencyKey.trim() } : {}),
           }),
         ),
       );
@@ -2008,6 +2245,10 @@ 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");
+      // Per-row idempotency: derive a stable seedKey from this column so
+      // re-running the same create-many cannot duplicate rows. Rows whose
+      // key already exists are skipped (`status: "already_existed"`).
+      const dedupeColumn = getFlag(ctx.args, "--dedupe-key");
       const allowUnknown = hasFlag(ctx.args, "--allow-unknown");
       const rows = parseCreateManyRows(
         await readJsonArrayInput({
@@ -2018,23 +2259,43 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         }),
       );
       await assertKnownDataKeys(ctx, objectName, rows, allowUnknown);
+      const seedKeys = dedupeColumn
+        ? rows.map((row, index) =>
+            dedupeKeyFromColumn({
+              prefix: `many:${objectName}:${dedupeColumn}`,
+              column: dedupeColumn,
+              row,
+              rowIndex: index,
+              command: "crm entries create-many",
+            }),
+          )
+        : null;
       const { chunks, results } = await applyBatchOpsInChunks(
         ctx,
-        rows.map((data) => ({
+        rows.map((data, index) => ({
           type: "entries.create",
           objectName,
           data,
+          ...(seedKeys
+            ? { seedKey: seedKeys[index], rowIndex: index + 1 }
+            : {}),
         })),
         idempotencyKey,
         allowUnknown,
+        seedKeys ? "skip" : undefined,
       );
       // Only claim per-row links when we actually got a result per row. A
       // silently-empty `results` is indistinguishable from "this object has
       // no links" and sends the agent right back to inventing URLs — the
       // exact failure this command's `url`/`href` output exists to prevent.
       const linked = results.length;
+      const statusCounts =
+        seedKeys && results.length > 0 ? countResultStatuses(results) : null;
       out(ctx, {
-        created: rows.length,
+        created: statusCounts ? statusCounts.created : rows.length,
+        ...(statusCounts
+          ? { alreadyExisted: statusCounts.alreadyExisted }
+          : {}),
         chunks,
         ...(linked > 0
           ? {
@@ -2076,6 +2337,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
           'dench crm entries update requires --data \'{"Field":"Value",...}\' (alias: --fields)',
         );
       }
+      rejectAtFileValue(dataRaw, "--data");
       const data = (parseJson(dataRaw) as JsonRecord | undefined) ?? {};
       if (!data || Object.keys(data).length === 0) {
         throw new CrmCliError(
@@ -2144,17 +2406,36 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
     }
     case "bulk-delete":
     case "bulkDelete": {
-      const _objectName = shift(ctx.args, "object name");
+      const objectName = shift(ctx.args, "object name");
       const idsCsv = getFlag(ctx.args, "--ids") ?? "";
       assertNoUnknownFlags(ctx.args, "crm entries bulk-delete");
-      const entryIds = idsCsv.split(",").filter(Boolean);
-      out(
+      const entryIds = idsCsv
+        .split(",")
+        .map((id) => id.trim())
+        .filter(Boolean);
+      if (entryIds.length === 0) {
+        throw new CrmCliError(
+          "dench crm entries bulk-delete requires --ids id1,id2,…",
+        );
+      }
+      // Automatic undo file: snapshot the target rows to JSONL BEFORE
+      // deleting. A bulk-delete driven by a buggy dedupe script is only
+      // recoverable if the pre-delete state exists somewhere — this file
+      // is that somewhere. Snapshot failure aborts the delete.
+      const snapshot = await snapshotEntriesBeforeBulkDelete(
         ctx,
-        await callMutation(ctx, api.entries.bulkDelete, {
-          entryIds: entryIds as any,
-          ...runContextArgs(ctx),
-        }),
+        objectName,
+        entryIds,
       );
+      const result = await callMutation(ctx, api.entries.bulkDelete, {
+        entryIds: entryIds as any,
+        ...runContextArgs(ctx),
+      });
+      out(ctx, {
+        ...(isJsonRecord(result) ? result : { result }),
+        snapshotPath: snapshot.path,
+        snapshotRows: snapshot.rows,
+      });
       return;
     }
     default:
@@ -2162,6 +2443,56 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
   }
 }
 
+/**
+ * Fetch every target row and write it to a JSONL snapshot under the OS
+ * temp dir ($TMPDIR or /tmp). This is an automatic undo file, not an
+ * interactive gate: the delete proceeds after a successful snapshot and
+ * ABORTS if the snapshot cannot be captured or written.
+ */
+async function snapshotEntriesBeforeBulkDelete(
+  ctx: CrmCliContext,
+  objectName: string,
+  entryIds: string[],
+): Promise<{ path: string; rows: number }> {
+  const lines: string[] = [];
+  try {
+    for (const entryId of entryIds) {
+      const entry = await callQuery(ctx, api.entries.get, {
+        objectName,
+        entryId: entryId as any,
+      });
+      lines.push(JSON.stringify(entry));
+    }
+  } catch (error) {
+    throw new CrmCliError(
+      "bulk-delete aborted: could not snapshot the target rows before " +
+        `deleting (${error instanceof Error ? error.message : String(error)}). ` +
+        "No entries were deleted.",
+    );
+  }
+  const os = await import("node:os");
+  const path = await import("node:path");
+  const fs = await import("node:fs/promises");
+  const snapshotPath = path.join(
+    os.tmpdir(),
+    `dench-bulk-delete-${objectName.replace(/[^A-Za-z0-9._-]+/g, "_")}-${Date.now()}.jsonl`,
+  );
+  try {
+    await fs.writeFile(
+      snapshotPath,
+      lines.length > 0 ? `${lines.join("\n")}\n` : "",
+      "utf-8",
+    );
+  } catch (error) {
+    throw new CrmCliError(
+      `bulk-delete aborted: failed to write snapshot file ${snapshotPath} ` +
+        `(${error instanceof Error ? error.message : String(error)}). ` +
+        "No entries were deleted.",
+    );
+  }
+  return { path: snapshotPath, rows: lines.length };
+}
+
 async function runHistoryCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = shift(ctx.args, "object name");
   const entryId = shift(ctx.args, "entry id");
@@ -2280,12 +2611,19 @@ async function runQueryCommand(ctx: CrmCliContext): Promise<void> {
     | undefined;
   const select = getFlag(ctx.args, "--select")?.split(",").filter(Boolean);
   const sort = getFlag(ctx.args, "--sort");
-  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "100", 10);
+  // The server clamps at 1000 silently; surface the clamp on stderr so
+  // callers never mistake a truncated page for the full dataset. Output
+  // here is a bare JSON array, so stderr is the only safe channel.
+  const limit = resolveLimitFlag(ctx.args, {
+    defaultValue: 100,
+    cap: 1000,
+    command: "crm query",
+  });
   assertNoUnknownFlags(ctx.args, "crm query");
   // Convex's wire serializer rejects $-prefixed object keys, so we
   // route the DSL through the dslJson string field whenever the filter
   // has any operator-shaped clause.
-  const dsl = { filter, select, sort, limit };
+  const dsl = { filter, select, sort, limit: limit.effective };
   const hasDollarKey = filter ? containsDollarKey(filter) : false;
   out(
     ctx,
@@ -2324,14 +2662,27 @@ async function runAggregateCommand(ctx: CrmCliContext): Promise<void> {
 
 async function runSearchCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = getFlag(ctx.args, "--object");
-  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "50", 10);
+  // Search caps at 100 server-side. Warn on stderr when clamped (the
+  // output is a bare JSON array, so stdout must stay untouched).
+  const limit = resolveLimitFlag(ctx.args, {
+    defaultValue: 50,
+    cap: 100,
+    command: "crm search",
+  });
   // Drain known flags before joining the rest into the search text so a
   // typo like `--objct` surfaces instead of being concatenated into the
   // query string.
   assertNoUnknownFlags(ctx.args, "crm search");
   const text = ctx.args.join(" ").trim();
   if (!text) throw new CrmCliError("Search text required");
-  out(ctx, await callQuery(ctx, api.query.search, { text, objectName, limit }));
+  out(
+    ctx,
+    await callQuery(ctx, api.query.search, {
+      text,
+      objectName,
+      limit: limit.effective,
+    }),
+  );
 }
 
 async function runStatusesCommand(ctx: CrmCliContext): Promise<void> {
@@ -2681,15 +3032,44 @@ async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
 
 // ── Import / export ──────────────────────────────────────────────────────
 
+/**
+ * Compute the stable per-row dedupe key for `crm import`.
+ *
+ * Default: content hash — `import:<object>:<sha256(stable JSON of row)>`.
+ * With `--dedupe-key <column>`: `import:<object>:<column>:<normalized
+ * value>` (trim + lowercase).
+ *
+ * Both are deterministic across runs — re-running the same import file
+ * hits the same keys and the server's on-conflict policy applies instead
+ * of duplicating every row (the old key embedded `Date.now()`, which
+ * turned a re-run of a 42-row CSV into 84 rows).
+ */
+export function importSeedKeyForRow(opts: {
+  objectName: string;
+  row: Record<string, unknown>;
+  rowIndex: number; // 0-based
+  dedupeColumn?: string;
+  sha256: (input: string) => string;
+}): string {
+  if (opts.dedupeColumn) {
+    return dedupeKeyFromColumn({
+      prefix: `import:${opts.objectName}:${opts.dedupeColumn}`,
+      column: opts.dedupeColumn,
+      row: opts.row,
+      rowIndex: opts.rowIndex,
+      command: "crm import",
+    });
+  }
+  return `import:${opts.objectName}:${opts.sha256(stableJsonStringify(opts.row))}`;
+}
+
 async function runImportCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = shift(ctx.args, "object name");
   const csvPath = getFlag(ctx.args, "--csv");
   const jsonlPath = getFlag(ctx.args, "--jsonl");
   const mapJson = getFlag(ctx.args, "--map");
-  const onConflict = (getFlag(ctx.args, "--on-conflict") ?? "skip") as
-    | "skip"
-    | "update"
-    | "error";
+  const dedupeColumn = getFlag(ctx.args, "--dedupe-key");
+  const onConflict = parseOnConflictFlag(getFlag(ctx.args, "--on-conflict"));
   assertNoUnknownFlags(ctx.args, "crm import");
   if (!csvPath && !jsonlPath) {
     throw new CrmCliError(
@@ -2712,41 +3092,98 @@ async function runImportCommand(ctx: CrmCliContext): Promise<void> {
       rows.push(remapKeys(parsed, colMap));
     }
   }
-  // Chunk into 100-op batches and call batch.apply repeatedly.
-  let imported = 0;
-  for (let i = 0; i < rows.length; i += 100) {
-    const chunk = rows.slice(i, i + 100);
-    const ops = chunk.map((data) => ({
-      type: "entries.create" as const,
+  const { createHash } = await import("node:crypto");
+  const sha256 = (input: string) =>
+    createHash("sha256").update(input).digest("hex");
+  const ops: CrmBatchOp[] = rows.map((data, index) => ({
+    type: "entries.create",
+    objectName,
+    data,
+    seedKey: importSeedKeyForRow({
       objectName,
-      data,
-    }));
-    const result = (await callMutation(ctx, api.batch.apply, {
-      ops: ops as any,
-      idempotencyKey: `import:${objectName}:${Date.now()}:${i}`,
-    } as any)) as { count: number };
-    imported += result.count;
-  }
-  out(ctx, { imported, onConflict });
+      row: data,
+      rowIndex: index,
+      dedupeColumn,
+      sha256,
+    }),
+    rowIndex: index + 1,
+  }));
+  // batch.apply enforces the on-conflict policy per row against the
+  // (objectId, seedKey) index; chunking is handled by the shared helper.
+  const { results } = await applyBatchOpsInChunks(
+    ctx,
+    ops,
+    undefined,
+    false,
+    onConflict,
+  );
+  const counts = countResultStatuses(results);
+  out(ctx, {
+    objectName,
+    sourceRowsParsed: rows.length,
+    imported: counts.created,
+    skipped: counts.alreadyExisted,
+    updated: counts.updated,
+    errors: 0,
+    onConflict,
+    ...(dedupeColumn ? { dedupeKey: dedupeColumn } : {}),
+  });
 }
 
 async function runExportCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = shift(ctx.args, "object name");
   const format = (getFlag(ctx.args, "--format") ?? "jsonl") as "csv" | "jsonl";
-  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "10000", 10);
+  const limit = resolveLimitFlag(ctx.args, {
+    defaultValue: 10000,
+    cap: Number.MAX_SAFE_INTEGER,
+    command: "crm export",
+  }).effective;
   assertNoUnknownFlags(ctx.args, "crm export");
-  // Page through entries.list in 1000-row chunks.
+  // Page through entries.listPage in 1000-row chunks using a real
+  // creation-time cursor. The previous loop called `entries.list` with
+  // no cursor at all, so every iteration re-fetched the newest 1000 rows
+  // — a 10,000-row export was the same 1,000 rows ten times, and the
+  // dedupe script that consumed it deleted ~8,000 real accounts.
   const all: any[] = [];
-  let cursor = 0;
+  let cursor: string | null = null;
   while (all.length < limit) {
-    const page = (await callQuery(ctx, api.entries.list, {
+    const result = (await callQuery(ctx, api.entries.listPage, {
       objectName,
       limit: Math.min(1000, limit - all.length),
-    })) as any[];
-    if (!page || page.length === 0) break;
+      ...(cursor !== null ? { cursor } : {}),
+    })) as {
+      page?: unknown[];
+      isDone?: boolean;
+      continueCursor?: string | null;
+      truncated?: boolean;
+    } | null;
+    const page = Array.isArray(result?.page) ? result.page : [];
     all.push(...page);
-    cursor += page.length;
-    if (page.length < 1000) break;
+    if (result?.truncated) {
+      process.stderr.write(
+        `warning: crm export of "${objectName}" is capped at ${page.length} rows ` +
+          "(personal objects load single-shot); the export may be incomplete.\n",
+      );
+    }
+    if (!result || result.isDone !== false) break;
+    const next = result.continueCursor ?? null;
+    if (!next || next === cursor) break; // defensive: never loop in place
+    cursor = next;
+  }
+  // Invariant guard: one export must never contain the same entry twice.
+  // Duplicates mean pagination is broken and the file is unsafe to feed
+  // into any dedupe/migration script — fail hard rather than emit it.
+  const ids = all.map((entry) => String(entry?.id ?? ""));
+  const uniqueIds = new Set(ids).size;
+  if (uniqueIds !== all.length) {
+    process.stderr.write(
+      `error: crm export produced duplicate rows (${all.length} rows, ` +
+        `${uniqueIds} unique entry ids). Pagination invariant violated — ` +
+        "no output was written.\n",
+    );
+    throw new CrmCliError(
+      `crm export: duplicate entry ids detected (${all.length} rows, ${uniqueIds} unique). Export aborted.`,
+    );
   }
   if (format === "csv") {
     const fields = Object.keys(all[0]?.fields ?? {});
@@ -2766,21 +3203,34 @@ async function runExportCommand(ctx: CrmCliContext): Promise<void> {
       );
     }
   }
+  // Verification trailer (stderr — stdout is the data stream): row count
+  // and unique-id count so callers can assert integrity in scripts.
+  process.stderr.write(
+    `crm export ${objectName}: exportedCount=${all.length} uniqueIds=${uniqueIds}\n`,
+  );
 }
 
 export function parseCsv(
   text: string,
   colMap: Record<string, string>,
 ): Record<string, unknown>[] {
-  // Tiny CSV parser: comma separator, double-quote escaping. Doesn't
-  // handle multi-line quoted cells (rare for CRM imports). Callers with
-  // pathological CSVs should pre-clean via `csvkit` or similar.
+  // Full-stream CSV parser: comma separator, double-quote escaping,
+  // QUOTED CELLS SPANNING MULTIPLE LINES, and CRLF endings. The previous
+  // implementation split on newlines before parsing quotes, so any CSV
+  // with a multiline Notes cell was silently corrupted (a 217-row file
+  // collapsed to 42 parsed rows). Header names are trimmed (" Email" →
+  // "Email"); both the raw and the trimmed header resolve via colMap.
+  const records = parseCsvRecords(text).filter((cells) =>
+    cells.some((cell) => cell.trim().length > 0),
+  );
+  if (records.length === 0) return [];
+  const header = records[0].map((col) => {
+    const trimmed = col.trim();
+    return colMap[trimmed] ?? colMap[col] ?? trimmed;
+  });
   const rows: Record<string, unknown>[] = [];
-  const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
-  if (lines.length === 0) return rows;
-  const header = parseCsvLine(lines[0]).map((col) => colMap[col] ?? col);
-  for (let i = 1; i < lines.length; i++) {
-    const cols = parseCsvLine(lines[i]);
+  for (let i = 1; i < records.length; i++) {
+    const cols = records[i];
     const row: Record<string, unknown> = {};
     for (let j = 0; j < header.length; j++) {
       row[header[j]] = cols[j] ?? null;
@@ -2790,6 +3240,61 @@ export function parseCsv(
   return rows;
 }
 
+/**
+ * Split raw CSV text into records of cells, walking the text as ONE
+ * character stream (never line-splitting first) so quoted cells can
+ * contain literal newlines. Quote semantics match `parseCsvLine`: a
+ * quote only opens a quoted section at the start of a cell, and `""`
+ * inside quotes is an escaped quote.
+ */
+export function parseCsvRecords(text: string): string[][] {
+  const records: string[][] = [];
+  let record: string[] = [];
+  let buf = "";
+  let inQuotes = false;
+  let sawAny = false; // any char consumed into the current record
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inQuotes) {
+      if (ch === '"' && text[i + 1] === '"') {
+        buf += '"';
+        i++;
+      } else if (ch === '"') {
+        inQuotes = false;
+      } else {
+        // Includes \n / \r — this is what makes multiline cells work.
+        buf += ch;
+      }
+      continue;
+    }
+    if (ch === ",") {
+      record.push(buf);
+      buf = "";
+      sawAny = true;
+    } else if (ch === '"' && buf === "") {
+      inQuotes = true;
+      sawAny = true;
+    } else if (ch === "\n" || ch === "\r") {
+      if (ch === "\r" && text[i + 1] === "\n") i++;
+      record.push(buf);
+      records.push(record);
+      record = [];
+      buf = "";
+      sawAny = false;
+    } else {
+      buf += ch;
+      sawAny = true;
+    }
+  }
+  // Trailing record without a final newline (or an unterminated quote —
+  // best-effort: keep what was read).
+  if (sawAny || buf.length > 0 || record.length > 0) {
+    record.push(buf);
+    records.push(record);
+  }
+  return records;
+}
+
 export function parseCsvLine(line: string): string[] {
   const out: string[] = [];
   let buf = "";
@@ -3721,6 +4226,9 @@ Fields (columns):
   dench crm fields enum-add <object> <field> <value> [--color HEX] [--position N]
       Appends <value> to the field's enumValues. --color is a hex like
       "#22c55e"; --position is a 0-based insertion index (defaults to append).
+      Without --color the option is auto-colored: semantic keyword match
+      (Done/Won → green, Working → blue, At Risk/Pending → yellow,
+      Churned/Lost → red, Todo/New → gray), else a rotating palette.
       Idempotent (case-insensitive): re-adding "won" when "Won" exists does
       NOT create a twin option — the response's "value" echoes the canonical
       casing; a given --color still updates the existing option's color.
@@ -3728,16 +4236,19 @@ Fields (columns):
       kanban column (positioned to match), so you do NOT need a separate
       "statuses set" call.
   dench crm fields enum-remove <object> <field> <value>
-      Removes the value from the option list. Historical entry rows that held
-      <value> keep the literal string (the badge falls back to the default
-      tint), matching Notion's "remove option, keep history" semantics. A
-      matching kanban column is removed too.
+      Removes the value from the option list AND unsets it on every entry
+      that held it (complete for indexed enum fields — the default). A
+      matching kanban column is removed too. Use enum-rename first if the
+      entries should migrate to another option instead of losing the value.
   dench crm fields enum-rename <object> <field> <oldValue> <newValue>
       Renames the option AND migrates every entry that referenced the old
       value (complete for indexed enum fields — the default — via the
-      projection index) AND renames matching crmStatuses. NOTE: saved views
-      whose filters pin the OLD label are not rewritten; update those view
-      filters after a rename or they silently go empty.
+      projection index) AND renames matching crmStatuses. When <newValue>
+      matches an EXISTING option case-insensitively, the rename MERGES onto
+      that option's canonical casing (entries migrate, the duplicate is
+      dropped) — the canonical way to dedupe two same-meaning options.
+      NOTE: saved views whose filters pin the OLD label are not rewritten;
+      update those view filters after a rename or they silently go empty.
   dench crm fields enum-set-color <object> <field> <value> <hex>
       Update the color (e.g. "#3b82f6") for an existing enum option.
 
@@ -3745,12 +4256,19 @@ Entries (rows):
   dench crm entries list <object> [--limit N] [--with-meta] [--json]
   dench crm entries get <object> <entryId>
   dench crm history <object> <entryId> [--include-system] [--limit N] [--cursor CURSOR] [--json]
-  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 create <object> --data '{"Field":"Value",...}'    (alias: --fields) [--allow-unknown] [--idempotency-key <key>]
+      --idempotency-key upserts on (object, key): a retried create returns
+      the existing row with alreadyExisted: true instead of duplicating it.
+  dench crm entries create-many <object> --data '[{"Field":"Value",...}]' [--file rows.json] [--idempotency-key <key>] [--dedupe-key <column>] [--allow-unknown]
+      --dedupe-key <column> makes each row idempotent by that column's
+      value; rows that already exist are skipped (status: already_existed).
   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
+      Automatically snapshots the target rows to a JSONL undo file in the
+      temp dir first (snapshotPath/snapshotRows in the output); the delete
+      aborts if the snapshot cannot be written.
   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.
@@ -3814,9 +4332,14 @@ Batch:
   and calls a batch surface in chunks.
 
 Import / export:
-  dench crm import <object> --csv leads.csv [--map '{"Email":"Email Address"}'] [--on-conflict skip|update|error]
+  dench crm import <object> --csv leads.csv [--map '{"Email":"Email Address"}'] [--on-conflict skip|update|error] [--dedupe-key <column>]
   dench crm import <object> --jsonl rows.jsonl
+      Imports are idempotent: every row gets a stable dedupe key (content
+      hash, or --dedupe-key <column>), so re-running the same file skips /
+      updates / errors per --on-conflict instead of duplicating rows.
   dench crm export <object> --format csv|jsonl [--limit N]
+      Pages with a real cursor and verifies no duplicate ids before
+      emitting; a summary (exportedCount/uniqueIds) is printed to stderr.
 
 Transactions (multi-step, all-or-nothing):
   TXN=$(dench crm transaction begin)