groundmail-cli 0.46.0 → 0.47.0

package/README.md

@@ -1,6 +1,6 @@
 # groundmail-cli
 
-Command-line client for [Groundmail](https://groundmail.dev) — send transactional email and manage domains, webhooks, templates, and more from the terminal.
+Command-line client for [Groundmail](https://groundmail.dev) — send email and manage domains, webhooks, templates, and more from the terminal.
 
 ```bash
 npm install -g groundmail-cli

package/dist/cli.js

@@ -2090,10 +2090,11 @@ async function runListKeysCommandWithClient(args, env = process.env) {
 }
 
 // package.json
-var version = "0.46.0";
+var version = "0.47.0";
 
 // src/help.ts
 var USAGE_LINES = [
+  '  groundmail cli search "<what you want to do>" [--limit 5] [--json]   find the right command by describing the task; works offline, no sign-in',
   "  groundmail login [--scope <scopes>] [--workspace <name>]   sign in through the browser (OAuth; no key to copy)",
   "  groundmail logout [--workspace <name>|--all]   revokes the sign-in server-side",
   "  groundmail whoami",
@@ -2124,7 +2125,7 @@ var USAGE_LINES = [
   "  groundmail mailboxes create [--local-part signup-bot] [--domain agents.example.com] [--display-name \u2026] [--external-id \u2026] [--tenant <tenant>] [--retention-days 7] [--spam-threshold 5] [--metadata JSON] [--forward-from <mailbox>] [--json]   a real address your agent reads and sends from; no --domain: a hosted address, which can only reply; --forward-from: a hosted mailbox this one replaces",
   "  groundmail mailboxes list [--tenant <tenant>] [--limit 25] [--cursor \u2026] [--json]",
   "  groundmail mailboxes get <mailbox> [--json]",
-  "  groundmail mailboxes update <mailbox> [--send-as support@example.com] [--allowed-senders you@example.com,example.com] [--blocked-senders spam.example]   none clears one",
+  "  groundmail mailboxes update <mailbox> [--send-as support@example.com] [--allowed-senders you@example.com,example.com] [--blocked-senders spam.example]   choose who can reach the mailbox and what it sends as; none clears a setting",
   "  groundmail mailboxes delete <mailbox> --yes   the mailbox and all its mail; a hosted address is never given out again",
   "  groundmail mailboxes forward <mailbox> --to <new mailbox> --yes   move a hosted address to a mailbox on your own domain, for 30 days; it can't send meanwhile",
   "  groundmail mailboxes threads <mailbox> [--label \u2026] [--participant \u2026] [--unread] [--archived] [--since <iso>] [--include-held] [--limit 25] [--cursor \u2026] [--json]",
@@ -2256,8 +2257,9 @@ var ALIASES = {
 function words(line) {
   return line.trim().split(/\s+/);
 }
+var SEARCH_TIP = 'Not sure which command? Run: groundmail cli search "what you want to do"';
 function fullUsage() {
-  return ["Usage:", ...USAGE_LINES, "", ...FOOTER_LINES].join("\n");
+  return [SEARCH_TIP, "", "Usage:", ...USAGE_LINES, "", ...FOOTER_LINES].join("\n");
 }
 function unknownCommandMessage(argv) {
   const typed = argv.filter((arg) => !arg.startsWith("-")).slice(0, 2).join(" ");
@@ -2653,19 +2655,19 @@ async function accessTokenFor(workspace, apiUrl, options = {}) {
   for (let attempt = 0; attempt < 2; attempt++) {
     const response = await refresh(apiUrl, refreshToken, narrowed ? options.scope.trim() : null, env);
     if (response.ok && isTokenSet(response.body)) {
-      const tokens = response.body;
-      const stored = storeRefreshToken({ apiUrl, workspaceId: workspace.id, refreshToken: tokens.refresh_token, scope: oauth.scope }, env);
+      const tokens2 = response.body;
+      const stored = storeRefreshToken({ apiUrl, workspaceId: workspace.id, refreshToken: tokens2.refresh_token, scope: oauth.scope }, env);
       updateConfig((config) => {
         const current = config.workspaces?.[workspace.id];
         if (!current) return config;
         const next = {
           ...stored,
           scope: oauth.scope,
-          ...narrowed ? { accessToken: current.oauth?.accessToken, accessTokenExpiresAt: current.oauth?.accessTokenExpiresAt } : { accessToken: tokens.access_token, accessTokenExpiresAt: now() + tokens.expires_in * 1e3 }
+          ...narrowed ? { accessToken: current.oauth?.accessToken, accessTokenExpiresAt: current.oauth?.accessTokenExpiresAt } : { accessToken: tokens2.access_token, accessTokenExpiresAt: now() + tokens2.expires_in * 1e3 }
         };
         return { ...config, workspaces: { ...config.workspaces, [workspace.id]: { ...current, oauth: next } } };
       }, env);
-      return { ok: true, token: tokens.access_token, scope: tokens.scope };
+      return { ok: true, token: tokens2.access_token, scope: tokens2.scope };
     }
     const code = oauthErrorCode(response);
     if (code === "invalid_grant" && attempt === 0) {
@@ -2816,14 +2818,14 @@ var CLI_SCOPES = [
   "mailboxes:send"
 ];
 function parseScopeFlag(value) {
-  const tokens = String(value ?? "").split(/[\s,]+/).map((token) => token.trim()).filter(Boolean);
-  if (!tokens.length) return { ok: true, scope: "full" };
-  const unknown = tokens.filter((token) => !CLI_SCOPES.includes(token));
+  const tokens2 = String(value ?? "").split(/[\s,]+/).map((token) => token.trim()).filter(Boolean);
+  if (!tokens2.length) return { ok: true, scope: "full" };
+  const unknown = tokens2.filter((token) => !CLI_SCOPES.includes(token));
   if (unknown.length) {
     return { ok: false, error: `Unknown scope: ${unknown.join(", ")}. Scopes: ${CLI_SCOPES.join(", ")}.` };
   }
-  if (tokens.includes("full")) return { ok: true, scope: "full" };
-  return { ok: true, scope: CLI_SCOPES.filter((scope) => tokens.includes(scope)).join(" ") };
+  if (tokens2.includes("full")) return { ok: true, scope: "full" };
+  return { ok: true, scope: CLI_SCOPES.filter((scope) => tokens2.includes(scope)).join(" ") };
 }
 function openInBrowser(url) {
   const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
@@ -2987,12 +2989,12 @@ ${next}`);
     throw error;
   }
 }
-async function finishLogin(tokens, login, { io, env, json, now }) {
+async function finishLogin(tokens2, login, { io, env, json, now }) {
   const brand = cliBrand(env);
-  const workspace = tokens.workspace ?? {};
-  const user = tokens.user ?? {};
+  const workspace = tokens2.workspace ?? {};
+  const user = tokens2.user ?? {};
   const id = typeof workspace.id === "string" && workspace.id ? workspace.id : "default";
-  const scope = typeof tokens.scope === "string" && tokens.scope ? tokens.scope : login.scope ?? "full";
+  const scope = typeof tokens2.scope === "string" && tokens2.scope ? tokens2.scope : login.scope ?? "full";
   const previous = loadConfig(env).workspaces?.[id];
   let replacedKey = false;
   if (previous?.apiKey) {
@@ -3003,11 +3005,11 @@ async function finishLogin(tokens, login, { io, env, json, now }) {
     const oldRefresh = readRefreshToken(previous, login.apiUrl, env);
     if (oldRefresh) await revokeRefreshToken(login.apiUrl, oldRefresh, env).catch(() => null);
   }
-  const stored = storeRefreshToken({ apiUrl: login.apiUrl, workspaceId: id, refreshToken: tokens.refresh_token, scope }, env);
+  const stored = storeRefreshToken({ apiUrl: login.apiUrl, workspaceId: id, refreshToken: tokens2.refresh_token, scope }, env);
   const saved = {
     id,
     name: typeof workspace.name === "string" && workspace.name ? workspace.name : "Workspace",
-    oauth: { ...stored, accessToken: tokens.access_token, accessTokenExpiresAt: now() + tokens.expires_in * 1e3 },
+    oauth: { ...stored, accessToken: tokens2.access_token, accessTokenExpiresAt: now() + tokens2.expires_in * 1e3 },
     ...login.apiUrl !== defaultApiUrl(env) ? { apiUrl: login.apiUrl } : {},
     email: typeof user.email === "string" ? user.email : null,
     savedAt: new Date(now()).toISOString()
@@ -3021,12 +3023,12 @@ async function finishLogin(tokens, login, { io, env, json, now }) {
   const envKey = envApiKey(env);
   const envNote = envKey ? `${sourceLabel("env", env)} is set in this environment and is used instead of this sign-in until you unset it.` : null;
   const where = storeLabel(saved.oauth, configPath(env), env);
-  const next = await nextStep(login.apiUrl, tokens.access_token, scope, env);
+  const next = await nextStep(login.apiUrl, tokens2.access_token, scope, env);
   if (json) {
     printJson(io, {
       status: "signed_in",
       next,
-      user: tokens.user ?? null,
+      user: tokens2.user ?? null,
       workspace: { id: saved.id, name: saved.name },
       scope,
       refresh_token_store: stored.store,
@@ -5532,6 +5534,195 @@ async function runMailboxesCommand(subcommand, argv, env = process.env) {
   }
 }
 
+// src/commands/cli/search.ts
+var USAGE4 = 'Usage: groundmail cli search "<what you want to do>" [--limit 5] [--json]';
+var DEFAULT_LIMIT = 5;
+var MAX_LIMIT = 20;
+var USAGE_WIDTH = 80;
+var WEIGHT = { name: 5, keywords: 4, about: 2, flags: 1 };
+var SYNONYM_SHARE = 0.6;
+var STOP_WORDS = new Set(
+  "a about an and are as at be by can do for from get give how i in into is it its me my need of on or our out please show so that the them then this to up us want we what when where which who why will with you your".split(
+    " "
+  )
+);
+var SYNONYMS = {
+  inbox: ["mailbox"],
+  address: ["mailbox"],
+  bot: ["agent"],
+  agent: ["mailbox"],
+  mail: ["email"],
+  message: ["email"],
+  sender: ["senders"],
+  customer: ["tenant"],
+  client: ["tenant"],
+  company: ["tenant"],
+  workspace: ["workspaces"],
+  token: ["key"],
+  secret: ["key"],
+  make: ["create"],
+  add: ["create"],
+  change: ["update", "set"],
+  edit: ["update"],
+  new: ["create"],
+  setup: ["create", "apply"],
+  remove: ["delete"],
+  stop: ["pause", "cancel", "block"],
+  block: ["suppression"],
+  ban: ["block"],
+  unsubscribe: ["suppression"],
+  dns: ["apply", "domain"],
+  otp: ["code"],
+  magic: ["code"],
+  bounce: ["suppression", "get"],
+  newsletter: ["broadcast"],
+  logo: ["brand"],
+  color: ["brand"],
+  workflow: ["automation"],
+  sequence: ["automation"],
+  drip: ["automation"],
+  callback: ["webhook"],
+  trigger: ["event"],
+  check: ["validate", "verify"],
+  switch: ["migrate"],
+  move: ["migrate", "forward"],
+  import: ["migrate"]
+};
+var KEYWORDS = {
+  "mailboxes create": "inbox address agent own email",
+  "mailboxes update": "block allow sender stop reach who write send-as agent someone",
+  "mailboxes read": "inbox message check mail",
+  "mailboxes wait": "code verification sign-up magic link next",
+  "mailboxes reply": "answer respond thread message email",
+  "mailboxes send": "agent email first",
+  "emails send": "transactional test send",
+  "emails get": "status delivered bounce why happened",
+  "emails cancel": "scheduled unsend",
+  "test-inbox wait": "code verification sign-up test catch",
+  "test-inbox address": "test sign-up throwaway disposable",
+  "domains add": "sending own domain",
+  "domains apply": "dns records cloudflare vercel godaddy automatically",
+  "domains verify": "dns check records",
+  "suppressions add": "unsubscribe do-not-email block stop emailing someone address",
+  validate: "email address deliverable real check",
+  "webhooks create": "notify events wake receive",
+  "webhooks deliveries": "failed retry debug",
+  "keys create": "api token secret",
+  login: "sign-in authenticate account browser"
+};
+var NO_ACCOUNT_NEEDED = /* @__PURE__ */ new Set(["login", "logout", "whoami", "cli search", "validate"]);
+function stem(word) {
+  if (word.length > 5 && word.endsWith("ing")) return word.slice(0, -3);
+  if (word.length > 4 && word.endsWith("ies")) return `${word.slice(0, -3)}y`;
+  if (word.length > 4 && word.endsWith("ed")) return word.slice(0, -2);
+  if (word.length > 3 && word.endsWith("s") && !word.endsWith("ss")) return word.slice(0, -1);
+  return word;
+}
+function tokens(text) {
+  return (text.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((word) => !STOP_WORDS.has(word)).map(stem);
+}
+function queryTokens(task) {
+  return tokens(
+    task.toLowerCase().replace(/\b(log|sign)[ -]?(in|on)\b/g, "login").replace(/\bset[ -]up\b/g, "setup")
+  );
+}
+function parseLine(line) {
+  const [usagePart = "", ...rest] = line.trim().split(/\s{3,}/);
+  const parts2 = usagePart.split(/\s+/).slice(1);
+  const nameParts = [];
+  for (const part of parts2) {
+    if (!/^[a-z][a-z-]*$/.test(part) || nameParts.length === 3) break;
+    nameParts.push(part);
+  }
+  const name = nameParts.join(" ");
+  const summary = rest.join(" ").trim();
+  const needsAccount = !(name.startsWith("mailboxes ") || NO_ACCOUNT_NEEDED.has(name));
+  return {
+    command: `groundmail ${name}`,
+    summary,
+    usage: usagePart,
+    needs_account: needsAccount,
+    name: tokens(name.replace(/-/g, " ")),
+    keywords: tokens(KEYWORDS[name] ?? ""),
+    about: tokens(summary),
+    flags: tokens(parts2.slice(nameParts.length).join(" "))
+  };
+}
+function matches(term, word) {
+  if (term === word) return true;
+  return term.length >= 5 && word.length >= 5 && (word.startsWith(term) || term.startsWith(word));
+}
+function fieldScore(entry, term) {
+  let best = 0;
+  for (const field of ["name", "keywords", "about", "flags"]) {
+    if (entry[field].some((word) => matches(term, word))) best = Math.max(best, WEIGHT[field]);
+  }
+  return best;
+}
+function searchCommands(task, limit = DEFAULT_LIMIT) {
+  const terms = [...new Set(queryTokens(task))];
+  if (!terms.length) return [];
+  const entries = USAGE_LINES.map(parseLine);
+  const rarity = (term) => {
+    const hits = entries.filter((entry) => fieldScore(entry, term) > 0).length;
+    return hits ? 1 + Math.log(entries.length / hits) : 0;
+  };
+  const scored = entries.map((entry) => {
+    let score = 0;
+    let matched = 0;
+    for (const term of terms) {
+      const direct = fieldScore(entry, term) * rarity(term);
+      const viaSynonym = Math.max(
+        0,
+        ...(SYNONYMS[term] ?? []).map((word) => fieldScore(entry, stem(word)) * rarity(stem(word)) * SYNONYM_SHARE)
+      );
+      const best = Math.max(direct, viaSynonym);
+      if (best > 0) matched += 1;
+      score += best;
+    }
+    return { entry, score: score * (matched / terms.length) };
+  });
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  for (const { entry, score } of scored.sort((a, b) => b.score - a.score || a.entry.command.length - b.entry.command.length)) {
+    if (score <= 0 || results.length >= limit) break;
+    if (seen.has(entry.command)) continue;
+    seen.add(entry.command);
+    const { command, summary, usage, needs_account } = entry;
+    results.push({ command, summary, usage, needs_account });
+  }
+  return results;
+}
+function textOutput(found) {
+  const lines = found.map((match) => {
+    const usage = match.usage.length > USAGE_WIDTH ? `${match.usage.slice(0, USAGE_WIDTH)}\u2026` : match.usage;
+    const note = match.needs_account ? " (needs an account key)" : "";
+    return match.summary ? `${usage}${note}
+  ${match.summary}` : `${usage}${note}`;
+  });
+  return [...lines, "", "Add --help to any of these for its flags."].join("\n");
+}
+async function runCliCommand(subcommand, argv) {
+  if (subcommand !== "search") return { exitCode: 1, error: USAGE4 };
+  const parsed = parseArgs(argv, { values: ["--limit"], booleans: ["--json"] });
+  if (!parsed.ok) return { exitCode: 1, error: `${parsed.error}
+${USAGE4}` };
+  const task = parsed.args.positionals.join(" ").trim();
+  if (!task) return { exitCode: 1, error: USAGE4 };
+  const rawLimit = parsed.args.values["--limit"];
+  const limit = rawLimit === void 0 ? DEFAULT_LIMIT : Number(rawLimit);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    return { exitCode: 1, error: `--limit must be a whole number from 1 to ${MAX_LIMIT}.` };
+  }
+  const found = searchCommands(task, limit);
+  if (parsed.args.booleans["--json"]) {
+    console.log(JSON.stringify({ query: task, matches: found }, null, 2));
+    return { exitCode: 0 };
+  }
+  console.log(found.length ? textOutput(found) : "No matching command. Try other words, or run groundmail --help.");
+  return { exitCode: 0 };
+}
+
 // src/update-check.ts
 import { spawn as spawn2 } from "child_process";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
@@ -5631,6 +5822,7 @@ async function main() {
     console.log(meta.text);
     process.exit(0);
   }
+  if (command === "cli") await finish(await runCliCommand(subcommand, args.slice(1)));
   if (command === "login") await finish(await runLoginCommand(args));
   if (command === "logout") await finish(await runLogoutCommand(args));
   if (command === "whoami") await finish(await runWhoamiCommand(args));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "groundmail-cli",
-  "version": "0.46.0",
-  "description": "Groundmail CLI — send transactional email from the terminal",
+  "version": "0.47.0",
+  "description": "Groundmail CLI: send email and manage mailboxes from the terminal",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "groundmail": "0.48.0"
+    "groundmail": "0.48.1"
   },
   "devDependencies": {
     "tsup": "^8.5.0",