@dench.com/cli 3.6.5-staging.384 → 3.6.6-staging.386

package/crm.ts

@@ -1063,6 +1063,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 +1097,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);
@@ -2391,37 +2415,92 @@ 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 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 +2510,10 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
               },
             }
           : {}),
-        hasMore: totalCount > returnedCount,
+        hasMore,
+        isDone,
+        truncated,
+        continueCursor,
         entries,
       });
       return;
@@ -4785,8 +4867,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

package/dench.ts

@@ -4459,18 +4459,22 @@ async function main() {
   if (command === "crm") {
     const subArgs = stripRuntimeFlags(args.slice(args.indexOf("crm") + 1));
     const sub = subArgs[0];
+    const { runCrmCommand, isCrmReadHelpRequest } = await import("./crm");
     // Short-circuit help so users don't need a session to read the
     // surface. The crm dispatcher's own help resolves --json + the
     // subcommand list inline.
-    if (!sub || sub === "help" || sub === "--help") {
-      const { runCrmCommand } = await import("./crm");
+    if (
+      !sub ||
+      sub === "help" ||
+      sub === "--help" ||
+      isCrmReadHelpRequest(subArgs)
+    ) {
       // runCrmCommand only needs `convex` for actual queries; help
       // doesn't touch it. Pass a minimal stub.
       // biome-ignore lint/suspicious/noExplicitAny: harmless help-only stub
       await runCrmCommand({ convex: {} as any, args: subArgs });
       return;
     }
-    const { runCrmCommand } = await import("./crm");
     const runtime = await getRuntime();
     // CRM is org-scoped — accept either an agent session token
     // (`dch_agent_*` from `dench signin`) or a unified Dench API key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "3.6.5-staging.384",
+  "version": "3.6.6-staging.386",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {