kennel 0.2.1 → 0.2.2

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

@@ -0,0 +1,137 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference -- ambient bun:ffi types for out-of-package consumers (packages/api compiles this file)
+/// <reference path="./bun-ffi.d.ts" />
+import { closeSync, constants, openSync } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { dirname, resolve } from "node:path"
+
+/**
+ * Real POSIX advisory lock via `flock(2)` on MailOS-compatible lock files.
+ *
+ * MailOS (`emailos/internal/core/drafts.go` `withLocalDraftLock`) serializes
+ * draft mutations with an exclusive `flock` on `<draftDir>/.locks/<base>.lock`
+ * opened `O_CREATE|O_RDWR`. Kennel takes the *same* lock so destructive
+ * actions (delete/archive critical sections) coordinate with the MailOS
+ * binary itself, not just with other Kennel processes.
+ *
+ * Portability: `flock(2)` is reached through two supported FFI backends —
+ * `bun:ffi` when the process runs on Bun (the test runner), and the `koffi`
+ * N-API binding when it runs on Node (the Vite dev server / build). Both call
+ * the exact same libc symbol on the exact same lock files, so coordination
+ * holds across runtimes and against the Go MailOS binary. The wait is
+ * bounded so an abandoned holder cannot hang a server request forever.
+ */
+export class FlockTimeoutError extends Error {
+  readonly lockPath: string
+
+  constructor(lockPath: string, timeoutMs: number) {
+    super(
+      `Timed out after ${timeoutMs}ms waiting for the draft lock ${resolve(lockPath)}`,
+    )
+    this.name = "FlockTimeoutError"
+    this.lockPath = resolve(lockPath)
+  }
+}
+
+const LOCK_EX = 2
+const LOCK_NB = 4
+const LOCK_UN = 8
+const EINTR = 4
+const EWOULDBLOCK_DARWIN = 35
+const EWOULDBLOCK_LINUX = 11
+
+type FlockFn = (fd: number, operation: number) => number
+
+type FlockBackend = {
+  flock: FlockFn
+  /** Returns the last libc errno; only used on Node (koffi exposes it). */
+  errno: () => number
+}
+
+function isBunRuntime() {
+  return (
+    typeof process !== "undefined" &&
+    typeof process.versions !== "undefined" &&
+    "bun" in process.versions
+  )
+}
+
+const libcPath =
+  process.platform === "darwin" ? "/usr/lib/libSystem.B.dylib" : "libc.so.6"
+
+let backendPromise: Promise<FlockBackend> | null = null
+
+async function loadBackend(): Promise<FlockBackend> {
+  backendPromise ??= (async () => {
+    if (isBunRuntime()) {
+      // bun:ffi does not surface errno; a non-zero flock result on the just
+      // opened descriptor is treated as "held elsewhere" (would-block /
+      // EINTR) and retried until the bounded deadline, which is the only
+      // realistic outcome for a valid descriptor.
+      const { dlopen } = await import("bun:ffi")
+      const libc = dlopen(libcPath, {
+        flock: { args: ["int", "int"], returns: "int" },
+      })
+      return { flock: libc.symbols.flock as FlockFn, errno: () => 0 }
+    }
+    // Node: koffi exposes libc errno so would-block/EINTR can be told
+    // apart from a real locking error.
+    const koffi = (await import("koffi")).default
+    const libc = koffi.load(libcPath)
+    return {
+      flock: libc.func("int flock(int fd, int operation)"),
+      errno: koffi.errno,
+    }
+  })()
+  return backendPromise
+}
+
+const wouldBlockErrno =
+  process.platform === "darwin" ? EWOULDBLOCK_DARWIN : EWOULDBLOCK_LINUX
+
+function sleep(ms: number) {
+  return new Promise((resolveSleep) => {
+    setTimeout(resolveSleep, ms)
+  })
+}
+
+/**
+ * Run `action` while holding an exclusive `flock` on `lockPath`. The file is
+ * opened `O_RDWR|O_CREAT` (mode `0600`) exactly like MailOS; the lock is
+ * released (and the descriptor closed) before `withFlock` resolves, so a
+ * crash never leaves a stale advisory lock behind.
+ */
+export async function withFlock<T>(
+  lockPath: string,
+  timeoutMs: number,
+  action: () => Promise<T>,
+): Promise<T> {
+  const resolved = resolve(lockPath)
+  // MailOS creates the lock directory with `os.MkdirAll(lockDir, 0o700)`.
+  await mkdir(dirname(resolved), { mode: 0o700, recursive: true }).catch(
+    () => undefined,
+  )
+  const { flock, errno } = await loadBackend()
+  const fd = openSync(resolved, constants.O_RDWR | constants.O_CREAT, 0o600)
+  try {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      if (flock(fd, LOCK_EX | LOCK_NB) === 0) break
+      const code = errno()
+      if (code !== 0 && code !== EINTR && code !== wouldBlockErrno) {
+        throw new Error(`flock failed on ${resolved} (errno ${code})`)
+      }
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) {
+        throw new FlockTimeoutError(resolved, timeoutMs)
+      }
+      await sleep(Math.min(50, remaining))
+    }
+    return await action()
+  } finally {
+    try {
+      flock(fd, LOCK_UN)
+    } finally {
+      closeSync(fd)
+    }
+  }
+}

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

@@ -0,0 +1,37 @@
+import type { FolderFilterChoice } from "@raggle-ai/ui/lib/folder-filter"
+import {
+  folderFilterChoices,
+  folderFilterLabel,
+} from "@raggle-ai/ui/lib/folder-filter"
+
+export type MailFolderChoice = FolderFilterChoice
+
+/**
+ * Display text for a draft's owning folder relative to the viewed root:
+ * basename for root-owned drafts ("example-workspace"), relative path for
+ * descendants ("clients/client-one"). Null when the draft has no folder or it
+ * does not live under the viewed root.
+ *
+ * Delegates to the shared folder-filter lib.
+ */
+export function folderLabel(
+  folder: string | null,
+  rootFolder: string,
+): string | null {
+  return folderFilterLabel(folder, rootFolder)
+}
+
+/**
+ * Exact owning-folder choices with per-draft counts for filtering the mail
+ * list. Keyed by the full folder path so duplicate leaf names stay
+ * distinct; ordered with the root folder first, then descendants
+ * alphabetically by relative path.
+ *
+ * Delegates to the shared folder-filter lib.
+ */
+export function folderChoices(
+  items: readonly { folder: string | null }[],
+  rootFolder: string,
+): MailFolderChoice[] {
+  return folderFilterChoices(items, rootFolder, (item) => item.folder)
+}

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

@@ -0,0 +1,485 @@
+import { createHash } from "node:crypto"
+import {
+  lstat,
+  mkdir,
+  readFile,
+  realpath,
+  rename,
+  unlink,
+  writeFile,
+} from "node:fs/promises"
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+
+import { FlockTimeoutError, withFlock } from "./flock.ts"
+import { parseMailMarkdown } from "./parse.ts"
+
+export type DraftIdentity = {
+  id: string
+  filePath: string
+  folder: string | null
+  /** sha256 of the draft bytes the client last loaded. */
+  revision: string
+}
+
+export type DeleteOutcome = "deleted" | "changed" | "missing" | "invalid"
+
+export class MailDeleteError extends Error {
+  readonly outcome: DeleteOutcome
+
+  constructor(outcome: DeleteOutcome, message: string) {
+    super(message)
+    this.name = "MailDeleteError"
+    this.outcome = outcome
+  }
+}
+
+/**
+ * How long delete waits for the MailOS-compatible flock before giving up.
+ * MailOS blocks indefinitely; Kennel bounds the wait so an abandoned holder
+ * cannot hang a request, and reports the result as a conflict instead.
+ */
+export const deleteLockTimeoutMs = 30_000
+
+function validDraftId(id: string) {
+  const trimmed = id.trim()
+  return (
+    Boolean(trimmed) &&
+    trimmed !== "." &&
+    trimmed !== ".." &&
+    !/[\\/]/.test(trimmed)
+  )
+}
+
+function draftRevision(content: string) {
+  return createHash("sha256").update(content).digest("hex")
+}
+
+/**
+ * Walk `childPath` (which must be inside canonical `anchor`) and make sure
+ * every existing component is a real directory — never a symlink —
+ * creating missing components ourselves. This closes the history/locks
+ * directory symlink-escape: a planted `history`, `<id>`, or `.locks` symlink
+ * is rejected instead of followed.
+ */
+async function ensureRealDirChain(
+  anchor: string,
+  childPath: string,
+): Promise<void> {
+  const rel = relative(anchor, childPath)
+  if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new MailDeleteError(
+      "invalid",
+      "Lock/history path escapes the mail folder",
+    )
+  }
+  let current = anchor
+  for (const segment of rel.split(sep)) {
+    if (!segment) continue
+    current = resolve(current, segment)
+    let info = await lstat(current).catch(() => undefined)
+    if (!info) {
+      await mkdir(current, { mode: 0o700 }).catch(() => undefined)
+      info = await lstat(current).catch(() => undefined)
+      if (!info || info.isSymbolicLink() || !info.isDirectory()) {
+        throw new MailDeleteError(
+          "invalid",
+          "Could not create a real directory for the draft lock/history",
+        )
+      }
+      continue
+    }
+    if (info.isSymbolicLink() || !info.isDirectory()) {
+      throw new MailDeleteError(
+        "invalid",
+        "Draft lock/history path must use real directories (no symlinked components)",
+      )
+    }
+  }
+}
+
+/**
+ * Delete a local draft with a byte-exact, verified history snapshot, under
+ * the real MailOS advisory lock.
+ *
+ * Locking — `withFlock` takes the exclusive `flock(2)` on
+ * `<mailDir>/.locks/<id>.md.lock`, the exact file MailOS holds
+ * (`emailos/internal/core/drafts.go withLocalDraftLock`) while it
+ * snapshots/updates/sends a draft. Kennel's delete/archive critical section
+ * therefore serializes against the MailOS binary itself, not only against
+ * other Kennel processes.
+ *
+ * Byte-level guarantees (inside the lock):
+ * - the draft file's current bytes must still hash to the revision the client
+ *   loaded, or the delete is refused ("changed") and newer work survives;
+ * - the snapshot written to history/<id>/<revision>.md is byte-identical to
+ *   the draft content (temp sibling + rename + verified re-read/hash);
+ * - pre-existing history is verified byte-for-byte first — corrupt existing
+ *   history is never overwritten or deleted, and the draft is left in place;
+ * - the draft is re-read and re-hashed immediately before the unlink, and its
+ *   realpath re-verified, so the final unlink only ever removes the exact
+ *   file whose bytes matched the loaded revision at that moment.
+ *
+ * Exact guarantee (limitation): a non-cooperating writer that does not take
+ * the flock and rewrites the file *after* the final re-read but *before* the
+ * unlink can still have newer work deleted — the same two-instruction window
+ * MailOS itself has between its locked re-read and remove. No filesystem API
+ * can make a byte-compare-and-unlink atomic; the flock + closing re-read +
+ * realpath re-check reduce this to the unavoidable sub-microsecond window,
+ * and cooperative writers (Kennel, MailOS send/archive/snapshot) are fully
+ * serialized.
+ */
+export async function deleteLocalDraftVerified(
+  mail: DraftIdentity,
+  mailDir: string,
+): Promise<"deleted"> {
+  if (!validDraftId(mail.id)) {
+    throw new MailDeleteError("invalid", "Invalid mail id")
+  }
+  const mailDirReal = await realpath(resolve(mailDir))
+  const target = resolve(mail.filePath)
+  const targetDir = await realpath(dirname(target)).catch(() => null)
+  if (targetDir !== mailDirReal) {
+    throw new MailDeleteError(
+      "invalid",
+      "Draft path is outside the mail folder",
+    )
+  }
+  // The draft file itself must be the plain expected file: a symlink that
+  // realpaths somewhere else is rejected rather than followed.
+  const expected = resolve(mailDirReal, `${mail.id.trim()}.md`)
+  const targetReal = await realpath(target).catch(() => null)
+  if (targetReal === null) {
+    throw new MailDeleteError("missing", "Draft no longer exists")
+  }
+  if (targetReal !== expected) {
+    throw new MailDeleteError(
+      "invalid",
+      "Draft path is not a direct file in the mail folder",
+    )
+  }
+
+  if (!/^[a-f0-9]{64}$/i.test(mail.revision)) {
+    throw new MailDeleteError("invalid", "Invalid draft revision")
+  }
+
+  const locksDir = resolve(mailDirReal, ".locks")
+  await ensureRealDirChain(mailDirReal, locksDir)
+  const lockPath = resolve(locksDir, `${mail.id.trim()}.md.lock`)
+
+  try {
+    return await withFlock(lockPath, deleteLockTimeoutMs, async () => {
+      // Under the lock: the re-read, the hash, the snapshot, the re-verify
+      // and the unlink are one critical section.
+      const content = await readFile(target, "utf8").catch(() => null)
+      if (content === null) {
+        throw new MailDeleteError("missing", "Draft no longer exists")
+      }
+      if (draftRevision(content) !== mail.revision.toLowerCase()) {
+        throw new MailDeleteError(
+          "changed",
+          "Draft changed since it was loaded; refusing to delete newer work",
+        )
+      }
+
+      const historyDir = resolve(mailDirReal, "history", mail.id)
+      await ensureRealDirChain(mailDirReal, historyDir)
+      const historyPath = resolve(historyDir, `${mail.revision}.md`)
+
+      const existingLstat = await lstat(historyPath).catch(() => undefined)
+      if (existingLstat?.isSymbolicLink()) {
+        throw new MailDeleteError(
+          "invalid",
+          "History snapshot path is a symlink; refusing to touch it",
+        )
+      }
+      const existing = existingLstat ?? undefined
+      if (existing?.isFile()) {
+        // Never overwrite or trust an existing snapshot: verify its bytes
+        // still hash to the revision, exactly like MailOS
+        // (readVerifiedLocalDraftRevisionForPath). A corrupt existing history
+        // blocks the delete rather than being clobbered.
+        const existingContent = await readFile(historyPath, "utf8").catch(
+          () => null,
+        )
+        if (
+          existingContent === null ||
+          draftRevision(existingContent) !== mail.revision.toLowerCase()
+        ) {
+          throw new MailDeleteError(
+            "changed",
+            "Existing draft history does not match this revision; refusing to delete",
+          )
+        }
+      } else if (existing) {
+        throw new MailDeleteError(
+          "invalid",
+          "History snapshot path is not a regular file",
+        )
+      } else {
+        // Write to a temp sibling then rename so a crash never leaves a
+        // partial snapshot under the revision name. "wx" refuses to follow or
+        // overwrite a planted temp symlink.
+        const tempPath = resolve(historyDir, `${mail.revision}.md.tmp`)
+        for (let attempt = 0; ; attempt += 1) {
+          try {
+            await writeFile(tempPath, content, { flag: "wx", mode: 0o600 })
+            break
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error
+            const tempInfo = await lstat(tempPath).catch(() => undefined)
+            if (attempt === 0 && tempInfo?.isFile()) {
+              // A stale temp from an interrupted run: remove and write once
+              // more. A symlink/directory is never followed.
+              await unlink(tempPath)
+              continue
+            }
+            throw new MailDeleteError(
+              "invalid",
+              "Temp snapshot path is not a plain file; refusing to write through it",
+            )
+          }
+        }
+        const written = await readFile(tempPath, "utf8").catch(() => null)
+        if (
+          written !== content ||
+          draftRevision(written ?? "") !== mail.revision.toLowerCase()
+        ) {
+          throw new MailDeleteError(
+            "changed",
+            "Draft changed while snapshotting; refusing to delete",
+          )
+        }
+        await rename(tempPath, historyPath)
+      }
+
+      // Re-verify the draft is byte-identical to the snapshot immediately
+      // before unlinking, and that it is still the same regular file; an
+      // editor or symlink that raced in is left untouched.
+      const current = await readFile(target, "utf8").catch(() => null)
+      if (current === null) {
+        throw new MailDeleteError("missing", "Draft no longer exists")
+      }
+      if (draftRevision(current) !== mail.revision.toLowerCase()) {
+        throw new MailDeleteError(
+          "changed",
+          "Draft changed since it was loaded; refusing to delete newer work",
+        )
+      }
+      const finalReal = await realpath(target).catch(() => null)
+      if (finalReal !== expected) {
+        throw new MailDeleteError(
+          "invalid",
+          "Draft path changed identity before deletion; refusing to unlink",
+        )
+      }
+
+      await unlink(target)
+      return "deleted" as const
+    })
+  } catch (error) {
+    if (error instanceof FlockTimeoutError) {
+      throw new MailDeleteError(
+        "changed",
+        "Draft is locked by another process (MailOS or another delete); try again",
+      )
+    }
+    throw error
+  }
+}
+
+export type AttachmentRemoveOutcome =
+  "removed" | "changed" | "missing" | "invalid"
+
+export class MailAttachmentError extends Error {
+  readonly outcome: AttachmentRemoveOutcome
+
+  constructor(outcome: AttachmentRemoveOutcome, message: string) {
+    super(message)
+    this.name = "MailAttachmentError"
+    this.outcome = outcome
+  }
+}
+
+/**
+ * Rewrite the frontmatter `file:` block in place: drop the given attachment
+ * path and bump `updated_at`. Key order, quoting, and all other lines stay
+ * byte-identical, so MailOS reads the file exactly as before with one fewer
+ * linked file. Returns null when there is no `file:` key.
+ */
+function rewriteFileFrontmatter(
+  frontmatterRaw: string,
+  remaining: string[],
+  updatedAt: string,
+): string | null {
+  const lines = frontmatterRaw.split("\n")
+  const fileIndex = lines.findIndex((line) => /^file:/.test(line))
+  if (fileIndex < 0) return null
+
+  // Eat the block-list item lines directly below an empty `file:` key.
+  let end = fileIndex + 1
+  if ((lines[fileIndex] ?? "").trim() === "file:") {
+    while (end < lines.length) {
+      if (!/^\s+- /.test(lines[end] ?? "")) break
+      end += 1
+    }
+  }
+
+  const fileBlock = remaining.length
+    ? ["file:", ...remaining.map((path) => `  - ${JSON.stringify(path)}`)]
+    : ["file: []"]
+  lines.splice(fileIndex, end - fileIndex, ...fileBlock)
+
+  const updatedIndex = lines.findIndex((line) => /^updated_at:/.test(line))
+  if (updatedIndex >= 0) {
+    lines[updatedIndex] = `updated_at: ${JSON.stringify(updatedAt)}`
+  }
+
+  return lines.join("\n")
+}
+
+/**
+ * Remove one attachment path from a local draft's frontmatter `file:` list.
+ * Mirrors deleteLocalDraftVerified's safety pattern: the draft must be a real
+ * file in the mail folder, the edit runs under the same MailOS-compatible
+ * flock with a byte-exact revision guard, the rewritten file is written to a
+ * temp sibling and atomically renamed, and `updated_at` is bumped. The
+ * attachment file itself is never touched — only the link in the draft.
+ * Returns the new draft revision so callers can continue against fresh data.
+ */
+export async function removeDraftAttachmentVerified(
+  mail: DraftIdentity,
+  mailDir: string,
+  attachment: string,
+): Promise<{ revision: string }> {
+  if (!validDraftId(mail.id)) {
+    throw new MailAttachmentError("invalid", "Invalid mail id")
+  }
+  const mailDirReal = await realpath(resolve(mailDir))
+  const target = resolve(mail.filePath)
+  const targetDir = await realpath(dirname(target)).catch(() => null)
+  if (targetDir !== mailDirReal) {
+    throw new MailAttachmentError(
+      "invalid",
+      "Draft path is outside the mail folder",
+    )
+  }
+  const expected = resolve(mailDirReal, `${mail.id.trim()}.md`)
+  const targetReal = await realpath(target).catch(() => null)
+  if (targetReal === null) {
+    throw new MailAttachmentError("missing", "Draft no longer exists")
+  }
+  if (targetReal !== expected) {
+    throw new MailAttachmentError(
+      "invalid",
+      "Draft path is not a direct file in the mail folder",
+    )
+  }
+  if (!/^[a-f0-9]{64}$/i.test(mail.revision)) {
+    throw new MailAttachmentError("invalid", "Invalid draft revision")
+  }
+
+  const locksDir = resolve(mailDirReal, ".locks")
+  await ensureRealDirChain(mailDirReal, locksDir)
+  const lockPath = resolve(locksDir, `${mail.id.trim()}.md.lock`)
+
+  try {
+    return await withFlock(lockPath, deleteLockTimeoutMs, async () => {
+      const revision = mail.revision.toLowerCase()
+      const content = await readFile(target, "utf8").catch(() => null)
+      if (content === null) {
+        throw new MailAttachmentError("missing", "Draft no longer exists")
+      }
+      if (draftRevision(content) !== revision) {
+        throw new MailAttachmentError(
+          "changed",
+          "Draft changed since it was loaded; refusing to edit",
+        )
+      }
+      if (!content.startsWith("---\n")) {
+        throw new MailAttachmentError("invalid", "Draft has no frontmatter")
+      }
+      const end = content.indexOf("\n---\n")
+      if (end < 0) {
+        throw new MailAttachmentError("invalid", "Draft has no frontmatter")
+      }
+
+      const parsed = parseMailMarkdown(content)
+      if (!parsed.attachments.includes(attachment)) {
+        throw new MailAttachmentError(
+          "missing",
+          "Attachment is not linked to this draft",
+        )
+      }
+      const remaining = parsed.attachments.filter((path) => path !== attachment)
+      const frontmatterRaw = content.slice(4, end)
+      const newFrontmatter = rewriteFileFrontmatter(
+        frontmatterRaw,
+        remaining,
+        new Date().toISOString(),
+      )
+      if (newFrontmatter === null) {
+        throw new MailAttachmentError(
+          "invalid",
+          "Draft frontmatter has no file list",
+        )
+      }
+      const newContent = `---\n${newFrontmatter}\n---\n${content.slice(
+        end + "\n---\n".length,
+      )}`
+
+      const tempPath = resolve(mailDirReal, `${mail.id.trim()}.md.tmp`)
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          await writeFile(tempPath, newContent, { flag: "wx", mode: 0o600 })
+          break
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error
+          const tempInfo = await lstat(tempPath).catch(() => undefined)
+          if (attempt === 0 && tempInfo?.isFile()) {
+            await unlink(tempPath)
+            continue
+          }
+          throw new MailAttachmentError(
+            "invalid",
+            "Temp draft path is not a plain file; refusing to write through it",
+          )
+        }
+      }
+      const written = await readFile(tempPath, "utf8").catch(() => null)
+      if (written !== newContent) {
+        throw new MailAttachmentError(
+          "changed",
+          "Draft changed while writing; refusing to save",
+        )
+      }
+
+      // The draft must still hash to the client's revision immediately
+      // before the rename, so a concurrent editor is never overwritten.
+      const current = await readFile(target, "utf8").catch(() => null)
+      if (current === null) {
+        throw new MailAttachmentError("missing", "Draft no longer exists")
+      }
+      if (draftRevision(current) !== revision) {
+        throw new MailAttachmentError(
+          "changed",
+          "Draft changed since it was loaded; refusing to edit",
+        )
+      }
+      await rename(tempPath, target)
+
+      return { revision: draftRevision(newContent) }
+    })
+  } catch (error) {
+    if (error instanceof FlockTimeoutError) {
+      throw new MailAttachmentError(
+        "changed",
+        "Draft is locked by another process (MailOS or another edit); try again",
+      )
+    }
+    throw error
+  }
+}
+
+export function historyDirFor(mail: DraftIdentity, mailDir: string) {
+  return resolve(resolve(mailDir), "history", mail.id)
+}

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

@@ -0,0 +1,3 @@
+export type { Mail, MailListItem, MailStatus } from "./parse.ts"
+export { mailExcerpt, parseMailMarkdown } from "./parse.ts"
+export type { MailPreview } from "./types.ts"