@goodandready/dsh-cron 0.2.5 → 0.2.7

package/lib/llm-ask.js

@@ -0,0 +1,141 @@
+/**
+ * Small helper for asking the configured model a short question (#44, #43).
+ *
+ * The harness exposes the model through `ctx.llm.stream(...)`, which yields
+ * text deltas and a finish chunk. That is enough for a cheap side question such
+ * as "is this output worth alerting about?".
+ *
+ * Everything here fails open: any problem returns `{ ok: false }` and the caller
+ * falls back to its normal behaviour, so a broken model call can never silence a
+ * report or lose a diagnosis.
+ */
+
+const DEFAULT_TIMEOUT_MS = 20000;
+const DEFAULT_MAX_TOKENS = 400;
+
+function getLlm(ctx) {
+  if (!ctx) return null;
+  if (ctx.llm && typeof ctx.llm.stream === 'function') return ctx.llm;
+  if (typeof ctx.get === 'function') {
+    const service = ctx.get('llm');
+    if (service && typeof service.stream === 'function') return service;
+  }
+  return null;
+}
+
+/** Provider and model for an auxiliary question: task first, then the default. */
+export function resolveAskTarget(ctx, task = {}, preferredModel = '') {
+  let defaultSelection = null;
+  try {
+    defaultSelection = ctx && typeof ctx.get === 'function'
+      ? ctx.get('agentDefaultModel')?.currentSelection?.() || null
+      : null;
+  } catch {}
+  return {
+    provider: task.provider || defaultSelection?.provider || '',
+    model: preferredModel || task.model || defaultSelection?.model || '',
+  };
+}
+
+/** Collect the assistant text and how the stream ended. */
+async function collectText(stream) {
+  let text = '';
+  let finishKind = '';
+  for await (const chunk of stream) {
+    if (!chunk) continue;
+    if (chunk.type === 'text-delta' && chunk.text) text += chunk.text;
+    if (chunk.type === 'finish') {
+      finishKind = (chunk.reason && chunk.reason.kind) || '';
+      break;
+    }
+  }
+  return { text, finishKind };
+}
+
+/** A stream that stopped for any other reason is not a usable answer. */
+function isCleanFinish(kind) {
+  return kind === 'stop';
+}
+
+async function buildUserMessage(text) {
+  const content = [{ type: 'text', text }];
+  const source = { kind: 'plugin', plugin: 'dsh-cron', form: 'helper-call' };
+  try {
+    const mod = await import('@deepseek-ai/dsh-llm');
+    if (mod && typeof mod.createUserMessage === 'function') {
+      return mod.createUserMessage({ content, source });
+    }
+  } catch {}
+  return { role: 'user', content, source };
+}
+
+/**
+ * Ask the model one question and return its text.
+ * @returns {Promise<{ok: true, text: string} | {ok: false, error: string}>}
+ */
+export async function askModel(ctx, options = {}) {
+  const { provider, model, prompt, system, maxTokens, timeoutMs, purpose } = options;
+  const llm = getLlm(ctx);
+  if (!llm) return { ok: false, error: 'the harness exposes no model stream' };
+  if (!provider || !model) return { ok: false, error: 'no provider/model is configured for this call' };
+  if (!prompt) return { ok: false, error: 'no prompt given' };
+
+  const limit = Number(timeoutMs) > 0 ? Number(timeoutMs) : DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  let timer;
+  // The abort signal only helps a stream that honours it, so the whole call is
+  // raced against the same deadline: a model helper must never hold a run open.
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`the model call did not finish within ${limit} ms`));
+    }, limit);
+  });
+
+  try {
+    const work = (async () => {
+      const messages = [await buildUserMessage(prompt)];
+      const stream = llm.stream({
+        provider,
+        model,
+        messages,
+        ...(system ? { system } : {}),
+        maxTokens: Number(maxTokens) > 0 ? Number(maxTokens) : DEFAULT_MAX_TOKENS,
+        signal: controller.signal,
+        ...(purpose ? { purpose } : {}),
+      });
+      const { text, finishKind } = await collectText(stream);
+      return { text: String(text || '').trim(), finishKind };
+    })();
+    // The abandoned stream must not surface as an unhandled rejection.
+    work.catch(() => {});
+
+    const { text, finishKind } = await Promise.race([work, deadline]);
+    if (!isCleanFinish(finishKind)) {
+      return { ok: false, error: `the model call ended with ${finishKind || 'no finish reason'}` };
+    }
+    return { ok: true, text };
+  } catch (err) {
+    return { ok: false, error: (err && err.message) || String(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Read the first JSON object out of a model answer.
+ * Models like to wrap JSON in prose or fences, so the text is searched rather
+ * than parsed directly. Returns null when nothing usable is found.
+ */
+export function parseJsonAnswer(text) {
+  const raw = String(text || '');
+  const start = raw.indexOf('{');
+  const end = raw.lastIndexOf('}');
+  if (start === -1 || end <= start) return null;
+  try {
+    const parsed = JSON.parse(raw.slice(start, end + 1));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/lib/metrics.js

@@ -0,0 +1,97 @@
+/**
+ * Prometheus exposition of the scheduler (#53).
+ *
+ * The renderer is hand-rolled on purpose: the profile has no prom-client and
+ * adding a production dependency for a handful of counters is not justified.
+ * Only counts, statuses and durations are exported — never prompts, run output
+ * or task configuration, so the endpoint can be scraped without leaking work
+ * content.
+ */
+
+export const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+
+/** Run statuses the scheduler can finish with. */
+export const RUN_STATUSES = ['success', 'error', 'timeout', 'skipped', 'missed'];
+
+const NL = String.fromCharCode(10);
+const BACKSLASH = String.fromCharCode(92);
+const QUOTE = String.fromCharCode(34);
+
+/** Escape a label value for the Prometheus text format. */
+export function escapeLabel(value) {
+  return String(value)
+    .split(BACKSLASH).join(BACKSLASH + BACKSLASH)
+    .split(QUOTE).join(BACKSLASH + QUOTE)
+    .split(NL).join(BACKSLASH + 'n');
+}
+
+function sample(name, labels, value) {
+  const rendered = Object.keys(labels)
+    .map((key) => key + '=' + QUOTE + escapeLabel(labels[key]) + QUOTE)
+    .join(',');
+  return name + (rendered ? '{' + rendered + '}' : '') + ' ' + value;
+}
+
+/**
+ * Render the current scheduler state as Prometheus text exposition.
+ * Pure function over plain data so it is testable without a store.
+ */
+export function renderMetrics({ tasks = [], stats = {}, runCounters = {} } = {}) {
+  const lines = [];
+  const byStatus = {};
+  for (const task of tasks) {
+    const status = task.status || 'unknown';
+    byStatus[status] = (byStatus[status] || 0) + 1;
+  }
+
+  lines.push('# HELP dsh_cron_tasks_total Scheduled tasks by status.');
+  // A gauge despite the name: this is a snapshot of how many tasks are in each
+  // state, not a monotonically growing total.
+  lines.push('# TYPE dsh_cron_tasks_total gauge');
+  for (const status of Object.keys(byStatus).sort()) {
+    lines.push(sample('dsh_cron_tasks_total', { status }, byStatus[status]));
+  }
+
+  lines.push('# HELP dsh_cron_task_last_duration_seconds Duration of the last finished run of a task.');
+  lines.push('# TYPE dsh_cron_task_last_duration_seconds gauge');
+  for (const task of tasks) {
+    // lastRunAt marks a finished run: a task that never ran still carries
+    // lastDurationMs = 0, and exporting that would show instant runs in
+    // monitoring.
+    if (!Number.isFinite(task.lastDurationMs) || !task.lastRunAt) continue;
+    lines.push(sample('dsh_cron_task_last_duration_seconds', { task: task.id }, task.lastDurationMs / 1000));
+  }
+
+  lines.push('# HELP dsh_cron_runs_total Finished runs since the plugin started, by status.');
+  lines.push('# TYPE dsh_cron_runs_total counter');
+  for (const status of RUN_STATUSES) {
+    lines.push(sample('dsh_cron_runs_total', { status }, Number(runCounters[status]) || 0));
+  }
+
+  lines.push('# HELP dsh_cron_run_records Run records currently kept in memory.');
+  lines.push('# TYPE dsh_cron_run_records gauge');
+  lines.push('dsh_cron_run_records ' + (Number(stats.totalRuns) || 0));
+
+  return lines.join(NL) + NL;
+}
+
+/**
+ * GET /dsh-cron/metrics — read-only. A scraper is a plain local client, so no
+ * cross-origin check applies, and nothing sensitive is exposed.
+ */
+export function createMetricsHandler({ store, scheduler }) {
+  return function handleMetrics(req, res) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('Method not allowed' + NL);
+      return;
+    }
+    const body = renderMetrics({
+      tasks: store.list({ status: 'all' }),
+      stats: store.getAggregatedStats(),
+      runCounters: typeof scheduler.getRunCounters === 'function' ? scheduler.getRunCounters() : {},
+    });
+    res.writeHead(200, { 'Content-Type': METRICS_CONTENT_TYPE, 'Cache-Control': 'no-store' });
+    res.end(req.method === 'HEAD' ? undefined : body);
+  };
+}

package/lib/recipes.js

@@ -0,0 +1,238 @@
+/**
+ * Built-in recipe hub (#48): preconfigured monitoring jobs a user can create in
+ * one click instead of hand-writing shell commands.
+ *
+ * Two rules shape every entry:
+ *   - read-only. No recipe deletes, prunes, restarts or installs anything; the
+ *     worst a bad match can do is print output. Destructive maintenance stays a
+ *     deliberate, hand-written task.
+ *   - no secrets and no private endpoints. Everything here is a public command
+ *     or a self-contained check.
+ *
+ * Recipes are ordinary task presets: the UI opens the normal form with the
+ * fields prefilled, so nothing is created without an explicit action.
+ */
+
+export const RECIPE_CATEGORIES = [
+  { id: 'system', title: 'System health' },
+  { id: 'services', title: 'Services and containers' },
+  { id: 'storage', title: 'Storage' },
+  { id: 'security', title: 'Security' },
+  { id: 'maintenance', title: 'Maintenance windows' },
+];
+
+/** Commands a recipe must never contain, checked by the test suite. */
+/**
+ * Commands a recipe must never contain, checked by the test suite.
+ *
+ * Deliberately broad: this is a gate for the curated catalog, not a sandbox, so
+ * a false positive costs one recipe while a false negative ships a recipe that
+ * destroys something. An independent review of this block defeated the first
+ * version with `find -delete`, `shred`, `mv` and `apt purge`, so the list now
+ * covers deletion and wiping, raw device writes, service and container state,
+ * packages, users and permissions, scheduling and the network edge, power state
+ * and writes outside the working tree.
+ */
+export const DESTRUCTIVE_PATTERNS = [
+  /\brm\b/i,
+  /\bunlink\b/i,
+  /\bshred\b/i,
+  /\bwipefs\b/i,
+  /\bmkfs\b/i,
+  /\btruncate\b/i,
+  /\bfind\b[^|;]*\s-delete\b/i,
+  /\bmv\s+[^|;]*\/etc\//i,
+  /\bdd\b/i,
+  /\bof=\/dev\//i,
+  /\bsystemctl\s+(stop|restart|disable|mask|kill)\b/i,
+  /\bkill(all)?\b/i,
+  /\bdocker\s+(?:[a-z-]+\s+)*(rm|rmi|prune|stop|kill|down)\b/i,
+  /\bdocker\s+volume\s+rm\b/i,
+  /\bapt(-get)?\s+(install|remove|purge|autoremove|upgrade|dist-upgrade|full-upgrade)\b/i,
+  /\bdpkg\s+(-r|-P|--purge)\b/i,
+  /\byum\s+(remove|erase|update|install)\b/i,
+  /\bpip3?\s+uninstall\b/i,
+  /\bnpm\s+(uninstall|rm)\b/i,
+  /\buserdel\b/i,
+  /\bgroupdel\b/i,
+  /\bchmod\s+(-R\s+)?0?777\b/i,
+  /\bchown\s+-R\b/i,
+  /\bcrontab\s+-r\b/i,
+  /\biptables\b/i,
+  /\bnft\s+(flush|delete)\b/i,
+  /\bufw\s+disable\b/i,
+  /\bshutdown\b/i,
+  /\breboot\b/i,
+  /\bhalt\b/i,
+  /\bpoweroff\b/i,
+  />\s*\/(etc|var|usr|boot)\//i,
+  /\btee\s+\/(etc|var|usr|boot)\//i,
+  /\bsed\s+-i\b/i,
+];
+
+export const RECIPES = [
+  {
+    id: 'recipe_disk_pressure',
+    category: 'system',
+    title: 'Disk pressure',
+    description: 'Report partitions above 80% usage; stay quiet when everything is comfortable.',
+    type: 'script',
+    schedule: '0 8 * * *',
+    scheduleText: 'Every day at 08:00',
+    prompt: "df -h -x tmpfs -x devtmpfs | awk 'NR==1 || $5+0 > 80'",
+    channels: ['telegram'],
+    silentRule: 'Stay silent when no filesystem in the output is above 80% usage. Otherwise report the offending lines.',
+  },
+  {
+    id: 'recipe_memory_pressure',
+    category: 'system',
+    title: 'Memory and swap pressure',
+    description: 'Report memory and swap state; stay quiet while swap stays untouched.',
+    type: 'script',
+    schedule: '0 */6 * * *',
+    scheduleText: 'Every 6 hours',
+    prompt: 'free -m && echo "---" && uptime',
+    channels: ['telegram'],
+    silentRule: 'Stay silent when swap used is 0 MB and the load average is below the number of CPU cores. Otherwise report the numbers.',
+  },
+  {
+    id: 'recipe_failed_units',
+    category: 'services',
+    title: 'Failed systemd units',
+    description: 'List failed units; stay quiet when the list is empty.',
+    type: 'script',
+    schedule: '0 * * * *',
+    scheduleText: 'Every hour',
+    prompt: 'systemctl --failed --no-pager --no-legend',
+    channels: ['telegram'],
+    silentRule: 'Stay silent when the output lists no failed units. Otherwise report every failed unit.',
+  },
+  {
+    id: 'recipe_journal_errors',
+    category: 'services',
+    title: 'Errors in the journal',
+    description: 'Surface error-level journal entries from the last day.',
+    type: 'script',
+    schedule: '30 8 * * *',
+    scheduleText: 'Every day at 08:30',
+    prompt: "journalctl -p err --since '24 hours ago' --no-pager | tail -n 40",
+    channels: ['telegram'],
+    silentRule: 'Stay silent when the output contains no error lines. Otherwise summarise what is failing repeatedly.',
+  },
+  {
+    id: 'recipe_container_health',
+    category: 'services',
+    title: 'Container health',
+    description: 'List containers that are not Up; skip the task silently without Docker.',
+    type: 'script',
+    schedule: '*/30 * * * *',
+    scheduleText: 'Every 30 minutes',
+    prompt: "command -v docker >/dev/null 2>&1 || { echo 'docker is not installed'; exit 0; }; docker ps --format '{{.Names}}\\t{{.Status}}\\t{{.Image}}'",
+    channels: ['telegram'],
+    silentRule: 'Stay silent when every listed container is Up and no container is restarting. Otherwise report the unhealthy ones.',
+  },
+  {
+    id: 'recipe_log_growth',
+    category: 'storage',
+    title: 'Log directory growth',
+    description: 'Track the size of /var/log and the largest files inside it.',
+    type: 'script',
+    schedule: '0 9 * * 1',
+    scheduleText: 'Mondays at 09:00',
+    prompt: "du -sh /var/log 2>/dev/null; du -ah /var/log 2>/dev/null | sort -rh | head -n 10",
+    channels: ['telegram'],
+    silentRule: 'Stay silent when /var/log is smaller than 1 GB. Otherwise report the total and the largest files.',
+  },
+  {
+    id: 'recipe_backup_freshness',
+    category: 'storage',
+    title: 'Backup freshness',
+    description: 'Show the newest backup files so a stalled backup job becomes visible.',
+    type: 'script',
+    schedule: '0 7 * * *',
+    scheduleText: 'Every day at 07:00',
+    prompt: "ls -lt /var/backups 2>/dev/null | head -n 5 || echo 'no /var/backups directory'",
+    channels: ['telegram'],
+    silentRule: 'Stay silent when the newest backup file is less than 48 hours old. Report out loud when it is older or the directory is missing.',
+  },
+  {
+    id: 'recipe_certificate_expiry',
+    category: 'security',
+    title: 'Certificate expiry',
+    description: 'Report TLS certificates that expire within 30 days.',
+    type: 'script',
+    schedule: '0 8 * * 1',
+    scheduleText: 'Mondays at 08:00',
+    prompt: "find /etc/letsencrypt/live -name fullchain.pem 2>/dev/null | while read -r cert; do days=$(( ( $(date -d \"$(openssl x509 -enddate -noout -in \"$cert\" | cut -d= -f2)\" +%s) - $(date +%s) ) / 86400 )); echo \"$days days  $cert\"; done",
+    channels: ['telegram'],
+    silentRule: 'Stay silent when every certificate has more than 30 days left. Report the ones that expire sooner.',
+  },
+  {
+    id: 'recipe_pending_updates',
+    category: 'security',
+    title: 'Pending package updates',
+    description: 'Count upgradable packages without installing anything.',
+    type: 'script',
+    schedule: '0 10 * * 5',
+    scheduleText: 'Fridays at 10:00',
+    prompt: "command -v apt >/dev/null 2>&1 || { echo 'apt is not available'; exit 0; }; apt list --upgradable 2>/dev/null | tail -n +2 | wc -l",
+    channels: ['telegram'],
+    silentRule: 'Stay silent when there are no pending updates. Otherwise report the count and mention that applying them is a manual step.',
+  },
+  {
+    id: 'recipe_uptime_review',
+    category: 'maintenance',
+    title: 'Weekly uptime review',
+    description: 'A short weekly note with uptime, load and the kernel in use.',
+    type: 'script',
+    schedule: '0 9 * * 1',
+    scheduleText: 'Mondays at 09:00',
+    prompt: 'uptime && echo "---" && uname -r && echo "---" && df -h / | tail -n 1',
+    channels: ['telegram'],
+  },
+];
+
+/** Detached copy of the catalog, safe to hand to the UI. */
+export function listRecipes() {
+  return RECIPES.map((recipe) => ({ ...recipe, channels: [...(recipe.channels || [])] }));
+}
+
+export function recipesByCategory() {
+  return RECIPE_CATEGORIES.map((category) => ({
+    ...category,
+    recipes: listRecipes().filter((recipe) => recipe.category === category.id),
+  }));
+}
+
+/**
+ * The panel's "recommended" list: the same catalog, flattened, so the hub is
+ * the single source instead of a second hand-written list (legacy shape kept).
+ */
+export function recipeRecommendations(limit = 6) {
+  return listRecipes()
+    .slice(0, limit)
+    .map((recipe) => ({
+      id: recipe.id,
+      title: recipe.title,
+      schedule: recipe.schedule,
+      scheduleText: recipe.scheduleText,
+      prompt: recipe.prompt,
+      description: recipe.description,
+      type: recipe.type,
+      category: recipe.category,
+      channels: recipe.channels,
+      silentRule: recipe.silentRule || '',
+    }));
+}
+
+/** A recipe must never contain a destructive command. */
+export function findDestructiveRecipe(recipes = RECIPES) {
+  for (const recipe of recipes) {
+    for (const pattern of DESTRUCTIVE_PATTERNS) {
+      if (pattern.test(String(recipe.prompt || ''))) {
+        return { id: recipe.id, pattern: String(pattern) };
+      }
+    }
+  }
+  return null;
+}