@goodandready/dsh-kanban 0.2.19 → 0.2.21

package/lib/store.js

@@ -1,15 +1,13 @@
-// Хранилище задач доски.
+// Board task storage.
 //
-// У канбана свои поля и своя история, которых в Gitea нет: сессия, модель,
-// журнал переходов, порядок карточек. Поэтому задачи живут здесь, а не только
-// в issue.
+// Kanban maintains its own fields and history not tracked in Gitea: session,
+// model, transition log, and card ordering. Tasks therefore persist here in SQLite.
 //
-// Колонка в таблице названа `col`, а не `column`: `column` — зарезервированное
-// слово SQL, и без экранирования запрос падает. Наружу поле по-прежнему
-// называется `column`, переименование спрятано внутри этого модуля.
+// Column is named `col` in the schema because `column` is a reserved SQL keyword.
+// Externally, the field remains named `column`.
 //
-// Поля `branch` и `worktree` — НАБЛЮДЕНИЕ, вычитанное из issue и событий
-// Gitea, а не намерение: плагин ветки не создаёт.
+// Fields `branch` and `worktree` are observed from issues and Gitea events rather
+// than driven locally: this plugin does not create branches.
 
 import { DatabaseSync } from 'node:sqlite'
 import { randomUUID } from 'node:crypto'
@@ -98,7 +96,7 @@ CREATE TABLE IF NOT EXISTS dismissed (
 );
 `
 
-/** Поля задачи, которые разрешено править через updateTask. */
+/** Task fields allowed to be modified via updateTask. */
 const WRITABLE = [
   'title', 'body', 'owner', 'repo', 'issueNumber', 'issueUrl', 'externalRef', 'labels',
   'branch', 'worktree', 'workspaceId', 'sessionId', 'model', 'provider', 'waiting', 'syncedAt', 'plan',
@@ -108,7 +106,7 @@ const WRITABLE = [
   'workflowRunId', 'workflowStatus',
 ]
 
-/** Источники перехода; чужое значение не пишем, чтобы журнал оставался читаемым. */
+/** Valid transition sources; unexpected values are rejected to preserve log integrity. */
 const SOURCES = new Set(['manual', 'session', 'gitea', 'github', 'tool', 'workflow'])
 
 function rowToTask(row) {
@@ -118,32 +116,32 @@ function rowToTask(row) {
   try {
     const value = JSON.parse(checklist ?? '[]')
     if (Array.isArray(value)) parsedChecklist = value
-  } catch { /* игнорируем битый json */ }
+  } catch { /* ignore malformed json */ }
   let parsedReport = {}
   try {
     const value = JSON.parse(report ?? '{}')
     if (value !== null && typeof value === 'object' && !Array.isArray(value)) parsedReport = value
-  } catch { /* игнорируем битый json */ }
+  } catch { /* ignore malformed json */ }
   let parsedComments = []
   try {
     const value = JSON.parse(comments ?? '[]')
     if (Array.isArray(value)) parsedComments = value
-  } catch { /* игнорируем битый json */ }
+  } catch { /* ignore malformed json */ }
   let parsed = []
   try {
     const value = JSON.parse(labels)
     if (Array.isArray(value)) parsed = value.filter((l) => typeof l === 'string')
-  } catch { /* испорченное поле не должно ронять чтение всей доски */ }
+  } catch { /* corrupted field must not fail board read */ }
   let colors = {}
   try {
     const value = JSON.parse(labelColors ?? '{}')
     if (value !== null && typeof value === 'object' && !Array.isArray(value)) colors = value
-  } catch { /* испорченное поле не должно ронять чтение всей доски */ }
+  } catch { /* corrupted field must not fail board read */ }
   let parsedRuns = []
   try {
     const value = JSON.parse(runs ?? '[]')
     if (Array.isArray(value)) parsedRuns = value
-  } catch { /* испорченное поле не должно ронять чтение всей доски */ }
+  } catch { /* corrupted field must not fail board read */ }
   return {
     ...rest,
     column: col,
@@ -163,11 +161,11 @@ function rowToTask(row) {
 }
 
 /**
- * Обеспечить безопасные права доступа к каталогу хранилища и файлам базы.
- * Каталог и подкаталог бэкапов: 0700 (rwx------)
- * Файлы базы, WAL, SHM и файлы бэкапов: 0600 (rw-------)
+ * Ensure secure file permissions for the storage directory and database files.
+ * Directory and backups subdirectory: 0700 (rwx------)
+ * Database, WAL, SHM, and backup files: 0600 (rw-------)
  *
- * @param {string} dir каталог хранилища
+ * @param {string} dir storage directory path
  */
 export function secureStorePermissions(dir) {
   try {
@@ -197,9 +195,9 @@ export function secureStorePermissions(dir) {
 }
 
 /**
- * Открыть хранилище задач.
- * @param {{dir: string}} options каталог, в котором лежит файл базы
- * @returns {object} интерфейс хранилища
+ * Open task database storage.
+ * @param {{dir: string}} options directory holding the database file
+ * @returns {object} storage interface
  */
 export function openStore({ dir }) {
   mkdirSync(dir, { recursive: true, mode: 0o700 })
@@ -209,9 +207,8 @@ export function openStore({ dir }) {
   db.exec('PRAGMA foreign_keys = ON')
   db.exec('PRAGMA busy_timeout = 5000')
   db.exec(SCHEMA)
-  // База могла быть создана прежней версией. Добавляем недостающие столбцы
-  // поштучно: ALTER на существующий столбец бросает, и это штатный ответ
-  // «уже есть», а не поломка.
+  // Database might have been created by an older version. Add missing columns
+  // individually: duplicate ALTER TABLE errors are safely caught and ignored.
   for (const [column, definition] of [
     ['waiting', 'INTEGER NOT NULL DEFAULT 0'],
     ['syncedAt', 'INTEGER NOT NULL DEFAULT 0'],
@@ -246,14 +243,13 @@ export function openStore({ dir }) {
     ['workflowRunId', "TEXT NOT NULL DEFAULT ''"],
     ['workflowStatus', "TEXT NOT NULL DEFAULT ''"],
   ]) {
-    try { db.exec(`ALTER TABLE tasks ADD COLUMN ${column} ${definition}`) } catch { /* столбец уже есть */ }
+    try { db.exec(`ALTER TABLE tasks ADD COLUMN ${column} ${definition}`) } catch { /* column already exists */ }
   }
-  try { db.exec("ALTER TABLE boards ADD COLUMN kind TEXT NOT NULL DEFAULT 'project'") } catch { /* уже есть */ }
-  // Старые карточки не знают, когда попали в свою колонку. Считаем от
-  // заведения: это честнее нуля, который читался бы как «в 1970 году».
+  try { db.exec("ALTER TABLE boards ADD COLUMN kind TEXT NOT NULL DEFAULT 'project'") } catch { /* already exists */ }
+  // Older cards lack column entry timestamps; default to creation timestamp.
   db.exec('UPDATE tasks SET columnAt = createdAt WHERE columnAt = 0')
 
-  // Индексы для ускорения выборок активных задач, поиска по Gitea issue и cron-задач
+  // Indexes for active tasks, Gitea issue lookups, and cron jobs.
   db.exec('CREATE INDEX IF NOT EXISTS tasks_board_active ON tasks(board, archivedAt, col, position)')
   db.exec('CREATE INDEX IF NOT EXISTS tasks_gitea_issue ON tasks(owner, repo, issueNumber)')
   db.exec('CREATE INDEX IF NOT EXISTS tasks_external_ref ON tasks(externalRef)')
@@ -265,7 +261,7 @@ export function openStore({ dir }) {
   db.exec('PRAGMA synchronous = NORMAL')
   try { db.exec('PRAGMA optimize') } catch { /* pragma optimize best-effort */ }
 
-  // Повторно обеспечиваем права на созданные/изменённые файлы базы, WAL и SHM
+  // Enforce secure permissions on newly created or modified DB/WAL/SHM files.
   secureStorePermissions(dir)
 
   const q = {
@@ -316,16 +312,11 @@ export function openStore({ dir }) {
     return q.boardById.get(id)
   }
 
-  // Обе доски заводятся сразу: пустое хранилище без единой доски выглядит в
-  // интерфейсе как поломка, а не как чистый старт.
-  //
-  // Прежняя единственная доска `main` СТАНОВИТСЯ проектной, а не заводится
-  // рядом с новой: заведи мы вторую, задачи остались бы на осиротевшей.
+  // Initialize default boards so an empty store does not render as broken.
+  // The original 'main' board becomes project-kind rather than creating a duplicate.
   for (const board of DEFAULT_BOARDS) ensureBoard(board.id, board.title, board.kind)
-  // Прежняя доска называлась «Основная», и рядом с «Простой» это читается как
-  // разница в важности, а не в виде. Переименовываем только нетронутое
-  // название: если его меняли, значит оно чьё-то.
-  db.prepare("UPDATE boards SET title = ? WHERE id = 'main' AND title = 'Основная доска'")
+  // Rename legacy default title to English if it was untouched.
+  db.prepare("UPDATE boards SET title = ? WHERE id = 'main' AND (title = 'Main board' OR title = '\u041e\u0441\u043d\u043e\u0432\u043d\u0430\u044f \u0434\u043e\u0441\u043a\u0430')")
     .run(DEFAULT_BOARDS[0].title)
 
   function positionFor(board, column, beforeId, afterId) {
@@ -363,7 +354,7 @@ export function openStore({ dir }) {
       copyFileSync(join(dir, 'kanban.db'), dest)
       try { chmodSync(dest, 0o600) } catch { /* ignore */ }
 
-      // Ротация: сохраняем только последние 10 бэкапов
+      // Rotation: retain only the 10 most recent backups.
       try {
         const files = readdirSync(backupsDir)
           .filter((f) => f.startsWith('kanban-backup-') && f.endsWith('.db'))
@@ -391,7 +382,7 @@ export function openStore({ dir }) {
       return ensureBoard(id, title ?? id, kind)
     },
 
-    /** Вид доски. Неизвестная доска — проектная: пустого набора колонок нет. */
+    /** Board kind. Unrecognized kinds default to 'project'. */
     boardKind(id) {
       return normalizeKind(q.boardById.get(id)?.kind)
     },
@@ -405,17 +396,16 @@ export function openStore({ dir }) {
       return rowToTask(q.taskById.get(id))
     },
 
-    /** Задачи, за которыми стоит issue и по которым работа ещё идёт. */
+    /** Active tasks linked to a Gitea issue currently in progress. */
     listWatchable() {
       return q.watchable.all().map(rowToTask)
     },
 
     /**
-     * ВСЕ задачи сессии, в порядке постановки в очередь.
+     * All tasks belonging to a session, ordered by queue time.
      *
-     * Одна сессия ведёт пачку задач, и «чья это сессия» перестало иметь
-     * единственный ответ. Инструменты обязаны различать один случай от
-     * нескольких, а не брать первую попавшуюся.
+     * A single session can manage a batch of tasks, so tools must distinguish
+     * single-task from batch workflows.
      */
     listTasksBySession(sessionId) {
       if (!sessionId) return []
@@ -435,14 +425,12 @@ export function openStore({ dir }) {
 
     createTask(input) {
       const now = Date.now()
-      // Задача заведена тогда, когда её завели в Gitea, а не когда подхват
-      // довёз карточку. `columnAt` остаётся сегодняшним: в колонку она въехала
-      // сейчас, и это разные даты.
+      // Card creation timestamp reflects when the issue was created in Gitea.
+      // columnAt reflects when it entered the column.
       const born = Number(input.createdAt) || now
       const board = input.board ?? 'main'
       const column = input.column ?? 'backlog'
-      // Импорт восстанавливает задачу с её прежним id; обычное заведение
-      // генерирует новый.
+      // Import restores existing task ID; new creation generates a random UUID.
       const id = typeof input.id === 'string' && input.id !== '' ? input.id : randomUUID()
       const position = positionFor(board, column, input.beforeId, input.afterId)
       q.insertTask.run(
@@ -485,7 +473,7 @@ export function openStore({ dir }) {
 
     updateTask(id, patch) {
       const current = q.taskById.get(id)
-      if (current === undefined) throw new Error(`задача ${id} не найдена`)
+      if (current === undefined) throw new Error(`task ${id} not found`)
       const fields = []
       const values = []
       for (const key of WRITABLE) {
@@ -553,6 +541,15 @@ export function openStore({ dir }) {
       return this.updateTask(id, { comments })
     },
 
+    addTaskComment(id, comment) {
+      if (!comment || typeof comment !== 'object') return undefined
+      return this.addComment(id, {
+        author: comment.author,
+        role: comment.role,
+        text: comment.text || comment.body || '',
+      })
+    },
+
     updateChecklist(id, items) {
       const task = rowToTask(q.taskById.get(id))
       if (!task) return undefined
@@ -572,7 +569,7 @@ export function openStore({ dir }) {
       const task = rowToTask(q.taskById.get(id))
       if (!task) return undefined
       const r = String(reason ?? '').trim()
-      const commentText = `[Возврат на доработку / Rejection]: ${r}`
+      const commentText = `[Rejection]: ${r}`
       this.addComment(id, { author: 'user', role: 'user', text: commentText })
       this.moveTask(id, { column: 'in-progress' })
       this.addTransition({
@@ -600,17 +597,14 @@ export function openStore({ dir }) {
     },
     moveTask(id, { column, beforeId, afterId }) {
       const current = q.taskById.get(id)
-      if (current === undefined) throw new Error(`задача ${id} не найдена`)
+      if (current === undefined) throw new Error(`task ${id} not found`)
       const target = column ?? current.col
       const position = positionFor(current.board, target, beforeId, afterId)
       const now = Date.now()
-      // Время в колонке считаем по отметке, а не по журналу переходов: журнал
-      // пришлось бы читать на каждую карточку при каждой сборке доски.
-      // Перестановка внутри колонки отметку НЕ сбрасывает — задача в ревью
-      // третий день там и остаётся, как бы её ни двигали вверх-вниз.
+      // Time in column is tracked via timestamp rather than querying transition logs.
+      // Reordering within the column preserves columnAt.
       const enteredAt = target === current.col ? current.columnAt : now
-      // Переезд в работу снимает задачу с очереди: она уже не ждёт, а
-      // делается. Иначе номер очереди висел бы у карточки, которая идёт.
+      // Moving to in-progress resets queuedAt since the task is no longer waiting.
       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)
@@ -618,9 +612,7 @@ export function openStore({ dir }) {
     },
 
     deleteTask(id) {
-      // Удалённая карточка задачи из Gitea запоминается как отказанная: иначе
-      // подхват вернул бы её на доску следующим же проходом, и доска спорила
-      // бы с человеком каждые две минуты.
+      // Record deleted Gitea tasks as dismissed to prevent the intake loop from re-importing them.
       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())
@@ -628,12 +620,12 @@ export function openStore({ dir }) {
       q.deleteTask.run(id)
     },
 
-    /** Отказывались ли уже от этого issue. */
+    /** Whether an issue was previously dismissed. */
     isDismissed({ owner, repo, issueNumber }) {
       return q.isDismissed.get(owner, repo, issueNumber) !== undefined
     },
 
-    /** Задача по issue — чтобы подхват не заводил второй раз то же самое. */
+    /** Find task by issue to prevent duplicate import. */
     findTaskByIssue({ owner, repo, issueNumber }) {
       return rowToTask(q.byIssue.get(owner, repo, issueNumber))
     },
@@ -659,17 +651,16 @@ export function openStore({ dir }) {
       return this.updateTask(id, { parentId: parentId ?? '' })
     },
 
-    /** Задачи в архиве: свой список, а не колонка. */
+    /** Archived tasks list. */
     listArchived() {
       return q.archived.all().map(rowToTask)
     },
 
     /**
-     * Что пора убрать в архив.
+     * Query tasks ready for archiving.
      *
-     * Возраст считаем по отметке входа в колонку, а не по `updatedAt`: сверка
-     * трогает задачу и после завершения, и по `updatedAt` архив откладывался
-     * бы бесконечно.
+     * Age is calculated based on column entry timestamp rather than updatedAt,
+     * as background reconciliation touches updatedAt after completion.
      */
     listArchivable(before) {
       return q.archivable.all(before).map(rowToTask)
@@ -682,7 +673,7 @@ export function openStore({ dir }) {
     },
 
     addTransition({ taskId, fromCol, toCol, source, detail }) {
-      if (!SOURCES.has(source)) throw new Error(`неизвестный источник перехода: ${source}`)
+      if (!SOURCES.has(source)) throw new Error(`unknown transition source: ${source}`)
       q.insertTransition.run(taskId, fromCol ?? null, toCol, source, detail ?? '', Date.now())
     },
 
@@ -690,14 +681,14 @@ export function openStore({ dir }) {
       return q.transitionsOf.all(taskId)
     },
 
-    /** Все переходы разом: метрике нужен журнал целиком, а не по одной задаче. */
+    /** Return all transitions; used by metrics calculator across the entire board. */
     listAllTransitions() {
       return q.allTransitions.all()
     },
 
     /**
-     * Полный снимок доски для экспорта: все доски, все задачи (включая
-     * архивные) и журнал переходов. Импорт восстанавливает его как есть.
+     * Full board snapshot for export: all boards, tasks (including archived),
+     * and transition history.
      */
     exportAll() {
       return {