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

package/dench.ts

@@ -28,10 +28,12 @@ import {
   resolveHostFromArgs,
   STAGING_HOST,
 } from "./host";
+import { CliArgError, isHelpRequest } from "./lib/cli-args";
 import { cliVersion } from "./lib/cli-version";
+import { assertDeclaredCommandFlags } from "./lib/command-args";
 import { denchConfigDirectory } from "./lib/config-path.mjs";
 import { resolveOrganizationBySelector } from "./lib/organizationSelector";
-import { backendErrorText } from "./lib/public-error";
+import { backendErrorText, publicErrorDetails } from "./lib/public-error";
 import { formatApprovalOpenMessage, openUrl } from "./openUrl";
 import {
   explicitSessionKeyInput,
@@ -215,7 +217,10 @@ const api = {
 };
 const CONFIG_DIR = denchConfigDirectory();
 const CONFIG_PATH = join(CONFIG_DIR, "config.json");
-const args = process.argv.slice(2);
+const args = process.argv.slice(2).flatMap((arg) => {
+  const split = arg.startsWith("--") ? arg.indexOf("=") : -1;
+  return split > 2 ? [arg.slice(0, split), arg.slice(split + 1)] : [arg];
+});
 const json = args.includes("--json");
 const filteredArgs = args.filter((arg) => arg !== "--json");
 const scopedStatus = args.includes("--mine") || args.includes("--self");
@@ -321,13 +326,18 @@ function throwIfCliError(value: unknown) {
   }
   const record = value as JsonRecord;
   if (record.ok === false && typeof record.error === "string") {
-    throw new Error(record.error);
+    throw new CliError(record.error, publicErrorDetails(record));
   }
 }
 
 function normalizeCliError(error: unknown): CliError {
-  if (error instanceof CliError) return error;
+  if (error instanceof CliError) {
+    error.payload = { ...error.payload, ...publicErrorDetails(error.payload) };
+    return error;
+  }
   const message = backendErrorText(error);
+  if (error instanceof CliArgError)
+    return new CliError(message, { code: error.code, retryable: false });
   if (message.includes("Invalid dev agent key")) {
     return new CliError("Invalid dev agent key", {
       code: "invalid_dev_agent_key",
@@ -369,7 +379,10 @@ function normalizeCliError(error: unknown): CliError {
       ],
     });
   }
-  return new CliError(message);
+  return new CliError(message, {
+    code: "cli_error",
+    ...publicErrorDetails(error),
+  });
 }
 
 function _parseJsonObjectOption(name: string) {
@@ -673,6 +686,8 @@ Subagents:
   Help: dench agent help
 
   dench --version
+  dench reference <name> [--json]      Offline CLI-version-matched skill/reference
+  dench reference --list [--json]     Bundled reference index and revision
 
 Self-updating agent harness:
   dench identity show | edit                    IDENTITY.md (org-wide)
@@ -2701,12 +2716,21 @@ function stripRuntimeFlags(args: string[]) {
     "--staging",
     "--use-dev-env",
   ]);
-  const valueFlags = new Set(["--convex-url", "--host", "--backend"]);
+  const valueFlags = new Set([
+    "--convex-url",
+    "--host",
+    "--backend",
+    "--session-key",
+    "--session",
+  ]);
   const stripped: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (booleanFlags.has(arg)) continue;
     if (valueFlags.has(arg)) {
+      if (!args[i + 1] || args[i + 1].startsWith("--")) {
+        throw new CliArgError(`Missing value for ${arg}`);
+      }
       i++;
       continue;
     }
@@ -3392,7 +3416,7 @@ async function resolveFsDaemonEnv(): Promise<NodeJS.ProcessEnv> {
 }
 
 async function runFsCommand() {
-  const subArgs = args.slice(args.indexOf("fs") + 1);
+  const subArgs = stripRuntimeFlags(args.slice(args.indexOf("fs") + 1));
   const configuredBinary = process.env.DENCH_FS_DAEMON_BIN?.trim();
   const binary = configuredBinary || "dench-fs-daemon";
   const daemonEnv = await resolveFsDaemonEnv();
@@ -4303,10 +4327,95 @@ function isCommandNotFound(error: unknown) {
 }
 
 async function main() {
+  if (isHelpRequest(args)) {
+    const helpArgs = stripRuntimeFlags(args).filter((arg) => arg !== "--json");
+    if (helpArgs[0] === "help") helpArgs.shift();
+    if (!helpArgs.length || ["--help", "-h"].includes(helpArgs[0])) {
+      help();
+      return;
+    }
+    const path = helpArgs.filter(
+      (arg) => !["help", "--help", "-h"].includes(arg),
+    );
+    // Root help retains domain-specific setup, account and pagination guidance.
+    // These are explicit help-only paths; never pass mutation arguments to a handler.
+    if (path.length === 1) {
+      const roots: Record<string, () => void | Promise<void>> = {
+        reference: async () =>
+          console.log((await import("./reference")).REFERENCE_HELP),
+        tool: toolHelp,
+        integrations: integrationsHelp,
+        backend: backendHelp,
+        signin: signinHelp,
+        login: signinHelp,
+        onboard: signinHelp,
+        setup: signinHelp,
+        "what-can-i-do": signinHelp,
+        register: signinHelp,
+        memory: memoryHelp,
+        billing: billingHelp,
+        logout: logoutHelp,
+        context: contextHelp,
+        artifacts: artifactsHelp,
+        "suggested-work": artifactsHelp,
+        lists: listsCliHelp,
+        leads: leadsHelp,
+        companies: companiesHelp,
+        jobs: jobsHelp,
+        status: statusHelp,
+        web: async () => (await import("./web")).webHelp(),
+        crm: async () =>
+          (await import("./crm")).runCrmCommand({
+            convex: {} as ConvexHttpClient,
+            args: ["help"],
+          }),
+        apps: async () =>
+          (await import("./apps")).runAppsCommand({
+            convex: {} as ConvexHttpClient,
+            args: ["help"],
+          }),
+      };
+      if (roots[path[0]]) {
+        await roots[path[0]]();
+        return;
+      }
+    }
+    if (helpArgs[0] === "reference") {
+      console.log((await import("./reference")).REFERENCE_HELP);
+      return;
+    }
+    // Preserve the small, established CRM read help including its cursor contract.
+    if (helpArgs[0] === "crm" && ["query", "aggregate"].includes(helpArgs[1])) {
+      const { runCrmCommand } = await import("./crm");
+      await runCrmCommand({
+        convex: {} as ConvexHttpClient,
+        args: [...helpArgs.slice(1), "--help"],
+      });
+      return;
+    }
+    const { commandHelp } = await import("./lib/command-help");
+    const usage =
+      helpArgs[0] === "email"
+        ? (await import("./email")).emailHelpText()
+        : helpArgs[0] === "crm"
+          ? (await import("./crm")).crmHelpText()
+          : "";
+    console.log(commandHelp(helpArgs, usage));
+    return;
+  }
   const command = positional(0);
   const subcommand = positional(1);
 
-  if (command === "version" || hasFlag("--version")) {
+  assertDeclaredCommandFlags(stripRuntimeFlags(args));
+
+  if (command === "reference") {
+    await (await import("./reference")).runReferenceCommand(
+      stripRuntimeFlags(args.slice(args.indexOf("reference") + 1)),
+    );
+    return;
+  }
+
+  if (command === "version" || stripRuntimeFlags(args)[0] === "--version") {
     console.log(await cliVersion());
     return;
   }
@@ -4459,18 +4568,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
@@ -4737,7 +4850,7 @@ async function main() {
   }
 
   if (command === "web") {
-    const subArgs = args.slice(args.indexOf("web") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("web") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runWebCommand, webHelp } = await import("./web");
     const sub = filteredSubArgs[0];
@@ -4757,7 +4870,7 @@ async function main() {
   }
 
   if (command === "search") {
-    const subArgs = args.slice(args.indexOf("search") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("search") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runSearchCommand } = await import("./search");
     const sub = filteredSubArgs[0];
@@ -4780,7 +4893,7 @@ async function main() {
   }
 
   if (command === "image") {
-    const subArgs = args.slice(args.indexOf("image") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("image") + 1));
     const filteredSubArgs = subArgs.filter((a) => a !== "--json");
     const { runImageCommand } = await import("./image");
     const sub = filteredSubArgs[0];
@@ -4800,7 +4913,7 @@ async function main() {
   }
 
   if (command === "email") {
-    const subArgs = args.slice(args.indexOf("email") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("email") + 1));
     const { runEmailCommand } = await import("./email");
     const runtime = await getRuntime();
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench email");
@@ -4809,7 +4922,7 @@ async function main() {
       | undefined;
     try {
       if (
-        subArgs[0] !== "draft" &&
+        !["draft", "inbox", "send"].includes(subArgs[0]) &&
         !subArgs.some(
           (arg) => arg === "--mailbox" || arg.startsWith("--mailbox="),
         )
@@ -4918,7 +5031,7 @@ async function main() {
   }
 
   if (command === "browser") {
-    const subArgs = args.slice(args.indexOf("browser") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("browser") + 1));
     const { runBrowserCommand } = await import("./browser");
     const runtime = await getRuntime();
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench browser");
@@ -4943,7 +5056,7 @@ async function main() {
   // `dench ads` is canonical; `dench ad` and `dench adline` are aliases for
   // the same command (one code path in ./ads).
   if (command === "ads" || command === "ad" || command === "adline") {
-    const subArgs = args.slice(args.indexOf(command) + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
     const { runAdsCommand } = await import("./ads");
     // Earning is opt-in: resolve the agent session token best-effort so a
     // signed-in developer gets credited on flush, but never require login —
@@ -4979,7 +5092,7 @@ async function main() {
   }
 
   if (command === "chat") {
-    const subArgs = args.slice(args.indexOf("chat") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("chat") + 1));
     const sub = subArgs[0];
     if (!sub || sub === "help" || sub === "--help") {
       const { runChatCommand } = await import("./chat");
@@ -5029,7 +5142,7 @@ async function main() {
   }
 
   if (command === "agent") {
-    const subArgs = args.slice(args.indexOf("agent") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("agent") + 1));
     const sub = subArgs[0];
     if (!sub || sub === "help" || sub === "--help") {
       const { runAgentCommand } = await import("./agent");
@@ -5106,7 +5219,7 @@ async function main() {
   // `dench cron`. Same dispatch, same auth, same handler — only the
   // top-level command name differs to match the workspace UI rename.
   if (command === "cron" || command === "routine" || command === "routines") {
-    const subArgs = args.slice(args.indexOf(command) + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
     const sub = subArgs[0];
     // Help is a no-auth path so users can read the surface without a
     // session — mirrors `dench crm help`.
@@ -5155,7 +5268,7 @@ async function main() {
     "daily",
   ]);
   if (AGENT_CONFIG_COMMANDS.has(command)) {
-    const subArgs = args.slice(args.indexOf(command) + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf(command) + 1));
     if (
       subArgs[0] === "help" ||
       subArgs.includes("--help") ||

package/email-inbox.ts

@@ -0,0 +1,169 @@
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { assertNoUnknownFlags, getFlag, hasFlag } from "./lib/cli-args";
+
+export const EMAIL_INBOX_HELP = `
+  dench email inbox search [--mailbox <id|email>] [--from <email>] [--to <email>] [--subject <text>] [--after <ISO-date|milliseconds>] [--before <ISO-date|milliseconds>] [--direction inbound|outbound] [--limit 1..50] [--cursor <cursor>] [--json]
+  dench email inbox thread <thread-handle> [--limit 1..50] [--cursor <cursor>] [--json]
+  dench email inbox message <message-handle> [--format text|html] [--max-bytes 1..100000] [--json]
+
+Search reads synced headers only; it does not contact the provider or search message bodies.
+--from/--to match exact addresses (to includes cc/bcc); --subject is a case-insensitive substring.
+--after is inclusive, --before exclusive; date-only values mean midnight UTC. Older undated rows use createdAt.
+isDone means the persisted scan ended, not that the provider's entire mailbox has been synced.
+coverage.privacyLimited reports older rows omitted when complete record privacy cannot be established.
+Keep the returned cursor through empty filtered pages. Thread/message handles come from these results.
+`;
+
+export type EmailInboxCliContext = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  sessionToken?: string;
+};
+function valueFlag(args: string[], name: string) {
+  const present = args.includes(name);
+  const value = getFlag(args, name);
+  if (present && (!value?.trim() || value.startsWith("--")))
+    throw new Error(`${name} requires a value`);
+  return value;
+}
+function integerFlag(args: string[], name: string, maximum: number) {
+  const raw = valueFlag(args, name);
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (
+    !/^\d+$/.test(raw) ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > maximum
+  )
+    throw new Error(`${name} must be an integer from 1 to ${maximum}`);
+  return value;
+}
+function dateFlag(args: string[], name: string) {
+  const raw = valueFlag(args, name);
+  if (raw === undefined) return undefined;
+  if (/^-?\d+$/.test(raw)) {
+    const value = Number(raw);
+    if (Number.isSafeInteger(value)) return value;
+  }
+  const dateOnly = /^\d{4}-\d{2}-\d{2}$/.test(raw);
+  if (dateOnly || /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(raw)) {
+    const value = Date.parse(dateOnly ? `${raw}T00:00:00.000Z` : raw);
+    const day = raw.slice(0, 10);
+    const calendar = Date.parse(`${day}T00:00:00.000Z`);
+    if (
+      Number.isFinite(value) &&
+      Number.isFinite(calendar) &&
+      new Date(calendar).toISOString().slice(0, 10) === day
+    )
+      return value;
+  }
+  throw new Error(
+    `${name} must be YYYY-MM-DD, an ISO timestamp with timezone, or Unix milliseconds`,
+  );
+}
+export async function runEmailInboxCommand(
+  ctx: EmailInboxCliContext,
+): Promise<void> {
+  const args = [...ctx.args];
+  if (
+    !args.length ||
+    args.includes("--help") ||
+    args.includes("-h") ||
+    args[0] === "help"
+  ) {
+    console.log(EMAIL_INBOX_HELP.trim());
+    return;
+  }
+  const command = args.shift();
+  const jsonOutput = hasFlag(args, "--json") || ctx.jsonOutput;
+  const input: Record<string, unknown> = {};
+  const add = (key: string, value: unknown) => {
+    if (value !== undefined) input[key] = value;
+  };
+  if (command === "search") {
+    for (const flag of ["mailbox", "from", "to", "subject"])
+      add(flag, valueFlag(args, `--${flag}`));
+    add("after", dateFlag(args, "--after"));
+    add("before", dateFlag(args, "--before"));
+    const direction = valueFlag(args, "--direction");
+    if (
+      direction !== undefined &&
+      direction !== "inbound" &&
+      direction !== "outbound"
+    )
+      throw new Error("--direction must be inbound or outbound");
+    add("direction", direction);
+    if (
+      typeof input.after === "number" &&
+      typeof input.before === "number" &&
+      input.after >= input.before
+    )
+      throw new Error("--after must be earlier than --before");
+  } else if (command === "thread" || command === "message") {
+    const handle = args.shift();
+    if (
+      !handle?.startsWith(`email-${command}:`) ||
+      handle.length <= `email-${command}:`.length
+    )
+      throw new Error(
+        `Use an exact ${command} handle returned by email inbox search`,
+      );
+    input[`${command}Handle`] = handle;
+  } else
+    throw new Error("Unknown inbox command. Run `dench email inbox --help`.");
+  if (command === "message") {
+    const format = valueFlag(args, "--format");
+    if (format !== undefined && format !== "text" && format !== "html")
+      throw new Error("--format must be text or html");
+    add("format", format);
+    add("maxBytes", integerFlag(args, "--max-bytes", 100_000));
+  } else {
+    add("limit", integerFlag(args, "--limit", 50));
+    add("cursor", valueFlag(args, "--cursor"));
+  }
+  assertNoUnknownFlags(args, "email inbox");
+  if (args.length)
+    throw new Error(
+      `Unexpected inbox argument: ${args[0]}. Run \`dench email inbox --help\`.`,
+    );
+  const result = await ctx.convex.query(
+    makeFunctionReference<"query">(`functions/emailInbox:${command}`),
+    {
+      ...input,
+      ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+    },
+  );
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (command === "message") {
+    console.log(
+      `${result.header.subject}\nFrom: ${result.header.from.email}\n\n${result.body.content}`,
+    );
+    if (result.body.truncated)
+      console.log(
+        `\nBody truncated to the requested byte limit (${result.body.totalBytes} bytes stored).`,
+      );
+  } else {
+    for (const row of result.page)
+      console.log(
+        `${new Date(row.at).toISOString()}  ${row.from.email}  ${row.subject}\n  ${row.messageHandle}  ${row.threadHandle}`,
+      );
+    if (!result.page.length) console.log("No matching headers on this page.");
+    if (!result.isDone)
+      console.log(
+        `Continue with --cursor ${JSON.stringify(result.continueCursor)}`,
+      );
+  }
+  if (result.coverage.privacyLimited)
+    console.log(
+      "Some older messages were omitted because their full record privacy scope is unavailable.",
+    );
+  console.log(
+    `Synced mailbox: ${result.coverage.mailboxEmail} (${result.coverage.phase}); provider completeness is not established.`,
+  );
+}