customer-map-codex-bridge 0.5.0 → 0.5.2

package/mail-action.mjs

@@ -1,363 +1,363 @@
-import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { delimiter, isAbsolute, join, resolve } from 'node:path';
-import process from 'node:process';
-
-const MIN_GOG_VERSION = [0, 11, 0];
-const MAX_GOG_BODY_BYTES = 100_000;
-const MAX_PROCESS_OUTPUT_CHARS = 1_000_000;
-const mailActionResults = new Map();
-const gogVersionCache = new Map();
-
-export async function executeCustomerMapMailAction(
-  value,
-  { signal, timeoutMs, gogCommand: requestedGogCommand = '' },
-) {
-  let action;
-  try {
-    action = normalizeMailAction(value);
-  } catch (error) {
-    return mailActionResult(value, 'failed', { error: formatError(error) });
-  }
-
-  const cacheKey = `${action.kind}:${action.actionId}`;
-  const cached = mailActionResults.get(cacheKey);
-  if (cached) {
-    if (cached.bodyHash !== action.bodyHash) {
-      return mailActionResult(action, 'failed', { error: 'Mail action id was reused with different content.' });
-    }
-    return cached.result;
-  }
-
-  let gogCommand;
-  let toolVersion;
-  try {
-    gogCommand = resolveGogCommand(requestedGogCommand);
-    toolVersion = await readGogVersion(gogCommand, signal);
-  } catch (error) {
-    return cacheMailResult(cacheKey, action, mailActionResult(action, 'failed', {
-      error: `gog is unavailable or unsupported: ${compactStatus(formatError(error))}`,
-    }));
-  }
-
-  const processResult = await runProcess(gogCommand, buildGogMailArgs(action), {
-    signal,
-    timeoutMs: Math.max(5_000, Math.min(Number(timeoutMs) - 2_000 || 90_000, 90_000)),
-  });
-  return cacheMailResult(cacheKey, action, classifyGogProcessResult(action, processResult, toolVersion));
-}
-
-export function normalizeMailAction(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error('Invalid Customer Map mail action.');
-  }
-  const source = value;
-  const kind = source.kind === 'sendEmail' || source.kind === 'saveDraft' ? source.kind : '';
-  const actionId = cleanText(source.actionId).toLowerCase();
-  const account = cleanText(source.account).toLowerCase();
-  const recipient = cleanText(source.recipient).toLowerCase();
-  const subject = cleanText(source.subject);
-  const plainTextBody = stringValue(source.plainTextBody);
-  const htmlBody = stringValue(source.htmlBody);
-  const bodyHash = cleanText(source.bodyHash).toLowerCase();
-  if (source.version !== 1 || !kind) throw new Error('Unsupported Customer Map mail action version or kind.');
-  if (!/^[0-9a-f]{32}$/.test(actionId)) throw new Error('Invalid Customer Map mail action id.');
-  if (!validEmail(account) || !validEmail(recipient)) throw new Error('Invalid Gmail account or recipient.');
-  if (!subject || /[\r\n]/.test(subject)) throw new Error('Invalid email subject.');
-  if (!plainTextBody && !htmlBody) throw new Error('Email body is empty.');
-  if (looksLikeBodyPath(plainTextBody) || looksLikeBodyPath(htmlBody)) {
-    throw new Error('Email body cannot be a filesystem or stdin path.');
-  }
-  if (Buffer.byteLength(plainTextBody, 'utf8') > MAX_GOG_BODY_BYTES || Buffer.byteLength(htmlBody, 'utf8') > MAX_GOG_BODY_BYTES) {
-    throw new Error('Email body is too large for safe gog argument execution.');
-  }
-  if (!htmlBody && containsMarkdownTable(plainTextBody)) {
-    throw new Error('Markdown table requires an HTML body before using Gmail.');
-  }
-  if (bodyHash !== mailBodyHash(recipient, subject, plainTextBody, htmlBody)) {
-    throw new Error('Email body integrity check failed.');
-  }
-  return { version: 1, actionId, kind, account, recipient, subject, plainTextBody, htmlBody, bodyHash };
-}
-
-export function buildGogMailArgs(action) {
-  const args = action.kind === 'sendEmail' ? ['gmail', 'send'] : ['gmail', 'drafts', 'create'];
-  args.push(`--to=${action.recipient}`, `--subject=${action.subject}`);
-  if (action.htmlBody) args.push(`--body-html=${action.htmlBody}`);
-  if (action.plainTextBody) args.push(`--body=${action.plainTextBody}`);
-  args.push(`--account=${action.account}`);
-  if (action.kind === 'sendEmail') args.push('--force');
-  args.push('--json', '--no-input');
-  return args;
-}
-
-export function mailBodyHash(recipient, subject, plainTextBody, htmlBody) {
-  return createHash('sha256')
-    .update(recipient)
-    .update('\n')
-    .update(subject)
-    .update('\n')
-    .update(plainTextBody)
-    .update('\n')
-    .update(htmlBody)
-    .digest('hex');
-}
-
-export function extractMailResultId(text, kind) {
-  if (!text) return '';
-  const candidates = [];
-  try {
-    candidates.push(JSON.parse(text));
-  } catch {
-    for (const line of String(text).split(/\r?\n/).reverse()) {
-      try {
-        candidates.push(JSON.parse(line));
-        break;
-      } catch {
-        // Keep looking for the final JSON line.
-      }
-    }
-  }
-  for (const candidate of candidates) {
-    const found = findMailResultId(candidate, kind);
-    if (found) return found;
-  }
-  return /"(?:draftId|draft_id|messageId|message_id|id)"\s*:\s*"([^"\s]{6,})"/.exec(String(text))?.[1] || '';
-}
-
-export function classifyGogProcessResult(action, result, toolVersion = '') {
-  const operation = action.kind === 'sendEmail' ? 'send' : 'draft create';
-  const mailbox = action.kind === 'sendEmail' ? 'Gmail Sent' : 'Gmail Drafts';
-  if (result.timedOut || result.aborted) {
-    return mailActionResult(action, 'needsConfirmation', {
-      error: `gog ${operation} timed out or was cancelled; check ${mailbox} before retrying.`,
-      toolVersion,
-      exitCode: result.exitCode,
-    });
-  }
-  if (result.error) {
-    return mailActionResult(action, 'failed', {
-      error: `gog ${operation} could not start: ${compactStatus(result.error)}`,
-      toolVersion,
-      exitCode: result.exitCode,
-    });
-  }
-  const messageId = extractMailResultId(result.stdout, action.kind);
-  if (result.exitCode === 0 && messageId) {
-    return mailActionResult(action, 'succeeded', { messageId, toolVersion, exitCode: 0 });
-  }
-  if (result.exitCode === 0) {
-    return mailActionResult(action, 'needsConfirmation', {
-      error: `gog ${operation} returned success without a verifiable Gmail id; check ${mailbox} before retrying.`,
-      toolVersion,
-      exitCode: 0,
-    });
-  }
-  const details = compactStatus(result.stderr || result.stdout || '');
-  return mailActionResult(action, 'failed', {
-    error: `gog ${operation} failed with exit code ${result.exitCode ?? 'unknown'}${details ? `: ${details}` : '.'}`,
-    toolVersion,
-    exitCode: result.exitCode,
-  });
-}
-
-export function resolveGogCommand(value = '') {
-  const requested = cleanText(value || process.env.CUSTOMER_MAP_GOG_BIN);
-  const fixedCandidates = process.platform === 'win32'
-    ? []
-    : [
-        '/opt/homebrew/bin/gog',
-        '/usr/local/bin/gog',
-        '/usr/bin/gog',
-        join(homedir(), '.local', 'bin', 'gog'),
-        join(homedir(), 'go', 'bin', 'gog'),
-      ];
-  const candidates = [
-    ...resolveCommandCandidate(requested),
-    ...fixedCandidates,
-    ...pathCommandCandidates(),
-  ];
-  const found = candidates.find(candidate => candidate && existsSync(candidate));
-  if (!found) throw new Error('gog was not found. Install it or pass --gog /absolute/path/to/gog.');
-  return found;
-}
-
-function mailActionResult(value, status, options = {}) {
-  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
-  const error = options.error || '';
-  const successReply = source.kind === 'saveDraft'
-    ? '邮件已通过 Codex Bridge 的固定 gog 参数保存到 Gmail 草稿。'
-    : '邮件已通过 Codex Bridge 的固定 gog 参数发送。';
-  return {
-    reply: status === 'succeeded' ? successReply : error,
-    subject: '',
-    sendText: '',
-    tag: '',
-    aiNote: '',
-    continue: false,
-    actionReceipt: {
-      kind: source.kind === 'saveDraft' ? 'saveDraft' : 'sendEmail',
-      status,
-      provider: 'gmail',
-      messageId: options.messageId || '',
-      recipient: cleanText(source.recipient).toLowerCase(),
-      occurredAt: status === 'succeeded' ? new Date().toISOString() : '',
-      error,
-      tool: 'gog',
-      toolVersion: options.toolVersion || '',
-      bodyMode: bodyMode(source),
-      bodyHash: cleanText(source.bodyHash).toLowerCase(),
-      actionId: cleanText(source.actionId).toLowerCase(),
-      exitCode: options.exitCode ?? null,
-    },
-  };
-}
-
-async function readGogVersion(command, signal) {
-  if (gogVersionCache.has(command)) return gogVersionCache.get(command);
-  const result = await runProcess(command, ['--version'], { signal, timeoutMs: 10_000 });
-  if (result.timedOut || result.aborted) throw new Error('unable to read gog version before timeout');
-  if (result.error) throw new Error(result.error);
-  const match = /v?(\d+)\.(\d+)\.(\d+)/.exec(result.stdout || result.stderr);
-  if (result.exitCode !== 0 || !match) throw new Error('unable to read gog version');
-  const version = match.slice(1, 4).map(Number);
-  if (compareVersion(version, MIN_GOG_VERSION) < 0) {
-    throw new Error(`gog v${version.join('.')} is older than v${MIN_GOG_VERSION.join('.')}`);
-  }
-  const normalized = version.join('.');
-  gogVersionCache.set(command, normalized);
-  return normalized;
-}
-
-function runProcess(executable, args, { signal, timeoutMs }) {
-  return new Promise(resolveResult => {
-    let stdout = '';
-    let stderr = '';
-    let settled = false;
-    let child;
-    const finish = result => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      signal?.removeEventListener('abort', abort);
-      resolveResult({ ...result, stdout, stderr });
-    };
-    const terminate = (timedOut, aborted) => {
-      child?.kill();
-      finish({ exitCode: null, timedOut, aborted, error: '' });
-    };
-    const abort = () => terminate(false, true);
-    const timer = setTimeout(() => terminate(true, false), Math.max(1_000, timeoutMs));
-    try {
-      child = spawn(executable, args, { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
-    } catch (error) {
-      finish({ exitCode: null, timedOut: false, aborted: false, error: formatError(error) });
-      return;
-    }
-    child.stdout?.on('data', chunk => { stdout = appendBounded(stdout, chunk); });
-    child.stderr?.on('data', chunk => { stderr = appendBounded(stderr, chunk); });
-    child.once('error', error => finish({ exitCode: null, timedOut: false, aborted: false, error: formatError(error) }));
-    child.once('close', code => finish({ exitCode: code, timedOut: false, aborted: false, error: '' }));
-    if (signal?.aborted) abort();
-    else signal?.addEventListener('abort', abort, { once: true });
-  });
-}
-
-function cacheMailResult(cacheKey, action, result) {
-  mailActionResults.set(cacheKey, { bodyHash: action.bodyHash, result });
-  while (mailActionResults.size > 200) mailActionResults.delete(mailActionResults.keys().next().value);
-  return result;
-}
-
-function findMailResultId(value, kind) {
-  if (Array.isArray(value)) {
-    for (const child of value) {
-      const found = findMailResultId(child, kind);
-      if (found) return found;
-    }
-    return '';
-  }
-  if (!value || typeof value !== 'object') return '';
-  const keys = kind === 'saveDraft'
-    ? ['draftId', 'draft_id', 'id', 'messageId', 'message_id']
-    : ['messageId', 'message_id', 'id', 'threadId', 'thread_id'];
-  for (const key of keys) {
-    const candidate = cleanText(value[key]);
-    if (candidate.length >= 6) return candidate;
-  }
-  for (const child of Object.values(value)) {
-    const found = findMailResultId(child, kind);
-    if (found) return found;
-  }
-  return '';
-}
-
-function resolveCommandCandidate(value) {
-  if (!value) return [];
-  if (isAbsolute(value)) return [value];
-  if (value.includes('/') || value.includes('\\')) return [resolve(value)];
-  return pathCommandCandidates(value);
-}
-
-function pathCommandCandidates(command = process.platform === 'win32' ? 'gog.exe' : 'gog') {
-  return cleanText(process.env.PATH)
-    .split(delimiter)
-    .filter(Boolean)
-    .flatMap(pathEntry => {
-      const path = join(pathEntry, command);
-      return process.platform === 'win32' && !/\.(?:exe|cmd)$/i.test(command) ? [path, `${path}.exe`, `${path}.cmd`] : [path];
-    });
-}
-
-function bodyMode(value) {
-  const hasHtml = Boolean(stringValue(value.htmlBody));
-  const hasPlain = Boolean(stringValue(value.plainTextBody));
-  if (hasHtml && hasPlain) return 'body-html+body';
-  if (hasHtml) return 'body-html';
-  if (hasPlain) return 'body';
-  return '';
-}
-
-function compareVersion(left, right) {
-  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
-    const difference = (left[index] || 0) - (right[index] || 0);
-    if (difference) return difference > 0 ? 1 : -1;
-  }
-  return 0;
-}
-
-function appendBounded(current, chunk) {
-  if (current.length >= MAX_PROCESS_OUTPUT_CHARS) return current;
-  return (current + String(chunk)).slice(0, MAX_PROCESS_OUTPUT_CHARS);
-}
-
-function validEmail(value) {
-  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
-}
-
-function looksLikeBodyPath(value) {
-  return /^(?:\/dev\/stdin|\/(?:private\/)?tmp\/\S+|[A-Za-z]:\\\S+|file:\/\/\S+)$/i.test(value.trim());
-}
-
-function containsMarkdownTable(value) {
-  return /(?:^|\n)\s*\|?.+\|.+\n\s*\|?\s*:?-{3,}/.test(value);
-}
-
-function compactStatus(value) {
-  const compact = String(value || '').replace(/\s+/g, ' ').trim();
-  return compact.length <= 320 ? compact : `${compact.slice(0, 317).trimEnd()}...`;
-}
-
-function cleanText(value) {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
-function stringValue(value) {
-  return typeof value === 'string' ? value : '';
-}
-
-function formatError(error) {
-  return error instanceof Error ? error.message : String(error || 'Unknown error');
-}
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, isAbsolute, join, resolve } from 'node:path';
+import process from 'node:process';
+
+const MIN_GOG_VERSION = [0, 11, 0];
+const MAX_GOG_BODY_BYTES = 100_000;
+const MAX_PROCESS_OUTPUT_CHARS = 1_000_000;
+const mailActionResults = new Map();
+const gogVersionCache = new Map();
+
+export async function executeCustomerMapMailAction(
+  value,
+  { signal, timeoutMs, gogCommand: requestedGogCommand = '' },
+) {
+  let action;
+  try {
+    action = normalizeMailAction(value);
+  } catch (error) {
+    return mailActionResult(value, 'failed', { error: formatError(error) });
+  }
+
+  const cacheKey = `${action.kind}:${action.actionId}`;
+  const cached = mailActionResults.get(cacheKey);
+  if (cached) {
+    if (cached.bodyHash !== action.bodyHash) {
+      return mailActionResult(action, 'failed', { error: 'Mail action id was reused with different content.' });
+    }
+    return cached.result;
+  }
+
+  let gogCommand;
+  let toolVersion;
+  try {
+    gogCommand = resolveGogCommand(requestedGogCommand);
+    toolVersion = await readGogVersion(gogCommand, signal);
+  } catch (error) {
+    return cacheMailResult(cacheKey, action, mailActionResult(action, 'failed', {
+      error: `gog is unavailable or unsupported: ${compactStatus(formatError(error))}`,
+    }));
+  }
+
+  const processResult = await runProcess(gogCommand, buildGogMailArgs(action), {
+    signal,
+    timeoutMs: Math.max(5_000, Math.min(Number(timeoutMs) - 2_000 || 90_000, 90_000)),
+  });
+  return cacheMailResult(cacheKey, action, classifyGogProcessResult(action, processResult, toolVersion));
+}
+
+export function normalizeMailAction(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Invalid Customer Map mail action.');
+  }
+  const source = value;
+  const kind = source.kind === 'sendEmail' || source.kind === 'saveDraft' ? source.kind : '';
+  const actionId = cleanText(source.actionId).toLowerCase();
+  const account = cleanText(source.account).toLowerCase();
+  const recipient = cleanText(source.recipient).toLowerCase();
+  const subject = cleanText(source.subject);
+  const plainTextBody = stringValue(source.plainTextBody);
+  const htmlBody = stringValue(source.htmlBody);
+  const bodyHash = cleanText(source.bodyHash).toLowerCase();
+  if (source.version !== 1 || !kind) throw new Error('Unsupported Customer Map mail action version or kind.');
+  if (!/^[0-9a-f]{32}$/.test(actionId)) throw new Error('Invalid Customer Map mail action id.');
+  if (!validEmail(account) || !validEmail(recipient)) throw new Error('Invalid Gmail account or recipient.');
+  if (!subject || /[\r\n]/.test(subject)) throw new Error('Invalid email subject.');
+  if (!plainTextBody && !htmlBody) throw new Error('Email body is empty.');
+  if (looksLikeBodyPath(plainTextBody) || looksLikeBodyPath(htmlBody)) {
+    throw new Error('Email body cannot be a filesystem or stdin path.');
+  }
+  if (Buffer.byteLength(plainTextBody, 'utf8') > MAX_GOG_BODY_BYTES || Buffer.byteLength(htmlBody, 'utf8') > MAX_GOG_BODY_BYTES) {
+    throw new Error('Email body is too large for safe gog argument execution.');
+  }
+  if (!htmlBody && containsMarkdownTable(plainTextBody)) {
+    throw new Error('Markdown table requires an HTML body before using Gmail.');
+  }
+  if (bodyHash !== mailBodyHash(recipient, subject, plainTextBody, htmlBody)) {
+    throw new Error('Email body integrity check failed.');
+  }
+  return { version: 1, actionId, kind, account, recipient, subject, plainTextBody, htmlBody, bodyHash };
+}
+
+export function buildGogMailArgs(action) {
+  const args = action.kind === 'sendEmail' ? ['gmail', 'send'] : ['gmail', 'drafts', 'create'];
+  args.push(`--to=${action.recipient}`, `--subject=${action.subject}`);
+  if (action.htmlBody) args.push(`--body-html=${action.htmlBody}`);
+  if (action.plainTextBody) args.push(`--body=${action.plainTextBody}`);
+  args.push(`--account=${action.account}`);
+  if (action.kind === 'sendEmail') args.push('--force');
+  args.push('--json', '--no-input');
+  return args;
+}
+
+export function mailBodyHash(recipient, subject, plainTextBody, htmlBody) {
+  return createHash('sha256')
+    .update(recipient)
+    .update('\n')
+    .update(subject)
+    .update('\n')
+    .update(plainTextBody)
+    .update('\n')
+    .update(htmlBody)
+    .digest('hex');
+}
+
+export function extractMailResultId(text, kind) {
+  if (!text) return '';
+  const candidates = [];
+  try {
+    candidates.push(JSON.parse(text));
+  } catch {
+    for (const line of String(text).split(/\r?\n/).reverse()) {
+      try {
+        candidates.push(JSON.parse(line));
+        break;
+      } catch {
+        // Keep looking for the final JSON line.
+      }
+    }
+  }
+  for (const candidate of candidates) {
+    const found = findMailResultId(candidate, kind);
+    if (found) return found;
+  }
+  return /"(?:draftId|draft_id|messageId|message_id|id)"\s*:\s*"([^"\s]{6,})"/.exec(String(text))?.[1] || '';
+}
+
+export function classifyGogProcessResult(action, result, toolVersion = '') {
+  const operation = action.kind === 'sendEmail' ? 'send' : 'draft create';
+  const mailbox = action.kind === 'sendEmail' ? 'Gmail Sent' : 'Gmail Drafts';
+  if (result.timedOut || result.aborted) {
+    return mailActionResult(action, 'needsConfirmation', {
+      error: `gog ${operation} timed out or was cancelled; check ${mailbox} before retrying.`,
+      toolVersion,
+      exitCode: result.exitCode,
+    });
+  }
+  if (result.error) {
+    return mailActionResult(action, 'failed', {
+      error: `gog ${operation} could not start: ${compactStatus(result.error)}`,
+      toolVersion,
+      exitCode: result.exitCode,
+    });
+  }
+  const messageId = extractMailResultId(result.stdout, action.kind);
+  if (result.exitCode === 0 && messageId) {
+    return mailActionResult(action, 'succeeded', { messageId, toolVersion, exitCode: 0 });
+  }
+  if (result.exitCode === 0) {
+    return mailActionResult(action, 'needsConfirmation', {
+      error: `gog ${operation} returned success without a verifiable Gmail id; check ${mailbox} before retrying.`,
+      toolVersion,
+      exitCode: 0,
+    });
+  }
+  const details = compactStatus(result.stderr || result.stdout || '');
+  return mailActionResult(action, 'failed', {
+    error: `gog ${operation} failed with exit code ${result.exitCode ?? 'unknown'}${details ? `: ${details}` : '.'}`,
+    toolVersion,
+    exitCode: result.exitCode,
+  });
+}
+
+export function resolveGogCommand(value = '') {
+  const requested = cleanText(value || process.env.CUSTOMER_MAP_GOG_BIN);
+  const fixedCandidates = process.platform === 'win32'
+    ? []
+    : [
+        '/opt/homebrew/bin/gog',
+        '/usr/local/bin/gog',
+        '/usr/bin/gog',
+        join(homedir(), '.local', 'bin', 'gog'),
+        join(homedir(), 'go', 'bin', 'gog'),
+      ];
+  const candidates = [
+    ...resolveCommandCandidate(requested),
+    ...fixedCandidates,
+    ...pathCommandCandidates(),
+  ];
+  const found = candidates.find(candidate => candidate && existsSync(candidate));
+  if (!found) throw new Error('gog was not found. Install it or pass --gog /absolute/path/to/gog.');
+  return found;
+}
+
+function mailActionResult(value, status, options = {}) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const error = options.error || '';
+  const successReply = source.kind === 'saveDraft'
+    ? '邮件已通过 Codex Bridge 的固定 gog 参数保存到 Gmail 草稿。'
+    : '邮件已通过 Codex Bridge 的固定 gog 参数发送。';
+  return {
+    reply: status === 'succeeded' ? successReply : error,
+    subject: '',
+    sendText: '',
+    tag: '',
+    aiNote: '',
+    continue: false,
+    actionReceipt: {
+      kind: source.kind === 'saveDraft' ? 'saveDraft' : 'sendEmail',
+      status,
+      provider: 'gmail',
+      messageId: options.messageId || '',
+      recipient: cleanText(source.recipient).toLowerCase(),
+      occurredAt: status === 'succeeded' ? new Date().toISOString() : '',
+      error,
+      tool: 'gog',
+      toolVersion: options.toolVersion || '',
+      bodyMode: bodyMode(source),
+      bodyHash: cleanText(source.bodyHash).toLowerCase(),
+      actionId: cleanText(source.actionId).toLowerCase(),
+      exitCode: options.exitCode ?? null,
+    },
+  };
+}
+
+async function readGogVersion(command, signal) {
+  if (gogVersionCache.has(command)) return gogVersionCache.get(command);
+  const result = await runProcess(command, ['--version'], { signal, timeoutMs: 10_000 });
+  if (result.timedOut || result.aborted) throw new Error('unable to read gog version before timeout');
+  if (result.error) throw new Error(result.error);
+  const match = /v?(\d+)\.(\d+)\.(\d+)/.exec(result.stdout || result.stderr);
+  if (result.exitCode !== 0 || !match) throw new Error('unable to read gog version');
+  const version = match.slice(1, 4).map(Number);
+  if (compareVersion(version, MIN_GOG_VERSION) < 0) {
+    throw new Error(`gog v${version.join('.')} is older than v${MIN_GOG_VERSION.join('.')}`);
+  }
+  const normalized = version.join('.');
+  gogVersionCache.set(command, normalized);
+  return normalized;
+}
+
+function runProcess(executable, args, { signal, timeoutMs }) {
+  return new Promise(resolveResult => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let child;
+    const finish = result => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      resolveResult({ ...result, stdout, stderr });
+    };
+    const terminate = (timedOut, aborted) => {
+      child?.kill();
+      finish({ exitCode: null, timedOut, aborted, error: '' });
+    };
+    const abort = () => terminate(false, true);
+    const timer = setTimeout(() => terminate(true, false), Math.max(1_000, timeoutMs));
+    try {
+      child = spawn(executable, args, { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      finish({ exitCode: null, timedOut: false, aborted: false, error: formatError(error) });
+      return;
+    }
+    child.stdout?.on('data', chunk => { stdout = appendBounded(stdout, chunk); });
+    child.stderr?.on('data', chunk => { stderr = appendBounded(stderr, chunk); });
+    child.once('error', error => finish({ exitCode: null, timedOut: false, aborted: false, error: formatError(error) }));
+    child.once('close', code => finish({ exitCode: code, timedOut: false, aborted: false, error: '' }));
+    if (signal?.aborted) abort();
+    else signal?.addEventListener('abort', abort, { once: true });
+  });
+}
+
+function cacheMailResult(cacheKey, action, result) {
+  mailActionResults.set(cacheKey, { bodyHash: action.bodyHash, result });
+  while (mailActionResults.size > 200) mailActionResults.delete(mailActionResults.keys().next().value);
+  return result;
+}
+
+function findMailResultId(value, kind) {
+  if (Array.isArray(value)) {
+    for (const child of value) {
+      const found = findMailResultId(child, kind);
+      if (found) return found;
+    }
+    return '';
+  }
+  if (!value || typeof value !== 'object') return '';
+  const keys = kind === 'saveDraft'
+    ? ['draftId', 'draft_id', 'id', 'messageId', 'message_id']
+    : ['messageId', 'message_id', 'id', 'threadId', 'thread_id'];
+  for (const key of keys) {
+    const candidate = cleanText(value[key]);
+    if (candidate.length >= 6) return candidate;
+  }
+  for (const child of Object.values(value)) {
+    const found = findMailResultId(child, kind);
+    if (found) return found;
+  }
+  return '';
+}
+
+function resolveCommandCandidate(value) {
+  if (!value) return [];
+  if (isAbsolute(value)) return [value];
+  if (value.includes('/') || value.includes('\\')) return [resolve(value)];
+  return pathCommandCandidates(value);
+}
+
+function pathCommandCandidates(command = process.platform === 'win32' ? 'gog.exe' : 'gog') {
+  return cleanText(process.env.PATH)
+    .split(delimiter)
+    .filter(Boolean)
+    .flatMap(pathEntry => {
+      const path = join(pathEntry, command);
+      return process.platform === 'win32' && !/\.(?:exe|cmd)$/i.test(command) ? [path, `${path}.exe`, `${path}.cmd`] : [path];
+    });
+}
+
+function bodyMode(value) {
+  const hasHtml = Boolean(stringValue(value.htmlBody));
+  const hasPlain = Boolean(stringValue(value.plainTextBody));
+  if (hasHtml && hasPlain) return 'body-html+body';
+  if (hasHtml) return 'body-html';
+  if (hasPlain) return 'body';
+  return '';
+}
+
+function compareVersion(left, right) {
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] || 0) - (right[index] || 0);
+    if (difference) return difference > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+function appendBounded(current, chunk) {
+  if (current.length >= MAX_PROCESS_OUTPUT_CHARS) return current;
+  return (current + String(chunk)).slice(0, MAX_PROCESS_OUTPUT_CHARS);
+}
+
+function validEmail(value) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
+function looksLikeBodyPath(value) {
+  return /^(?:\/dev\/stdin|\/(?:private\/)?tmp\/\S+|[A-Za-z]:\\\S+|file:\/\/\S+)$/i.test(value.trim());
+}
+
+function containsMarkdownTable(value) {
+  return /(?:^|\n)\s*\|?.+\|.+\n\s*\|?\s*:?-{3,}/.test(value);
+}
+
+function compactStatus(value) {
+  const compact = String(value || '').replace(/\s+/g, ' ').trim();
+  return compact.length <= 320 ? compact : `${compact.slice(0, 317).trimEnd()}...`;
+}
+
+function cleanText(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function stringValue(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error || 'Unknown error');
+}