opencode-workspace-mailbox 0.0.0-stage → 0.1.0

package/src/config.ts

@@ -0,0 +1,133 @@
+import path from "node:path"
+import { assertInside, isSafeRecipient } from "./paths.js"
+
+export type MailboxConfig = {
+  mailboxDir?: string
+  project?: string | null
+  maxAutoRounds?: number
+  cooldownMs?: number
+  enabled?: boolean
+  stateFile?: string | null
+  wake?: boolean
+  pollMs?: number
+  spawnOnSend?: boolean
+  spawnCooldownMs?: number
+  maxSpawnsPerTurn?: number
+  projectDirs?: Record<string, string>
+}
+
+export type NormalizedConfig = {
+  mailboxDir: string
+  project: string
+  /** True when mailboxDir came from options (disables folder-tree discovery). */
+  explicitMailboxDir: boolean
+  storage: "file"
+  maxAutoRounds: number
+  cooldownMs: number
+  enabled: boolean
+  stateFile: string
+  wake: boolean
+  pollMs: number
+  spawnOnSend: boolean
+  spawnCooldownMs: number
+  maxSpawnsPerTurn: number
+  projectDirs: Record<string, string>
+}
+
+function clampInt(value: unknown, def: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return def
+  return Math.min(max, Math.max(min, Math.floor(value)))
+}
+
+function nonNegativeInt(value: unknown, def: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return def
+  return Math.max(0, Math.floor(value))
+}
+
+/** Turn an arbitrary directory name into a lowercase kebab-case recipient id. */
+function toKebab(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function isStrictlyInside(base: string, candidate: string): boolean {
+  const rel = path.relative(path.resolve(base), path.resolve(candidate))
+  return rel !== "" && !path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + path.sep)
+}
+
+export function normalizeConfig(
+  options: Record<string, unknown> | undefined,
+  directory: string,
+): NormalizedConfig {
+  const opts = options ?? {}
+
+  const configuredMailboxDir =
+    typeof opts.mailboxDir === "string" && opts.mailboxDir.length > 0 ? opts.mailboxDir : null
+  const mailboxDir = path.resolve(configuredMailboxDir ?? path.join(directory, "handoffs"))
+  // Only the file backend is implemented today; the field exists so a SQLite
+  // backend can be selected later without a config-format change.
+  const storage: "file" = "file"
+
+  const rawProject = opts.project
+  const configuredProject = typeof rawProject === "string" && rawProject.length > 0 ? rawProject : null
+  // Identity is resolved per session, not per config:
+  //   explicit `project` wins; otherwise a session whose directory *contains*
+  //   the shared mailbox directory is the workspace parent, and every other
+  //   session uses its own directory name. The containment rule only applies to
+  //   an explicitly configured mailboxDir, so the per-project default
+  //   (`<directory>/handoffs`) never turns every project into the parent.
+  const project =
+    configuredProject ??
+    (configuredMailboxDir !== null && isStrictlyInside(directory, mailboxDir)
+      ? "workspace"
+      : toKebab(path.basename(path.resolve(directory))))
+  if (!isSafeRecipient(project)) {
+    throw new Error(
+      configuredProject !== null
+        ? `Invalid project name "${configuredProject}": must be lowercase kebab-case`
+        : `Cannot derive a valid project name from "${directory}": set the "project" plugin option`,
+    )
+  }
+
+  const maxAutoRounds = clampInt(opts.maxAutoRounds, 2, 0, 20)
+  const cooldownMs = nonNegativeInt(opts.cooldownMs, 30000)
+  const enabled = typeof opts.enabled === "boolean" ? opts.enabled : true
+  const wake = typeof opts.wake === "boolean" ? opts.wake : false
+  const pollMs = clampInt(opts.pollMs, 10000, 100, 600000)
+  const spawnOnSend = typeof opts.spawnOnSend === "boolean" ? opts.spawnOnSend : false
+  const spawnCooldownMs = nonNegativeInt(opts.spawnCooldownMs, 60000)
+  const maxSpawnsPerTurn = clampInt(opts.maxSpawnsPerTurn, 1, 0, 10)
+  const projectDirs: Record<string, string> = {}
+  if (opts.projectDirs && typeof opts.projectDirs === "object" && !Array.isArray(opts.projectDirs)) {
+    for (const [key, value] of Object.entries(opts.projectDirs as Record<string, unknown>)) {
+      if (typeof value === "string" && value.length > 0 && isSafeRecipient(key)) {
+        projectDirs[key] = path.resolve(value)
+      }
+    }
+  }
+
+  const rawStateFile =
+    typeof opts.stateFile === "string" && opts.stateFile.length > 0
+      ? opts.stateFile
+      : path.join(directory, ".atl", "mailbox-state.json")
+  const stateFile = assertInside(directory, rawStateFile, "stateFile")
+
+  return {
+    mailboxDir,
+    project,
+    explicitMailboxDir: configuredMailboxDir !== null,
+    storage,
+    maxAutoRounds,
+    cooldownMs,
+    enabled,
+    stateFile,
+    wake,
+    pollMs,
+    spawnOnSend,
+    spawnCooldownMs,
+    maxSpawnsPerTurn,
+    projectDirs,
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,133 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+
+export type Tier = "meta" | "account" | "repo" | "custom"
+
+export type TierContext = {
+  tier: Tier
+  /** Mailbox identity inside its own tier: "workspace" for a tier root, else the directory name. */
+  project: string
+  /** Directory holding this tier's files: `<tierRoot>/handoffs`. */
+  mailboxDir: string
+  /** Session directory the context was derived from. */
+  directory: string
+  /** The account directory (account or repo tier). */
+  accountRoot?: string
+  accountName?: string
+  /** The workspace root directory (meta tier, or the ancestor above an account). */
+  rootDir?: string
+  /** The root tier's handoffs directory, when one exists above this tier. */
+  rootMailboxDir?: string
+}
+
+function kebab(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+}
+
+function hasHandoffs(dir: string): boolean {
+  return existsSync(path.join(dir, "handoffs", "workspace.md")) || existsSync(path.join(dir, "handoffs"))
+}
+
+/**
+ * Derive the tier from the folder tree:
+ *
+ *   - a directory with its own `handoffs/` is a tier root: meta when nothing
+ *     above it has one, account when the parent does;
+ *   - anything else belongs to the nearest ancestor that has one (repo tier),
+ *     whatever the bucket depth (`<account>/tools/<repo>` still resolves);
+ *   - an explicit `mailboxDir` in config overrides discovery entirely.
+ */
+export function discoverTier(
+  directory: string,
+  explicit?: { mailboxDir?: string; project?: string },
+): TierContext {
+  const dir = path.resolve(directory)
+
+  if (explicit?.mailboxDir) {
+    const mailboxDir = path.resolve(explicit.mailboxDir)
+    const inside = isStrictlyInside(dir, mailboxDir)
+    return {
+      tier: "custom",
+      project: explicit.project ?? (inside ? "workspace" : kebab(path.basename(dir))),
+      mailboxDir,
+      directory: dir,
+      rootDir: inside ? path.dirname(mailboxDir) : undefined,
+      rootMailboxDir: inside ? mailboxDir : undefined,
+    }
+  }
+
+  if (hasHandoffs(dir)) {
+    const parent = path.dirname(dir)
+    const above = parent !== dir && hasHandoffs(parent)
+    return {
+      tier: above ? "account" : "meta",
+      project: "workspace",
+      mailboxDir: path.join(dir, "handoffs"),
+      directory: dir,
+      accountRoot: above ? dir : undefined,
+      accountName: above ? kebab(path.basename(dir)) : undefined,
+      rootDir: above ? parent : dir,
+      rootMailboxDir: path.join(above ? parent : dir, "handoffs"),
+    }
+  }
+
+  let cursor = dir
+  for (;;) {
+    const parent = path.dirname(cursor)
+    if (parent === cursor) break
+    if (hasHandoffs(parent)) {
+      const grand = path.dirname(parent)
+      return {
+        tier: "repo",
+        project: kebab(path.basename(dir)),
+        mailboxDir: path.join(parent, "handoffs"),
+        directory: dir,
+        accountRoot: parent,
+        accountName: kebab(path.basename(parent)),
+        rootDir: grand,
+        rootMailboxDir: hasHandoffs(grand) ? path.join(grand, "handoffs") : undefined,
+      }
+    }
+    cursor = parent
+  }
+
+  return {
+    tier: "repo",
+    project: kebab(path.basename(dir)),
+    mailboxDir: path.join(dir, "handoffs"),
+    directory: dir,
+  }
+}
+
+export type Route = { mailboxDir: string; project: string }
+
+/**
+ * Where a message addressed to `to` belongs.
+ *   - `workspace`      -> this tier's own inbox (the tier root's `workspace.md`)
+ *   - an account name  -> the root tier's `<account>.md` (escalate up / lateral between accounts)
+ *   - anything else    -> a sibling/child file in this tier (lateral / delegate down)
+ */
+export function routeRecipient(to: string, ctx: TierContext): Route {
+  if (to === "workspace") return { mailboxDir: ctx.mailboxDir, project: "workspace" }
+  if (to === ctx.project) return { mailboxDir: ctx.mailboxDir, project: ctx.project }
+
+  if (ctx.tier !== "meta" && ctx.rootMailboxDir) {
+    const ownAccount = ctx.accountName !== undefined && to === ctx.accountName
+    const siblingAccount =
+      existsSync(path.join(ctx.rootMailboxDir, `${to}.md`)) ||
+      (ctx.rootDir !== undefined && hasHandoffs(path.join(ctx.rootDir, to)))
+    if (ownAccount || siblingAccount) {
+      return { mailboxDir: ctx.rootMailboxDir, project: to }
+    }
+  }
+
+  return { mailboxDir: ctx.mailboxDir, project: to }
+}
+
+function isStrictlyInside(base: string, candidate: string): boolean {
+  const rel = path.relative(path.resolve(base), path.resolve(candidate))
+  return rel !== "" && !path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + path.sep)
+}

package/src/hash.ts

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto"
+
+export function normalizeForHash(text: string): string {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim()
+}
+
+export function messageHash(parts: { header: string; topic: string; body: string }): string {
+  const header = normalizeForHash(parts.header)
+  const topic = normalizeForHash(parts.topic)
+  const body = normalizeForHash(parts.body)
+  return createHash("sha256").update(`${header}\n${topic}\n${body}`).digest("hex").slice(0, 16)
+}