@dench.com/cli 0.4.5 → 0.4.7

package/fs-daemon.ts

@@ -68,6 +68,12 @@ import {
   readMountInfo,
 } from "./fs-daemon-mount";
 
+type FileTreeSyncRow = {
+  path: string;
+  contentHash?: string;
+  isDir: boolean;
+};
+
 type Args = {
   orgId?: string;
   workspace: string;
@@ -302,6 +308,9 @@ const api = {
     ),
     deleteFile: makeFunctionReference<"mutation">("functions/files:deleteFile"),
     listTree: makeFunctionReference<"query">("functions/files:listTree"),
+    listTreeSnapshot: makeFunctionReference<"query">(
+      "functions/files:listTreeSnapshot",
+    ),
     resolveApiKeyOrganization: makeFunctionReference<"query">(
       "functions/files:resolveApiKeyOrganization",
     ),
@@ -404,13 +413,11 @@ class DenchFileClient {
    * fs status` to recursively crawl the canonical tree and diff
    * against the local FS snapshot.
    */
-  async listTree(
-    prefix: string,
-  ): Promise<Array<{ path: string; contentHash?: string; isDir: boolean }>> {
+  async listTree(prefix: string): Promise<FileTreeSyncRow[]> {
     const rows = (await this.http.query(api.files.listTree, {
       prefix,
       apiKey: this.apiKey,
-    })) as Array<{ path: string; contentHash?: string; isDir: boolean }>;
+    })) as FileTreeSyncRow[];
     return Array.isArray(rows) ? rows : [];
   }
 
@@ -468,25 +475,26 @@ class DenchFileClient {
    */
   subscribeFileTree(
     convexUrl: string,
-    onChange: (
-      rows: Array<{ path: string; contentHash?: string; isDir: boolean }>,
-    ) => void,
+    onChange: (rows: FileTreeSyncRow[]) => void,
   ): () => void {
     if (!this.realtime) {
       this.realtime = new ConvexClient(convexUrl);
     }
     const unsubscribe = this.realtime.onUpdate(
-      api.files.listTree,
-      { prefix: "/", apiKey: this.apiKey },
-      (rows: unknown) => {
-        const list = Array.isArray(rows)
-          ? (rows as Array<{
-              path: string;
-              contentHash?: string;
-              isDir: boolean;
-            }>)
-          : [];
-        onChange(list);
+      api.files.listTreeSnapshot,
+      { apiKey: this.apiKey },
+      (snapshot: unknown) => {
+        // Remote writes may land deep in the tree (for example seeded
+        // `/skills/<slug>/SKILL.md` files). A root-only `listTree`
+        // subscription only sees the `/skills` directory row, so it
+        // never pulls the actual file bytes down to the volume.
+        const rows =
+          snapshot &&
+          typeof snapshot === "object" &&
+          Array.isArray((snapshot as { rows?: unknown }).rows)
+            ? (snapshot as { rows: FileTreeSyncRow[] }).rows
+            : [];
+        onChange(rows);
       },
     );
     return unsubscribe;

package/host.ts

@@ -1,7 +1,24 @@
 export const PRODUCTION_HOST = "https://dench.dev";
 export const STAGING_HOST = "https://workspace-staging.dench.com";
+export const LOCAL_HOST = "http://localhost:3000";
 export const DEFAULT_HOST = PRODUCTION_HOST;
 
+/**
+ * Production-only fallbacks baked into the CLI binary so it does the
+ * right thing even when run with no config and no env vars (e.g. in a
+ * sandbox whose `buildSandboxEnvVars` map was assembled while the
+ * Vercel deployment was missing one of these keys).
+ *
+ * If any of these is wrong, EVERY install of @dench.com/cli is broken
+ * until republished — keep them in sync with whichever Convex
+ * deployment + Next.js host backs `https://www.dench.com`.
+ */
+export const PRODUCTION_API_URL = "https://www.dench.com";
+export const PRODUCTION_CONVEX_URL = "https://beaming-alligator-67.convex.cloud";
+export const PRODUCTION_GATEWAY_URL = "https://gateway.merseoriginals.com";
+
+export type BackendAlias = "production" | "prod" | "staging" | "local";
+
 function optionFromArgs(args: string[], name: string) {
   const index = args.indexOf(name);
   if (index === -1) return undefined;
@@ -13,7 +30,13 @@ function hasFlag(args: string[], name: string) {
 }
 
 export function normalizeHost(input: string) {
-  const withProtocol = /^https?:\/\//.test(input) ? input : `https://${input}`;
+  const trimmed = input.trim();
+  if (/^(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::|$)/.test(trimmed)) {
+    return new URL(`http://${trimmed}`).origin;
+  }
+  const withProtocol = /^https?:\/\//.test(trimmed)
+    ? trimmed
+    : `https://${trimmed}`;
   const url = new URL(withProtocol);
   return url.origin;
 }
@@ -29,6 +52,39 @@ export function isLocalHost(input: string) {
   );
 }
 
+/**
+ * Resolve `local|staging|prod|production|<url>` -> a normalized host
+ * origin. Aliases let `dench backend set <alias>` (and `--backend
+ * <alias>`) accept the short forms most agents reach for first.
+ * Returns `undefined` for empty input and throws on values that
+ * neither match an alias nor parse as a URL.
+ */
+export function resolveBackendAlias(input: string): string {
+  const value = input.trim();
+  if (!value) {
+    throw new Error(
+      "Backend value is empty. Pass local, staging, prod, or a URL like https://dench.dev.",
+    );
+  }
+  const normalized = value.toLowerCase();
+  if (normalized === "prod" || normalized === "production") {
+    return PRODUCTION_HOST;
+  }
+  if (normalized === "staging" || normalized === "stage") {
+    return STAGING_HOST;
+  }
+  if (normalized === "local" || normalized === "localhost" || normalized === "dev") {
+    return LOCAL_HOST;
+  }
+  try {
+    return normalizeHost(value);
+  } catch (_error) {
+    throw new Error(
+      `Unrecognized backend "${value}". Use local, staging, prod, or a URL like https://dench.dev.`,
+    );
+  }
+}
+
 export function resolveHostFromArgs(
   args: string[],
   configHost?: string,
@@ -37,6 +93,9 @@ export function resolveHostFromArgs(
   if (hasFlag(args, "--prod")) return PRODUCTION_HOST;
   if (hasFlag(args, "--staging")) return STAGING_HOST;
 
+  const explicitBackend = optionFromArgs(args, "--backend");
+  if (explicitBackend) return resolveBackendAlias(explicitBackend);
+
   const explicit = optionFromArgs(args, "--host") ?? envHost;
   if (explicit) return normalizeHost(explicit);
   if (configHost) return normalizeHost(configHost);

package/lib/enrichment-gateway.ts

@@ -5,10 +5,13 @@ export type FetchLike = (
   init?: RequestInit,
 ) => Promise<Response>;
 
-export type EnrichmentGatewayEnv = Pick<
-  NodeJS.ProcessEnv,
-  "DENCH_API_KEY" | "DENCH_GATEWAY_URL" | "GATEWAY_URL" | "DENCH_HOST"
->;
+export type EnrichmentGatewayEnv = {
+  DENCH_API_KEY?: string;
+  DENCH_GATEWAY_URL?: string;
+  GATEWAY_URL?: string;
+  DENCH_HOST?: string;
+  [key: string]: string | undefined;
+};
 
 export class EnrichmentGatewayError extends Error {
   readonly status?: number;

package/lib/load-dev-env.mjs

@@ -1,27 +1,100 @@
-// When `./dench` (or `./dench.mjs`) runs through Node from inside the
-// dench.com source tree, Node does not auto-load workspace `.env` files
-// the way Bun does for `bun run`. That made every gateway-backed
-// subcommand (`dench apps`, `dench tool …`, the enrichment helpers,
-// etc.) silently default to production
-// (`https://gateway.merseoriginals.com`), because `cli/tools.ts`
-// resolves the gateway URL purely from `process.env`. A dev-issued
-// `DENCH_API_KEY` then 401'd against prod with `invalid_api_key`.
+// `./dench` and `./dench.mjs` ship as Node entry points. When Node runs
+// them from inside the dench.com source tree it does NOT auto-load
+// workspace `.env` files the way `bun run` does, so we have a one-shot
+// chance here to inject env vars (e.g. `GATEWAY_URL`,
+// `NEXT_PUBLIC_CONVEX_URL`) before `dench.ts` is imported.
 //
-// This helper detects the dench.com source tree (via the parent
-// `package.json` name) and loads `.env` then `.env.local` from the repo
-// root. Globally-installed and sandbox-baked CLI installs never see
-// that marker, so this is a no-op there. Existing `process.env` values
-// always win, so explicit shell exports (e.g.
-// `GATEWAY_URL=… ./dench …`) still take precedence over file values.
+// HISTORY: this helper used to ALWAYS load `.env` and `.env.local` when
+// the parent package was `ironclaw-cloud`. That fixed gateway-backed
+// subcommands (`dench apps`, `dench tool …`, the enrichment helpers)
+// that would otherwise silently 401 against production gateway with a
+// dev-issued `DENCH_API_KEY`. The side effect was severe: the auto-load
+// also injected `NEXT_PUBLIC_CONVEX_URL=…dev convex…` and friends, so
+// every Convex call from the CLI silently pointed at the dev
+// deployment, even when the user expected production.
+//
+// FIX: dev-env loading is now OPT-IN. The default is "do nothing" so
+// the CLI always defaults to production, no matter where it is invoked
+// from. Users opt into local/dev env vars one of three ways:
+//
+//   1. `--dev` flag in argv (existing flag — also flips the runtime to
+//      dev workspace mode).
+//   2. `--use-dev-env` flag in argv (load `.env` files without
+//      switching to dev workspace mode — useful when you want
+//      `GATEWAY_URL=http://0.0.0.0:8787` baked in but still talk to a
+//      stored session).
+//   3. `DENCH_USE_DEV_ENV=1` env var (same effect as `--use-dev-env`,
+//      handy for `direnv` setups).
+//   4. `defaultBackend: "http://localhost:…"` (or any local URL) in
+//      `~/.dench/config.json` — set via `dench backend set local`. If
+//      the user has explicitly pointed the CLI at localhost they almost
+//      always also want the dev gateway URL.
+//
+// Existing `process.env` values always win, so explicit shell exports
+// (e.g. `GATEWAY_URL=… ./dench …`) keep working even with auto-load
+// disabled.
 
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const WORKSPACE_PACKAGE_NAME = "ironclaw-cloud";
 const ENV_FILES = [".env", ".env.local"];
+const CONFIG_PATH = join(homedir(), ".dench", "config.json");
+
+const TRUE_ENV_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function envFlagEnabled(value) {
+  if (!value) return false;
+  return TRUE_ENV_VALUES.has(value.trim().toLowerCase());
+}
 
-export function loadDevEnv(callerUrl) {
+function argvOptIn(argv) {
+  if (!Array.isArray(argv)) return false;
+  return argv.includes("--dev") || argv.includes("--use-dev-env");
+}
+
+function configOptIn() {
+  try {
+    if (!existsSync(CONFIG_PATH)) return false;
+    const raw = readFileSync(CONFIG_PATH, "utf8");
+    const config = JSON.parse(raw);
+    const backend = config?.defaultBackend;
+    if (typeof backend !== "string" || !backend.trim()) return false;
+    return isLocalUrl(backend.trim());
+  } catch {
+    return false;
+  }
+}
+
+function isLocalUrl(value) {
+  try {
+    const url = new URL(/^https?:\/\//.test(value) ? value : `https://${value}`);
+    const host = url.hostname;
+    return (
+      host === "localhost" ||
+      host === "127.0.0.1" ||
+      host === "0.0.0.0" ||
+      host === "::1" ||
+      host.endsWith(".localhost")
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function shouldLoadDevEnv({
+  argv = process.argv.slice(2),
+  env = process.env,
+} = {}) {
+  if (envFlagEnabled(env.DENCH_USE_DEV_ENV)) return "env";
+  if (argvOptIn(argv)) return "argv";
+  if (configOptIn()) return "config";
+  return false;
+}
+
+export function loadDevEnv(callerUrl, options = {}) {
   try {
     const here = dirname(fileURLToPath(callerUrl));
     const repoRoot = dirname(here);
@@ -30,6 +103,8 @@ export function loadDevEnv(callerUrl) {
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
     if (pkg?.name !== WORKSPACE_PACKAGE_NAME) return;
 
+    if (!shouldLoadDevEnv(options)) return;
+
     for (const filename of ENV_FILES) {
       const path = join(repoRoot, filename);
       if (!existsSync(path)) continue;

package/lib/load-dev-env.test.mjs

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "bun:test";
+import { shouldLoadDevEnv } from "./load-dev-env.mjs";
+
+describe("shouldLoadDevEnv", () => {
+  it("returns false on a fresh install with no opt-in", () => {
+    expect(shouldLoadDevEnv({ argv: [], env: {} })).toBe(false);
+  });
+
+  it("opts in when --dev is in argv", () => {
+    expect(shouldLoadDevEnv({ argv: ["status", "--dev"], env: {} })).toBe(
+      "argv",
+    );
+  });
+
+  it("opts in when --use-dev-env is in argv", () => {
+    expect(
+      shouldLoadDevEnv({ argv: ["apps", "--use-dev-env"], env: {} }),
+    ).toBe("argv");
+  });
+
+  it("opts in when DENCH_USE_DEV_ENV is set to a truthy value", () => {
+    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "1" } })).toBe(
+      "env",
+    );
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "true" } }),
+    ).toBe("env");
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "yes" } }),
+    ).toBe("env");
+  });
+
+  it("ignores DENCH_USE_DEV_ENV when set to a falsy/empty value", () => {
+    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "" } })).toBe(
+      false,
+    );
+    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "0" } })).toBe(
+      false,
+    );
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "false" } }),
+    ).toBe(false);
+  });
+});

package/package.json

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

package/tools.ts

@@ -36,6 +36,10 @@
  * working.
  */
 
+import {
+  PRODUCTION_API_URL,
+  PRODUCTION_GATEWAY_URL,
+} from "./host";
 import {
   CliArgError,
   getFlag,
@@ -380,7 +384,7 @@ function resolveGatewayBaseUrl(): string {
   if (host && /localhost|127\.0\.0\.1/.test(host)) {
     return "http://localhost:8787";
   }
-  return "https://gateway.merseoriginals.com";
+  return PRODUCTION_GATEWAY_URL;
 }
 
 /**
@@ -403,7 +407,7 @@ function resolveAppPublicOrigin(): string {
     const trimmed = candidate?.trim();
     if (trimmed) return trimmed.replace(/\/+$/, "");
   }
-  return "https://dench.com";
+  return PRODUCTION_API_URL;
 }
 
 function requireApiKey(): string {