@goodandready/dsh-cron 0.2.3 → 0.2.5

package/lib/secrets.js

@@ -0,0 +1,123 @@
+/**
+ * Credential handling for dsh-cron (#51).
+ *
+ * Settings store only the NAME of a credential (an environment-variable-style
+ * reference); the value is resolved at send time through the DSH credentials
+ * service, with an environment fallback. This mirrors the pattern already
+ * used by dsh-clinebot and dsh-agentrouter.
+ */
+
+import fs from 'node:fs';
+import { getDshSettingsPath } from './telegram.js';
+
+const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TOKEN_LIKE = /^[A-Za-z0-9:_-]{24,}$/;
+
+export function isCredentialRefName(value) {
+  return REF_PATTERN.test(String(value || '').trim());
+}
+
+/** Heuristic: a pasted secret instead of a credential name. */
+export function looksLikeSecret(value) {
+  const s = String(value || '').trim();
+  if (!s || isCredentialRefName(s)) return false;
+  return TOKEN_LIKE.test(s);
+}
+
+/**
+ * Validate a credential-reference field. Returns { ok, name } or
+ * { ok: false, error } with actionable text for the settings card.
+ */
+export function credentialRefStatus(value) {
+  const name = String(value || '').trim();
+  if (!name) return { ok: true, name: '' };
+  if (looksLikeSecret(name)) {
+    return {
+      ok: false,
+      error: 'That looks like a secret value. Store it in DSH credentials and enter only the credential name (for example CRON_TELEGRAM_BOT_TOKEN).',
+    };
+  }
+  if (!isCredentialRefName(name)) {
+    return { ok: false, error: 'Credential name must look like an environment variable name, e.g. CRON_TELEGRAM_BOT_TOKEN.' };
+  }
+  return { ok: true, name };
+}
+
+/** Resolve a credential through the harness service, then the environment. */
+export async function resolveCredentialValue(ctx, refName) {
+  const name = String(refName || '').trim();
+  if (!name) return null;
+  try {
+    const creds = (ctx && typeof ctx.get === 'function' ? ctx.get('credentials') : null)
+      || (ctx && ctx.credentials);
+    if (creds && typeof creds.resolve === 'function') {
+      // Prefer the harness ref factory; fall back to the plain name when the
+      // package is not installed (keeps tests and trimmed builds working).
+      let ref = name;
+      try {
+        const mod = await import('@deepseek-ai/dsh-credentials');
+        if (mod && typeof mod.credentialRef === 'function') ref = mod.credentialRef(name);
+      } catch {}
+      const hit = await creds.resolve(ref);
+      if (hit && hit.value) return String(hit.value);
+    }
+  } catch {
+    // credentials service unavailable — fall back to the environment
+  }
+  const fromEnv = process.env[name];
+  return fromEnv ? String(fromEnv) : null;
+}
+
+/** Read the best-effort Telegram defaults from the messenger-gateway file. */
+function readGatewayToken() {
+  try {
+    const p = getDshSettingsPath();
+    if (!fs.existsSync(p)) return null;
+    const text = fs.readFileSync(p, 'utf-8');
+    const lines = text.split('\n');
+    let inside = false;
+    for (const line of lines) {
+      if (/^[^\s#]/.test(line)) inside = line.startsWith('dsh-messenger-gateway:');
+      if (!inside) continue;
+      const hit = /^[ \t]+botToken:[ \t]*(.+?)[ \t]*$/.exec(line);
+      if (hit) return hit[1].replace(/^['"]|['"]$/g, '').trim() || null;
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * Resolve the Telegram delivery secrets for a run.
+ * Precedence: credential reference → legacy stored token → messenger-gateway
+ * settings file → environment variable.
+ */
+export async function resolveTelegramSecrets(ctx, settings = {}) {
+  const out = { botToken: '', chatId: '', tokenSource: 'none' };
+
+  const fromRef = await resolveCredentialValue(ctx, settings.botTokenRef);
+  if (fromRef) {
+    out.botToken = fromRef;
+    out.tokenSource = 'credential';
+  }
+  if (!out.botToken && settings.botToken) {
+    out.botToken = String(settings.botToken);
+    out.tokenSource = 'legacy-settings';
+  }
+  if (!out.botToken) {
+    const gateway = readGatewayToken();
+    if (gateway) {
+      out.botToken = gateway;
+      out.tokenSource = 'messenger-gateway';
+    }
+  }
+  if (!out.botToken) {
+    const fromEnv = await resolveCredentialValue(ctx, 'CRON_TELEGRAM_BOT_TOKEN');
+    if (fromEnv) {
+      out.botToken = fromEnv;
+      out.tokenSource = 'env';
+    }
+  }
+
+  out.chatId = String(settings.chatId || '').trim();
+  return out;
+}

package/lib/store.js

@@ -2,11 +2,31 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { getDshDefaultTelegramCredentials } from './telegram.js';
 
+/**
+ * Where plugin data lives.
+ *
+ * DSH_DATA_DIR wins when the harness sets it. Otherwise the profile home
+ * (DSH_HOME) is authoritative: falling back to ~/.dsh would make an isolated
+ * profile — a test contour, a second profile — write its tasks into another
+ * home's data directory, which is how the MiniPC test cycle leaked a task into
+ * the non-test profile.
+ */
 export function getDefaultStorePath() {
-  const base = process.env.DSH_DATA_DIR || path.join(process.env.HOME || '.', '.dsh', 'data');
+  const base = process.env.DSH_DATA_DIR
+    || (process.env.DSH_HOME
+      ? path.join(process.env.DSH_HOME, 'data')
+      : path.join(process.env.HOME || '.', '.dsh', 'data'));
   return path.join(base, 'cron', 'tasks.json');
 }
 
+/** Mask a secret for transport to the browser, keeping a readable hint. */
+function maskSecretValue(value) {
+  const s = String(value == null ? '' : value);
+  if (!s) return '';
+  if (s.length <= 8) return '••••••••';
+  return s.slice(0, 4) + '••••••••' + s.slice(-3);
+}
+
 export class TaskStore {
   constructor(filePath) {
     this.filePath = filePath || getDefaultStorePath();
@@ -70,14 +90,15 @@ export class TaskStore {
 
   getSettings() {
     const defaults = getDshDefaultTelegramCredentials();
-    return {
-      botToken: this.settings.botToken !== undefined ? this.settings.botToken : (defaults.botToken || ''),
-      chatId: this.settings.chatId !== undefined ? this.settings.chatId : (defaults.chatId || ''),
-      notifyTelegram: Boolean(this.settings.notifyTelegram),
-      onlyOnFailure: Boolean(this.settings.onlyOnFailure),
-      hasDefaultCredentials: Boolean(defaults.botToken && defaults.chatId),
-      kanbanBaseUrl: this.settings.kanbanBaseUrl || 'http://127.0.0.1:3000',
-    };
+    const base = { ...this.settings };
+    base.botToken = base.botToken !== undefined ? base.botToken : (defaults.botToken || '');
+    base.botTokenRef = base.botTokenRef || '';
+    base.chatId = base.chatId !== undefined ? base.chatId : (defaults.chatId || '');
+    base.notifyTelegram = Boolean(base.notifyTelegram);
+    base.onlyOnFailure = Boolean(base.onlyOnFailure);
+    base.kanbanBaseUrl = base.kanbanBaseUrl || 'http://127.0.0.1:3000';
+    base.hasDefaultCredentials = Boolean(defaults.botToken && defaults.chatId);
+    return base;
   }
 
   getClientSettings() {
@@ -85,38 +106,87 @@ export class TaskStore {
     const isCustom = Boolean(this.settings.botToken);
     const hasToken = Boolean(raw.botToken);
     const masked = hasToken ? (raw.botToken.length > 8 ? raw.botToken.slice(0, 4) + '••••••••' + raw.botToken.slice(-3) : '••••••••') : '';
-    return {
+    const { botToken, ...rest } = raw;
+    const out = {
+      ...rest,
       botToken: masked,
       botTokenMasked: masked,
       hasBotToken: hasToken,
       hasCustomBotToken: isCustom,
-      chatId: raw.chatId,
-      notifyTelegram: raw.notifyTelegram,
-      onlyOnFailure: raw.onlyOnFailure,
-      hasDefaultCredentials: raw.hasDefaultCredentials,
-      kanbanBaseUrl: raw.kanbanBaseUrl,
     };
+    // Webhook URLs and the Bark device key carry an embedded secret, so they
+    // are never sent to the browser in clear text either.
+    for (const key of TaskStore.MASKED_SETTING_KEYS) {
+      if (key === 'botToken') continue;
+      out[key] = maskSecretValue(raw[key]);
+    }
+    return out;
+  }
+
+  /**
+   * Raw secret values that must not be stored in plugin settings; the
+   * corresponding *Ref credential names are the supported way to configure
+   * these channels.
+   */
+  static get FORBIDDEN_SETTING_KEYS() {
+    return ['giteaToken', 'ntfyToken', 'pushplusToken', 'discordToken', 'slackToken'];
+  }
+
+  /**
+   * Settings that hold a secret and are therefore masked on read: tokens and
+   * webhook URLs (the URL embeds the auth token), plus the Bark device key.
+   * These are stored in the plugin settings file; the credential-reference
+   * fields (botTokenRef, ntfyTokenRef, …) take precedence over them.
+   */
+  static get MASKED_SETTING_KEYS() {
+    return ['botToken', 'discordWebhookUrl', 'slackWebhookUrl', 'barkKey'];
   }
 
   saveSettings(newSettings = {}) {
+    const patch = { ...newSettings };
+
+    for (const key of TaskStore.FORBIDDEN_SETTING_KEYS) {
+      if (key in patch) {
+        console.warn(`[dsh-cron] refusing to store raw secret "${key}" in settings — use a credential reference instead`);
+        delete patch[key];
+      }
+    }
+
     let botTokenToSave = this.settings.botToken || '';
-    if (newSettings.botToken !== undefined) {
-      const val = String(newSettings.botToken).trim();
+    if (patch.botToken !== undefined) {
+      const val = String(patch.botToken).trim();
       // If client sends masked token or empty string while custom token existed, don't overwrite with dots
       if (val && !val.includes('••') && !val.includes('****')) {
         botTokenToSave = val;
       } else if (val === '') {
         botTokenToSave = '';
       }
+      delete patch.botToken;
+    }
+
+    // A masked value echoed back by the UI must never overwrite the real one.
+    for (const key of TaskStore.MASKED_SETTING_KEYS) {
+      if (key === 'botToken') continue;
+      const val = patch[key];
+      if (typeof val === 'string' && (val.includes('••') || val.includes('****'))) {
+        delete patch[key];
+      }
+    }
+
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === undefined) delete patch[key];
+      else if (typeof value === 'string') patch[key] = value.trim();
     }
 
     this.settings = {
       ...this.settings,
+      ...patch,
       botToken: botTokenToSave,
-      chatId: newSettings.chatId !== undefined ? String(newSettings.chatId).trim() : (this.settings.chatId || ''),
-      notifyTelegram: newSettings.notifyTelegram !== undefined ? Boolean(newSettings.notifyTelegram) : Boolean(this.settings.notifyTelegram),
-      onlyOnFailure: newSettings.onlyOnFailure !== undefined ? Boolean(newSettings.onlyOnFailure) : Boolean(this.settings.onlyOnFailure),
-      kanbanBaseUrl: newSettings.kanbanBaseUrl !== undefined ? String(newSettings.kanbanBaseUrl).trim() : (this.settings.kanbanBaseUrl || 'http://127.0.0.1:3000'),
+      kanbanBaseUrl: patch.kanbanBaseUrl !== undefined
+        ? (patch.kanbanBaseUrl || 'http://127.0.0.1:3000')
+        : (this.settings.kanbanBaseUrl || 'http://127.0.0.1:3000'),
+      notifyTelegram: patch.notifyTelegram !== undefined ? Boolean(patch.notifyTelegram) : Boolean(this.settings.notifyTelegram),
+      onlyOnFailure: patch.onlyOnFailure !== undefined ? Boolean(patch.onlyOnFailure) : Boolean(this.settings.onlyOnFailure),
     };
     this.save();
     return this.getSettings();

package/lib/task-transfer.js

@@ -0,0 +1,226 @@
+/**
+ * Task transfer helpers: duplication, export and import (#41, #42).
+ *
+ * Pure functions over plain task objects with no I/O, so the whole
+ * configuration-transfer contract is unit-testable and the HTTP layer stays a
+ * thin adapter. Kept out of index.js both for cohesion and to keep that file
+ * from growing further (see issue #97).
+ */
+
+import { randomUUID } from 'node:crypto';
+import { normalizeTaskType } from './runtimes.js';
+import { CHANNEL_IDS } from './channels.js';
+
+/** Task fields a client may patch; the single source of truth below. */
+export const PATCHABLE_TASK_FIELDS = [
+  'title',
+  'schedule',
+  'scheduleText',
+  'prompt',
+  'type',
+  'delivery',
+  'provider',
+  'model',
+  'timezone',
+  'misfirePolicy',
+  'maxRetries',
+  'retryBackoffMs',
+  'permissionPreset',
+  'env',
+  'cwd',
+  'workspaceId',
+  'worktree',
+  'keepWorktree',
+  'httpMethod',
+  'httpUrl',
+  'httpHeaders',
+  'httpBody',
+  'sshTarget',
+  'sshPort',
+  'sshKeyPath',
+  'sshProfileId',
+  'dockerImage',
+  'pythonPath',
+  'nodePath',
+  'skillName',
+  'workflowName',
+  'notifyTelegram',
+  'onlyOnFailure',
+  'timeoutSeconds',
+  'overlapPolicy',
+  'kanbanMode',
+  'channels',
+  'template',
+  'status',
+  'oneShot',
+];
+
+/** Fields a duplicate inherits; anything else is runtime state, not config. */
+export const DUPLICATE_TASK_FIELDS = PATCHABLE_TASK_FIELDS.filter((key) => key !== 'status');
+
+/**
+ * Task ids that would shadow the collection routes under /dsh-cron/tasks.
+ * A task may not use them, otherwise it could never be fetched, paused or
+ * deleted again (#42 review finding).
+ */
+export const RESERVED_TASK_IDS = ['export', 'import'];
+
+/**
+ * Task-level fields that can carry a secret the user typed in by hand
+ * (`env` values, authorization headers). The export includes them, so the UI
+ * and docs must say so instead of promising a secret-free file.
+ */
+export const EXPORT_SECRET_BEARING_FIELDS = ['env', 'httpHeaders', 'httpBody'];
+
+/**
+ * Validate runtime-specific task configuration. Returns an error string or
+ * null when the payload is usable for the given type.
+ */
+export function validateTaskType(type, payload) {
+  const t = normalizeTaskType(type);
+  if (t === 'http') {
+    const raw = String((payload && (payload.httpUrl || payload.prompt)) || '').trim();
+    if (!raw) return 'HTTP tasks require a URL (httpUrl or prompt)';
+    try {
+      // eslint-disable-next-line no-new
+      new URL(raw);
+    } catch {
+      return `Invalid HTTP URL: ${raw}`;
+    }
+  }
+  if (t === 'ssh') {
+    const hasProfile = Boolean(payload && String(payload.sshProfileId || '').trim());
+    const hasTarget = Boolean(payload && String(payload.sshTarget || '').trim());
+    if (!hasProfile && !hasTarget) return 'SSH tasks require sshProfileId (remote-workspace profile) or sshTarget (user@host)';
+  }
+  if (t === 'docker' && !String((payload && payload.dockerImage) || '').trim()) {
+    return 'Docker tasks require dockerImage';
+  }
+  return null;
+}
+
+/**
+ * Build a paused copy of a task (#41).
+ *
+ * Configuration is copied, execution state is not: the copy starts paused with
+ * no history, no token/cost totals, no last-run info and no retry counter, so a
+ * duplicate can be reviewed before it ever runs. A duplicated one-shot keeps
+ * its original schedule string and stays inert until the user resumes it.
+ */
+export function buildDuplicateTask(source, { id } = {}) {
+  const copy = {
+    id: id || randomUUID(),
+    title: `${source.title || 'Task'} (copy)`,
+    status: 'paused',
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+  for (const key of DUPLICATE_TASK_FIELDS) {
+    if (key === 'title') continue;
+    if (source[key] !== undefined) copy[key] = Array.isArray(source[key]) ? [...source[key]] : source[key];
+  }
+  return copy;
+}
+
+// ---------------------------------------------------- export / import (#42)
+
+/** Document kind marker so a random JSON file is not mistaken for an export. */
+export const TASK_EXPORT_KIND = 'dsh-cron-tasks';
+export const TASK_EXPORT_VERSION = 1;
+
+/** Fields an exported task carries: identity + configuration, never run state. */
+export const EXPORT_TASK_FIELDS = ['id', 'title', ...DUPLICATE_TASK_FIELDS.filter((k) => k !== 'title')];
+
+/** Import strategies: add (new ids), replace (overwrite by id), skip (leave existing). */
+export const IMPORT_STRATEGIES = ['add', 'replace', 'skip'];
+
+/**
+ * Serialise tasks for transfer/backup. Run state (history, token and cost
+ * totals, last-run info) is deliberately excluded — the file is a
+ * configuration artefact. Channels reference credentials by name, but task-level
+ * `env` and headers can contain hand-typed secrets, so the caller must not
+ * claim the file is secret-free.
+ */
+export function buildTaskExport(tasks, { now = Date.now() } = {}) {
+  const list = Array.isArray(tasks) ? tasks : [];
+  return {
+    kind: TASK_EXPORT_KIND,
+    version: TASK_EXPORT_VERSION,
+    exportedAt: new Date(now).toISOString(),
+    tasks: list.map((task) => {
+      const out = {};
+      for (const key of EXPORT_TASK_FIELDS) {
+        if (task[key] === undefined || key === 'status') continue;
+        out[key] = Array.isArray(task[key]) ? [...task[key]] : task[key];
+      }
+      return out;
+    }),
+  };
+}
+
+/**
+ * Validate an import document and return sanitised tasks.
+ *
+ * An import file is external input, so it is treated as untrusted: only
+ * whitelisted configuration fields survive, the file's `status` is ignored
+ * (imported tasks always start paused, matching the documented behaviour), and
+ * a document that would shadow a collection route id is refused. A malformed
+ * file is rejected as a whole so nothing is written.
+ */
+export function validateImportDocument(doc) {
+  if (!doc || typeof doc !== 'object') return { ok: false, error: 'Import file is not a JSON object' };
+  if (doc.kind !== TASK_EXPORT_KIND) return { ok: false, error: `Not a ${TASK_EXPORT_KIND} export (missing kind marker)` };
+  if (Number(doc.version) > TASK_EXPORT_VERSION) {
+    return { ok: false, error: `Export version ${doc.version} is newer than this plugin understands (${TASK_EXPORT_VERSION})` };
+  }
+  if (!Array.isArray(doc.tasks)) return { ok: false, error: 'Export has no tasks array' };
+  const tasks = [];
+  for (const [index, raw] of doc.tasks.entries()) {
+    if (!raw || typeof raw !== 'object') return { ok: false, error: `Task #${index + 1} is not an object` };
+    if (!raw.title || !String(raw.title).trim()) return { ok: false, error: `Task #${index + 1} has no title` };
+    if (!raw.schedule || !String(raw.schedule).trim()) return { ok: false, error: `Task #${index + 1} has no schedule` };
+    if (!raw.prompt || !String(raw.prompt).trim()) return { ok: false, error: `Task #${index + 1} has no prompt` };
+    const id = raw.id === undefined ? undefined : String(raw.id);
+    if (id && RESERVED_TASK_IDS.includes(id)) {
+      return { ok: false, error: `Task #${index + 1} uses the reserved id "${id}" which would shadow a task route` };
+    }
+    const type = normalizeTaskType(raw.type);
+    const typeError = validateTaskType(type, raw);
+    if (typeError) return { ok: false, error: `Task #${index + 1} ("${raw.title}"): ${typeError}` };
+    const channels = Array.isArray(raw.channels) ? raw.channels.filter((c) => CHANNEL_IDS.includes(c)) : undefined;
+    // Whitelist: drop anything the file tried to smuggle in (counters, history
+    // pointers, unknown keys) and never inherit the file's status.
+    const clean = { status: 'paused', type };
+    for (const key of DUPLICATE_TASK_FIELDS) {
+      if (raw[key] !== undefined) clean[key] = Array.isArray(raw[key]) ? [...raw[key]] : raw[key];
+    }
+    if (id) clean.id = id;
+    if (channels) clean.channels = channels;
+    tasks.push(clean);
+  }
+  return { ok: true, tasks };
+}
+
+/** True when any task in a validated batch executes code on the host. */
+export function hasCodeExecutingTask(tasks) {
+  const CODE_TYPES = ['script', 'node', 'python', 'ssh', 'docker'];
+  return (tasks || []).some((task) => CODE_TYPES.includes(normalizeTaskType(task.type)));
+}
+
+/**
+ * Decide what an import would do, without touching anything. Existing ids are
+ * compared against tasks already in the store.
+ */
+export function planImport(tasks, existingIds, strategy = 'skip') {
+  const mode = IMPORT_STRATEGIES.includes(strategy) ? strategy : 'skip';
+  const existing = new Set(existingIds || []);
+  const plan = { strategy: mode, add: [], replace: [], skip: [] };
+  for (const task of tasks || []) {
+    const hasId = Boolean(task.id) && existing.has(task.id);
+    if (!hasId) plan.add.push(task);
+    else if (mode === 'replace') plan.replace.push(task);
+    else if (mode === 'skip') plan.skip.push(task);
+    else plan.add.push({ ...task, id: undefined });
+  }
+  return plan;
+}

package/lib/telegram.js

@@ -37,13 +37,27 @@ export function extractFirstAllowedChatId(text) {
   return undefined;
 }
 
+/**
+ * Harness home for this process. DSH_HOME wins so an isolated profile reads
+ * its own settings file instead of another home's (same rule as the store).
+ */
+export function getDshHomeDir() {
+  const fromEnv = process.env.DSH_HOME;
+  if (fromEnv && String(fromEnv).trim()) return String(fromEnv).trim();
+  return path.join(process.env.HOME || os.homedir(), '.dsh');
+}
+
+export function getDshSettingsPath() {
+  return path.join(getDshHomeDir(), 'settings.yaml');
+}
+
 /**
  * Read system DSH settings for fallback credentials.
  * Fails soft with a logged warning so silent misconfiguration is visible (#93).
  */
 export function getDshDefaultTelegramCredentials() {
   try {
-    const p = path.join(process.env.HOME || os.homedir(), '.dsh', 'settings.yaml');
+    const p = getDshSettingsPath();
     if (fs.existsSync(p)) {
       let raw;
       try {
@@ -105,7 +119,7 @@ export function formatTaskTelegramMessage(task, runInfo) {
 /**
  * Send telegram message via Bot API.
  */
-export async function sendTelegramMessage({ botToken, chatId, text, parseMode = 'Markdown' }) {
+export async function sendTelegramMessage({ botToken, chatId, text, parseMode = 'Markdown', fetchFn = globalThis.fetch, signal }) {
   if (!botToken) throw new Error('Telegram botToken is not configured');
   if (!chatId) throw new Error('Telegram chatId is not configured');
 
@@ -117,20 +131,22 @@ export async function sendTelegramMessage({ botToken, chatId, text, parseMode =
   };
   if (parseMode) body.parse_mode = parseMode;
 
-  const res = await fetch(url, {
+  const res = await fetchFn(url, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(body),
+    signal,
   });
 
   const data = await res.json().catch(() => ({}));
   if (!res.ok || !data.ok) {
     if (parseMode && data.description && data.description.includes("can't parse entities")) {
       delete body.parse_mode;
-      const retryRes = await fetch(url, {
+      const retryRes = await fetchFn(url, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(body),
+        signal,
       });
       const retryData = await retryRes.json().catch(() => ({}));
       if (retryRes.ok && retryData.ok) {

package/lib/templates.js

@@ -0,0 +1,88 @@
+/**
+ * Notification template engine (#25).
+ *
+ * Messages for every channel are rendered from a template with `{var}`
+ * placeholders. Pure functions only — no I/O — so the whole matrix is
+ * unit-testable.
+ */
+
+export const TEMPLATE_VARIABLES = [
+  'title',
+  'id',
+  'status',
+  'output',
+  'error',
+  'duration',
+  'schedule',
+  'time',
+  'tokens',
+  'cost',
+];
+
+export const DEFAULT_PLAIN_TEMPLATE = '⏰ {title}\nStatus: {status}\nSchedule: {schedule}\nDuration: {duration}\n{output}';
+
+export const DEFAULT_FAILURE_TEMPLATE = '❌ {title} failed\nSchedule: {schedule}\nDuration: {duration}\n{error}';
+
+const MAX_FIELD = 2000;
+
+export function truncateText(text, limit = MAX_FIELD) {
+  const s = String(text == null ? '' : text);
+  if (s.length <= limit) return s;
+  return s.slice(0, limit) + '…';
+}
+
+export function formatDuration(ms) {
+  if (ms === null || ms === undefined || ms === '') return '—';
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n < 0) return '—';
+  if (n < 1000) return `${Math.round(n)} ms`;
+  const seconds = n / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)} s`;
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}m ${Math.round(seconds % 60)}s`;
+}
+
+/** Build the placeholder map for one run. */
+export function buildTemplateVars(task, runInfo = {}) {
+  const status = runInfo.status || 'unknown';
+  const output = status === 'success' ? (runInfo.output || '') : '';
+  const error = runInfo.error || (status === 'error' || status === 'timeout' ? runInfo.output || '' : '');
+  const usage = runInfo.usage || {};
+  const tokens = (usage.inputTokens || 0) + (usage.outputTokens || 0) + (usage.cacheReadTokens || 0);
+  return {
+    title: task.title || 'Task',
+    id: task.id || '',
+    status,
+    output: truncateText(output),
+    error: truncateText(error),
+    duration: formatDuration(runInfo.durationMs),
+    schedule: task.scheduleText || task.schedule || '',
+    time: new Date(runInfo.at || Date.now()).toISOString(),
+    tokens: String(tokens),
+    cost: `$${Number(runInfo.costUsd || 0).toFixed(4)}`,
+  };
+}
+
+/** Replace {var} placeholders; unknown placeholders are left untouched. */
+export function renderTemplate(template, vars) {
+  return String(template == null ? '' : template).replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (match, name) => {
+    if (Object.prototype.hasOwnProperty.call(vars, name)) {
+      const value = vars[name];
+      return value === null || value === undefined ? '' : String(value);
+    }
+    return match;
+  });
+}
+
+/**
+ * Pick the template for a run: failure template for failed runs unless a
+ * custom template is configured, plain template otherwise.
+ */
+export function resolveTemplateText({ template, task, runInfo }) {
+  const custom = typeof template === 'string' && template.trim() ? template.trim() : '';
+  if (custom) return renderTemplate(custom, buildTemplateVars(task, runInfo));
+  const failed = runInfo.status === 'error' || runInfo.status === 'timeout';
+  const base = failed ? DEFAULT_FAILURE_TEMPLATE : DEFAULT_PLAIN_TEMPLATE;
+  const text = renderTemplate(base, buildTemplateVars(task, runInfo));
+  return text.replace(/\n{3,}/g, '\n\n').trim();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cron",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Scheduled cron tasks, background automation and agent execution for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",