@goodandready/dsh-kanban 0.1.14

package/lib/markdown.js

@@ -0,0 +1,161 @@
+// Разбор тела задачи в дерево узлов.
+//
+// Тело приходит из Gitea и пишет его кто угодно. Поэтому разбор отдаёт ДЕРЕВО,
+// а не строку HTML: браузерная половина собирает его элементами React, и
+// подстановка чужой разметки становится невозможной по построению, а не по
+// бдительности того, кто вспомнит про экранирование.
+//
+// Полноценный markdown здесь не нужен и не будет: заголовки, списки, выделение,
+// код и ссылки покрывают почти всякое тело issue. Всё непонятое остаётся
+// текстом как есть — это честнее, чем угадывать.
+
+/** Ссылки открываем только по этим схемам: `javascript:` в теле — тот же обход. */
+const SAFE_LINK = /^https?:\/\//i
+
+/**
+ * Разобрать тело в список блоков.
+ *
+ * @returns {Array<object>} блоки вида
+ *   `{kind:'heading', level, spans}`, `{kind:'para', spans}`,
+ *   `{kind:'list', ordered, items:[spans]}`, `{kind:'code', text}`,
+ *   `{kind:'quote', spans}`, `{kind:'rule'}`
+ */
+export function parseBody(text) {
+  const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n')
+  const blocks = []
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i]
+
+    if (line.trim() === '') { i += 1; continue }
+
+    // Блок кода: всё внутри дословно, включая то, что похоже на разметку.
+    const fence = /^\s*```(.*)$/.exec(line)
+    if (fence !== null) {
+      const body = []
+      i += 1
+      while (i < lines.length && !/^\s*```/.test(lines[i])) { body.push(lines[i]); i += 1 }
+      i += 1
+      blocks.push({ kind: 'code', lang: fence[1].trim(), text: body.join('\n') })
+      continue
+    }
+
+    if (/^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(line)) { blocks.push({ kind: 'rule' }); i += 1; continue }
+
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+    if (heading !== null) {
+      blocks.push({ kind: 'heading', level: heading[1].length, spans: parseSpans(heading[2]) })
+      i += 1
+      continue
+    }
+
+    if (/^\s*>\s?/.test(line)) {
+      const body = []
+      while (i < lines.length && /^\s*>\s?/.test(lines[i])) {
+        body.push(lines[i].replace(/^\s*>\s?/, ''))
+        i += 1
+      }
+      blocks.push({ kind: 'quote', spans: parseSpans(body.join(' ')) })
+      continue
+    }
+
+    const bullet = /^\s*[-*+]\s+(.*)$/.exec(line)
+    const numbered = /^\s*\d+[.)]\s+(.*)$/.exec(line)
+    if (bullet !== null || numbered !== null) {
+      const ordered = numbered !== null
+      const items = []
+      while (i < lines.length) {
+        const m = ordered
+          ? /^\s*\d+[.)]\s+(.*)$/.exec(lines[i])
+          : /^\s*[-*+]\s+(.*)$/.exec(lines[i])
+        if (m === null) break
+        items.push(parseSpans(m[1]))
+        i += 1
+      }
+      blocks.push({ kind: 'list', ordered, items })
+      continue
+    }
+
+    // Абзац: строки до пустой склеиваются, как это делает markdown.
+    const body = []
+    while (i < lines.length && lines[i].trim() !== ''
+      && !/^\s*(#{1,6})\s+/.test(lines[i])
+      && !/^\s*[-*+]\s+/.test(lines[i])
+      && !/^\s*\d+[.)]\s+/.test(lines[i])
+      && !/^\s*```/.test(lines[i])
+      && !/^\s*>\s?/.test(lines[i])) {
+      body.push(lines[i])
+      i += 1
+    }
+    blocks.push({ kind: 'para', spans: parseSpans(body.join(' ')) })
+  }
+
+  return blocks
+}
+
+/**
+ * Разобрать строку на куски: обычный текст, код, выделение, ссылка.
+ *
+ * @returns {Array<{kind: 'text'|'code'|'strong'|'em'|'link', text: string, href?: string}>}
+ */
+export function parseSpans(text) {
+  const out = []
+  const src = String(text ?? '')
+  // Код первым: внутри обратных кавычек разметки нет, там всё дословно.
+  const re = /(`[^`]+`)|(\[[^\]]+\]\([^)\s]+\))|(\*\*[^*]+\*\*)|(__[^_]+__)|(\*[^*]+\*)|(_[^_]+_)/g
+  let at = 0
+  let m = re.exec(src)
+
+  while (m !== null) {
+    if (m.index > at) out.push({ kind: 'text', text: src.slice(at, m.index) })
+    const piece = m[0]
+
+    if (piece.startsWith('`')) {
+      out.push({ kind: 'code', text: piece.slice(1, -1) })
+    } else if (piece.startsWith('[')) {
+      const cut = piece.indexOf('](')
+      const label = piece.slice(1, cut)
+      const href = piece.slice(cut + 2, -1)
+      // Небезопасная схема — не ссылка, а текст. Молча выбрасывать нельзя:
+      // человек должен видеть, что там было написано.
+      if (SAFE_LINK.test(href)) out.push({ kind: 'link', text: label, href })
+      else out.push({ kind: 'text', text: piece })
+    } else if (piece.startsWith('**') || piece.startsWith('__')) {
+      out.push({ kind: 'strong', text: piece.slice(2, -2) })
+    } else {
+      out.push({ kind: 'em', text: piece.slice(1, -1) })
+    }
+
+    at = m.index + piece.length
+    m = re.exec(src)
+  }
+
+  if (at < src.length) out.push({ kind: 'text', text: src.slice(at) })
+  return mergeText(out)
+}
+
+/**
+ * Склеить соседние куски текста.
+ *
+ * Разбор дробит строку там, где нашёл разметку и передумал: `[клик](javascript:…)`
+ * не стал ссылкой, но оставил после себя два куска. Дробление наружу не
+ * выпускаем — оно не значит ничего, а читателю мешает.
+ */
+function mergeText(spans) {
+  const out = []
+  for (const span of spans) {
+    const last = out[out.length - 1]
+    if (span.kind === 'text' && last !== undefined && last.kind === 'text') {
+      last.text += span.text
+      continue
+    }
+    out.push(span)
+  }
+  return out
+}
+
+/** Безопасна ли ссылка. Наружу — чтобы браузерная половина не решала это заново. */
+export function isSafeHref(href) {
+  return SAFE_LINK.test(String(href ?? ''))
+}

package/lib/order.js

@@ -0,0 +1,66 @@
+// Дробный индекс порядка карточек.
+//
+// Наивный подход хранит целочисленный индекс, и перетаскивание карточки в
+// начало колонки из десяти строк требует переписать все десять. Здесь порядок
+// хранится строкой, а новое значение выдаётся МЕЖДУ двумя соседями, поэтому
+// перетаскивание — всегда один UPDATE одной строки, сколько бы карточек ни
+// было в колонке.
+//
+// Реализация строковая намеренно. Вариант на числах с плавающей точкой
+// проходит поверхностную проверку и разваливается примерно на пятидесятой
+// вставке в одно и то же место, когда кончается разрядность.
+//
+// Ключ читается как дробь после подразумеваемого «0.»: сравнение обычное
+// лексикографическое. Ключ никогда не заканчивается первым символом алфавита —
+// иначе следующее деление слева стало бы невозможным.
+
+/** Алфавит в порядке возрастания кодов символов. */
+const DIGITS = '0123456789abcdefghijklmnopqrstuvwxyz'
+const FIRST = DIGITS[0]
+
+/** Значение строго между `a` и `b`; `b === undefined` означает «до конца». */
+function midpoint(a, b) {
+  if (b !== undefined && a >= b) {
+    throw new Error(`порядок нарушен: ${JSON.stringify(a)} не меньше ${JSON.stringify(b)}`)
+  }
+  if (a.endsWith(FIRST) || (b !== undefined && b.endsWith(FIRST))) {
+    throw new Error('ключ порядка не может заканчиваться первым символом алфавита')
+  }
+
+  if (b !== undefined) {
+    // Общий префикс переносится в результат как есть, деление продолжается на
+    // остатке — иначе для близких соседей пришлось бы наращивать длину с нуля.
+    let n = 0
+    while ((a[n] ?? FIRST) === b[n]) n += 1
+    if (n > 0) return b.slice(0, n) + midpoint(a.slice(n), b.slice(n))
+  }
+
+  const from = a === '' ? 0 : DIGITS.indexOf(a[0])
+  const to = b === undefined ? DIGITS.length : DIGITS.indexOf(b[0])
+  if (from < 0 || to < 0) throw new Error('ключ порядка содержит символ вне алфавита')
+
+  if (to - from > 1) {
+    return DIGITS[Math.round(0.5 * (from + to))]
+  }
+  if (b !== undefined && b.length > 1) {
+    return b.slice(0, 1)
+  }
+  // Соседние символы: занимаем разряд `a` и делим следующий.
+  return DIGITS[from] + midpoint(a.slice(1), undefined)
+}
+
+/**
+ * Ключ порядка строго между двумя соседями.
+ *
+ * Оба соседа необязательны: без обоих выдаётся стартовое значение, без правого
+ * — значение после `a`, без левого — значение перед `b`. Результат всегда
+ * можно снова разделить.
+ *
+ * @param {string} [a] ключ карточки слева
+ * @param {string} [b] ключ карточки справа
+ * @returns {string} ключ строго между ними
+ * @throws если `a` не меньше `b` либо ключ содержит символ вне алфавита
+ */
+export function keyBetween(a, b) {
+  return midpoint(a ?? '', b ?? undefined)
+}

package/lib/outbound.js

@@ -0,0 +1,88 @@
+// Канбан → Gitea: закрытие issue.
+//
+// Отправка идёт очередью, а не прямо из обработчика переноса. Причина простая:
+// Gitea может быть недоступен, а доска обязана двигать карточки и при
+// недоступном Gitea. Перенос, ждущий сети, превратил бы доску в заложника
+// чужого времени ответа.
+//
+// Неудачная отправка не теряется и не молчит: она повторяется, а после
+// нескольких неудач попадает в журнал задачи как проблема. Молча съеденное
+// расхождение — худшее, что может сделать синхронизация.
+//
+// Меток колонок доска НЕ ставит. Она их никогда и не читала: колонка выводится
+// из состояния issue, ветки и pull request, а метка лишь пересказывала в Gitea
+// то, что там уже написано. Взамен доска не трогает чужую разметку вовсе.
+
+export function planOutbound(task, column, config) {
+  if (typeof task?.issueNumber !== 'number') return []
+  // Закрытие issue — единственное, что доска сообщает Gitea: это факт, а не
+  // пересказ фактов, которые в issue и так видны.
+  return column === 'done'
+    ? [{ kind: 'close', owner: task.owner, repo: task.repo, index: task.issueNumber }]
+    : []
+}
+
+/**
+ * Очередь отправки с повторами.
+ *
+ * @param {object} options
+ * @param {object} options.gitea клиент
+ * @param {object} options.store хранилище — туда пишется отчёт о неудаче
+ * @param {number} [options.maxAttempts] после скольких неудач сдаться и записать
+ */
+export function createOutbox({ gitea, store, logger, maxAttempts = 4 }) {
+  const queue = []
+
+  return {
+    size: () => queue.length,
+
+    push(taskId, ops) {
+      for (const op of ops) queue.push({ taskId, op, attempts: 0 })
+    },
+
+    /**
+     * Попробовать отправить всё накопленное.
+     *
+     * Успех убирает операцию, неудача возвращает её в очередь до предела
+     * попыток. Исчерпав попытки, операция НЕ исчезает молча: о ней пишется в
+     * журнал задачи, чтобы расхождение с Gitea было видно человеку.
+     */
+    async flush() {
+      const pending = queue.splice(0)
+      let sent = 0
+      let retried = 0
+      let dropped = 0
+
+      for (const item of pending) {
+        try {
+          if (item.op.kind === 'close') {
+            await gitea.closeIssue({ owner: item.op.owner, repo: item.op.repo, index: item.op.index })
+          }
+          sent += 1
+        } catch (error) {
+          item.attempts += 1
+          if (item.attempts < maxAttempts) {
+            queue.push(item)
+            retried += 1
+            continue
+          }
+          dropped += 1
+          logger?.warn?.(`dsh-kanban: отправка в Gitea не удалась окончательно: ${error?.message}`)
+          try {
+            const task = store.getTask(item.taskId)
+            if (task !== undefined) {
+              store.addTransition({
+                taskId: item.taskId,
+                fromCol: task.column,
+                toCol: task.column,
+                source: 'gitea',
+                detail: `не отправлено в Gitea после ${item.attempts} попыток: ${item.op.kind}`,
+              })
+            }
+          } catch { /* журнал не должен ронять отправку */ }
+        }
+      }
+      return { sent, retried, dropped }
+    },
+  }
+}

package/lib/plan.js

@@ -0,0 +1,153 @@
+// План работы агента и состояние задачи.
+//
+// План получаем ПРЯМО — своим инструментом, а не разбором сообщений агента:
+// разбор это гадание, а инструмент `todo_list` принадлежит чужому плагину, и
+// опираться на его события значит завести зависимость.
+//
+// Состояние тоже факт, а не догадка по таймауту. Порог тишины в настройки не
+// выносим: он был бы догадкой там, где есть точный признак.
+
+/** Пункты плана дальше этого числа не храним: план — не журнал. */
+export const MAX_ITEMS = 50
+
+/** Длиннее этого пункт обрезаем: он едет на карточку в одну строку. */
+export const MAX_ITEM_LENGTH = 120
+
+const EMPTY = { items: [], current: 0 }
+
+/** Приведение пункта к строке разумной длины. */
+function cleanItem(value) {
+  const text = String(value ?? '').replace(/\s+/g, ' ').trim()
+  return text.length > MAX_ITEM_LENGTH ? text.slice(0, MAX_ITEM_LENGTH - 1) + '…' : text
+}
+
+/**
+ * Разобрать план из хранилища.
+ *
+ * Испорченное поле не должно ронять чтение всей доски, поэтому любой сбой
+ * разбора превращается в пустой план.
+ */
+export function parsePlan(raw) {
+  if (typeof raw !== 'string' || raw === '') return EMPTY
+  try {
+    const value = JSON.parse(raw)
+    const items = Array.isArray(value?.items)
+      ? value.items.map(cleanItem).filter((t) => t !== '').slice(0, MAX_ITEMS)
+      : []
+    return { items, current: clampCurrent(value?.current, items.length) }
+  } catch {
+    return EMPTY
+  }
+}
+
+export function serializePlan(plan) {
+  return JSON.stringify({ items: plan.items, current: plan.current })
+}
+
+/**
+ * Указатель на пункт в работе.
+ *
+ * Ноль означает «плана нет либо он ещё не начат»; значение больше длины плана —
+ * «всё сделано», и удерживать его на последнем пункте нельзя: тогда законченный
+ * план вечно показывал бы последний пункт как текущий.
+ */
+function clampCurrent(value, total) {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n < 0) return 0
+  return Math.min(Math.floor(n), total + 1)
+}
+
+/**
+ * Наложить правку инструмента на прежний план.
+ *
+ * Пункты необязательны: агент публикует план один раз, а дальше двигает только
+ * указатель. Требовать список на каждом шаге значило бы гонять его целиком ради
+ * одного числа.
+ */
+export function applyPlan(previous, patch) {
+  const prev = previous ?? EMPTY
+  const items = Array.isArray(patch?.items)
+    ? patch.items.map(cleanItem).filter((t) => t !== '').slice(0, MAX_ITEMS)
+    : prev.items
+  const current = patch?.current === undefined || patch?.current === null
+    ? clampCurrent(prev.current, items.length)
+    : clampCurrent(patch.current, items.length)
+  return { items, current }
+}
+
+/**
+ * Что показать о плане.
+ *
+ * Числа и текст пункта отдаём отдельно: строку «3 из 7» собирает браузер, он
+ * же её и переводит.
+ *
+ * @returns {{total: number, done: number, current: number, text: string}|undefined}
+ */
+export function planProgress(plan) {
+  const items = plan?.items ?? []
+  if (items.length === 0) return undefined
+  const current = clampCurrent(plan?.current, items.length)
+  // Всё, что до текущего пункта, считается сделанным. Модель линейная: агент
+  // двигает одно число, а не ведёт список галочек.
+  const done = current === 0 ? 0 : Math.min(current - 1, items.length)
+  const text = current >= 1 && current <= items.length ? items[current - 1] : ''
+  return { total: items.length, done, current, text }
+}
+
+/** Отметки пунктов для окна карточки. */
+export function planItems(plan) {
+  const items = plan?.items ?? []
+  const current = clampCurrent(plan?.current, items.length)
+  return items.map((text, i) => ({
+    text,
+    done: current > i + 1,
+    active: current === i + 1,
+  }))
+}
+
+/**
+ * Состояние задачи.
+ *
+ * `stopped` — не догадка по тишине, а факт: у задачи записана сессия, но живого
+ * агента за ней нет. Так выглядит прерванная работа после перезапуска харнесса.
+ *
+ * `queued` — задача отдана сессии, но агент до неё не дошёл: она ждёт своей
+ * очереди. Выводится из отметки постановки, а не хранится отдельным полем.
+ *
+ * @param {{task: object, live: 'running'|'idle'|undefined}} args
+ *   `live` — состояние живого агента; `undefined` означает, что агента нет.
+ */
+export function taskState({ task, live }) {
+  const sessionId = typeof task?.sessionId === 'string' ? task.sessionId : ''
+  if (sessionId === '') return 'none'
+  // Задача отдана агенту, но он до неё ещё не дошёл. Без этого состояния
+  // десять карточек в бэклоге ничем не отличаются от нетронутых, и через час
+  // никто не вспомнит, какие уже отданы.
+  if (typeof task?.queuedAt === 'number' && task.queuedAt > 0) return 'queued'
+  // Ожидание человека важнее хода: агент технически «работает», но без ответа
+  // не сдвинется, и именно это надо показать.
+  if (task?.waiting === true) return 'waiting'
+  if (live === undefined) return 'stopped'
+  return live === 'running' ? 'running' : 'idle'
+}
+
+/**
+ * Номер задачи в очереди своей сессии.
+ *
+ * Считается на лету, а не хранится: агент берёт задачи одну за другой, и у
+ * оставшихся третий сам становится вторым. Хранимый номер пришлось бы
+ * пересчитывать, и однажды его бы забыли.
+ *
+ * Порядок — по отметке постановки, а НЕ по положению карточки в колонке.
+ * Перетаскивание мышью — про то, как задачи лежат; очередь — про то, в каком
+ * порядке их получит агент, и менять второе первым нельзя.
+ *
+ * @returns {number|undefined} место начиная с единицы
+ */
+export function queuePosition(task, sameSession) {
+  const at = task?.queuedAt
+  if (typeof at !== 'number' || at <= 0) return undefined
+  const ahead = (sameSession ?? [])
+    .filter((x) => typeof x?.queuedAt === 'number' && x.queuedAt > 0 && x.queuedAt < at)
+  return ahead.length + 1
+}