@dench.com/cli 3.6.6-staging.386 → 3.7.0-staging.387

package/lib/command-help.ts

@@ -0,0 +1,78 @@
+import { COMMAND_ARGUMENTS } from "./command-args";
+import { apiOperations } from "./command-registry";
+
+/** Literal command words only; never interpret a data value as a command. */
+function words(usage: string): string[] {
+  const parts = usage
+    .replace(/^dench\s+/, "")
+    .split(/\s+/)
+    .filter(Boolean);
+  const end = parts.findIndex((part) => /^[<[(-]/.test(part));
+  return end < 0 ? parts : parts.slice(0, end);
+}
+
+function matches(
+  prefix: readonly string[],
+  candidate: readonly string[],
+): boolean {
+  return prefix.every((word, index) =>
+    candidate[index]?.split("|").includes(word),
+  );
+}
+
+/** Registry metadata supplies discovery, never invokes command implementations. */
+export function commandHelp(argv: readonly string[], usageText = ""): string {
+  const args = [...argv];
+  if (args[0] === "help") args.shift();
+  const input = words(args.filter((arg) => arg !== "help").join(" "));
+  const usageLines = usageText
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("dench "));
+  const candidates = [
+    ...usageLines.map((usage) => ({ usage, description: "" })),
+    ...COMMAND_ARGUMENTS.map((entry) => ({
+      usage:
+        `dench ${entry.command} ${[...entry.values.map((flag) => `[${flag} <value>]`), ...entry.switches.map((flag) => `[${flag}]`)].join(" ")}`.trim(),
+      description: "",
+    })),
+    ...apiOperations
+      .filter((op) => !op.deprecated)
+      .map((op) => ({ usage: op.cli, description: op.summary })),
+  ];
+  let prefix = input;
+  while (
+    prefix.length &&
+    !candidates.some((item) => matches(prefix, words(item.usage)))
+  ) {
+    prefix = prefix.slice(0, -1);
+  }
+  const selected = candidates.filter((item) =>
+    matches(prefix, words(item.usage)),
+  );
+  // Domain usage has real flag spellings; a backend schema is not a CLI parser.
+  const exactUsage = selected.filter((item) => !item.description);
+  const entries = exactUsage.length ? exactUsage : selected;
+  const seen = new Set<string>();
+  const lines = entries.filter((item) => {
+    if (seen.has(item.usage)) return false;
+    seen.add(item.usage);
+    return true;
+  });
+  const heading = `Usage: dench ${prefix.join(" ")}${prefix.length ? "" : "<command>"}`;
+  return [
+    heading,
+    ...lines
+      .slice(0, 12)
+      .map(
+        (item) =>
+          `  ${item.usage}${item.description ? `\n    ${item.description}` : ""}`,
+      ),
+    ...(lines.length > 12
+      ? [
+          `  ${lines.length - 12} more commands; add a subcommand before --help.`,
+        ]
+      : []),
+    "Options: --help, -h (local help); --json (structured command results).",
+  ].join("\n");
+}

package/lib/command-registry.ts

@@ -974,6 +974,18 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("query", "functions/crm/objects:list"),
   }),
+  op({
+    id: "crm.objects.listCompact",
+    group: "crm",
+    summary:
+      "List names, display labels, visibility and workspace counts without internal state.",
+    cli: "dench crm objects list --compact",
+    method: "GET",
+    path: "/crm/catalog/objects",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/crm/objects:listCompact"),
+  }),
   op({
     id: "crm.objects.get",
     group: "crm",
@@ -1259,6 +1271,18 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("query", "functions/crm/fields:list"),
   }),
+  op({
+    id: "crm.fields.listCompact",
+    group: "crm",
+    summary:
+      "List field names, types and effective constraints without indexing or enrichment internals.",
+    cli: "dench crm fields list --compact",
+    method: "GET",
+    path: "/crm/catalog/objects/{objectName}/fields",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/crm/fields:listCompact"),
+  }),
   op({
     id: "crm.fields.create",
     group: "crm",
@@ -2306,6 +2330,18 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("query", "functions/crm/query:search"),
   }),
+  op({
+    id: "crm.search.page",
+    group: "crm",
+    summary:
+      "Search bounded pages of readable CRM entries, optionally projecting cells. Always follow continueCursor until isDone.",
+    cli: "dench crm search --page",
+    method: "GET",
+    path: "/crm/search/page",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/crm/query:searchPage"),
+  }),
   op({
     id: "crm.statuses.list",
     group: "crm",
@@ -3347,6 +3383,42 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("mutation", "functions/emailCampaigns:deleteIdentity"),
   }),
+  op({
+    id: "email.inbox.search",
+    group: "email",
+    summary:
+      "Search authorized synced mailbox headers with bounded cursor pagination. isDone covers stored records, not provider completeness.",
+    cli: "dench email inbox search",
+    method: "GET",
+    path: "/email/inbox/search",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/emailInbox:search"),
+  }),
+  op({
+    id: "email.inbox.thread",
+    group: "email",
+    summary:
+      "Read a bounded page of synced headers using an exact thread handle from inbox search; bodies remain on demand.",
+    cli: "dench email inbox thread",
+    method: "GET",
+    path: "/email/inbox/threads/{threadHandle}",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/emailInbox:thread"),
+  }),
+  op({
+    id: "email.inbox.message",
+    group: "email",
+    summary:
+      "Read a bounded stored body using an exact message handle from inbox search; rechecks mailbox and record privacy.",
+    cli: "dench email inbox message",
+    method: "GET",
+    path: "/email/inbox/messages/{messageHandle}",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/emailInbox:message"),
+  }),
   op({
     id: "email.drafts.create",
     group: "email",
@@ -3434,7 +3506,7 @@ const rawApiOperations = [
     group: "email",
     summary:
       "Send through a native Gmail or Outlook mailbox with a durable request receipt. Only use for an explicit send request.",
-    cli: "dench email send --mailbox",
+    cli: "dench email send [--mailbox <id/email>]",
     method: "POST",
     path: "/email/native/send",
     requestSchema: anyObject,
@@ -3449,7 +3521,7 @@ const rawApiOperations = [
     group: "email",
     summary:
       "Send one raw email (no campaign): to/cc/bcc, custom from-name and reply-to, optional reply threading via replyToMessageId.",
-    cli: "dench email send",
+    cli: "dench email send --from <verified-email>",
     method: "POST",
     path: "/email/send",
     requestSchema: anyObject,
@@ -5139,7 +5211,7 @@ const rawApiOperations = [
     id: "agentConfig.tools.edit",
     group: "agent-config",
     summary: "Update tool notes.",
-    cli: "dench tools notes-edit",
+    cli: "dench tools edit",
     method: "PUT",
     path: "/agent-config/tools",
     requestSchema: anyObject,

package/lib/native-email-wait.ts

@@ -0,0 +1,75 @@
+import { backendErrorText, publicErrorDetails } from "./public-error";
+
+export const NATIVE_EMAIL_WAIT_MS = 10_000;
+const pending = new Set(["pending", "syncing", "synced", "sending"]);
+type Receipt = Record<string, unknown>;
+
+/** Observe one durable receipt. Never resubmit a send after an uncertain read. */
+export async function waitForNativeEmail(
+  initial: unknown,
+  read: (draftId: string, signal: AbortSignal) => Promise<unknown>,
+  waitMs = NATIVE_EMAIL_WAIT_MS,
+): Promise<unknown> {
+  if (!Number.isFinite(waitMs) || waitMs < 0 || waitMs > 60_000)
+    throw new Error(
+      "Email receipt wait must be between 0 and 60000 milliseconds",
+    );
+  if (waitMs === 0 || !initial || typeof initial !== "object") return initial;
+  let receipt = initial as Receipt;
+  const draftId = receipt.draftId;
+  if (typeof draftId !== "string" || !pending.has(String(receipt.syncStatus)))
+    return initial;
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error("Receipt observation timed out"));
+    }, waitMs);
+  });
+  try {
+    return await Promise.race([
+      (async () => {
+        while (!controller.signal.aborted) {
+          const next = await read(draftId, controller.signal);
+          if (
+            !next ||
+            typeof next !== "object" ||
+            (next as Receipt).draftId !== draftId ||
+            typeof (next as Receipt).syncStatus !== "string"
+          ) {
+            throw new Error("Invalid email receipt response");
+          }
+          receipt = next as Receipt;
+          if (!pending.has(String(receipt.syncStatus))) return receipt;
+          await new Promise<void>((resolve) => {
+            const pollTimer = setTimeout(done, 500);
+            function done() {
+              clearTimeout(pollTimer);
+              controller.signal.removeEventListener("abort", done);
+              resolve();
+            }
+            controller.signal.addEventListener("abort", done, { once: true });
+          });
+        }
+        return receipt;
+      })(),
+      deadline,
+    ]);
+  } catch (error) {
+    return {
+      ...receipt,
+      observation: {
+        status: controller.signal.aborted ? "timed_out" : "unavailable",
+        ...publicErrorDetails(error),
+        message: controller.signal.aborted
+          ? "Still awaiting the send result."
+          : backendErrorText(error),
+        nextAction: `dench email draft show ${draftId} --json`,
+      },
+    };
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    controller.abort();
+  }
+}

package/lib/public-error.ts

@@ -1,6 +1,88 @@
 const BACKEND_CALL_PREFIX = /\[CONVEX [^\]]*\]\s*/g;
 const REQUEST_ID_ONLY = /^\[Request ID:\s*([A-Za-z0-9]+)\]\s*Server Error$/i;
 
+/** Preserve actionable public fields without dumping arbitrary backend data. */
+export function publicErrorDetails(error: unknown): Record<string, unknown> {
+  if (!error || typeof error !== "object") return {};
+  let outer = error as Record<string, unknown>;
+  // Domain wrappers can preserve the original RPC error as a cause. Keep the
+  // walk bounded so an accidental cyclic cause never hides the actual failure.
+  for (let depth = 0; depth < 3; depth++) {
+    if (
+      outer.data !== undefined ||
+      outer.payload !== undefined ||
+      typeof outer.code === "string"
+    )
+      break;
+    if (
+      !outer.cause ||
+      typeof outer.cause !== "object" ||
+      outer.cause === outer
+    )
+      break;
+    outer = outer.cause as Record<string, unknown>;
+  }
+  const raw = outer.data ?? outer.payload ?? outer;
+  let data = raw;
+  if (typeof raw === "string") {
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      return {};
+    }
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return {};
+  const value = data as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const key of [
+    "code",
+    "requestId",
+    "operationId",
+    "executionStatus",
+    "draftId",
+    "receiptId",
+    "nextAction",
+  ] as const) {
+    if (typeof value[key] === "string") result[key] = value[key];
+  }
+  if (typeof value.retryable === "boolean") result.retryable = value.retryable;
+  const neverRetry = new Set(["uncertain_outcome", "unconfirmed"]);
+  const noAutomaticRetry = new Set([
+    "invalid_arguments",
+    "validation_failed",
+    "missing_connection",
+    "needs_connection",
+    "needs_sender",
+    "permission_denied",
+    "forbidden",
+    "login_required",
+    "canceled",
+    "cancelled",
+    "stale_owner",
+    "provider_failure",
+    "provider_failed",
+    "upstream_failed",
+  ]);
+  if (
+    typeof result.code === "string" &&
+    (neverRetry.has(result.code) ||
+      (result.retryable === undefined && noAutomaticRetry.has(result.code)))
+  )
+    result.retryable = false;
+  if (
+    typeof value.retryAfterMs === "number" &&
+    Number.isFinite(value.retryAfterMs)
+  ) {
+    result.retryAfterMs = value.retryAfterMs;
+  }
+  if (Array.isArray(value.nextActions)) {
+    result.nextActions = value.nextActions.filter(
+      (item) => typeof item === "string",
+    );
+  }
+  return result;
+}
+
 export function publicErrorMessage(message: string): string {
   const cleaned = message
     .replace(BACKEND_CALL_PREFIX, "")