@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/src/core/markdown.ts

@@ -0,0 +1,114 @@
+// Markdown → HTML for the mail body.
+//
+// The agent answers in Markdown. Sending it escaped means the reader sees `**bold**`,
+// `| a | b |` and ``` fences in a client that could have rendered them.
+//
+// Rendering is delegated to **markdown-it**, configured to be safe by default rather
+// than trusted:
+//
+//   - `html: false` — raw HTML in the model output is escaped, not passed through, so
+//     there is no sanitiser to get wrong and nothing to lose on a library upgrade.
+//   - `linkify: true` — bare URLs become links, which is most of the value of an email.
+//   - markdown-it's own `validateLink` refuses `javascript:`, `vbscript:` and `data:`
+//     hrefs, so a link in model output cannot become script in the reader's client.
+//   - `breaks: true` — single newlines are `<br>`, matching how the body is written
+//     (answer, then our fixed footer) instead of reflowing it into one paragraph.
+//
+// Dependency cost is markdown-it plus six small transitive packages (entities,
+// linkify-it, mdurl, argparse, uc.micro, punycode.js), all from the same maintainers.
+
+import MarkdownIt from "markdown-it"
+
+const md = new MarkdownIt({
+	html: false,
+	linkify: true,
+	breaks: true,
+	typographer: false,
+})
+
+// --- email-safe styling ------------------------------------------------------
+//
+// markdown-it emits bare tags. Mail clients default to *no* table borders, so a table
+// arrived as loose text; and a `<style>` block is stripped by several clients. Inline
+// styles on each cell are what survive that, so the rendering rules are overridden
+// rather than the output being post-processed.
+
+const CELL_BORDER = "border:1px solid #c8ccd1"
+
+/**
+ * Merge our style with any attributes markdown-it already set (alignment, mostly).
+ * `attrs` is typed loosely because @types/markdown-it uses its own TokenAttribute
+ * shape; it is always a list of name/value pairs at runtime.
+ */
+function styledTag(name: string, rawAttrs: unknown, extra: string): string {
+	const pairs = Array.isArray(rawAttrs) ? (rawAttrs as [string, string][]) : []
+	const attrs = new Map<string, string>(pairs)
+	const existing = attrs.get("style")
+	attrs.set("style", existing ? `${existing};${extra}` : extra)
+	// cellspacing/cellpadding are attributes, not CSS, and survive sanitising better.
+	const rendered = [...attrs].map(([key, value]) => ` ${key}="${md.utils.escapeHtml(value)}"`).join("")
+	return `<${name}${rendered}>`
+}
+
+md.renderer.rules.table_open = () =>
+	'<table cellspacing="0" cellpadding="0" style="border-collapse:collapse;margin:10px 0;font-size:13px">'
+md.renderer.rules.th_open = (tokens, idx) =>
+	styledTag("th", tokens[idx]?.attrs, `${CELL_BORDER};padding:6px 10px;background:#f2f4f7;text-align:left`)
+md.renderer.rules.td_open = (tokens, idx) => styledTag("td", tokens[idx]?.attrs, `${CELL_BORDER};padding:6px 10px`)
+
+const MONO = "font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace"
+md.renderer.rules.fence = (tokens, idx) => {
+	const token = tokens[idx]!
+	const language = token.info.trim().split(/\s+/)[0] ?? ""
+	const cls = language ? ` class="language-${md.utils.escapeHtml(language)}"` : ""
+	return (
+		`<pre style="background:#f6f8fa;${CELL_BORDER};border-radius:4px;padding:10px;overflow:auto;${MONO};font-size:13px">` +
+		`<code${cls}>${md.utils.escapeHtml(token.content)}</code></pre>`
+	)
+}
+md.renderer.rules.code_inline = (tokens, idx) =>
+	`<code style="background:#f2f4f7;border-radius:3px;padding:1px 4px;${MONO};font-size:13px">${md.utils.escapeHtml(tokens[idx]!.content)}</code>`
+
+
+/** Inline Markdown (no block structure). */
+export function renderInline(text: string): string {
+	return md.renderInline(text)
+}
+
+/** Block Markdown as HTML, trimmed so callers can concatenate it. */
+export function renderMarkdown(text: string): string {
+	return md.render(text).trim()
+}
+
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;")
+}
+
+/** The RFC 3676 signature delimiter, which our own body uses before its metadata. */
+const FOOTER_SPLIT = /^--$/m
+
+/**
+ * Render an outbound body: Markdown above the `--` delimiter, literal text below it.
+ *
+ * The footer is deliberately not Markdown. A line of `--` after a text line is a setext
+ * heading underline, so rendering it would swallow our metadata into an `<h2>`.
+ */
+export function renderBody(text: string): string {
+	const index = text.search(FOOTER_SPLIT)
+	if (index === -1) return renderMarkdown(text)
+
+	const head = text.slice(0, index)
+	const tailLines = text.slice(index).split("\n")
+	// The `--` line itself is dropped in HTML: the top border is the divider there. It
+	// stays in the text part, where RFC 3676 needs it and quote stripping relies on it.
+	const tail = (tailLines[0]?.trim() === "--" ? tailLines.slice(1) : tailLines).join("\n")
+	// A visible divider, but literal text: rendering `--` as Markdown would make it a
+	// setext heading underline and swallow the body above it.
+	const signatureStyle = "font:inherit;opacity:.75;margin:18px 0 0;padding-top:10px;border-top:1px solid #d8dee4"
+	return `${renderMarkdown(head)}\n<pre class="signature" style="${signatureStyle}">${escapeHtml(tail)}</pre>`
+}

package/src/core/oauth-device.ts

@@ -0,0 +1,195 @@
+// Device-code OAuth2 — one auth path for every provider.
+//
+// Microsoft killed app passwords for outlook.com; Gmail keeps them but discourages
+// them; self-hosted boxes may move to OAuth2 next. Rather than write a flow per
+// provider, this module speaks plain OAuth2 **device authorization** (RFC 8628),
+// which every provider we care about supports:
+//
+//   Microsoft (consumers or any tenant)  https://login.microsoftonline.com/consumers/v2.0
+//   Google                              https://accounts.google.com
+//   any OIDC                            your issuer
+//
+// The flow is deliberately the *pull* variant: no redirect URI, no local listener,
+// no browser on the daemon box. You approve on whatever device you like — which is
+// also why the rest of this package can be driven from any device with email.
+//
+// openid-client is reached through an adapter (see core/oauth-openid.ts) so the
+// provider itself is testable and the library stays swappable.
+
+import type { TokenProvider } from "./oauth.ts"
+
+export interface OAuthConfig {
+	/** Issuer / discovery base URL, e.g. https://login.microsoftonline.com/consumers/v2.0 */
+	issuer: string
+	clientId: string
+	/** Omit for a public client using PKCE-style device flow. */
+	clientSecret?: string
+	/** Space-separated scopes, e.g. "offline_access https://outlook.office.com/IMAP.AccessAsUser.All" */
+	scope: string
+}
+
+export interface OAuthTokens {
+	accessToken: string
+	refreshToken?: string
+	/** Epoch ms when accessToken expires. */
+	expiresAt: number
+}
+
+/** What the human has to see to approve the login. */
+export interface DeviceAuthorization {
+	verificationUri: string
+	/** Short code to type, if the provider uses one. */
+	userCode: string
+}
+
+/** The OAuth client surface this module needs. */
+export interface OAuthClient {
+	deviceAuthorization(): Promise<DeviceAuthorization>
+	/** Polls until the human approves or the code expires. */
+	pollDeviceAuthorization(): Promise<OAuthTokens>
+	refresh(refreshToken: string): Promise<OAuthTokens>
+}
+
+/** Persisted tokens. Only the refresh token matters long-term. */
+export interface StoredTokens {
+	refreshToken?: string
+	accessToken?: string
+	expiresAt?: number
+}
+
+export interface TokenStore {
+	read(): StoredTokens | undefined
+	write(tokens: StoredTokens): void
+}
+
+export interface DeviceCodeProviderOptions {
+	client: OAuthClient
+	store: TokenStore
+	now?: () => number
+	/** Refresh this long before expiry rather than at it. */
+	skewMs?: number
+}
+
+const DEFAULT_SKEW_MS = 60_000
+
+/**
+ * A `TokenProvider` backed by the device-code grant.
+ *
+ * Resolution order: cached access token -> stored refresh token -> fail with an
+ * instruction to run the login command. It never silently degrades to a password:
+ * half-configured auth is worse than a clear error.
+ */
+/** Consecutive refresh failures tolerated before the provider disables itself. */
+const MAX_REFRESH_FAILURES = 3
+
+/**
+ * Errors that mean the grant itself is gone, so retrying cannot help.
+ * Everything else (DNS, TLS, timeout, 5xx) is treated as transient.
+ */
+function isCredentialError(error: unknown): boolean {
+	const text = error instanceof Error ? `${error.name} ${error.message}` : String(error)
+	return /invalid_grant|invalid_request|unauthorized_client|consent_required|interaction_required|refresh token (?:is )?(?:invalid|expired|revoked)/i.test(
+		text,
+	)
+}
+
+export function createDeviceCodeProvider(options: DeviceCodeProviderOptions): TokenProvider & {
+	/** Run the interactive login once and persist the refresh token. */
+	login(): Promise<DeviceAuthorization>
+} {
+	const { client, store } = options
+	const now = options.now ?? (() => Date.now())
+	const skew = options.skewMs ?? DEFAULT_SKEW_MS
+
+	let cached: OAuthTokens | undefined
+	let failures = 0
+	let disabled = false
+	let inFlight: Promise<string> | undefined
+
+	function fresh(tokens: StoredTokens | OAuthTokens | undefined): boolean {
+		return Boolean(tokens?.accessToken && tokens.expiresAt && tokens.expiresAt - skew > now())
+	}
+
+	async function acquire(): Promise<string> {
+		const stored = store.read()
+
+		if (fresh(stored)) {
+			cached = { accessToken: stored!.accessToken!, expiresAt: stored!.expiresAt! }
+			return cached.accessToken
+		}
+
+		if (!stored?.refreshToken) {
+			disabled = true
+			throw new Error(
+				"pi-mailbridge: not authorised yet — run `pi-mailbridge --auth` once to approve device login, or set mail.*.tokenCommand",
+			)
+		}
+
+		try {
+			const refreshed = await client.refresh(stored.refreshToken)
+			cached = refreshed
+			store.write({
+				...(refreshed.refreshToken ? { refreshToken: refreshed.refreshToken } : { refreshToken: stored.refreshToken }),
+				accessToken: refreshed.accessToken,
+				expiresAt: refreshed.expiresAt,
+			})
+			failures = 0
+			return refreshed.accessToken
+		} catch (error) {
+			failures++
+			// A revoked grant is permanent: say so now. A network failure is not - disabling
+			// on the first DNS blip stopped every notification until a human restarted pi.
+			const fatal = isCredentialError(error) || failures >= MAX_REFRESH_FAILURES
+			if (fatal) disabled = true
+			const reason = error instanceof Error ? error.message : String(error)
+			const suffix = fatal
+				? " — re-run `pi-mailbridge --auth`"
+				: ` — retrying on next use (${failures}/${MAX_REFRESH_FAILURES})`
+			throw new Error(`pi-mailbridge: OAuth2 token refresh failed: ${reason}${suffix}`)
+		}
+	}
+
+	return {
+		async getToken() {
+			if (cached && fresh(cached)) return cached.accessToken
+			if (disabled) {
+				throw new Error(
+					`pi-mailbridge: OAuth2 is disabled after ${failures} failure(s) — re-run \`pi-mailbridge --auth\``,
+				)
+			}
+			if (!inFlight) {
+				inFlight = acquire().finally(() => {
+					inFlight = undefined
+				})
+			}
+			return inFlight
+		},
+
+		invalidate() {
+			cached = undefined
+			const stored = store.read()
+			if (stored) store.write({ ...stored, accessToken: undefined, expiresAt: undefined })
+		},
+
+		isDisabled() {
+			return disabled
+		},
+
+		state() {
+			return { cached: Boolean(cached && fresh(cached)), disabled, failures }
+		},
+
+		async login() {
+			const authorization = await client.deviceAuthorization()
+			const tokens = await client.pollDeviceAuthorization()
+			if (!tokens.refreshToken) {
+				throw new Error(
+					"pi-mailbridge: the provider returned no refresh_token — make sure `offline_access` is in oauth.scope",
+				)
+			}
+			cached = tokens
+			store.write({ refreshToken: tokens.refreshToken, accessToken: tokens.accessToken, expiresAt: tokens.expiresAt })
+			return authorization
+		},
+	}
+}

package/src/core/oauth-openid.ts

@@ -0,0 +1,61 @@
+// openid-client adapter.
+//
+// The one place that knows the OAuth library's API. Types are derived from the
+// library itself (`Awaited<ReturnType<...>>`) so a major bump fails the build here
+// rather than producing silently wrong field names.
+
+import * as oidc from "openid-client"
+
+import type { DeviceAuthorization, OAuthClient, OAuthConfig, OAuthTokens } from "./oauth-device.ts"
+
+type DeviceResponse = Awaited<ReturnType<typeof oidc.initiateDeviceAuthorization>>
+type TokenResponse = Awaited<ReturnType<typeof oidc.pollDeviceAuthorizationGrant>>
+
+/** Map an OAuth token response onto our shape. */
+export function toOAuthTokens(tokens: TokenResponse, now: number = Date.now()): OAuthTokens {
+	const lifetime = typeof tokens.expires_in === "number" ? tokens.expires_in : 3600
+	return {
+		accessToken: tokens.access_token,
+		...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+		expiresAt: now + lifetime * 1000,
+	}
+}
+
+/** Human-facing part of a device authorization response. */
+export function toDeviceAuthorization(response: DeviceResponse): DeviceAuthorization {
+	return {
+		// Prefer the combined URL when the provider offers one: fewer typos.
+		verificationUri: response.verification_uri_complete ?? response.verification_uri,
+		userCode: response.user_code,
+	}
+}
+
+/**
+ * Build a real OAuth client for `config`.
+ * Async because discovery fetches the provider metadata.
+ */
+export async function createOpenidClient(config: OAuthConfig, now: () => number = Date.now): Promise<OAuthClient> {
+	const issuer = new URL(config.issuer)
+	const configuration = await oidc.discovery(issuer, config.clientId, config.clientSecret)
+
+	let pending: DeviceResponse | undefined
+
+	return {
+		async deviceAuthorization() {
+			pending = await oidc.initiateDeviceAuthorization(configuration, { scope: config.scope })
+			return toDeviceAuthorization(pending)
+		},
+
+		async pollDeviceAuthorization() {
+			if (!pending) throw new Error("pi-mailbridge: deviceAuthorization() must run before polling")
+			const tokens = await oidc.pollDeviceAuthorizationGrant(configuration, pending)
+			return toOAuthTokens(tokens, now())
+		},
+
+		async refresh(refreshToken: string) {
+			const tokens = await oidc.refreshTokenGrant(configuration, refreshToken)
+			return toOAuthTokens(tokens, now())
+		},
+	}
+}
+

package/src/core/oauth.ts

@@ -0,0 +1,182 @@
+// OAuth2 access-token supply for XOAUTH2 (Outlook).
+//
+// Microsoft retired SMTP basic auth for outlook.com/hotmail on 2024-09-16, so an
+// app password is not an option there. Two flows are built in - device code
+// (oauth-device.ts) and OpenID Connect (oauth-openid.ts) - and token acquisition can also
+// be delegated to a configurable command whose stdout is the token. This module is the
+// caching/retry layer shared by all three.
+//
+// Two design rules:
+//   1. The command is executed with `execFile` and an argv array — never a shell
+//      — so a token or a path containing shell metacharacters cannot be
+//      reinterpreted as syntax.
+//   2. A broken command disables the provider instead of being retried forever.
+//      The daemon would otherwise spawn a failing process on every scan.
+
+import { execFile } from "node:child_process"
+
+export interface ExecResult {
+	stdout: string
+}
+
+export type ExecFileLike = (file: string, args: string[]) => Promise<ExecResult>
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+/** Default executor: argv only, bounded output, hard timeout. */
+export const defaultExec: ExecFileLike = (file, args) =>
+	new Promise((resolve, reject) => {
+		execFile(file, args, { timeout: DEFAULT_TIMEOUT_MS, maxBuffer: 1 << 20, shell: false }, (error, stdout) => {
+			if (error) {
+				reject(error)
+				return
+			}
+			resolve({ stdout: stdout.toString() })
+		})
+	})
+
+export interface TokenProvider {
+	/** Current access token, fetching only when stale. */
+	getToken(): Promise<string>
+	/** Force the next getToken() to re-run the command (after a 401). */
+	invalidate(): void
+	/** True once the command has failed past the retry budget. */
+	isDisabled(): boolean
+	/** Diagnostics for `/mailbridge`: never the token itself. */
+	state(): { cached: boolean; disabled: boolean; failures: number }
+}
+
+export interface CommandTokenProviderOptions {
+	/** argv; argv[0] is the executable. */
+	command: readonly string[]
+	exec?: ExecFileLike
+	now?: () => number
+	/** How long a fetched token is considered fresh. Default 50 minutes. */
+	ttlMs?: number
+	/** Consecutive failures allowed before disabling. Default 3. */
+	maxConsecutiveFailures?: number
+}
+
+const DEFAULT_TTL_MS = 50 * 60 * 1000
+
+export function createCommandTokenProvider(options: CommandTokenProviderOptions): TokenProvider {
+	const { command } = options
+	const exec = options.exec ?? defaultExec
+	const now = options.now ?? (() => Date.now())
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+	// "A broken command should not be retried forever" is right; disabling after ONE failure
+	// is not - a DNS blip or a momentary exec failure then stops all mail until a restart.
+	// Three consecutive failures is still quick to notice and survives a transient one.
+	const maxFailures = options.maxConsecutiveFailures ?? 3
+
+	let token: string | undefined
+	let fetchedAt = 0
+	let failures = 0
+	let disabled = false
+	let inFlight: Promise<string> | undefined
+
+	function describeCommand(): string {
+		// Only argv[0]; later args may contain secrets (client ids, paths).
+		return command[0] ? `${command[0]} …` : "(empty command)"
+	}
+
+	async function fetchToken(): Promise<string> {
+		if (!command.length) {
+			disabled = true
+			throw new Error("pi-mailbridge: mail.smtp.tokenCommand is empty but authType is XOAUTH2")
+		}
+		try {
+			const { stdout } = await exec(command[0]!, command.slice(1))
+			const value = stdout.trim().split(/\r?\n/).pop()?.trim() ?? ""
+			if (!value) throw new Error("command produced no output")
+			failures = 0
+			token = value
+			fetchedAt = now()
+			return value
+		} catch (error) {
+			failures++
+			if (failures >= maxFailures) disabled = true
+			// Node's execFile message is "Command failed: <file> <all args>\n<stderr>", and the
+			// argv tail is exactly what describeCommand() refuses to print because it may hold a
+			// client secret. Keep the exit shape, drop the rest.
+			const reason = (() => {
+				const raw = error instanceof Error ? error.message : String(error)
+				const code = (error as NodeJS.ErrnoException | undefined)?.code
+				const firstLine = raw.split("\n")[0] ?? ""
+				const withoutArgv = firstLine.replace(/^Command failed: .*$/i, "command failed")
+				const stderr = raw.split("\n").slice(1).join(" ").trim()
+				const detail = stderr ? `${withoutArgv}: ${stderr.slice(0, 200)}` : withoutArgv
+				return code && !detail.includes(code) ? `${detail} (${code})` : detail
+			})()
+			const suffix = disabled
+				? " — OAuth2 is now disabled for this session; fix mail.smtp.tokenCommand and restart"
+				: ` — will retry on next use (${failures}/${maxFailures})`
+			throw new Error(`pi-mailbridge: OAuth2 token command failed (${describeCommand()}): ${reason}${suffix}`)
+		}
+	}
+
+	return {
+		async getToken() {
+			if (disabled) {
+				throw new Error(
+					`pi-mailbridge: OAuth2 token provider disabled after ${failures} failure(s) (${describeCommand()}); re-authenticate and restart`,
+				)
+			}
+			if (token && now() - fetchedAt < ttlMs) return token
+			// Collapse concurrent callers onto one exec.
+			if (!inFlight) {
+				inFlight = fetchToken().finally(() => {
+					inFlight = undefined
+				})
+			}
+			return inFlight
+		},
+
+		invalidate() {
+			token = undefined
+			fetchedAt = 0
+		},
+
+		isDisabled() {
+			return disabled
+		},
+
+		state() {
+			return { cached: token !== undefined && now() - fetchedAt < ttlMs, disabled, failures }
+		},
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Auth-failure detection + one-shot refresh
+// ---------------------------------------------------------------------------
+
+/** SMTP/IMAP auth failures as surfacing from the transport or a provider API. */
+const AUTH_ERROR_RE = /(\b401\b|\b535\b|\b534\b|invalid.?credentials?|InvalidAuthenticationToken|AUTHENTICATIONFAILED|token.?(expired|invalid))/i
+
+export function isAuthError(error: unknown): boolean {
+	const text = error instanceof Error ? `${error.name} ${error.message}` : String(error)
+	return AUTH_ERROR_RE.test(text)
+}
+
+/**
+ * Run `use(token)`; on an auth error invalidate and retry exactly once.
+ *
+ * One retry, not a loop: a second failure means the credential is genuinely bad,
+ * and retrying forever would hammer the provider and get the account locked.
+ */
+export async function withFreshToken<T>(
+	provider: TokenProvider,
+	use: (accessToken: string) => Promise<T>,
+	isAuth: (error: unknown) => boolean = isAuthError,
+): Promise<T> {
+	const first = await provider.getToken()
+	try {
+		return await use(first)
+	} catch (error) {
+		if (!isAuth(error)) throw error
+		provider.invalidate()
+		const second = await provider.getToken()
+		return use(second)
+	}
+}

package/src/core/prime.ts

@@ -0,0 +1,74 @@
+// "Watch from now on": skip the mail that is already in the mailbox.
+//
+// This is a first-run decision, not an operation. The scanner polls `UID <cursor>+1:*`, so
+// moving the cursor past unscanned mail makes it permanently invisible to the bridge: no
+// ack, no `\Seen`, no error - just a reply nobody ever answers. That is only possible when a
+// cursor already exists, which is why priming refuses to run a second time (a `/mailbridge
+// on` that processes what arrived meanwhile depends on that cursor staying put).
+//
+// Both the CLI (`--prime`) and the in-pi command go through here, so the two cannot disagree
+// about when it is allowed.
+
+import type { ResolvedConfig } from "./config.ts"
+
+export type PrimePlan =
+	| { ok: false; currentUid: number }
+	| { ok: true; highest: number; count: number; currentUid: number }
+
+/**
+ * Decide whether to prime, given the stored cursor and the mailbox's UIDs.
+ *
+ * Pure: the callers do the IMAP work, so the rule is testable without a server.
+ */
+export function planPrime(currentUid: number, uids: readonly number[], alreadyWatching: boolean): PrimePlan {
+	// Neither "the file exists" nor "uid > 0" answers this on its own. The daemon writes the file
+	// on its first connect, before reading anything (a fresh install wants prime); a renumbering
+	// resets the uid to 0 while the mailbox is already being watched (prime would skip exactly
+	// the mail the reset was meant to re-read). The caller passes a flag set by prime itself.
+	if (alreadyWatching) return { ok: false, currentUid }
+	const highest = uids.length > 0 ? Math.max(...uids) : 0
+	return { ok: true, highest, count: uids.length, currentUid }
+}
+
+/** The message shown when priming is refused, in both surfaces. */
+export function alreadyPrimedMessage(currentUid: number): string {
+	return (
+		`already watching from uid ${currentUid} - prime is a first-run step, and moving the cursor ` +
+		`now would skip any reply that arrived while the bridge was not scanning. ` +
+		`To re-prime deliberately, remove uid-cursor.json from the state directory.`
+	)
+}
+
+export interface PrimeDeps {
+	/** Injected so the two surfaces can share this without importing each other's plumbing. */
+	openMailbox: (config: ResolvedConfig) => Promise<{
+		search: () => Promise<number[]>
+		close: () => Promise<void>
+	}>
+	readCursor: () => number
+	/** Whether this mailbox is already being watched; see isPrimed. */
+	isPrimed: () => boolean
+	/** Record that prime ran, so the next attempt refuses. */
+	markPrimed: () => void
+	advanceCursor: (uid: number) => void
+}
+
+/**
+ * Run the check, and only touch the cursor when the plan allows it.
+ *
+ * The mailbox is still searched when priming is refused: the count is what makes the refusal
+ * concrete ("3 messages are in that range"), and a search is cheap.
+ */
+export async function runPrime(config: ResolvedConfig, deps: PrimeDeps): Promise<PrimePlan> {
+	const mailbox = await deps.openMailbox(config)
+	try {
+		const plan = planPrime(deps.readCursor(), await mailbox.search(), deps.isPrimed())
+		if (plan.ok) {
+			deps.advanceCursor(plan.highest)
+			deps.markPrimed()
+		}
+		return plan
+	} finally {
+		await mailbox.close().catch(() => undefined)
+	}
+}