kennel 0.2.0 → 0.2.2

package/kernel/plugins/mail/test/node.test.mjs

@@ -0,0 +1,207 @@
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+
+import { isFolderWithin, listMailForFolder, readMailById } from "../src/node.ts"
+
+let tmpBase
+let root
+let sibling
+let outside
+
+beforeAll(async () => {
+  tmpBase = await mkdtemp(join(tmpdir(), "kennel-mail-nested-"))
+  root = join(tmpBase, "project")
+  sibling = join(tmpBase, "project-x")
+  outside = join(tmpBase, "outside")
+  await mkdir(join(root, "clients", "client-one"), { recursive: true })
+  await mkdir(join(root, "client-one"), { recursive: true })
+  await mkdir(sibling, { recursive: true })
+  await mkdir(outside, { recursive: true })
+  // Symlink escape: a "folder" inside root that realpaths outside it.
+  await mkdir(join(root, "clients"), { recursive: true })
+  await symlink(outside, join(root, "clients", "escape"))
+})
+
+afterAll(async () => {
+  await rm(tmpBase, { recursive: true, force: true })
+})
+
+describe("isFolderWithin", () => {
+  test("exact folder is within itself", () => {
+    expect(isFolderWithin(root, root)).toBe(true)
+  })
+
+  test("real descendant is within", () => {
+    expect(isFolderWithin(root, join(root, "clients", "client-one"))).toBe(true)
+    expect(isFolderWithin(root, join(root, "clients"))).toBe(true)
+  })
+
+  test("sibling prefix path is rejected", () => {
+    expect(isFolderWithin(root, sibling)).toBe(false)
+  })
+
+  test("outside ancestor is rejected", () => {
+    expect(isFolderWithin(root, tmpBase)).toBe(false)
+    expect(isFolderWithin(root, tmpdir())).toBe(false)
+  })
+
+  test("traversal escapes collapse and are resolved against real paths", () => {
+    expect(isFolderWithin(root, join(root, "clients", "..", ".."))).toBe(false)
+    expect(
+      isFolderWithin(root, join(root, "clients", "..", "client-one")),
+    ).toBe(true)
+  })
+
+  test("symlink escape is rejected", () => {
+    expect(isFolderWithin(root, join(root, "clients", "escape"))).toBe(false)
+  })
+
+  test("unresolved (missing) candidate is rejected", () => {
+    expect(isFolderWithin(root, join(root, "not-created-yet"))).toBe(false)
+    expect(isFolderWithin(join(root, "not-created-yet"), root)).toBe(false)
+  })
+
+  test("null or undefined candidate is rejected", () => {
+    expect(isFolderWithin(root, null)).toBe(false)
+    expect(isFolderWithin(root, undefined)).toBe(false)
+  })
+})
+
+function draftFile(folder, id, subject = `Subject ${id}`) {
+  const folderLine = folder ? `folder: ${folder}` : ""
+  return `---\nid: ${id}\n${folderLine}\nstatus: working\nsubject: ${subject}\n---\n\nBody of ${id}\n`
+}
+
+describe("listMailForFolder", () => {
+  test("lists exact and descendant folders only", async () => {
+    const mailDir = join(tmpBase, "drafts")
+    await mkdir(mailDir, { recursive: true })
+    await writeFile(
+      join(mailDir, "d_root.md"),
+      draftFile(resolve(root), "d_root"),
+    )
+    await writeFile(
+      join(mailDir, "d_nested.md"),
+      draftFile(resolve(root, "clients", "client-one"), "d_nested"),
+    )
+    await writeFile(
+      join(mailDir, "d_nested2.md"),
+      draftFile(resolve(root, "clients"), "d_nested2"),
+    )
+    await writeFile(
+      join(mailDir, "d_sibling.md"),
+      draftFile(resolve(sibling), "d_sibling"),
+    )
+    await writeFile(
+      join(mailDir, "d_outside.md"),
+      draftFile(resolve(outside), "d_outside"),
+    )
+    await writeFile(
+      join(mailDir, "d_escape.md"),
+      draftFile(resolve(root, "clients", "escape"), "d_escape"),
+    )
+    await writeFile(
+      join(mailDir, "d_nofolder.md"),
+      draftFile(null, "d_nofolder"),
+    )
+
+    const items = await listMailForFolder({ mailDir, folder: root })
+    const ids = items.map((item) => item.id).sort()
+    expect(ids).toEqual(["d_nested", "d_nested2", "d_root"])
+
+    const nested = items.find((item) => item.id === "d_nested")
+    expect(nested?.folder).toBe(resolve(root, "clients", "client-one"))
+    expect(nested?.subject).toBe("Subject d_nested")
+  })
+
+  test("nested folder scope works for a subfolder row", async () => {
+    const mailDir = join(tmpBase, "drafts")
+    const items = await listMailForFolder({
+      mailDir,
+      folder: resolve(root, "clients"),
+    })
+    const ids = items.map((item) => item.id).sort()
+    expect(ids).toContain("d_nested")
+    expect(ids).toContain("d_nested2")
+    expect(ids).not.toContain("d_root")
+  })
+
+  test("reads only working and ready drafts from the mail folder", async () => {
+    const mailDir = join(tmpBase, "active-drafts")
+    await mkdir(mailDir, { recursive: true })
+
+    const statusDraft = (id, status) =>
+      `---\nid: ${id}\nfolder: ${resolve(root)}\nstatus: ${status}\nsubject: ${id}\n---\n\nBody of ${id}\n`
+    await writeFile(
+      join(mailDir, "d_aaaaaa.md"),
+      statusDraft("d_aaaaaa", "working"),
+    )
+    await writeFile(
+      join(mailDir, "d_ccccc1.md"),
+      statusDraft("d_ccccc1", "ready"),
+    )
+    await writeFile(
+      join(mailDir, "d_bbbbbb.md"),
+      statusDraft("d_bbbbbb", "sent"),
+    )
+    await writeFile(
+      join(mailDir, "d_dddddd.md"),
+      statusDraft("d_dddddd", "archived"),
+    )
+    await writeFile(join(mailDir, "d_eeeeee.md"), `# No status\n`)
+
+    const items = await listMailForFolder({ mailDir, folder: root })
+    const ids = items.map((item) => item.id).sort()
+    expect(ids).toEqual(["d_aaaaaa", "d_ccccc1"])
+  })
+})
+
+describe("readMailById", () => {
+  test("reads the authoritative draft file by id", async () => {
+    const mailDir = join(tmpBase, "direct-path")
+    await mkdir(mailDir, { recursive: true })
+
+    const path = join(mailDir, "d_cccccc.md")
+    await writeFile(path, draftFile(resolve(root), "d_cccccc"))
+
+    const mail = await readMailById("d_cccccc", mailDir)
+
+    expect(mail?.id).toBe("d_cccccc")
+    expect(mail?.filePath).toBe(path)
+    expect(mail?.body).toBe(`Body of d_cccccc\n`)
+  })
+
+  test("supports MailOS descriptive draft ids", async () => {
+    const mailDir = join(tmpBase, "descriptive-ids")
+    await mkdir(mailDir, { recursive: true })
+
+    const id = "draft_20251129_215834_Test-Draft"
+    await writeFile(join(mailDir, `${id}.md`), draftFile(resolve(root), id))
+
+    const mail = await readMailById(id, mailDir)
+    expect(mail?.id).toBe(id)
+  })
+
+  test("rejects drafts that are no longer active", async () => {
+    const mailDir = join(tmpBase, "inactive-drafts")
+    await mkdir(mailDir, { recursive: true })
+
+    await writeFile(
+      join(mailDir, "d_bbbbbb.md"),
+      `---\nid: d_bbbbbb\nfolder: ${resolve(root)}\nstatus: sent\nsubject: Sent\n---\n\nBody\n`,
+    )
+
+    const mail = await readMailById("d_bbbbbb", mailDir)
+    expect(mail).toBeNull()
+  })
+
+  test("rejects traversal ids", () => {
+    const mailDir = join(tmpBase, "traversal-drafts")
+    expect(() => readMailById("../d_aaaaaa", mailDir)).toThrow(
+      "Invalid mail id",
+    )
+    expect(() => readMailById("a/b", mailDir)).toThrow("Invalid mail id")
+  })
+})

package/kernel/plugins/mail/test/package.test.mjs

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const packageJson = JSON.parse(
+  await readFile(new URL("../package.json", import.meta.url), "utf8"),
+)
+
+test("mail package is ready for public npm publishing", () => {
+  assert.equal(packageJson.private, undefined)
+  assert.equal(packageJson.version, "0.1.0")
+  assert.equal(packageJson.license, "MIT")
+  assert.equal(packageJson.publishConfig?.access, "public")
+  assert.equal(packageJson.repository?.directory, "plugins/mail")
+  assert.deepEqual(packageJson.files, ["src"])
+})
+
+test("mail package ships the standard plugin script set", () => {
+  for (const script of [
+    "test",
+    "typecheck",
+    "format",
+    "lint",
+    "clean",
+    "pack:check",
+    "publish:public:dry-run",
+  ]) {
+    assert.ok(
+      typeof packageJson.scripts?.[script] === "string",
+      `missing script "${script}"`,
+    )
+  }
+})
+
+test("mail package exposes the core plugin deep exports", () => {
+  const keys = Object.keys(packageJson.exports).sort()
+  for (const required of [
+    ".",
+    "./client",
+    "./manifest",
+    "./parse",
+    "./server",
+  ]) {
+    assert.ok(keys.includes(required), `missing export "${required}"`)
+  }
+})
+
+test("mail client entry does not import the Node server entry", async () => {
+  const clientSource = await readFile(
+    new URL("../src/client.tsx", import.meta.url),
+    "utf8",
+  )
+  assert.doesNotMatch(clientSource, /node:|\/server"/)
+})

package/kernel/plugins/mail/test/parse.test.mjs

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test"
+
+import { parseMailMarkdown } from "../src/parse.ts"
+
+function baseMail(body = "Hello") {
+  return `---\nid: d_abcdef\nfolder: /tmp/project\n---\n\n${body}\n`
+}
+
+describe("parseMailMarkdown", () => {
+  test("parses normal frontmatter", () => {
+    const parsed = parseMailMarkdown(baseMail("Body"))
+    expect(parsed.id).toBe("d_abcdef")
+    expect(parsed.folder).toBe("/tmp/project")
+    expect(parsed.body).toBe("Body\n")
+  })
+
+  test("empty frontmatter does not throw and returns defaults", () => {
+    const content = `---\n---\n\nBody\n`
+    const parsed = parseMailMarkdown(content)
+    expect(parsed.id).toBe(null)
+    expect(parsed.folder).toBe(null)
+    expect(parsed.body).toBe("Body\n")
+  })
+
+  test("non-object frontmatter does not throw and returns defaults", () => {
+    const content = `---\n[]\n---\n\nBody\n`
+    const parsed = parseMailMarkdown(content)
+    expect(parsed.id).toBe(null)
+    expect(parsed.folder).toBe(null)
+    expect(parsed.body).toBe("Body\n")
+  })
+})

package/kernel/plugins/mail/test/server.test.mjs

@@ -0,0 +1,116 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterAll, beforeAll, expect, test } from "bun:test"
+
+import { createMailPlugin } from "../src/server.ts"
+
+function draftFile(folder, id) {
+  return `---\nid: ${id}\nfolder: ${folder}\nstatus: working\nsubject: ${id}\n---\n\nBody of ${id}\n`
+}
+
+let base
+let root
+let mailDir
+
+beforeAll(async () => {
+  base = await mkdtemp(join(tmpdir(), "kennel-mail-plugin-"))
+  root = join(base, "project")
+  mailDir = join(base, "drafts")
+  await mkdir(join(root, "clients"), { recursive: true })
+  await mkdir(mailDir, { recursive: true })
+})
+
+afterAll(async () => {
+  await rm(base, { recursive: true, force: true })
+})
+
+test("detect is unavailable with no active drafts", async () => {
+  const plugin = createMailPlugin({ mailDir })
+  const detection = await plugin.detect({ folder: root })
+  expect(detection.status).toBe("unavailable")
+})
+
+test("detect reports available with a count of matching active drafts", async () => {
+  const nested = join(root, "clients", "nested")
+  await mkdir(nested, { recursive: true })
+  await writeFile(join(mailDir, "d_root.md"), draftFile(root, "d_root"))
+  await writeFile(join(mailDir, "d_nested.md"), draftFile(nested, "d_nested"))
+
+  const plugin = createMailPlugin({ mailDir })
+  const detection = await plugin.detect({ folder: root })
+  expect(detection.status).toBe("available")
+  expect(detection.count).toBe(2)
+})
+
+test("handle list returns only folder-and-descendant active drafts", async () => {
+  const plugin = createMailPlugin({ mailDir })
+  const result = await plugin.handle({ folder: root }, "")
+  expect(result.kind).toBe("available")
+  if (result.kind !== "available") return
+  const payload = result.data
+  expect(payload.status).toBe("available")
+  const ids = payload.items.map((item) => item.id).sort()
+  expect(ids).toEqual(["d_nested", "d_root"])
+})
+
+test("handle detail returns the mail and injected preview", async () => {
+  const calls = []
+  const plugin = createMailPlugin({
+    mailDir,
+    previewer: async (options) => {
+      calls.push(options.id)
+      return { body: "COMPOSED BODY", signature: "--\nSig" }
+    },
+  })
+  const result = await plugin.handle({ folder: root }, "d_root")
+  expect(result.kind).toBe("available")
+  if (result.kind !== "available") return
+  expect(result.data.mail.id).toBe("d_root")
+  expect(result.data.preview.body).toBe("COMPOSED BODY")
+  expect(calls).toEqual(["d_root"])
+})
+
+test("handle detail rejects a folder mismatch before preview", async () => {
+  const other = join(base, "other")
+  await mkdir(other, { recursive: true })
+  let called = false
+  const plugin = createMailPlugin({
+    mailDir,
+    previewer: async () => {
+      called = true
+      return { body: "x", signature: null }
+    },
+  })
+  await expect(plugin.handle({ folder: other }, "d_root")).rejects.toThrow(
+    "Mail not found for this folder",
+  )
+  expect(called).toBe(false)
+})
+
+test("handle detail maps a preview read failure to a server failure", async () => {
+  const plugin = createMailPlugin({
+    mailDir,
+    previewer: async () => {
+      throw new Error("mailos parse failed")
+    },
+  })
+  await expect(plugin.handle({ folder: root }, "d_root")).rejects.toMatchObject(
+    {
+      name: "FolderPluginFailure",
+    },
+  )
+  await expect(plugin.handle({ folder: root }, "d_root")).rejects.toThrow(
+    "Mail preview failed",
+  )
+})
+
+test("handle detail rejects traversal ids", async () => {
+  const plugin = createMailPlugin({ mailDir })
+  await expect(plugin.handle({ folder: root }, "../x")).rejects.toThrow(
+    "Invalid mail id",
+  )
+  await expect(plugin.handle({ folder: root }, "a/b")).rejects.toThrow(
+    "Invalid mail id",
+  )
+})

package/kernel/plugins/mail/test/viewer.test.mjs

@@ -0,0 +1,192 @@
+import { createElement as h } from "react"
+import { describe, expect, test } from "bun:test"
+import { renderToStaticMarkup } from "react-dom/server"
+
+import { folderChoices, folderLabel } from "../src/folders.ts"
+import { MailFolderFilter, mailItemContext, MailList } from "../src/viewer.tsx"
+
+const WORKSPACE = "/tmp/kennel-example/example-workspace"
+const CLIENT_ONE = `${WORKSPACE}/clients/client-one`
+const CLIENT_TWO = `${WORKSPACE}/clients/client-two`
+const CLIENT_THREE = `${WORKSPACE}/clients/client-three`
+
+function mailItem({ folder, id, subject }) {
+  return {
+    bcc: [],
+    cc: [],
+    createdAt: "2026-09-18T08:23:23.805127Z",
+    excerpt: "Draft excerpt",
+    filePath: `/tmp/${id}.md`,
+    folder,
+    id,
+    status: "working",
+    subject,
+    tags: [],
+    to: ["ed@example.com"],
+    updatedAt: null,
+  }
+}
+
+function renderMailList(items) {
+  return renderToStaticMarkup(
+    h(MailList, {
+      folderLabel: (folder) => folderLabel(folder, WORKSPACE),
+      items,
+      mailHref: (id) => `/folder/x/mail/${id}`,
+    }),
+  )
+}
+
+describe("MailList cards", () => {
+  test("each card shows its owning folder and keeps a stable link", () => {
+    const html = renderMailList([
+      mailItem({ folder: WORKSPACE, id: "d_root0", subject: "Root draft" }),
+      mailItem({
+        folder: CLIENT_ONE,
+        id: "d_client-one0",
+        subject: "Client One draft",
+      }),
+      mailItem({ folder: null, id: "d_none0", subject: "No folder draft" }),
+    ])
+
+    expect(html).toContain("Root draft")
+    expect(html).toContain("Client One draft")
+    expect(html).toContain("No folder draft")
+    // Stable per-draft links survive filtering.
+    expect(html).toContain('href="/folder/x/mail/d_root0"')
+    expect(html).toContain('href="/folder/x/mail/d_client-one0"')
+    expect(html).toContain('href="/folder/x/mail/d_none0"')
+    expect(html).toContain(">example-workspace<")
+    expect(html).toContain(">clients/client-one<")
+    expect(html).toContain(`title="${CLIENT_ONE}"`)
+    expect(html.match(/lucide-folder /g)).toHaveLength(2)
+    expect(html).toContain('class="truncate">clients/client-one</span>')
+  })
+
+  test("shows the To domain favicon and a truncated message preview", () => {
+    const html = renderMailList([
+      {
+        ...mailItem({ folder: CLIENT_ONE, id: "d_preview", subject: "Draft" }),
+        to: ["Ed <ed@example.com>"],
+      },
+    ])
+
+    expect(html).toContain(
+      "https://www.google.com/s2/favicons?domain=example.com&amp;sz=32",
+    )
+    expect(html).not.toContain("domain=ed")
+    expect(html).toContain('referrerPolicy="no-referrer"')
+    expect(html).toContain("grid-cols-[2rem_minmax(0,1fr)]")
+    expect(html).toMatch(/<p class="[^"]*truncate[^"]*">Draft excerpt<\/p>/)
+  })
+
+  test("uses a mail icon without a favicon request for missing or invalid To addresses", () => {
+    for (const to of [[], ["invalid"], ["user@localhost"]]) {
+      const html = renderMailList([
+        {
+          ...mailItem({ folder: null, id: "d_fallback", subject: "Draft" }),
+          to,
+          cc: ["cc@example.com"],
+          excerpt: "",
+        },
+      ])
+
+      expect(html).toContain("lucide-mail")
+      expect(html).not.toContain("s2/favicons")
+      expect(html).not.toMatch(/<p[\s>]/)
+    }
+  })
+
+  test("time precedes the recipient in a left-aligned row", () => {
+    const html = renderMailList([
+      {
+        ...mailItem({ folder: CLIENT_ONE, id: "d_time", subject: "Draft" }),
+        updatedAt: new Date().toISOString(),
+      },
+    ])
+
+    expect(html).toContain("just now")
+    expect(html.indexOf("just now")).toBeLessThan(html.indexOf("To:"))
+    expect(html).toContain('class="flex items-start gap-2"')
+  })
+})
+
+describe("mailItemContext", () => {
+  test("formats one draft's fields into an agent-friendly prompt", () => {
+    const item = mailItem({
+      folder: WORKSPACE,
+      id: "d_ctx",
+      subject: "Pricing follow-up",
+    })
+    const text = mailItemContext(item, "Hi Ed,\n\nConfirming the numbers.")
+
+    expect(text).toContain("Instructions for the LLM:")
+    expect(text).toContain("- Subject: Pricing follow-up")
+    expect(text).toContain("- To: ed@example.com")
+    expect(text).toContain("- Status: working")
+    expect(text).toContain(`- Draft file: /tmp/d_ctx.md`)
+    expect(text).toContain("Draft body:")
+    expect(text).toContain("Confirming the numbers.")
+  })
+
+  test("falls back to the excerpt and a no-subject placeholder", () => {
+    const item = mailItem({ folder: null, id: "d_none", subject: null })
+    const text = mailItemContext(item)
+
+    expect(text).toContain("Subject: (no subject)")
+    expect(text).toContain("Draft excerpt:")
+    expect(text).toContain("Draft excerpt")
+    expect(text).not.toContain("Draft body:")
+  })
+})
+
+describe("MailFolderFilter markup", () => {
+  const drafts = [
+    WORKSPACE,
+    WORKSPACE,
+    CLIENT_ONE,
+    CLIENT_TWO,
+    CLIENT_THREE,
+  ].map((folder, index) => ({ folder, id: `d_${index}` }))
+  const choices = folderChoices(drafts, WORKSPACE)
+
+  test("one trigger button shows the total when nothing is selected", () => {
+    const html = renderToStaticMarkup(
+      h(MailFolderFilter, {
+        choices,
+        onSelect: () => {},
+        selected: [],
+        total: drafts.length,
+      }),
+    )
+
+    // Single trigger with accessible name and the unfiltered total badge.
+    expect(html).toContain('aria-label="Filter drafts by folder"')
+    expect(html).toContain("lucide-folder-search")
+    expect(html).toContain(">Folder<")
+    expect(html).toContain(">5<")
+    // The All folders row lives inside the portal, so no SSR markup carries it.
+    expect(html).not.toContain("All folders")
+    // No pressed chips outside the portal dropdown.
+    const pressed = html.match(/aria-pressed=/g) ?? []
+    expect(pressed.length).toBe(0)
+  })
+
+  test("a single selection shows the count on the trigger", () => {
+    const html = renderToStaticMarkup(
+      h(MailFolderFilter, {
+        choices,
+        onSelect: () => {},
+        selected: [CLIENT_ONE],
+        total: drafts.length,
+      }),
+    )
+
+    // Same single trigger; the badge shows the selected count.
+    expect(html).toContain('aria-label="Filter drafts by folder"')
+    expect(html).toContain(">Folder<")
+    expect(html).toContain(">1<")
+    expect(html).not.toContain("lucide-x")
+    expect(html).not.toContain("All folders")
+  })
+})

package/kernel/plugins/mail/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@raggle-ai/tsconfig/base.json",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "jsx": "preserve",
+    "baseUrl": ".",
+    "allowImportingTsExtensions": true,
+    // local copy: bun doesn't read paths inherited via `extends`
+    "paths": {
+      "~/*": ["${configDir}/../../packages/*/src"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "eslint.config.mjs"]
+}