@dench.com/cli 0.4.8 → 2.0.0

package/README.md

@@ -23,7 +23,7 @@ dench login --name "AI Agent - Billing Repo"
 to lowercase snake_case before send (e.g. `--kind "Claude Code"` becomes
 `claude_code`).
 
-The default backend is `https://dench.dev` (production). Use `dench backend`
+The default backend is `https://dench.com` (production). Use `dench backend`
 to switch:
 
 ```bash

package/agent-config.ts

@@ -0,0 +1,645 @@
+/**
+ * `dench identity / organisation / user / heartbeat / bootstrap /
+ *  model / daily / mem aggregate` — CLI surface for the OpenClaw-
+ * parity self-updating harness.
+ *
+ * Mirrors the auth pattern in `cli/cron.ts`:
+ *   • Convex calls go through the shared `ConvexHttpClient`.
+ *   • Auth resolves via `sessionToken` — accepts either a
+ *     `dch_agent_*` agent session token (from `dench login`) or a
+ *     unified Dench API key (`DENCH_API_KEY` baked into sandbox
+ *     envVars). Server-side `requireCronAccess` dispatches on
+ *     bearer prefix.
+ *
+ * Subcommands:
+ *   identity show | edit
+ *   organisation show | edit
+ *   user show | edit
+ *   tools show | notes-edit
+ *   memory show | append <text> | set                   (MEMORY.md aggregate)
+ *   heartbeat status | enable | disable | interval <duration> |
+ *             instructions
+ *   bootstrap status | complete | reopen | template
+ *   model default <id> | model default clear |
+ *   model thread <threadId> <id> | model thread <threadId> clear
+ *   daily today | daily show <YYYY-MM-DD> | daily append <text>
+ *
+ * `edit` / `notes-edit` / `instructions` / `template` open the
+ * user's `$EDITOR` (default `vi`) to capture the new body. The
+ * stdin path is also supported via `--stdin`, useful in scripts.
+ */
+
+import { execSync } from "node:child_process";
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ConvexHttpClient } from "convex/browser";
+import { api } from "@/../convex/_generated/api";
+import { CliArgError, getFlag, hasFlag } from "./lib/cli-args";
+
+class AgentConfigCliError extends Error {}
+
+type CliCtx = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  sessionToken?: string;
+};
+
+function out(ctx: CliCtx, value: unknown): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (typeof value === "string") {
+    console.log(value);
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+async function runQuery(
+  ctx: CliCtx,
+  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 runMutation(
+  ctx: CliCtx,
+  fn: Parameters<ConvexHttpClient["mutation"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return ctx.convex.mutation(fn, {
+    ...args,
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+  } as never);
+}
+
+// ── Editor helpers ────────────────────────────────────────────────────────
+
+async function readContentFromStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", reject);
+  });
+}
+
+function openEditor(initial: string, suffix: string): string {
+  const editor = process.env.EDITOR?.trim() || "vi";
+  const dir = join(tmpdir(), "dench-agent-cli");
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${Date.now()}-${suffix}.md`);
+  writeFileSync(file, initial, "utf8");
+  try {
+    execSync(`${editor} ${file}`, { stdio: "inherit" });
+    return readFileSync(file, "utf8");
+  } finally {
+    try {
+      unlinkSync(file);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
+async function resolveContent(args: string[]): Promise<string> {
+  if (hasFlag(args, "--stdin")) {
+    const text = await readContentFromStdin();
+    if (!text.trim().length) {
+      throw new AgentConfigCliError("--stdin received empty input");
+    }
+    return text;
+  }
+  const inline = getFlag(args, "--content");
+  if (inline) return inline;
+  // Otherwise launch the editor with the existing content as the
+  // starting point. Caller is expected to call this AFTER fetching
+  // the current value.
+  throw new AgentConfigCliError(
+    "No content provided. Use --content '<markdown>' or --stdin or run without flags to launch $EDITOR.",
+  );
+}
+
+// ── Loader (one round-trip for all reads + display) ──────────────────────
+
+async function loadAgentConfig(ctx: CliCtx): Promise<{
+  agentConfig: {
+    identity: { content: string; updatedAt: number } | null;
+    organisation: { content: string; updatedAt: number } | null;
+    memoryAggregate: { content: string; updatedAt: number } | null;
+    toolsNotes: { content: string; updatedAt: number } | null;
+    bootstrap: {
+      completed: boolean;
+      completedAt?: number;
+      template?: string;
+    };
+    heartbeat: {
+      enabled: boolean;
+      intervalMs: number;
+      instructions: string;
+      lastFiredAt?: number;
+    };
+  };
+  userProfile: { content: string; updatedAt: number } | null;
+  organizationId: string;
+}> {
+  const result = (await runQuery(ctx, api.functions.agentConfig.getAgentConfig)) as {
+    agentConfig: {
+      identity: { content: string; updatedAt: number } | null;
+      organisation: { content: string; updatedAt: number } | null;
+      memoryAggregate: { content: string; updatedAt: number } | null;
+      toolsNotes: { content: string; updatedAt: number } | null;
+      bootstrap: {
+        completed: boolean;
+        completedAt?: number;
+        template?: string;
+      };
+      heartbeat: {
+        enabled: boolean;
+        intervalMs: number;
+        instructions: string;
+        lastFiredAt?: number;
+      };
+    };
+    userProfile: { content: string; updatedAt: number } | null;
+    organizationId: string;
+  };
+  return result;
+}
+
+// ── Per-section handlers ─────────────────────────────────────────────────
+
+async function handleSimpleMagicFile(
+  ctx: CliCtx,
+  args: string[],
+  opts: {
+    label: "identity" | "organisation" | "tools" | "user" | "memory";
+    field: "identity" | "organisation" | "toolsNotes" | "memoryAggregate";
+    perMember?: boolean;
+  },
+): Promise<void> {
+  const sub = args[0];
+  if (!sub || sub === "show") {
+    const config = await loadAgentConfig(ctx);
+    const value =
+      opts.field === "memoryAggregate"
+        ? config.agentConfig.memoryAggregate
+        : opts.field === "toolsNotes"
+          ? config.agentConfig.toolsNotes
+          : opts.field === "identity"
+            ? config.agentConfig.identity
+            : opts.field === "organisation"
+              ? config.agentConfig.organisation
+              : null;
+    if (opts.perMember) {
+      out(ctx, config.userProfile?.content ?? "(empty)");
+      return;
+    }
+    out(ctx, value?.content ?? "(empty)");
+    return;
+  }
+  if (sub === "edit" || sub === "set") {
+    let content: string;
+    if (hasFlag(args, "--stdin") || getFlag(args, "--content")) {
+      content = await resolveContent(args);
+    } else {
+      const config = await loadAgentConfig(ctx);
+      const initial = opts.perMember
+        ? config.userProfile?.content ?? ""
+        : opts.field === "memoryAggregate"
+          ? config.agentConfig.memoryAggregate?.content ?? ""
+          : opts.field === "toolsNotes"
+            ? config.agentConfig.toolsNotes?.content ?? ""
+            : opts.field === "identity"
+              ? config.agentConfig.identity?.content ?? ""
+              : config.agentConfig.organisation?.content ?? "";
+      content = openEditor(initial, opts.label);
+    }
+    if (!content.trim().length) {
+      throw new AgentConfigCliError(`${opts.label} content cannot be empty`);
+    }
+    const fn = (() => {
+      switch (opts.field) {
+        case "identity":
+          return api.functions.agentConfig.updateIdentity;
+        case "organisation":
+          return api.functions.agentConfig.updateOrganisation;
+        case "toolsNotes":
+          return api.functions.agentConfig.updateToolsNotes;
+        case "memoryAggregate":
+          return api.functions.agentConfig.updateMemory;
+      }
+    })();
+    if (opts.perMember) {
+      await runMutation(ctx, api.functions.agentConfig.updateUserProfile, {
+        content,
+      });
+      out(ctx, { ok: true, kind: "user_profile" });
+      return;
+    }
+    if (opts.field === "memoryAggregate") {
+      await runMutation(ctx, api.functions.agentConfig.updateMemory, {
+        content,
+        append: hasFlag(args, "--append"),
+      });
+      out(ctx, { ok: true, kind: "memory" });
+      return;
+    }
+    await runMutation(ctx, fn, { content });
+    out(ctx, { ok: true, kind: opts.label });
+    return;
+  }
+  throw new AgentConfigCliError(
+    `Unknown ${opts.label} subcommand: "${sub}". Try "show" or "edit".`,
+  );
+}
+
+function formatInterval(ms: number): string {
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  if (ms < 60 * 60_000) return `${Math.round(ms / 60_000)}m`;
+  if (ms < 24 * 60 * 60_000) {
+    const hours = ms / (60 * 60_000);
+    return Number.isInteger(hours) ? `${hours}h` : `${hours.toFixed(1)}h`;
+  }
+  return `${(ms / (24 * 60 * 60_000)).toFixed(1)}d`;
+}
+
+const DURATION_RE = /^(\d+)\s*(ms|s|m|h|d)$/i;
+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;
+}
+
+async function handleHeartbeat(ctx: CliCtx, args: string[]): Promise<void> {
+  const sub = args[0];
+  if (!sub || sub === "status" || sub === "show") {
+    const config = await loadAgentConfig(ctx);
+    const hb = config.agentConfig.heartbeat;
+    if (ctx.jsonOutput) {
+      out(ctx, hb);
+      return;
+    }
+    out(
+      ctx,
+      `enabled=${hb.enabled} interval=${formatInterval(hb.intervalMs)}\n\n${hb.instructions}`,
+    );
+    return;
+  }
+  if (sub === "enable") {
+    await runMutation(ctx, api.functions.agentConfig.updateHeartbeat, {
+      enabled: true,
+    });
+    out(ctx, { ok: true, enabled: true });
+    return;
+  }
+  if (sub === "disable") {
+    await runMutation(ctx, api.functions.agentConfig.updateHeartbeat, {
+      enabled: false,
+    });
+    out(ctx, { ok: true, enabled: false });
+    return;
+  }
+  if (sub === "interval") {
+    const raw = args[1];
+    if (!raw) {
+      throw new AgentConfigCliError(
+        "Usage: dench heartbeat interval <duration> (e.g. 30m, 2h, 1d)",
+      );
+    }
+    const ms = parseDurationFlagToMs(raw);
+    if (!ms) throw new AgentConfigCliError(`Invalid duration: ${raw}`);
+    await runMutation(ctx, api.functions.agentConfig.updateHeartbeat, {
+      intervalMs: ms,
+    });
+    out(ctx, { ok: true, intervalMs: ms, label: formatInterval(ms) });
+    return;
+  }
+  if (sub === "instructions" || sub === "edit") {
+    let content: string;
+    if (hasFlag(args, "--stdin") || getFlag(args, "--content")) {
+      content = await resolveContent(args);
+    } else {
+      const config = await loadAgentConfig(ctx);
+      content = openEditor(
+        config.agentConfig.heartbeat.instructions,
+        "heartbeat",
+      );
+    }
+    if (!content.trim().length) {
+      throw new AgentConfigCliError("heartbeat instructions cannot be empty");
+    }
+    await runMutation(ctx, api.functions.agentConfig.updateHeartbeat, {
+      instructions: content,
+    });
+    out(ctx, { ok: true, kind: "heartbeat" });
+    return;
+  }
+  throw new AgentConfigCliError(
+    `Unknown heartbeat subcommand: "${sub}". Try "status", "enable", "disable", "interval <duration>", "instructions".`,
+  );
+}
+
+async function handleBootstrap(ctx: CliCtx, args: string[]): Promise<void> {
+  const sub = args[0];
+  if (!sub || sub === "status" || sub === "show") {
+    const config = await loadAgentConfig(ctx);
+    out(
+      ctx,
+      ctx.jsonOutput
+        ? config.agentConfig.bootstrap
+        : `completed=${config.agentConfig.bootstrap.completed}${
+            config.agentConfig.bootstrap.completedAt
+              ? ` at ${new Date(config.agentConfig.bootstrap.completedAt).toISOString()}`
+              : ""
+          }`,
+    );
+    return;
+  }
+  if (sub === "complete") {
+    await runMutation(ctx, api.functions.agentConfig.completeBootstrap, {
+      completed: true,
+    });
+    out(ctx, { ok: true, completed: true });
+    return;
+  }
+  if (sub === "reopen") {
+    await runMutation(ctx, api.functions.agentConfig.completeBootstrap, {
+      completed: false,
+    });
+    out(ctx, { ok: true, completed: false });
+    return;
+  }
+  if (sub === "template") {
+    let content: string;
+    if (hasFlag(args, "--stdin") || getFlag(args, "--content")) {
+      content = await resolveContent(args);
+    } else {
+      const config = await loadAgentConfig(ctx);
+      content = openEditor(
+        config.agentConfig.bootstrap.template ?? "",
+        "bootstrap",
+      );
+    }
+    if (!content.trim().length) {
+      throw new AgentConfigCliError("bootstrap template cannot be empty");
+    }
+    await runMutation(ctx, api.functions.agentConfig.updateBootstrapTemplate, {
+      content,
+    });
+    out(ctx, { ok: true, kind: "bootstrap_template" });
+    return;
+  }
+  throw new AgentConfigCliError(
+    `Unknown bootstrap subcommand: "${sub}". Try "status", "complete", "reopen", "template".`,
+  );
+}
+
+async function handleModel(ctx: CliCtx, args: string[]): Promise<void> {
+  const sub = args[0];
+  if (sub === "default") {
+    const arg = args[1];
+    if (!arg || arg === "show") {
+      const config = await loadAgentConfig(ctx);
+      // org default lives outside agentConfig — use the same query
+      // but pull from a separate getMyOrganization call. For now we
+      // surface "(use the dashboard for the current value)".
+      out(
+        ctx,
+        ctx.jsonOutput
+          ? { organizationId: config.organizationId }
+          : "Use `dench identity show` and your settings page to view the active default; this command sets the value.",
+      );
+      return;
+    }
+    if (arg === "clear") {
+      await runMutation(ctx, api.functions.agentConfig.setDefaultChatModelV2, {
+        modelId: null,
+      });
+      out(ctx, { ok: true, defaultChatModelId: null });
+      return;
+    }
+    await runMutation(ctx, api.functions.agentConfig.setDefaultChatModelV2, {
+      modelId: arg,
+    });
+    out(ctx, { ok: true, defaultChatModelId: arg });
+    return;
+  }
+  if (sub === "thread") {
+    const threadId = args[1];
+    const target = args[2];
+    if (!threadId || !target) {
+      throw new AgentConfigCliError(
+        "Usage: dench model thread <threadId> <modelId|clear>",
+      );
+    }
+    if (target === "clear") {
+      await runMutation(ctx, api.functions.agentConfig.setThreadModelOverride, {
+        threadId: threadId as never,
+        modelId: null,
+      });
+      out(ctx, { ok: true, threadId, modelOverride: null });
+      return;
+    }
+    await runMutation(ctx, api.functions.agentConfig.setThreadModelOverride, {
+      threadId: threadId as never,
+      modelId: target,
+    });
+    out(ctx, { ok: true, threadId, modelOverride: target });
+    return;
+  }
+  throw new AgentConfigCliError(
+    `Unknown model subcommand: "${sub}". Try "default <id|clear>" or "thread <threadId> <id|clear>".`,
+  );
+}
+
+// ── Entry points consumed by cli/dench.ts ────────────────────────────────
+
+export async function runIdentityCommand(ctx: CliCtx): Promise<void> {
+  await handleSimpleMagicFile(ctx, ctx.args, {
+    label: "identity",
+    field: "identity",
+  });
+}
+
+export async function runOrganisationCommand(ctx: CliCtx): Promise<void> {
+  await handleSimpleMagicFile(ctx, ctx.args, {
+    label: "organisation",
+    field: "organisation",
+  });
+}
+
+export async function runUserCommand(ctx: CliCtx): Promise<void> {
+  await handleSimpleMagicFile(ctx, ctx.args, {
+    label: "user",
+    field: "identity", // unused (perMember=true)
+    perMember: true,
+  });
+}
+
+export async function runToolsCommand(ctx: CliCtx): Promise<void> {
+  await handleSimpleMagicFile(ctx, ctx.args, {
+    label: "tools",
+    field: "toolsNotes",
+  });
+}
+
+/**
+ * Aggregate-MEMORY operations (separate from `dench memory
+ * search/save` which still hit `workspaceMemories`). Subcommands:
+ *   show | append <text> | set
+ */
+export async function runMemoryAggregateCommand(ctx: CliCtx): Promise<void> {
+  const sub = ctx.args[0];
+  if (!sub || sub === "show") {
+    const config = await loadAgentConfig(ctx);
+    out(ctx, config.agentConfig.memoryAggregate?.content ?? "(empty)");
+    return;
+  }
+  if (sub === "append") {
+    const text = ctx.args.slice(1).join(" ").trim();
+    if (!text)
+      throw new AgentConfigCliError("Usage: dench mem append <text>");
+    await runMutation(ctx, api.functions.agentConfig.updateMemory, {
+      content: text,
+      append: true,
+    });
+    out(ctx, { ok: true, kind: "memory_aggregate", appended: true });
+    return;
+  }
+  if (sub === "set" || sub === "edit") {
+    let content: string;
+    if (hasFlag(ctx.args, "--stdin") || getFlag(ctx.args, "--content")) {
+      content = await resolveContent(ctx.args);
+    } else {
+      const config = await loadAgentConfig(ctx);
+      content = openEditor(
+        config.agentConfig.memoryAggregate?.content ?? "",
+        "memory",
+      );
+    }
+    if (!content.trim().length) {
+      throw new AgentConfigCliError("memory cannot be empty");
+    }
+    await runMutation(ctx, api.functions.agentConfig.updateMemory, {
+      content,
+      append: false,
+    });
+    out(ctx, { ok: true, kind: "memory_aggregate" });
+    return;
+  }
+  throw new AgentConfigCliError(
+    `Unknown mem subcommand: "${sub}". Try "show", "append <text>", "set".`,
+  );
+}
+
+export async function runHeartbeatCommand(ctx: CliCtx): Promise<void> {
+  await handleHeartbeat(ctx, ctx.args);
+}
+
+export async function runBootstrapCommand(ctx: CliCtx): Promise<void> {
+  await handleBootstrap(ctx, ctx.args);
+}
+
+export async function runModelCommand(ctx: CliCtx): Promise<void> {
+  await handleModel(ctx, ctx.args);
+}
+
+/**
+ * Daily activity log subcommands (real fileTree files under
+ * `/workspace/daily/`). Today / show <YYYY-MM-DD> read the inline
+ * cache; append delegates to the agent action so timestamps and
+ * heading wrappers stay consistent.
+ */
+export async function runDailyCommand(ctx: CliCtx): Promise<void> {
+  const sub = ctx.args[0];
+  if (!sub || sub === "today") {
+    const today = new Date();
+    const yyyy = today.getUTCFullYear();
+    const mm = String(today.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(today.getUTCDate()).padStart(2, "0");
+    const path = `/daily/${yyyy}-${mm}-${dd}.md`;
+    // Daily logs are real files — fetch via the workspace file API
+    // hop so the same auth (Convex Auth or API key) works.
+    out(
+      ctx,
+      ctx.jsonOutput
+        ? { path }
+        : `Today's daily log lives at ${path}. Use \`dench fs cat ${path}\` to read it, or open it in the workspace UI.`,
+    );
+    return;
+  }
+  if (sub === "show") {
+    const date = ctx.args[1];
+    if (!date) {
+      throw new AgentConfigCliError(
+        "Usage: dench daily show <YYYY-MM-DD>",
+      );
+    }
+    out(
+      ctx,
+      ctx.jsonOutput
+        ? { path: `/daily/${date}.md` }
+        : `Daily log for ${date} lives at /daily/${date}.md. Use \`dench fs cat\` to read it.`,
+    );
+    return;
+  }
+  if (sub === "append") {
+    throw new AgentConfigCliError(
+      "Daily append is currently only available via the agent's `append_daily_log` tool. Use the chat to log entries with timestamps.",
+    );
+  }
+  throw new AgentConfigCliError(
+    `Unknown daily subcommand: "${sub}". Try "today", "show <YYYY-MM-DD>".`,
+  );
+}
+
+export function printAgentConfigCliHelp(): void {
+  console.log(
+    `Self-updating agent harness:
+
+  dench identity show | edit                        IDENTITY.md (org-wide)
+  dench organisation show | edit                    ORGANISATION.md
+  dench user show | edit                            USER.md (per-member)
+  dench tools show | notes-edit                     TOOLS.md notes section
+  dench mem show | append <text> | set              MEMORY.md aggregate
+  dench heartbeat status | enable | disable         Heartbeat cron
+                  | interval <30m|1h|…> | instructions
+  dench bootstrap status | complete | reopen | template
+  dench model default <id|clear> | model thread <threadId> <id|clear>
+  dench daily today | show <YYYY-MM-DD>              Activity log paths
+
+Editing flags:
+  --content "<markdown>"   Inline body
+  --stdin                  Read body from stdin
+  (default)                Launch $EDITOR ($EDITOR or vi)
+
+Auth:
+  --json                   Machine-readable output
+  Bearer token via DENCH_API_KEY or \`dench login\` session.`,
+  );
+}
+
+// Re-export error so callers can branch on it
+export { AgentConfigCliError, CliArgError };