kennel 0.2.0 → 0.2.2

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

@@ -0,0 +1,7 @@
+import type { FolderPluginManifest } from "@raggle-ai/folder-plugin"
+
+/** Stable Mail plugin identity and navigation label. No side effects. */
+export const mailManifest: FolderPluginManifest = {
+  id: "mail",
+  label: "Mail",
+}

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

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto"
+import { realpathSync } from "node:fs"
+import { readdir, readFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { isAbsolute, relative, resolve, sep } from "node:path"
+
+import type { Mail, MailListItem } from "./parse.ts"
+import { mailExcerpt, parseMailMarkdown } from "./parse.ts"
+
+export type ListMailOptions = {
+  mailDir?: string
+  folder: string
+}
+
+export function defaultMailDir() {
+  return resolve(homedir(), ".email/drafts")
+}
+
+function draftFilePath(mailDir: string, id: string) {
+  const trimmed = id.trim()
+  if (
+    !trimmed ||
+    trimmed === "." ||
+    trimmed === ".." ||
+    /[\\/]/.test(trimmed)
+  ) {
+    throw new Error("Invalid mail id")
+  }
+  return resolve(mailDir, `${trimmed}.md`)
+}
+
+/**
+ * Drafts currently being worked on. MailOS keeps sent and archived drafts in
+ * the same folder, so the reader must exclude them here to show the same
+ * current draft set without invoking the MailOS binary.
+ */
+const activeStatuses = new Set(["working", "ready"])
+
+function isActiveStatus(status: string | null) {
+  return status !== null && activeStatuses.has(status)
+}
+
+function canonicalDraftPath(path: string): string | null {
+  try {
+    return realpathSync(resolve(path))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * True when `candidate` is `root` itself or a real descendant directory of
+ * `root`. Both paths must exist on disk and are resolved through realpath, so
+ * sibling-prefix paths, outside ancestors, traversal escapes, and symlink
+ * escapes are rejected; an unresolved (missing) folder is denied rather than
+ * guessed. Shared by list and detail authorization so draft membership is
+ * consistent everywhere.
+ */
+export function isFolderWithin(
+  root: string,
+  candidate: string | null | undefined,
+): boolean {
+  if (!candidate) return false
+  const anchor = canonicalDraftPath(root)
+  if (anchor === null) return false
+  const target = canonicalDraftPath(candidate)
+  if (target === null) return false
+  if (anchor === target) return true
+  const rel = relative(anchor, target)
+  if (!rel) return true
+  if (rel === ".." || rel.startsWith(`..${sep}`)) return false
+  return !isAbsolute(rel)
+}
+
+function sortDateKey(value: string | null) {
+  const parsed = value ? Date.parse(value) : Number.NaN
+  if (Number.isNaN(parsed)) return 0
+  return parsed
+}
+
+function sortMail(items: MailListItem[]) {
+  items.sort((a, b) => {
+    const aKey = sortDateKey(a.updatedAt ?? a.createdAt)
+    const bKey = sortDateKey(b.updatedAt ?? b.createdAt)
+    return bKey - aKey
+  })
+  return items
+}
+
+function draftRevision(content: string) {
+  return createHash("sha256").update(content).digest("hex")
+}
+
+async function mailFromFile(
+  filePath: string,
+): Promise<(Mail & { filePath: string; revision: string }) | null> {
+  const content = await readFile(filePath, "utf8").catch(() => null)
+  if (!content) return null
+  const parsed = parseMailMarkdown(content)
+  if (!parsed.id) return null
+  if (!isActiveStatus(parsed.status)) return null
+
+  return {
+    id: parsed.id,
+    status: parsed.status,
+    tags: parsed.tags,
+    folder: parsed.folder,
+    attachments: parsed.attachments,
+    from: parsed.from,
+    inReplyTo: parsed.inReplyTo,
+    references: parsed.references,
+    to: parsed.to,
+    cc: parsed.cc,
+    bcc: parsed.bcc,
+    subject: parsed.subject,
+    createdAt: parsed.createdAt,
+    updatedAt: parsed.updatedAt,
+    noSignature: parsed.noSignature,
+    body: parsed.body,
+    filePath,
+    revision: draftRevision(content),
+  }
+}
+
+export async function listMailForFolder({
+  mailDir = defaultMailDir(),
+  folder,
+}: ListMailOptions): Promise<MailListItem[]> {
+  const entries = await readdir(mailDir, { withFileTypes: true })
+  const items: MailListItem[] = []
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    if (!entry.name.endsWith(".md")) continue
+
+    const filePath = resolve(mailDir, entry.name)
+    const mail = await mailFromFile(filePath)
+    if (!mail) continue
+    if (!isFolderWithin(folder, mail.folder)) continue
+
+    items.push({
+      id: mail.id,
+      status: mail.status,
+      tags: mail.tags,
+      folder: mail.folder,
+      attachments: mail.attachments,
+      from: mail.from,
+      inReplyTo: mail.inReplyTo,
+      references: mail.references,
+      to: mail.to,
+      cc: mail.cc,
+      bcc: mail.bcc,
+      subject: mail.subject,
+      createdAt: mail.createdAt,
+      updatedAt: mail.updatedAt,
+      noSignature: mail.noSignature,
+      excerpt: mailExcerpt(mail.body),
+      filePath,
+      revision: mail.revision,
+    })
+  }
+
+  return sortMail(items)
+}
+
+export async function readMailById(
+  id: string,
+  mailDir = defaultMailDir(),
+): Promise<(Mail & { filePath: string; revision: string }) | null> {
+  return mailFromFile(draftFilePath(mailDir, id))
+}

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

@@ -0,0 +1,139 @@
+import { parse as parseYaml } from "yaml"
+
+export type MailStatus = "working" | "ready" | "sent" | "canceled" | string
+
+export type Mail = {
+  id: string
+  status: MailStatus | null
+  tags: string[]
+  folder: string | null
+  attachments: string[]
+  from: string | null
+  inReplyTo: string | null
+  references: string[]
+  to: string[]
+  cc: string[]
+  bcc: string[]
+  subject: string | null
+  createdAt: string | null
+  updatedAt: string | null
+  /** Draft frontmatter `no_signature: true`: suppresses any signature on send. */
+  noSignature: boolean
+  body: string
+}
+
+export type MailListItem = Omit<Mail, "body"> & {
+  excerpt: string
+  filePath: string
+  /**
+   * sha256 of the exact draft file bytes. MailOS treats this hash as the
+   * draft revision, so guarded destructive actions can prove the file has not
+   * changed since the client last loaded it.
+   */
+  revision: string
+}
+
+function stringOrNull(value: unknown) {
+  return typeof value === "string" && value.trim() ? value : null
+}
+
+function boolValue(value: unknown) {
+  return value === true || value === "true"
+}
+
+function stringList(value: unknown): string[] {
+  if (!value) return []
+  if (Array.isArray(value))
+    return value
+      .filter((item): item is string => typeof item === "string")
+      .map((item) => item.trim())
+      .filter(Boolean)
+  if (typeof value === "string") return value.trim() ? [value.trim()] : []
+  return []
+}
+
+export function parseMailMarkdown(content: string): Omit<Mail, "id"> & {
+  id: string | null
+} {
+  if (!content.startsWith("---\n")) {
+    return {
+      id: null,
+      status: null,
+      tags: [],
+      folder: null,
+      attachments: [],
+      from: null,
+      inReplyTo: null,
+      references: [],
+      to: [],
+      cc: [],
+      bcc: [],
+      subject: null,
+      createdAt: null,
+      updatedAt: null,
+      noSignature: false,
+      body: content,
+    }
+  }
+
+  const end = content.indexOf("\n---\n")
+  if (end < 0) {
+    return {
+      id: null,
+      status: null,
+      tags: [],
+      folder: null,
+      attachments: [],
+      from: null,
+      inReplyTo: null,
+      references: [],
+      to: [],
+      cc: [],
+      bcc: [],
+      subject: null,
+      createdAt: null,
+      updatedAt: null,
+      noSignature: false,
+      body: content,
+    }
+  }
+
+  const frontmatterRaw = content.slice(4, end)
+  const body = content.slice(end + "\n---\n".length).replace(/^\n+/, "")
+
+  const frontmatterValue = parseYaml(frontmatterRaw) as unknown
+  const frontmatter =
+    frontmatterValue &&
+    typeof frontmatterValue === "object" &&
+    !Array.isArray(frontmatterValue)
+      ? (frontmatterValue as Record<string, unknown>)
+      : {}
+
+  return {
+    id: stringOrNull(frontmatter.id),
+    status: stringOrNull(frontmatter.status),
+    tags: stringList(frontmatter.tags),
+    folder: stringOrNull(frontmatter.folder),
+    attachments: stringList(frontmatter.file),
+    from: stringOrNull(frontmatter.from),
+    inReplyTo: stringOrNull(frontmatter.in_reply_to),
+    references: stringList(frontmatter.references),
+    to: stringList(frontmatter.to),
+    cc: stringList(frontmatter.cc),
+    bcc: stringList(frontmatter.bcc),
+    subject: stringOrNull(frontmatter.subject),
+    createdAt: stringOrNull(frontmatter.created_at),
+    updatedAt: stringOrNull(frontmatter.updated_at),
+    noSignature: boolValue(frontmatter.no_signature),
+    body,
+  }
+}
+
+export function mailExcerpt(body: string, maxChars = 280) {
+  const normalized = body
+    .trim()
+    .replace(/\r\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+  if (normalized.length <= maxChars) return normalized
+  return `${normalized.slice(0, maxChars).trimEnd()}…`
+}

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

@@ -0,0 +1,125 @@
+import type {
+  FolderPluginContext,
+  FolderPluginData,
+  FolderPluginDetection,
+} from "@raggle-ai/folder-plugin/server"
+import { FolderPluginFailure } from "@raggle-ai/folder-plugin/server"
+
+import type { Mail, MailListItem } from "./parse.ts"
+import type { MailPreview } from "./types.ts"
+import { createMailosService } from "./mailos.ts"
+import { mailManifest } from "./manifest.ts"
+import {
+  defaultMailDir,
+  isFolderWithin,
+  listMailForFolder,
+  readMailById,
+} from "./node.ts"
+
+export type MailCreatePluginOptions = {
+  /**
+   * Override MailOS mail directory. Intended for tests.
+   * Defaults to ~/.email/drafts.
+   */
+  mailDir?: string
+  /** Preview execution hook. Fallback reads the draft body without a composer. */
+  previewer?: (options: {
+    folder: string
+    id: string
+    mail: NonNullable<Awaited<ReturnType<typeof readMailById>>>
+  }) => Promise<MailPreview>
+}
+
+type DetailMail = Mail & { filePath: string; revision: string }
+
+function detailData(mail: DetailMail, preview: MailPreview): FolderPluginData {
+  return {
+    kind: "available",
+    data: {
+      mail: {
+        ...mail,
+        bcc: mail.bcc,
+        body: mail.body,
+        cc: mail.cc,
+        createdAt: mail.createdAt,
+        filePath: mail.filePath,
+        folder: mail.folder,
+        id: mail.id,
+        status: mail.status,
+        subject: mail.subject,
+        tags: mail.tags,
+        to: mail.to,
+        updatedAt: mail.updatedAt,
+        noSignature: mail.noSignature,
+      },
+      preview,
+    },
+  }
+}
+
+export function createMailPlugin({
+  mailDir = defaultMailDir(),
+  previewer,
+}: MailCreatePluginOptions = {}) {
+  const mailos = createMailosService()
+  const compose =
+    previewer ??
+    (async ({ mail }) => ({
+      body: mail.body,
+      // A no_signature draft sends without any signature; do not show one.
+      signature: mail.noSignature
+        ? null
+        : mail.folder
+          ? await mailos.signature(mail.folder)
+          : null,
+    }))
+
+  return {
+    ...mailManifest,
+    async detect(context: FolderPluginContext): Promise<FolderPluginDetection> {
+      const items = await listMailForFolder({ folder: context.folder, mailDir })
+      if (!items.length) return { status: "unavailable" }
+      return { count: items.length, status: "available" }
+    },
+    async handle(
+      context: FolderPluginContext,
+      subpath: string,
+    ): Promise<FolderPluginData> {
+      const folder = context.folder
+
+      if (subpath === "") {
+        const items = await listMailForFolder({ folder, mailDir })
+        if (!items.length) {
+          return {
+            kind: "available",
+            data: { folder, items: [], status: "unavailable" },
+          }
+        }
+        return {
+          kind: "available",
+          data: { folder, items, status: "available" },
+        }
+      }
+
+      const id = subpath.trim()
+      const mail = await readMailById(id, mailDir)
+      if (!mail) throw new Error("Mail not found")
+      if (!mail.folder) throw new Error("Mail has no folder")
+      if (!isFolderWithin(folder, mail.folder))
+        throw new Error("Mail not found for this folder")
+
+      let preview: MailPreview
+      try {
+        preview = await compose({ folder, id: mail.id, mail })
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Unknown preview error"
+        throw new FolderPluginFailure(`Mail preview failed: ${message}`)
+      }
+
+      return detailData(mail, preview)
+    },
+  }
+}
+
+export type { MailListItem }

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

@@ -0,0 +1,10 @@
+export type MailPreview = {
+  /**
+   * Plain body of the draft read directly from its Markdown file.
+   */
+  body: string
+  /**
+   * Appended signature text. Null when no signature is present.
+   */
+  signature: string | null
+}

package/kernel/plugins/mail/src/viewer.tsx

@@ -0,0 +1,147 @@
+import type { ReactNode } from "react"
+
+import { FolderFilterBar } from "@raggle-ai/ui/components/folder-filter-bar"
+
+import type { MailFolderChoice } from "./folders.ts"
+import type { MailPreview } from "./types.ts"
+import { MailCard } from "./mail-card.tsx"
+
+export type MailListItem = {
+  attachments: string[]
+  bcc: string[]
+  cc: string[]
+  createdAt: string | null
+  excerpt: string
+  filePath: string
+  folder: string | null
+  from: string | null
+  id: string
+  inReplyTo: string | null
+  references: string[]
+  revision: string
+  status: string | null
+  subject: string | null
+  tags: string[]
+  to: string[]
+  updatedAt: string | null
+  noSignature: boolean
+}
+
+export type MailDetail = Omit<MailListItem, "excerpt"> & { body: string }
+
+export type { MailPreview } from "./types.ts"
+
+export type MailListAction = "archive" | "delete"
+
+export type MailContextInput = {
+  attachments?: ReadonlyArray<string>
+  bcc?: ReadonlyArray<string>
+  cc?: ReadonlyArray<string>
+  excerpt?: string
+  filePath: string
+  folder?: string | null
+  from?: string | null
+  status?: string | null
+  subject?: string | null
+  tags?: ReadonlyArray<string>
+  to?: ReadonlyArray<string>
+}
+
+/**
+ * Agent-friendly text context for one mail item, in the same shape the tasks
+ * plugin copies (`todoItemContext`). Callers pass the item they have — a list
+ * item (excerpt only) or a detail (full body via the second argument).
+ */
+export const mailItemContext = (item: MailContextInput, body?: string) =>
+  [
+    "You are helping with an email draft. Use the context below to understand the message and what it needs next.",
+    "",
+    "Instructions for the LLM:",
+    "- Treat the subject as the draft's objective.",
+    "- Use recipients, tags and body (or the owning draft file) as the authoritative message context.",
+    "- If information is missing, state the exact missing input or recipient needed.",
+    "- Return: 1) current status, 2) what the message needs next, 3) suggested edits or reply if asked.",
+    "",
+    "Mail context:",
+    `- Subject: ${item.subject ?? "(no subject)"}`,
+    item.from ? `- From: ${item.from}` : null,
+    item.to?.length ? `- To: ${item.to.join(", ")}` : null,
+    item.cc?.length ? `- Cc: ${item.cc.join(", ")}` : null,
+    item.bcc?.length ? `- Bcc: ${item.bcc.join(", ")}` : null,
+    item.attachments?.length
+      ? `- Attachments: ${item.attachments.join(", ")}`
+      : null,
+    `- Status: ${item.status ?? "unknown"}`,
+    item.folder ? `- Folder: ${item.folder}` : null,
+    item.tags?.length
+      ? `- Tags: ${item.tags.map((tag) => `#${tag}`).join(" ")}`
+      : null,
+    `- Draft file: ${item.filePath}`,
+    body ? "" : null,
+    body ? "Draft body:" : null,
+    body ?? null,
+    !body && item.excerpt ? "" : null,
+    !body && item.excerpt ? "Draft excerpt:" : null,
+    !body && item.excerpt ? item.excerpt : null,
+  ]
+    .filter((line): line is string => line != null)
+    .join("\n")
+
+export type MailDetailResponse = {
+  mail: MailDetail
+  preview?: MailPreview
+}
+
+export function MailFolderFilter({
+  choices,
+  onSelect,
+  selected,
+  total,
+}: {
+  choices: MailFolderChoice[]
+  onSelect: (folders: readonly string[]) => void
+  selected: readonly string[]
+  total: number
+}) {
+  return (
+    <FolderFilterBar
+      allLabel="All folders"
+      ariaLabel="Filter drafts by folder"
+      choices={choices}
+      onSelect={onSelect}
+      selected={selected}
+      total={total}
+    />
+  )
+}
+
+export function MailList({
+  actions,
+  folderLabel,
+  mailHref,
+  items,
+}: {
+  /**
+   * Optional per-draft action menu rendered in the card corner. The mail
+   * package stays UI-framework agnostic: the web layer passes its own menu
+   * (e.g. a shadcn dropdown) through this render slot.
+   */
+  actions?: (item: MailListItem) => ReactNode
+  folderLabel?: (folder: string | null) => string | null
+  mailHref: (id: string) => string
+  items: MailListItem[]
+}) {
+  return (
+    <ol className="m-0 grid list-none grid-cols-1 gap-2 p-0">
+      {items.map((item) => (
+        <MailCard
+          actions={actions}
+          folderLabel={folderLabel?.(item.folder)}
+          href={mailHref(item.id)}
+          item={item}
+          key={item.id}
+        />
+      ))}
+    </ol>
+  )
+}