@dench.com/cli 2.2.6 → 2.3.0

package/cron.ts

@@ -33,10 +33,16 @@
  *   enable <jobId>                       Re-arm a paused cron.
  *   disable <jobId>                      Soft-pause without delete.
  *   run <jobId> [--wait]                 Manual fire; --wait blocks.
+ *   secret <jobId>                       Mint/rotate a signing secret (any type).
+ *   events <toolkit>                     List a connected app's event types.
  *   runs <jobId> [--limit N] [--status]  Run history per trigger.
  *   history [--limit N]                  Flat history across all crons.
  *   help                                 Print this help.
  *
+ * Trigger types accepted by `create --type`:
+ *   schedule (default) | webhook | composio (app event) | crm (CRM event).
+ *   composio/crm POST to /api/cron/jobs; the others use the Convex mutation.
+ *
  * Schedule flags accepted by `create` and `update`:
  *   --every <duration>   30s | 5m | 2h | 1d | 12h…
  *   --every-ms <number>  Same, raw milliseconds.
@@ -138,6 +144,28 @@ async function postJson(
   return json;
 }
 
+async function getJson(
+  url: string,
+  headers: Record<string, string>,
+): Promise<unknown> {
+  const response = await fetch(url, { method: "GET", headers });
+  const text = await response.text();
+  let json: unknown;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    json = { raw: text };
+  }
+  if (!response.ok) {
+    const detail =
+      json && typeof json === "object" && "error" in json
+        ? String((json as Record<string, unknown>).error)
+        : JSON.stringify(json);
+    throw new CronCliError(`${url} failed (${response.status}): ${detail}`);
+  }
+  return json;
+}
+
 async function callQuery(
   ctx: CronCliContext,
   fn: Parameters<ConvexHttpClient["query"]>[0],
@@ -196,7 +224,9 @@ export type CronScheduleSpec =
  *
  * `--at` implicitly drops `--every` / `--cron` if both are passed.
  */
-export function consumeScheduleFlags(args: string[]): CronScheduleSpec | undefined {
+export function consumeScheduleFlags(
+  args: string[],
+): CronScheduleSpec | undefined {
   const at = getFlag(args, "--at");
   if (at) {
     const ts = new Date(at).getTime();
@@ -335,10 +365,15 @@ async function runGet(ctx: CronCliContext): Promise<void> {
 }
 
 async function runCreate(ctx: CronCliContext): Promise<void> {
-  const name = shift(ctx.args, "name (positional, e.g. dench cron create \"Daily standup digest\" --prompt … --every 1d)");
+  const name = shift(
+    ctx.args,
+    'name (positional, e.g. dench cron create "Daily standup digest" --prompt … --every 1d)',
+  );
   const prompt = getFlag(ctx.args, "--prompt");
   if (!prompt || !prompt.trim()) {
-    throw new CronCliError("--prompt is required (becomes the user message of each cron-fired chat thread)");
+    throw new CronCliError(
+      "--prompt is required (becomes the user message of each cron-fired chat thread)",
+    );
   }
   const description = getFlag(ctx.args, "--description");
   const overlapPolicy = getFlag(ctx.args, "--overlap") as
@@ -346,10 +381,7 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
     | "queue"
     | "kill_old"
     | undefined;
-  if (
-    overlapPolicy &&
-    !["skip", "queue", "kill_old"].includes(overlapPolicy)
-  ) {
+  if (overlapPolicy && !["skip", "queue", "kill_old"].includes(overlapPolicy)) {
     throw new CronCliError(
       `--overlap must be one of skip|queue|kill_old (got "${overlapPolicy}")`,
     );
@@ -360,26 +392,285 @@ async function runCreate(ctx: CronCliContext): Promise<void> {
   if (target && target !== "chat_turn") {
     throw new CronCliError(`--target must be chat_turn (got "${target}")`);
   }
-  const schedule = consumeScheduleFlags(ctx.args);
-  if (!schedule) {
+  const triggerType = (getFlag(ctx.args, "--type") ?? "schedule") as
+    | "schedule"
+    | "webhook"
+    | "composio"
+    | "crm";
+  if (!["schedule", "webhook", "composio", "crm"].includes(triggerType)) {
     throw new CronCliError(
-      "One of --every / --cron / --at is required. Examples:\n" +
-        "  dench cron create \"Hourly health check\" --prompt 'Check uptime…' --every 1h\n" +
-        '  dench cron create "Weekday digest" --prompt \'Pull yesterday…\' --cron "0 9 * * 1-5"\n' +
-        '  dench cron create "May 4 launch" --prompt \'Send launch tweet\' --at 2026-05-04T09:00:00Z',
+      `--type must be schedule|webhook|composio|crm (got "${triggerType}").`,
     );
   }
-  const result = await callMutation(ctx, createCronTriggerRef, {
+
+  // App-event (composio) and CRM-event automations are created through the
+  // REST `/api/cron/jobs` POST: composio needs the upstream subscribe +
+  // connection-ownership flow (Node runtime, project Composio key), and CRM
+  // rides the same path for one create surface. schedule + webhook keep the
+  // direct Convex mutation below.
+  if (triggerType === "composio" || triggerType === "crm") {
+    return await runCreateAppOrCrm(ctx, {
+      triggerType,
+      name,
+      prompt,
+      description,
+      overlapPolicy,
+      disabled,
+      deleteAfterRun,
+      target,
+    });
+  }
+  const isWebhook = triggerType === "webhook";
+
+  let schedule: CronScheduleSpec | undefined;
+  if (isWebhook) {
+    // Webhook automations fire on demand / via their signed URL — no schedule.
+    if (consumeScheduleFlags(ctx.args)) {
+      throw new CronCliError(
+        "Webhook automations don't take a schedule. Omit --every/--cron/--at.",
+      );
+    }
+  } else {
+    schedule = consumeScheduleFlags(ctx.args);
+    if (!schedule) {
+      throw new CronCliError(
+        "One of --every / --cron / --at is required for schedule automations. Examples:\n" +
+          "  dench cron create \"Hourly health check\" --prompt 'Check uptime…' --every 1h\n" +
+          '  dench cron create "Weekday digest" --prompt \'Pull yesterday…\' --cron "0 9 * * 1-5"\n' +
+          "  dench cron create \"Inbound lead\" --prompt 'Triage the lead…' --type webhook",
+      );
+    }
+  }
+  const created = (await callMutation(ctx, createCronTriggerRef, {
     name,
     prompt,
+    triggerType,
     schedule,
     description,
     overlapPolicy,
     enabled: disabled ? false : undefined,
     deleteAfterRun: deleteAfterRun ? true : undefined,
     target,
+  })) as { jobId?: string };
+
+  // Webhook automations need a signing secret to be externally callable. Mint
+  // one now (unless --no-secret) so `create` hands back a working URL+secret.
+  if (isWebhook && !hasFlag(ctx.args, "--no-secret") && created.jobId) {
+    const secret = await mintAutomationSecret(ctx, created.jobId);
+    out(ctx, { ...created, ...secret });
+    return;
+  }
+  out(ctx, created);
+}
+
+/**
+ * Mint (or rotate) a signing secret for an automation via the Next REST route
+ * (secret encryption runs in the Node route, not Convex's V8 runtime). Returns
+ * the plaintext secret + callable URL — shown once.
+ */
+async function mintAutomationSecret(
+  ctx: CronCliContext,
+  jobId: string,
+): Promise<{ webhookUrl: string | null; webhookSecret: string | null }> {
+  const url = `${getApiBase()}/api/cron/jobs/${encodeURIComponent(jobId)}/regenerate-secret`;
+  const res = (await postJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+    {},
+  )) as { webhookUrl?: string | null; webhookSecret?: string | null };
+  return {
+    webhookUrl: res.webhookUrl ?? null,
+    webhookSecret: res.webhookSecret ?? null,
+  };
+}
+
+async function runSecret(ctx: CronCliContext): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const secret = await mintAutomationSecret(ctx, jobId);
+  out(ctx, {
+    jobId,
+    ...secret,
+    note: "Secret shown once — store it now. Re-running rotates it (invalidates the old one).",
   });
-  out(ctx, result);
+}
+
+export type AppOrCrmCreateBase = {
+  triggerType: "composio" | "crm";
+  name: string;
+  prompt: string;
+  description?: string;
+  overlapPolicy?: "skip" | "queue" | "kill_old";
+  disabled: boolean;
+  deleteAfterRun: boolean;
+  target?: "chat_turn";
+};
+
+/**
+ * Build the `/api/cron/jobs` POST body for an app-event (composio) or
+ * CRM-event automation from the create flags. Pure (no network) so the flag
+ * parsing + validation + payload shape can be unit-tested directly. Consumes
+ * the type-specific flags off `args` (composio: --connection/--event/--toolkit/
+ * --trigger-config; crm: --object/--event/--where/--where-logic) and throws a
+ * `CronCliError` with discovery hints when a required input is missing.
+ */
+export function buildAppOrCrmCreateBody(
+  args: string[],
+  base: AppOrCrmCreateBase,
+): Record<string, unknown> {
+  // Neither type takes a schedule — reject one early instead of silently
+  // dropping it server-side.
+  if (consumeScheduleFlags(args)) {
+    throw new CronCliError(
+      `${base.triggerType} automations don't take a schedule. Omit --every/--cron/--at.`,
+    );
+  }
+
+  const body: Record<string, unknown> = {
+    name: base.name,
+    prompt: base.prompt,
+    triggerType: base.triggerType,
+    description: base.description,
+    overlapPolicy: base.overlapPolicy,
+    enabled: base.disabled ? false : undefined,
+    deleteAfterRun: base.deleteAfterRun ? true : undefined,
+    target: base.target,
+  };
+
+  if (base.triggerType === "composio") {
+    const connection = getFlag(args, "--connection");
+    const event = getFlag(args, "--event");
+    if (!connection?.trim() || !event?.trim()) {
+      throw new CronCliError(
+        "app-event automations need --connection <connectedAccountId> and --event <triggerSlug>.\n" +
+          "  Discover apps:   dench apps --json              (use connectedAccountId + toolkit)\n" +
+          "  Discover events: dench cron events <toolkit>    (use the event slug)\n" +
+          "Example:\n" +
+          '  dench cron create "New GitHub star" --prompt "Thank the new stargazer" \\\n' +
+          "    --type composio --connection ca_123 --event GITHUB_STAR_ADDED_EVENT --toolkit github",
+      );
+    }
+    const toolkit = getFlag(args, "--toolkit");
+    const triggerConfigRaw = getFlag(args, "--trigger-config");
+    let triggerConfig: unknown;
+    if (triggerConfigRaw) {
+      try {
+        triggerConfig = JSON.parse(triggerConfigRaw);
+      } catch {
+        throw new CronCliError(
+          `--trigger-config must be valid JSON (got ${triggerConfigRaw})`,
+        );
+      }
+    }
+    body.composioConnectionId = connection.trim();
+    body.composioTriggerSlug = event.trim();
+    if (toolkit?.trim()) body.composioToolkitSlug = toolkit.trim();
+    if (triggerConfig !== undefined) body.triggerConfig = triggerConfig;
+  } else {
+    const object = getFlag(args, "--object");
+    const event = getFlag(args, "--event");
+    if (!object?.trim() || !event?.trim()) {
+      throw new CronCliError(
+        "CRM-event automations need --object <objectId> and --event create|update|delete.\n" +
+          "  Discover objects: dench crm objects list\n" +
+          "  Discover fields:  dench crm fields list <object>   (filter on field _id via --where)\n" +
+          "Example:\n" +
+          '  dench cron create "New company" --prompt "Research the new company" \\\n' +
+          "    --type crm --object <objectId> --event create",
+      );
+    }
+    if (!["create", "update", "delete"].includes(event)) {
+      throw new CronCliError(
+        `--event must be create|update|delete for CRM automations (got "${event}")`,
+      );
+    }
+    const whereRaw = getFlag(args, "--where");
+    const whereLogic = (getFlag(args, "--where-logic") ?? "AND") as
+      | "AND"
+      | "OR";
+    if (!["AND", "OR"].includes(whereLogic)) {
+      throw new CronCliError(
+        `--where-logic must be AND|OR (got "${whereLogic}")`,
+      );
+    }
+    const crmTriggerConfig: Record<string, unknown> = {
+      eventType: event,
+      objectId: object.trim(),
+    };
+    if (whereRaw) {
+      let whereGroups: unknown;
+      try {
+        whereGroups = JSON.parse(whereRaw);
+      } catch {
+        throw new CronCliError(
+          "--where must be valid JSON: an array of groups like " +
+            '\'[{"logic":"AND","conditions":[{"fieldId":"<id>","operator":"equals","value":"x"}]}]\'',
+        );
+      }
+      if (!Array.isArray(whereGroups)) {
+        throw new CronCliError(
+          "--where must be a JSON array of where-groups (each { logic, conditions }).",
+        );
+      }
+      crmTriggerConfig.whereGroups = whereGroups;
+      crmTriggerConfig.whereLogic = whereLogic;
+    }
+    body.crmTriggerConfig = crmTriggerConfig;
+  }
+
+  return body;
+}
+
+/**
+ * Create an app-event (composio) or CRM-event automation via the REST
+ * `/api/cron/jobs` POST. composio creation also subscribes the trigger
+ * instance upstream + verifies the org owns the connection (handled
+ * server-side in the Node route); CRM creation validates the object +
+ * filter field ids in the mutation.
+ */
+async function runCreateAppOrCrm(
+  ctx: CronCliContext,
+  base: AppOrCrmCreateBase,
+): Promise<void> {
+  const body = buildAppOrCrmCreateBody(ctx.args, base);
+  const url = `${getApiBase()}/api/cron/jobs`;
+  const created = await postJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+    body,
+  );
+  out(ctx, created);
+}
+
+/**
+ * List the app-event types a connected app publishes, so the caller can pick
+ * a `--event <triggerSlug>` for `dench cron create --type composio`. Backed by
+ * `GET /api/cron/trigger-types` (project-level Composio catalogue).
+ */
+async function runEvents(ctx: CronCliContext): Promise<void> {
+  const toolkit = shift(
+    ctx.args,
+    "toolkit slug (e.g. github — run `dench apps --json` to see each app's slug)",
+  );
+  const url = `${getApiBase()}/api/cron/trigger-types?toolkit=${encodeURIComponent(toolkit)}`;
+  const result = (await getJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+  )) as {
+    items?: Array<{ slug?: string; name?: string; description?: string }>;
+  };
+  if (ctx.jsonOutput) {
+    out(ctx, result);
+    return;
+  }
+  const items = result.items ?? [];
+  if (items.length === 0) {
+    console.log(`(no app events found for "${toolkit}")`);
+    return;
+  }
+  for (const item of items) {
+    console.log(`${item.slug ?? "?"}  —  ${item.name ?? ""}`);
+    if (item.description) console.log(`    ${item.description}`);
+  }
 }
 
 async function runUpdate(ctx: CronCliContext): Promise<void> {
@@ -458,7 +749,11 @@ async function runRunNow(ctx: CronCliContext): Promise<void> {
     })) as { entries: Array<{ ts: number; status?: string }> };
     const matching = runs.entries.find(() => true);
     if (matching && matching.status) {
-      out(ctx, { ...fired, finalStatus: matching.status, durationMs: Date.now() - start });
+      out(ctx, {
+        ...fired,
+        finalStatus: matching.status,
+        durationMs: Date.now() - start,
+      });
       return;
     }
     await new Promise((resolve) => setTimeout(resolve, 3000));
@@ -509,10 +804,12 @@ Browse:
   dench cron get <jobId> [--json]
   dench cron history [--limit 50] [--status ok|error|skipped] [--json]
   dench cron runs <jobId> [--limit 50] [--status ok|error|skipped] [--json]
+  dench cron events <toolkit> [--json]            # app-event types for a connected app
 
-Create / update (one of --every / --cron / --at is required for create):
+Create / update:
   dench cron create "Daily standup digest" \\
       --prompt "Pull yesterday's commits + Slack #standup msgs and post a summary…" \\
+      --type schedule                     # default. also: webhook | composio | crm (see below)
       --every 1d                          # or --cron "0 9 * * 1-5"  or --at 2026-05-04T09:00:00Z
       [--description "..."]               # human-readable note shown in dashboard / list
       [--overlap skip|queue|kill_old]     # default: skip
@@ -521,6 +818,25 @@ Create / update (one of --every / --cron / --at is required for create):
       [--target chat_turn]                # default: chat_turn (fires a fresh chat thread)
       [--json]
 
+  # Webhook automation (fires on demand or via a signed URL). Mints + prints a
+  # signing secret unless --no-secret. The secret is shown ONCE.
+  dench cron create "Inbound lead triage" --prompt "Triage the lead…" --type webhook
+
+  # App-event automation (fires when something happens in a connected app).
+  #   1. dench apps --json                    → connectedAccountId + toolkit
+  #   2. dench cron events <toolkit>          → event slug
+  dench cron create "New GitHub star" --prompt "Thank the new stargazer" \\
+      --type composio --connection <connectedAccountId> --event <triggerSlug> \\
+      [--toolkit <slug>] [--trigger-config '<json>']
+
+  # CRM-event automation (fires on a CRM object create/update/delete).
+  #   1. dench crm objects list               → objectId
+  #   2. dench crm fields list <object>       → field _id (for --where filters)
+  dench cron create "New company added" --prompt "Research the new company" \\
+      --type crm --object <objectId> --event create|update|delete \\
+      [--where '[{"logic":"AND","conditions":[{"fieldId":"<id>","operator":"equals","value":"x"}]}]'] \\
+      [--where-logic AND|OR]
+
   dench cron update <jobId> [--name N] [--prompt P] [--description D] \\
       [--every X | --cron EXPR | --at ISO] [--enabled true|false] [--overlap …]
 
@@ -529,6 +845,7 @@ Lifecycle:
   dench cron disable <jobId>
   dench cron delete  <jobId>
   dench cron run     <jobId> [--wait] [--json]   # manual fire; --wait blocks until run finishes
+  dench cron secret  <jobId> [--json]            # mint/rotate a signing secret → callable signed URL (any automation type)
 
 Schedule formats:
   --every <duration>   Repeat every N. Accepts 30s, 5m, 2h, 1d, 12h, etc.
@@ -599,6 +916,10 @@ export async function runCronCommand(opts: {
       return await runEnable(ctx, false);
     case "run":
       return await runRunNow(ctx);
+    case "secret":
+      return await runSecret(ctx);
+    case "events":
+      return await runEvents(ctx);
     case "runs":
       return await runRuns(ctx);
     case "history":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.2.6",
+  "version": "2.3.0",
   "description": "Dench agent workspace CLI. v2 unifies auth behind `dench signin`; the legacy `dench login` / `dench onboard` / `dench setup` / `dench what-can-i-do` / `dench register` commands now error with a redirect.",
   "type": "module",
   "bin": {