popilot 0.5.0 → 0.7.0

package/scaffold/pm-api/src/mcp-tools/story.ts

@@ -0,0 +1,230 @@
+import { query, execute } from '../db/adapter.js'
+import { text, err, today, resolveSprint, notify, checkRateLimit, emitAgentEvent, validateAssignee, resolveMemberId, type ToolResult } from './utils.js'
+
+export async function toolListStories(args: Record<string, unknown>): Promise<ToolResult> {
+  const isBacklog = (args.sprint as string)?.toLowerCase() === 'backlog'
+  const sprint = isBacklog ? null : await resolveSprint(args.sprint as string | undefined)
+  if (!isBacklog && !sprint) return err('Please specify a sprint.')
+
+  let sql = `SELECT s.id, s.title, s.status, s.priority, s.assignee, s.area, s.story_points,
+             e.id as epic_id, e.title as epic_title
+             FROM pm_stories s LEFT JOIN pm_epics e ON s.epic_id = e.id`
+  const sqlArgs: (string | number)[] = []
+
+  if (isBacklog) {
+    sql += ' WHERE s.sprint IS NULL'
+  } else {
+    sql += ' WHERE s.sprint = ?'
+    sqlArgs.push(sprint!)
+  }
+
+  if (args.epic_id !== undefined) { sql += ' AND s.epic_id = ?'; sqlArgs.push(args.epic_id as number) }
+  if (args.status) { sql += ' AND s.status = ?'; sqlArgs.push(args.status as string) }
+  if (args.assignee) { sql += ' AND s.assignee LIKE ?'; sqlArgs.push(`%${args.assignee as string}%`) }
+  sql += ' ORDER BY e.title, s.sort_order'
+
+  const result = await query<{
+    id: number; title: string; status: string; priority: string; assignee: string | null
+    area: string; story_points: number | null; epic_id: number | null; epic_title: string | null
+  }>(sql, sqlArgs)
+  if (result.error) return err(result.error)
+  const label = isBacklog ? 'Backlog' : sprint!.toUpperCase()
+  if (result.rows.length === 0) return text(`No stories in ${label}.`)
+
+  const statusIcon: Record<string, string> = { draft: '📝', backlog: '📋', ready: '🟡', 'in-progress': '🔵', review: '🟣', done: '✅' }
+  const priorityIcon: Record<string, string> = { low: '⬇️', medium: '➡️', high: '⬆️', critical: '🔴' }
+
+  const lines = [`📖 ${label} Stories (${result.rows.length})`, '─────────────']
+  let lastEpic: string | null = null
+  for (const s of result.rows) {
+    const epic = s.epic_title ?? '(No epic)'
+    if (epic !== lastEpic) { lines.push(`\n🏷 ${epic}`); lastEpic = epic }
+    const pts = s.story_points ? ` ${s.story_points}pt` : ''
+    lines.push(`  ${statusIcon[s.status] ?? '⬜'} [S${s.id}] ${s.title} ${priorityIcon[s.priority] ?? ''}${pts} (${s.assignee ?? 'Unassigned'})`)
+  }
+  return text(lines.join('\n'))
+}
+
+export async function toolListBacklog(args: Record<string, unknown>): Promise<ToolResult> {
+  let sql = `SELECT s.id, s.title, s.status, s.priority, s.assignee, s.area, s.story_points,
+             e.id as epic_id, e.title as epic_title
+             FROM pm_stories s LEFT JOIN pm_epics e ON s.epic_id = e.id WHERE s.sprint IS NULL`
+  const sqlArgs: (string | number)[] = []
+
+  if (args.epic_id !== undefined) { sql += ' AND s.epic_id = ?'; sqlArgs.push(args.epic_id as number) }
+  if (args.status) { sql += ' AND s.status = ?'; sqlArgs.push(args.status as string) }
+  if (args.assignee) { sql += ' AND s.assignee LIKE ?'; sqlArgs.push(`%${args.assignee as string}%`) }
+  sql += ' ORDER BY e.title, s.sort_order'
+
+  const result = await query<{
+    id: number; title: string; status: string; priority: string; assignee: string | null
+    area: string; story_points: number | null; epic_id: number | null; epic_title: string | null
+  }>(sql, sqlArgs)
+  if (result.error) return err(result.error)
+  if (result.rows.length === 0) return text('No stories in backlog.')
+
+  const statusIcon: Record<string, string> = { draft: '📝', backlog: '📋', ready: '🟡', 'in-progress': '🔵', review: '🟣', done: '✅' }
+  const priorityIcon: Record<string, string> = { low: '⬇️', medium: '➡️', high: '⬆️', critical: '🔴' }
+
+  const lines = [`📦 Backlog Stories (${result.rows.length})`, '─────────────']
+  let lastEpic: string | null = null
+  for (const s of result.rows) {
+    const epic = s.epic_title ?? '(No epic)'
+    if (epic !== lastEpic) { lines.push(`\n🏷 ${epic}`); lastEpic = epic }
+    const pts = s.story_points ? ` ${s.story_points}pt` : ''
+    lines.push(`  ${statusIcon[s.status] ?? '⬜'} [S${s.id}] ${s.title} ${priorityIcon[s.priority] ?? ''}${pts} (${s.assignee ?? 'Unassigned'})`)
+  }
+  return text(lines.join('\n'))
+}
+
+export async function toolAddStory(user: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const title = args.title as string
+  const sprintArg = args.sprint as string | undefined
+  const isBacklog = !sprintArg || sprintArg.toLowerCase() === 'backlog'
+  const sprint = isBacklog ? null : await resolveSprint(sprintArg)
+
+  const epicId = (args.epic_id as number) ?? null
+  const description = (args.description as string) ?? null
+  const acceptanceCriteria = (args.acceptance_criteria as string) ?? null
+  const assignee = (args.assignee as string) ?? null
+  const assigneeErr = await validateAssignee(assignee)
+  if (assigneeErr) return err(assigneeErr)
+  const assigneeId = assignee ? await resolveMemberId(assignee) : null
+  const priority = (args.priority as string) || 'medium'
+  const area = (args.area as string) || 'FE'
+  const storyPoints = (args.story_points as number) ?? null
+
+  const maxResult = sprint
+    ? await query<{ max_order: number | null }>('SELECT MAX(sort_order) as max_order FROM pm_stories WHERE sprint = ?', [sprint])
+    : await query<{ max_order: number | null }>('SELECT MAX(sort_order) as max_order FROM pm_stories WHERE sprint IS NULL')
+  const sortOrder = (maxResult.rows[0]?.max_order ?? -1) + 1
+
+  const epicUid = epicId ? `pm:${epicId}` : 'pm:0'
+
+  const result = await execute(
+    'INSERT INTO pm_stories (epic_id, epic_uid, sprint, title, description, acceptance_criteria, assignee, assignee_id, status, priority, area, story_points, sort_order, start_date, due_date) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [epicId, epicUid, sprint, title, description, acceptanceCriteria, assignee, assigneeId, 'backlog', priority, area, storyPoints, sortOrder, (args.start_date as string) ?? null, (args.due_date as string) ?? null],
+  )
+  if (result.error) return err(result.error)
+  const idResult = await query<{ id: number }>('SELECT last_insert_rowid() as id')
+  const newId = idResult.rows[0]?.id ?? '?'
+
+  // Notify assignee(s)
+  if (assignee) {
+    for (const a of assignee.split(',').map(s => s.trim()).filter(Boolean)) {
+      await notify(a, 'story_assigned', `Story assigned: ${title}`, `${user} assigned story [S${newId}].`, 'story', String(newId), 'board', user)
+    }
+  }
+
+  const epicLabel = epicId ? ` (Epic #${epicId})` : ''
+  const sprintLabel = sprint ? sprint.toUpperCase() : 'Backlog'
+  return text(`✅ Story created${epicLabel}: ${title} (ID: ${newId}, ${sprintLabel})`)
+}
+
+export async function toolUpdateStory(user: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const storyId = args.story_id as number
+
+  // Get current story for notification comparison
+  const current = await query<{ assignee: string | null; title: string }>(
+    'SELECT assignee, title FROM pm_stories WHERE id = ?', [storyId],
+  )
+  if (current.error) return err(current.error)
+  if (current.rows.length === 0) return err(`Story #${storyId} not found.`)
+  const oldAssignee = current.rows[0].assignee
+  const storyTitle = current.rows[0].title
+
+  if (args.assignee !== undefined) {
+    const assigneeErr = await validateAssignee(args.assignee as string | null)
+    if (assigneeErr) return err(assigneeErr)
+  }
+
+  // Normalize sprint='backlog' to NULL
+  if (args.sprint !== undefined) {
+    const sv = args.sprint as string | null
+    if (sv === null || (typeof sv === 'string' && sv.toLowerCase() === 'backlog')) {
+      args.sprint = null
+    }
+  }
+
+  const fieldMap: Record<string, string> = {
+    title: 'title', description: 'description', acceptance_criteria: 'acceptance_criteria',
+    assignee: 'assignee', status: 'status', priority: 'priority', area: 'area',
+    story_points: 'story_points', figma_url: 'figma_url', epic_id: 'epic_id', sprint: 'sprint',
+  }
+  const sets: string[] = []
+  const sqlArgs: (string | number | null)[] = []
+
+  for (const [key, col] of Object.entries(fieldMap)) {
+    if (args[key] !== undefined) {
+      sets.push(`${col} = ?`)
+      sqlArgs.push(args[key] as string | number | null)
+    }
+  }
+
+  // Also update assignee_id when assignee changes
+  if (args.assignee !== undefined) {
+    const newAssignee = args.assignee as string | null
+    const newAssigneeId = newAssignee ? await resolveMemberId(newAssignee) : null
+    sets.push('assignee_id = ?')
+    sqlArgs.push(newAssigneeId)
+  }
+
+  if (sets.length === 0) return text('No fields to update.')
+
+  sets.push('updated_at = CURRENT_TIMESTAMP')
+  sqlArgs.push(storyId)
+  const result = await execute(`UPDATE pm_stories SET ${sets.join(', ')} WHERE id = ?`, sqlArgs)
+  if (result.error) return err(result.error)
+  if (result.rowsAffected === 0) return err(`Story #${storyId} not found.`)
+
+  // Notify new assignee(s) on assignment change
+  if (args.assignee !== undefined) {
+    const newAssignee = args.assignee as string | null
+    if (newAssignee) {
+      const oldSet = new Set((oldAssignee ?? '').split(',').map(s => s.trim()).filter(Boolean))
+      for (const a of newAssignee.split(',').map(s => s.trim()).filter(Boolean)) {
+        if (!oldSet.has(a)) {
+          await notify(a, 'story_assigned', `Story assigned: ${storyTitle}`, `${user} assigned story [S${storyId}].`, 'story', String(storyId), 'board', user)
+        }
+      }
+    }
+  }
+
+  // Agent webhook notification (on status change)
+  if (args.status !== undefined) {
+    const assignee = (args.assignee as string) ?? oldAssignee
+    if (assignee) {
+      const { notifyByName } = await import('../utils/agent-notify.js')
+      await notifyByName(assignee, `📌 Status changed`, `S${storyId}: ${storyTitle}\nStatus: ${args.status}`)
+    }
+  }
+
+  return text(`✅ Story #${storyId} updated`)
+}
+
+export async function toolDeleteStory(args: Record<string, unknown>): Promise<ToolResult> {
+  const storyId = args.story_id as number
+  const r1 = await execute('DELETE FROM pm_tasks WHERE story_id = ?', [storyId])
+  if (r1.error) return err(r1.error)
+  const r2 = await execute('DELETE FROM pm_stories WHERE id = ?', [storyId])
+  if (r2.error) return err(r2.error)
+  if (r2.rowsAffected === 0) return err(`Story #${storyId} not found.`)
+  return text(`✅ Story #${storyId} deleted (${r1.rowsAffected} tasks also deleted)`)
+}
+
+export async function toolAssignStory(args: Record<string, unknown>): Promise<ToolResult> {
+  const storyId = args.story_id as number
+  const sprintId = args.sprint_id as string
+  if (!storyId || !sprintId) return err('story_id, sprint_id required')
+  const r = await execute('UPDATE pm_stories SET sprint = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?', [sprintId, storyId])
+  if (r.error) return err(r.error)
+  return text(`✅ S${storyId} → ${sprintId} assigned`)
+}
+
+export async function toolUnassignStory(args: Record<string, unknown>): Promise<ToolResult> {
+  const storyId = args.story_id as number
+  if (!storyId) return err('story_id required')
+  const r = await execute('UPDATE pm_stories SET sprint = NULL, updated_at = CURRENT_TIMESTAMP WHERE id = ?', [storyId])
+  if (r.error) return err(r.error)
+  return text(`✅ S${storyId} → backlog unassigned`)
+}

package/scaffold/pm-api/src/mcp-tools/task.ts

@@ -0,0 +1,187 @@
+import { query, execute } from '../db/adapter.js'
+import { text, err, today, resolveSprint, notify, checkRateLimit, emitAgentEvent, validateAssignee, resolveMemberId, type ToolResult } from './utils.js'
+
+export async function toolListTasks(user: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const sprint = await resolveSprint(args.sprint as string | undefined)
+  if (!sprint) return err('Please specify a sprint.')
+  const status = args.status as string | undefined
+
+  let sql = `SELECT t.id as task_id, t.title as task_title, t.status as task_status, s.id as story_id, s.title as story_title, e.id as epic_id, e.title as epic_title FROM pm_tasks t JOIN pm_stories s ON t.story_id = s.id LEFT JOIN pm_epics e ON s.epic_id = e.id WHERE t.assignee = ? AND s.sprint = ?`
+  const sqlArgs: (string | number)[] = [user, sprint]
+  if (status) { sql += ' AND t.status = ?'; sqlArgs.push(status) }
+  sql += ' ORDER BY e.title, s.sort_order, t.sort_order'
+
+  const result = await query<{ task_id: number; task_title: string; task_status: string; story_id: number; story_title: string; epic_id: number | null; epic_title: string | null }>(sql, sqlArgs)
+  if (result.error) return err(result.error)
+  if (result.rows.length === 0) return text(`No tasks found for ${user}.`)
+
+  const statusIcon: Record<string, string> = { todo: '⬜', 'in-progress': '🔵', done: '✅' }
+  const tree = new Map<string, Map<string, Array<{ id: number; title: string; status: string }>>>()
+  for (const r of result.rows) {
+    const ek = r.epic_title ?? '(No epic)'
+    if (!tree.has(ek)) tree.set(ek, new Map())
+    const em = tree.get(ek)!
+    const sk = `[S${r.story_id}] ${r.story_title}`
+    if (!em.has(sk)) em.set(sk, [])
+    em.get(sk)!.push({ id: r.task_id, title: r.task_title, status: r.task_status })
+  }
+
+  const lines: string[] = [`📋 ${user}'s Tasks (${sprint.toUpperCase()})`, '─────────────']
+  for (const [epicTitle, stories] of tree) {
+    lines.push(`\n🏷 ${epicTitle}`)
+    for (const [storyTitle, tasks] of stories) {
+      lines.push(`  📖 ${storyTitle}`)
+      for (const t of tasks) lines.push(`    ${statusIcon[t.status] ?? '⬜'} [T${t.id}] ${t.title}`)
+    }
+  }
+  return text(lines.join('\n'))
+}
+
+export async function toolGetTask(args: Record<string, unknown>): Promise<ToolResult> {
+  const taskId = args.task_id as number
+  const taskResult = await query<{ id: number; story_id: number; title: string; assignee: string | null; status: string; description: string | null; sort_order: number; created_at: string; updated_at: string }>('SELECT * FROM pm_tasks WHERE id = ?', [taskId])
+  if (taskResult.error) return err(taskResult.error)
+  if (taskResult.rows.length === 0) return err(`Task #${taskId} not found.`)
+
+  const t = taskResult.rows[0]
+  const [storyResult, siblingsResult] = await Promise.all([
+    query<{ id: number; title: string; description: string | null; acceptance_criteria: string | null; assignee: string | null; status: string; sprint: string }>('SELECT id, title, description, acceptance_criteria, assignee, status, sprint FROM pm_stories WHERE id = ?', [t.story_id]),
+    query<{ id: number; title: string; status: string; assignee: string | null }>('SELECT id, title, status, assignee FROM pm_tasks WHERE story_id = ? ORDER BY sort_order', [t.story_id]),
+  ])
+
+  const si: Record<string, string> = { todo: '⬜', 'in-progress': '🔵', done: '✅' }
+  const s = storyResult.rows[0]
+  const lines = [`📋 Task #${t.id}: ${t.title}`, '─────────────', `Status: ${si[t.status] ?? '⬜'} ${t.status}`, `Assignee: ${t.assignee ?? 'Unassigned'}`, t.description ? `Description: ${t.description}` : '', `Created: ${t.created_at} | Modified: ${t.updated_at}`].filter(Boolean)
+  if (s) {
+    lines.push('', `📖 Parent Story [S${s.id}]: ${s.title}`, `  Sprint: ${s.sprint} | Status: ${s.status} | Assignee: ${s.assignee ?? 'Unassigned'}`)
+    if (s.description) lines.push(`  Description: ${s.description}`)
+    if (s.acceptance_criteria) lines.push(`  AC: ${s.acceptance_criteria}`)
+  }
+  if (siblingsResult.rows.length > 0) {
+    lines.push('', '👥 Sibling Tasks:')
+    for (const sb of siblingsResult.rows) {
+      const marker = sb.id === taskId ? ' ← current' : ''
+      lines.push(`  ${si[sb.status] ?? '⬜'} [T${sb.id}] ${sb.title} (${sb.assignee ?? 'Unassigned'})${marker}`)
+    }
+  }
+  return text(lines.join('\n'))
+}
+
+export async function toolUpdateTaskStatus(args: Record<string, unknown>): Promise<ToolResult> {
+  const taskId = args.task_id as number
+  const status = args.status as string
+  const result = await execute('UPDATE pm_tasks SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?', [status, taskId])
+  if (result.error) return err(result.error)
+  if (result.rowsAffected === 0) return err(`Task #${taskId} not found.`)
+  return text(`✅ Task #${taskId} → ${status}`)
+}
+
+export async function toolUpdateTask(user: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const taskId = args.task_id as number
+
+  // Get current for notification
+  const current = await query<{ assignee: string | null; title: string }>(
+    'SELECT assignee, title FROM pm_tasks WHERE id = ?', [taskId],
+  )
+  if (current.error) return err(current.error)
+  if (current.rows.length === 0) return err(`Task #${taskId} not found.`)
+  const oldAssignee = current.rows[0].assignee
+  const taskTitle = current.rows[0].title
+
+  if (args.assignee !== undefined) {
+    const assigneeErr = await validateAssignee(args.assignee as string | null)
+    if (assigneeErr) return err(assigneeErr)
+  }
+
+  const fieldMap: Record<string, string> = { title: 'title', assignee: 'assignee', status: 'status', description: 'description', story_points: 'story_points' }
+  const sets: string[] = []
+  const sqlArgs: (string | number | null)[] = []
+
+  for (const [key, col] of Object.entries(fieldMap)) {
+    if (args[key] !== undefined) {
+      sets.push(`${col} = ?`)
+      sqlArgs.push(args[key] as string | number | null)
+    }
+  }
+
+  // Also update assignee_id when assignee changes
+  if (args.assignee !== undefined) {
+    const newAssignee = args.assignee as string | null
+    const newAssigneeId = newAssignee ? await resolveMemberId(newAssignee) : null
+    sets.push('assignee_id = ?')
+    sqlArgs.push(newAssigneeId)
+  }
+
+  if (sets.length === 0) return text('No fields to update.')
+
+  sets.push('updated_at = CURRENT_TIMESTAMP')
+  sqlArgs.push(taskId)
+  const result = await execute(`UPDATE pm_tasks SET ${sets.join(', ')} WHERE id = ?`, sqlArgs)
+  if (result.error) return err(result.error)
+
+  // Auto-sum story SP when task SP changes
+  if (args.story_points !== undefined) {
+    const storyResult = await query<{ story_id: number }>('SELECT story_id FROM pm_tasks WHERE id = ?', [taskId])
+    if (!storyResult.error && storyResult.rows.length > 0) {
+      const sid = storyResult.rows[0].story_id
+      const spResult = await query<{ total: number | null }>('SELECT SUM(story_points) as total FROM pm_tasks WHERE story_id = ?', [sid])
+      if (!spResult.error && spResult.rows.length > 0) {
+        await execute('UPDATE pm_stories SET story_points = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?', [spResult.rows[0].total ?? 0, sid])
+      }
+    }
+  }
+
+  // Notify on assignee change
+  if (args.assignee !== undefined) {
+    const newAssignee = args.assignee as string | null
+    if (newAssignee && newAssignee !== oldAssignee) {
+      await notify(newAssignee, 'task_assigned', `Task assigned: ${taskTitle}`, `${user} assigned task [T${taskId}].`, 'task', String(taskId), 'board', user)
+    }
+  }
+
+  return text(`✅ Task #${taskId} updated`)
+}
+
+export async function toolAddTask(user: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const storyId = args.story_id as number
+  const title = args.title as string
+  const assignee = (args.assignee as string) || user
+  const assigneeErr = await validateAssignee(assignee)
+  if (assigneeErr) return err(assigneeErr)
+  const assigneeId = await resolveMemberId(assignee)
+  const description = args.description as string | undefined
+
+  const storyPoints = (args.story_points as number) ?? null
+
+  const maxResult = await query<{ max_order: number | null }>('SELECT MAX(sort_order) as max_order FROM pm_tasks WHERE story_id = ?', [storyId])
+  const sortOrder = (maxResult.rows[0]?.max_order ?? -1) + 1
+  const result = await execute('INSERT INTO pm_tasks (story_id, title, assignee, assignee_id, description, sort_order, story_points) VALUES (?, ?, ?, ?, ?, ?, ?)', [storyId, title, assignee, assigneeId, description ?? null, sortOrder, storyPoints])
+  if (result.error) return err(result.error)
+
+  const idResult = await query<{ id: number }>('SELECT last_insert_rowid() as id')
+  const newId = idResult.rows[0]?.id ?? '?'
+
+  // Auto-sum story SP
+  if (storyPoints != null) {
+    const spResult = await query<{ total: number | null }>('SELECT SUM(story_points) as total FROM pm_tasks WHERE story_id = ?', [storyId])
+    if (!spResult.error && spResult.rows.length > 0) {
+      await execute('UPDATE pm_stories SET story_points = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?', [spResult.rows[0].total ?? 0, storyId])
+    }
+  }
+
+  // Notify assignee
+  if (assignee !== user) {
+    await notify(assignee, 'task_assigned', `Task assigned: ${title}`, `${user} assigned task [T${newId}].`, 'task', String(newId), 'board', user)
+  }
+
+  const spLabel = storyPoints != null ? ` ${storyPoints}SP` : ''
+  return text(`✅ Task added (Story #${storyId}): ${title}${spLabel} (ID: ${newId})`)
+}
+
+export async function toolDeleteTask(args: Record<string, unknown>): Promise<ToolResult> {
+  const taskId = args.task_id as number
+  const result = await execute('DELETE FROM pm_tasks WHERE id = ?', [taskId])
+  if (result.error) return err(result.error)
+  if (result.rowsAffected === 0) return err(`Task #${taskId} not found.`)
+  return text(`✅ Task #${taskId} deleted`)
+}

package/scaffold/pm-api/src/mcp-tools/utils.ts

@@ -0,0 +1,83 @@
+import { query, execute } from '../db/adapter.js'
+
+export type ToolResult = { content: Array<{ type: string; text: string }>; isError?: boolean }
+
+export function today(): string {
+  const d = new Date()
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+export function text(t: string): ToolResult {
+  return { content: [{ type: 'text', text: t }] }
+}
+
+export function err(msg: string): ToolResult {
+  return text(`Error: ${msg}`)
+}
+
+export async function getActiveSprint(): Promise<string | null> {
+  const result = await query<{ id: string }>('SELECT id FROM nav_sprints WHERE active = 1 LIMIT 1')
+  return result.rows?.[0]?.id ?? null
+}
+
+export async function resolveSprint(arg?: string): Promise<string | null> {
+  return arg || await getActiveSprint()
+}
+
+export async function notify(
+  userName: string, type: string, title: string, body: string,
+  sourceType: string, sourceId: string | number, pageId: string, actor: string,
+): Promise<void> {
+  if (userName === actor) return
+  await execute(
+    'INSERT INTO notifications (user_name, type, title, body, source_type, source_id, page_id, actor) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+    [userName, type, title, body, sourceType, String(sourceId), pageId, actor],
+  )
+}
+
+export { validateAssignee, resolveMemberId } from '../utils/assignee.js'
+
+const RATE_LIMIT = 30
+const emitRateMap = new Map<string, number[]>()
+
+export function checkRateLimit(user: string): boolean {
+  const now = Date.now()
+  const window = 60_000
+  if (emitRateMap.size > 100) {
+    for (const [k, v] of emitRateMap) {
+      const filtered = v.filter(t => now - t < window)
+      if (filtered.length === 0) emitRateMap.delete(k)
+      else emitRateMap.set(k, filtered)
+    }
+  }
+  const timestamps = (emitRateMap.get(user) ?? []).filter(t => now - t < window)
+  if (timestamps.length >= RATE_LIMIT) return false
+  timestamps.push(now)
+  emitRateMap.set(user, timestamps)
+  return true
+}
+
+export async function emitAgentEvent(
+  eventType: string, sourceAgent: string, targetAgent: string,
+  targetUser: string, payload: Record<string, unknown>,
+): Promise<void> {
+  try {
+    const expiresAt = new Date(Date.now() + 24 * 3600_000).toISOString()
+    await execute(
+      `INSERT INTO agent_events (event_type, source_agent, target_agent, target_user, payload, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [eventType, sourceAgent, targetAgent, targetUser, JSON.stringify(payload), expiresAt],
+    )
+  } catch {
+    // fire-and-forget
+  }
+}
+
+export function progressBar(done: number, total: number, width = 10): string {
+  if (total === 0) return '░'.repeat(width)
+  const filled = Math.round((done / total) * width)
+  return '█'.repeat(filled) + '░'.repeat(width - filled)
+}