@dench.com/cli 3.6.5-staging.384 → 3.7.0-staging.387

package/crm.ts

@@ -239,6 +239,7 @@ function normalizeRpcError(error: unknown): Error {
       userFacingConvexErrorMessage(error) ??
         (error instanceof Error ? error.message : String(error)),
     ),
+    { cause: error },
   );
 }
 
@@ -246,7 +247,8 @@ export function shift(args: string[], expected: string): string {
   try {
     return shiftRaw(args, expected);
   } catch (error) {
-    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    if (error instanceof CliArgError)
+      throw new CrmCliError(error.message, { cause: error });
     throw error;
   }
 }
@@ -290,7 +292,8 @@ function resolveLimitFlag(
   try {
     parsed = parseLimitRaw(raw, opts);
   } catch (error) {
-    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    if (error instanceof CliArgError)
+      throw new CrmCliError(error.message, { cause: error });
     throw error;
   }
   if (parsed.clamped) {
@@ -365,7 +368,8 @@ function parseJson(value: string | undefined): unknown {
   try {
     return parseJsonRaw(value);
   } catch (error) {
-    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    if (error instanceof CliArgError)
+      throw new CrmCliError(error.message, { cause: error });
     throw error;
   }
 }
@@ -377,7 +381,8 @@ export function assertNoUnknownFlags(
   try {
     assertNoUnknownFlagsRaw(args, command);
   } catch (error) {
-    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    if (error instanceof CliArgError)
+      throw new CrmCliError(error.message, { cause: error });
     throw error;
   }
 }
@@ -780,11 +785,23 @@ export async function callQuery(
   }
 }
 
+/** Every parsed token must be accounted for before an external effect. */
+function assertWriteArguments(ctx: CrmCliContext): void {
+  assertNoUnknownFlags(ctx.args, "crm");
+  if (ctx.args.length) {
+    const error = new CliArgError(
+      `Unexpected argument: ${ctx.args[0]}. Run the command with --help for usage.`,
+    );
+    throw new CrmCliError(error.message, { cause: error });
+  }
+}
+
 export async function callMutation(
   ctx: CrmCliContext,
   fn: Parameters<ConvexHttpClient["mutation"]>[0],
   args: Record<string, unknown> = {},
 ): Promise<unknown> {
+  assertWriteArguments(ctx);
   try {
     return await ctx.convex.mutation(fn, {
       ...args,
@@ -800,6 +817,7 @@ export async function callAction(
   fn: Parameters<ConvexHttpClient["action"]>[0],
   args: Record<string, unknown> = {},
 ): Promise<unknown> {
+  assertWriteArguments(ctx);
   try {
     return await ctx.convex.action(fn, {
       ...args,
@@ -914,6 +932,9 @@ const api = {
   },
   objects: {
     list: makeFunctionReference<"query">("functions/crm/objects:list"),
+    listCompact: makeFunctionReference<"query">(
+      "functions/crm/objects:listCompact",
+    ),
     get: makeFunctionReference<"query">("functions/crm/objects:get"),
     materializeView: makeFunctionReference<"action">(
       "functions/crm/objects:completeView",
@@ -963,6 +984,9 @@ const api = {
   },
   fields: {
     list: makeFunctionReference<"query">("functions/crm/fields:list"),
+    listCompact: makeFunctionReference<"query">(
+      "functions/crm/fields:listCompact",
+    ),
     create: makeFunctionReference<"mutation">("functions/crm/fields:create"),
     update: makeFunctionReference<"mutation">("functions/crm/fields:update"),
     remove: makeFunctionReference<"mutation">("functions/crm/fields:remove"),
@@ -1013,6 +1037,9 @@ const api = {
     ),
     aggregate: makeFunctionReference<"query">("functions/crm/query:aggregate"),
     search: makeFunctionReference<"query">("functions/crm/query:search"),
+    searchPage: makeFunctionReference<"query">(
+      "functions/crm/query:searchPage",
+    ),
   },
   statuses: {
     list: makeFunctionReference<"query">("functions/crm/statuses:list"),
@@ -1063,6 +1090,15 @@ const api = {
   },
 };
 
+/** These read commands have local, command-specific help (no runtime needed). */
+export function isCrmReadHelpRequest(args: readonly string[]): boolean {
+  const command = args.find((arg) => arg !== "--json");
+  return (
+    (command === "query" || command === "aggregate") &&
+    (args.includes("--help") || args.includes("-h"))
+  );
+}
+
 export async function runCrmCommand(opts: {
   convex: ConvexHttpClient;
   args: string[];
@@ -1088,6 +1124,21 @@ export async function runCrmCommand(opts: {
     crmHelp();
     return;
   }
+  if (isCrmReadHelpRequest(opts.args)) {
+    if (subcommand === "query") {
+      console.log(`Usage: dench crm query <object> [--where '<JSON>'] [--select Name,Email] [--sort -Score] [--limit N] [--json]
+  --page [--cursor '<continueCursor>']  Return {page,isDone,continueCursor} in index order; omit --sort.
+  --assigned-to me|unassigned|<userId|email> (or --mine) [--assignee-field <Field>]
+  Default limit: 100. Maximum: 1000 for a one-shot array, 100 for a cursor page.
+  Continue cursor pages until isDone, including empty filtered pages.
+Example: dench crm query company --where '{"Status":"New"}' --select Name --limit 25 --json`);
+    } else {
+      console.log(`Usage: dench crm aggregate <object> --field <Field> [--sum <NumberField>] [--json]
+  Count rows per value of --field. --sum also totals a number field within each bucket.
+Example: dench crm aggregate deal --field Stage --sum Amount --json`);
+    }
+    return;
+  }
   switch (subcommand) {
     case "objects":
       return await runObjectsCommand(ctx);
@@ -1435,8 +1486,16 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
     case "list": {
+      const compact = hasFlag(ctx.args, "--compact");
       assertNoUnknownFlags(ctx.args, "crm objects list");
-      out(ctx, await callQuery(ctx, api.objects.list, {}));
+      out(
+        ctx,
+        await callQuery(
+          ctx,
+          compact ? api.objects.listCompact : api.objects.list,
+          {},
+        ),
+      );
       return;
     }
     case "get": {
@@ -2135,8 +2194,16 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
   switch (verb) {
     case "list": {
       const objectName = shift(ctx.args, "object name");
+      const compact = hasFlag(ctx.args, "--compact");
       assertNoUnknownFlags(ctx.args, "crm fields list");
-      out(ctx, await callQuery(ctx, api.fields.list, { objectName }));
+      out(
+        ctx,
+        await callQuery(
+          ctx,
+          compact ? api.fields.listCompact : api.fields.list,
+          { objectName },
+        ),
+      );
       return;
     }
     case "create": {
@@ -2270,7 +2337,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
       // Assert before consuming the rest as positional field names so a
       // typo'd flag fails loudly rather than getting silently filtered.
       assertNoUnknownFlags(ctx.args, "crm fields reorder");
-      const orderedFieldNames = [...ctx.args];
+      const orderedFieldNames = ctx.args.splice(0);
       out(
         ctx,
         await callMutation(ctx, api.fields.reorder, {
@@ -2287,7 +2354,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
       // there are no stray flags so a typo'd `--limit` fails loud
       // instead of being silently consumed as an enum value.
       assertNoUnknownFlags(ctx.args, "crm fields enum-reorder");
-      const orderedValues = [...ctx.args];
+      const orderedValues = ctx.args.splice(0);
       if (orderedValues.length === 0) {
         throw new CrmCliError(
           "dench crm fields enum-reorder requires at least one value. " +
@@ -2391,37 +2458,100 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
   switch (verb) {
     case "list": {
       const objectName = shift(ctx.args, "object name");
+      const withMeta = hasFlag(ctx.args, "--with-meta");
+      const cursorSpecified = ctx.args.includes("--cursor");
+      const cursorValue = ctx.args[ctx.args.indexOf("--cursor") + 1];
+      if (
+        cursorSpecified &&
+        (!cursorValue?.trim() || cursorValue.startsWith("--"))
+      )
+        throw new CrmCliError(
+          "--cursor requires a non-empty continuation cursor.",
+          { cause: new CliArgError("Invalid --cursor") },
+        );
+      const cursor = getFlag(ctx.args, "--cursor");
+      if (cursorSpecified && (!cursor?.trim() || cursor.startsWith("--")))
+        throw new CrmCliError(
+          "--cursor requires a non-empty continuation cursor.",
+        );
+      const assigneeScopeArgs = resolveAssigneeScopeFlags(ctx.args);
       const limit = resolveLimitFlag(ctx.args, {
         defaultValue: 100,
-        cap: 1000,
+        cap:
+          withMeta && assigneeScopeArgs.assignedTo !== undefined ? 100 : 1000,
         command: "crm entries list",
+        ...(withMeta
+          ? {
+              fullDatasetHint:
+                "Continue with --with-meta --cursor '<continueCursor>' when a cursor is returned.",
+            }
+          : {}),
       });
-      const withMeta = hasFlag(ctx.args, "--with-meta");
-      const assigneeScopeArgs = resolveAssigneeScopeFlags(ctx.args);
+      if (cursor !== undefined && !withMeta) {
+        throw new CrmCliError(
+          "--cursor requires --with-meta on crm entries list.",
+        );
+      }
       assertNoUnknownFlags(ctx.args, "crm entries list");
-      const entries = await callQuery(ctx, api.entries.list, {
-        objectName,
-        limit: limit.effective,
-        ...assigneeScopeArgs,
-      });
       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);
+        out(
+          ctx,
+          await callQuery(ctx, api.entries.list, {
+            objectName,
+            limit: limit.effective,
+            ...assigneeScopeArgs,
+          }),
+        );
         return;
       }
-      const object = (await callQuery(ctx, api.objects.get, {
-        name: objectName,
-      })) as { entryCount?: number } | null;
-      const returnedCount = Array.isArray(entries) ? entries.length : 0;
-      const totalCount =
-        typeof object?.entryCount === "number"
-          ? object.entryCount
-          : returnedCount;
+      // Catalog counts include hidden and unassigned records. Only the
+      // readable page can tell us whether this caller has a continuation.
+      const [result, object] = (await Promise.all([
+        assigneeScopeArgs.assignedTo !== undefined
+          ? callQuery(ctx, api.query.scanEntries, {
+              objectName,
+              dsl: { limit: limit.effective },
+              paginationOpts: {
+                cursor: cursor ?? null,
+                numItems: limit.effective,
+              },
+              ...assigneeScopeArgs,
+            })
+          : callQuery(ctx, api.entries.listPage, {
+              objectName,
+              limit: limit.effective,
+              ...(cursor !== undefined ? { cursor } : {}),
+            }),
+        callQuery(ctx, api.objects.get, { name: objectName }),
+      ])) as [
+        {
+          page?: unknown[];
+          isDone?: boolean;
+          continueCursor?: string | null;
+          truncated?: boolean;
+        } | null,
+        { entryCount?: number; visibility?: string } | null,
+      ];
+      const entries = Array.isArray(result?.page) ? result.page : [];
+      const isDone = typeof result?.isDone === "boolean" ? result.isDone : null;
+      const truncated = result?.truncated === true;
+      const continueCursor =
+        isDone === false ? result?.continueCursor || null : null;
+      const hasMore = continueCursor
+        ? true
+        : isDone === true && !truncated
+          ? false
+          : null;
       out(ctx, {
         objectName,
-        totalCount,
-        returnedCount,
+        totalCount:
+          typeof object?.entryCount === "number" ? object.entryCount : null,
+        totalCountScope: "object",
+        visibility: object?.visibility ?? null,
+        returnedCount: entries.length,
+        returnedCountScope: "readable",
         limit: limit.effective,
         ...(limit.clamped
           ? {
@@ -2431,7 +2561,10 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
               },
             }
           : {}),
-        hasMore: totalCount > returnedCount,
+        hasMore,
+        isDone,
+        truncated,
+        continueCursor,
         entries,
       });
       return;
@@ -3152,25 +3285,31 @@ async function runAggregateCommand(ctx: CrmCliContext): Promise<void> {
 
 async function runSearchCommand(ctx: CrmCliContext): Promise<void> {
   const objectName = getFlag(ctx.args, "--object");
-  // Search caps at 100 server-side. Warn on stderr when clamped (the
-  // output is a bare JSON array, so stdout must stay untouched).
+  const selectRaw = getFlag(ctx.args, "--select");
+  const select = selectRaw?.split(",").map((name) => name.trim());
+  if (select && (select.length > 30 || select.some((name) => !name))) {
+    throw new CrmCliError(
+      "--select requires between 1 and 30 nonempty field names.",
+    );
+  }
+  const page = hasFlag(ctx.args, "--page");
+  const cursor = getFlag(ctx.args, "--cursor");
+  const projected = select !== undefined || page || cursor !== undefined;
   const limit = resolveLimitFlag(ctx.args, {
-    defaultValue: 50,
+    defaultValue: projected ? 20 : 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, {
+    await callQuery(ctx, projected ? api.query.searchPage : api.query.search, {
       text,
       objectName,
       limit: limit.effective,
+      ...(projected ? { select, cursor } : {}),
     }),
   );
 }
@@ -3300,7 +3439,8 @@ async function runActionsCommand(ctx: CrmCliContext): Promise<void> {
       const objectName = shift(ctx.args, "object name");
       const fieldId = shift(ctx.args, "field id");
       const actionId = shift(ctx.args, "action id");
-      const entryIds = ctx.args.filter((a) => !a.startsWith("--"));
+      assertNoUnknownFlags(ctx.args, "crm actions run");
+      const entryIds = ctx.args.splice(0);
       if (entryIds.length === 0) {
         throw new CrmCliError("Provide at least one entry id");
       }
@@ -3840,7 +3980,7 @@ export function remapKeys(
 // ── SQL escape hatch ─────────────────────────────────────────────────────
 
 async function runSqlCommand(ctx: CrmCliContext): Promise<void> {
-  const sql = ctx.args.join(" ").trim();
+  const sql = ctx.args.splice(0).join(" ").trim();
   if (!sql) {
     throw new CrmCliError("dench crm sql '<SELECT ... FROM ...>'");
   }
@@ -4329,6 +4469,7 @@ async function enrichCellThroughGateway(
   ctx: CrmCliContext,
   args: CellEnrichmentArgs,
 ): Promise<Record<string, unknown>> {
+  assertWriteArguments(ctx);
   const target = await resolveEnrichmentTarget(ctx, args);
   const entry = asEntry(
     await callQuery(ctx, api.entries.get, {
@@ -4352,6 +4493,7 @@ async function enrichObjectThroughGateway(
   ctx: CrmCliContext,
   args: ObjectEnrichmentArgs,
 ): Promise<Record<string, unknown>> {
+  assertWriteArguments(ctx);
   const target = await resolveEnrichmentTarget(ctx, args);
   const entries = asEntries(
     await callQuery(ctx, api.entries.list, {
@@ -4533,6 +4675,7 @@ async function runEnrichCommand(ctx: CrmCliContext): Promise<void> {
       const lookups = input.map((value, index) =>
         requireNonEmptyJsonRecord(value, `lookup ${index + 1}`),
       );
+      assertWriteArguments(ctx);
       out(ctx, await enrichProfiles({ kind, lookups }, ctx.enrichmentGateway));
       return;
     }
@@ -4638,10 +4781,14 @@ async function runReportsCommand(ctx: CrmCliContext): Promise<void> {
 }
 
 function crmHelp(): void {
-  console.log(`Usage: dench crm <subcommand>
+  console.log(crmHelpText());
+}
+
+export function crmHelpText(): string {
+  return `Usage: dench crm <subcommand>
 
 Objects (CRM tables):
-  dench crm objects list [--json]
+  dench crm objects list [--json] [--compact]
   dench crm objects get <name>
   dench crm objects create <name> [--description ...] [--default-view kanban] [--icon ...]
   dench crm objects update <name> [--default-view ...] [--icon ...] [--display-name "Clients"] [--display-name-singular "Client"] [--visibility workspace|owner_only|owner_plus_members]
@@ -4728,7 +4875,7 @@ Sidebar (progressive disclosure — Library + home Pinned strip; layout is WORKS
       shared shortcut, not a Library move; open to any member.
 
 Fields (columns):
-  dench crm fields list <object> [--json]
+  dench crm fields list <object> [--compact] [--json]
   dench crm fields create <object> <name> --type text|email|phone|url|number|boolean|date|enum|relation|user|tags|action|file|richtext \\
         [--required] [--description ...] [--enum-values JSON] [--enum-colors JSON] \\
         [--enum-multiple] [--related-object <name>] [--relationship many_to_one|many_to_many] \\
@@ -4785,8 +4932,12 @@ Fields (columns):
       Update the color (e.g. "#3b82f6") for an existing enum option.
 
 Entries (rows):
-  dench crm entries list <object> [--limit N] [--with-meta] [--json]
+  dench crm entries list <object> [--limit N] [--with-meta [--cursor '<continueCursor>']] [--json]
       [--assigned-to me|unassigned|<userId|email> | --mine] [--assignee-field <Field>]
+      --with-meta includes readable pagination; totalCount is the entire object's catalog count,
+      not a readable or assigned total. Continue only when continueCursor is returned, preserving filters.
+      Scoped reads may be truncated with no cursor (hasMore: null); repeating the same call will not advance.
+      Assigned metadata pages cap at 100 rows; other list reads cap at 1000.
   dench crm entries get <object> <entryId> [--with-context]   (--with-context appends the newest activity + notes)
   dench crm entries sync-history <object> <entryId> [--status]
       Queue a full, paged pull of the record's email history from every
@@ -4945,7 +5096,10 @@ Aggregates:
   dench crm aggregate <object> --field Status [--sum Amount]
 
 Full-text search:
-  dench crm search [--object <name>] [--limit N] <text>
+  dench crm search [--object <name>] [--select "Name,Email"] [--limit N] [--page] [--cursor <cursor>] <text>
+      --select returns a compact page with stable IDs, selected cells, isDone
+      and continueCursor. Follow cursors until isDone for complete results.
+      Without --select/--page/--cursor the legacy full-row array is unchanged.
 
 Statuses (kanban columns):
   dench crm statuses list <object>
@@ -5129,5 +5283,5 @@ unambiguous, but prefer canonical names from 'crm objects list'.
 
 Global flags:
   --json    Output raw JSON instead of pretty-printed text.
-`);
+`;
 }