@dench.com/cli 3.6.6-staging.386 → 3.8.0-staging.389

package/context-settings.ts

@@ -0,0 +1,86 @@
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { CliArgError } from "./lib/cli-args";
+import { parseEnvironmentOptions } from "./lib/environment-cli-args";
+
+export const CONTEXT_SECTIONS = [
+  "identity",
+  "organisation",
+  "user",
+  "tools",
+  "rules",
+] as const;
+export function validateContextSet(input: readonly string[]) {
+  const parsed = parseEnvironmentOptions(
+    input,
+    ["--content"],
+    ["--stdin", "--json"],
+  );
+  const [verb, section] = parsed.positional;
+  if (
+    verb !== "set" ||
+    parsed.positional.length !== 2 ||
+    !CONTEXT_SECTIONS.includes(section as never) ||
+    parsed.child.length
+  )
+    throw new CliArgError(
+      `Usage: dench context set <${CONTEXT_SECTIONS.join("|")}> --stdin | --content <text> [--json]`,
+    );
+  if (
+    Number(parsed.flags["--stdin"] === true) +
+      Number(typeof parsed.flags["--content"] === "string") !==
+    1
+  )
+    throw new CliArgError(
+      "Choose exactly one of --stdin or --content. Store credentials with dench secrets set, never in context.",
+    );
+  return {
+    section: section as (typeof CONTEXT_SECTIONS)[number],
+    content: parsed.flags["--content"] as string | undefined,
+  };
+}
+
+export async function runContextSet(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  sessionToken?: string;
+  readStdin?: () => Promise<string>;
+}) {
+  const parsed = validateContextSet(opts.args);
+  const content =
+    parsed.content ??
+    (await (
+      opts.readStdin ??
+      (async () => {
+        const chunks: Buffer[] = [];
+        let size = 0;
+        for await (const chunk of process.stdin) {
+          size += Buffer.byteLength(chunk);
+          if (size > 32000)
+            throw new CliArgError(
+              "Context exceeds 32 KB. Keep standing instructions short; use workspace files for references.",
+            );
+          chunks.push(Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks).toString("utf8");
+      })
+    )());
+  if (!content.trim() || Buffer.byteLength(content) > 32000)
+    throw new CliArgError("Context must contain 1–32000 UTF-8 bytes.");
+  const fn = {
+    identity: "updateIdentity",
+    organisation: "updateOrganisation",
+    user: "updateUserProfile",
+    tools: "updateToolsNotes",
+    rules: "writeMagicFileFromUI",
+  }[parsed.section];
+  await opts.convex.mutation(
+    makeFunctionReference<"mutation">(`functions/agentConfig:${fn}`),
+    {
+      ...(opts.sessionToken ? { sessionToken: opts.sessionToken } : {}),
+      content,
+      ...(parsed.section === "rules" ? { path: "/RULES.md" } : {}),
+    },
+  );
+  console.log(JSON.stringify({ ok: true, section: parsed.section }));
+}

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"),
@@ -1459,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": {
@@ -2159,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": {
@@ -2294,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, {
@@ -2311,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. " +
@@ -2417,6 +2460,15 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       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(
@@ -2483,8 +2535,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         { entryCount?: number; visibility?: string } | null,
       ];
       const entries = Array.isArray(result?.page) ? result.page : [];
-      const isDone =
-        typeof result?.isDone === "boolean" ? result.isDone : null;
+      const isDone = typeof result?.isDone === "boolean" ? result.isDone : null;
       const truncated = result?.truncated === true;
       const continueCursor =
         isDone === false ? result?.continueCursor || null : null;
@@ -3234,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 } : {}),
     }),
   );
 }
@@ -3382,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");
       }
@@ -3922,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 ...>'");
   }
@@ -4411,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, {
@@ -4434,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, {
@@ -4615,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;
     }
@@ -4720,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]
@@ -4810,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] \\
@@ -5031,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>
@@ -5215,5 +5283,5 @@ unambiguous, but prefer canonical names from 'crm objects list'.
 
 Global flags:
   --json    Output raw JSON instead of pretty-printed text.
-`);
+`;
 }

package/cron.ts

@@ -392,6 +392,9 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
       "--prompt is required (becomes the user message of each cron-fired chat thread)",
     );
   }
+  const environment = getFlag(ctx.args, "--environment");
+  if (environment && !/^[a-z][a-z0-9-]{0,63}$/.test(environment))
+    throw new CronCliError("Invalid environment name");
   const description = getFlag(ctx.args, "--description");
   const overlapPolicy = getFlag(ctx.args, "--overlap") as
     | "skip"
@@ -431,6 +434,7 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
       triggerType,
       name,
       prompt,
+      environment,
       description,
       overlapPolicy,
       disabled,
@@ -462,6 +466,7 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
   const created = (await callMutation(ctx, createCronTriggerRef, {
     name,
     prompt,
+    environment,
     triggerType,
     schedule,
     description,
@@ -551,6 +556,7 @@ async function runSecret(ctx: CronCliContext): Promise<void> {
 }
 
 export type AppOrCrmCreateBase = {
+  environment?: string;
   triggerType: "composio" | "crm";
   name: string;
   prompt: string;
@@ -584,6 +590,7 @@ export function buildAppOrCrmCreateBody(
   const body: Record<string, unknown> = {
     name: base.name,
     prompt: base.prompt,
+    environment: base.environment,
     triggerType: base.triggerType,
     description: base.description,
     overlapPolicy: base.overlapPolicy,
@@ -731,6 +738,15 @@ async function runEvents(ctx: CronCliContext): Promise<void> {
 
 async function runUpdate(ctx: CronCliContext): Promise<void> {
   const jobId = shift(ctx.args, "job id");
+  const environment = getFlag(ctx.args, "--environment");
+  const clearEnvironment = hasFlag(ctx.args, "--clear-environment");
+  if (
+    environment &&
+    (clearEnvironment || !/^[a-z][a-z0-9-]{0,63}$/.test(environment))
+  )
+    throw new CronCliError(
+      "Choose a valid --environment name or --clear-environment",
+    );
   const name = getFlag(ctx.args, "--name");
   const prompt = getFlag(ctx.args, "--prompt");
   const description = getFlag(ctx.args, "--description");
@@ -753,6 +769,7 @@ async function runUpdate(ctx: CronCliContext): Promise<void> {
   const schedule = consumeScheduleFlags(ctx.args);
   const result = await callMutation(ctx, updateCronTriggerRef, {
     jobId,
+    environment: clearEnvironment ? null : environment,
     name,
     prompt,
     description,
@@ -866,6 +883,8 @@ Browse:
   dench cron events <toolkit> [--json]            # app-event types for a connected app
 
 Create / update:
+  Add --environment <name> to bind a ready reusable setup.
+  New runs use its latest ready revision; --clear-environment removes the binding on update.
   dench cron create "Daily standup digest" \\
       --prompt "Pull yesterday's commits + Slack #standup msgs and post a summary…" \\
       --type schedule                     # default. also: webhook | app | crm (see below)