@dench.com/cli 2.7.2 → 2.7.4

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

@@ -40,6 +40,7 @@ import {
   type StoredSessionEntry,
   selectStoredSession,
   selectStoredSessionEntry,
+  usesInjectedAgentSession,
   withCurrentSessionSelection,
   withSavedSession,
 } from "./session";
@@ -173,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",
       ),
@@ -470,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]
@@ -610,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.
 
@@ -666,7 +674,7 @@ 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]
@@ -681,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.
@@ -2392,7 +2400,13 @@ async function getRuntime() {
   if (!hasFlag("--dev")) {
     const config = await loadConfig();
     const host = resolveHost(config, scope);
-    const stored = await getStoredSession(host, scope);
+
+    // An injected agent-session token outranks whatever `dench signin` last
+    // saved here — see `usesInjectedAgentSession` for why the API key does not
+    // get the same treatment.
+    const stored = usesInjectedAgentSession()
+      ? ({ status: "missing" } as const)
+      : await getStoredSession(host, scope);
     if (stored.status === "found") {
       return {
         mode: "session" as const,
@@ -2451,9 +2465,9 @@ async function getRuntime() {
       };
     }
 
-    // Fallback: no API key present (older sandbox images / custom setups) —
-    // use the agent-session token. Still subject to expiry, but it's the
-    // only credential available in this branch.
+    // No API key present: an older sandbox image, a custom setup, or Dench
+    // Code, which injects only this token. Still subject to expiry, but it is
+    // the only credential available in this branch.
     const sandboxAgentToken = process.env.DENCH_AGENT_SESSION_TOKEN?.trim();
     if (sandboxAgentToken && sandboxConvexUrl) {
       const apiHost = resolveApiHost(host);
@@ -3413,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 !== ".") {
@@ -3547,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"),
@@ -3563,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.2",
+  "version": "2.7.4",
   "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/session.ts

@@ -208,6 +208,26 @@ export function resolveSessionScope({
   };
 }
 
+/**
+ * Whether an injected agent-session token should stand in for a saved
+ * `dench signin` session.
+ *
+ * `DENCH_AGENT_SESSION_TOKEN` names which identity to act as, so it outranks
+ * whatever was last saved on the host. Only sandboxes and Dench Code set it —
+ * nobody exports it by hand — and without this a host with any saved session
+ * silently ignores it, or fails as `session_ambiguous` when several are saved.
+ *
+ * `DENCH_API_KEY` deliberately does not qualify. People export that one
+ * manually for unrelated reasons, and quietly swapping their identity would be
+ * a surprise. Sandboxes set both and have no saved session anyway, so they
+ * keep landing on the API key, which is what they want: the key has no TTL
+ * while the agent-session token expires.
+ */
+export function usesInjectedAgentSession(env: Env = process.env) {
+  if (env.DENCH_API_KEY?.trim()) return false;
+  return Boolean(env.DENCH_AGENT_SESSION_TOKEN?.trim());
+}
+
 export function sessionConfigKey(host: string, scope: SessionScope) {
   return `${normalizeHostValue(host)}#${scope.key}`;
 }