@goodandready/dsh-cron 0.2.3 → 0.2.5

package/docs/plans/0.2.5-ui-block.md

@@ -0,0 +1,50 @@
+# План: блок A — пользовательские поверхности (0.2.5)
+
+Живой план блока. Обновляется по факту работы; источник истины по задачам —
+Gitea (`goodandready/dsh-cron`), milestone `0.2.5`.
+
+## Состав блока (согласован владельцем)
+
+| Issue | Задача | Сложность |
+|:--|:--|:--|
+| #34 | Сворачиваемый раздел активных задач в сайдбаре | H |
+| #40 | Поиск и фильтры списка задач | M |
+| #39 | Адаптив под узкие экраны | M |
+| #41 | Клонирование задачи | L |
+| #42 | Экспорт/импорт задач (JSON/YAML) | L |
+| #115 | Поле «Delivery timeout»: сброс и нижняя граница | L |
+
+Дальше по согласованию: блок B (0.2.6) — #45, #44, #43, #49, #48;
+блок C (0.2.7) — #54, #50, #53, #97, #121.
+
+## Границы и инварианты
+
+- Один блок → одна ветка `feat/0.2.5-ui-block` → один PR → один релиз 0.2.5.
+- В релиз 0.2.5 также входит уже смёрженное удаление email-канала (#23, PR #120).
+- Клиентская половина остаётся single-file (`lib/client.js`) — требование загрузчика DSH.
+- Новых зависимостей блок не добавляет; экспорт/импорт использует существующие средства разбора.
+- Публичные экспорты `lib/index.js` и контракты маршрутов не ломаются: новые поля — только additive.
+- Секреты в экспортируемом файле отсутствуют: переносятся лишь имена credential-ссылок.
+
+## Вне scope
+
+- Серверная авторизация и внешний API (блок C).
+- Изменения в путях исполнения и работе с моделью (блок B).
+- `#117` (мажор croner), `#95` (scope токена), `#113` (инфраструктура тест-контура) — вне блоков.
+
+## План проверки блока
+
+- `npm test` + новые тесты на каждый пункт (контракт разметки, фильтрация, сериализация, клонирование, клампинг таймаута).
+- `bash deploy.sh check` — тесты, гейт размера пакета, сборка кандидата.
+- Приёмка на изолированном MiniPC: установка кандидата, проверка списка/фильтров/дублей/экспорта-импорта и геометрии на 375/768/1280 в браузере.
+- Независимое ревью PR перед merge.
+
+## Журнал
+
+- 2026-09-11 — блок согласован (A=0.2.5, B=0.2.6, C=0.2.7), созданы milestones и ТЗ по каждой задаче.
+- 2026-09-11 — реализовано: #115 (клампинг таймаута), #41 (дублирование серверным маршрутом), #42 (экспорт/импорт JSON), #40 (фильтры), #39 (адаптив), #34 (аккордеон в сайдбаре). 123/123 тестов, гейт размера 23 файла.
+- Приёмка на MiniPC (изолированный профиль, кандидат из ветки): дубликат — копия `disk-check (copy)` в статусе paused, настройки скопированы, история и счётчики пусты; экспорт — 4 задачи, поля только конфигурации (нет status/totalTokens/lastRunAt/nextRunAt); dry-run импорта — `{add:0, replace:0, skip:4}`, импорт со стратегией add — 4 задачи, все на паузе; битый документ → 400 без изменений в хранилище. В браузере: секция «Active jobs» свёрнута по умолчанию, раскрывается, показывает 3 активные задачи с временем следующего запуска, состояние сохраняется; клик по задаче открывает панель и подсвечивает её; фильтры — 8 → 6 (type=script) → 2 (+channel=ntfy) с подписью «Showing N of 8» и сбросом; дублирование из строки — 9 задач и подтверждение «copy created and paused»; поле таймаута доставки: ввод 4000 сохраняется, очистка возвращает 15000.
+- Ограничение приёмки: смена ширины окна в текущем браузерном транспорте недоступна, поэтому адаптив (#39) проверен наличием и разбором media-query-правил и тестами, а не визуально на 375 px. Это единственный пункт блока без живой визуальной проверки.
+- 2026-09-11 — после независимого ревью (FAIL): импорт переведён на жёсткий whitelist (статус из файла игнорируется, лишние ключи отбрасываются), добавлен confirm-заголовок для документов с code-задачами, зарезервированы id `export`/`import` на создании и импорте, добавлен откат при частичном сбое записи, сайдбар и панель разведены разными атрибутами, добавлен 16px для полей на телефоне, `mountSidebarJobs` разбит на мелкие функции. Проверено живьём: без заголовка 403, с заголовком задача приходит paused с обнулёнными счётчиками и отброшенными лишними ключами; подсветка из сайдбара указывает на строку панели (`.dsh-cron-container .dsh-cron-task-highlight`). 127/127 тестов.
+- 2026-09-11 — релиз: bump 0.2.4 → 0.2.5, тег v0.2.5, npm publish, GitHub Release, установка точной версии в production web-профиль MiniAI и production-проверки. Закрыты #34, #39, #40, #41, #42, #115.
+- Отклонения от первоначального ТЗ (зафиксированы в issue): #41 — сделан отдельный маршрут вместо клиентской сборки payload (сервер знает, что конфигурация, а что состояние запуска, и это тестируемо); #42 — только JSON вместо JSON/YAML (парсера YAML в проекте нет, зависимость ради формата не добавляется); состояние фильтров не пишется в URL-хеш, чтобы не конфликтовать с роутингом SPA.

package/lib/channels.js

@@ -0,0 +1,412 @@
+/**
+ * Delivery channels and router (#26, #20, #21, #22, #47, #28).
+ *
+ * Every adapter is split into a pure payload/request builder (unit-testable
+ * without network) and a thin send step using an injected fetch. The router
+ * decides which channels a run goes to and never throws: failures are
+ * collected so one broken channel cannot hide another.
+ */
+
+import { formatTaskTelegramMessage, sendTelegramMessage } from './telegram.js';
+import { createKanbanCard, shouldCreateKanbanCard } from './integrations.js';
+import { resolveTemplateText, truncateText } from './templates.js';
+
+export const CHANNEL_IDS = ['telegram', 'kanban', 'discord', 'slack', 'ntfy', 'bark', 'pushplus', 'tts', 'gitea'];
+
+export const CHANNEL_LABELS = {
+  telegram: 'Telegram',
+  kanban: 'dsh-kanban card',
+  discord: 'Discord webhook',
+  slack: 'Slack webhook',
+  ntfy: 'ntfy push',
+  bark: 'Bark push',
+  pushplus: 'PushPlus',
+  tts: 'Voice via dsh-tts',
+  gitea: 'Gitea issue',
+};
+
+const isFailed = (status) => status === 'error' || status === 'timeout';
+
+/** The message text for a channel: custom template, else built-in defaults. */
+export function messageTextFor(channelId, task, runInfo, settings = {}) {
+  const templates = (settings && settings.channelTemplates) || {};
+  const template = templates[channelId] || settings.template || '';
+  return resolveTemplateText({ template, task, runInfo });
+}
+
+/**
+ * Which channels deliver a given run.
+ * Explicit per-task channels win; otherwise the legacy flags decide.
+ */
+export function resolveChannels(task, settings = {}) {
+  if (Array.isArray(task.channels)) {
+    const explicit = task.channels.filter((id) => CHANNEL_IDS.includes(id));
+    if (explicit.length) return explicit;
+  }
+  const out = [];
+  const notify = task.notifyTelegram !== undefined ? task.notifyTelegram : settings.notifyTelegram;
+  if (notify) out.push('telegram');
+  if ((task.kanbanMode || 'none') !== 'none') out.push('kanban');
+  return out;
+}
+
+/**
+ * Channel ids a task still references that no longer exist (for example the
+ * removed `email` channel). They are filtered out of routing, so they must be
+ * reported explicitly — a silently dropped notification is worse than a
+ * visible failure.
+ */
+export function unknownChannels(task) {
+  if (!Array.isArray(task.channels)) return [];
+  return task.channels.filter((id) => !CHANNEL_IDS.includes(id));
+}
+
+/** Failure/only-on-failure filtering, per channel. */
+export function shouldSendToChannel(channelId, task, runInfo, settings = {}) {
+  if (channelId === 'kanban') return shouldCreateKanbanCard(task, runInfo);
+  const onlyOnFail = task.onlyOnFailure !== undefined
+    ? Boolean(task.onlyOnFailure)
+    : Boolean(settings.onlyOnFailure);
+  if (onlyOnFail && !isFailed(runInfo.status)) return false;
+  return true;
+}
+
+// ---------------------------------------------------------------- builders
+
+export function buildDiscordPayload({ text, task, runInfo }) {
+  const failed = isFailed(runInfo.status);
+  return {
+    content: truncateText(text, 1900),
+    embeds: [{
+      title: `${failed ? '❌' : '✅'} ${truncateText(task.title || 'Task', 200)}`,
+      description: truncateText(failed ? (runInfo.error || '') : (runInfo.output || ''), 1900) || undefined,
+      color: failed ? 0xef4444 : 0x10b981,
+      footer: { text: truncateText(task.scheduleText || task.schedule || '', 200) },
+      timestamp: new Date(runInfo.at || Date.now()).toISOString(),
+    }],
+  };
+}
+
+export function buildSlackPayload({ text }) {
+  return { text: truncateText(text, 3000) };
+}
+
+export function buildNtfyRequest({ settings = {}, text, task, token }) {
+  const base = String(settings.ntfyUrl || 'https://ntfy.sh').replace(/\/+$/, '');
+  const topic = String(settings.ntfyTopic || '').trim();
+  if (!topic) throw new Error('ntfyTopic is not configured');
+  const headers = {
+    Title: truncateText(task && task.title ? task.title : 'DSH Cron', 120),
+    Tags: isFailed(task && task.lastStatus) ? 'warning' : 'robot',
+    'Content-Type': 'text/plain; charset=utf-8',
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return { url: `${base}/${encodeURIComponent(topic)}`, method: 'POST', headers, body: truncateText(text, 4000) };
+}
+
+export function buildBarkRequest({ settings = {}, text, task }) {
+  const server = String(settings.barkServerUrl || 'https://api.day.app').replace(/\/+$/, '');
+  const key = String(settings.barkKey || '').trim();
+  if (!key) throw new Error('barkKey is not configured');
+  const title = truncateText(task && task.title ? task.title : 'DSH Cron', 100);
+  return {
+    url: `${server}/${encodeURIComponent(key)}/${encodeURIComponent(title)}/${encodeURIComponent(truncateText(text, 1200))}`,
+    method: 'GET',
+    headers: {},
+  };
+}
+
+export function buildPushplusRequest({ settings = {}, text, task, token }) {
+  const effective = token || settings.pushplusToken || '';
+  if (!effective) throw new Error('pushplus token is not configured');
+  const url = String(settings.pushplusUrl || 'https://www.pushplus.plus/send').trim();
+  return {
+    url,
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      token: effective,
+      title: truncateText(task && task.title ? task.title : 'DSH Cron', 100),
+      content: truncateText(text, 4000),
+      template: 'markdown',
+    }),
+  };
+}
+
+export function buildGiteaIssuePayload({ task, runInfo }) {
+  const failed = isFailed(runInfo.status);
+  return {
+    title: `${failed ? '[Cron failure]' : '[Cron run]'} ${truncateText(task.title || 'Task', 200)}`,
+    body: [
+      `**Cron task:** ${task.title} (\`${task.id}\`)`,
+      `**Schedule:** ${task.scheduleText || task.schedule || ''}`,
+      `**Status:** ${runInfo.status}`,
+      `**Started at:** ${new Date(runInfo.at || Date.now()).toISOString()}`,
+      runInfo.error ? `\n**Error:**\n\`\`\`\n${truncateText(runInfo.error, 1000)}\n\`\`\`` : '',
+      runInfo.output ? `\n**Output:**\n\`\`\`\n${truncateText(runInfo.output, 1000)}\n\`\`\`` : '',
+    ].filter(Boolean).join('\n\n'),
+    labels: failed ? ['cron', 'bug', 'alert'] : ['cron', 'auto'],
+  };
+}
+
+// ------------------------------------------------------------------ sender
+
+export const DEFAULT_DELIVERY_TIMEOUT_MS = 15000;
+
+/**
+ * Lower bound for a per-channel deadline (#115). A stored value of a few
+ * milliseconds would fail every delivery before the request could even be sent,
+ * which looks like "delivery is broken" rather than a misconfiguration, so the
+ * router clamps instead of trusting the setting blindly.
+ */
+export const MIN_DELIVERY_TIMEOUT_MS = 1000;
+
+/** Normalise a configured delivery timeout: finite, >= MIN, else the default. */
+export function resolveDeliveryTimeoutMs(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_DELIVERY_TIMEOUT_MS;
+  return Math.max(MIN_DELIVERY_TIMEOUT_MS, Math.round(n));
+}
+
+/**
+ * Bound every outbound request. Without this a single unresponsive endpoint
+ * blocks the remaining channels and, because the run is awaited inside the
+ * croner callback with protect enabled, silently skips subsequent ticks.
+ */
+function deliverySignal(timeoutMs) {
+  const ms = resolveDeliveryTimeoutMs(timeoutMs);
+  if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') {
+    return AbortSignal.timeout(ms);
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  if (typeof timer.unref === 'function') timer.unref();
+  return controller.signal;
+}
+
+function isAbort(err) {
+  return Boolean(err) && (err.name === 'AbortError' || err.name === 'TimeoutError');
+}
+
+/**
+ * Hard deadline around one channel's whole work. Signal-based aborts only help
+ * where the callee supports AbortSignal (fetch), while credential resolution
+ * ignores it — this is the backstop that keeps every channel bounded.
+ */
+function withDeadline(promise, timeoutMs, channelId) {
+  const ms = resolveDeliveryTimeoutMs(timeoutMs);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${channelId}: timed out after ${ms} ms`));
+    }, ms);
+    Promise.resolve(promise).then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      (err) => { clearTimeout(timer); reject(err); },
+    );
+  });
+}
+
+async function sendHttp(fetchFn, request, channelId, signal, timeoutMs) {
+  let res;
+  try {
+    res = await fetchFn(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+      signal,
+    });
+  } catch (err) {
+    if (isAbort(err)) throw new Error(`${channelId}: timed out after ${timeoutMs} ms`);
+    throw err;
+  }
+  if (!res || !res.ok) {
+    const status = res && res.status ? res.status : 'no-response';
+    throw new Error(`${channelId}: HTTP ${status}`);
+  }
+  return { status: res.status };
+}
+
+/** POST/PUT style JSON request helper used by the tts and gitea channels. */
+async function postJson(http, url, headers, body, channelId, signal, timeoutMs) {
+  let res;
+  try {
+    res = await http(url, { method: 'POST', headers, body, signal });
+  } catch (err) {
+    if (isAbort(err)) throw new Error(`${channelId}: timed out after ${timeoutMs} ms`);
+    throw err;
+  }
+  if (!res || !res.ok) throw new Error(`${channelId}: HTTP ${res && res.status ? res.status : 'no-response'}`);
+  return res.json().catch(() => ({}));
+}
+
+/**
+ * One handler per channel. Each returns a small detail object and throws a
+ * descriptive Error on failure; the router turns that into a failure entry.
+ */
+export const CHANNEL_HANDLERS = {
+  async telegram({ task, runInfo, settings, secrets, http, signal, timeoutMs }) {
+    const botToken = secrets.botToken || '';
+    const chatId = String(settings.chatId || '').trim();
+    if (!botToken || !chatId) throw new Error('telegram: botToken or chatId is not configured');
+    const text = settings.template
+      ? messageTextFor('telegram', task, runInfo, settings)
+      : formatTaskTelegramMessage(task, runInfo);
+    try {
+      await sendTelegramMessage({ botToken, chatId, text, fetchFn: http, signal });
+    } catch (err) {
+      if (isAbort(err)) throw new Error(`telegram: timed out after ${timeoutMs} ms`);
+      throw err;
+    }
+    return { chatId };
+  },
+
+  async kanban({ task, runInfo, settings, http, signal }) {
+    const isErr = isFailed(runInfo.status);
+    const result = await createKanbanCard({
+      title: `${isErr ? '[Cron failure]' : '[Cron completed]'} ${task.title}`,
+      body: buildGiteaIssuePayload({ task, runInfo }).body,
+      board: 'main',
+      column: isErr ? 'backlog' : 'done',
+      labels: isErr ? ['cron', 'bug', 'alert'] : ['cron', 'auto'],
+      kanbanBaseUrl: settings.kanbanBaseUrl || 'http://127.0.0.1:3000',
+      fetchFn: http,
+      signal,
+    });
+    if (!result.success) throw new Error(`kanban: ${result.error}`);
+    return { column: isErr ? 'backlog' : 'done' };
+  },
+
+  async discord({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const url = String(settings.discordWebhookUrl || '').trim();
+    if (!url) throw new Error('discord: discordWebhookUrl is not configured');
+    const payload = buildDiscordPayload({ text: messageTextFor('discord', task, runInfo, settings), task, runInfo });
+    return sendHttp(http, { url, method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }, 'discord', signal, timeoutMs);
+  },
+
+  async slack({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const url = String(settings.slackWebhookUrl || '').trim();
+    if (!url) throw new Error('slack: slackWebhookUrl is not configured');
+    const payload = buildSlackPayload({ text: messageTextFor('slack', task, runInfo, settings) });
+    return sendHttp(http, { url, method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }, 'slack', signal, timeoutMs);
+  },
+
+  async ntfy({ task, runInfo, settings, secrets, http, signal, timeoutMs, resolveSecret }) {
+    const token = settings.ntfyTokenRef ? await resolveSecret(settings.ntfyTokenRef) : null;
+    const req = buildNtfyRequest({ settings, text: messageTextFor('ntfy', task, runInfo, settings), task, token });
+    return sendHttp(http, req, 'ntfy', signal, timeoutMs);
+  },
+
+  async bark({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const req = buildBarkRequest({ settings, text: messageTextFor('bark', task, runInfo, settings), task });
+    return sendHttp(http, req, 'bark', signal, timeoutMs);
+  },
+
+  async pushplus({ task, runInfo, settings, secrets, http, signal, timeoutMs, resolveSecret }) {
+    const token = settings.pushplusTokenRef ? await resolveSecret(settings.pushplusTokenRef) : null;
+    const req = buildPushplusRequest({ settings, text: messageTextFor('pushplus', task, runInfo, settings), task, token });
+    return sendHttp(http, req, 'pushplus', signal, timeoutMs);
+  },
+
+  async tts({ task, runInfo, settings, http, signal, timeoutMs }) {
+    const base = String(settings.ttsBaseUrl || 'http://127.0.0.1:3080').replace(/\/+$/, '');
+    const payload = { text: truncateText(messageTextFor('tts', task, runInfo, settings), 600) };
+    const data = await postJson(http, `${base}/dsh-tts/speak`, { 'Content-Type': 'application/json' }, JSON.stringify(payload), 'tts', signal, timeoutMs);
+    return { provider: data.provider || 'dsh-tts', tookMs: data.tookMs || null };
+  },
+
+  async gitea({ task, runInfo, settings, http, signal, timeoutMs, resolveSecret }) {
+    const base = String(settings.giteaBaseUrl || '').replace(/\/+$/, '');
+    const repo = String(settings.giteaRepo || '').trim();
+    if (!base || !repo) throw new Error('gitea: giteaBaseUrl and giteaRepo are required');
+    const token = settings.giteaTokenRef ? await resolveSecret(settings.giteaTokenRef) : '';
+    if (!token) throw new Error(`gitea: credential "${settings.giteaTokenRef || ''}" did not resolve`);
+    const payload = buildGiteaIssuePayload({ task, runInfo });
+    const issue = await postJson(
+      http,
+      `${base}/api/v1/repos/${repo}/issues`,
+      { 'Content-Type': 'application/json', Authorization: `token ${token}` },
+      JSON.stringify(payload),
+      'gitea',
+      signal,
+      timeoutMs,
+    );
+    return { number: issue.number || null };
+  },
+};
+
+/**
+ * Deliver one run to one channel.
+ * `resolveSecret(ref)` resolves credential references; `fetchFn` is injectable
+ * so every channel is testable without network access.
+ */
+export async function sendToChannel({ channelId, task, runInfo, settings = {}, secrets = {}, fetchFn, timeoutMs = DEFAULT_DELIVERY_TIMEOUT_MS }) {
+  const handler = CHANNEL_HANDLERS[channelId];
+  if (!handler) throw new Error(`unknown channel: ${channelId}`);
+  const resolveSecret = typeof secrets.resolveSecret === 'function' ? secrets.resolveSecret : async () => null;
+  const http = fetchFn || globalThis.fetch;
+  const effectiveTimeout = resolveDeliveryTimeoutMs(timeoutMs);
+  const work = handler({
+    task,
+    runInfo,
+    settings,
+    secrets,
+    http,
+    resolveSecret,
+    signal: deliverySignal(effectiveTimeout),
+    timeoutMs: effectiveTimeout,
+  });
+  return withDeadline(work, effectiveTimeout, channelId);
+}
+
+/**
+ * Deliver a finished run to every applicable channel.
+ *
+ * Channels are dispatched concurrently and every channel is individually
+ * bounded (AbortSignal for fetch-based channels plus a hard deadline around the
+ * whole handler), so a slow endpoint cannot delay the rest of the report nor
+ * hold the cron callback open. Never throws: per-channel failures are returned
+ * in `failures`.
+ */
+export async function deliverRun({ task, runInfo, settings = {}, secrets = {}, fetchFn }) {
+  const timeoutMs = resolveDeliveryTimeoutMs(settings.deliveryTimeoutMs);
+
+  let channels = [];
+  try {
+    channels = resolveChannels(task, settings);
+  } catch (err) {
+    return { channels: [], delivered: [], skipped: [], failures: [{ channel: 'router', error: (err && err.message) || String(err) }] };
+  }
+
+  const outcomes = await Promise.all(channels.map(async (channelId) => {
+    try {
+      if (!shouldSendToChannel(channelId, task, runInfo, settings)) {
+        return { channel: channelId, skipped: true };
+      }
+      const detail = await sendToChannel({ channelId, task, runInfo, settings, secrets, fetchFn, timeoutMs });
+      return { channel: channelId, detail: detail || null };
+    } catch (err) {
+      return { channel: channelId, error: (err && err.message) || String(err) };
+    }
+  }));
+
+  const delivered = [];
+  const skipped = [];
+  const failures = [];
+  // Report ids that no longer exist before the per-channel results, so a task
+  // still carrying a removed channel fails loudly instead of silently.
+  let removed = [];
+  try {
+    removed = unknownChannels(task);
+  } catch {
+    removed = [];
+  }
+  for (const channelId of removed) {
+    failures.push({ channel: channelId, error: `unknown channel: ${channelId}` });
+  }
+  for (const outcome of outcomes) {
+    if (outcome.skipped) skipped.push(outcome.channel);
+    else if (outcome.error) failures.push({ channel: outcome.channel, error: outcome.error });
+    else delivered.push({ channel: outcome.channel, detail: outcome.detail });
+  }
+  return { channels, delivered, skipped, failures };
+}