@dench.com/cli 2.7.3 → 2.7.5

package/apps.ts

@@ -0,0 +1,226 @@
+/**
+ * `dench apps` — the App Store surface (create / list / gallery / install /
+ * publish / uninstall / enable / pin). Distinct from `dench integrations`
+ * (Composio connected apps). Backed by convex/functions/appStore.ts — the same
+ * functions the workspace App Store panel and the API v1 `/apps/*` routes call.
+ *
+ * Thin dispatcher; forwards the caller's bearer through `sessionToken`, which
+ * the server's requireCrmAccess accepts (and appStore forwards to the file
+ * functions as an apiKey for publish/install/create).
+ */
+import type { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+
+const api = {
+  listInstalled: makeFunctionReference<"query">(
+    "functions/appStore:listInstalled",
+  ),
+  listListings: makeFunctionReference<"query">(
+    "functions/appStore:listListings",
+  ),
+  listGallery: makeFunctionReference<"query">("functions/appStore:listGallery"),
+  install: makeFunctionReference<"action">("functions/appStore:install"),
+  publish: makeFunctionReference<"action">("functions/appStore:publish"),
+  createApp: makeFunctionReference<"action">("functions/appStore:createApp"),
+  uninstall: makeFunctionReference<"mutation">("functions/appStore:uninstall"),
+  setEnabled: makeFunctionReference<"mutation">(
+    "functions/appStore:setEnabled",
+  ),
+  setPinned: makeFunctionReference<"mutation">("functions/appStore:setPinned"),
+};
+
+class AppsCliError extends Error {}
+
+type Ctx = {
+  convex: ConvexHttpClient;
+  args: string[];
+  sessionToken?: string;
+  jsonOutput: boolean;
+};
+
+function shift(args: string[], label: string): string {
+  const value = args.shift();
+  if (!value) throw new AppsCliError(`Missing ${label}`);
+  return value;
+}
+
+function takeFlag(args: string[], name: string): string | undefined {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  const next = args[i + 1];
+  if (next !== undefined && !next.startsWith("--")) {
+    args.splice(i, 2);
+    return next;
+  }
+  args.splice(i, 1);
+  return undefined;
+}
+
+function firstPositional(args: string[]): string | undefined {
+  return args.find((a) => !a.startsWith("--"));
+}
+
+function out(ctx: Ctx, value: unknown) {
+  console.log(JSON.stringify(value, null, ctx.jsonOutput ? 0 : 2));
+}
+
+function withAuth(ctx: Ctx, args: Record<string, unknown>) {
+  return {
+    ...args,
+    ...(ctx.sessionToken ? { sessionToken: ctx.sessionToken } : {}),
+  } as never;
+}
+
+function appsHelp() {
+  console.log(`Usage: dench apps <subcommand>   (App Store — not Composio; see 'dench integrations')
+
+  dench apps list [--json]                       Installed apps in this workspace
+  dench apps gallery [--json]                    Discover listings — Official (Dench) + Community
+  dench apps info <slug> [--json]                One installed app's record
+  dench apps create <slug> --name "My App" [--icon <name>] [--description "…"]
+                                                 Scaffold .dench.yaml + index.html and register it
+  dench apps install <listingId> [--json]        Install a gallery listing into this workspace
+  dench apps publish <appPath> --slug <slug> --name "My App" \\
+        [--description "…"] [--icon <name>] [--visibility org|public|official|unlisted] [--version 1.0.0]
+                                                 Bundle an app's files into a version + listing
+  dench apps uninstall <slug>                    Remove an installed app
+  dench apps enable | disable <slug>             Toggle whether the app loads
+  dench apps pin | unpin <slug>                  Toggle the rail pin
+`);
+}
+
+export async function runAppsCommand(opts: {
+  convex: ConvexHttpClient;
+  args: string[];
+  sessionToken?: string;
+}): Promise<void> {
+  const jsonOutput = opts.args.includes("--json");
+  const args = opts.args.filter((a) => a !== "--json");
+  const ctx: Ctx = {
+    convex: opts.convex,
+    args,
+    sessionToken: opts.sessionToken,
+    jsonOutput,
+  };
+  const sub = ctx.args.shift();
+  switch (sub) {
+    case undefined:
+      if (jsonOutput) {
+        out(ctx, await ctx.convex.query(api.listInstalled, withAuth(ctx, {})));
+        return;
+      }
+      appsHelp();
+      return;
+    case "help":
+    case "--help":
+      appsHelp();
+      return;
+    case "list":
+      out(ctx, await ctx.convex.query(api.listInstalled, withAuth(ctx, {})));
+      return;
+    case "gallery":
+      out(ctx, await ctx.convex.query(api.listGallery, withAuth(ctx, {})));
+      return;
+    case "info": {
+      const slug = shift(ctx.args, "app slug");
+      const installed = (await ctx.convex.query(
+        api.listInstalled,
+        withAuth(ctx, {}),
+      )) as Array<{ slug: string }>;
+      out(ctx, installed.find((a) => a.slug === slug) ?? null);
+      return;
+    }
+    case "create": {
+      const name = takeFlag(ctx.args, "--name");
+      const icon = takeFlag(ctx.args, "--icon");
+      const description = takeFlag(ctx.args, "--description");
+      const slug = firstPositional(ctx.args) ?? name;
+      if (!slug) {
+        throw new AppsCliError(
+          'Usage: dench apps create <slug> --name "My App" [--icon <name>]',
+        );
+      }
+      out(
+        ctx,
+        await ctx.convex.action(
+          api.createApp,
+          withAuth(ctx, {
+            slug,
+            name: name ?? slug,
+            ...(icon ? { icon } : {}),
+            ...(description ? { description } : {}),
+          }),
+        ),
+      );
+      return;
+    }
+    case "install": {
+      const listingId = shift(ctx.args, "listing id");
+      out(
+        ctx,
+        await ctx.convex.action(api.install, withAuth(ctx, { listingId })),
+      );
+      return;
+    }
+    case "publish": {
+      const slug = takeFlag(ctx.args, "--slug");
+      const name = takeFlag(ctx.args, "--name");
+      const description = takeFlag(ctx.args, "--description");
+      const icon = takeFlag(ctx.args, "--icon");
+      const visibility = takeFlag(ctx.args, "--visibility");
+      const version = takeFlag(ctx.args, "--version");
+      const appPath = firstPositional(ctx.args);
+      if (!appPath || !slug || !name) {
+        throw new AppsCliError(
+          'Usage: dench apps publish <appPath> --slug <slug> --name "My App"',
+        );
+      }
+      out(
+        ctx,
+        await ctx.convex.action(
+          api.publish,
+          withAuth(ctx, {
+            appPath,
+            slug,
+            name,
+            ...(description ? { description } : {}),
+            ...(icon ? { icon } : {}),
+            ...(visibility ? { visibility } : {}),
+            ...(version ? { version } : {}),
+          }),
+        ),
+      );
+      return;
+    }
+    case "uninstall": {
+      const slug = shift(ctx.args, "app slug");
+      out(
+        ctx,
+        await ctx.convex.mutation(api.uninstall, withAuth(ctx, { slug })),
+      );
+      return;
+    }
+    case "enable":
+    case "disable": {
+      const slug = shift(ctx.args, "app slug");
+      await ctx.convex.mutation(
+        api.setEnabled,
+        withAuth(ctx, { slug, enabled: sub === "enable" }),
+      );
+      out(ctx, { ok: true, slug, enabled: sub === "enable" });
+      return;
+    }
+    case "pin":
+    case "unpin": {
+      const slug = shift(ctx.args, "app slug");
+      await ctx.convex.mutation(
+        api.setPinned,
+        withAuth(ctx, { slug, pinned: sub === "pin" }),
+      );
+      out(ctx, { ok: true, slug, pinned: sub === "pin" });
+      return;
+    }
+    default:
+      throw new AppsCliError(`Unknown apps subcommand: ${sub}`);
+  }
+}

package/dench.ts

@@ -174,6 +174,12 @@ const api = {
     },
     files: {
       listTree: makeFunctionReference<"query">("functions/files:listTree"),
+      getFileContent: makeFunctionReference<"query">(
+        "functions/files:getFileContent",
+      ),
+      editFileFromUI: makeFunctionReference<"action">(
+        "functions/files:editFileFromUI",
+      ),
       deleteFile: makeFunctionReference<"mutation">(
         "functions/files:deleteFile",
       ),
@@ -471,7 +477,7 @@ Usage:
   dench approval reject <approvalId> [--evidence "User said no in chat"] [--json]
   dench billing status [--json]
   dench billing topup --amount 5 [--no-open] [--json]
-  dench apps [--json]
+  dench integrations [--json]
   dench tool status [toolkit] [--json]
   dench tool connect <toolkit> [--json]
   dench tool search "create github issue" [--toolkit github] [--limit 20] [--compact] [--json]
@@ -611,7 +617,8 @@ Self-updating agent harness:
   Help: dench identity help
 
 External tools:
-  dench apps is an alias for dench tool status -- it lists connected apps.
+  dench integrations is an alias for dench tool status -- it lists connected apps.
+  dench apps is the App Store (create / install / publish / list), not Composio.
   dench tool with no subcommand prints tool help.
   Read-only FETCH, GET, LIST, SEARCH, READ, and FIND tools do not need manual approval.
 
@@ -667,10 +674,10 @@ function toolHelp() {
   console.log(`Dench tool commands
 
 Usage:
-  dench apps [--json]
+  dench integrations [--json]
   dench tool status [toolkit] [--json]
   dench tool connect <toolkit> [--callback-url <url>] [--json]
-  dench tool search "create github issue" [--toolkit github] [--limit 20] [--json]
+  dench tool search "create github issue" [--toolkit github] [--limit 20] [--compact] [--json]
   dench tool run <composio_tool_slug> --args '{"key":"value"}' [--account <connectedAccountId>] [--json]
   dench tool disconnect <connectionId> [--json]
 
@@ -682,7 +689,7 @@ Auth:
   same way (the CLI exchanges the session for a gateway key on demand).
 
 Notes:
-  dench apps is an alias for dench tool status.
+  dench integrations is an alias for dench tool status.
   dench tool connect prints the OAuth redirect URL for the human to open.
   dench tool run output is redacted for display; pass --json for raw JSON.
   Override the gateway base with DENCH_GATEWAY_URL or GATEWAY_URL.
@@ -3420,6 +3427,105 @@ async function runFilesRm() {
   });
 }
 
+/**
+ * Print a workspace file's text.
+ *
+ * `download` cannot reach the magic files (IDENTITY.md, ORGANISATION.md, …)
+ * because they render from agentConfig and have no storage blob, so this is
+ * the only way to read them from outside a browser session.
+ */
+async function runFilesCat() {
+  const runtime = await getRuntime();
+  const apiKey = await requireFilesApiKey(runtime, "dench files cat");
+  const targetRaw = positional(2);
+  if (!targetRaw) {
+    throw new CliError("Usage: dench files cat <path> [--json]", {
+      code: "files_cat_usage",
+    });
+  }
+  const target = normalizeFilesPath(targetRaw);
+  const file = (await runtime.client.query(api.functions.files.getFileContent, {
+    path: target,
+    apiKey,
+  } as never)) as {
+    path: string;
+    isDir: boolean;
+    virtual: boolean;
+    size: number | null;
+    content: string | null;
+    downloadable: boolean;
+  } | null;
+
+  if (!file) {
+    throw new CliError(`Not found in Convex: ${target}`, {
+      code: "files_cat_not_found",
+      nextActions: [
+        "Run `dench files ls` on the parent directory to confirm.",
+        "If the file only exists on the sandbox FS, run `dench fs sync --initial` first.",
+      ],
+    });
+  }
+  if (file.isDir) {
+    throw new CliError(`${target} is a directory`, {
+      code: "files_cat_directory",
+      nextActions: ["Run `dench files ls` to list its entries."],
+    });
+  }
+  if (file.content === null) {
+    throw new CliError(`No inline text for ${target}`, {
+      code: "files_cat_not_text",
+      nextActions: file.downloadable
+        ? ["Run `dench files download` to fetch the bytes."]
+        : ["The file has no stored bytes yet."],
+    });
+  }
+
+  if (hasFlag("--json")) {
+    print({ ok: true, ...file });
+    return;
+  }
+  process.stdout.write(
+    file.content.endsWith("\n") ? file.content : `${file.content}\n`,
+  );
+}
+
+/**
+ * Replace a workspace file's text, reading the new content from stdin.
+ *
+ * `stage` copies from a sandbox path and `commitFileUpload` needs an upload
+ * round-trip, so neither works for "change these few lines from a terminal".
+ */
+async function runFilesWrite() {
+  const runtime = await getRuntime();
+  const apiKey = await requireFilesApiKey(runtime, "dench files write");
+  const targetRaw = positional(2);
+  if (!targetRaw) {
+    throw new CliError("Usage: dench files write <path> < file.md", {
+      code: "files_write_usage",
+      nextActions: ["Pipe the new contents in on stdin."],
+    });
+  }
+  const target = normalizeFilesPath(targetRaw);
+  const content = await new Response(Bun.stdin.stream()).text();
+
+  const result = (await runtime.client.action(
+    api.functions.files.editFileFromUI,
+    {
+      path: target,
+      content,
+      apiKey,
+    } as never,
+  )) as { path: string; contentHash: string };
+
+  if (hasFlag("--json")) {
+    print({ ok: true, ...result, bytes: content.length });
+    return;
+  }
+  process.stdout.write(
+    `dench files write: ${result.path} (${content.length}B)\n`,
+  );
+}
+
 async function writeLocalFileBytes(localPath: string, bytes: Uint8Array) {
   const parent = dirname(localPath);
   if (parent && parent !== ".") {
@@ -3554,15 +3660,19 @@ async function runFilesCommand() {
   if (!sub || sub === "help" || hasFlag("--help")) {
     process.stdout.write(
       [
-        "dench files <ls|mv|rm|download> — workspace file ops that update the UI tree",
+        "dench files <ls|cat|write|mv|rm|download> — workspace file ops that update the UI tree",
         "",
         "  dench files ls [<path>] [--recursive] [--json]",
+        "  dench files cat <path> [--json]",
+        "  dench files write <path> < file.md   (content on stdin)",
         "  dench files mv <src> <dst> [--json]",
         "  dench files rm <path> [--recursive] [--json]",
         "  dench files download <path> [<local-dest>] [--url] [--json]",
         "",
         "Paths are POSIX paths under /workspace; you can pass either form.",
         "These mutate Convex directly (and the daemon syncs to the volume).",
+        "cat prints inline text and is the only way to read the magic files",
+        "(IDENTITY.md, ORGANISATION.md, …), which have no stored bytes.",
         "download fetches canonical bytes from Convex (dirs recurse);",
         "--url prints a short-lived signed URL instead of saving.",
       ].join("\n"),
@@ -3570,6 +3680,8 @@ async function runFilesCommand() {
     return;
   }
   if (sub === "ls") return await runFilesLs();
+  if (sub === "cat") return await runFilesCat();
+  if (sub === "write") return await runFilesWrite();
   if (sub === "mv") return await runFilesMv();
   if (sub === "rm") return await runFilesRm();
   if (sub === "download") return await runFilesDownload();

package/lib/command-registry.ts

@@ -1957,6 +1957,32 @@ const rawApiOperations = [
       tokenArg: "apiKey",
     }),
   }),
+  op({
+    id: "files.content",
+    group: "files",
+    summary: "Read a workspace file's text.",
+    cli: "dench files cat",
+    method: "GET",
+    path: "/files/content",
+    requestSchema: noBody,
+    responseSchema: anyResponse,
+    backend: convex("query", "functions/files:getFileContent", "bearer", {
+      tokenArg: "apiKey",
+    }),
+  }),
+  op({
+    id: "files.write",
+    group: "files",
+    summary: "Write a workspace file's text.",
+    cli: "dench files write",
+    method: "PUT",
+    path: "/files/content",
+    requestSchema: anyObject,
+    responseSchema: anyResponse,
+    backend: convex("action", "functions/files:editFileFromUI", "bearer", {
+      tokenArg: "apiKey",
+    }),
+  }),
   op({
     id: "files.downloadUrl",
     group: "files",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "2.7.3",
+  "version": "2.7.5",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {
@@ -32,6 +32,7 @@
     "search.ts",
     "image.ts",
     "tools.ts",
+    "apps.ts",
     "agentKind.ts",
     "agent-config.ts",
     "host.ts",

package/tools.ts

@@ -11,7 +11,7 @@
  *
  *   dench apps [--json]                                            — list connected apps
  *   dench tool status [toolkit?] [--json]                          — list connections (optionally narrowed)
- *   dench tool search "<query>" [--toolkit <slug>] [--limit N] [--json]
+ *   dench tool search "<query>" [--toolkit <slug>] [--limit N] [--compact] [--json]
  *   dench tool run <slug> [--args <json>] [--account <id>] [--json]
  *   dench tool connect <toolkit> [--callback-url <url>] [--json]   — print OAuth redirect URL
  *   dench tool disconnect <connectionId> [--json]
@@ -187,12 +187,22 @@ async function runSearchSubcommand(ctx: ToolCliContext): Promise<void> {
   const toolkit = getFlag(ctx.args, "--toolkit");
   const limitRaw = getFlag(ctx.args, "--limit");
   const limit = limitRaw ? parsePositiveInt("--limit", limitRaw) : undefined;
+  const compact = hasFlag(ctx.args, "--compact");
   const queryParts = ctx.args.slice();
   ctx.args.length = 0;
+  // Everything left is the query, so an unconsumed flag would be searched for
+  // as a word and quietly match nothing. Refuse it instead: a typo that reads
+  // as "no results" is indistinguishable from an empty catalog.
+  const unknown = queryParts.find((part) => part.startsWith("--"));
+  if (unknown) {
+    throw new ToolCliError(
+      `Unknown flag for dench tool search: ${unknown}. Supported: --toolkit <slug>, --limit N, --compact, --json.`,
+    );
+  }
   const query = queryParts.join(" ").trim();
   if (!query) {
     throw new ToolCliError(
-      'Usage: dench tool search "<query>" [--toolkit <slug>] [--limit N] [--json]',
+      'Usage: dench tool search "<query>" [--toolkit <slug>] [--limit N] [--compact] [--json]',
     );
   }
 
@@ -210,7 +220,7 @@ async function runSearchSubcommand(ctx: ToolCliContext): Promise<void> {
     console.log(JSON.stringify(payload, null, 2));
     return;
   }
-  console.log(formatSearchResult(payload));
+  console.log(formatSearchResult(payload, compact));
 }
 
 async function runRunSubcommand(ctx: ToolCliContext): Promise<void> {
@@ -249,7 +259,22 @@ async function runRunSubcommand(ctx: ToolCliContext): Promise<void> {
       body,
     );
   } catch (error) {
-    if (error instanceof GatewayHttpError && isLikelyNoConnection(error)) {
+    if (!(error instanceof GatewayHttpError)) throw error;
+    // Ambiguity is the opposite of a missing connection, and it has to be
+    // checked first: the gateway reports it with a 400 whose body also trips
+    // the no-connection hints, which would send the caller off to add a third
+    // account when the fix is to name one of the two they have.
+    if (isAccountSelectionRequired(error)) {
+      const selection = accountSelectionPayload(toolSlug, error);
+      console.log(
+        ctx.jsonOutput
+          ? JSON.stringify(selection, null, 2)
+          : formatAccountSelection(selection),
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (isLikelyNoConnection(error)) {
       const noConnPayload = noConnectionPayload(toolSlug, error);
       if (ctx.jsonOutput) {
         console.log(JSON.stringify(noConnPayload, null, 2));
@@ -475,8 +500,9 @@ async function callGateway(
 // Result extraction & formatting
 // ---------------------------------------------------------------------------
 
+const ACCOUNT_SELECTION_CODE = "composio_account_selection_required";
+
 const NO_CONNECTION_HINTS = [
-  "composio_account_selection_required",
   "no active connection",
   "no connection found",
   "connected_account_id is required",
@@ -493,6 +519,78 @@ function isLikelyNoConnection(error: GatewayHttpError): boolean {
   return NO_CONNECTION_HINTS.some((hint) => lower.includes(hint));
 }
 
+function isAccountSelectionRequired(error: GatewayHttpError): boolean {
+  return error.body.toLowerCase().includes(ACCOUNT_SELECTION_CODE);
+}
+
+function accountSelectionPayload(toolSlug: string, error: GatewayHttpError) {
+  const accounts = accountChoices(error.body);
+  return {
+    ok: false,
+    account_selection_required: true,
+    tool_slug: toolSlug,
+    toolkit: toolkitFromSlug(toolSlug),
+    accounts,
+    error: error.message,
+    next_actions: accounts.length
+      ? accounts.map(
+          (account) =>
+            `Re-run with --account ${account.connected_account_id}${account.label ? ` (${account.label})` : ""}`,
+        )
+      : [
+          "Re-run with --account <connected_account_id>. Run `dench tool status <toolkit> --json` to list them.",
+        ],
+  };
+}
+
+/**
+ * The candidate accounts named in an account-selection error. The gateway
+ * already lists them, so parse them back out rather than spending a round trip
+ * re-listing connections the caller was just handed.
+ *
+ * They arrive as a JSON array inside the JSON-encoded error message, so decode
+ * the body first: that hands the array back unescaped instead of leaving us to
+ * undo the escaping by hand.
+ */
+function accountChoices(body: string) {
+  const error = asRecord(asRecord(parseJsonOrUndefined(body))?.error);
+  const message = stringField(error, "message") ?? "";
+  const start = message.indexOf("[");
+  const end = message.lastIndexOf("]");
+  if (start === -1 || end <= start) return [];
+  const parsed = parseJsonOrUndefined(message.slice(start, end + 1));
+  return asRecordArray(parsed).flatMap((entry) => {
+    const id = stringField(entry, "connected_account_id");
+    if (!id) return [];
+    return [
+      { connected_account_id: id, label: stringField(entry, "label", "email") },
+    ];
+  });
+}
+
+function parseJsonOrUndefined(value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function formatAccountSelection(
+  payload: ReturnType<typeof accountSelectionPayload>,
+) {
+  return [
+    "Multiple active accounts for this tool — name the one to use.",
+    `Tool: ${payload.tool_slug}`,
+    payload.toolkit ? `Toolkit: ${payload.toolkit}` : null,
+    "",
+    "Next actions:",
+    ...payload.next_actions.map((line) => `  - ${line}`),
+  ]
+    .filter((line) => line !== null)
+    .join("\n");
+}
+
 function noConnectionPayload(toolSlug: string, error: GatewayHttpError) {
   const toolkit = toolkitFromSlug(toolSlug);
   return {
@@ -623,7 +721,7 @@ function toolApprovalHint(toolSlug: string | undefined): string {
   return readOnly ? `read-only (${readOnly})` : "approval likely";
 }
 
-function formatSearchResult(searchResult: unknown): string {
+function formatSearchResult(searchResult: unknown, compact = false): string {
   const root = asRecord(searchResult);
   const data = asRecord(root?.data) ?? root;
   const items = extractSearchItems(data);
@@ -658,7 +756,9 @@ function formatSearchResult(searchResult: unknown): string {
     const isConnected =
       booleanField(asRecord(tool.connection_status), "is_connected") ??
       connectedSet.has(toolkit.toLowerCase());
-    const description = compactLine(tool.description) ?? null;
+    const description = compact
+      ? null
+      : (compactLine(tool.description) ?? null);
     lines.push(
       `${index + 1}. ${slug} - ${name}`,
       `   toolkit: ${toolkit} | ${toolApprovalHint(slug)} | ${
@@ -752,7 +852,7 @@ Usage:
   dench apps [--json]
   dench tool status [toolkit] [--json]
   dench tool connect <toolkit> [--callback-url <url>] [--json]
-  dench tool search "create github issue" [--toolkit github] [--limit 20] [--json]
+  dench tool search "create github issue" [--toolkit github] [--limit 20] [--compact] [--json]
   dench tool run <composio_tool_slug> --args '{"key":"value"}' [--account <connectedAccountId>] [--json]
   dench tool disconnect <connectionId> [--json]