@dench.com/cli 0.3.4 → 0.3.6

package/cron.ts

@@ -0,0 +1,612 @@
+/**
+ * `dench cron <subcommand>` — CLI surface for managing Convex-native
+ * cron triggers.
+ *
+ * Each cron is a row in the Convex `triggers` table that, when due,
+ * spawns a fresh chat thread (the `target: "chat_turn"` path — new
+ * default) running in YOLO mode and seeded with the cron's prompt as
+ * the first user message. The Vercel cron dispatcher (`/api/cron/dispatch`,
+ * scheduled via `vercel.json` at every minute) walks the
+ * `by_enabled_nextFireAt` index, claims due rows, and fires the
+ * workflow.
+ *
+ * Auth: prefers the unified Dench API key from `DENCH_API_KEY`
+ * (sandbox envVar baked at create time). Falls back to `dench login`
+ * session token. The server-side `requireCronAccess` helper accepts
+ * both formats; we just pass whichever bearer the parent runtime
+ * resolved through `sessionToken`.
+ *
+ * Convex calls go direct via `ConvexHttpClient` (same pattern as
+ * `cli/crm.ts`); `run-now` is the one operation that goes through
+ * the REST API hop (`POST /api/cron/jobs/<id>/run-now`) because it
+ * needs to start a Vercel Workflow which can only be done from a
+ * Next.js route.
+ *
+ * Subcommands:
+ *   list                                 List all cron jobs in the org.
+ *   get <jobId>                          Single job detail.
+ *   create <name> --prompt … --every …   Create a new cron.
+ *   update <jobId> [flags]               Patch any subset of fields.
+ *   delete <jobId> [--force]             Permanently delete.
+ *   enable <jobId>                       Re-arm a paused cron.
+ *   disable <jobId>                      Soft-pause without delete.
+ *   run <jobId> [--wait]                 Manual fire; --wait blocks.
+ *   runs <jobId> [--limit N] [--status]  Run history per trigger.
+ *   history [--limit N]                  Flat history across all crons.
+ *   help                                 Print this help.
+ *
+ * Schedule flags accepted by `create` and `update`:
+ *   --every <duration>   30s | 5m | 2h | 1d | 12h…
+ *   --every-ms <number>  Same, raw milliseconds.
+ *   --cron <expr>        5-field POSIX cron, e.g. "0 9 * * 1-5".
+ *   --at <iso>           ISO 8601 timestamp (one-shot; auto-disable).
+ */
+
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+class CronCliError extends Error {}
+
+type CronCliContext = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  sessionToken?: string;
+};
+
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new CronCliError(error.message);
+    throw error;
+  }
+}
+
+function out(ctx: CronCliContext, value: unknown): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (value === null || value === undefined) {
+    console.log("(empty)");
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+// ─── Auth helpers (mirror cli/agent.ts shape) ─────────────────────────────
+
+function getApiBase(): string {
+  const base = (
+    process.env.DENCH_API_URL ??
+    process.env.DENCH_BASE_URL ??
+    "http://localhost:3000"
+  ).replace(/\/+$/, "");
+  if (!base) {
+    throw new CronCliError(
+      "DENCH_API_URL is not configured. Pass it as an env var or run from a sandbox where it is baked in.",
+    );
+  }
+  return base;
+}
+
+function apiKeyHeaders(token: string): Record<string, string> {
+  if (!token) {
+    throw new CronCliError(
+      "Missing auth token. Provide DENCH_API_KEY in env or run `dench login` first.",
+    );
+  }
+  return {
+    "content-type": "application/json",
+    authorization: `Bearer ${token}`,
+  };
+}
+
+async function postJson(
+  url: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<unknown> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body ?? {}),
+  });
+  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],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return ctx.convex.query(fn, {
+    ...args,
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+  } as never);
+}
+
+async function callMutation(
+  ctx: CronCliContext,
+  fn: Parameters<ConvexHttpClient["mutation"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return ctx.convex.mutation(fn, {
+    ...args,
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+  } as never);
+}
+
+// ─── Schedule flag parser ────────────────────────────────────────────────
+
+const DURATION_RE = /^(\d+)\s*(ms|s|m|h|d)$/i;
+
+export function parseDurationFlagToMs(input: string): number | null {
+  const m = DURATION_RE.exec(input.trim());
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  switch (m[2].toLowerCase()) {
+    case "ms":
+      return n;
+    case "s":
+      return n * 1000;
+    case "m":
+      return n * 60_000;
+    case "h":
+      return n * 3_600_000;
+    case "d":
+      return n * 86_400_000;
+  }
+  return null;
+}
+
+export type CronScheduleSpec =
+  | { kind: "every"; everyMs: number; anchorMs?: number }
+  | { kind: "cron"; expr: string; tz?: string }
+  | { kind: "at"; at: string };
+
+/**
+ * Pull a schedule out of the args, accepting any of `--every`,
+ * `--every-ms`, `--cron`, `--at`. Returns undefined if NONE of those
+ * flags are present (the caller decides whether that's an error).
+ *
+ * `--at` implicitly drops `--every` / `--cron` if both are passed.
+ */
+export function consumeScheduleFlags(args: string[]): CronScheduleSpec | undefined {
+  const at = getFlag(args, "--at");
+  if (at) {
+    const ts = new Date(at).getTime();
+    if (Number.isNaN(ts)) {
+      throw new CronCliError(
+        `--at must be ISO 8601 (got "${at}"). Example: --at 2026-05-04T17:00:00Z`,
+      );
+    }
+    return { kind: "at", at };
+  }
+  const cronExpr = getFlag(args, "--cron");
+  if (cronExpr) {
+    const tz = getFlag(args, "--tz");
+    return { kind: "cron", expr: cronExpr, tz };
+  }
+  const everyRaw = getFlag(args, "--every");
+  const everyMsRaw = getFlag(args, "--every-ms");
+  if (everyMsRaw) {
+    const ms = parseInt(everyMsRaw, 10);
+    if (!Number.isFinite(ms) || ms < 1000) {
+      throw new CronCliError(
+        `--every-ms must be a positive integer >= 1000 (got "${everyMsRaw}")`,
+      );
+    }
+    return { kind: "every", everyMs: ms };
+  }
+  if (everyRaw) {
+    const ms = parseDurationFlagToMs(everyRaw);
+    if (ms == null || ms < 1000) {
+      throw new CronCliError(
+        `--every must be a duration like "30s", "5m", "2h", "1d" (got "${everyRaw}")`,
+      );
+    }
+    return { kind: "every", everyMs: ms };
+  }
+  return undefined;
+}
+
+function formatScheduleForList(schedule: unknown): string {
+  if (!schedule || typeof schedule !== "object") return String(schedule ?? "?");
+  const s = schedule as Record<string, unknown>;
+  if (s.kind === "every" && typeof s.everyMs === "number") {
+    const ms = s.everyMs;
+    if (ms >= 86_400_000) return `every ${Math.round(ms / 86_400_000)}d`;
+    if (ms >= 3_600_000) return `every ${Math.round(ms / 3_600_000)}h`;
+    if (ms >= 60_000) return `every ${Math.round(ms / 60_000)}m`;
+    return `every ${Math.round(ms / 1000)}s`;
+  }
+  if (s.kind === "cron" && typeof s.expr === "string") {
+    return `cron "${s.expr}"${s.tz ? ` (${s.tz})` : ""}`;
+  }
+  if (s.kind === "at" && typeof s.at === "string") return `at ${s.at}`;
+  return JSON.stringify(s);
+}
+
+function formatRowsAsTable(jobs: unknown[]): string {
+  if (jobs.length === 0) return "(no cron jobs)";
+  const rows: Array<[string, string, string, string, string]> = jobs.map(
+    (raw) => {
+      const j = raw as Record<string, unknown>;
+      const id = String(j.id ?? "?");
+      const name = String(j.name ?? "");
+      const enabled = j.enabled === false ? "off" : "on";
+      const sched = formatScheduleForList(
+        (j as { schedule?: unknown }).schedule,
+      );
+      const next =
+        typeof (j.state as Record<string, unknown> | undefined)?.nextRunAtMs ===
+        "number"
+          ? new Date(
+              (j.state as Record<string, unknown>).nextRunAtMs as number,
+            ).toISOString()
+          : "—";
+      return [id, enabled, name.slice(0, 30), sched, next];
+    },
+  );
+  const widths = [
+    Math.max(...rows.map((r) => r[0].length), 8),
+    3,
+    Math.max(...rows.map((r) => r[2].length), 4),
+    Math.max(...rows.map((r) => r[3].length), 8),
+    Math.max(...rows.map((r) => r[4].length), 24),
+  ];
+  const header = ["job id", "en", "name", "schedule", "next fire"]
+    .map((h, i) => h.padEnd(widths[i]))
+    .join("  ");
+  const lines = rows.map((r) =>
+    r.map((cell, i) => cell.padEnd(widths[i])).join("  "),
+  );
+  return [header, "-".repeat(header.length), ...lines].join("\n");
+}
+
+// ─── Subcommands ──────────────────────────────────────────────────────────
+
+const listCronJobsRef = makeFunctionReference<"query">(
+  "functions/triggers:listCronJobs",
+);
+const getCronJobRef = makeFunctionReference<"query">(
+  "functions/triggers:getCronJob",
+);
+const listCronRunsRef = makeFunctionReference<"query">(
+  "functions/triggers:listCronRuns",
+);
+const listOrgCronRunHistoryRef = makeFunctionReference<"query">(
+  "functions/triggers:listOrgCronRunHistory",
+);
+const createCronTriggerRef = makeFunctionReference<"mutation">(
+  "functions/triggers:createCronTrigger",
+);
+const updateCronTriggerRef = makeFunctionReference<"mutation">(
+  "functions/triggers:updateCronTrigger",
+);
+const deleteCronTriggerRef = makeFunctionReference<"mutation">(
+  "functions/triggers:deleteCronTrigger",
+);
+const setCronEnabledRef = makeFunctionReference<"mutation">(
+  "functions/triggers:setCronEnabled",
+);
+
+async function runList(ctx: CronCliContext): Promise<void> {
+  const enabledOnly = hasFlag(ctx.args, "--enabled-only");
+  const result = (await callQuery(ctx, listCronJobsRef, { enabledOnly })) as {
+    jobs: unknown[];
+  };
+  if (ctx.jsonOutput) {
+    out(ctx, result);
+    return;
+  }
+  console.log(formatRowsAsTable(result.jobs ?? []));
+}
+
+async function runGet(ctx: CronCliContext): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const job = await callQuery(ctx, getCronJobRef, { jobId });
+  out(ctx, job);
+}
+
+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 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)");
+  }
+  const description = getFlag(ctx.args, "--description");
+  const overlapPolicy = getFlag(ctx.args, "--overlap") as
+    | "skip"
+    | "queue"
+    | "kill_old"
+    | undefined;
+  if (
+    overlapPolicy &&
+    !["skip", "queue", "kill_old"].includes(overlapPolicy)
+  ) {
+    throw new CronCliError(
+      `--overlap must be one of skip|queue|kill_old (got "${overlapPolicy}")`,
+    );
+  }
+  const disabled = hasFlag(ctx.args, "--disabled");
+  const deleteAfterRun = hasFlag(ctx.args, "--delete-after-run");
+  const target = getFlag(ctx.args, "--target") as
+    | "chat_turn"
+    | "agent_run"
+    | undefined;
+  if (target && !["chat_turn", "agent_run"].includes(target)) {
+    throw new CronCliError(
+      `--target must be chat_turn|agent_run (got "${target}")`,
+    );
+  }
+  const schedule = consumeScheduleFlags(ctx.args);
+  if (!schedule) {
+    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',
+    );
+  }
+  const result = await callMutation(ctx, createCronTriggerRef, {
+    name,
+    prompt,
+    schedule,
+    description,
+    overlapPolicy,
+    enabled: disabled ? false : undefined,
+    deleteAfterRun: deleteAfterRun ? true : undefined,
+    target,
+  });
+  out(ctx, result);
+}
+
+async function runUpdate(ctx: CronCliContext): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const name = getFlag(ctx.args, "--name");
+  const prompt = getFlag(ctx.args, "--prompt");
+  const description = getFlag(ctx.args, "--description");
+  const overlapPolicy = getFlag(ctx.args, "--overlap") as
+    | "skip"
+    | "queue"
+    | "kill_old"
+    | undefined;
+  const enabledRaw = getFlag(ctx.args, "--enabled");
+  let enabled: boolean | undefined;
+  if (enabledRaw !== undefined) {
+    if (enabledRaw === "true") enabled = true;
+    else if (enabledRaw === "false") enabled = false;
+    else {
+      throw new CronCliError(
+        `--enabled must be true|false (got "${enabledRaw}")`,
+      );
+    }
+  }
+  const schedule = consumeScheduleFlags(ctx.args);
+  const result = await callMutation(ctx, updateCronTriggerRef, {
+    jobId,
+    name,
+    prompt,
+    description,
+    overlapPolicy,
+    enabled,
+    schedule,
+  });
+  out(ctx, result);
+}
+
+async function runDelete(ctx: CronCliContext): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const result = await callMutation(ctx, deleteCronTriggerRef, { jobId });
+  out(ctx, result);
+}
+
+async function runEnable(ctx: CronCliContext, enabled: boolean): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const result = await callMutation(ctx, setCronEnabledRef, {
+    jobId,
+    enabled,
+  });
+  out(ctx, result);
+}
+
+async function runRunNow(ctx: CronCliContext): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const wait = hasFlag(ctx.args, "--wait");
+  const url = `${getApiBase()}/api/cron/jobs/${encodeURIComponent(jobId)}/run-now`;
+  const fired = (await postJson(
+    url,
+    apiKeyHeaders(ctx.sessionToken ?? ""),
+    {},
+  )) as { runId?: string; threadId?: string | null };
+  if (!wait) {
+    out(ctx, fired);
+    return;
+  }
+  // Poll the run status until terminal, with a 5-minute safety timeout.
+  if (!fired.runId) {
+    out(ctx, fired);
+    return;
+  }
+  const start = Date.now();
+  const TIMEOUT_MS = 5 * 60_000;
+  while (Date.now() - start < TIMEOUT_MS) {
+    const runs = (await callQuery(ctx, listCronRunsRef, {
+      jobId,
+      limit: 5,
+    })) 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 });
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+  }
+  out(ctx, { ...fired, status: "wait_timeout", waitedMs: TIMEOUT_MS });
+}
+
+async function runRuns(ctx: CronCliContext): Promise<void> {
+  const jobId = shift(ctx.args, "job id");
+  const limitRaw = getFlag(ctx.args, "--limit");
+  const limit = limitRaw ? parseInt(limitRaw, 10) : 50;
+  const status = getFlag(ctx.args, "--status");
+  const result = (await callQuery(ctx, listCronRunsRef, { jobId, limit })) as {
+    entries: Array<Record<string, unknown>>;
+  };
+  const filtered = status
+    ? {
+        entries: result.entries.filter((e) => e.status === status),
+      }
+    : result;
+  out(ctx, filtered);
+}
+
+async function runHistory(ctx: CronCliContext): Promise<void> {
+  const limitRaw = getFlag(ctx.args, "--limit");
+  const limit = limitRaw ? parseInt(limitRaw, 10) : 50;
+  const status = getFlag(ctx.args, "--status");
+  const result = (await callQuery(ctx, listOrgCronRunHistoryRef, {
+    limit,
+  })) as { entries: Array<Record<string, unknown>> };
+  const filtered = status
+    ? {
+        entries: result.entries.filter((e) => e.status === status),
+      }
+    : result;
+  out(ctx, filtered);
+}
+
+// ─── Help ─────────────────────────────────────────────────────────────────
+
+function cronHelp(): void {
+  console.log(`Usage: dench cron <subcommand>
+
+Browse:
+  dench cron list [--enabled-only] [--json]
+  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]
+
+Create / update (one of --every / --cron / --at is required for create):
+  dench cron create "Daily standup digest" \\
+      --prompt "Pull yesterday's commits + Slack #standup msgs and post a summary…" \\
+      --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
+      [--disabled]                        # default: enabled
+      [--delete-after-run]                # one-shot at-schedule; default false
+      [--target chat_turn|agent_run]      # default: chat_turn (fires a fresh chat thread)
+      [--json]
+
+  dench cron update <jobId> [--name N] [--prompt P] [--description D] \\
+      [--every X | --cron EXPR | --at ISO] [--enabled true|false] [--overlap …]
+
+Lifecycle:
+  dench cron enable  <jobId>
+  dench cron disable <jobId>
+  dench cron delete  <jobId>
+  dench cron run     <jobId> [--wait] [--json]   # manual fire; --wait blocks until run finishes
+
+Schedule formats:
+  --every <duration>   Repeat every N. Accepts 30s, 5m, 2h, 1d, 12h, etc.
+  --every-ms <number>  Same, raw milliseconds (>= 1000ms).
+  --cron <expr>        5-field POSIX cron (minute hour day-of-month month day-of-week).
+                       Examples: "*/30 * * * *" (every 30 min), "0 9 * * 1-5" (weekdays 9am)
+  --tz <iana>          Optional timezone for --cron (e.g. "America/New_York"). Default UTC.
+  --at <iso>           ISO 8601 timestamp for a one-shot fire. Auto-disables after firing.
+
+Examples:
+  # Remind me to drink water every 30 min
+  dench cron create "Water reminder" --prompt "Send a friendly nudge to drink water." --every 30m
+
+  # Daily 9am standup digest from CRM + workspace
+  dench cron create "Standup digest" \\
+      --prompt "Pull yesterday's CRM Activity entries and post a summary to /workspace/standups/$(date +%%Y-%%m-%%d).md" \\
+      --cron "0 9 * * 1-5"
+
+  # One-shot launch
+  dench cron create "May 4 launch" \\
+      --prompt "Send launch tweet from @denchhq quoting today's blog post." \\
+      --at 2026-05-04T17:00:00Z
+
+  # Pause and re-enable
+  dench cron disable <jobId>
+  dench cron enable  <jobId>
+
+Auth: prefers DENCH_API_KEY (sandbox envVar). Falls back to a session token from
+\`dench login\` for local terminals. The Bearer token must carry either
+\`crons:read\` (queries) or \`crons:write\` (mutations) scope, or the wildcard \`*\`.
+`);
+}
+
+// ─── Entry point ──────────────────────────────────────────────────────────
+
+export async function runCronCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  sessionToken?: string;
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonOutput = hasFlag(args, "--json");
+  const ctx: CronCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput,
+    sessionToken: opts.sessionToken,
+  };
+  const subcommand = args.shift();
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    cronHelp();
+    return;
+  }
+  switch (subcommand) {
+    case "list":
+      return await runList(ctx);
+    case "get":
+      return await runGet(ctx);
+    case "create":
+      return await runCreate(ctx);
+    case "update":
+      return await runUpdate(ctx);
+    case "delete":
+      return await runDelete(ctx);
+    case "enable":
+      return await runEnable(ctx, true);
+    case "disable":
+      return await runEnable(ctx, false);
+    case "run":
+      return await runRunNow(ctx);
+    case "runs":
+      return await runRuns(ctx);
+    case "history":
+      return await runHistory(ctx);
+    default:
+      throw new CronCliError(
+        `Unknown cron subcommand: ${subcommand}. Run 'dench cron help'.`,
+      );
+  }
+}