@dench.com/cli 0.2.0

package/crm.ts

@@ -0,0 +1,1402 @@
+/**
+ * `dench crm <subcommand>` — CLI surface for the Convex CRM.
+ *
+ * All operations resolve via the unified Dench API key baked into the
+ * sandbox (DENCH_API_KEY) or the locally-stored session token. Talks to
+ * the Convex deployment URL stored in the active session.
+ *
+ * This is a thin command dispatcher; the heavy lifting lives in
+ * convex/functions/crm/* and convex/lib/crm/*.
+ *
+ * The full surface mirrors the plan's "dench-cli CRM surface" section:
+ *   crm objects   list / get / create / update / delete / rename
+ *   crm fields    list / create / update / delete / reorder
+ *   crm entries   list / get / create / update / delete / bulk-delete
+ *   crm cells     get / set / append
+ *   crm query     <object> --where … --select … --sort … --limit …
+ *   crm aggregate <object> --field …
+ *   crm batch     --file ops.jsonl
+ *   crm statuses  list / set
+ *   crm docs      list / create / link
+ *   crm actions   list / run / runs
+ */
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  parseJson as parseJsonRaw,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+type JsonRecord = Record<string, unknown>;
+
+type CrmCliContext = {
+  convex: ConvexHttpClient;
+  args: string[];
+  jsonOutput: boolean;
+  /**
+   * Agent session token (`dch_agent_*`) minted by `dench login`. Sent
+   * with every Convex call so the server-side `requireCrmAccess` helper
+   * can resolve the caller's organization without a Convex Auth cookie.
+   */
+  sessionToken?: string;
+};
+
+// Adapt the shared helpers to throw CrmCliError so existing call sites
+// don't need to change their try/catch shape.
+class CrmCliError extends Error {}
+
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    throw error;
+  }
+}
+
+function parseJson(value: string | undefined): unknown {
+  try {
+    return parseJsonRaw(value);
+  } catch (error) {
+    if (error instanceof CliArgError) throw new CrmCliError(error.message);
+    throw error;
+  }
+}
+
+async function callQuery(
+  ctx: CrmCliContext,
+  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: CrmCliContext,
+  fn: Parameters<ConvexHttpClient["mutation"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return ctx.convex.mutation(fn, {
+    ...args,
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+  } as never);
+}
+
+function out(ctx: CrmCliContext, value: unknown): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (value === null || value === undefined) {
+    console.log("(empty)");
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      console.log("(no rows)");
+      return;
+    }
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+const api = {
+  transaction: {
+    begin: makeFunctionReference<"mutation">(
+      "functions/crm/transaction:begin",
+    ),
+    addOp: makeFunctionReference<"mutation">(
+      "functions/crm/transaction:addOp",
+    ),
+    commit: makeFunctionReference<"mutation">(
+      "functions/crm/transaction:commit",
+    ),
+    abort: makeFunctionReference<"mutation">(
+      "functions/crm/transaction:abort",
+    ),
+    inspect: makeFunctionReference<"query">(
+      "functions/crm/transaction:inspect",
+    ),
+  },
+  reports: {
+    generate: makeFunctionReference<"query">(
+      "functions/crm/reports:generate",
+    ),
+  },
+  enrich: {
+    requestCellEnrichment: makeFunctionReference<"mutation">(
+      "functions/crm/enrich:requestCellEnrichment",
+    ),
+    requestObjectEnrichment: makeFunctionReference<"mutation">(
+      "functions/crm/enrich:requestObjectEnrichment",
+    ),
+  },
+  objects: {
+    list: makeFunctionReference<"query">("functions/crm/objects:list"),
+    get: makeFunctionReference<"query">("functions/crm/objects:get"),
+    create: makeFunctionReference<"mutation">("functions/crm/objects:create"),
+    update: makeFunctionReference<"mutation">("functions/crm/objects:update"),
+    rename: makeFunctionReference<"mutation">("functions/crm/objects:rename"),
+    remove: makeFunctionReference<"mutation">("functions/crm/objects:remove"),
+  },
+  fields: {
+    list: makeFunctionReference<"query">("functions/crm/fields:list"),
+    create: makeFunctionReference<"mutation">("functions/crm/fields:create"),
+    update: makeFunctionReference<"mutation">("functions/crm/fields:update"),
+    remove: makeFunctionReference<"mutation">("functions/crm/fields:remove"),
+    reorder: makeFunctionReference<"mutation">(
+      "functions/crm/fields:reorder",
+    ),
+  },
+  entries: {
+    list: makeFunctionReference<"query">("functions/crm/entries:list"),
+    get: makeFunctionReference<"query">("functions/crm/entries:get"),
+    create: makeFunctionReference<"mutation">(
+      "functions/crm/entries:create",
+    ),
+    update: makeFunctionReference<"mutation">(
+      "functions/crm/entries:update",
+    ),
+    remove: makeFunctionReference<"mutation">(
+      "functions/crm/entries:remove",
+    ),
+    bulkDelete: makeFunctionReference<"mutation">(
+      "functions/crm/entries:bulkDelete",
+    ),
+  },
+  cells: {
+    get: makeFunctionReference<"query">("functions/crm/cells:get"),
+    set: makeFunctionReference<"mutation">("functions/crm/cells:set"),
+    append: makeFunctionReference<"mutation">(
+      "functions/crm/cells:append",
+    ),
+  },
+  query: {
+    queryEntries: makeFunctionReference<"query">(
+      "functions/crm/query:queryEntries",
+    ),
+    aggregate: makeFunctionReference<"query">("functions/crm/query:aggregate"),
+    search: makeFunctionReference<"query">("functions/crm/query:search"),
+  },
+  statuses: {
+    list: makeFunctionReference<"query">("functions/crm/statuses:list"),
+    upsertMany: makeFunctionReference<"mutation">(
+      "functions/crm/statuses:upsertMany",
+    ),
+  },
+  batch: {
+    apply: makeFunctionReference<"mutation">("functions/crm/batch:apply"),
+  },
+  documents: {
+    list: makeFunctionReference<"query">("functions/crm/documents:list"),
+    create: makeFunctionReference<"mutation">(
+      "functions/crm/documents:create",
+    ),
+    link: makeFunctionReference<"mutation">("functions/crm/documents:link"),
+  },
+  actions: {
+    list: makeFunctionReference<"query">("functions/crm/actions:list"),
+    startActionRun: makeFunctionReference<"mutation">(
+      "functions/crm/actions:startActionRun",
+    ),
+  },
+};
+
+export async function runCrmCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  sessionToken?: string;
+}): Promise<void> {
+  const args = [...opts.args];
+  const jsonOutput = hasFlag(args, "--json");
+  const ctx: CrmCliContext = {
+    convex: opts.convex,
+    args,
+    jsonOutput,
+    sessionToken: opts.sessionToken,
+  };
+  const subcommand = args.shift();
+  if (!subcommand || subcommand === "help" || subcommand === "--help") {
+    crmHelp();
+    return;
+  }
+  switch (subcommand) {
+    case "objects":
+      return await runObjectsCommand(ctx);
+    case "fields":
+      return await runFieldsCommand(ctx);
+    case "entries":
+      return await runEntriesCommand(ctx);
+    case "cells":
+      return await runCellsCommand(ctx);
+    case "query":
+      return await runQueryCommand(ctx);
+    case "sql":
+      return await runSqlCommand(ctx);
+    case "aggregate":
+      return await runAggregateCommand(ctx);
+    case "search":
+      return await runSearchCommand(ctx);
+    case "statuses":
+      return await runStatusesCommand(ctx);
+    case "batch":
+      return await runBatchCommand(ctx);
+    case "import":
+      return await runImportCommand(ctx);
+    case "export":
+      return await runExportCommand(ctx);
+    case "transaction":
+      return await runTransactionCommand(ctx);
+    case "people":
+      return await runPeopleCommand(ctx);
+    case "companies":
+      return await runCompaniesCommand(ctx);
+    case "enrich":
+      return await runEnrichCommand(ctx);
+    case "reports":
+      return await runReportsCommand(ctx);
+    case "docs":
+    case "documents":
+      return await runDocsCommand(ctx);
+    case "actions":
+      return await runActionsCommand(ctx);
+    default:
+      throw new CrmCliError(`Unknown crm subcommand: ${subcommand}`);
+  }
+}
+
+async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "list": {
+      out(ctx, await callQuery(ctx, api.objects.list, {}));
+      return;
+    }
+    case "get": {
+      const name = shift(ctx.args, "object name");
+      out(ctx, await callQuery(ctx, api.objects.get, { name }));
+      return;
+    }
+    case "create": {
+      const name = shift(ctx.args, "object name");
+      const description = getFlag(ctx.args, "--description");
+      const defaultView = getFlag(ctx.args, "--default-view") as any;
+      const icon = getFlag(ctx.args, "--icon");
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.create, {
+          name,
+          description,
+          defaultView,
+          icon,
+        }),
+      );
+      return;
+    }
+    case "update": {
+      const name = shift(ctx.args, "object name");
+      const description = getFlag(ctx.args, "--description");
+      const defaultView = getFlag(ctx.args, "--default-view") as any;
+      const icon = getFlag(ctx.args, "--icon");
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.update, {
+          name,
+          description,
+          defaultView,
+          icon,
+        }),
+      );
+      return;
+    }
+    case "rename": {
+      const from = shift(ctx.args, "current name");
+      const to = shift(ctx.args, "new name");
+      out(ctx, await callMutation(ctx, api.objects.rename, { from, to }));
+      return;
+    }
+    case "delete":
+    case "remove": {
+      const name = shift(ctx.args, "object name");
+      out(ctx, await callMutation(ctx, api.objects.remove, { name }));
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm objects verb: ${verb ?? "<none>"}`);
+  }
+}
+
+async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "list": {
+      const objectName = shift(ctx.args, "object name");
+      out(ctx, await callQuery(ctx, api.fields.list, { objectName }));
+      return;
+    }
+    case "create": {
+      const objectName = shift(ctx.args, "object name");
+      const name = shift(ctx.args, "field name");
+      const type = (getFlag(ctx.args, "--type") ?? "text") as any;
+      const required = hasFlag(ctx.args, "--required");
+      const description = getFlag(ctx.args, "--description");
+      const enumValues = parseJson(getFlag(ctx.args, "--enum-values")) as
+        | string[]
+        | undefined;
+      const enumColors = parseJson(getFlag(ctx.args, "--enum-colors")) as
+        | string[]
+        | undefined;
+      const enumMultiple = hasFlag(ctx.args, "--enum-multiple");
+      const relatedObjectName = getFlag(ctx.args, "--related-object");
+      const relationshipType = getFlag(ctx.args, "--relationship") as any;
+      const indexed = hasFlag(ctx.args, "--indexed")
+        ? true
+        : hasFlag(ctx.args, "--no-indexed")
+          ? false
+          : undefined;
+      out(
+        ctx,
+        await callMutation(ctx, api.fields.create, {
+          objectName,
+          name,
+          type,
+          required,
+          description,
+          enumValues,
+          enumColors,
+          enumMultiple,
+          relatedObjectName,
+          relationshipType,
+          indexed,
+        }),
+      );
+      return;
+    }
+    case "update": {
+      const objectName = shift(ctx.args, "object name");
+      const fieldName = shift(ctx.args, "field name");
+      const description = getFlag(ctx.args, "--description");
+      const required = hasFlag(ctx.args, "--required");
+      const enumValues = parseJson(getFlag(ctx.args, "--enum-values")) as
+        | string[]
+        | undefined;
+      const indexed = hasFlag(ctx.args, "--indexed")
+        ? true
+        : hasFlag(ctx.args, "--no-indexed")
+          ? false
+          : undefined;
+      out(
+        ctx,
+        await callMutation(ctx, api.fields.update, {
+          objectName,
+          fieldName,
+          description,
+          required,
+          enumValues,
+          indexed,
+        }),
+      );
+      return;
+    }
+    case "delete":
+    case "remove": {
+      const objectName = shift(ctx.args, "object name");
+      const fieldName = shift(ctx.args, "field name");
+      out(
+        ctx,
+        await callMutation(ctx, api.fields.remove, {
+          objectName,
+          fieldName,
+        }),
+      );
+      return;
+    }
+    case "reorder": {
+      const objectName = shift(ctx.args, "object name");
+      const orderedFieldNames = ctx.args.filter((arg) => !arg.startsWith("--"));
+      out(
+        ctx,
+        await callMutation(ctx, api.fields.reorder, {
+          objectName,
+          orderedFieldNames,
+        }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm fields verb: ${verb ?? "<none>"}`);
+  }
+}
+
+async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "list": {
+      const objectName = shift(ctx.args, "object name");
+      const limit = parseInt(getFlag(ctx.args, "--limit") ?? "100", 10);
+      out(
+        ctx,
+        await callQuery(ctx, api.entries.list, { objectName, limit }),
+      );
+      return;
+    }
+    case "get": {
+      const objectName = shift(ctx.args, "object name");
+      const entryId = shift(ctx.args, "entry id");
+      out(
+        ctx,
+        await callQuery(ctx, api.entries.get, {
+          objectName,
+          entryId: entryId as any,
+        }),
+      );
+      return;
+    }
+    case "create": {
+      const objectName = shift(ctx.args, "object name");
+      const data =
+        (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
+        {};
+      out(
+        ctx,
+        await callMutation(ctx, api.entries.create, { objectName, data }),
+      );
+      return;
+    }
+    case "update": {
+      const objectName = shift(ctx.args, "object name");
+      const entryId = shift(ctx.args, "entry id");
+      const data =
+        (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
+        {};
+      out(
+        ctx,
+        await callMutation(ctx, api.entries.update, {
+          objectName,
+          entryId: entryId as any,
+          data,
+        }),
+      );
+      return;
+    }
+    case "delete":
+    case "remove": {
+      const _objectName = shift(ctx.args, "object name");
+      const entryId = shift(ctx.args, "entry id");
+      out(
+        ctx,
+        await callMutation(ctx, api.entries.remove, {
+          entryId: entryId as any,
+        }),
+      );
+      return;
+    }
+    case "bulk-delete":
+    case "bulkDelete": {
+      const _objectName = shift(ctx.args, "object name");
+      const idsCsv = getFlag(ctx.args, "--ids") ?? "";
+      const entryIds = idsCsv.split(",").filter(Boolean);
+      out(
+        ctx,
+        await callMutation(ctx, api.entries.bulkDelete, {
+          entryIds: entryIds as any,
+        }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm entries verb: ${verb ?? "<none>"}`);
+  }
+}
+
+async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  const objectName = shift(ctx.args, "object name");
+  const entryId = shift(ctx.args, "entry id");
+  const fieldName = shift(ctx.args, "field name");
+  switch (verb) {
+    case "get": {
+      out(
+        ctx,
+        await callQuery(ctx, api.cells.get, {
+          objectName,
+          entryId: entryId as any,
+          fieldName,
+        }),
+      );
+      return;
+    }
+    case "set": {
+      const value = parseJson(ctx.args.shift()) ?? null;
+      out(
+        ctx,
+        await callMutation(ctx, api.cells.set, {
+          objectName,
+          entryId: entryId as any,
+          fieldName,
+          value,
+        }),
+      );
+      return;
+    }
+    case "append": {
+      const value = parseJson(ctx.args.shift()) ?? null;
+      out(
+        ctx,
+        await callMutation(ctx, api.cells.append, {
+          objectName,
+          entryId: entryId as any,
+          fieldName,
+          value,
+        }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm cells verb: ${verb ?? "<none>"}`);
+  }
+}
+
+async function runQueryCommand(ctx: CrmCliContext): Promise<void> {
+  const objectName = shift(ctx.args, "object name");
+  const filter = parseJson(getFlag(ctx.args, "--where")) as
+    | JsonRecord
+    | undefined;
+  const select = getFlag(ctx.args, "--select")?.split(",").filter(Boolean);
+  const sort = getFlag(ctx.args, "--sort");
+  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "100", 10);
+  // Convex's wire serializer rejects $-prefixed object keys, so we
+  // route the DSL through the dslJson string field whenever the filter
+  // has any operator-shaped clause.
+  const dsl = { filter, select, sort, limit };
+  const hasDollarKey = filter ? containsDollarKey(filter) : false;
+  out(
+    ctx,
+    await callQuery(ctx, 
+      api.query.queryEntries,
+      hasDollarKey
+        ? { objectName, dslJson: JSON.stringify(dsl) }
+        : { objectName, dsl },
+    ),
+  );
+}
+
+export function containsDollarKey(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(containsDollarKey);
+  for (const key of Object.keys(value)) {
+    if (key.startsWith("$")) return true;
+    if (containsDollarKey((value as Record<string, unknown>)[key])) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function runAggregateCommand(ctx: CrmCliContext): Promise<void> {
+  const objectName = shift(ctx.args, "object name");
+  const fieldName = getFlag(ctx.args, "--field");
+  if (!fieldName) throw new CrmCliError("--field is required");
+  out(
+    ctx,
+    await callQuery(ctx, api.query.aggregate, { objectName, fieldName }),
+  );
+}
+
+async function runSearchCommand(ctx: CrmCliContext): Promise<void> {
+  const objectName = getFlag(ctx.args, "--object");
+  const text = ctx.args.join(" ").trim();
+  if (!text) throw new CrmCliError("Search text required");
+  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "50", 10);
+  out(
+    ctx,
+    await callQuery(ctx, api.query.search, { text, objectName, limit }),
+  );
+}
+
+async function runStatusesCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "list": {
+      const objectName = shift(ctx.args, "object name");
+      out(ctx, await callQuery(ctx, api.statuses.list, { objectName }));
+      return;
+    }
+    case "set": {
+      const objectName = shift(ctx.args, "object name");
+      const statuses = parseJson(getFlag(ctx.args, "--statuses")) as any[];
+      if (!Array.isArray(statuses)) {
+        throw new CrmCliError("--statuses (JSON array) is required");
+      }
+      out(
+        ctx,
+        await callMutation(ctx, api.statuses.upsertMany, {
+          objectName,
+          statuses,
+        }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm statuses verb: ${verb ?? "<none>"}`);
+  }
+}
+
+async function runBatchCommand(ctx: CrmCliContext): Promise<void> {
+  const filePath = getFlag(ctx.args, "--file");
+  if (!filePath) {
+    throw new CrmCliError(
+      "dench crm batch requires --file <ops.jsonl> (one op per line)",
+    );
+  }
+  const fs = await import("node:fs/promises");
+  const text = await fs.readFile(filePath, "utf-8");
+  const ops: unknown[] = [];
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    ops.push(JSON.parse(trimmed));
+  }
+  if (ops.length === 0) {
+    throw new CrmCliError(`No operations found in ${filePath}`);
+  }
+  out(
+    ctx,
+    await callMutation(ctx, api.batch.apply, {
+      ops: ops as any,
+    }),
+  );
+}
+
+async function runDocsCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "list": {
+      out(ctx, await callQuery(ctx, api.documents.list, {}));
+      return;
+    }
+    case "create": {
+      const filePath = shift(ctx.args, "file path");
+      const title = getFlag(ctx.args, "--title") ?? filePath.split("/").pop()!;
+      const icon = getFlag(ctx.args, "--icon");
+      const linkEntryId = getFlag(ctx.args, "--link-entry");
+      out(
+        ctx,
+        await callMutation(ctx, api.documents.create, {
+          filePath,
+          title,
+          icon,
+          entryId: linkEntryId as any,
+        }),
+      );
+      return;
+    }
+    case "link": {
+      const filePath = shift(ctx.args, "file path");
+      const objectName = getFlag(ctx.args, "--object");
+      const entryId = getFlag(ctx.args, "--entry");
+      out(
+        ctx,
+        await callMutation(ctx, api.documents.link, {
+          filePath,
+          objectName,
+          entryId: entryId as any,
+        }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm docs verb: ${verb ?? "<none>"}`);
+  }
+}
+
+async function runActionsCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "list": {
+      const entryId = shift(ctx.args, "entry id");
+      out(
+        ctx,
+        await callQuery(ctx, api.actions.list, {
+          entryId: entryId as any,
+        }),
+      );
+      return;
+    }
+    case "run": {
+      // Two-step happy path: insert crmActionRuns row → POST run-action
+      // route which creates the workflow run + starts agentRunWorkflow.
+      const actionId = shift(ctx.args, "action id");
+      const fieldId = getFlag(ctx.args, "--field-id");
+      const entryId = getFlag(ctx.args, "--entry-id");
+      const goal = getFlag(ctx.args, "--goal") ?? "";
+      const wait = hasFlag(ctx.args, "--wait");
+      if (!fieldId || !entryId) {
+        throw new CrmCliError(
+          "dench crm actions run requires --field-id and --entry-id",
+        );
+      }
+      const created = (await callMutation(ctx, api.actions.startActionRun, {
+        actionId,
+        fieldId: fieldId as any,
+        entryId: entryId as any,
+      })) as { id: string };
+      // Hop through /api/crm/run-action so the workflow actually starts.
+      const apiBase = (
+        process.env.DENCH_API_URL ?? "http://localhost:3000"
+      ).replace(/\/+$/, "");
+      const apiKey =
+        process.env.DENCH_API_KEY?.trim() ??
+        process.env.DENCH_FALLBACK_API_KEY?.trim() ??
+        "";
+      if (!apiKey) {
+        throw new CrmCliError(
+          "DENCH_API_KEY required to fire the action workflow",
+        );
+      }
+      const response = await fetch(`${apiBase}/api/crm/run-action`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ actionRunId: created.id, goal }),
+      });
+      const json = (await response.json().catch(() => ({}))) as {
+        runId?: string;
+        error?: string;
+      };
+      if (!response.ok) {
+        throw new CrmCliError(
+          `run-action failed (${response.status}): ${json.error ?? ""}`,
+        );
+      }
+      out(ctx, { actionRunId: created.id, runId: json.runId, wait });
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm actions verb: ${verb ?? "<none>"}`);
+  }
+}
+
+// ── Transactions ─────────────────────────────────────────────────────────
+
+async function runTransactionCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "begin": {
+      out(ctx, await callMutation(ctx, api.transaction.begin, {}));
+      return;
+    }
+    case "add": {
+      const txnId = shift(ctx.args, "txn id");
+      const opType = shift(ctx.args, "op type (entries.create|update|delete)");
+      const objectName = ctx.args[0];
+      let op: any;
+      if (opType === "entries.create") {
+        op = {
+          type: "entries.create",
+          objectName: shift(ctx.args, "object name"),
+          data:
+            (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
+            {},
+        };
+      } else if (opType === "entries.update") {
+        op = {
+          type: "entries.update",
+          entryId: shift(ctx.args, "entry id"),
+          data:
+            (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
+            {},
+        };
+      } else if (opType === "entries.delete") {
+        op = { type: "entries.delete", entryId: shift(ctx.args, "entry id") };
+      } else {
+        throw new CrmCliError(`Unknown txn op type: ${opType}`);
+      }
+      out(
+        ctx,
+        await callMutation(ctx, api.transaction.addOp, {
+          txnId: txnId as any,
+          op,
+        }),
+      );
+      return;
+    }
+    case "commit": {
+      const txnId = shift(ctx.args, "txn id");
+      out(
+        ctx,
+        await callMutation(ctx, api.transaction.commit, {
+          txnId: txnId as any,
+        }),
+      );
+      return;
+    }
+    case "abort": {
+      const txnId = shift(ctx.args, "txn id");
+      out(
+        ctx,
+        await callMutation(ctx, api.transaction.abort, {
+          txnId: txnId as any,
+        }),
+      );
+      return;
+    }
+    case "inspect": {
+      const txnId = shift(ctx.args, "txn id");
+      out(
+        ctx,
+        await callQuery(ctx, api.transaction.inspect, {
+          txnId: txnId as any,
+        }),
+      );
+      return;
+    }
+    case undefined:
+    case "--file": {
+      // Single-shot: read JSON ops file, run begin → addOp* → commit.
+      ctx.args.unshift(verb ?? "");
+      const filePath = getFlag(ctx.args, "--file");
+      const commit = hasFlag(ctx.args, "--commit");
+      if (!filePath) {
+        throw new CrmCliError(
+          "dench crm transaction --file <ops.json> [--commit]",
+        );
+      }
+      const fs = await import("node:fs/promises");
+      const text = await fs.readFile(filePath, "utf-8");
+      const ops = JSON.parse(text) as unknown[];
+      const begun = (await callMutation(ctx, 
+        api.transaction.begin,
+        {},
+      )) as { txnId: string };
+      for (const op of ops) {
+        await callMutation(ctx, api.transaction.addOp, {
+          txnId: begun.txnId as any,
+          op: op as any,
+        });
+      }
+      if (commit) {
+        out(
+          ctx,
+          await callMutation(ctx, api.transaction.commit, {
+            txnId: begun.txnId as any,
+          }),
+        );
+      } else {
+        out(ctx, { txnId: begun.txnId, queued: ops.length });
+      }
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm transaction verb: ${verb}`);
+  }
+}
+
+// ── Import / export ──────────────────────────────────────────────────────
+
+async function runImportCommand(ctx: CrmCliContext): Promise<void> {
+  const objectName = shift(ctx.args, "object name");
+  const csvPath = getFlag(ctx.args, "--csv");
+  const jsonlPath = getFlag(ctx.args, "--jsonl");
+  const mapJson = getFlag(ctx.args, "--map");
+  const onConflict = (getFlag(ctx.args, "--on-conflict") ?? "skip") as
+    | "skip"
+    | "update"
+    | "error";
+  if (!csvPath && !jsonlPath) {
+    throw new CrmCliError(
+      "dench crm import <object> requires --csv <path> or --jsonl <path>",
+    );
+  }
+  const fs = await import("node:fs/promises");
+  const colMap = mapJson ? (parseJson(mapJson) as Record<string, string>) : {};
+  const rows: Record<string, unknown>[] = [];
+  if (csvPath) {
+    const text = await fs.readFile(csvPath, "utf-8");
+    rows.push(...parseCsv(text, colMap));
+  }
+  if (jsonlPath) {
+    const text = await fs.readFile(jsonlPath, "utf-8");
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      rows.push(remapKeys(parsed, colMap));
+    }
+  }
+  // Chunk into 100-op batches and call batch.apply repeatedly.
+  let imported = 0;
+  for (let i = 0; i < rows.length; i += 100) {
+    const chunk = rows.slice(i, i + 100);
+    const ops = chunk.map((data) => ({
+      type: "entries.create" as const,
+      objectName,
+      data,
+    }));
+    const result = (await callMutation(ctx, api.batch.apply, {
+      ops: ops as any,
+      idempotencyKey: `import:${objectName}:${Date.now()}:${i}`,
+    } as any)) as { count: number };
+    imported += result.count;
+  }
+  out(ctx, { imported, onConflict });
+}
+
+async function runExportCommand(ctx: CrmCliContext): Promise<void> {
+  const objectName = shift(ctx.args, "object name");
+  const format = (getFlag(ctx.args, "--format") ?? "jsonl") as
+    | "csv"
+    | "jsonl";
+  const limit = parseInt(getFlag(ctx.args, "--limit") ?? "10000", 10);
+  // Page through entries.list in 1000-row chunks.
+  const all: any[] = [];
+  let cursor = 0;
+  while (all.length < limit) {
+    const page = (await callQuery(ctx, api.entries.list, {
+      objectName,
+      limit: Math.min(1000, limit - all.length),
+    })) as any[];
+    if (!page || page.length === 0) break;
+    all.push(...page);
+    cursor += page.length;
+    if (page.length < 1000) break;
+  }
+  if (format === "csv") {
+    const fields = Object.keys(all[0]?.fields ?? {});
+    const header = ["_id", ...fields].join(",");
+    const lines = all.map((entry) => {
+      const cells = [
+        entry.id,
+        ...fields.map((f) => csvEscape(entry.fields[f])),
+      ];
+      return cells.join(",");
+    });
+    process.stdout.write(`${header}\n${lines.join("\n")}\n`);
+  } else {
+    for (const entry of all) {
+      process.stdout.write(
+        `${JSON.stringify({ _id: entry.id, ...entry.fields })}\n`,
+      );
+    }
+  }
+}
+
+export function parseCsv(
+  text: string,
+  colMap: Record<string, string>,
+): Record<string, unknown>[] {
+  // Tiny CSV parser: comma separator, double-quote escaping. Doesn't
+  // handle multi-line quoted cells (rare for CRM imports). Callers with
+  // pathological CSVs should pre-clean via `csvkit` or similar.
+  const rows: Record<string, unknown>[] = [];
+  const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
+  if (lines.length === 0) return rows;
+  const header = parseCsvLine(lines[0]).map(
+    (col) => colMap[col] ?? col,
+  );
+  for (let i = 1; i < lines.length; i++) {
+    const cols = parseCsvLine(lines[i]);
+    const row: Record<string, unknown> = {};
+    for (let j = 0; j < header.length; j++) {
+      row[header[j]] = cols[j] ?? null;
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+export function parseCsvLine(line: string): string[] {
+  const out: string[] = [];
+  let buf = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"' && line[i + 1] === '"') {
+        buf += '"';
+        i++;
+      } else if (ch === '"') {
+        inQuotes = false;
+      } else {
+        buf += ch;
+      }
+    } else {
+      if (ch === ",") {
+        out.push(buf);
+        buf = "";
+      } else if (ch === '"' && buf === "") {
+        inQuotes = true;
+      } else {
+        buf += ch;
+      }
+    }
+  }
+  out.push(buf);
+  return out;
+}
+
+export function csvEscape(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const text = Array.isArray(value) ? value.join(";") : String(value);
+  if (text.includes(",") || text.includes('"') || text.includes("\n")) {
+    return `"${text.replace(/"/g, '""')}"`;
+  }
+  return text;
+}
+
+export function remapKeys(
+  row: Record<string, unknown>,
+  colMap: Record<string, string>,
+): Record<string, unknown> {
+  if (Object.keys(colMap).length === 0) return row;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(row)) {
+    out[colMap[key] ?? key] = value;
+  }
+  return out;
+}
+
+// ── SQL escape hatch ─────────────────────────────────────────────────────
+
+async function runSqlCommand(ctx: CrmCliContext): Promise<void> {
+  const sql = ctx.args.join(" ").trim();
+  if (!sql) {
+    throw new CrmCliError("dench crm sql '<SELECT ... FROM ...>'");
+  }
+  // v1: translate the simplest SELECT shape into the query DSL. Anything
+  // beyond that ("SELECT ... FROM ... WHERE ... ORDER BY ... LIMIT N")
+  // shells out to duckdb on the local file if available; otherwise we
+  // surface a helpful error.
+  const m =
+    /^SELECT\s+(.+?)\s+FROM\s+([\w"]+)(?:\s+WHERE\s+(.+?))?(?:\s+ORDER\s+BY\s+(.+?))?(?:\s+LIMIT\s+(\d+))?\s*;?$/i.exec(
+      sql,
+    );
+  if (!m) {
+    throw new CrmCliError(
+      "dench crm sql only supports flat SELECT for now. Use the DSL or duckdb directly.",
+    );
+  }
+  const [, selectStr, tableRaw, _whereStr, sortStr, limitStr] = m;
+  const objectName = tableRaw.replace(/"/g, "");
+  const select =
+    selectStr.trim() === "*"
+      ? undefined
+      : selectStr.split(",").map((s) => s.trim().replace(/"/g, ""));
+  const limit = limitStr ? parseInt(limitStr, 10) : 100;
+  const sort = sortStr
+    ? sortStr
+        .split(",")
+        .map((s) => {
+          const desc = /\s+DESC\s*$/i.test(s);
+          return `${desc ? "-" : ""}${s.replace(/\s+(asc|desc)\s*$/i, "").trim().replace(/"/g, "")}`;
+        })
+        .join(",")
+    : undefined;
+  out(
+    ctx,
+    await callQuery(ctx, api.query.queryEntries, {
+      objectName,
+      dsl: { select, sort, limit },
+    }),
+  );
+}
+
+// ── People + companies shortcuts ─────────────────────────────────────────
+//
+// These are thin wrappers around the standard objects/entries surface,
+// using the canonical "people" / "company" object names.
+
+async function runPeopleCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "search": {
+      const text = ctx.args.join(" ").trim();
+      if (!text) throw new CrmCliError("Search text required");
+      out(
+        ctx,
+        await callQuery(ctx, api.query.search, {
+          text,
+          objectName: "people",
+          limit: 50,
+        }),
+      );
+      return;
+    }
+    case "upsert": {
+      const data =
+        (parseJson(getFlag(ctx.args, "--data")) as JsonRecord | undefined) ??
+        {};
+      out(
+        ctx,
+        await callMutation(ctx, api.entries.create, {
+          objectName: "people",
+          data,
+        }),
+      );
+      return;
+    }
+    case "enrich": {
+      const entryId = shift(ctx.args, "person entry id");
+      const provider = getFlag(ctx.args, "--provider");
+      out(
+        ctx,
+        await callMutation(ctx, api.enrich.requestObjectEnrichment, {
+          objectName: "people",
+          fieldName: getFlag(ctx.args, "--field") ?? "Email Address",
+          provider,
+        }),
+      );
+      // Don't reference entryId in the request — Phase 3 v1 enrichment is
+      // object-level only; cell-level lands once gateway enrichment ships.
+      // Print entryId in the result so the caller has context.
+      out(ctx, { entryId });
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm people verb: ${verb ?? "<none>"}`);
+  }
+}
+
+async function runCompaniesCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "search": {
+      const text = ctx.args.join(" ").trim();
+      if (!text) throw new CrmCliError("Search text required");
+      out(
+        ctx,
+        await callQuery(ctx, api.query.search, {
+          text,
+          objectName: "company",
+          limit: 50,
+        }),
+      );
+      return;
+    }
+    case "upsert": {
+      const domain = getFlag(ctx.args, "--domain");
+      const name = getFlag(ctx.args, "--name");
+      const data: Record<string, unknown> = {};
+      if (domain) data["Domain"] = domain;
+      if (name) data["Name"] = name;
+      out(
+        ctx,
+        await callMutation(ctx, api.entries.create, {
+          objectName: "company",
+          data,
+        }),
+      );
+      return;
+    }
+    case "enrich": {
+      const entryId = shift(ctx.args, "company entry id");
+      const provider = getFlag(ctx.args, "--provider");
+      out(
+        ctx,
+        await callMutation(ctx, api.enrich.requestObjectEnrichment, {
+          objectName: "company",
+          fieldName: getFlag(ctx.args, "--field") ?? "Domain",
+          provider,
+        }),
+      );
+      out(ctx, { entryId });
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm companies verb: ${verb ?? "<none>"}`);
+  }
+}
+
+// ── Cell / row / object enrichment ───────────────────────────────────────
+
+async function runEnrichCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  switch (verb) {
+    case "cell": {
+      const objectName = shift(ctx.args, "object name");
+      const entryId = shift(ctx.args, "entry id");
+      const fieldName = shift(ctx.args, "field name");
+      const provider = getFlag(ctx.args, "--provider");
+      out(
+        ctx,
+        await callMutation(ctx, api.enrich.requestCellEnrichment, {
+          objectName,
+          entryId: entryId as any,
+          fieldName,
+          provider,
+        }),
+      );
+      return;
+    }
+    case "object": {
+      const objectName = shift(ctx.args, "object name");
+      const fieldName = getFlag(ctx.args, "--field");
+      const missingOnly = !hasFlag(ctx.args, "--all");
+      const provider = getFlag(ctx.args, "--provider");
+      if (!fieldName) {
+        throw new CrmCliError(
+          "dench crm enrich object <name> --field <field> [--provider ...] [--all]",
+        );
+      }
+      out(
+        ctx,
+        await callMutation(ctx, api.enrich.requestObjectEnrichment, {
+          objectName,
+          fieldName,
+          provider,
+          missingOnly,
+        }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm enrich verb: ${verb ?? "<none>"}`);
+  }
+}
+
+// ── Reports ──────────────────────────────────────────────────────────────
+
+async function runReportsCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift();
+  if (verb !== "generate") {
+    throw new CrmCliError(
+      "Usage: dench crm reports generate <name> --object <object> --type pie|bar|line|table --group-by <field> [--metric count|sum --metric-field <field>]",
+    );
+  }
+  const _name = shift(ctx.args, "report name");
+  const objectName = getFlag(ctx.args, "--object");
+  const type = getFlag(ctx.args, "--type") as
+    | "pie"
+    | "bar"
+    | "line"
+    | "table";
+  const groupBy = getFlag(ctx.args, "--group-by");
+  const metric = getFlag(ctx.args, "--metric") as
+    | "count"
+    | "sum"
+    | "avg"
+    | "min"
+    | "max"
+    | undefined;
+  const metricField = getFlag(ctx.args, "--metric-field");
+  if (!objectName || !type || !groupBy) {
+    throw new CrmCliError(
+      "dench crm reports generate requires --object, --type, --group-by",
+    );
+  }
+  out(
+    ctx,
+    await callQuery(ctx, api.reports.generate, {
+      objectName,
+      type,
+      groupByField: groupBy,
+      metric,
+      metricField,
+    }),
+  );
+}
+
+function crmHelp(): void {
+  console.log(`Usage: dench crm <subcommand>
+
+Objects (CRM tables):
+  dench crm objects list [--json]
+  dench crm objects get <name>
+  dench crm objects create <name> [--description ...] [--default-view kanban] [--icon ...]
+  dench crm objects update <name> [--default-view ...] [--icon ...]
+  dench crm objects rename <from> <to>
+  dench crm objects delete <name>
+
+Fields (columns):
+  dench crm fields list <object> [--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] \\
+        [--indexed | --no-indexed]
+  dench crm fields update <object> <field> [--description ...] [--required] [--enum-values JSON] [--indexed | --no-indexed]
+  dench crm fields delete <object> <field>
+  dench crm fields reorder <object> <field1> <field2> <field3> ...
+
+Entries (rows):
+  dench crm entries list <object> [--limit N] [--json]
+  dench crm entries get <object> <entryId>
+  dench crm entries create <object> --data '{"Field":"Value",...}'
+  dench crm entries update <object> <entryId> --data '{...}'
+  dench crm entries delete <object> <entryId>
+  dench crm entries bulk-delete <object> --ids id1,id2,id3
+
+Cells (single-field updates):
+  dench crm cells get <object> <entryId> <field>
+  dench crm cells set <object> <entryId> <field> '<JSON value>'
+  dench crm cells append <object> <entryId> <field> '<JSON value>'
+
+Query DSL:
+  dench crm query <object> --where '{"Status":"New"}' --select Name,Email --sort -Score --limit 100
+
+Aggregates:
+  dench crm aggregate <object> --field Status
+
+Full-text search:
+  dench crm search [--object <name>] [--limit N] <text>
+
+Statuses (kanban columns):
+  dench crm statuses list <object>
+  dench crm statuses set <object> --statuses '[{"name":"New","color":"#94a3b8"},...]'
+
+Batch:
+  dench crm batch --file ops.jsonl [--idempotency-key <key>]
+
+Import / export:
+  dench crm import <object> --csv leads.csv [--map '{"Email":"Email Address"}'] [--on-conflict skip|update|error]
+  dench crm import <object> --jsonl rows.jsonl
+  dench crm export <object> --format csv|jsonl [--limit N]
+
+Transactions (multi-step, all-or-nothing):
+  TXN=$(dench crm transaction begin)
+  dench crm transaction add $TXN entries.create company --data '{...}'
+  dench crm transaction add $TXN entries.update <entryId> --data '{...}'
+  dench crm transaction commit $TXN
+  dench crm transaction abort  $TXN
+  dench crm transaction --file ops.json --commit
+
+SQL escape hatch (subset; flat SELECTs only):
+  dench crm sql 'SELECT "Full Name","Email Address" FROM lead WHERE "Status"='New' ORDER BY _creationTime DESC LIMIT 10'
+
+People + companies shortcuts:
+  dench crm people search '<query>'
+  dench crm people upsert --data '{"Email Address":"jane@example.com",...}'
+  dench crm people enrich <entryId> [--provider apollo]
+  dench crm companies search '<query>'
+  dench crm companies upsert --domain acme.com [--name Acme]
+  dench crm companies enrich <entryId>
+
+Cell / row / object enrichment:
+  dench crm enrich cell <object> <entryId> <field> [--provider ...]
+  dench crm enrich object <object> --field <field> [--provider ...] [--all]
+
+Reports (chart-ready JSON):
+  dench crm reports generate '<name>' --object <object> --type pie|bar|line|table --group-by <field> [--metric count|sum --metric-field <field>]
+
+Docs:
+  dench crm docs list
+  dench crm docs create <path> [--title ...] [--icon ...] [--link-entry <id>]
+  dench crm docs link <path> --object <name> --entry <id>
+
+Actions:
+  dench crm actions list <entryId>
+  dench crm actions run <actionId> --field-id <id> --entry-id <id>
+
+Global flags:
+  --json    Output raw JSON instead of pretty-printed text.
+`);
+}