kennel 0.2.0 → 0.2.2

package/kernel/plugins/mail/src/mailos.ts

@@ -0,0 +1,723 @@
+import { execFile as execFileCb } from "node:child_process"
+import { constants } from "node:fs"
+import { access, realpath } from "node:fs/promises"
+import { homedir } from "node:os"
+import { delimiter, isAbsolute, resolve as resolvePath, sep } from "node:path"
+import { promisify } from "node:util"
+
+/**
+ * Injectable subprocess runner. Production uses `execFile`; tests inject a
+ * fake that records exact arguments and controls output/errors. The options
+ * mirror execFile's accepted shape so the real and fake implementations can
+ * share one signature.
+ */
+export type ExecFileLike = (
+  file: string,
+  args: string[],
+  options: {
+    cwd: string
+    timeout: number
+    maxBuffer: number
+    windowsHide?: boolean
+    signal?: AbortSignal
+  },
+) => Promise<{ stdout: string; stderr: string }>
+
+const defaultExecFileLike = promisify(execFileCb) as ExecFileLike
+
+/**
+ * Failure code for a MailOS command. `timeout` when the child was killed by
+ * the deadline, `not-found` when the CLI reported the target missing,
+ * `aborted` when the caller cancelled (e.g. client disconnect), `failed` for
+ * every other non-zero exit.
+ */
+export type MailosCommandFailure =
+  "timeout" | "not-found" | "aborted" | "failed"
+
+export class MailosCommandError extends Error {
+  readonly code: MailosCommandFailure
+  readonly timedOut: boolean
+  readonly aborted: boolean
+  readonly exitCode: number | null
+
+  constructor(
+    code: MailosCommandFailure,
+    message: string,
+    details: {
+      exitCode?: number | null
+      timedOut?: boolean
+      aborted?: boolean
+    } = {},
+  ) {
+    super(message)
+    this.name = "MailosCommandError"
+    this.code = code
+    this.timedOut = details.timedOut ?? code === "timeout"
+    this.aborted = details.aborted ?? code === "aborted"
+    this.exitCode = details.exitCode ?? null
+  }
+}
+
+function classifyExecError(error: unknown): MailosCommandError {
+  if (error instanceof MailosCommandError) return error
+  if (!(error instanceof Error)) {
+    return new MailosCommandError("failed", "MailOS command failed")
+  }
+  if (error.name === "AbortError") {
+    return new MailosCommandError("aborted", "MailOS command cancelled")
+  }
+  const execError = error as Error & {
+    code?: string | number
+    killed?: boolean
+  }
+  if (execError.killed) {
+    return new MailosCommandError("timeout", "MailOS command timed out", {
+      timedOut: true,
+      exitCode: typeof execError.code === "number" ? execError.code : null,
+    })
+  }
+  return new MailosCommandError("failed", "MailOS command failed to complete", {
+    exitCode: typeof execError.code === "number" ? execError.code : null,
+  })
+}
+
+/**
+ * Central subprocess lifecycle: a hard timeout kills the child, an optional
+ * AbortSignal (client disconnect) cancels it, and errors are converted into
+ * redacted `MailosCommandError` values that never carry command output
+ * (credentials or message bodies cannot leak into error messages or logs).
+ */
+export async function runMailos(
+  execFile: ExecFileLike,
+  mailosBin: string,
+  args: string[],
+  options: {
+    cwd: string
+    timeoutMs: number
+    maxBufferBytes?: number
+    signal?: AbortSignal
+  },
+): Promise<{ stdout: string; stderr: string }> {
+  if (options.signal?.aborted) {
+    throw new MailosCommandError("aborted", "MailOS command cancelled")
+  }
+  try {
+    return await execFile(mailosBin, args, {
+      cwd: options.cwd,
+      timeout: options.timeoutMs,
+      maxBuffer: options.maxBufferBytes ?? 10 * 1024 * 1024,
+      windowsHide: true,
+      signal: options.signal,
+    })
+  } catch (error) {
+    const classified = classifyExecError(error)
+    if (options.signal?.aborted && classified.code !== "aborted") {
+      throw new MailosCommandError("aborted", "MailOS command cancelled")
+    }
+    throw classified
+  }
+}
+
+export type MailosServiceOptions = {
+  execFile?: ExecFileLike
+  mailosBin?: string
+  /** Test seam: MailOS's global draft dir (defaults to ~/.email/drafts). */
+  globalDraftDir?: string
+}
+
+export type MailosIdentity = {
+  from: string | null
+  name: string | null
+  /** False when the CLI could not resolve an identity (caller may hide the row). */
+  ok: boolean
+}
+
+export type ConversationMessage = {
+  body: string
+  date: string | null
+  from: string | null
+  id: string
+  subject: string | null
+  to: string | null
+}
+
+export type ConversationOutcome =
+  "empty" | "ok" | "partial" | "not-found" | "timeout"
+
+export type ConversationResult = {
+  items: ConversationMessage[]
+  missing: string[]
+  outcome: ConversationOutcome
+}
+
+export type SendPreviewResult = {
+  dryRun: true
+  output: string
+  revision: string
+}
+
+export type SendResult = {
+  dryRun: false
+  output: string
+}
+
+export type SendFailureReason =
+  | "revision-match"
+  | "contract"
+  | "command"
+  | "invalid-draft"
+  | "unsupported-draft-dir"
+
+export class MailSendFailure extends Error {
+  readonly reason: SendFailureReason
+
+  constructor(reason: SendFailureReason, message: string) {
+    super(message)
+    this.name = "MailSendFailure"
+    this.reason = reason
+  }
+}
+
+async function isExecutable(path: string) {
+  try {
+    await access(path, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function pathIsWithin(child: string, parent: string) {
+  const rel = child.startsWith(parent) ? child.slice(parent.length) : null
+  if (!rel) return false
+  return rel === "" || rel.startsWith(sep)
+}
+
+/**
+ * Resolve the MailOS binary, refusing to pick a binary that lives inside the
+ * working folder so drafts cannot point commands at an attacker-controlled
+ * executable.
+ */
+export async function resolveMailosBinary({
+  cwd,
+}: {
+  cwd: string
+}): Promise<string> {
+  const preferred = resolvePath(homedir(), ".local", "bin", "mailos")
+  if (await isExecutable(preferred)) return preferred
+
+  const pathEnv = process.env.PATH ?? ""
+  for (const dir of pathEnv.split(delimiter)) {
+    const trimmed = dir.trim()
+    if (!trimmed) continue
+    if (!isAbsolute(trimmed)) continue
+
+    const candidate = resolvePath(trimmed, "mailos")
+    if (!isAbsolute(candidate)) continue
+    if (pathIsWithin(candidate, cwd)) continue
+
+    if (await isExecutable(candidate)) return candidate
+  }
+
+  throw new Error(
+    "MailOS binary not found. Expected ~/.local/bin/mailos or an absolute PATH entry.",
+  )
+}
+
+/**
+ * Bounded per-(folder, id) in-flight and success cache. The scope key embeds
+ * the working folder so caches never cross account/folder scope, in-flight
+ * reads are deduplicated, and successful reads are held for the conversation
+ * window instead of re-invoking the CLI on every detail view.
+ *
+ * Cancellation is subscriber-scoped: each caller's AbortSignal is registered
+ * on the shared in-flight entry; one canceled consumer only removes its own
+ * subscription, and the shared child is aborted only when the *last*
+ * subscriber cancels. A canceled consumer therefore never kills a concurrent
+ * consumer of the same (cwd, id), while a fully-disconnected request still
+ * stops its children.
+ */
+type ConversationMessageCacheEntry = {
+  message: ConversationMessage
+  at: number
+}
+
+type ConversationInFlight = {
+  promise: Promise<ConversationMessage>
+  controller: AbortController
+  signals: Map<AbortSignal, () => void>
+}
+
+type ConversationCache = {
+  inFlight: Map<string, ConversationInFlight>
+  success: Map<string, ConversationMessageCacheEntry>
+}
+
+const conversationCache: ConversationCache = {
+  inFlight: new Map(),
+  success: new Map(),
+}
+
+export const conversationLimits = {
+  maxReferences: 12,
+  // MailOS `read` is an IMAP/notmuch operation; real-world successful reads
+  // are measured at 22-26s, so the per-read cap sits above that envelope
+  // (60s) while the whole conversation view stays bounded at 75s. There is
+  // deliberately no retry loop: slow-but-successful reads must not be
+  // classified as failures.
+  perReadTimeoutMs: 60_000,
+  totalBudgetMs: 75_000,
+  concurrency: 3,
+  successCacheSize: 40,
+  // Successful reads are only reused within the conversation window; after
+  // this the CLI is re-invoked so actions (send/archive/delete) never stay
+  // masked by a stale server-side copy.
+  successTtlMs: 60_000,
+} as const
+
+export function resetConversationCache() {
+  conversationCache.inFlight.clear()
+  conversationCache.success.clear()
+}
+
+function scopeKey(cwd: string, id: string) {
+  return `${cwd}\u0000${id}`
+}
+
+function parseConversationMarkdown(
+  id: string,
+  output: string,
+): ConversationMessage {
+  const subject = /^#\s+(.+)$/m.exec(output)?.[1]?.trim() ?? null
+  const from =
+    /^\*\*From:\*\*\s+(.+?)(?:\s{2,}|$)/m.exec(output)?.[1]?.trim() ?? null
+  const to =
+    /^\*\*To:\*\*\s+(.+?)(?:\s{2,}|$)/m.exec(output)?.[1]?.trim() ?? null
+  const date =
+    /^\*\*Date:\*\*\s+(.+?)(?:\s{2,}|$)/m.exec(output)?.[1]?.trim() ?? null
+  const separator = output.indexOf("\n---\n")
+  const body = (separator >= 0 ? output.slice(separator + 5) : output).trim()
+  return { body, date, from, id, subject, to }
+}
+
+/**
+ * Structured, account-scoped MailOS access. Every command is an explicit
+ * fixed template over a canonical draft identity; nothing from the client is
+ * ever formatted into the command line. Identity/conversation/send/archive
+ * live here instead of the web plugin so the basic draft reader (`node.ts`)
+ * never needs the CLI.
+ */
+export type SendDraftOptions = {
+  /**
+   * The exact draft directory the client authorized (its mailDir). MailOS
+   * resolves draft ids against the global ~/.email/drafts by default; passing
+   * this makes send/preview target the file already read by list/detail,
+   * never a same-named draft elsewhere.
+   */
+  draftDir: string
+  signal?: AbortSignal
+}
+
+/** Internal parameter shape: the draft dir may be absent until validated. */
+type SendDraftParams = {
+  draftDir?: string
+  signal?: AbortSignal
+}
+
+function requireDraftDir(draftDir: string | undefined) {
+  if (!draftDir || !isAbsolute(draftDir)) {
+    throw new MailSendFailure(
+      "invalid-draft",
+      "A send draft directory (the authorized mailDir) is required",
+    )
+  }
+  return draftDir
+}
+
+function sameCanonicalDir(left: string, right: string) {
+  const canonical = async (value: string) =>
+    realpath(value).catch(() => resolvePath(value))
+  return Promise.all([canonical(left), canonical(right)]).then(
+    ([leftReal, rightReal]) => leftReal === rightReal,
+  )
+}
+
+/** The single directory `mailos drafts archive <id>` can address. */
+export function mailosGlobalDraftDir() {
+  return resolvePath(homedir(), ".email", "drafts")
+}
+
+export function createMailosService(options: MailosServiceOptions = {}) {
+  const execFile = options.execFile ?? defaultExecFileLike
+  const mailosBin = options.mailosBin
+  const globalDraftDir = options.globalDraftDir
+
+  async function binary(cwd: string) {
+    if (mailosBin) {
+      if (!isAbsolute(mailosBin)) {
+        throw new Error("mailosBin must be an absolute path")
+      }
+      if (pathIsWithin(mailosBin, cwd)) {
+        throw new Error("mailosBin cannot live inside the working folder")
+      }
+      return mailosBin
+    }
+    return resolveMailosBinary({ cwd })
+  }
+
+  function normalizeIdentityValue(value: string | null): string | null {
+    return value && value !== "(not set)" ? value : null
+  }
+
+  async function identity(cwd: string): Promise<MailosIdentity> {
+    try {
+      const bin = await binary(cwd)
+      const { stdout, stderr } = await runMailos(execFile, bin, ["whoami"], {
+        cwd,
+        timeoutMs: 15_000,
+      })
+      const output = [stdout, stderr].filter(Boolean).join("\n")
+      const from = normalizeIdentityValue(
+        /^Effective From:[ \t]*([^\r\n]+)$/im.exec(output)?.[1]?.trim() ?? null,
+      )
+      const name = normalizeIdentityValue(
+        /^From Name:[ \t]*([^\r\n]+)$/im.exec(output)?.[1]?.trim() ?? null,
+      )
+      return { from, name, ok: Boolean(from ?? name) }
+    } catch {
+      // Sender resolution is best-effort lazy enrichment; never fail the row.
+      return { from: null, name: null, ok: false }
+    }
+  }
+
+  /**
+   * Resolved markdown signature for a folder, or null when the folder has no
+   * signature configured (or the CLI cannot resolve one). Best-effort exactly
+   * like `identity`: a failing or empty `mailos sig` never fails the draft
+   * preview, it just leaves the signature section empty.
+   */
+  async function signature(
+    folder: string,
+    signal?: AbortSignal,
+  ): Promise<string | null> {
+    try {
+      const bin = await binary(folder)
+      const { stdout } = await runMailos(execFile, bin, ["sig", folder], {
+        cwd: folder,
+        timeoutMs: 15_000,
+        signal,
+      })
+      const output = stdout.trim()
+      if (!output) return null
+      if (output.includes("(no signature configured)")) return null
+      if (output.includes("(signature is empty)")) return null
+      return output
+    } catch {
+      return null
+    }
+  }
+
+  async function readMessage(
+    cwd: string,
+    id: string,
+    signal?: AbortSignal,
+  ): Promise<ConversationMessage> {
+    const bin = await binary(cwd)
+    const { stdout } = await runMailos(
+      execFile,
+      bin,
+      ["read", id, "--markdown"],
+      {
+        cwd,
+        timeoutMs: conversationLimits.perReadTimeoutMs,
+        signal,
+      },
+    )
+    return parseConversationMarkdown(id, stdout)
+  }
+
+  function cachedRead(
+    cwd: string,
+    id: string,
+    signal?: AbortSignal,
+  ): Promise<ConversationMessage> {
+    const key = scopeKey(cwd, id)
+    const cached = conversationCache.success.get(key)
+    if (cached) {
+      if (Date.now() - cached.at < conversationLimits.successTtlMs) {
+        return Promise.resolve(cached.message)
+      }
+      conversationCache.success.delete(key)
+    }
+
+    let entry = conversationCache.inFlight.get(key)
+    if (!entry) {
+      const controller = new AbortController()
+      const started = readMessage(cwd, id, controller.signal)
+      const created: ConversationInFlight = {
+        promise: started,
+        controller,
+        signals: new Map(),
+      }
+      entry = created
+      conversationCache.inFlight.set(key, created)
+      void started
+        .then((message) => {
+          const success = conversationCache.success
+          if (success.size >= conversationLimits.successCacheSize) {
+            success.delete(success.keys().next().value as string)
+          }
+          success.set(key, { message, at: Date.now() })
+        })
+        .catch(() => {
+          // The failure is delivered to `started` consumers; only the cache
+          // bookkeeping chain observes it here and must swallow it.
+        })
+        .finally(() => {
+          conversationCache.inFlight.delete(key)
+          for (const [subscriber, onAbort] of created.signals) {
+            subscriber.removeEventListener("abort", onAbort)
+          }
+        })
+    }
+    const active = entry
+    if (signal) {
+      const onAbort = () => {
+        active.signals.delete(signal)
+        // Last subscriber cancel kills the shared child; any remaining
+        // subscriber keeps it alive and still receives the result.
+        if (active.signals.size === 0) active.controller.abort()
+      }
+      active.signals.set(signal, onAbort)
+      if (signal.aborted) onAbort()
+      else signal.addEventListener("abort", onAbort, { once: true })
+    }
+    // The shared child runs on its own controller. Each caller's own abort
+    // only races their individual wait: the caller stops waiting (their
+    // request rejects as aborted) while the shared child keeps running for
+    // any remaining subscribers — production requests therefore reuse the
+    // in-flight read AND still stop on client disconnect.
+    if (!signal) return active.promise
+    return new Promise<ConversationMessage>((resolveOuter, rejectOuter) => {
+      let settled = false
+      const settleRace = (value: ConversationMessage | Error) => {
+        if (settled) return
+        settled = true
+        signal.removeEventListener("abort", onCallerAbort)
+        if (value instanceof Error) rejectOuter(value)
+        else resolveOuter(value)
+      }
+      const onCallerAbort = () =>
+        settleRace(
+          new MailosCommandError("aborted", "MailOS command cancelled"),
+        )
+      active.promise.then(
+        (message) => settleRace(message),
+        (error: unknown) =>
+          settleRace(error instanceof Error ? error : new Error(String(error))),
+      )
+      signal.addEventListener("abort", onCallerAbort, { once: true })
+      if (signal.aborted) onCallerAbort()
+    })
+  }
+
+  async function conversation(
+    cwd: string,
+    references: string[],
+    signal?: AbortSignal,
+  ): Promise<ConversationResult> {
+    const ids = [
+      ...new Set(
+        references
+          .map((candidate) => candidate.trim())
+          .filter((candidate) => Boolean(candidate) && !/\s/.test(candidate)),
+      ),
+    ].slice(0, conversationLimits.maxReferences)
+
+    const items: ConversationMessage[] = []
+    const missing: string[] = []
+    if (!ids.length) return { items, missing, outcome: "empty" }
+
+    const deadline = Date.now() + conversationLimits.totalBudgetMs
+    let timedOut = false
+    const queued = ids.map((id) => ({ id, started: false, done: false }))
+    let nextIndex = 0
+
+    const worker = async () => {
+      while (nextIndex < queued.length) {
+        const slot = queued[nextIndex]
+        if (!slot) break
+        nextIndex += 1
+        slot.started = true
+        try {
+          const message = await cachedRead(cwd, slot.id, signal)
+          if (!items.some((item) => item.id === message.id)) {
+            items.push(message)
+          }
+        } catch (error) {
+          if (error instanceof MailosCommandError) {
+            if (error.timedOut) timedOut = true
+            if (error.aborted) throw error
+          }
+          missing.push(slot.id)
+        }
+        if (Date.now() >= deadline) {
+          timedOut = true
+          break
+        }
+      }
+    }
+
+    const workers = Array.from(
+      { length: Math.min(conversationLimits.concurrency, ids.length) },
+      () => worker(),
+    )
+    await Promise.all(workers)
+
+    if (timedOut) return { items, missing, outcome: "timeout" }
+    if (!items.length && missing.length === ids.length) {
+      return { items, missing, outcome: "not-found" }
+    }
+    if (missing.length > 0) return { items, missing, outcome: "partial" }
+    return { items, missing, outcome: "ok" }
+  }
+
+  async function sendPreview(
+    cwd: string,
+    id: string,
+    options: SendDraftParams = {},
+  ): Promise<SendPreviewResult> {
+    const draftDir = requireDraftDir(options.draftDir)
+    const bin = await binary(cwd)
+    const args = ["send", "draft", id, "--draft-dir", draftDir, "--preview"]
+    const { stdout, stderr } = await runMailos(execFile, bin, args, {
+      cwd,
+      timeoutMs: 30_000,
+      signal: options.signal,
+    })
+    const output = [stdout, stderr].filter(Boolean).join("\n")
+    const revision = /^Revision:\s*([a-f0-9]{64})\s*$/im.exec(output)?.[1]
+    if (!revision) {
+      throw new MailSendFailure(
+        "invalid-draft",
+        "MailOS did not return a revision; the draft is not sendable.",
+      )
+    }
+    return { dryRun: true, output, revision }
+  }
+
+  async function confirmSend(
+    cwd: string,
+    id: string,
+    revision: string,
+    options: SendDraftParams = {},
+  ): Promise<SendResult> {
+    if (!/^[a-f0-9]{64}$/i.test(revision)) {
+      throw new MailSendFailure("revision-match", "Invalid draft revision")
+    }
+    const draftDir = requireDraftDir(options.draftDir)
+    const bin = await binary(cwd)
+    const args = [
+      "send",
+      "draft",
+      id,
+      "--draft-dir",
+      draftDir,
+      "--draft-revision",
+      revision,
+      "--delete-after=false",
+    ]
+    const { stdout, stderr } = await runMailos(execFile, bin, args, {
+      cwd,
+      timeoutMs: 60_000,
+      signal: options.signal,
+    })
+    const output = [stdout, stderr].filter(Boolean).join("\n")
+    // MailOS refuses a single draft whose bytes changed after the preview
+    // (send.go prints `❌ Draft <base> changed after preview` and errors the
+    // run). Surface that retryable conflict as a revision conflict, not as a
+    // generic command failure.
+    if (/\n?\s*❌\s*Draft\s+\S+\s+changed after preview/.test(output)) {
+      throw new MailSendFailure(
+        "revision-match",
+        "Draft changed after preview; refresh and preview again before sending",
+      )
+    }
+    const contract = validateSendContract(output)
+    if (!contract.ok) {
+      throw new MailSendFailure("contract", contract.reason)
+    }
+    return { dryRun: false, output }
+  }
+
+  async function archive(
+    cwd: string,
+    id: string,
+    options: SendDraftParams = {},
+  ): Promise<void> {
+    const draftDir = requireDraftDir(options.draftDir)
+    // `mailos drafts archive <id>` resolves ids ONLY against the global
+    // ~/.email/drafts directory (drafts.go `localDraftPath` ->
+    // `globalDraftDir`); it has no --draft-dir flag. A custom mailDir would
+    // silently mutate a same-named file (or fail) in the home drafts folder,
+    // so a non-canonical target is rejected here, before any spawn.
+    if (
+      !(await sameCanonicalDir(
+        draftDir,
+        globalDraftDir ?? mailosGlobalDraftDir(),
+      ))
+    ) {
+      throw new MailSendFailure(
+        "unsupported-draft-dir",
+        "MailOS drafts archive can only address the default ~/.email/drafts folder; this draft lives elsewhere. Delete it or archive it directly with mailos.",
+      )
+    }
+    const bin = await binary(cwd)
+    await runMailos(execFile, bin, ["drafts", "archive", id], {
+      cwd,
+      timeoutMs: 30_000,
+      signal: options.signal,
+    })
+  }
+
+  return {
+    identity,
+    signature,
+    conversation,
+    sendPreview,
+    confirmSend,
+    archive,
+  }
+}
+
+export type MailosService = ReturnType<typeof createMailosService>
+
+/**
+ * MailOS exits successfully even when a bulk run skipped or failed drafts, so
+ * a non-zero exit alone cannot prove delivery. Validate the printed contract:
+ * no failure/skip markers, a summary claiming at least one sent draft, and no
+ * recorded errors.
+ */
+export function validateSendContract(
+  output: string,
+): { ok: true } | { ok: false; reason: string } {
+  const markers = /^\s*(❌|⏭️)/m.exec(output)
+  if (markers) {
+    return { ok: false, reason: "MailOS reported a failed or skipped draft" }
+  }
+  if (output.includes("No draft files found to send")) {
+    return { ok: false, reason: "MailOS did not find the draft to send" }
+  }
+  const errors = /^\s*❌\s*Errors:\s*(\d+)/m.exec(output)
+  if (errors?.[1] && Number(errors[1]) > 0) {
+    return {
+      ok: false,
+      reason: `MailOS reported ${errors[1]} send error(s)`,
+    }
+  }
+  const sent = /^\s*✅\s*(?:Sent|Previewed|Would send):\s*(\d+)/m.exec(output)
+  if (!sent || Number(sent[1]) < 1) {
+    return { ok: false, reason: "MailOS did not confirm the draft was sent" }
+  }
+  return { ok: true }
+}