@goodandready/dsh-kanban 0.1.14

package/lib/gitea.js

@@ -0,0 +1,309 @@
+// Клиент Gitea для доски.
+//
+// Своего клиента канбан держит намеренно: токен всё равно живёт в службе
+// учётных данных ядра, а не в соседнем плагине, и шесть вызовов REST дешевле,
+// чем зависимость от чужого выпуска.
+//
+// Сеть приходит параметром (`fetchImpl`), токен — функцией разрешения.
+// Поэтому клиент проверяется без единого реального запроса.
+//
+// Токен в настройках не хранится: там только ИМЯ учётной записи. Наружу
+// значение не отдаётся никогда, включая сообщения об ошибках.
+
+/** Убрать хвостовые слэши: адрес приходит из поля, куда человек пишет как хочет. */
+export function normalizeBaseUrl(url) {
+  return String(url || '').trim().replace(/\/+$/, '')
+}
+
+/**
+ * Сегмент пути, пригодный для подстановки в URL.
+ *
+ * `owner`, `repo` и номер приходят из данных Gitea и из браузера, а не из
+ * кода. Без проверки сюда подставится `..` или слэш, и запрос уйдёт не туда,
+ * куда собирались.
+ *
+ * @returns {string|undefined} закодированный сегмент либо undefined
+ */
+export function safeSegment(value) {
+  const s = String(value ?? '').trim()
+  if (s === '' || s === '.' || s === '..') return undefined
+  if (!/^[A-Za-z0-9._-]+$/.test(s)) return undefined
+  return encodeURIComponent(s)
+}
+
+/** Имя учётной записи — имя переменной окружения, а не сам секрет. */
+export function isCredentialName(value) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(String(value || ''))
+}
+
+/** Похоже на сам токен, а не на его имя. */
+export function looksLikeSecret(value) {
+  return /^[A-Za-z0-9_-]{32,}$/.test(String(value || '').trim())
+}
+
+/**
+ * Упорядочить репозитории по актуальности.
+ *
+ * Сверху те, где работа идёт прямо сейчас. Признак «идёт» выбран самый честный
+ * из доступных без лишних запросов: есть открытые задачи И репозиторий недавно
+ * трогали. Архивные уходят вниз всегда — там работы не ведут по определению.
+ *
+ * Точного «ведётся прямо сейчас» инстанс не знает, и выдумывать его не из чего;
+ * это приближение, а не истина.
+ */
+export function rankRepos(repos) {
+  const rank = (r) => {
+    if (r.archived) return 3
+    if ((r.openIssues ?? 0) > 0) return 0
+    return 1
+  }
+  return [...(repos ?? [])].sort((a, b) => {
+    const byRank = rank(a) - rank(b)
+    if (byRank !== 0) return byRank
+    const byTime = String(b.updatedAt || '').localeCompare(String(a.updatedAt || ''))
+    if (byTime !== 0) return byTime
+    return String(a.fullName || '').localeCompare(String(b.fullName || ''))
+  })
+}
+
+/**
+ * Клиент Gitea.
+ *
+ * @param {object} options
+ * @param {() => object} options.getConfig текущие настройки плагина
+ * @param {(name: string) => Promise<string>} options.resolveToken разрешение учётной записи
+ * @param {Function} [options.fetchImpl] реализация fetch
+ * @param {number} [options.timeoutMs]
+ */
+export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch, timeoutMs = 30_000 }) {
+  async function request(method, path, body) {
+    const config = getConfig()
+    const baseUrl = normalizeBaseUrl(config?.giteaUrl)
+    if (baseUrl === '') throw Object.assign(new Error('адрес Gitea не задан'), { code: 'unconfigured' })
+
+    const token = await resolveToken(config?.giteaTokenRef)
+    if (!token) throw Object.assign(new Error('учётная запись с токеном не настроена'), { code: 'unconfigured' })
+
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      const res = await fetchImpl(`${baseUrl}/api/v1${path}`, {
+        method,
+        headers: {
+          // Заголовком, а не basic-авторизацией: на внутренних сетях basic
+          // отдаёт «Missing API key».
+          'Authorization': `token ${token}`,
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      })
+      const text = await res.text()
+      let payload
+      try { payload = text.trim() === '' ? null : JSON.parse(text) } catch { payload = null }
+      if (!res.ok) {
+        // Тело ответа наружу не выносим: в нём может быть эхо заголовков.
+        throw Object.assign(new Error(`Gitea ответил ${res.status}`), { code: 'http', status: res.status })
+      }
+      return payload
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  function repoPath(owner, repo, suffix = '') {
+    const o = safeSegment(owner)
+    const r = safeSegment(repo)
+    if (o === undefined || r === undefined) {
+      throw Object.assign(new Error('недопустимый владелец или репозиторий'), { code: 'bad-segment' })
+    }
+    return `/repos/${o}/${r}${suffix}`
+  }
+
+  /**
+   * Собрать голый массив со всех страниц.
+   *
+   * Gitea отдаёт списки порциями, и запрос без перелистывания молча теряет
+   * хвост. Признак конца — неполная страница: инстанс отдал меньше, чем
+   * просили, значит дальше пусто. Верхний предел стоит, чтобы очень большой
+   * ответ не превратил сверку в бесконечный поход.
+   *
+   * @param {object} options
+   * @param {(page: number, size: number) => string} options.buildPath путь страницы
+   * @param {number} [options.limit] размер страницы
+   * @param {number} [options.maxPages] верхний предел страниц
+   * @returns {Promise<Array>} все строки со всех прочитанных страниц
+   */
+  async function collectPages({ buildPath, limit, maxPages = 10 }) {
+    const size = Math.min(Math.max(Number(limit) || 50, 1), 50)
+    const out = []
+    for (let page = 1; page <= maxPages; page += 1) {
+      const rows = await request('GET', buildPath(page, size))
+      if (!Array.isArray(rows)) break
+      out.push(...rows)
+      if (rows.length < size) break
+    }
+    return out
+  }
+
+  // Признак «настроено» кэшируется по ключу настроек. `isConfigured` стоит в
+  // горячем пути — его спрашивают на каждый запрос списка issue и поиска
+  // репозиториев, — а резолв токена это поход в хранилище учётных данных.
+  // Пока адрес и имя учётной записи не менялись, ответ не мог измениться.
+  let configuredCache
+  const configuredKey = () => {
+    const config = getConfig()
+    return `${normalizeBaseUrl(config?.giteaUrl)}\u0000${String(config?.giteaTokenRef ?? '')}`
+  }
+
+  return {
+    /** Настроен ли доступ. Значение токена наружу не отдаётся. */
+    async isConfigured() {
+      const key = configuredKey()
+      if (configuredCache?.key === key) return configuredCache.value
+      const config = getConfig()
+      const value = normalizeBaseUrl(config?.giteaUrl) !== ''
+        && isCredentialName(config?.giteaTokenRef)
+        && await resolveToken(config.giteaTokenRef).then(Boolean).catch(() => false)
+      configuredCache = { key, value }
+      return value
+    },
+
+    async listIssues({ owner, repo, state = 'open', limit = 50 }) {
+      // API отдаёт issue и pull request одним списком; доске нужны только issue.
+      // Перелистываем до конца: при 50+ открытых issue хвост иначе теряется
+      // молча, и подхват задач смотрит на неполную картину.
+      const rows = await collectPages({
+        limit,
+        buildPath: (page, size) => repoPath(owner, repo,
+          `/issues?state=${encodeURIComponent(state)}&page=${page}&limit=${size}&sort=updated&direction=desc`),
+      })
+      return rows.filter((r) => !r.pull_request)
+    },
+
+    async getIssue({ owner, repo, index }) {
+      const n = safeSegment(index)
+      if (n === undefined) throw Object.assign(new Error('недопустимый номер issue'), { code: 'bad-segment' })
+      return request('GET', repoPath(owner, repo, `/issues/${n}`))
+    },
+
+    async comment({ owner, repo, index, body }) {
+      const n = safeSegment(index)
+      if (n === undefined) throw Object.assign(new Error('недопустимый номер issue'), { code: 'bad-segment' })
+      return request('POST', repoPath(owner, repo, `/issues/${n}/comments`), { body })
+    },
+
+    /** Завести issue. Метки не ставим: доска чужой разметкой не распоряжается. */
+    async createIssue({ owner, repo, title, body }) {
+      const name = String(title ?? '').trim()
+      if (name === '') throw Object.assign(new Error('пустой заголовок'), { code: 'bad-title' })
+      return request('POST', repoPath(owner, repo, '/issues'), { title: name, body: String(body ?? '') })
+    },
+
+    /**
+     * Завести репозиторий в организации.
+     *
+     * Приватный и пустой — так решил владелец: расширить права потом дешевле,
+     * чем убирать лишнее из публичного, а пустой репозиторий честнее чужих
+     * заготовок.
+     */
+    async createRepo({ owner, name, description = '' }) {
+      const safe = safeSegment(name)
+      if (safe === undefined) throw Object.assign(new Error('недопустимое имя'), { code: 'bad-segment' })
+      return request('POST', `/orgs/${safeSegment(owner)}/repos`, {
+        name: safe, description, private: true, auto_init: false,
+      })
+    },
+
+    async closeIssue({ owner, repo, index }) {
+      const n = safeSegment(index)
+      if (n === undefined) throw Object.assign(new Error('недопустимый номер issue'), { code: 'bad-segment' })
+      return request('PATCH', repoPath(owner, repo, `/issues/${n}`), { state: 'closed' })
+    },
+
+    /** Организации, доступные токену. Нужны, чтобы не спрашивать владельца лишний раз. */
+    async listOrgs() {
+      const rows = await request('GET', '/user/orgs?limit=50')
+      return (Array.isArray(rows) ? rows : [])
+        .map((o) => String(o?.username ?? o?.name ?? ''))
+        .filter((name) => name !== '')
+    },
+
+    /**
+     * Репозитории организации с числом открытых задач.
+     *
+     * Число приходит в том же ответе, и по нему отсеиваются пустые: ходить за
+     * задачами в репозиторий, где их нет, — полсотни запросов впустую каждые
+     * две минуты. Перелистываем: при 100+ репозиториях одна страница теряла бы
+     * хвост, и доска смотрела бы на неполную организацию.
+     */
+    async listOrgRepos({ owner, limit = 100 }) {
+      const rows = await collectPages({
+        limit,
+        buildPath: (page, size) => `/orgs/${safeSegment(owner)}/repos?page=${page}&limit=${size}`,
+      })
+      return rows.map((r) => ({
+        name: String(r?.name ?? ''),
+        openIssues: Number(r?.open_issues_count ?? 0),
+        archived: r?.archived === true,
+      })).filter((r) => r.name !== '')
+    },
+
+    /** Pull request-ы репозитория. */
+    async listPulls({ owner, repo, state = 'all', limit = 50 }) {
+      return collectPages({
+        limit,
+        buildPath: (page, size) => repoPath(owner, repo,
+          `/pulls?state=${encodeURIComponent(state)}&page=${page}&limit=${size}&sort=recentupdate`),
+      })
+    },
+
+    /**
+     * Ветки репозитория: по ним видно, начата ли работа и сделан ли cleanup.
+     *
+     * Ветки перелистываются не ради полноты списка, а ради правды наблюдения:
+     * `branchOfTask` не найдёт ветку задачи на усечённой странице и сочтёт её
+     * отсутствующей — карточка уедет не туда на пустом месте.
+     */
+    async listBranches({ owner, repo, limit = 100 }) {
+      const rows = await collectPages({
+        limit,
+        buildPath: (page, size) => repoPath(owner, repo, `/branches?page=${page}&limit=${size}`),
+      })
+      return rows.map((b) => ({ name: b?.name ?? '' })).filter((b) => b.name !== '')
+    },
+
+    /**
+     * Репозитории инстанса, все страницы.
+     *
+     * Одной страницы не хватает: Gitea отдаёт их порциями, и запрос без
+     * перелистывания молча теряет хвост. Верхний предел стоит, чтобы очень
+     * большой инстанс не превратил открытие диалога в долгую загрузку.
+     *
+     * Число открытых задач и время правки приходят в том же ответе — считать
+     * их отдельными запросами не нужно.
+     */
+    async searchRepos({ query, limit = 50, maxPages = 10 }) {
+      const q = encodeURIComponent(String(query || ''))
+      const size = Math.min(Math.max(Number(limit) || 50, 1), 50)
+      const out = []
+      for (let page = 1; page <= maxPages; page += 1) {
+        const rows = await request('GET', `/repos/search?q=${q}&limit=${size}&page=${page}`)
+        const data = Array.isArray(rows?.data) ? rows.data : []
+        for (const r of data) {
+          out.push({
+            owner: r.owner?.login ?? '',
+            repo: r.name ?? '',
+            fullName: r.full_name ?? '',
+            openIssues: typeof r.open_issues_count === 'number' ? r.open_issues_count : 0,
+            updatedAt: typeof r.updated_at === 'string' ? r.updated_at : '',
+            archived: r.archived === true,
+          })
+        }
+        if (data.length < size) break
+      }
+      return rankRepos(out)
+    },
+  }
+}

package/lib/import.js

@@ -0,0 +1,214 @@
+// Перенос issue Gitea в задачу доски.
+//
+// Синхронизация в 0.1 односторонняя: Gitea → канбан, в момент импорта и по
+// кнопке обновления. Двусторонняя синхронизация — отдельный выпуск, и тянуть
+// её сюда нельзя.
+//
+// Клиент Gitea приходит параметром — его собирает `lib/gitea.js`. Здесь только
+// перенос полей и решение, что делать, когда доступ не настроен.
+
+import { safeSegment } from './gitea.js'
+import { colorsOfIssue } from './filters.js'
+
+/**
+ * Когда issue завели в Gitea.
+ *
+ * Без этого карточка показывала бы дату подхвата: задача годичной давности
+ * выглядела бы заведённой сегодня, и по дате нельзя было бы понять ничего.
+ */
+export function issueBornAt(issue) {
+  const at = Date.parse(issue?.created_at ?? '')
+  return Number.isFinite(at) && at > 0 ? at : undefined
+}
+
+/**
+ * Кто завёл issue.
+ *
+ * Берём `login`: он же стоит в Gitea под задачей и по нему её ищут. Полное
+ * имя заполнено не у всех, и подставлять его вместо логина значило бы
+ * показывать то одно, то другое.
+ */
+export function issueAuthor(issue) {
+  const login = issue?.user?.login
+  return typeof login === 'string' ? login : ''
+}
+
+/**
+ * Поля задачи из issue.
+ *
+ * `owner` и `repo` берутся из запроса, а не из issue: API Gitea возвращает их
+ * не во всех формах ответа, и полагаться на это нельзя.
+ *
+ * Поля `branch`, `worktree`, `sessionId`, `model` НЕ заполняются: они
+ * наблюдаются позже, когда работа начнётся. Плагин ветки не создаёт.
+ */
+export function issueToTask(issue, { board = 'main', column = 'backlog', owner, repo }) {
+  return {
+    board,
+    column,
+    title: typeof issue?.title === 'string' ? issue.title : '',
+    body: typeof issue?.body === 'string' ? issue.body : '',
+    labels: Array.isArray(issue?.labels)
+      ? issue.labels.map((l) => (typeof l === 'string' ? l : l?.name)).filter((n) => typeof n === 'string')
+      : [],
+    // Цвета едут рядом с именами, а не вместо них: имена читают отборы,
+    // сверка, чип и поиск.
+    labelColors: colorsOfIssue(issue?.labels),
+    owner,
+    repo,
+    issueNumber: typeof issue?.number === 'number' ? issue.number : undefined,
+    issueUrl: typeof issue?.html_url === 'string' ? issue.html_url : undefined,
+    createdAt: issueBornAt(issue),
+    author: issueAuthor(issue),
+  }
+}
+
+/**
+ * Пометить issue, которые уже лежат на доске.
+ *
+ * Сравнение идёт по тройке владелец–репозиторий–номер. Сравнение по одному
+ * номеру пометило бы задачу №1 из чужого репозитория как уже импортированную.
+ *
+ * Помеченные не прячутся, а приглушаются: задачу иногда заводят второй раз
+ * осознанно.
+ */
+export function markImported(issues, existing, { owner, repo }) {
+  const seen = new Set(
+    (existing ?? [])
+      .filter((t) => t.owner === owner && t.repo === repo && typeof t.issueNumber === 'number')
+      .map((t) => t.issueNumber),
+  )
+  return (issues ?? []).map((issue) => ({ ...issue, imported: seen.has(issue?.number) }))
+}
+
+/**
+ * Что переписать в задаче при обновлении из issue.
+ *
+ * Переписываются только поля, пришедшие из Gitea. Локальные — колонка,
+ * позиция, сессия, модель — не трогаются: иначе обновление сбрасывало бы
+ * работу, которая уже идёт.
+ */
+export function refreshPatch(task, issue) {
+  const patch = {}
+  if (typeof issue?.title === 'string') patch.title = issue.title
+  if (typeof issue?.body === 'string') patch.body = issue.body
+  if (Array.isArray(issue?.labels)) {
+    patch.labels = issue.labels
+      .map((l) => (typeof l === 'string' ? l : l?.name))
+      .filter((n) => typeof n === 'string')
+    patch.labelColors = colorsOfIssue(issue.labels)
+  }
+  if (typeof issue?.html_url === 'string') patch.issueUrl = issue.html_url
+  const born = issueBornAt(issue)
+  if (born !== undefined) patch.createdAt = born
+  const author = issueAuthor(issue)
+  if (author !== '') patch.author = author
+  return patch
+}
+
+/**
+ * Клиент Gitea готов к работе. Отсутствие клиента и ненастроенный доступ —
+ * разные беды, и человеку они говорят разное.
+ *
+ * Проверка асинхронная, потому что готовность включает разрешение учётной
+ * записи с токеном, а это обращение к службе учётных данных.
+ */
+export async function giteaState(gitea) {
+  if (gitea === undefined || gitea === null) return 'absent'
+  if (typeof gitea.isConfigured !== 'function') return 'ready'
+  try {
+    return (await gitea.isConfigured()) === true ? 'ready' : 'unconfigured'
+  } catch {
+    return 'unconfigured'
+  }
+}
+
+/**
+ * Список issue для диалога импорта: открытые, уже импортированные помечены.
+ */
+export async function listImportable({ gitea, store, owner, repo, board = 'main' }) {
+  const state = await giteaState(gitea)
+  if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
+  const issues = await gitea.listIssues({ owner, repo, state: 'open' })
+  const existing = store.listTasks({ board })
+  return { issues: markImported(issues, existing, { owner, repo }) }
+}
+
+/** Завести задачу из issue. */
+export async function importIssue({ gitea, store, owner, repo, issueNumber, board = 'main', column = 'backlog' }) {
+  const state = await giteaState(gitea)
+  if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
+  if (typeof issueNumber !== 'number') return { error: 'issue-number-required', status: 400 }
+  // Простая доска — для задач без issue. Импорт на неё привёл бы задачу с
+  // веткой и PR в набор колонок, где их некуда показать.
+  if (store.boardKind(board) !== 'project') return { error: 'board-not-for-issues', status: 400 }
+  const issue = await gitea.getIssue({ owner, repo, index: issueNumber })
+  if (issue === undefined || issue === null) return { error: 'issue-not-found', status: 404 }
+  return { task: store.createTask(issueToTask(issue, { board, column, owner, repo })) }
+}
+
+/** Перечитать issue и обновить задачу, не трогая локальные поля. */
+export async function refreshTask({ gitea, store, id }) {
+  const state = await giteaState(gitea)
+  if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
+  const task = store.getTask(id)
+  if (task === undefined) return { error: 'task-not-found', status: 404 }
+  if (typeof task.issueNumber !== 'number') return { error: 'task-has-no-issue', status: 400 }
+  const issue = await gitea.getIssue({ owner: task.owner, repo: task.repo, index: task.issueNumber })
+  if (issue === undefined || issue === null) return { error: 'issue-not-found', status: 404 }
+  return { task: store.updateTask(id, refreshPatch(task, issue)) }
+}
+
+/** Поиск репозиториев для диалога импорта. */
+export async function searchRepos({ gitea, query, limit = 20 }) {
+  const state = await giteaState(gitea)
+  if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
+  return { repos: await gitea.searchRepos({ query, limit }) }
+}
+
+/**
+ * Завести проектную задачу: issue в Gitea плюс карточка, привязанная к нему.
+ *
+ * Репозиторий либо выбирается из существующих, либо заводится по имени.
+ * Заводит его ЧЕЛОВЕК кнопкой: инструмента у агента для этого нет — он
+ * пользуется `gitea_issue_create` из соседнего плагина, а карточка приезжает
+ * подхватом.
+ *
+ * Порядок неслучаен: сперва репозиторий, потом issue, потом карточка. Обрыв на
+ * середине не должен оставить карточку привязанной к репозиторию без issue —
+ * лучше не завести карточку вовсе и сказать об этом, чем завести полупустую.
+ */
+export async function createProjectTask({
+  gitea, store, owner, repo, newRepo, title, body, board = 'main',
+}) {
+  const state = await giteaState(gitea)
+  if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
+
+  const name = typeof title === 'string' ? title.trim() : ''
+  if (name === '') return { error: 'title-required', status: 400 }
+
+  let targetRepo = typeof repo === 'string' ? repo.trim() : ''
+  if (targetRepo === '') {
+    const wanted = typeof newRepo === 'string' ? newRepo.trim() : ''
+    if (wanted === '') return { error: 'repo-required', status: 400 }
+    // Имя проверяем ДО запроса: отказ Gitea пришёл бы позже и невнятнее.
+    if (safeSegment(wanted) === undefined) return { error: 'bad-repo-name', status: 400 }
+    try {
+      await gitea.createRepo({ owner, name: wanted })
+    } catch (error) {
+      return { error: 'repo-not-created', status: 502, detail: String(error?.message ?? error) }
+    }
+    targetRepo = wanted
+  }
+
+  let issue
+  try {
+    issue = await gitea.createIssue({ owner, repo: targetRepo, title: name, body })
+  } catch (error) {
+    // Репозиторий, возможно, уже создан. Не удаляем его: удаление чужого
+    // добра из-за своей неудачи хуже лишнего пустого репозитория.
+    return { error: 'issue-not-created', status: 502, detail: String(error?.message ?? error) }
+  }
+
+  return { task: store.createTask(issueToTask(issue, { board, column: 'backlog', owner, repo: targetRepo })) }
+}