@goodandready/dsh-kanban 0.1.14

package/lib/commands.js

@@ -0,0 +1,167 @@
+// Перенос карточки — это КОМАНДА агенту, а не запись о состоянии.
+//
+// Владелец не двигает карточки вручную ради учёта: если он двинул, значит
+// просит запустить тот этап, куда двинул. Поэтому таблица ниже описывает не
+// «что стало», а «что сделать», и текст уходит в чат задачи.
+//
+// Тексты последствий для окна подтверждения живут в клиентской половине:
+// они переводятся, а инструкция агенту — нет.
+
+/** Виды досок. Простая доска появляется в #63; таблица под неё уже здесь. */
+export const BOARD_KINDS = ['project', 'simple']
+
+/**
+ * Колонка `done` для инструмента агента закрыта.
+ *
+ * Путь агента к завершению — получить согласие, закрыть issue и удалить ветку;
+ * сверка с Gitea сама увидит закрытый issue без ветки и передвинет карточку.
+ * Карточка двигается фактом, а не заявлением, и подделать это нечем.
+ */
+export const TOOL_FORBIDDEN_COLUMNS = ['done']
+
+const TABLE = {
+  project: {
+    'backlog': { stops: true },
+    'in-progress': {
+      instruction: 'Начни или продолжи реализацию этой задачи по стандартному воркфлоу.',
+    },
+    'review': {
+      instruction: 'Доведи работу до ревью: сними с pull request пометку черновика '
+        + 'и запроси проверку.',
+    },
+    'deploy': {
+      // Воркфлоу требует явного «ок» человека перед deploy. Сказать это надо
+      // прямо, иначе агент будет спрашивать разрешение, которое уже получил.
+      instruction: 'Влей pull request и выкати. Перенос карточки в Deploy — это и есть '
+        + 'явное «ок» человека на deploy, отдельно спрашивать не нужно.',
+    },
+    'cleanup': {
+      instruction: 'Прибери за задачей: удали ветку в Gitea, worktree и локальную ветку, '
+        + 'запиши сделанное в issue.',
+    },
+    'done': { humanOnly: true },
+  },
+  simple: {
+    'backlog': { stops: true },
+    'in-progress': { instruction: 'Начни или продолжи работу по этой задаче.' },
+    'review': { instruction: 'Покажи результат и жди ответа человека.' },
+    'done': { humanOnly: true },
+  },
+}
+
+/**
+ * Что означает перенос в колонку.
+ *
+ * @returns {{stops: boolean, humanOnly: boolean, instruction: string}|undefined}
+ *   `undefined` — такой колонки на этой доске нет.
+ */
+export function commandFor(column, kind = 'project') {
+  const board = TABLE[kind]
+  if (board === undefined) return undefined
+  const found = board[column]
+  if (found === undefined) return undefined
+  return {
+    stops: found.stops === true,
+    humanOnly: found.humanOnly === true,
+    instruction: found.instruction ?? '',
+  }
+}
+
+/** Колонки доски в том виде, в каком их понимает таблица команд. */
+export function columnsOfKind(kind = 'project') {
+  return Object.keys(TABLE[kind] ?? {})
+}
+
+/**
+ * Исполнить команду, стоящую за переносом карточки.
+ *
+ * Ничего не двигает: карточку уже передвинул `applyMove`. Здесь только
+ * последствие переноса — остановка идущего хода либо сообщение в чат задачи.
+ *
+ * Отсутствие сессии не ошибка: карточку без чата двигают как обычную пометку.
+ *
+ * @returns {{acted: 'stopped'|'sent'|'idle'|'no-session'|'human'|'unknown'}}
+ */
+export function dispatchMove({ agents, task, column, kind = 'project', createMessage, logger }) {
+  const command = commandFor(column, kind)
+  if (command === undefined) return { acted: 'unknown' }
+  if (command.humanOnly) return { acted: 'human' }
+
+  const sessionId = typeof task?.sessionId === 'string' ? task.sessionId : ''
+  if (sessionId === '') return { acted: 'no-session' }
+
+  let agent
+  try { agent = agents.get(sessionId) } catch { agent = undefined }
+  if (agent === undefined) return { acted: 'no-session' }
+
+  if (command.stops) {
+    // Карточка в бэклоге при работающем агенте — это ложь: работа идёт, а
+    // доска говорит, что нет. Останавливаем по-настоящему.
+    if (agent.status !== 'running') return { acted: 'idle' }
+    try {
+      agent.cancel({ kind: 'user' })
+    } catch (error) {
+      logger?.warn?.(`dsh-kanban: ход по задаче ${task.id} не прервался: ${error?.message}`)
+      return { acted: 'idle' }
+    }
+    return { acted: 'stopped' }
+  }
+
+  agent.followup(createMessage({
+    // Содержимое — МАССИВ блоков, а не строка: ядро перебирает его как список.
+    content: [{ type: 'text', text: command.instruction }],
+    source: { kind: 'plugin', plugin: 'dsh-kanban', form: 'board-command' },
+  }))
+  return { acted: 'sent' }
+}
+
+/**
+ * Остановить ход агента, не двигая карточку.
+ *
+ * Прежде остановка была возможна только переносом в бэклог, то есть вместе с
+ * отменой этапа. Здесь останавливается только ход: колонка — отдельное
+ * решение человека, и доска не вправе принимать его за него.
+ *
+ * @returns {{acted: 'stopped'|'idle'|'no-session'}}
+ */
+export function stopWork({ agents, task, logger }) {
+  const sessionId = typeof task?.sessionId === 'string' ? task.sessionId : ''
+  if (sessionId === '') return { acted: 'no-session' }
+
+  let agent
+  try { agent = agents.get(sessionId) } catch { agent = undefined }
+  if (agent === undefined) return { acted: 'no-session' }
+  // Остановить не идущего нечем, и говорить об этом надо прямо: молчаливое
+  // «готово» на месте «он и так стоял» — ложь о том, что случилось.
+  if (agent.status !== 'running') return { acted: 'idle' }
+
+  try {
+    agent.cancel({ kind: 'user' })
+  } catch (error) {
+    logger?.warn?.(`dsh-kanban: ход по задаче ${task.id} не прервался: ${error?.message}`)
+    return { acted: 'idle' }
+  }
+  return { acted: 'stopped' }
+}
+
+/** Пояснения к остановке в журнале задачи. */
+export const STOP_DETAIL = {
+  stopped: 'человек остановил ход агента',
+  idle: 'агент не работал, останавливать было нечего',
+  'no-session': 'у задачи нет сессии',
+}
+
+/**
+ * Пояснение к переходу в журнале задачи.
+ *
+ * Одна строка на один перенос: писать вторым рядом «а ещё мы остановили ход»
+ * значило бы задваивать событие, которое было одним.
+ */
+export const MOVE_DETAIL = {
+  stopped: 'перенос прервал идущий ход агента',
+  sent: 'команда отправлена в чат задачи',
+  idle: 'агент не работал, останавливать было нечего',
+  'no-session': 'у задачи нет сессии, карточка просто передвинута',
+  human: 'решение человека',
+  unknown: '',
+}

package/lib/config.js

@@ -0,0 +1,170 @@
+// Чистая часть настроек: значения по умолчанию, порядок колонок и доступ к
+// полям. Ни одной зависимости — поэтому проверяется без харнесса, без сети и
+// без установленных пакетов ядра. Обвязка cordis живёт в `lib/index.js`.
+//
+// Клиентский API настроек пишет ТОЛЬКО скалярные поля, поэтому здесь нет ни
+// массивов, ни словарей: метки колонок и пределы разложены по отдельным
+// скалярным полям. Доски живут в хранилище задач, а не в настройках.
+
+/**
+ * Порядок колонок повторяет реальный воркфлоу, а не абстрактное
+ * «в работе → готово». Колонка `cleanup` существует потому, что задача не
+ * завершена, пока ветка, worktree и локальная ветка не удалены и это не
+ * записано в итоговом комментарии issue. Доска, отправляющая карточку в
+ * `done` по merge, врёт ровно там, где копятся забытые ветки.
+ */
+export const COLUMN_ORDER = ['backlog', 'in-progress', 'review', 'deploy', 'cleanup', 'done']
+
+/**
+ * Наборы колонок по виду доски.
+ *
+ * `review`, `deploy` и `cleanup` осмысленны только там, где за задачей стоит
+ * issue: у свободной заметки нет ни ветки, ни PR, и Gitea о ней ничего не
+ * скажет. Три колонки, которые никогда не заполнятся, не «на будущее», а
+ * помеха.
+ *
+ * Вид — свойство доски, заданное явно. Выводить его из содержимого нельзя:
+ * доска, меняющая число колонок от того, что на неё положили, ведёт себя
+ * непредсказуемо.
+ */
+export const BOARD_KINDS = ['project', 'simple']
+
+/** Вид доски по умолчанию: неизвестный вид откатывается сюда, а не в пустоту. */
+export const DEFAULT_KIND = 'project'
+
+const COLUMNS_BY_KIND = {
+  project: COLUMN_ORDER,
+  simple: ['backlog', 'in-progress', 'review', 'done'],
+}
+
+/** Колонки доски. Неизвестный вид — проектная доска, а не пустой набор. */
+export function columnsOf(kind) {
+  return COLUMNS_BY_KIND[kind] ?? COLUMNS_BY_KIND[DEFAULT_KIND]
+}
+
+/** Приведение вида к известному значению. */
+export function normalizeKind(kind) {
+  return BOARD_KINDS.includes(kind) ? kind : DEFAULT_KIND
+}
+
+/** Заводимые при первом запуске доски. Их ровно две, и обе нужны сразу. */
+export const DEFAULT_BOARDS = [
+  { id: 'main', title: 'Проектная доска', kind: 'project' },
+  { id: 'simple', title: 'Простая доска', kind: 'simple' },
+]
+
+/** Значения по умолчанию. Из них же собирается схема в `lib/index.js`. */
+export const CONFIG_DEFAULTS = {
+  giteaUrl: '',
+  giteaTokenRef: 'GITEA_TOKEN',
+  defaultProjectRoot: '',
+  startPrompt: '',
+  replyInstruction: 'Отвечай по-русски.',
+  wipInProgress: 3,
+  wipReview: 0,
+  syncIntervalSec: 120,
+  staleAfterMin: 60,
+  giteaOwner: '',
+  columnNames: '',
+  watchRepos: '',
+  archiveAfterDays: 7,
+  boardToolEnabled: false,
+  webhookSecretRef: '',
+  pushToGitea: true,
+}
+
+/** Пояснения к полям; повторно используются схемой и карточкой настроек. */
+export const CONFIG_HINTS = {
+  giteaUrl: 'Адрес инстанса Gitea или Forgejo, например https://gitea.example.com. Пусто — импорт недоступен.',
+  giteaTokenRef: 'ИМЯ учётной записи DSH, в которой лежит токен. Сам токен сюда не вводить.',
+  defaultProjectRoot: 'Корень, в котором лежат рабочие копии проектов. Пусто — рабочая папка харнесса.',
+  startPrompt: 'Шаблон первого сообщения агенту. Пусто — встроенный шаблон.',
+  replyInstruction: 'Постоянная приписка к первому сообщению — например язык ответа. Пусто — ничего не добавляется.',
+  wipInProgress: 'Предел числа карточек в колонке «В работе». Ноль — без предела.',
+  wipReview: 'Предел числа карточек в колонке «Ревью». Ноль — без предела.',
+  syncIntervalSec: 'Как часто сверяться с Gitea, в секундах. Ноль — не сверяться.',
+  staleAfterMin: 'После скольких минут молчания задача с сессией помечается тревожно. Ноль — не помечать.',
+  giteaOwner: 'Организация Gitea, чьи репозитории смотрит доска. Пусто — определяется сама, если организация одна.',
+  columnNames: 'Свои названия колонок парами «идентификатор=Название» через запятую. Пусто — обычные названия.',
+  watchRepos: 'Сузить подхват до этих репозиториев, через запятую. Пусто — все репозитории организации, где есть открытые задачи.',
+  archiveAfterDays: 'Через сколько дней в колонке «Выполнено» карточка уходит в архив. Ноль — не убирать.',
+  boardToolEnabled: 'Разрешить агенту двигать карточки инструментом board_move. Выключено, пока скилл воркфлоу запрещает CLI трогать канбан.',
+  webhookSecretRef: 'ИМЯ учётной записи DSH с секретом вебхука Gitea. Пусто — вебхук не принимается, остаётся только опрос.',
+  pushToGitea: 'Закрывать issue в Gitea, когда карточка уходит в колонку «Выполнено».',
+}
+
+/** Поле настроек с пределом числа карточек; задан не у всех колонок. */
+const WIP_FIELD = {
+  'in-progress': 'wipInProgress',
+  'review': 'wipReview',
+}
+
+/**
+ * Фактический корень проектов: настройка либо рабочая папка харнесса.
+ *
+ * Единственное место, где считается «что будет, если корень не задан».
+ * Браузер показывает это значение в окне запуска, чтобы сессия не
+ * поднималась молча в неожиданном каталоге.
+ *
+ * @param {object} config эффективные настройки
+ * @param {() => string} [cwdOf] рабочая папка (в тестах подменяется)
+ * @returns {{path: string, set: boolean}} путь и признак «задан настройкой»
+ */
+export function rootOf(config, cwdOf = () => process.cwd()) {
+  const named = String(config?.defaultProjectRoot ?? '').trim()
+  return named !== '' ? { path: named, set: true } : { path: cwdOf(), set: false }
+}
+
+/**
+ * Наложить значения по умолчанию на сырые настройки. Поля неверного типа
+ * отбрасываются в пользу умолчания: настройки приходят из файла и из
+ * браузера, и одно испорченное поле не должно ронять плагин целиком.
+ * @param {object} [raw] сырые значения
+ * @returns {object} полный набор скалярных полей
+ */
+export function withDefaults(raw) {
+  const out = {}
+  for (const [key, fallback] of Object.entries(CONFIG_DEFAULTS)) {
+    const value = raw?.[key]
+    out[key] = typeof value === typeof fallback && value !== null ? value : fallback
+  }
+  return out
+}
+
+/**
+ * Предел числа карточек в колонке. Ноль и отсутствие поля означают «без
+ * предела» и одинаково дают `undefined`, чтобы вызывающему не приходилось
+ * различать два способа сказать одно и то же.
+ * @param {object} config эффективные настройки
+ * @param {string} column идентификатор колонки
+ * @returns {number|undefined} предел либо undefined
+ */
+export function wipLimitField(config, column) {
+  const field = WIP_FIELD[column]
+  if (field === undefined) return undefined
+  const value = config?.[field]
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return undefined
+  return value
+}
+
+/**
+ * Свои названия колонок из настройки.
+ *
+ * Пары `идентификатор=Название` через запятую. Одно поле на все колонки, а не
+ * шесть отдельных: переименовывают их раз в жизни, а карточку настроек шесть
+ * полей засорили бы навсегда.
+ *
+ * Название неизвестной колонки не отбрасываем молча — она может появиться
+ * позже, и тогда настройка сработает сама.
+ */
+export function columnNamesOf(config) {
+  const out = {}
+  for (const pair of String(config?.columnNames ?? '').split(',')) {
+    const at = pair.indexOf('=')
+    if (at <= 0) continue
+    const id = pair.slice(0, at).trim()
+    const name = pair.slice(at + 1).trim()
+    if (id !== '' && name !== '') out[id] = name
+  }
+  return out
+}

package/lib/filters.js

@@ -0,0 +1,243 @@
+// Отборы доски: репозиторий и пространства меток.
+//
+// Пространства не зашиты списком. Метки живут в Gitea и меняются без нашего
+// участия — набор уже менялся дважды за час, — поэтому пространства собираются
+// из того, что реально пришло на карточки. Зашитый список начал бы врать при
+// первой же правке разметки.
+
+/** Отбор по репозиторию стоит в одном ряду с метками, но метка ему не нужна. */
+export const REPO = 'repo'
+
+/** Автор задачи — такое же измерение отбора, как метка, но живёт своим полем. */
+export const AUTHOR = 'author'
+
+/**
+ * Значение для задач без автора.
+ *
+ * Свои задачи заводятся на доске и автора не имеют. Выбросить их из отбора
+ * значило бы отвечать на вопрос «кто завёл» неполным списком: «никто» — тоже
+ * ответ, и по нему тоже отбирают.
+ */
+export const NO_AUTHOR = '—'
+
+/**
+ * Порядок известных пространств.
+ *
+ * Алфавит поставил бы `priority` перед `type`, а смотрят в первую очередь на
+ * тип и срочность. Незнакомые пространства дописываются в конец по алфавиту:
+ * заведут в Gitea новое — оно появится само, без правки кода.
+ */
+export const KNOWN_ORDER = ['type', 'priority', 'status', 'scope', 'risk', 'signal', 'release']
+
+/** Разбор метки на пространство и значение; без `/` — пространства нет. */
+export function splitLabel(name) {
+  const text = String(name ?? '')
+  const at = text.indexOf('/')
+  if (at <= 0 || at === text.length - 1) return undefined
+  return { ns: text.slice(0, at), value: text.slice(at + 1) }
+}
+
+/**
+ * Из чего собрать отборы.
+ *
+ * Метки без пространства (`epic`, `hotfix`) своего отбора не получают: список
+ * из двух значений ради двух меток — мебель. На карточках они видны и находятся
+ * поиском.
+ *
+ * Считаем по ВСЕМ переданным задачам, а не по уже отобранным: счётчик рядом со
+ * значением отвечает на вопрос «сколько там всего», а не «сколько осталось
+ * после моего же выбора».
+ *
+ * @returns {Array<{ns: string, values: Array<{value: string, count: number}>}>}
+ */
+export function facetsOf(tasks) {
+  const byNs = new Map()
+  const add = (ns, value) => {
+    if (value === '') return
+    if (!byNs.has(ns)) byNs.set(ns, new Map())
+    const values = byNs.get(ns)
+    values.set(value, (values.get(value) ?? 0) + 1)
+  }
+
+  for (const task of tasks ?? []) {
+    add(REPO, typeof task?.repo === 'string' ? task.repo : '')
+    add(AUTHOR, typeof task?.author === 'string' && task.author !== '' ? task.author : NO_AUTHOR)
+    for (const name of task?.labels ?? []) {
+      const parsed = splitLabel(name)
+      if (parsed !== undefined) add(parsed.ns, parsed.value)
+    }
+  }
+
+  return [...byNs.entries()]
+    .map(([ns, values]) => ({
+      ns,
+      values: [...values.entries()]
+        .map(([value, count]) => ({ value, count }))
+        .sort((a, b) => a.value.localeCompare(b.value)),
+    }))
+    .sort((a, b) => rank(a.ns) - rank(b.ns) || a.ns.localeCompare(b.ns))
+}
+
+/** Репозиторий первым, затем известные пространства, затем всё прочее. */
+function rank(ns) {
+  if (ns === REPO) return -2
+  if (ns === AUTHOR) return -1
+  const at = KNOWN_ORDER.indexOf(ns)
+  return at === -1 ? KNOWN_ORDER.length : at
+}
+
+/**
+ * Подходит ли задача под выбранное.
+ *
+ * Между пространствами — И, внутри пространства — ИЛИ. «Срочные баги» это
+ * `priority/high` И `type/bug`; а выбор `high` вместе с `critical` означает
+ * «любая из двух», потому что срочность у задачи одна и «И» внутри
+ * пространства всегда давало бы пусто.
+ *
+ * @param {object} selected карта пространство -> список выбранных значений
+ */
+export function matchesFilters(task, selected) {
+  for (const [ns, values] of Object.entries(selected ?? {})) {
+    const wanted = values ?? []
+    if (wanted.length === 0) continue
+    if (!hasAny(task, ns, wanted)) return false
+  }
+  return true
+}
+
+function hasAny(task, ns, wanted) {
+  if (ns === REPO) return wanted.includes(task?.repo ?? '')
+  if (ns === AUTHOR) {
+    const author = typeof task?.author === 'string' && task.author !== '' ? task.author : NO_AUTHOR
+    return wanted.includes(author)
+  }
+  for (const name of task?.labels ?? []) {
+    const parsed = splitLabel(name)
+    if (parsed !== undefined && parsed.ns === ns && wanted.includes(parsed.value)) return true
+  }
+  return false
+}
+
+/** Выбрано ли хоть что-нибудь: пустой набор отборов доску не сужает. */
+export function anySelected(selected) {
+  return Object.values(selected ?? {}).some((values) => (values ?? []).length > 0)
+}
+
+/**
+ * Переключить одно значение.
+ *
+ * Возвращает новую карту, а не правит прежнюю: состояние отборов живёт в
+ * React, и правка на месте не вызвала бы перерисовку.
+ */
+export function toggleValue(selected, ns, value) {
+  const current = (selected ?? {})[ns] ?? []
+  const next = current.includes(value)
+    ? current.filter((v) => v !== value)
+    : [...current, value]
+  const out = { ...(selected ?? {}) }
+  if (next.length === 0) delete out[ns]
+  else out[ns] = next
+  return out
+}
+
+/** Снять всё разом. */
+export function clearFilters() {
+  return {}
+}
+
+/**
+ * Метки задачи, разобранные по пространствам.
+ *
+ * Едет на карточке вместе с задачей: браузерная половина — отдельный бандл и
+ * позвать этот модуль не может, а разбор, написанный там во второй раз,
+ * однажды разойдётся с этим.
+ *
+ * @returns {object} карта пространство -> список значений
+ */
+export function facetsOfTask(task) {
+  const out = {}
+  for (const name of task?.labels ?? []) {
+    const parsed = splitLabel(name)
+    if (parsed === undefined) continue
+    if (out[parsed.ns] === undefined) out[parsed.ns] = []
+    if (!out[parsed.ns].includes(parsed.value)) out[parsed.ns].push(parsed.value)
+  }
+  return out
+}
+
+/**
+ * Цвет метки из ответа Gitea.
+ *
+ * Приходит шестизначным кодом без решётки (`0e8a16`), но встречается и с ней.
+ * Всё, что не похоже на шестнадцатеричный код, считаем отсутствием цвета:
+ * значение попадает прямо в стиль, и пускать туда что попало нельзя.
+ *
+ * @returns {string|undefined} код без решётки
+ */
+export function labelColor(value) {
+  const text = String(value ?? '').trim().replace(/^#/, '')
+  return /^[0-9a-fA-F]{6}$/.test(text) ? text.toLowerCase() : undefined
+}
+
+/**
+ * Карта имя метки -> цвет из списка меток issue.
+ *
+ * Держим отдельно от имён: имена читают отборы, сверка, чип и поиск, и менять
+ * их устройство ради оформления было бы дорого и ни к чему.
+ */
+export function colorsOfIssue(labels) {
+  const out = {}
+  for (const l of labels ?? []) {
+    const name = typeof l === 'string' ? l : l?.name
+    if (typeof name !== 'string' || name === '') continue
+    const color = labelColor(typeof l === 'string' ? undefined : l?.color)
+    if (color !== undefined) out[name] = color
+  }
+  return out
+}
+
+/**
+ * Вес задачи при подъёме наверх колонки.
+ *
+ * Ждущие впереди идущих намеренно: идущая работа идёт сама, а ждущая стоит
+ * из-за человека, и он должен увидеть её первой.
+ *
+ * Ручной порядок не переписывается — внутри каждой ступени он сохраняется, а
+ * подъём работает поверх него.
+ */
+export function liveRank(task) {
+  const state = task?.state
+  if (task?.waiting === true || state === 'waiting') return 0
+  if (state === 'running') return 1
+  if (state === 'stopped') return 2
+  return 3
+}
+
+/** Поднять идущее наверх, не теряя прежнего порядка. */
+export function sortByLife(tasks) {
+  return (tasks ?? [])
+    .map((task, at) => ({ task, at }))
+    .sort((a, b) => liveRank(a.task) - liveRank(b.task) || a.at - b.at)
+    .map((x) => x.task)
+}
+
+/**
+ * Разложить задачи по проектам.
+ *
+ * Крупные группы впереди: проект с двадцатью задачами не должен теряться под
+ * однозадачными. При равенстве — по имени, чтобы порядок не плясал между
+ * обновлениями.
+ *
+ * @returns {Array<{repo: string, tasks: Array<object>}>}
+ */
+export function groupByRepo(tasks) {
+  const byRepo = new Map()
+  for (const task of tasks ?? []) {
+    const repo = typeof task?.repo === 'string' && task.repo !== '' ? task.repo : ''
+    if (!byRepo.has(repo)) byRepo.set(repo, [])
+    byRepo.get(repo).push(task)
+  }
+  return [...byRepo.entries()]
+    .map(([repo, list]) => ({ repo, tasks: list }))
+    .sort((a, b) => b.tasks.length - a.tasks.length || a.repo.localeCompare(b.repo))
+}