@goodandready/dsh-kanban 0.2.18 → 0.2.20

package/lib/commands.js

@@ -1,21 +1,14 @@
-// Перенос карточки — это КОМАНДА агенту, а не запись о состоянии.
-//
-// Владелец не двигает карточки вручную ради учёта: если он двинул, значит
-// просит запустить тот этап, куда двинул. Поэтому таблица ниже описывает не
-// «что стало», а «что сделать», и текст уходит в чат задачи.
-//
-// Тексты последствий для окна подтверждения живут в клиентской половине:
-// они переводятся, а инструкция агенту — нет.
+// Moving a card is a COMMAND to the agent, not merely a state update.
+// If user moved a card, it instructs the agent to run that lifecycle phase.
+// Confirmation dialog texts reside in client bundles where they are localized.
 
-/** Виды досок. Простая доска появляется в #63; таблица под неё уже здесь. */
+/** Board kinds. Simple board introduced in #63; table supports it here. */
 export const BOARD_KINDS = ['project', 'simple']
 
 /**
- * Колонка `done` для инструмента агента закрыта.
- *
- * Путь агента к завершению — получить согласие, закрыть issue и удалить ветку;
- * сверка с Gitea сама увидит закрытый issue без ветки и передвинет карточку.
- * Карточка двигается фактом, а не заявлением, и подделать это нечем.
+ * `done` column is inaccessible to agent tool.
+ * Agent finishes task by obtaining acceptance, closing issue and deleting branch.
+ * Sync detects closed issue without branch and advances the card.
  */
 export const TOOL_FORBIDDEN_COLUMNS = ['done']
 
@@ -45,10 +38,10 @@ const TABLE = {
 }
 
 /**
- * Что означает перенос в колонку.
+ * Semantics of moving card to column.
  *
  * @returns {{stops: boolean, humanOnly: boolean, instruction: string}|undefined}
- *   `undefined` — такой колонки на этой доске нет.
+ *   `undefined` - column absent on this board.
  */
 export function commandFor(column, kind = 'project') {
   if (!columnsOfKind(kind).includes(column)) return undefined
@@ -63,18 +56,15 @@ export function commandFor(column, kind = 'project') {
   }
 }
 
-/** Колонки доски в том виде, в каком их понимает таблица команд. */
+/** Board columns as understood by commands table. */
 export function columnsOfKind(kind = 'project') {
   return Object.keys(TABLE[kind] ?? {})
 }
 
 /**
- * Исполнить команду, стоящую за переносом карточки.
- *
- * Ничего не двигает: карточку уже передвинул `applyMove`. Здесь только
- * последствие переноса — остановка идущего хода либо сообщение в чат задачи.
- *
- * Отсутствие сессии не ошибка: карточку без чата двигают как обычную пометку.
+ * Execute command triggered by moving a card.
+ * Does not move card: move already applied. Handles side effects:
+ * interrupting active turn or posting instruction to task chat.
  *
  * @returns {{acted: 'stopped'|'sent'|'idle'|'no-session'|'human'|'unknown'}}
  */
@@ -91,8 +81,7 @@ export function dispatchMove({ agents, task, column, kind = 'project', createMes
   if (agent === undefined) return { acted: 'no-session' }
 
   if (command.stops) {
-    // Карточка в бэклоге при работающем агенте — это ложь: работа идёт, а
-    // доска говорит, что нет. Останавливаем по-настоящему.
+    // Card in backlog with running agent is inconsistent: interrupt active turn.
     if (agent.status !== 'running') return { acted: 'idle' }
     try {
       agent.cancel({ kind: 'user' })
@@ -104,7 +93,7 @@ export function dispatchMove({ agents, task, column, kind = 'project', createMes
   }
 
   agent.followup(createMessage({
-    // Содержимое — МАССИВ блоков, а не строка: ядро перебирает его как список.
+    // Content is array of blocks: core processes as list.
     content: [{ type: 'text', text: command.instruction }],
     source: { kind: 'dsh-kanban', plugin: 'dsh-kanban', form: 'board-command' },
   }))
@@ -112,11 +101,8 @@ export function dispatchMove({ agents, task, column, kind = 'project', createMes
 }
 
 /**
- * Остановить ход агента, не двигая карточку.
- *
- * Прежде остановка была возможна только переносом в бэклог, то есть вместе с
- * отменой этапа. Здесь останавливается только ход: колонка — отдельное
- * решение человека, и доска не вправе принимать его за него.
+ * Stop agent turn without moving card.
+ * Interrupts execution while preserving column position.
  *
  * @returns {{acted: 'stopped'|'idle'|'no-session'}}
  */
@@ -127,8 +113,7 @@ export function stopWork({ agents, task, logger }) {
   let agent
   try { agent = agents.get(sessionId) } catch { agent = undefined }
   if (agent === undefined) return { acted: 'no-session' }
-  // Остановить не идущего нечем, и говорить об этом надо прямо: молчаливое
-  // «готово» на месте «он и так стоял» — ложь о том, что случилось.
+  // Agent was already idle, report explicitly.
   if (agent.status !== 'running') return { acted: 'idle' }
 
   try {
@@ -140,7 +125,7 @@ export function stopWork({ agents, task, logger }) {
   return { acted: 'stopped' }
 }
 
-/** Пояснения к остановке в журнале задачи. */
+/** Stop details recorded in task transitions. */
 export const STOP_DETAIL = {
   stopped: 'user stopped agent turn',
   idle: 'agent was idle, nothing to stop',
@@ -148,10 +133,8 @@ export const STOP_DETAIL = {
 }
 
 /**
- * Пояснение к переходу в журнале задачи.
- *
- * Одна строка на один перенос: писать вторым рядом «а ещё мы остановили ход»
- * значило бы задваивать событие, которое было одним.
+ * Transition detail recorded in task history.
+ * Single event entry per transition.
  */
 export const MOVE_DETAIL = {
   stopped: 'move interrupted running agent turn',

package/lib/config.js

@@ -1,35 +1,25 @@
-// Чистая часть настроек: значения по умолчанию, порядок колонок и доступ к
-// полям. Ни одной зависимости — поэтому проверяется без харнесса, без сети и
-// без установленных пакетов ядра. Обвязка cordis живёт в `lib/index.js`.
+// Pure configuration logic: defaults, column ordering, and field accessors.
+// Zero dependencies: tested without harness, network, or core packages.
+// Cordis bindings reside in `lib/index.js`.
 //
-// Клиентский API настроек пишет ТОЛЬКО скалярные поля, поэтому здесь нет ни
-// массивов, ни словарей: метки колонок и пределы разложены по отдельным
-// скалярным полям. Доски живут в хранилище задач, а не в настройках.
+// Client settings API writes scalar values only; complex options are decomposed
+// into individual scalar settings.
 
 /**
- * Порядок колонок повторяет реальный воркфлоу, а не абстрактное
- * «в работе → готово». Колонка `cleanup` существует потому, что задача не
- * завершена, пока ветка, worktree и локальная ветка не удалены и это не
- * записано в итоговом комментарии issue. Доска, отправляющая карточку в
- * `done` по merge, врёт ровно там, где копятся забытые ветки.
+ * Column order mirrors the actual workflow.
+ * `cleanup` column exists because a task is not done until remote branch,
+ * worktree, and local branch are cleaned up and recorded in issue comment.
  */
 export const COLUMN_ORDER = ['backlog', 'in-progress', 'review', 'deploy', 'cleanup', 'done']
 
 /**
- * Наборы колонок по виду доски.
+ * Column sets per board kind.
  *
- * `review`, `deploy` и `cleanup` осмысленны только там, где за задачей стоит
- * issue: у свободной заметки нет ни ветки, ни PR, и Gitea о ней ничего не
- * скажет. Три колонки, которые никогда не заполнятся, не «на будущее», а
- * помеха.
  *
- * Вид — свойство доски, заданное явно. Выводить его из содержимого нельзя:
- * доска, меняющая число колонок от того, что на неё положили, ведёт себя
- * непредсказуемо.
  */
 export const BOARD_KINDS = ['project', 'simple']
 
-/** Вид доски по умолчанию: неизвестный вид откатывается сюда, а не в пустоту. */
+/** Default board kind fallback. */
 const DEFAULT_KIND = 'project'
 
 const COLUMNS_BY_KIND = {
@@ -37,23 +27,23 @@ const COLUMNS_BY_KIND = {
   simple: ['backlog', 'in-progress', 'review', 'done'],
 }
 
-/** Колонки доски. Неизвестный вид — проектная доска, а не пустой набор. */
+/** Board columns. Unknown kind defaults to project board. */
 export function columnsOf(kind) {
   return COLUMNS_BY_KIND[kind] ?? COLUMNS_BY_KIND[DEFAULT_KIND]
 }
 
-/** Приведение вида к известному значению. */
+/** Coerce board kind to supported value. */
 export function normalizeKind(kind) {
   return BOARD_KINDS.includes(kind) ? kind : DEFAULT_KIND
 }
 
-/** Заводимые при первом запуске доски. Их ровно две, и обе нужны сразу. */
+/** Initial boards seeded on first run. */
 export const DEFAULT_BOARDS = [
   { id: 'main', title: 'Project Board', kind: 'project' },
   { id: 'simple', title: 'Simple Board', kind: 'simple' },
 ]
 
-/** Значения по умолчанию. Из них же собирается схема в `lib/index.js`. */
+/** Default settings values used in schema. */
 export const CONFIG_DEFAULTS = {
   gitProvider: 'auto',
   giteaUrl: '',
@@ -88,7 +78,7 @@ export const CONFIG_DEFAULTS = {
   autoSyncSessions: false,
 }
 
-/** Пояснения к полям; повторно используются схемой и карточкой настроек. */
+/** Field descriptions reused in schema and settings card. */
 export const CONFIG_HINTS = {
   gitProvider: 'Active Git forge: "auto" (detect by credentials), "gitea", or "github".',
   giteaUrl: 'Gitea or Forgejo instance URL, e.g. https://gitea.example.com. Empty disables import.',
@@ -123,22 +113,17 @@ export const CONFIG_HINTS = {
   autoSyncSessions: 'Automatically sync and attach live background agent sessions to cards.',
 }
 
-/** Поле настроек с пределом числа карточек; задан не у всех колонок. */
+/** Setting key for column WIP limit; not all columns have limits. */
 const WIP_FIELD = {
   'in-progress': 'wipInProgress',
   'review': 'wipReview',
 }
 
 /**
- * Фактический корень проектов: настройка либо рабочая папка харнесса.
- *
- * Единственное место, где считается «что будет, если корень не задан».
- * Браузер показывает это значение в окне запуска, чтобы сессия не
- * поднималась молча в неожиданном каталоге.
- *
- * @param {object} config эффективные настройки
- * @param {() => string} [cwdOf] рабочая папка (в тестах подменяется)
- * @returns {{path: string, set: boolean}} путь и признак «задан настройкой»
+ * Effective project root: configured value or harness working directory.
+ * @param {object} config effective configuration
+ * @param {() => string} [cwdOf] working directory getter
+ * @returns {{path: string, set: boolean}} path and whether explicitly configured
  */
 export function rootOf(config, cwdOf = () => process.cwd()) {
   const named = String(config?.defaultProjectRoot ?? '').trim()
@@ -146,11 +131,9 @@ export function rootOf(config, cwdOf = () => process.cwd()) {
 }
 
 /**
- * Наложить значения по умолчанию на сырые настройки. Поля неверного типа
- * отбрасываются в пользу умолчания: настройки приходят из файла и из
- * браузера, и одно испорченное поле не должно ронять плагин целиком.
- * @param {object} [raw] сырые значения
- * @returns {object} полный набор скалярных полей
+ * Apply defaults to raw settings. Invalid types fallback to default.
+ * @param {object} [raw] raw configuration
+ * @returns {object} validated scalar settings
  */
 export function withDefaults(raw) {
   const out = {}
@@ -162,12 +145,10 @@ export function withDefaults(raw) {
 }
 
 /**
- * Предел числа карточек в колонке. Ноль и отсутствие поля означают «без
- * предела» и одинаково дают `undefined`, чтобы вызывающему не приходилось
- * различать два способа сказать одно и то же.
- * @param {object} config эффективные настройки
- * @param {string} column идентификатор колонки
- * @returns {number|undefined} предел либо undefined
+ * Column card limit. Zero and absent setting both return undefined.
+ * @param {object} config effective configuration
+ * @param {string} column column identifier
+ * @returns {number|undefined} limit or undefined
  */
 export function wipLimitField(config, column) {
   const field = WIP_FIELD[column]
@@ -178,14 +159,8 @@ export function wipLimitField(config, column) {
 }
 
 /**
- * Свои названия колонок из настройки.
- *
- * Пары `идентификатор=Название` через запятую. Одно поле на все колонки, а не
- * шесть отдельных: переименовывают их раз в жизни, а карточку настроек шесть
- * полей засорили бы навсегда.
- *
- * Название неизвестной колонки не отбрасываем молча — она может появиться
- * позже, и тогда настройка сработает сама.
+ * Custom column labels from settings.
+ * Format: comma-separated `id=Name` pairs.
  */
 export function columnNamesOf(config) {
   const out = {}

package/lib/cron.js

@@ -1,12 +1,12 @@
-// dsh-kanban: парсер 5-позиционного cron и вычисление следующего запуска.
-// Без внешних зависимостей: чистые функции над датами и числами.
+// dsh-kanban: 5-position cron parser and next run calculator.
+// Zero dependencies: pure functions over dates and numbers.
 
 const FIELD_RANGES = [
-  [0, 59], // минуты
-  [0, 23], // часы
-  [1, 31], // дни месяца
-  [1, 12], // месяцы
-  [0, 7],  // дни недели (0 и 7 — воскресенье)
+  [0, 59], // minutes
+  [0, 23], // hours
+  [1, 31], // days of month
+  [1, 12], // months
+  [0, 7],  // days of week (0 and 7 are Sunday)
 ]
 
 function parseField(token, min, max, targetSet) {
@@ -62,9 +62,9 @@ function parseField(token, min, max, targetSet) {
 }
 
 /**
- * Разобрать 5-позиционное выражение cron: "минута час день месяц день_недели".
+ * Parse 5-position cron expression: "minute hour day month day_of_week".
  * @param {string} expr 
- * @returns {object|null} распарсенное расписание или null, если выражение невалидно
+ * @returns {object|null} parsed schedule or null if expression is invalid
  */
 export function parseCron(expr) {
   if (typeof expr !== 'string') return null
@@ -94,17 +94,17 @@ export function parseCron(expr) {
 }
 
 /**
- * Вычислить время следующего запуска (в миллисекундах epoch) строго после `fromMs`.
- * Поиск ограничен 5 годами вперед, чтобы избежать бесконечного цикла.
+ * Calculate next run timestamp (epoch ms) strictly after `fromMs`.
+ * Search capped at 5 years forward to prevent infinite loops.
  * @param {string|object} exprOrSchedule 
  * @param {number} [fromMs] 
- * @returns {number|undefined} время следующего запуска или undefined
+ * @returns {number|undefined} next run timestamp or undefined
  */
 export function computeNextRun(exprOrSchedule, fromMs = Date.now()) {
   const schedule = typeof exprOrSchedule === 'string' ? parseCron(exprOrSchedule) : exprOrSchedule
   if (!schedule) return undefined
 
-  // Стартуем со следующей целой минуты
+  // Start at next whole minute
   const current = new Date(fromMs)
   current.setSeconds(0, 0)
   current.setMinutes(current.getMinutes() + 1)

package/lib/events.js

@@ -1,4 +1,4 @@
-// Broadcaster для Server-Sent Events (SSE) (#222).
+// Broadcaster for Server-Sent Events (SSE) (#222).
 
 export class KanbanEventHub {
   constructor(options = {}) {