kennel 0.2.3 → 0.2.5

package/kernel/plugins/mail/SKILL.md

@@ -1,97 +0,0 @@
----
-name: kennel-mail
-description: Open and read local MailOS email drafts for a Kennel folder — Markdown draft files in `~/.email/drafts` with YAML frontmatter, filtered to drafts whose `folder` is the viewed folder or one of its subfolders. Use when the user asks to view drafts for a folder in the Kennel viewer, read mail drafts by subject, status, tags, or recipient, list which drafts belong to a workspace, open a specific draft, or see a draft's excerpt and revision.
----
-
-# Kennel Mail Plugin
-
-The Mail plugin (`@raggle-ai/mail`) shows local MailOS email drafts —
-Markdown files with YAML frontmatter in `~/.email/drafts/*.md` — scoped to the
-folder the user is viewing. It offers a folder selector, a draft list, and a
-per-draft detail view, without invoking the MailOS binary.
-
-This skill covers the agent-facing parts of that plugin: where drafts live,
-which drafts are visible for a folder, and how to open and verify the view.
-For the plugin package's implementation contract, see `plugins/README.md`
-in the Kennel repo.
-
-## When to use
-
-- The user asks to open, list, or read email drafts for a folder in Kennel.
-- The user wants to know which drafts belong to a workspace, or see a draft's
-  subject, status, tags, recipients, excerpt, or revision.
-- Preview or verification work needs the Mail plugin tab to be available and
-  populated for a target folder.
-
-## Workflow
-
-1. **Identify the folder** whose drafts the user wants. The mail plugin shows
-   only drafts whose `folder` frontmatter value is that folder itself or a
-   real subfolder of it (checked through `realpath`, so symlink escapes and
-   sibling paths are rejected).
-2. **Check for drafts.** Drafts live in `~/.email/drafts/` as `<id>.md`
-   files. Open the folder in the viewer and confirm the **Mail** plugin tab
-   appears; the tab only appears when at least one active draft belongs to the
-   folder, and its badge shows the draft count.
-3. **Read the drafts.** Each draft is Markdown with YAML frontmatter followed
-   by the message body. Only drafts with a non-empty `id` and an active status
-   (`working` or `ready`) are listed — sent and canceled drafts are excluded,
-   even though MailOS keeps them in the same directory. Read values from the
-   files; do not invent recipients or subjects.
-4. **Open the view.** `kennel serve <folder>` (or `kennel view <folder>` in a
-   source checkout), then point at the Mail tab. Launch, port, watch, and
-   link verification mechanics come from the `kennel-preview` skill — install
-   it alongside this one so the full workflow works.
-5. **Verify before reporting.** Confirm the server is alive
-   (`curl -fsS "$URL/api/health"`), the printed URL serves the exact requested
-   folder root, and confirm the specific drafts the user asked about are in
-   the draft directory with an active status and the matching `folder` value.
-
-## Content shape
-
-### Draft file location
-
-- Default mail directory: `~/.email/drafts/` (the server entry accepts a
-  `mailDir` override, intended for tests).
-- Each draft is `<id>.md`; ids are validated (no path separators, no `.`/`..`)
-  before a file is read.
-- Only files ending in `.md` are considered.
-
-### Draft frontmatter
-
-| Field                       | Meaning                                                                                           |
-| --------------------------- | ------------------------------------------------------------------------------------------------- |
-| `id`                        | Required for the draft to be listed                                                               |
-| `status`                    | `working` \| `ready` (active, listed) — sent/canceled/other are hidden                            |
-| `folder`                    | The folder this draft belongs to; must be the viewed folder or a real descendant (realpath check) |
-| `tags`                      | Array of strings                                                                                  |
-| `from`, `to`, `cc`, `bcc`   | Sender; recipient lists (a raw string is wrapped into a single-element list)                      |
-| `in_reply_to`, `references` | Reply threading                                                                                   |
-| `subject`                   | Subject line                                                                                      |
-| `created_at`, `updated_at`  | Timestamps; the list is sorted by `updatedAt` (falling back to `createdAt`) descending            |
-
-The YAML body after the frontmatter is the message body. The list item also
-carries an `excerpt` (first ~280 characters of the body) and a `revision` (a
-sha256 of the exact draft file bytes — MailOS treats this hash as the draft
-revision for guarded destructive actions).
-
-## Verification
-
-- Server alive: `curl -fsS --connect-timeout 3 --max-time 5 "$URL/api/health"`
-- Folder root: request `/api/documents` and confirm `root` is the requested
-  absolute folder.
-- Mail availability: the Mail plugin tab is present and its badge equals the
-  number of active drafts whose `folder` is inside the served folder.
-- Per-draft checks: draft ids, subjects, statuses, and `folder` values in the
-  view match the `~/.email/drafts/*.md` source files; drafts with status
-  `sent`/`canceled` or a `folder` outside the served root do not appear.
-
-## Boundaries
-
-- This plugin is read-only over the draft directory: it lists and renders
-  drafts. Composing, sending, or changing draft status is done through MailOS
-  itself (the `mailos` CLI), not this plugin.
-- Do not invent draft contents, recipients, or subjects — read them from the
-  files.
-- The mail view only exists inside the Kennel viewer (server + web app); the
-  `@raggle-ai/mail` package is not a standalone CLI.

package/kernel/plugins/mail/eslint.config.js

@@ -1,10 +0,0 @@
-import baseConfig from "@raggle-ai/eslint-config/base"
-import reactConfig from "@raggle-ai/eslint-config/react"
-
-export default [
-  ...baseConfig,
-  ...reactConfig,
-  {
-    ignores: ["dist/**", "**/_generated/", "vendor/**"],
-  },
-]

package/kernel/plugins/mail/package.json

@@ -1,79 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/package.json",
-  "name": "@raggle-ai/mail",
-  "version": "0.1.0",
-  "description": "Mail folder plugin: parse and view MailOS local email drafts for Kennel folders.",
-  "type": "module",
-  "license": "MIT",
-  "prettier": "@raggle-ai/prettier-config",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/raggle-ai/kennel.git",
-    "directory": "plugins/mail"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "files": [
-    "src"
-  ],
-  "exports": {
-    ".": "./src/index.ts",
-    "./api": "./src/api.ts",
-    "./client": "./src/client.tsx",
-    "./folders": "./src/folders.ts",
-    "./history": "./src/history.ts",
-    "./mailos": "./src/mailos.ts",
-    "./manifest": "./src/manifest.ts",
-    "./node": "./src/node.ts",
-    "./parse": "./src/parse.ts",
-    "./server": "./src/server.ts",
-    "./viewer": "./src/viewer.tsx"
-  },
-  "scripts": {
-    "test": "bun test test/*.test.mjs",
-    "typecheck": "tsc --noEmit",
-    "format": "prettier . --check --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
-    "format:fix": "prettier . --write --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
-    "lint": "eslint . --cache --cache-location .cache/.eslintcache",
-    "lint:fix": "eslint . --fix --cache --cache-location .cache/.eslintcache",
-    "clean": "git clean -xdf dist node_modules .cache .turbo/cache",
-    "pack:check": "npm pack --dry-run",
-    "publish:public:dry-run": "npm --@raggle-ai:registry=https://registry.npmjs.org publish --dry-run --access public --registry=https://registry.npmjs.org"
-  },
-  "dependencies": {
-    "@raggle-ai/folder-plugin": "workspace:*",
-    "@raggle-ai/markdown": "workspace:*",
-    "@raggle-ai/ui": "workspace:*",
-    "@tanstack/react-query": "catalog:tanstack",
-    "koffi": "^3.3.1",
-    "lucide-react": "^0.562.0",
-    "yaml": "^2.9.0"
-  },
-  "peerDependencies": {
-    "react": ">=18.3.0"
-  },
-  "devDependencies": {
-    "@eslint/compat": "catalog:eslint",
-    "@eslint/eslintrc": "catalog:eslint",
-    "@ianvs/prettier-plugin-sort-imports": "catalog:prettier",
-    "@prettier/plugin-oxc": "catalog:prettier",
-    "@raggle-ai/eslint-config": "workspace:*",
-    "@raggle-ai/prettier-config": "workspace:*",
-    "@raggle-ai/tsconfig": "workspace:*",
-    "@types/node": "catalog:",
-    "@types/react": "catalog:react19",
-    "@types/react-dom": "catalog:react19",
-    "eslint": "catalog:eslint",
-    "eslint-plugin-unused-imports": "catalog:eslint",
-    "prettier": "catalog:prettier",
-    "prettier-plugin-classnames": "catalog:prettier",
-    "prettier-plugin-merge": "catalog:prettier",
-    "prettier-plugin-tailwindcss": "catalog:prettier",
-    "react": "catalog:react19",
-    "react-dom": "catalog:react19",
-    "typescript": "catalog:",
-    "typescript-eslint": "catalog:eslint"
-  }
-}

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

@@ -1,359 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http"
-
-import type { ApiRouteHandle } from "@raggle-ai/folder-plugin/endpoint"
-import type { MailosService } from "@raggle-ai/mail/mailos"
-import {
-  apiError,
-  jsonResponse,
-  parseJsonBody,
-  runApiRoute,
-} from "@raggle-ai/folder-plugin/endpoint"
-import {
-  deleteLocalDraftVerified,
-  MailAttachmentError,
-  MailDeleteError,
-  removeDraftAttachmentVerified,
-} from "@raggle-ai/mail/history"
-import {
-  createMailosService,
-  MailosCommandError,
-  MailSendFailure,
-} from "@raggle-ai/mail/mailos"
-import {
-  defaultMailDir,
-  isFolderWithin,
-  listMailForFolder,
-  readMailById,
-} from "@raggle-ai/mail/node"
-
-export type MailPreview = { body: string; signature: string | null }
-
-export type MailPreviewer = (options: {
-  folder: string
-  id: string
-  mail: NonNullable<Awaited<ReturnType<typeof readMailById>>>
-}) => Promise<MailPreview>
-
-/**
- * Context provided by the Vite plugin. `authorizeFolder` enforces the real
- * viewer root (realpath + locked root), `watch` wires folder live refresh,
- * and `mailPreviewer`/`mailDir`/`mailos` are test seams.
- */
-export type MailApiContext = {
-  authorizeFolder: (value: string | null) => string
-  mailDir?: string
-  mailos?: ReturnType<typeof createMailosService>
-  mailPreviewer?: MailPreviewer
-  watch: (folder: string) => void
-}
-
-type AuthorizedMail = {
-  folder: string
-  mail: NonNullable<Awaited<ReturnType<typeof readMailById>>> & {
-    folder: string
-  }
-}
-
-type Handler = ApiRouteHandle<MailApiContext>
-
-const defaultMailos = createMailosService()
-
-function defaultPreviewer(mailos: MailosService): MailPreviewer {
-  return 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,
-  })
-}
-
-function mailDirOption(mailDir?: string) {
-  return mailDir ?? defaultMailDir()
-}
-
-function requireString(value: unknown, name: string) {
-  if (typeof value !== "string" || !value.trim()) {
-    throw apiError("bad-request", `Missing ${name} parameter`)
-  }
-  return value.trim()
-}
-
-function requireRevision(value: unknown) {
-  const revision = requireString(value, "revision")
-  if (!/^[a-f0-9]{64}$/i.test(revision)) {
-    throw apiError("bad-request", "Invalid revision parameter")
-  }
-  return revision.toLowerCase()
-}
-
-/**
- * Shared authorized read: the folder must be a real root/descendant of the
- * viewer root and the draft id must be a canonical filename with an active
- * MailOS status; the draft's recorded folder must really be within the
- * requested folder (symlink/traversal escapes collapse through realpath).
- */
-async function authorizedMail(
-  context: MailApiContext,
-  id: string,
-  pathValue: string | null,
-): Promise<AuthorizedMail> {
-  const trimmed = id.trim()
-  if (!trimmed) throw apiError("bad-request", "Missing id parameter")
-  const folder = context.authorizeFolder(pathValue)
-  const mail = await readMailById(trimmed, mailDirOption(context.mailDir))
-  if (!mail) throw apiError("not-found", "Mail not found")
-  if (!mail.folder) throw apiError("not-found", "Mail has no folder")
-  if (!isFolderWithin(folder, mail.folder)) {
-    throw apiError("not-found", "Mail not found for this folder")
-  }
-  return { folder, mail: { ...mail, folder: mail.folder } }
-}
-
-const listMail: Handler = async ({ context, query, response }) => {
-  const folder = context.authorizeFolder(query.get("path"))
-  const items = await listMailForFolder({
-    folder,
-    mailDir: mailDirOption(context.mailDir),
-  })
-  jsonResponse(response, 200, { folder, items })
-}
-
-const readItem: Handler = async ({ context, query, response }) => {
-  const id = requireString(query.get("id"), "id")
-  const { folder, mail } = await authorizedMail(context, id, query.get("path"))
-  context.watch(folder)
-
-  let preview: MailPreview
-  try {
-    const previewer =
-      context.mailPreviewer ?? defaultPreviewer(context.mailos ?? defaultMailos)
-    preview = await previewer({ id, folder, mail })
-  } catch (error) {
-    const detail =
-      error instanceof Error ? error.message : "Unknown preview error"
-    throw apiError("internal", `Mail preview failed: ${detail}`)
-  }
-
-  jsonResponse(response, 200, { mail, preview })
-}
-
-const resolveSender: Handler = async ({ context, query, response }) => {
-  const id = requireString(query.get("id"), "id")
-  const { mail } = await authorizedMail(context, id, query.get("path"))
-  const mailos = context.mailos ?? defaultMailos
-  const identity = await mailos.identity(mail.folder)
-  jsonResponse(response, 200, identity)
-}
-
-const readConversation: Handler = async ({
-  context,
-  query,
-  response,
-  signal,
-}) => {
-  const id = requireString(query.get("id"), "id")
-  const { mail } = await authorizedMail(context, id, query.get("path"))
-  const mailos = context.mailos ?? defaultMailos
-  const references = [...mail.references, mail.inReplyTo].filter(
-    (reference): reference is string => Boolean(reference),
-  )
-  const result = await mailos.conversation(mail.folder, references, signal)
-  jsonResponse(response, 200, result)
-}
-
-/**
- * Convert a CLI-level failure into a structured API error without leaking
- * command output: a hard child timeout is a 504, an aborted child is
- * rethrown for the endpoint's disconnect handling, and any other non-zero
- * exit becomes a generic 500 with a fixed message.
- */
-function commandFailureError(error: MailosCommandError): never {
-  if (error.timedOut || error.code === "timeout") {
-    throw apiError("timeout", "MailOS command timed out")
-  }
-  if (error.code === "aborted") throw error
-  throw apiError("failed", "MailOS command failed")
-}
-
-function sendFailureError(error: MailSendFailure) {
-  switch (error.reason) {
-    case "revision-match":
-      return apiError("conflict", error.message)
-    case "invalid-draft":
-      return apiError("bad-request", error.message)
-    case "unsupported-draft-dir":
-      return apiError("bad-request", error.message)
-    default:
-      return apiError("failed", error.message)
-  }
-}
-
-const runAction: Handler = async ({ body, context, response, signal }) => {
-  const parsed = parseJsonBody(body)
-  const action = requireString(parsed.action, "action")
-  const id = requireString(parsed.id, "id")
-  const revision = requireRevision(parsed.revision)
-  if (
-    action !== "archive" &&
-    action !== "delete" &&
-    action !== "remove-attachment"
-  ) {
-    throw apiError("bad-request", "Invalid action parameter")
-  }
-
-  const { mail } = await authorizedMail(context, id, pathFromParsed(parsed))
-  if (mail.revision !== revision) {
-    throw apiError("conflict", "Draft changed since it was loaded")
-  }
-
-  const mailos = context.mailos ?? defaultMailos
-  if (action === "remove-attachment") {
-    const attachment = requireString(parsed.attachment, "attachment")
-    try {
-      await removeDraftAttachmentVerified(
-        mail,
-        mailDirOption(context.mailDir),
-        attachment,
-      )
-    } catch (error) {
-      if (error instanceof MailAttachmentError) {
-        switch (error.outcome) {
-          case "missing":
-            throw apiError("not-found", error.message)
-          case "invalid":
-            throw apiError("bad-request", error.message)
-          case "changed":
-            throw apiError("conflict", error.message)
-        }
-      }
-      throw error
-    }
-  } else if (action === "delete") {
-    try {
-      await deleteLocalDraftVerified(mail, mailDirOption(context.mailDir))
-    } catch (error) {
-      if (error instanceof MailDeleteError) {
-        switch (error.outcome) {
-          case "missing":
-            throw apiError("not-found", error.message)
-          case "invalid":
-            throw apiError("bad-request", error.message)
-          case "changed":
-            throw apiError("conflict", error.message)
-        }
-      }
-      throw error
-    }
-  } else {
-    try {
-      await mailos.archive(mail.folder, mail.id, {
-        draftDir: mailDirOption(context.mailDir),
-        signal,
-      })
-    } catch (error) {
-      if (error instanceof MailSendFailure) throw sendFailureError(error)
-      if (error instanceof MailosCommandError) commandFailureError(error)
-      throw error
-    }
-  }
-
-  jsonResponse(response, 200, { action, id: mail.id, ok: true })
-}
-
-const runSend: Handler = async ({ body, context, response, signal }) => {
-  const parsed = parseJsonBody(body)
-  const id = requireString(parsed.id, "id")
-  const dryRun = parsed.dryRun === true
-  const { mail } = await authorizedMail(context, id, pathFromParsed(parsed))
-  const mailos = context.mailos ?? defaultMailos
-
-  if (dryRun) {
-    const preview = await mailos
-      .sendPreview(mail.folder, mail.id, {
-        draftDir: mailDirOption(context.mailDir),
-        signal,
-      })
-      .catch((error: unknown) => {
-        if (error instanceof MailSendFailure) throw sendFailureError(error)
-        if (error instanceof MailosCommandError) commandFailureError(error)
-        throw error
-      })
-    jsonResponse(response, 200, preview)
-    return
-  }
-
-  const revision = requireRevision(parsed.revision)
-  if (mail.revision !== revision) {
-    throw apiError("conflict", "Draft changed since it was loaded")
-  }
-  const result = await mailos
-    .confirmSend(mail.folder, mail.id, revision, {
-      draftDir: mailDirOption(context.mailDir),
-      signal,
-    })
-    .catch((error: unknown) => {
-      if (error instanceof MailSendFailure) throw sendFailureError(error)
-      if (error instanceof MailosCommandError) commandFailureError(error)
-      throw error
-    })
-  jsonResponse(response, 200, result)
-}
-
-function pathFromParsed(parsed: Record<string, unknown>) {
-  return typeof parsed.path === "string" && parsed.path ? parsed.path : null
-}
-
-/**
- * All mail HTTP routes. `/api/mail`, `/api/mail/item`, `/api/mail/from` and
- * `/api/mail/conversation` are GET-only reads (GET never mutates);
- * `/api/mail/action` and `/api/mail/send` are POST mutations guarded by the
- * endpoint wrapper's same-origin check. Returns false for non-mail paths so
- * the plugin can continue its own routing.
- */
-export async function handleMailApiRoutes(
-  request: IncomingMessage,
-  response: ServerResponse,
-  context: MailApiContext,
-): Promise<boolean> {
-  const url = new URL(request.url ?? "/", "http://127.0.0.1")
-
-  const specByPath: Record<
-    string,
-    {
-      method: "GET" | "POST"
-      maxBodyBytes?: number
-      timeoutMs?: number
-      handle: Handler
-    }
-  > = {
-    "/api/mail": { method: "GET", handle: listMail },
-    "/api/mail/item": { method: "GET", handle: readItem },
-    "/api/mail/from": { method: "GET", handle: resolveSender },
-    "/api/mail/conversation": {
-      method: "GET",
-      timeoutMs: 75_000,
-      handle: readConversation,
-    },
-    "/api/mail/action": {
-      method: "POST",
-      maxBodyBytes: 16 * 1024,
-      timeoutMs: 60_000,
-      handle: runAction,
-    },
-    "/api/mail/send": {
-      method: "POST",
-      maxBodyBytes: 16 * 1024,
-      timeoutMs: 90_000,
-      handle: runSend,
-    },
-  }
-
-  const spec = specByPath[url.pathname]
-  if (!spec) return false
-
-  await runApiRoute(request, response, url, spec, context)
-  return true
-}

package/kernel/plugins/mail/src/bun-ffi.d.ts

@@ -1,14 +0,0 @@
-/**
- * Ambient typing for the `bun:ffi` surface flock.ts uses. Bun's runtime
- * module provides `dlopen`; TypeScript cannot resolve it without this, and
- * flock.ts keeps the import dynamic so the Node (koffi) path never touches
- * bun's runtime.
- */
-declare module "bun:ffi" {
-  export function dlopen(
-    path: string,
-    symbols: Record<string, { args: string[]; returns: string }>,
-  ): {
-    symbols: Record<string, (...args: number[]) => number>
-  }
-}

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

@@ -1,14 +0,0 @@
-import type { FolderPluginViewProps } from "@raggle-ai/folder-plugin/client"
-
-import { MailDetailPage } from "./mail-detail-page"
-import { MailPage } from "./mail-page"
-import { mailManifest } from "./manifest"
-
-export function MailPlugin(props: FolderPluginViewProps) {
-  return props.subpath ? <MailDetailPage {...props} /> : <MailPage {...props} />
-}
-
-export const mailClient = {
-  ...mailManifest,
-  component: MailPlugin,
-}