@dench.com/cli 0.3.4 → 0.3.6

package/search.ts

@@ -0,0 +1,420 @@
+/**
+ * `dench search` — live web access through the Dench Cloud Gateway.
+ *
+ * The gateway exposes Exa Search at three routes; we mirror them as
+ * three subcommands and authenticate with the `DENCH_API_KEY` baked
+ * into every sandbox at create time. Unlike most other CLI surfaces
+ * this one bypasses Convex entirely — it speaks straight HTTP to the
+ * gateway, so it works in any environment that has the env var
+ * (sandboxes, CI, local dev with `DENCH_API_KEY` exported manually).
+ *
+ * Subcommands:
+ *   search "<query>"       [--num-results N] [--type auto|fast|deep|deep-reasoning|neural]
+ *                          [--category news|company|people|...]
+ *                          [--include-domains a.com,b.com] [--exclude-domains c.com]
+ *                          [--max-chars 800] [--json]
+ *   search contents <url> [<url>...] [--max-chars 4000] [--summary "..."] [--json]
+ *   search answer "<query>" [--json]
+ */
+
+import {
+  CliArgError,
+  getFlag,
+  hasFlag,
+  shift as shiftRaw,
+} from "./lib/cli-args";
+
+type SearchCliContext = {
+  args: string[];
+  jsonOutput: boolean;
+};
+
+class SearchCliError extends Error {}
+
+function shift(args: string[], expected: string): string {
+  try {
+    return shiftRaw(args, expected);
+  } catch (error) {
+    if (error instanceof CliArgError) {
+      throw new SearchCliError(error.message);
+    }
+    throw error;
+  }
+}
+
+function parsePositiveInt(name: string, raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new SearchCliError(`Invalid ${name} value: ${raw}`);
+  }
+  return Math.floor(parsed);
+}
+
+function splitCsv(raw: string | undefined): string[] | undefined {
+  if (raw === undefined) return undefined;
+  const parts = raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  return parts.length > 0 ? parts : undefined;
+}
+
+const ALLOWED_TYPES = new Set([
+  "auto",
+  "neural",
+  "fast",
+  "deep",
+  "deep-reasoning",
+  "instant",
+]);
+
+const ALLOWED_CATEGORIES = new Set([
+  "company",
+  "research paper",
+  "news",
+  "personal site",
+  "financial report",
+  "people",
+]);
+
+function resolveGatewayBaseUrl(): string {
+  const explicit =
+    process.env.DENCH_GATEWAY_URL?.trim() || process.env.GATEWAY_URL?.trim();
+  if (explicit) return explicit.replace(/\/+$/, "");
+  // Local dev: the gateway listens on :8787 (matches gateway/src/index.ts
+  // and the dev-server skill). Anything that smells like localhost in
+  // DENCH_HOST routes to the local gateway too so `dench --host
+  // http://localhost:3000 search ...` does the right thing.
+  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 SearchCliError(
+      "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;
+}
+
+async function callGateway(
+  path: "/v1/search" | "/v1/search/contents" | "/v1/search/answer",
+  body: Record<string, unknown>,
+): Promise<unknown> {
+  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 SearchCliError(
+      `Gateway ${path} returned ${response.status}: ${truncated || response.statusText}`,
+    );
+  }
+  return response.json();
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Output formatting
+// ────────────────────────────────────────────────────────────────────────────
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function trimSnippet(text: string, maxChars: number): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= maxChars) return collapsed;
+  return `${collapsed.slice(0, maxChars - 1)}…`;
+}
+
+function formatHostname(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return url;
+  }
+}
+
+function formatSearchResults(payload: unknown, limit?: number): string {
+  const root = asObject(payload);
+  if (!root) return "(no results)";
+  const results = asArray(root.results);
+  const lines: string[] = [];
+  const auto = asString(root.autopromptString);
+  if (auto) {
+    lines.push(`Auto-prompt: ${auto}`);
+    lines.push("");
+  }
+  if (results.length === 0) {
+    lines.push("(no results)");
+    return lines.join("\n");
+  }
+  const cap = limit !== undefined ? Math.min(results.length, limit) : results.length;
+  for (let i = 0; i < cap; i++) {
+    const result = asObject(results[i]);
+    if (!result) continue;
+    const title = asString(result.title) ?? "(untitled)";
+    const url = asString(result.url) ?? "";
+    const host = formatHostname(url);
+    const published = asString(result.publishedDate);
+    const author = asString(result.author);
+    const meta = [host, published, author].filter(Boolean).join("  ·  ");
+    const snippet =
+      asString(result.text) ??
+      (Array.isArray(result.highlights)
+        ? result.highlights.filter((h): h is string => typeof h === "string").join(" ")
+        : undefined) ??
+      asString(result.summary);
+    lines.push(`${i + 1}. ${title}`);
+    if (url) lines.push(`   ${url}`);
+    if (meta) lines.push(`   ${meta}`);
+    if (snippet) lines.push(`   ${trimSnippet(snippet, 240)}`);
+    lines.push("");
+  }
+  const cost = asNumber(asObject(root.costDollars)?.total);
+  if (cost !== undefined) {
+    lines.push(`Cost (USD): $${cost.toFixed(4)}`);
+  }
+  return lines.join("\n").trimEnd();
+}
+
+function formatContentsResults(payload: unknown): string {
+  const root = asObject(payload);
+  if (!root) return "(no contents)";
+  const results = asArray(root.results);
+  const lines: string[] = [];
+  if (results.length === 0) {
+    return "(no contents)";
+  }
+  for (let i = 0; i < results.length; i++) {
+    const result = asObject(results[i]);
+    if (!result) continue;
+    const title = asString(result.title) ?? "(untitled)";
+    const url = asString(result.url) ?? "";
+    lines.push(`${i + 1}. ${title}`);
+    if (url) lines.push(`   ${url}`);
+    const summary = asString(result.summary);
+    if (summary) {
+      lines.push("   Summary:");
+      lines.push(...indent(trimSnippet(summary, 1200), "     "));
+    }
+    const text = asString(result.text);
+    if (text) {
+      lines.push("   Content:");
+      lines.push(...indent(trimSnippet(text, 2000), "     "));
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+function formatAnswer(payload: unknown): string {
+  const root = asObject(payload);
+  if (!root) return "(no answer)";
+  const answer = asString(root.answer) ?? "";
+  const citations = asArray(root.citations);
+  const lines: string[] = [];
+  if (answer) {
+    lines.push(answer.trim());
+    lines.push("");
+  }
+  if (citations.length > 0) {
+    lines.push("Citations:");
+    for (let i = 0; i < citations.length; i++) {
+      const citation = asObject(citations[i]);
+      if (!citation) continue;
+      const title = asString(citation.title) ?? "(untitled)";
+      const url = asString(citation.url) ?? "";
+      lines.push(`  ${i + 1}. ${title}`);
+      if (url) lines.push(`     ${url}`);
+    }
+  }
+  return lines.join("\n").trimEnd() || "(no answer)";
+}
+
+function indent(text: string, prefix: string): string[] {
+  return text.split("\n").map((line) => `${prefix}${line}`);
+}
+
+function out(ctx: SearchCliContext, payload: unknown, formatted: string): void {
+  if (ctx.jsonOutput) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(formatted);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Subcommands
+// ────────────────────────────────────────────────────────────────────────────
+
+async function runSearchSubcommand(ctx: SearchCliContext): Promise<void> {
+  const numResults = parsePositiveInt("--num-results", getFlag(ctx.args, "--num-results"));
+  const type = getFlag(ctx.args, "--type");
+  if (type !== undefined && !ALLOWED_TYPES.has(type)) {
+    throw new SearchCliError(
+      `Invalid --type: ${type}. Allowed: ${[...ALLOWED_TYPES].join(", ")}`,
+    );
+  }
+  const category = getFlag(ctx.args, "--category");
+  if (category !== undefined && !ALLOWED_CATEGORIES.has(category)) {
+    throw new SearchCliError(
+      `Invalid --category: ${category}. Allowed: ${[...ALLOWED_CATEGORIES].join(", ")}`,
+    );
+  }
+  const includeDomains = splitCsv(getFlag(ctx.args, "--include-domains"));
+  const excludeDomains = splitCsv(getFlag(ctx.args, "--exclude-domains"));
+  const maxChars =
+    parsePositiveInt("--max-chars", getFlag(ctx.args, "--max-chars")) ?? 800;
+  const queryParts = ctx.args.slice();
+  ctx.args.length = 0;
+  const query = queryParts.join(" ").trim();
+  if (!query) {
+    throw new SearchCliError(
+      'Usage: dench search "<query>" [--num-results N] [--type auto|fast|deep|deep-reasoning] [--category ...] [--include-domains a.com,b.com] [--exclude-domains c.com] [--max-chars 800] [--json]',
+    );
+  }
+  const body: Record<string, unknown> = {
+    query,
+    numResults: numResults ?? 10,
+    type: type ?? "auto",
+    contents: {
+      text: { maxCharacters: maxChars },
+      highlights: { maxCharacters: 200 },
+    },
+  };
+  if (category) body.category = category;
+  if (includeDomains) body.includeDomains = includeDomains;
+  if (excludeDomains) body.excludeDomains = excludeDomains;
+  const payload = await callGateway("/v1/search", body);
+  out(ctx, payload, formatSearchResults(payload, numResults));
+}
+
+async function runContentsSubcommand(ctx: SearchCliContext): Promise<void> {
+  const maxChars = parsePositiveInt("--max-chars", getFlag(ctx.args, "--max-chars"));
+  const summary = getFlag(ctx.args, "--summary");
+  const urls = ctx.args.slice();
+  ctx.args.length = 0;
+  if (urls.length === 0) {
+    throw new SearchCliError(
+      'Usage: dench search contents <url> [<url>...] [--max-chars 4000] [--summary "..."] [--json]',
+    );
+  }
+  if (urls.length > 10) {
+    throw new SearchCliError(
+      `Too many URLs (${urls.length}); the gateway accepts at most 10 per call.`,
+    );
+  }
+  const body: Record<string, unknown> = {
+    urls,
+    text: maxChars ? { maxCharacters: maxChars } : true,
+    highlights: { maxCharacters: 200 },
+  };
+  if (summary) body.summary = { query: summary };
+  const payload = await callGateway("/v1/search/contents", body);
+  out(ctx, payload, formatContentsResults(payload));
+}
+
+async function runAnswerSubcommand(ctx: SearchCliContext): Promise<void> {
+  const queryParts = ctx.args.slice();
+  ctx.args.length = 0;
+  const query = queryParts.join(" ").trim();
+  if (!query) {
+    throw new SearchCliError(
+      'Usage: dench search answer "<query>" [--json]',
+    );
+  }
+  const payload = await callGateway("/v1/search/answer", {
+    query,
+    text: true,
+    stream: false,
+  });
+  out(ctx, payload, formatAnswer(payload));
+}
+
+function searchHelp(): void {
+  console.log(`Usage: dench search <subcommand>
+
+Live web access through the Dench Cloud Gateway (Exa Search). Auths
+with DENCH_API_KEY (baked into every sandbox automatically).
+
+Search the web (default subcommand):
+  dench search "<query>" [--num-results N] [--type auto|fast|deep|deep-reasoning|neural]
+                         [--category news|company|people|...]
+                         [--include-domains a.com,b.com] [--exclude-domains c.com]
+                         [--max-chars 800] [--json]
+
+Deep-read one or more URLs (Exa /search/contents):
+  dench search contents <url> [<url>...] [--max-chars 4000] [--summary "..."] [--json]
+
+One-shot synthesised answer with citations (Exa /search/answer):
+  dench search answer "<query>" [--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.
+
+Exit codes: 0 success, non-zero on gateway / network errors.`);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ────────────────────────────────────────────────────────────────────────────
+
+export async function runSearchCommand(ctx: SearchCliContext): Promise<void> {
+  const sub = ctx.args[0];
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    searchHelp();
+    return;
+  }
+  if (sub === "contents") {
+    ctx.args.shift();
+    await runContentsSubcommand(ctx);
+    return;
+  }
+  if (sub === "answer") {
+    ctx.args.shift();
+    await runAnswerSubcommand(ctx);
+    return;
+  }
+  // No explicit subcommand — treat the rest of the argv as the query.
+  await runSearchSubcommand(ctx);
+}