@dench.com/cli 2.7.1 → 2.7.2

package/crm.ts

@@ -90,8 +90,109 @@ type CrmCliContext = {
   sessionToken?: string;
   runId?: string;
   enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+  /** App origin used to build absolute entry deep links (e.g. https://www.dench.com). */
+  host?: string;
+  /** Workspace slug for absolute entry deep links (e.g. dench). */
+  workspaceSlug?: string;
 };
 
+/**
+ * Canonical CRM entry deep links.
+ *
+ * Absolute (shareable): `https://…/<slug>?path=<object>&entry=<object>:<id>`
+ * Relative (in-app):    `/?path=<object>&entry=<object>:<id>`
+ *
+ * Never invent `?object=` or a bare `entry=<id>` without the object prefix.
+ * `view` / `hidden` are optional UI chrome — not part of the canonical link.
+ */
+export function buildCrmEntryDeepLink(args: {
+  host?: string;
+  workspaceSlug?: string;
+  objectName: string;
+  entryId: string;
+}): { href: string; url?: string } {
+  const objectName = args.objectName.trim();
+  const entryId = args.entryId.trim();
+  // Keep a literal `:` between object and id (docs + in-app links); only
+  // encode the segments themselves so Convex ids stay readable.
+  const entryParam = `${encodeURIComponent(objectName)}:${encodeURIComponent(entryId)}`;
+  const pathParam = encodeURIComponent(objectName);
+  const href = `/?path=${pathParam}&entry=${entryParam}`;
+  const slug = args.workspaceSlug?.trim();
+  const host = args.host?.trim();
+  if (!slug || !host) {
+    return { href };
+  }
+  const withProtocol = /^https?:\/\//.test(host) ? host : `https://${host}`;
+  let base: string;
+  try {
+    base = new URL(withProtocol).origin;
+  } catch {
+    return { href };
+  }
+  return {
+    href,
+    url: `${base}/${encodeURIComponent(slug)}?path=${pathParam}&entry=${entryParam}`,
+  };
+}
+
+function entryIdFromUnknown(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const record = value as JsonRecord;
+  for (const key of ["entryId", "id"]) {
+    const candidate = record[key];
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Canonical object name echoed by `entries.get` / `entries.create` /
+ * `batch.apply`. The server resolves display labels, case, and plurals
+ * (`lib/crm/resolveObject.ts`), so the name the caller typed is often NOT
+ * the one the workspace URL resolver matches on — it compares object names
+ * exactly. Always prefer this over the raw CLI argument.
+ */
+function canonicalObjectNameFromUnknown(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const candidate = (value as JsonRecord).objectName;
+  return typeof candidate === "string" && candidate.trim()
+    ? candidate.trim()
+    : undefined;
+}
+
+function withCrmEntryDeepLinks(
+  ctx: CrmCliContext,
+  fallbackObjectName: string,
+  value: unknown,
+): unknown {
+  const entryId = entryIdFromUnknown(value);
+  if (!entryId || !value || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  // Older deployments don't echo `objectName`; the raw arg is the only
+  // thing left, and it's correct whenever the caller used the canonical name.
+  const objectName =
+    canonicalObjectNameFromUnknown(value) ?? fallbackObjectName;
+  const links = buildCrmEntryDeepLink({
+    host: ctx.host,
+    workspaceSlug: ctx.workspaceSlug,
+    objectName,
+    entryId,
+  });
+  return {
+    ...(value as JsonRecord),
+    href: links.href,
+    ...(links.url ? { url: links.url } : {}),
+  };
+}
+
 // Adapt the shared helpers to throw CrmCliError so existing call sites
 // don't need to change their try/catch shape.
 class CrmCliError extends Error {}
@@ -291,18 +392,22 @@ async function applyBatchOpsInChunks(
   ops: CrmBatchOp[],
   idempotencyKey: string | undefined,
   allowUnknown = false,
-): Promise<number> {
+): Promise<{ chunks: number; results: unknown[] }> {
   const chunks = chunkArray(ops, CRM_BATCH_CHUNK_SIZE);
+  const results: unknown[] = [];
   for (const [chunkIndex, chunk] of chunks.entries()) {
     const chunkKey = chunkIdempotencyKey(idempotencyKey, chunkIndex);
-    await callMutation(ctx, api.batch.apply, {
+    const batchResult = (await callMutation(ctx, api.batch.apply, {
       ops: chunk,
       ...runContextArgs(ctx),
       ...(chunkKey ? { idempotencyKey: chunkKey } : {}),
       ...(allowUnknown ? { allowUnknown: true } : {}),
-    });
+    })) as { results?: unknown[] } | null | undefined;
+    if (Array.isArray(batchResult?.results)) {
+      results.push(...batchResult.results);
+    }
   }
-  return chunks.length;
+  return { chunks: chunks.length, results };
 }
 
 function runContextArgs(ctx: CrmCliContext): Record<string, string> {
@@ -568,6 +673,20 @@ const api = {
     deleteView: makeFunctionReference<"mutation">(
       "functions/crm/objects:deleteView",
     ),
+    setArchived: makeFunctionReference<"mutation">(
+      "functions/crm/objects:setArchived",
+    ),
+    setViewPinned: makeFunctionReference<"mutation">(
+      "functions/crm/objects:setViewPinned",
+    ),
+  },
+  sidebar: {
+    describe: makeFunctionReference<"query">(
+      "functions/workspaceNav:describeMySidebar",
+    ),
+    reposition: makeFunctionReference<"mutation">(
+      "functions/workspaceNav:repositionMyNavItem",
+    ),
   },
   fields: {
     list: makeFunctionReference<"query">("functions/crm/fields:list"),
@@ -672,6 +791,8 @@ export async function runCrmCommand(opts: {
   args: string[];
   sessionToken?: string;
   enrichmentGateway?: Pick<EnrichmentGatewayOptions, "apiKey" | "baseUrl">;
+  host?: string;
+  workspaceSlug?: string;
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
@@ -682,6 +803,8 @@ export async function runCrmCommand(opts: {
     sessionToken: opts.sessionToken,
     runId: process.env.DENCH_RUN_ID?.trim() || undefined,
     enrichmentGateway: opts.enrichmentGateway,
+    host: opts.host,
+    workspaceSlug: opts.workspaceSlug,
   };
   const subcommand = args.shift();
   if (!subcommand || subcommand === "help" || subcommand === "--help") {
@@ -693,6 +816,8 @@ export async function runCrmCommand(opts: {
       return await runObjectsCommand(ctx);
     case "views":
       return await runViewsCommand(ctx);
+    case "sidebar":
+      return await runSidebarCommand(ctx);
     case "fields":
       return await runFieldsCommand(ctx);
     case "entries":
@@ -833,6 +958,50 @@ async function runCrmMembersCommand(ctx: CrmCliContext): Promise<void> {
   });
 }
 
+/**
+ * `dench crm sidebar …` — the workspace app rail.
+ *
+ * Row VISIBILITY is team-shared and lives on the CRM records themselves
+ * (`crm objects archive`, `crm views pin/archive`). Row ORDER is a
+ * per-member preference, which is what `move` writes. `list` shows both
+ * halves: the visible rows with their 1-based positions, plus what's
+ * hidden and why.
+ */
+async function runSidebarCommand(ctx: CrmCliContext): Promise<void> {
+  const verb = ctx.args.shift() ?? "list";
+  switch (verb) {
+    case "list": {
+      assertNoUnknownFlags(ctx.args, "crm sidebar list");
+      out(ctx, await callQuery(ctx, api.sidebar.describe, {}));
+      return;
+    }
+    case "move": {
+      const navId = shift(ctx.args, "nav id");
+      const rawPosition = shift(ctx.args, "position");
+      assertNoUnknownFlags(ctx.args, "crm sidebar move");
+      let position: string | number;
+      if (rawPosition === "top" || rawPosition === "bottom") {
+        position = rawPosition;
+      } else {
+        const parsed = Number.parseInt(rawPosition, 10);
+        if (!Number.isFinite(parsed) || parsed < 1) {
+          throw new CrmCliError(
+            `position must be "top", "bottom", or a positive integer, got ${rawPosition}`,
+          );
+        }
+        position = parsed;
+      }
+      out(
+        ctx,
+        await callMutation(ctx, api.sidebar.reposition, { navId, position }),
+      );
+      return;
+    }
+    default:
+      throw new CrmCliError(`Unknown crm sidebar verb: ${verb}`);
+  }
+}
+
 async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
   switch (verb) {
@@ -902,6 +1071,22 @@ async function runObjectsCommand(ctx: CrmCliContext): Promise<void> {
       out(ctx, await callMutation(ctx, api.objects.remove, { name }));
       return;
     }
+    // Archive is the sidebar's "remove from my rail", NOT a delete: the
+    // table, its rows and every link to it keep working, the row just
+    // moves into the rail's Archived flyout. Team-shared.
+    case "archive":
+    case "unarchive": {
+      const name = shift(ctx.args, "object name");
+      assertNoUnknownFlags(ctx.args, `crm objects ${verb}`);
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.setArchived, {
+          name,
+          archived: verb === "archive",
+        }),
+      );
+      return;
+    }
     default:
       throw new CrmCliError(`Unknown crm objects verb: ${verb ?? "<none>"}`);
   }
@@ -1363,6 +1548,39 @@ async function runViewsCommand(ctx: CrmCliContext): Promise<void> {
       );
       return;
     }
+    // Only `pinned` views render as workspace sidebar rows. Pinning also
+    // clears any archive stamp, since a pinned-but-archived view still
+    // wouldn't show up.
+    case "pin":
+    case "unpin": {
+      const objectName = shift(ctx.args, "object name");
+      const viewName = shift(ctx.args, "view name");
+      assertNoUnknownFlags(ctx.args, `crm views ${verb}`);
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.setViewPinned, {
+          objectName,
+          viewName,
+          pinned: verb === "pin",
+        }),
+      );
+      return;
+    }
+    case "archive":
+    case "unarchive": {
+      const objectName = shift(ctx.args, "object name");
+      const viewName = shift(ctx.args, "view name");
+      assertNoUnknownFlags(ctx.args, `crm views ${verb}`);
+      out(
+        ctx,
+        await callMutation(ctx, api.objects.setArchived, {
+          name: objectName,
+          viewName,
+          archived: verb === "archive",
+        }),
+      );
+      return;
+    }
     default:
       throw new CrmCliError(`Unknown crm views verb: ${verb ?? "<none>"}`);
   }
@@ -1624,10 +1842,14 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       assertNoUnknownFlags(ctx.args, "crm entries get");
       out(
         ctx,
-        await callQuery(ctx, api.entries.get, {
+        withCrmEntryDeepLinks(
+          ctx,
           objectName,
-          entryId: entryId as any,
-        }),
+          await callQuery(ctx, api.entries.get, {
+            objectName,
+            entryId: entryId as any,
+          }),
+        ),
       );
       return;
     }
@@ -1657,12 +1879,16 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       // pre-fetch — that would add a round-trip to every create.
       out(
         ctx,
-        await callMutation(ctx, api.entries.create, {
+        withCrmEntryDeepLinks(
+          ctx,
           objectName,
-          data,
-          ...runContextArgs(ctx),
-          ...(allowUnknown ? { allowUnknown: true } : {}),
-        }),
+          await callMutation(ctx, api.entries.create, {
+            objectName,
+            data,
+            ...runContextArgs(ctx),
+            ...(allowUnknown ? { allowUnknown: true } : {}),
+          }),
+        ),
       );
       return;
     }
@@ -1680,7 +1906,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         }),
       );
       await assertKnownDataKeys(ctx, objectName, rows, allowUnknown);
-      const chunks = await applyBatchOpsInChunks(
+      const { chunks, results } = await applyBatchOpsInChunks(
         ctx,
         rows.map((data) => ({
           type: "entries.create",
@@ -1690,7 +1916,41 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         idempotencyKey,
         allowUnknown,
       );
-      out(ctx, { created: rows.length, chunks });
+      // Only claim per-row links when we actually got a result per row. A
+      // silently-empty `results` is indistinguishable from "this object has
+      // no links" and sends the agent right back to inventing URLs — the
+      // exact failure this command's `url`/`href` output exists to prevent.
+      const linked = results.length;
+      out(ctx, {
+        created: rows.length,
+        chunks,
+        ...(linked > 0
+          ? {
+              results: results.map((result) =>
+                withCrmEntryDeepLinks(ctx, objectName, result),
+              ),
+            }
+          : {}),
+        ...(linked === rows.length
+          ? {}
+          : {
+              linksUnavailable: true,
+              // The recovery path has to be followable. With zero results
+              // there is no entryId to hand to `entries get`, so point at
+              // `entries list` (it returns `id` per row) instead — a hint
+              // the agent can't act on just sends it back to guessing.
+              linksHint:
+                `Got ${linked} link(s) for ${rows.length} row(s). ` +
+                (linked === 0
+                  ? `Run \`dench crm entries list ${objectName} --json\` to get each row's ` +
+                    `\`id\`, then \`dench crm entries get ${objectName} <id> --json\` for its ` +
+                    "canonical url"
+                  : `The rows above carry \`url\`/\`href\`; for the rest run ` +
+                    `\`dench crm entries list ${objectName} --json\` to get their \`id\`, then ` +
+                    `\`dench crm entries get ${objectName} <id> --json\``) +
+                " — do not construct a url by hand.",
+            }),
+      });
       return;
     }
     case "update": {
@@ -1743,7 +2003,7 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
         updates.map((update) => update.data),
         allowUnknown,
       );
-      const chunks = await applyBatchOpsInChunks(
+      const { chunks } = await applyBatchOpsInChunks(
         ctx,
         updates.map((update) => ({
           type: "entries.update",
@@ -1874,7 +2134,7 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
           data,
         }),
       );
-      const chunks = await applyBatchOpsInChunks(ctx, ops, idempotencyKey);
+      const { chunks } = await applyBatchOpsInChunks(ctx, ops, idempotencyKey);
       out(ctx, { updated: updates.length, entriesUpdated: ops.length, chunks });
       return;
     }
@@ -3287,6 +3547,10 @@ Objects (CRM tables):
       command/API identifier (works on protected objects too).
   dench crm objects rename <from> <to>
   dench crm objects delete <name>
+  dench crm objects archive <name> | unarchive <name>
+      Hides/restores the object's workspace SIDEBAR row. Not a delete —
+      the table, its rows and every link keep working; the row just moves
+      into the rail's Archived flyout. Team-shared.
 
 Views (saved CRM subsets):
   dench crm views list <object> [--json]
@@ -3306,6 +3570,22 @@ Views (saved CRM subsets):
   dench crm views delete <object> <view-name>
       Idempotent; also clears the active-view pointer if it referenced
       the deleted view.
+  dench crm views pin <object> <view-name> | unpin <object> <view-name>
+      Only pinned views render as workspace sidebar rows. Pinning also
+      clears any archive stamp.
+  dench crm views archive <object> <view-name> | unarchive <object> <view-name>
+      Moves the view's sidebar row into the Archived flyout. Unarchiving
+      re-asserts the pin so the row comes back.
+
+Sidebar (the workspace app rail):
+  dench crm sidebar list [--json]
+      Visible rows in order with 1-based positions, plus what's hidden
+      from the rail and why (archived vs. an unpinned view).
+  dench crm sidebar move <nav-id> <top|bottom|N>
+      Reposition one row. Nav ids come from 'sidebar list' — e.g.
+      'crm-object:task', 'crm-view:task:Due%20today', 'crm-people',
+      'automation'. Row ORDER is per-member; row visibility (above) is
+      team-shared.
 
 Fields (columns):
   dench crm fields list <object> [--json]
@@ -3368,6 +3648,18 @@ Entries (rows):
         being silently dropped. Verify names with 'crm fields list <object>'
         first. Pass --allow-unknown to write the raw value anyway, and on
         create the object's required fields must be present.
+        create / get / create-many also return deep links when the
+        workspace slug is known: \`url\` (absolute shareable) and \`href\`
+        (relative in-app). Paste those — never invent \`?object=\` or a
+        bare \`entry=<id>\` without the \`<object>:\` prefix. Canonical form:
+        /<slug>?path=<object>&entry=<object>:<entryId>
+        The link uses the object's CANONICAL name (echoed back as
+        \`objectName\`), not the alias you typed — \`create Tasks\` resolves
+        server-side but only \`task\` opens the record. If a response has no
+        \`url\`/\`href\`, run 'crm entries get <object> <entryId> --json' for
+        one. If create-many reports \`linksUnavailable\`, the unlinked rows
+        have no id in that response — run 'crm entries list <object> --json'
+        to recover their \`id\` first.
 
 Cells (single-field updates):
   dench crm cells get <object> <entryId> <field>

package/dench.ts

@@ -4035,6 +4035,8 @@ async function main() {
         convex: runtime.client,
         args: subArgs,
         sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+        host: resolveApiHost(LOCAL_HOST),
+        workspaceSlug: runtime.workspaceArgs.workspaceSlug,
         enrichmentGateway: gatewayAuth
           ? {
               apiKey: gatewayAuth.bearerToken,
@@ -4053,6 +4055,11 @@ async function main() {
       convex: authedRuntime.client,
       args: subArgs,
       sessionToken: authedRuntime.sessionToken,
+      host: authedRuntime.host,
+      workspaceSlug:
+        authedRuntime.organization?.slug ??
+        process.env.DENCH_ORG_SLUG?.trim() ??
+        undefined,
       enrichmentGateway: gatewayAuth
         ? {
             apiKey: gatewayAuth.bearerToken,

package/lib/api-schemas.ts

@@ -2126,8 +2126,14 @@ export const responseSchemas: Record<string, ZodTypeAny> = {
         id: z.string(),
         role: z.enum(["user", "assistant", "system"]),
         createdAt: z.number(),
+        updatedAt: z.number(),
         text: z.string(),
         runId: z.string().nullable(),
+        status: z
+          .enum(["streaming", "complete", "error", "canceled"])
+          .nullable(),
+        revision: z.number(),
+        isDraft: z.boolean(),
       }),
     ),
   }),
@@ -3130,15 +3136,23 @@ export const responseExamples: Record<string, unknown> = {
         id: "cm_def456",
         role: "user",
         createdAt: 1765526400000,
+        updatedAt: 1765526400000,
         text: "How do we deploy?",
         runId: null,
+        status: "complete",
+        revision: 0,
+        isDraft: false,
       },
       {
         id: "cm_ghi789",
         role: "assistant",
         createdAt: 1765526460000,
+        updatedAt: 1765526460000,
         text: "Push to main; Vercel auto-deploys.",
         runId: "rn_jkl012",
+        status: "complete",
+        revision: 1,
+        isDraft: false,
       },
     ],
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {