@dench.com/cli 0.3.5 → 0.3.7

package/image.ts

@@ -0,0 +1,435 @@
+/**
+ * `dench image generate|edit` — gpt-image-2 backed image creation through
+ * the Dench Cloud Gateway.
+ *
+ * Mirrors `dench search`: bypasses Convex entirely and talks straight HTTP
+ * to the gateway, authenticating with the `DENCH_API_KEY` baked into every
+ * sandbox at create time. Works anywhere that env var is exported (sandbox,
+ * CI, local dev).
+ *
+ * Persistence model: the gateway already writes the bytes to Convex Storage
+ * + the org's fileTree on success (so the workspace UI sees the file
+ * immediately without any client-side orchestration). When the CLI is
+ * running inside a sandbox, we ALSO write the decoded bytes to disk at
+ * `--output` (default: `/workspace/image-generations/...`) so the very
+ * next bash command (e.g. `convert image.png -resize 50% small.png`) can
+ * see it without waiting on the daemon's downward sync — the same
+ * defense-in-depth pattern the chat-turn workflow tool uses.
+ *
+ * Subcommands:
+ *   image generate "<prompt>" [--size 1024x1024] [--quality auto|low|medium|high]
+ *                  [--format png|jpeg|webp] [--save-path /workspace/...]
+ *                  [--output <local file>] [--no-write] [--json]
+ *   image edit "<prompt>" --input <path> [--input <path> ...] [--mask <path>]
+ *              [--size ...] [--quality ...] [--format ...] [--save-path ...]
+ *              [--output ...] [--no-write] [--json]
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+type ImageCliContext = {
+  args: string[];
+  jsonOutput: boolean;
+};
+
+class ImageCliError extends Error {}
+
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) {
+      throw new ImageCliError(error.message);
+    }
+    throw error;
+  }
+}
+
+const ALLOWED_QUALITIES = new Set(["auto", "low", "medium", "high"]);
+const ALLOWED_FORMATS = new Set(["png", "jpeg", "webp"]);
+
+function resolveGatewayBaseUrl(): string {
+  const explicit =
+    process.env.DENCH_GATEWAY_URL?.trim() || process.env.GATEWAY_URL?.trim();
+  if (explicit) return explicit.replace(/\/+$/, "");
+  const host = process.env.DENCH_HOST?.trim();
+  if (host && /localhost|127\.0\.0\.1/.test(host)) {
+    return "http://localhost:8787";
+  }
+  return "https://gateway.merseoriginals.com";
+}
+
+function requireApiKey(): string {
+  const apiKey = process.env.DENCH_API_KEY?.trim();
+  if (!apiKey) {
+    throw new ImageCliError(
+      "DENCH_API_KEY is not set. Inside a Dench sandbox it is baked into " +
+        "the env automatically; outside, export it manually or run " +
+        "`dench login` first.",
+    );
+  }
+  return apiKey;
+}
+
+function resolveDefaultVolumeRoot(): string {
+  // Inside a sandbox the volume is mounted at `/workspace` and the
+  // gateway emits paths like `/image-generations/...png`. Outside a
+  // sandbox, write to `./image-generations/...png` so things still
+  // work in dev / CI.
+  return process.env.DENCH_VOLUME_PATH?.trim() || "/workspace";
+}
+
+function resolveOutputPath(
+  explicit: string | undefined,
+  gatewayPath: string,
+): string {
+  const root = resolveDefaultVolumeRoot();
+  if (explicit && explicit.length > 0) {
+    return isAbsolute(explicit) ? explicit : resolve(process.cwd(), explicit);
+  }
+  // gatewayPath is `/image-generations/<file>.png` (POSIX, leading slash).
+  return resolve(root, gatewayPath.replace(/^\/+/, ""));
+}
+
+async function readBase64FromPath(path: string): Promise<string> {
+  const absolute = isAbsolute(path) ? path : resolve(process.cwd(), path);
+  const bytes = await readFile(absolute);
+  return bytes.toString("base64");
+}
+
+type GatewayImageResponse = {
+  ok: boolean;
+  model?: string;
+  endpoint?: string;
+  prompt?: string;
+  revisedPrompt?: string;
+  quality?: string;
+  requestedSize?: string;
+  format?: string;
+  mimeType?: string;
+  estimatedCostUsd?: number;
+  b64_json?: string;
+  storageId?: string;
+  path?: string;
+  signedUrl?: string | null;
+  contentHash?: string;
+  sizeBytes?: number;
+  usage?: Record<string, number | undefined>;
+};
+
+async function callGateway(
+  path: "/v1/images/generations" | "/v1/images/edits",
+  body: Record<string, unknown>,
+): Promise<GatewayImageResponse> {
+  const apiKey = requireApiKey();
+  const baseUrl = resolveGatewayBaseUrl();
+  const response = await fetch(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = await response.text();
+    } catch {
+      // ignore
+    }
+    const truncated = detail.length > 500 ? `${detail.slice(0, 500)}…` : detail;
+    throw new ImageCliError(
+      `Gateway ${path} returned ${response.status}: ${truncated || response.statusText}`,
+    );
+  }
+  return (await response.json()) as GatewayImageResponse;
+}
+
+async function writeBytesToDisk(
+  outputPath: string,
+  base64: string,
+): Promise<{ path: string; size: number }> {
+  await mkdir(dirname(outputPath), { recursive: true });
+  const bytes = Buffer.from(base64, "base64");
+  await writeFile(outputPath, bytes);
+  return { path: outputPath, size: bytes.byteLength };
+}
+
+function out(
+  ctx: ImageCliContext,
+  payload: Record<string, unknown>,
+  formatted: string,
+): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(formatted);
+}
+
+function formatGenerationResult(
+  res: GatewayImageResponse,
+  localPath: string | null,
+): string {
+  const lines: string[] = [];
+  lines.push(`Generated image (${res.model ?? "gpt-image-2"})`);
+  if (res.prompt) {
+    lines.push(`  Prompt: ${res.prompt}`);
+  }
+  if (res.revisedPrompt && res.revisedPrompt !== res.prompt) {
+    lines.push(`  Revised: ${res.revisedPrompt}`);
+  }
+  if (res.requestedSize) lines.push(`  Size: ${res.requestedSize}`);
+  if (res.quality) lines.push(`  Quality: ${res.quality}`);
+  if (res.format) lines.push(`  Format: ${res.format}`);
+  if (typeof res.estimatedCostUsd === "number") {
+    lines.push(`  Cost (USD): $${res.estimatedCostUsd.toFixed(4)}`);
+  }
+  if (res.path) lines.push(`  Workspace: ${res.path}`);
+  if (res.signedUrl) lines.push(`  Signed URL: ${res.signedUrl}`);
+  if (localPath) lines.push(`  Local file: ${localPath}`);
+  return lines.join("\n");
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Subcommands
+// ────────────────────────────────────────────────────────────────────────────
+
+type CommonImageOpts = {
+  size?: string;
+  quality?: string;
+  format?: string;
+  savePath?: string;
+  output?: string;
+  noWrite: boolean;
+  background?: string;
+  moderation?: string;
+};
+
+function parseCommonOpts(args: string[]): CommonImageOpts {
+  const size = getFlag(args, "--size");
+  const quality = getFlag(args, "--quality");
+  if (quality !== undefined && !ALLOWED_QUALITIES.has(quality)) {
+    throw new ImageCliError(
+      `Invalid --quality: ${quality}. Allowed: ${[...ALLOWED_QUALITIES].join(", ")}`,
+    );
+  }
+  const format = getFlag(args, "--format");
+  if (format !== undefined && !ALLOWED_FORMATS.has(format)) {
+    throw new ImageCliError(
+      `Invalid --format: ${format}. Allowed: ${[...ALLOWED_FORMATS].join(", ")}`,
+    );
+  }
+  const savePath = getFlag(args, "--save-path");
+  const output = getFlag(args, "--output") ?? getFlag(args, "-o");
+  const noWrite = hasFlag(args, "--no-write");
+  const background = getFlag(args, "--background");
+  if (
+    background !== undefined &&
+    !["auto", "opaque", "transparent"].includes(background)
+  ) {
+    throw new ImageCliError(
+      `Invalid --background: ${background}. Allowed: auto, opaque, transparent`,
+    );
+  }
+  const moderation = getFlag(args, "--moderation");
+  if (moderation !== undefined && !["auto", "low"].includes(moderation)) {
+    throw new ImageCliError(
+      `Invalid --moderation: ${moderation}. Allowed: auto, low`,
+    );
+  }
+  return { size, quality, format, savePath, output, noWrite, background, moderation };
+}
+
+function buildGenerationBody(
+  prompt: string,
+  opts: CommonImageOpts,
+): Record<string, unknown> {
+  const body: Record<string, unknown> = { prompt };
+  if (opts.size) body.size = opts.size;
+  if (opts.quality) body.quality = opts.quality;
+  if (opts.format) body.format = opts.format;
+  if (opts.savePath) body.savePath = opts.savePath;
+  if (opts.background) body.background = opts.background;
+  if (opts.moderation) body.moderation = opts.moderation;
+  // Allow callers to pin organizationId when running with a wildcard
+  // key (rare; org-bound keys take precedence on the gateway side).
+  const orgId = process.env.DENCH_ORG_ID?.trim();
+  if (orgId) body.organizationId = orgId;
+  const runId = process.env.DENCH_RUN_ID?.trim();
+  if (runId) body.runId = runId;
+  return body;
+}
+
+async function runGenerateSubcommand(ctx: ImageCliContext): Promise<void> {
+  const opts = parseCommonOpts(ctx.args);
+  // Consume optional --print-b64 BEFORE we collapse the remainder into
+  // the prompt, otherwise it would be glued onto the prompt string.
+  const printB64 = hasFlag(ctx.args, "--print-b64");
+  const promptParts = ctx.args.slice();
+  ctx.args.length = 0;
+  const prompt = promptParts.join(" ").trim();
+  if (!prompt) {
+    throw new ImageCliError(
+      'Usage: dench image generate "<prompt>" [--size 1024x1024] [--quality auto|low|medium|high] [--format png|jpeg|webp] [--save-path /workspace/...] [--output <local>] [--no-write] [--json]',
+    );
+  }
+  const body = buildGenerationBody(prompt, opts);
+  const result = await callGateway("/v1/images/generations", body);
+  if (!result.b64_json) {
+    throw new ImageCliError("Gateway response did not include image bytes.");
+  }
+
+  let localPath: string | null = null;
+  if (!opts.noWrite) {
+    const target = resolveOutputPath(
+      opts.output,
+      result.path ?? `/image-generations/output.${result.format ?? "png"}`,
+    );
+    const written = await writeBytesToDisk(target, result.b64_json);
+    localPath = written.path;
+  }
+
+  out(
+    ctx,
+    {
+      ...result,
+      ok: true,
+      localPath,
+      // Strip the bytes from JSON output by default — they're already
+      // on disk + Convex. Re-include with --print-b64.
+      b64_json: ctx.jsonOutput && printB64 ? result.b64_json : undefined,
+    },
+    formatGenerationResult(result, localPath),
+  );
+}
+
+async function runEditSubcommand(ctx: ImageCliContext): Promise<void> {
+  const opts = parseCommonOpts(ctx.args);
+  const printB64 = hasFlag(ctx.args, "--print-b64");
+  const inputs: string[] = [];
+  // Repeatable --input flag.
+  while (true) {
+    const input = getFlag(ctx.args, "--input") ?? getFlag(ctx.args, "-i");
+    if (!input) break;
+    inputs.push(input);
+  }
+  const mask = getFlag(ctx.args, "--mask");
+  const promptParts = ctx.args.slice();
+  ctx.args.length = 0;
+  const prompt = promptParts.join(" ").trim();
+  if (!prompt) {
+    throw new ImageCliError(
+      'Usage: dench image edit "<prompt>" --input <path> [--input <path> ...] [--mask <path>] [--size ...] [--quality ...] [--format ...] [--save-path ...] [--output ...] [--no-write] [--json]',
+    );
+  }
+  if (inputs.length === 0) {
+    throw new ImageCliError(
+      "At least one --input <path> is required for image edits.",
+    );
+  }
+  if (inputs.length > 8) {
+    throw new ImageCliError(
+      `Too many --input paths (${inputs.length}); the gateway accepts at most 8.`,
+    );
+  }
+  const inputBase64 = await Promise.all(inputs.map((p) => readBase64FromPath(p)));
+  const maskBase64 = mask ? await readBase64FromPath(mask) : undefined;
+  const body = {
+    ...buildGenerationBody(prompt, opts),
+    input_images_base64: inputBase64,
+    ...(maskBase64 ? { mask_base64: maskBase64 } : {}),
+  };
+  const result = await callGateway("/v1/images/edits", body);
+  if (!result.b64_json) {
+    throw new ImageCliError("Gateway response did not include image bytes.");
+  }
+
+  let localPath: string | null = null;
+  if (!opts.noWrite) {
+    const target = resolveOutputPath(
+      opts.output,
+      result.path ?? `/image-generations/edit.${result.format ?? "png"}`,
+    );
+    const written = await writeBytesToDisk(target, result.b64_json);
+    localPath = written.path;
+  }
+
+  out(
+    ctx,
+    {
+      ...result,
+      ok: true,
+      localPath,
+      b64_json: ctx.jsonOutput && printB64 ? result.b64_json : undefined,
+    },
+    formatGenerationResult(result, localPath),
+  );
+}
+
+function imageHelp(): void {
+  console.log(`Usage: dench image <subcommand>
+
+Generate or edit images via the Dench Cloud Gateway (gpt-image-2). Auths
+with DENCH_API_KEY (baked into every sandbox automatically). Each call
+writes the bytes to Convex Storage (workspace tree updates immediately)
+and, when running inside a sandbox, also writes the decoded bytes to
+local disk so subsequent bash commands see the file without waiting on
+the daemon's downward sync.
+
+Generate from a text prompt:
+  dench image generate "<prompt>" [--size 1024x1024] [--quality auto|low|medium|high]
+                                  [--format png|jpeg|webp]
+                                  [--save-path /workspace/path/file.png]
+                                  [--output <local file>] [--no-write] [--json]
+
+Edit / remix one or more existing images (image-to-image):
+  dench image edit "<prompt>" --input <path> [--input <path> ...] [--mask <path>]
+                              [--size ...] [--quality ...] [--format ...]
+                              [--save-path ...] [--output ...] [--no-write] [--json]
+
+Environment variables:
+  DENCH_API_KEY        Required. Bearer token sent to the gateway.
+  DENCH_GATEWAY_URL    Override the gateway base URL.
+  GATEWAY_URL          Same, used when DENCH_GATEWAY_URL is unset.
+  DENCH_HOST           If it points at localhost, defaults to
+                       http://localhost:8787 instead of production.
+  DENCH_VOLUME_PATH    Sandbox volume mount root (default: /workspace).
+  DENCH_ORG_ID         Forwarded so wildcard keys can target an org.
+  DENCH_RUN_ID         Forwarded for telemetry correlation.
+
+Exit codes: 0 success, non-zero on gateway / network errors.`);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ────────────────────────────────────────────────────────────────────────────
+
+export async function runImageCommand(ctx: ImageCliContext): Promise<void> {
+  const sub = ctx.args[0];
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    imageHelp();
+    return;
+  }
+  if (sub === "generate" || sub === "gen" || sub === "g") {
+    ctx.args.shift();
+    await runGenerateSubcommand(ctx);
+    return;
+  }
+  if (sub === "edit" || sub === "e") {
+    ctx.args.shift();
+    await runEditSubcommand(ctx);
+    return;
+  }
+  throw new ImageCliError(
+    `Unknown subcommand: ${sub}. Run \`dench image help\` for usage.`,
+  );
+}

package/lib/cli-args.ts

@@ -7,9 +7,20 @@
  *   - shift(args, expected): pop the next positional arg or throw.
  *   - getFlag(args, name): pull the value following `--name` and remove
  *     both tokens from args. Returns undefined if the flag is missing.
+ *   - getFlagWithAliases(args, primary, aliases): like getFlag but
+ *     accepts multiple flag names; the first one found wins. Used to
+ *     accept e.g. `--data` and `--fields` interchangeably so a confused
+ *     caller doesn't silently produce blank rows.
  *   - hasFlag(args, name): true iff `--name` appears (and removes it).
  *   - parseJson(value): JSON.parse with a CliError-style throw on
  *     failure.
+ *   - assertNoUnknownFlags(args, command): after all known flags have
+ *     been drained via getFlag/hasFlag, throw if any token starting
+ *     with `--` is left in args. Catches typos like `--fields` when
+ *     the subcommand only knows `--data` — the previous behaviour
+ *     silently dropped the typo and produced empty writes (see
+ *     incident in chat y5710jn4313ht2p6fwmw0m0mjn8636ya where 15 blank
+ *     CRM rows were created before the agent realized).
  *
  * NOTE: each module wraps its own *CliError class so we don't import
  * across cli/ entry points; this module's errors throw plain Error and
@@ -24,10 +35,7 @@ export function shift(args: string[], expected: string): string {
   return value;
 }
 
-export function getFlag(
-  args: string[],
-  name: string,
-): string | undefined {
+export function getFlag(args: string[], name: string): string | undefined {
   const idx = args.indexOf(name);
   if (idx === -1) return undefined;
   const value = args[idx + 1];
@@ -35,6 +43,36 @@ export function getFlag(
   return value;
 }
 
+export function getFlagWithAliases(
+  args: string[],
+  primary: string,
+  aliases: readonly string[],
+): string | undefined {
+  // Try each name in order; the first one found is consumed and returned.
+  // Aliases (and duplicate occurrences of the picked name) are still
+  // removed from args so unknown-flag detection downstream doesn't flag
+  // them as typos and so the caller can't get bitten by silent
+  // first-wins drift across multiple invocations.
+  const all = [primary, ...aliases];
+  let chosen: string | undefined;
+  for (const name of all) {
+    const value = getFlag(args, name);
+    if (value !== undefined) {
+      chosen = value;
+      break;
+    }
+  }
+  // Drain any remaining occurrences of every alias (including the
+  // primary). With a single getFlag pass per name we'd leave a
+  // duplicate `--fields` behind to look like an unknown flag.
+  for (const name of all) {
+    while (getFlag(args, name) !== undefined) {
+      // Intentional empty body: drain duplicates.
+    }
+  }
+  return chosen;
+}
+
 export function hasFlag(args: string[], name: string): boolean {
   const idx = args.indexOf(name);
   if (idx === -1) return false;
@@ -50,3 +88,22 @@ export function parseJson(value: string | undefined): unknown {
     throw new CliArgError(`Invalid JSON: ${value}`);
   }
 }
+
+export function assertNoUnknownFlags(
+  args: readonly string[],
+  command: string,
+): void {
+  // After every getFlag/hasFlag/getFlagWithAliases call has had a chance
+  // to drain known flags, any remaining token that starts with `--` is
+  // unknown. We surface the first one with a hint so the caller can fix
+  // the typo. Don't include positional `--` literals; raw `--` (used by
+  // some shells to terminate option parsing) is allowed.
+  for (const token of args) {
+    if (token === "--") continue;
+    if (token.startsWith("--")) {
+      throw new CliArgError(
+        `Unknown flag for ${command}: ${token}. Run \`dench ${command.split(" ")[0]} help\` for the full flag list.`,
+      );
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {
@@ -18,6 +18,9 @@
     "chat.ts",
     "chat-spawn.ts",
     "crm.ts",
+    "cron.ts",
+    "search.ts",
+    "image.ts",
     "agentKind.ts",
     "host.ts",
     "openUrl.ts",