@goodandready/dsh-kanban 0.1.14

package/lib/routes.js

@@ -0,0 +1,256 @@
+// Обработчики HTTP доски.
+//
+// Браузерная половина не имеет доступа ни к хранилищу, ни к службам хоста —
+// она ходит сюда. Обработчики написаны так, чтобы проверяться без HTTP:
+// принимают разобранный вход и хранилище, возвращают объект ответа. Обвязка
+// вокруг req/res живёт в `lib/index.js`.
+//
+// Перехвата чужих маршрутов и промежуточных обработчиков в DSH нет:
+// `ctx.webServer.register` — единственный способ.
+
+import { COLUMN_ORDER, columnsOf, wipLimitField, columnNamesOf } from './config.js'
+import { parsePlan, planItems, planProgress, taskState, queuePosition } from './plan.js'
+import { isStale } from './time.js'
+import { facetsOf, facetsOfTask, groupByRepo, sortByLife } from './filters.js'
+import { parseBody } from './markdown.js'
+
+/** Больше этого тело запроса не читаем: без предела один запрос кладёт хост. */
+export const MAX_BODY_BYTES = 256 * 1024
+
+/**
+ * Запрос с чужого сайта. Изменяющие маршруты правят локальное состояние, и
+ * пускать в них кросс-сайтовый запрос нельзя.
+ */
+export function isTrustedRequest(req) {
+  return req?.headers?.['sec-fetch-site'] !== 'cross-site'
+}
+
+/** Разобрать `/dsh-kanban/task/<id>[/<action>]`; иначе undefined. */
+export function parseTaskPath(pathname) {
+  const m = /^\/dsh-kanban\/task\/([^/]+)(?:\/([a-z]+))?\/?$/.exec(pathname ?? '')
+  if (m === null) return undefined
+  return { id: decodeURIComponent(m[1]), action: m[2] }
+}
+
+/**
+ * Задача с разобранным планом и состоянием.
+ *
+ * Сырую строку плана наружу не отдаём: браузерная половина — отдельный бандл,
+ * она не может позвать `lib/plan.js`, и разбор пришлось бы писать второй раз.
+ *
+ * `liveOf` возвращает состояние живого агента сессии либо `undefined`, если
+ * агента нет. Без него состояние не вычислить: «остановился» — это факт об
+ * отсутствии агента, а не догадка по тишине.
+ */
+function withPlan(task, liveOf, config, now, sameSession) {
+  const plan = parsePlan(task.plan)
+  // Отказ реестра — это «агента нет», а не повод не собрать доску: одна
+  // непрочитанная сессия не должна прятать от человека все задачи.
+  let live
+  try {
+    if (typeof liveOf === 'function' && task.sessionId) live = liveOf(task.sessionId)
+  } catch { live = undefined }
+  return {
+    ...task,
+    plan: { items: planItems(plan), progress: planProgress(plan) },
+    state: taskState({ task, live }),
+    // Номер в очереди считается на лету: агент берёт задачи одну за другой, и
+    // у оставшихся третий сам становится вторым.
+    queuePos: queuePosition(task, sameSession),
+    // Метки разобраны здесь же: браузер сверяет списки, а не разбирает строки.
+    facets: facetsOfTask(task),
+    // Считаем здесь, а не в браузере: порог живёт в настройках, а настройки —
+    // на хосте. Отдавать браузеру ещё и порог значило бы отдавать ему решение.
+    stale: isStale({
+      now,
+      updatedAt: task.updatedAt,
+      sessionId: task.sessionId,
+      afterMinutes: config?.staleAfterMin,
+    }),
+  }
+}
+
+/** Разложить задачи: по колонкам, внутри — по проектам, внутри — идущее наверх. */
+function orderForBoard(tasks, columns) {
+  const out = []
+  for (const column of columns) {
+    const inColumn = tasks.filter((t) => t.column === column)
+    for (const group of groupByRepo(sortByLife(inColumn))) out.push(...group.tasks)
+  }
+  // Задачи в колонке, которой на этой доске нет, не теряем: спрятать их совсем
+  // хуже, чем показать в непривычном месте.
+  const seen = new Set(out.map((t) => t.id))
+  for (const task of tasks) if (!seen.has(task.id)) out.push(task)
+  return out
+}
+
+/**
+ * Ответ доски: колонки в фиксированном порядке, задачи и пределы.
+ * Порядок колонок задан кодом, а не настройками: он повторяет воркфлоу, и
+ * переставлять его местами незачем.
+ */
+export function buildBoard({ store, config, board = 'main', repo, liveOf, sync, projectRoot }) {
+  // Одно «сейчас» на всю сборку: иначе соседние карточки посчитались бы по
+  // разным моментам, и разница вылезла бы ровно на границе минуты.
+  const now = Date.now()
+  // Порядок задаём здесь, а не в браузере: правила группировки и подъёма
+  // повторять во второй раз значило бы завести вторую их редакцию.
+  //
+  // Отдаём задачи УЖЕ разложенными — сперва по проектам, внутри проекта идущая
+  // работа наверх. Браузер рисует заголовок при смене проекта, и после отбора
+  // группы остаются целыми, потому что отбор порядка не меняет.
+  const raw = store.listTasks({ board, repo })
+  // Очередь считается внутри своей сессии, а не по доске целиком: две сессии —
+  // две независимые очереди.
+  const bySession = new Map()
+  for (const task of raw) {
+    const id = typeof task.sessionId === 'string' ? task.sessionId : ''
+    if (id === '') continue
+    if (!bySession.has(id)) bySession.set(id, [])
+    bySession.get(id).push(task)
+  }
+  const tasks = orderForBoard(
+    raw.map((task) => withPlan(task, liveOf, config, now, bySession.get(task.sessionId) ?? [])),
+    columnsOf(store.boardKind(board)),
+  )
+  const kind = store.boardKind(board)
+  // Своё название приходит с сервера, а перевод остаётся на браузере: конфиг
+  // живёт здесь, а языки — там, и смешивать их не надо.
+  const names = columnNamesOf(config)
+  const columns = columnsOf(kind).map((id) => {
+    const count = tasks.filter((t) => t.column === id).length
+    const limit = wipLimitField(config, id)
+    return { id, name: names[id], count, limit, overLimit: limit !== undefined && count > limit }
+  })
+  // Отборы считаем по ВСЕМ задачам доски, а не по отобранным: счётчик рядом со
+  // значением отвечает «сколько там всего», а не «сколько осталось после моего
+  // же выбора».
+  return {
+    board, kind, now, boards: store.listBoards(), columns, tasks,
+    // Фактический корень проектов: {path, set} — путь и признак «задан
+    // настройкой». Считается на хосте — браузер не знает ни настройку, ни cwd.
+    projectRoot: projectRoot ?? { path: '', set: false },
+
+    facets: facetsOf(tasks),
+    // Состояние сверки едет вместе с доской: отдельный опрос ради него был бы
+    // вторым источником обращений и вторым местом, где это может отстать.
+    sync: sync ?? { state: 'never' },
+  }
+}
+
+/**
+ * Перенос карточки. Предел колонки — предупреждение, а не запрет: перенос
+ * выполняется, а признак превышения уезжает в ответ, и доска подсветит
+ * колонку. Запрет здесь превратил бы предел из ориентира в преграду.
+ */
+export function applyMove({ store, config, id, column, beforeId, afterId, source = 'manual', detail = '' }) {
+  const before = store.getTask(id)
+  if (before === undefined) return { error: 'task-not-found', status: 404 }
+  const task = store.moveTask(id, { column, beforeId, afterId })
+  if (task.column !== before.column) {
+    store.addTransition({
+      taskId: id, fromCol: before.column, toCol: task.column, source, detail,
+    })
+  }
+  const limit = wipLimitField(config, task.column)
+  const count = store.countInColumn(task.board, task.column)
+  return { task, overLimit: limit !== undefined && count > limit }
+}
+
+/** Создание своей задачи (не из Gitea). */
+export function createTask({ store, input }) {
+  const title = typeof input?.title === 'string' ? input.title.trim() : ''
+  if (title === '') return { error: 'title-required', status: 400 }
+  const board = input?.board ?? 'main'
+  // Колонка проверяется по ВИДУ доски, а не по общему списку: положить задачу
+  // в `deploy` на простой доске значило бы спрятать её в колонке, которой там
+  // нет.
+  const allowed = columnsOf(store.boardKind(board))
+  const column = allowed.includes(input?.column) ? input.column : 'backlog'
+  const task = store.createTask({
+    board,
+    column,
+    title,
+    body: typeof input?.body === 'string' ? input.body : '',
+    labels: Array.isArray(input?.labels) ? input.labels.filter((l) => typeof l === 'string') : [],
+  })
+  return { task }
+}
+
+/** Правка полей карточки. Колонку и порядок правит только перенос. */
+export function updateTask({ store, id, input }) {
+  if (store.getTask(id) === undefined) return { error: 'task-not-found', status: 404 }
+  const patch = {}
+  if (typeof input?.title === 'string' && input.title.trim() !== '') patch.title = input.title.trim()
+  if (typeof input?.body === 'string') patch.body = input.body
+  if (Array.isArray(input?.labels)) patch.labels = input.labels.filter((l) => typeof l === 'string')
+  return { task: store.updateTask(id, patch) }
+}
+
+/**
+ * Дописать заметку в тело задачи.
+ *
+ * Именно в тело, а не в отдельную ленту заметок и не комментарием в Gitea:
+ * владелец выбрал самый простой из трёх смыслов, и он же самый дешёвый.
+ *
+ * Дописываем на сервере, а не в браузере: чип держит копию задачи, и склейка
+ * у него потеряла бы всё, что тело нажило с момента её получения.
+ */
+export function appendNote({ store, id, input }) {
+  const task = store.getTask(id)
+  if (task === undefined) return { error: 'task-not-found', status: 404 }
+  const note = typeof input?.text === 'string' ? input.text.trim() : ''
+  if (note === '') return { error: 'note-required', status: 400 }
+  const body = typeof task.body === 'string' ? task.body : ''
+  return { task: store.updateTask(id, { body: body === '' ? note : `${body}\n\n${note}` }) }
+}
+
+/**
+ * Убрать карточку в архив или вернуть на доску.
+ *
+ * Возврат ставит её ровно туда, где она была: колонка и порядок сохранены, а
+ * `archivedAt` — единственное, что менялось.
+ */
+export function setArchived({ store, id, archived, now = Date.now() }) {
+  const task = store.getTask(id)
+  if (task === undefined) return { error: 'task-not-found', status: 404 }
+  return { task: store.setArchived(id, archived ? now : 0) }
+}
+
+/** Архив: свой список, а не колонка — архив стадией работы не является. */
+export function listArchive({ store }) {
+  return { tasks: store.listArchived() }
+}
+
+export function deleteTask({ store, id }) {
+  if (store.getTask(id) === undefined) return { error: 'task-not-found', status: 404 }
+  store.deleteTask(id)
+  return { ok: true }
+}
+
+/**
+ * Тело задачи, разобранное в дерево блоков.
+ *
+ * Разбираем здесь, а не в браузере: браузерная половина — отдельный бандл и
+ * позвать `lib/markdown.js` не может. Заодно тело не едет в разметку строкой,
+ * и подставить туда чужое нечем.
+ */
+export function taskBody({ store, id }) {
+  const task = store.getTask(id)
+  if (task === undefined) return { error: 'task-not-found', status: 404 }
+  return { blocks: parseBody(task.body) }
+}
+
+export function taskLog({ store, id }) {
+  if (store.getTask(id) === undefined) return { error: 'task-not-found', status: 404 }
+  return { transitions: store.listTransitions(id) }
+}
+
+/** Задача, привязанная к сессии; отсутствие задачи — штатный ответ. */
+export function taskBySession({ store, sessionId }) {
+  const task = store.findTaskBySession(sessionId)
+  if (task === undefined) return { task: null }
+  // Вид доски едет вместе с задачей: чип предлагает колонки, а предлагать
+  // `deploy` задаче с простой доски значит звать в колонку, которой нет.
+  return { task, columns: columnsOf(store.boardKind(task.board)) }
+}

package/lib/store.js

@@ -0,0 +1,366 @@
+// Хранилище задач доски.
+//
+// У канбана свои поля и своя история, которых в Gitea нет: сессия, модель,
+// журнал переходов, порядок карточек. Поэтому задачи живут здесь, а не только
+// в issue.
+//
+// Колонка в таблице названа `col`, а не `column`: `column` — зарезервированное
+// слово SQL, и без экранирования запрос падает. Наружу поле по-прежнему
+// называется `column`, переименование спрятано внутри этого модуля.
+//
+// Поля `branch` и `worktree` — НАБЛЮДЕНИЕ, вычитанное из issue и событий
+// Gitea, а не намерение: плагин ветки не создаёт.
+
+import { DatabaseSync } from 'node:sqlite'
+import { randomUUID } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { keyBetween } from './order.js'
+import { DEFAULT_BOARDS, normalizeKind } from './config.js'
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS boards (
+  id        TEXT PRIMARY KEY,
+  title     TEXT NOT NULL,
+  kind      TEXT NOT NULL DEFAULT 'project',
+  position  TEXT NOT NULL,
+  createdAt INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS tasks (
+  id           TEXT PRIMARY KEY,
+  board        TEXT NOT NULL,
+  col          TEXT NOT NULL,
+  position     TEXT NOT NULL,
+  title        TEXT NOT NULL,
+  body         TEXT NOT NULL DEFAULT '',
+  owner        TEXT,
+  repo         TEXT,
+  issueNumber  INTEGER,
+  issueUrl     TEXT,
+  labels       TEXT NOT NULL DEFAULT '[]',
+  branch       TEXT,
+  worktree     TEXT,
+  sessionId    TEXT,
+  model        TEXT,
+  provider     TEXT,
+  waiting      INTEGER NOT NULL DEFAULT 0,
+  plan         TEXT NOT NULL DEFAULT '',
+  columnAt     INTEGER NOT NULL DEFAULT 0,
+  archivedAt   INTEGER NOT NULL DEFAULT 0,
+  queuedAt     INTEGER NOT NULL DEFAULT 0,
+  labelColors  TEXT NOT NULL DEFAULT '{}',
+  author       TEXT NOT NULL DEFAULT '',
+  syncedAt     INTEGER NOT NULL DEFAULT 0,
+  createdAt    INTEGER NOT NULL,
+  updatedAt    INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS tasks_board_col ON tasks(board, col, position);
+CREATE INDEX IF NOT EXISTS tasks_session ON tasks(sessionId);
+CREATE TABLE IF NOT EXISTS transitions (
+  id      INTEGER PRIMARY KEY AUTOINCREMENT,
+  taskId  TEXT NOT NULL,
+  fromCol TEXT,
+  toCol   TEXT NOT NULL,
+  source  TEXT NOT NULL,
+  detail  TEXT NOT NULL DEFAULT '',
+  at      INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS transitions_task ON transitions(taskId, at);
+CREATE TABLE IF NOT EXISTS dismissed (
+  owner       TEXT NOT NULL,
+  repo        TEXT NOT NULL,
+  issueNumber INTEGER NOT NULL,
+  at          INTEGER NOT NULL,
+  PRIMARY KEY (owner, repo, issueNumber)
+);
+`
+
+/** Поля задачи, которые разрешено править через updateTask. */
+const WRITABLE = [
+  'title', 'body', 'owner', 'repo', 'issueNumber', 'issueUrl', 'labels',
+  'branch', 'worktree', 'sessionId', 'model', 'provider', 'waiting', 'syncedAt', 'plan',
+  'labelColors', 'queuedAt', 'createdAt', 'author',
+]
+
+/** Источники перехода; чужое значение не пишем, чтобы журнал оставался читаемым. */
+const SOURCES = new Set(['manual', 'session', 'gitea', 'tool'])
+
+function rowToTask(row) {
+  if (row === undefined) return undefined
+  const { col, labels, waiting, labelColors, ...rest } = row
+  let parsed = []
+  try {
+    const value = JSON.parse(labels)
+    if (Array.isArray(value)) parsed = value.filter((l) => typeof l === 'string')
+  } catch { /* испорченное поле не должно ронять чтение всей доски */ }
+  let colors = {}
+  try {
+    const value = JSON.parse(labelColors ?? '{}')
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) colors = value
+  } catch { /* испорченное поле не должно ронять чтение всей доски */ }
+  return { ...rest, column: col, labels: parsed, labelColors: colors, waiting: waiting === 1 }
+}
+
+/**
+ * Открыть хранилище задач.
+ * @param {{dir: string}} options каталог, в котором лежит файл базы
+ * @returns {object} интерфейс хранилища
+ */
+export function openStore({ dir }) {
+  mkdirSync(dir, { recursive: true })
+  const db = new DatabaseSync(join(dir, 'kanban.db'))
+  db.exec('PRAGMA journal_mode = WAL')
+  db.exec('PRAGMA foreign_keys = ON')
+  db.exec(SCHEMA)
+  // База могла быть создана прежней версией. Добавляем недостающие столбцы
+  // поштучно: ALTER на существующий столбец бросает, и это штатный ответ
+  // «уже есть», а не поломка.
+  for (const [column, definition] of [
+    ['waiting', 'INTEGER NOT NULL DEFAULT 0'],
+    ['syncedAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['plan', "TEXT NOT NULL DEFAULT ''"],
+    ['columnAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['archivedAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['queuedAt', 'INTEGER NOT NULL DEFAULT 0'],
+    ['labelColors', "TEXT NOT NULL DEFAULT '{}'"],
+    ['author', "TEXT NOT NULL DEFAULT ''"],
+  ]) {
+    try { db.exec(`ALTER TABLE tasks ADD COLUMN ${column} ${definition}`) } catch { /* столбец уже есть */ }
+  }
+  try { db.exec("ALTER TABLE boards ADD COLUMN kind TEXT NOT NULL DEFAULT 'project'") } catch { /* уже есть */ }
+  // Старые карточки не знают, когда попали в свою колонку. Считаем от
+  // заведения: это честнее нуля, который читался бы как «в 1970 году».
+  db.exec('UPDATE tasks SET columnAt = createdAt WHERE columnAt = 0')
+
+  const q = {
+    boards: db.prepare('SELECT * FROM boards ORDER BY position'),
+    boardById: db.prepare('SELECT * FROM boards WHERE id = ?'),
+    insertBoard: db.prepare('INSERT INTO boards (id, title, kind, position, createdAt) VALUES (?, ?, ?, ?, ?)'),
+    lastBoard: db.prepare('SELECT position FROM boards ORDER BY position DESC LIMIT 1'),
+    taskById: db.prepare('SELECT * FROM tasks WHERE id = ?'),
+    tasksByBoard: db.prepare('SELECT * FROM tasks WHERE board = ? AND archivedAt = 0 ORDER BY col, position'),
+    archived: db.prepare('SELECT * FROM tasks WHERE archivedAt > 0 ORDER BY archivedAt DESC'),
+    archivable: db.prepare(
+      "SELECT * FROM tasks WHERE archivedAt = 0 AND col = 'done' AND columnAt > 0 AND columnAt <= ?"),
+    dismiss: db.prepare('INSERT OR REPLACE INTO dismissed (owner, repo, issueNumber, at) VALUES (?, ?, ?, ?)'),
+    isDismissed: db.prepare('SELECT 1 FROM dismissed WHERE owner = ? AND repo = ? AND issueNumber = ?'),
+    byIssue: db.prepare('SELECT * FROM tasks WHERE owner = ? AND repo = ? AND issueNumber = ?'),
+    tasksBySession: db.prepare('SELECT * FROM tasks WHERE sessionId = ? LIMIT 1'),
+    lastInColumn: db.prepare('SELECT position FROM tasks WHERE board = ? AND col = ? ORDER BY position DESC LIMIT 1'),
+    deleteTask: db.prepare('DELETE FROM tasks WHERE id = ?'),
+    insertTransition: db.prepare('INSERT INTO transitions (taskId, fromCol, toCol, source, detail, at) VALUES (?, ?, ?, ?, ?, ?)'),
+    transitionsOf: db.prepare('SELECT * FROM transitions WHERE taskId = ? ORDER BY at, id'),
+    countInColumn: db.prepare('SELECT COUNT(*) AS n FROM tasks WHERE board = ? AND col = ?'),
+    watchable: db.prepare(
+      "SELECT * FROM tasks WHERE issueNumber IS NOT NULL AND col NOT IN ('done') ORDER BY updatedAt DESC"),
+  }
+
+  function ensureBoard(id, title, kind) {
+    const found = q.boardById.get(id)
+    if (found !== undefined) return found
+    const last = q.lastBoard.get()
+    const position = keyBetween(last?.position, undefined)
+    q.insertBoard.run(id, title, normalizeKind(kind), position, Date.now())
+    return q.boardById.get(id)
+  }
+
+  // Обе доски заводятся сразу: пустое хранилище без единой доски выглядит в
+  // интерфейсе как поломка, а не как чистый старт.
+  //
+  // Прежняя единственная доска `main` СТАНОВИТСЯ проектной, а не заводится
+  // рядом с новой: заведи мы вторую, задачи остались бы на осиротевшей.
+  for (const board of DEFAULT_BOARDS) ensureBoard(board.id, board.title, board.kind)
+  // Прежняя доска называлась «Основная», и рядом с «Простой» это читается как
+  // разница в важности, а не в виде. Переименовываем только нетронутое
+  // название: если его меняли, значит оно чьё-то.
+  db.prepare("UPDATE boards SET title = ? WHERE id = 'main' AND title = 'Основная доска'")
+    .run(DEFAULT_BOARDS[0].title)
+
+  function positionFor(board, column, beforeId, afterId) {
+    const before = beforeId ? q.taskById.get(beforeId) : undefined
+    const after = afterId ? q.taskById.get(afterId) : undefined
+    if (before === undefined && after === undefined) {
+      return keyBetween(q.lastInColumn.get(board, column)?.position, undefined)
+    }
+    return keyBetween(after?.position, before?.position)
+  }
+
+  return {
+    listBoards() {
+      return q.boards.all()
+    },
+
+    createBoard({ id, title, kind }) {
+      return ensureBoard(id, title ?? id, kind)
+    },
+
+    /** Вид доски. Неизвестная доска — проектная: пустого набора колонок нет. */
+    boardKind(id) {
+      return normalizeKind(q.boardById.get(id)?.kind)
+    },
+
+    listTasks({ board = 'main', repo } = {}) {
+      const rows = q.tasksByBoard.all(board).map(rowToTask)
+      return repo ? rows.filter((t) => t.repo === repo) : rows
+    },
+
+    getTask(id) {
+      return rowToTask(q.taskById.get(id))
+    },
+
+    /** Задачи, за которыми стоит issue и по которым работа ещё идёт. */
+    listWatchable() {
+      return q.watchable.all().map(rowToTask)
+    },
+
+    /**
+     * ВСЕ задачи сессии, в порядке постановки в очередь.
+     *
+     * Одна сессия ведёт пачку задач, и «чья это сессия» перестало иметь
+     * единственный ответ. Инструменты обязаны различать один случай от
+     * нескольких, а не брать первую попавшуюся.
+     */
+    listTasksBySession(sessionId) {
+      if (!sessionId) return []
+      return db.prepare(
+        'SELECT * FROM tasks WHERE sessionId = ? AND archivedAt = 0 ORDER BY queuedAt, col, position')
+        .all(sessionId).map(rowToTask)
+    },
+
+    findTaskBySession(sessionId) {
+      if (!sessionId) return undefined
+      return rowToTask(q.tasksBySession.get(sessionId))
+    },
+
+    countInColumn(board, column) {
+      return q.countInColumn.get(board, column).n
+    },
+
+    createTask(input) {
+      const now = Date.now()
+      // Задача заведена тогда, когда её завели в Gitea, а не когда подхват
+      // довёз карточку. `columnAt` остаётся сегодняшним: в колонку она въехала
+      // сейчас, и это разные даты.
+      const born = Number(input.createdAt) || now
+      const board = input.board ?? 'main'
+      const column = input.column ?? 'backlog'
+      const id = randomUUID()
+      const position = positionFor(board, column, input.beforeId, input.afterId)
+      db.prepare(`INSERT INTO tasks
+        (id, board, col, position, title, body, owner, repo, issueNumber, issueUrl,
+         labels, branch, worktree, sessionId, model, provider, waiting, syncedAt,
+         labelColors, author, columnAt, createdAt, updatedAt)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+        id, board, column, position,
+        input.title ?? '', input.body ?? '',
+        input.owner ?? null, input.repo ?? null,
+        input.issueNumber ?? null, input.issueUrl ?? null,
+        JSON.stringify(input.labels ?? []),
+        input.branch ?? null, input.worktree ?? null,
+        input.sessionId ?? null, input.model ?? null, input.provider ?? null,
+        input.waiting ? 1 : 0,
+        Number(input.syncedAt) || 0,
+        JSON.stringify(input.labelColors ?? {}),
+        input.author ?? '',
+        now, born, now,
+      )
+      return rowToTask(q.taskById.get(id))
+    },
+
+    updateTask(id, patch) {
+      const current = q.taskById.get(id)
+      if (current === undefined) throw new Error(`задача ${id} не найдена`)
+      const fields = []
+      const values = []
+      for (const key of WRITABLE) {
+        if (!Object.hasOwn(patch, key)) continue
+        fields.push(`${key} = ?`)
+        if (key === 'labels') values.push(JSON.stringify(patch[key] ?? []))
+        else if (key === 'labelColors') values.push(JSON.stringify(patch[key] ?? {}))
+        else if (key === 'waiting') values.push(patch[key] ? 1 : 0)
+        else if (key === 'syncedAt') values.push(Number(patch[key]) || 0)
+        else values.push(patch[key] ?? null)
+      }
+      if (fields.length > 0) {
+        values.push(Date.now(), id)
+        db.prepare(`UPDATE tasks SET ${fields.join(', ')}, updatedAt = ? WHERE id = ?`).run(...values)
+      }
+      return rowToTask(q.taskById.get(id))
+    },
+
+    moveTask(id, { column, beforeId, afterId }) {
+      const current = q.taskById.get(id)
+      if (current === undefined) throw new Error(`задача ${id} не найдена`)
+      const target = column ?? current.col
+      const position = positionFor(current.board, target, beforeId, afterId)
+      const now = Date.now()
+      // Время в колонке считаем по отметке, а не по журналу переходов: журнал
+      // пришлось бы читать на каждую карточку при каждой сборке доски.
+      // Перестановка внутри колонки отметку НЕ сбрасывает — задача в ревью
+      // третий день там и остаётся, как бы её ни двигали вверх-вниз.
+      const enteredAt = target === current.col ? current.columnAt : now
+      // Переезд в работу снимает задачу с очереди: она уже не ждёт, а
+      // делается. Иначе номер очереди висел бы у карточки, которая идёт.
+      const queuedAt = target === 'in-progress' ? 0 : current.queuedAt
+      db.prepare('UPDATE tasks SET col = ?, position = ?, columnAt = ?, queuedAt = ?, updatedAt = ? WHERE id = ?')
+        .run(target, position, enteredAt, queuedAt, now, id)
+      return rowToTask(q.taskById.get(id))
+    },
+
+    deleteTask(id) {
+      // Удалённая карточка задачи из Gitea запоминается как отказанная: иначе
+      // подхват вернул бы её на доску следующим же проходом, и доска спорила
+      // бы с человеком каждые две минуты.
+      const task = q.taskById.get(id)
+      if (task?.owner && task?.repo && typeof task.issueNumber === 'number') {
+        q.dismiss.run(task.owner, task.repo, task.issueNumber, Date.now())
+      }
+      q.deleteTask.run(id)
+    },
+
+    /** Отказывались ли уже от этого issue. */
+    isDismissed({ owner, repo, issueNumber }) {
+      return q.isDismissed.get(owner, repo, issueNumber) !== undefined
+    },
+
+    /** Задача по issue — чтобы подхват не заводил второй раз то же самое. */
+    findTaskByIssue({ owner, repo, issueNumber }) {
+      return rowToTask(q.byIssue.get(owner, repo, issueNumber))
+    },
+
+    /** Задачи в архиве: свой список, а не колонка. */
+    listArchived() {
+      return q.archived.all().map(rowToTask)
+    },
+
+    /**
+     * Что пора убрать в архив.
+     *
+     * Возраст считаем по отметке входа в колонку, а не по `updatedAt`: сверка
+     * трогает задачу и после завершения, и по `updatedAt` архив откладывался
+     * бы бесконечно.
+     */
+    listArchivable(before) {
+      return q.archivable.all(before).map(rowToTask)
+    },
+
+    setArchived(id, archivedAt) {
+      db.prepare('UPDATE tasks SET archivedAt = ?, updatedAt = ? WHERE id = ?')
+        .run(archivedAt, Date.now(), id)
+      return rowToTask(q.taskById.get(id))
+    },
+
+    addTransition({ taskId, fromCol, toCol, source, detail }) {
+      if (!SOURCES.has(source)) throw new Error(`неизвестный источник перехода: ${source}`)
+      q.insertTransition.run(taskId, fromCol ?? null, toCol, source, detail ?? '', Date.now())
+    },
+
+    listTransitions(taskId) {
+      return q.transitionsOf.all(taskId)
+    },
+
+    close() {
+      db.close()
+    },
+  }
+}