opencode-workspace-mailbox 0.0.0-stage → 0.1.0

package/src/parser.ts

@@ -0,0 +1,103 @@
+import { messageHash } from "./hash.js"
+
+export type MailboxMessage = {
+  header: string
+  from: string
+  to: string
+  status: string
+  topic: string
+  body: string
+  start: number
+  end: number
+  statusStart: number
+  statusEnd: number
+  /** Char offset of the end of the status line's content (before its line ending); -1 if absent. */
+  statusLineEnd: number
+  hash: string
+}
+
+function parseHeader(headerText: string): { from: string; to: string } {
+  const s = headerText.trim()
+  const re = /(?:—|–|-)\s*from\s+(.+?)\s*(?:→|->|-->)\s*to\s+(.+)$/
+  const m = s.match(re)
+  if (!m) return { from: "", to: "" }
+  return { from: m[1].trim(), to: m[2].trim() }
+}
+
+const HEADER_DATE_RE = /^\d{4}-\d{2}-\d{2}/
+
+/**
+ * A `###` line is a message header only when it carries a date or a
+ * `from ... to ...` shape. Anything else (`### Notes` inside a body) stays part
+ * of the previous message instead of splitting it.
+ */
+function looksLikeMessageHeader(header: string): boolean {
+  const text = header.trim()
+  if (HEADER_DATE_RE.test(text)) return true
+  const { from, to } = parseHeader(text)
+  return from.length > 0 && to.length > 0
+}
+
+export function parseMailbox(text: string): MailboxMessage[] {
+  const messages: MailboxMessage[] = []
+  const starts = Array.from(text.matchAll(/^###[ \t]+/gm))
+    .map((match) => match.index)
+    .filter((index) => {
+      const nl = text.indexOf("\n", index)
+      const line = text.slice(index, nl === -1 ? text.length : nl).replace(/\r$/, "")
+      return looksLikeMessageHeader(line.replace(/^###[ \t]+/, ""))
+    })
+
+  for (let i = 0; i < starts.length; i++) {
+    const start = starts[i]
+    const end = i + 1 < starts.length ? starts[i + 1] : text.length
+
+    let nl = text.indexOf("\n", start)
+    if (nl === -1 || nl >= end) nl = end
+    let headerLine = text.slice(start, nl)
+    if (headerLine.endsWith("\r")) headerLine = headerLine.slice(0, -1)
+    const header = headerLine.replace(/^###[ \t]+/, "")
+    const { from, to } = parseHeader(header)
+
+    const regionStart = nl >= text.length ? nl : nl + 1
+    const region = text.slice(regionStart, end)
+
+    let status = ""
+    let statusStart = -1
+    let statusEnd = -1
+    let statusLineEnd = -1
+    const statusMatch = /\*\*Status:\*\*[ \t]*([^\r\n]*)/.exec(region)
+    if (statusMatch) {
+      const raw = statusMatch[1]
+      const word = raw.match(/\S+/)
+      if (word) {
+        status = word[0].toUpperCase()
+        const prefix = statusMatch[0].length - statusMatch[1].length
+        statusStart = regionStart + statusMatch.index + prefix + (word.index ?? 0)
+        statusEnd = statusStart + word[0].length
+      }
+      statusLineEnd = regionStart + statusMatch.index + statusMatch[0].length
+    }
+
+    let topic = ""
+    let topicLineEnd = -1
+    const topicMatch = /\*\*Topic:\*\*[ \t]*([^\r\n]*)/.exec(region)
+    if (topicMatch) {
+      topic = topicMatch[1].trim()
+      topicLineEnd = regionStart + topicMatch.index + topicMatch[0].length
+    }
+
+    const bodyStart = Math.max(regionStart, statusLineEnd, topicLineEnd)
+    const body = text.slice(bodyStart, end).trim()
+
+    const hash = messageHash({ header, topic, body })
+
+    messages.push({ header, from, to, status, topic, body, start, end, statusStart, statusEnd, statusLineEnd, hash })
+  }
+
+  return messages
+}
+
+export function isOpen(message: MailboxMessage): boolean {
+  return message.status === "OPEN"
+}

package/src/paths.ts

@@ -0,0 +1,38 @@
+import path from "node:path"
+
+export const RECIPIENT_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export class PathSafetyError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "PathSafetyError"
+  }
+}
+
+export function isSafeRecipient(name: unknown): name is string {
+  return typeof name === "string" && RECIPIENT_RE.test(name)
+}
+
+export function resolveInside(baseDir: string, ...segments: string[]): string {
+  const target = path.resolve(baseDir, ...segments)
+  const rel = path.relative(baseDir, target)
+  if (rel === "" || rel === ".." || rel.startsWith(".." + path.sep) || path.isAbsolute(rel)) {
+    throw new PathSafetyError(`Path escapes base directory: ${target}`)
+  }
+  return target
+}
+
+export function mailboxFile(mailboxDir: string, recipient: string): string {
+  if (!isSafeRecipient(recipient)) {
+    throw new PathSafetyError(`Invalid recipient "${recipient}"`)
+  }
+  return resolveInside(mailboxDir, recipient + ".md")
+}
+
+export function assertInside(baseDir: string, candidate: string, label: string): string {
+  try {
+    return resolveInside(baseDir, candidate)
+  } catch {
+    throw new PathSafetyError(`${label} must resolve inside the project directory: ${candidate}`)
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,20 @@
+import type { MailboxMessage } from "./parser.js"
+
+function truncate(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max) : text
+}
+
+export function buildIdlePrompt(project: string, messages: MailboxMessage[]): string {
+  const n = messages.length
+  const topics = messages.map((m) => `- ${truncate(m.topic || "(no topic)", 120)}`).join("\n")
+  return (
+    `You have ${n} OPEN mailbox message(s) for this project.\n\n` +
+    `Load the \`workspace-mailbox\` skill, read \`handoffs/${project}.md\`, handle every OPEN message,\n` +
+    `flip each one to DONE (use \`mailbox_ack\`), and reply only if a decision is needed.\n\n` +
+    `Topics:\n${topics}`
+  )
+}
+
+export function buildCapNotice(project: string, count: number, maxAutoRounds = 2): string {
+  return `Mailbox: ${count} OPEN message(s) in ${project} — auto-handling stopped after ${maxAutoRounds} round(s); ask me to handle them.`
+}

package/src/state.ts

@@ -0,0 +1,119 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+export type SessionState = {
+  autoRounds: number
+  lastPromptAt: number
+  lastNoticeAt?: number
+  noticeKey?: string
+  spawnsThisTurn?: number
+}
+export type MailboxState = {
+  version: 1
+  prompted: string[]
+  ownWrites: string[]
+  sessions: Record<string, SessionState>
+  /** Session ids this plugin created (spawn-on-send). */
+  spawnedSessions: string[]
+  /** Message hashes that already triggered a spawn. */
+  spawnedHashes: string[]
+  lastSpawnAt?: number
+}
+
+const MAX_ENTRIES = 500
+
+export function emptyState(): MailboxState {
+  return { version: 1, prompted: [], ownWrites: [], sessions: {}, spawnedSessions: [], spawnedHashes: [] }
+}
+
+function finiteInt(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : 0
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const entry of value) {
+    if (typeof entry === "string" && !seen.has(entry)) {
+      seen.add(entry)
+      out.push(entry)
+    }
+  }
+  return out.slice(-MAX_ENTRIES)
+}
+
+function coerceSession(value: unknown): SessionState {
+  const obj = value && typeof value === "object" ? (value as Record<string, unknown>) : {}
+  const session: SessionState = {
+    autoRounds: finiteInt(obj.autoRounds),
+    lastPromptAt: finiteInt(obj.lastPromptAt),
+  }
+  if (typeof obj.lastNoticeAt === "number" && Number.isFinite(obj.lastNoticeAt)) {
+    session.lastNoticeAt = obj.lastNoticeAt
+  }
+  if (typeof obj.noticeKey === "string") {
+    session.noticeKey = obj.noticeKey
+  }
+  if (typeof obj.spawnsThisTurn === "number" && Number.isFinite(obj.spawnsThisTurn)) {
+    session.spawnsThisTurn = Math.max(0, Math.floor(obj.spawnsThisTurn))
+  }
+  return session
+}
+
+function coerce(value: unknown): MailboxState {
+  if (!value || typeof value !== "object") return emptyState()
+  const obj = value as Record<string, unknown>
+  const sessions: Record<string, SessionState> = {}
+  if (obj.sessions && typeof obj.sessions === "object") {
+    for (const [key, entry] of Object.entries(obj.sessions as Record<string, unknown>)) {
+      sessions[key] = coerceSession(entry)
+    }
+  }
+  return {
+    version: 1,
+    prompted: asStringArray(obj.prompted),
+    ownWrites: asStringArray(obj.ownWrites),
+    sessions,
+    spawnedSessions: asStringArray(obj.spawnedSessions),
+    spawnedHashes: asStringArray(obj.spawnedHashes),
+    ...(typeof obj.lastSpawnAt === "number" && Number.isFinite(obj.lastSpawnAt)
+      ? { lastSpawnAt: obj.lastSpawnAt }
+      : {}),
+  }
+}
+
+export class StateStore {
+  private file: string
+  private now: () => number
+
+  constructor(file: string, now?: () => number) {
+    this.file = file
+    this.now = now ?? (() => Date.now())
+  }
+
+  read(): MailboxState {
+    if (!existsSync(this.file)) return emptyState()
+    try {
+      const raw = readFileSync(this.file, "utf8")
+      return coerce(JSON.parse(raw))
+    } catch {
+      return emptyState()
+    }
+  }
+
+  write(state: MailboxState): void {
+    const clean = coerce(state)
+    mkdirSync(path.dirname(this.file), { recursive: true })
+    const tmp = `${this.file}.tmp`
+    writeFileSync(tmp, JSON.stringify(clean, null, 2), "utf8")
+    renameSync(tmp, this.file)
+  }
+
+  update(mutator: (state: MailboxState) => void): MailboxState {
+    const state = this.read()
+    mutator(state)
+    this.write(state)
+    return state
+  }
+}

package/src/store.ts

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { ackMessage, readMailbox, sendMessage, type AckResult, type SendResult } from "./mailbox.js"
+import { mailboxFile } from "./paths.js"
+import type { MailboxMessage } from "./parser.js"
+
+export type MailboxFilter = {
+  status?: string
+  topicContains?: string
+  limit?: number
+}
+
+export type AppendInput = {
+  from: string
+  topic: string
+  body: string
+  status?: "OPEN" | "DONE"
+  now?: Date
+}
+
+/**
+ * Storage contract. The file backend is the MVP; a SQLite backend only has to
+ * implement these five operations to replace it without touching the tools,
+ * the wake path, or spawn-on-send.
+ */
+export interface MailboxStore {
+  readonly kind: string
+  readonly dir: string
+  /** Create the project's mailbox file if it is missing; returns its path. */
+  ensure(project: string): string
+  listOpen(project: string): MailboxMessage[]
+  read(project: string): MailboxMessage[]
+  append(project: string, input: AppendInput): SendResult
+  ack(project: string, target: { hash?: string; header?: string }): AckResult
+  query(project: string, filter?: MailboxFilter): MailboxMessage[]
+}
+
+export function createFileStore(dir: string): MailboxStore {
+  const root = path.resolve(dir)
+  const fileFor = (project: string): string => mailboxFile(root, project)
+
+  return {
+    kind: "file",
+    dir: root,
+    ensure(project: string): string {
+      const target = fileFor(project)
+      if (!existsSync(target)) {
+        mkdirSync(path.dirname(target), { recursive: true })
+        writeFileSync(
+          target,
+          `# ${project} mailbox\n\nMessages addressed to \`${project}\`. Append-only.\n`,
+          "utf8",
+        )
+      }
+      return target
+    },
+    listOpen(project: string): MailboxMessage[] {
+      return readMailbox(fileFor(project)).open
+    },
+    read(project: string): MailboxMessage[] {
+      return readMailbox(fileFor(project)).messages
+    },
+    append(project: string, input: AppendInput): SendResult {
+      return sendMessage({
+        mailboxDir: root,
+        to: project,
+        from: input.from,
+        topic: input.topic,
+        body: input.body,
+        status: input.status,
+        now: input.now,
+      })
+    },
+    ack(project: string, target: { hash?: string; header?: string }): AckResult {
+      return ackMessage({ file: fileFor(project), hash: target.hash, header: target.header })
+    },
+    query(project: string, filter: MailboxFilter = {}): MailboxMessage[] {
+      let list = readMailbox(fileFor(project)).messages
+      if (filter.status) {
+        const wanted = filter.status.toUpperCase()
+        list = list.filter((message) => message.status === wanted)
+      }
+      if (filter.topicContains) {
+        const needle = filter.topicContains.toLowerCase()
+        list = list.filter((message) => message.topic.toLowerCase().includes(needle))
+      }
+      if (filter.limit && filter.limit > 0) list = list.slice(-filter.limit)
+      return list
+    },
+  }
+}