@goodandready/dsh-cron 0.2.6 → 0.2.7

package/lib/api.js

@@ -8,8 +8,9 @@
 import { randomUUID } from 'node:crypto';
 import { parseScheduleExpression } from './scheduler.js';
 import { normalizeTaskType, CODE_EXECUTING_TYPES } from './runtimes.js';
-import { CHANNEL_IDS } from './channels.js';
+import { CHANNEL_IDS, unknownChannelIds } from './channels.js';
 import { applyTaskPatch } from './task-patch.js';
+import { MANAGED_BY_CONFIG, configOwnedMessage } from './config-jobs.js';
 import { sendJson, rejectCrossOrigin, readBody, pickPatchableFields, SCRIPT_CONFIRM_HEADER } from './http-utils.js';
 import {
   validateTaskType,
@@ -26,6 +27,15 @@ import {
 const NOT_FOUND = { ok: false, error: 'Task not found' };
 const NOT_ALLOWED = { ok: false, error: 'Method not allowed' };
 
+/**
+ * A task declared in the profile config is owned by that file (#50): the next
+ * plugin start would revert any change made here, so every mutating route
+ * refuses it and says where the task really lives.
+ */
+function refuseConfigOwned(res, id) {
+  sendJson(res, 409, { ok: false, error: configOwnedMessage(id) });
+}
+
 /**
  * Shared implementation for the /dsh-cron/tasks... and /dsh-cron/action...
  * route families — the #66 alias is kept alive by the same code path instead
@@ -108,6 +118,15 @@ async function createOrUpdateTask({ store, scheduler, req, res }) {
     sendJson(res, 400, { ok: false, error: 'Fields title, schedule and prompt are required' });
     return;
   }
+  const unknownChannels = unknownChannelIds(body.channels);
+  if (unknownChannels.length) {
+    sendJson(res, 400, {
+      ok: false,
+      error: 'Unknown channel ids: ' + unknownChannels.join(', '),
+      unknownChannels,
+    });
+    return;
+  }
   const taskType = normalizeTaskType(body.type);
   if (CODE_EXECUTING_TYPES.includes(taskType) && req.headers[SCRIPT_CONFIRM_HEADER] !== 'script') {
     sendJson(res, 403, { ok: false, error: `Creating ${taskType} tasks over HTTP requires the x-dsh-cron-confirm: script header` });
@@ -126,6 +145,16 @@ async function createOrUpdateTask({ store, scheduler, req, res }) {
     sendJson(res, 400, { ok: false, error: `Task id "${body.id}" is reserved` });
     return;
   }
+  // Create-or-update with an existing id is an update too, so the config-owned
+  // refusal must apply here as well — otherwise the POST route would be a way
+  // around the guard on PATCH (#50 review finding).
+  if (body.id) {
+    const existing = store.get(body.id);
+    if (existing && existing.managedBy === MANAGED_BY_CONFIG) {
+      refuseConfigOwned(res, body.id);
+      return;
+    }
+  }
   const task = store.set(buildTaskRecord(store, body, taskType, parsed));
   if (task.status === 'active') {
     scheduler.scheduleTask(task);
@@ -192,8 +221,36 @@ async function handleTaskImport({ store, scheduler, req, res }) {
     });
     return;
   }
+  // #121: an imported file may name a channel this build no longer has. The
+  // import stays tolerant by design (#42), but the loss is reported instead of
+  // being invisible.
+  const rawTasks = Array.isArray(body.document && body.document.tasks) ? body.document.tasks : [];
+  const droppedChannels = [];
+  for (const item of rawTasks) {
+    for (const id of unknownChannelIds(item.channels)) {
+      if (!droppedChannels.includes(id)) droppedChannels.push(id);
+    }
+  }
+  if (droppedChannels.length) {
+    console.warn('[dsh-cron] import: unknown channel ids were dropped: ' + droppedChannels.join(', '));
+  }
   const existingIds = store.list({ status: 'all' }).map((x) => x.id);
   const plan = planImport(checked.tasks, existingIds, strategy);
+  // Replacing a task the config owns would be undone at the next start, and
+  // the id could then hold two different tasks (#50).
+  const configConflicts = plan.replace
+    .map((item) => item.id)
+    .filter((taskId) => {
+      const stored = store.get(taskId);
+      return stored && stored.managedBy === MANAGED_BY_CONFIG;
+    });
+  if (configConflicts.length) {
+    sendJson(res, 409, {
+      ok: false,
+      error: 'These tasks are declared in the profile config and cannot be replaced by an import: ' + configConflicts.join(', '),
+    });
+    return;
+  }
   const summary = { add: plan.add.length, replace: plan.replace.length, skip: plan.skip.length };
   if (body && body.dryRun) {
     sendJson(res, 200, {
@@ -202,6 +259,7 @@ async function handleTaskImport({ store, scheduler, req, res }) {
       strategy: plan.strategy,
       summary,
       codeExecuting: hasCodeExecutingTask(plan.add.concat(plan.replace)),
+      unknownChannels: droppedChannels,
     });
     return;
   }
@@ -210,7 +268,13 @@ async function handleTaskImport({ store, scheduler, req, res }) {
     sendJson(res, 500, { ok: false, error: applied.error });
     return;
   }
-  sendJson(res, 200, { ok: true, imported: applied.imported.length, summary, tasks: applied.imported });
+  sendJson(res, 200, {
+    ok: true,
+    imported: applied.imported.length,
+    summary,
+    unknownChannels: droppedChannels,
+    tasks: applied.imported,
+  });
 }
 
 /**
@@ -309,6 +373,10 @@ async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
     return true;
   }
   if (action === 'pause' || action === 'resume') {
+    if (store.get(id) && store.get(id).managedBy === MANAGED_BY_CONFIG) {
+      refuseConfigOwned(res, id);
+      return true;
+    }
     const task = action === 'pause' ? scheduler.pauseTask(id) : scheduler.resumeTask(id);
     if (!task) {
       sendJson(res, 404, NOT_FOUND);
@@ -318,10 +386,15 @@ async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
     return true;
   }
   if (action === 'toggle' || (!action && url.searchParams.get('action') === 'toggle')) {
-    if (!store.get(id)) {
+    const stored = store.get(id);
+    if (!stored) {
       sendJson(res, 404, NOT_FOUND);
       return true;
     }
+    if (stored.managedBy === MANAGED_BY_CONFIG) {
+      refuseConfigOwned(res, id);
+      return true;
+    }
     const task = scheduler.toggleTask(id);
     sendJson(res, 200, { ok: true, task });
     return true;
@@ -335,6 +408,10 @@ async function patchTask({ store, scheduler, req, res, id }) {
     sendJson(res, 404, NOT_FOUND);
     return;
   }
+  if (current.managedBy === MANAGED_BY_CONFIG) {
+    refuseConfigOwned(res, id);
+    return;
+  }
   const { body, error } = await readBody(req, res);
   if (error) return;
   const result = applyTaskPatch({
@@ -349,7 +426,11 @@ async function patchTask({ store, scheduler, req, res, id }) {
     const error = result.needsConfirmation
       ? `Switching a task to the ${normalizeTaskType(body.type)} type over HTTP requires the ${SCRIPT_CONFIRM_HEADER}: script header`
       : result.error;
-    sendJson(res, status, { ok: false, error });
+    sendJson(res, status, {
+      ok: false,
+      error,
+      ...(result.unknownChannels ? { unknownChannels: result.unknownChannels } : {}),
+    });
     return;
   }
   sendJson(res, 200, { ok: true, task: result.task });
@@ -357,6 +438,10 @@ async function patchTask({ store, scheduler, req, res, id }) {
 
 function deleteTask({ store, scheduler, res, id }) {
   const current = store.get(id);
+  if (current && current.managedBy === MANAGED_BY_CONFIG) {
+    refuseConfigOwned(res, id);
+    return;
+  }
   if (current) {
     scheduler.pauseTask(id);
     store.delete(id);
@@ -397,3 +482,52 @@ function mergeExecutionFields(current, body, parsed) {
     oneShot: Boolean((parsed && parsed.isOneShot) || (body && body.oneShot)),
   };
 }
+
+// --------------------------------------------------------- external surface
+
+/**
+ * Task operations for the token-guarded /dsh-cron/api/* prefix (#54). The shape
+ * is deliberately small — list, read, create or update, delete, manual run —
+ * and reuses the handlers above, so the confirmation gate for code-executing
+ * tasks and the config-owned refusals are the same code, not a second copy.
+ */
+export async function handleExternalTaskRequest({ store, scheduler, req, res, url }) {
+  const parts = url.pathname.split('/').filter(Boolean); // dsh-cron, api, tasks, :id?, :action?
+  const id = parts[3];
+  const action = parts[4];
+
+  if (!id) {
+    if (req.method === 'GET') {
+      const list = store
+        .list({ status: url.searchParams.get('status') || 'all', query: url.searchParams.get('query') || '' })
+        .map((task) => ({ ...task, running: scheduler.isRunning(task.id) }));
+      sendJson(res, 200, { ok: true, tasks: list });
+      return;
+    }
+    if (req.method === 'POST') {
+      await createOrUpdateTask({ store, scheduler, req, res });
+      return;
+    }
+    sendJson(res, 405, NOT_ALLOWED);
+    return;
+  }
+
+  if (req.method === 'POST') {
+    const handled = await handleItemPost({ store, scheduler, req, res, url, id, action });
+    if (handled) return;
+  }
+  if (req.method === 'GET' && !action) {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return;
+    }
+    sendJson(res, 200, { ok: true, task: { ...task, running: scheduler.isRunning(id) } });
+    return;
+  }
+  if (req.method === 'DELETE' && !action) {
+    deleteTask({ store, scheduler, res, id });
+    return;
+  }
+  sendJson(res, 405, NOT_ALLOWED);
+}

package/lib/channels.js

@@ -56,9 +56,13 @@ export function resolveChannels(task, settings = {}) {
  * reported explicitly — a silently dropped notification is worse than a
  * visible failure.
  */
+export function unknownChannelIds(list) {
+  if (!Array.isArray(list)) return [];
+  return list.filter((id) => !CHANNEL_IDS.includes(id));
+}
+
 export function unknownChannels(task) {
-  if (!Array.isArray(task.channels)) return [];
-  return task.channels.filter((id) => !CHANNEL_IDS.includes(id));
+  return unknownChannelIds(task && task.channels);
 }
 
 /** Failure/only-on-failure filtering, per channel. */

package/lib/client.js

@@ -108,6 +108,8 @@ window.__ModuleLoader__.load({
         'list.typeShell': 'Shell',
         'list.typeLlm': 'LLM',
         'list.oneShot': 'One-shot',
+        'list.configManaged': 'Config',
+        'list.configManagedHint': 'Declared in config.jobs in the profile config file; edit the file to change or remove it',
         'list.next': ' · next: {time}',
         'recs.title': 'Recommended tasks',
         'recs.hint': 'Ready-to-use recipes. Clicking one opens the form with its fields filled in — nothing is created until you save.',
@@ -229,6 +231,8 @@ window.__ModuleLoader__.load({
         'settings.channelTemplateLabel': 'Template for {channel}',
         'settings.botTokenRefLabel': 'Bot token credential name',
         'settings.botTokenRefPlaceholder': 'e.g. TELEGRAM_BOT_TOKEN',
+        'settings.apiTokenLabel': 'External API token',
+        'settings.apiTokenPlaceholder': 'Bearer token for /dsh-cron/api/* (empty = disabled)',
         'settings.discordLabel': 'Discord webhook URL',
         'settings.slackLabel': 'Slack webhook URL',
         'settings.ntfyUrlLabel': 'ntfy server URL',
@@ -373,6 +377,9 @@ window.__ModuleLoader__.load({
       { key: 'ntfyTokenRef', labelKey: 'settings.ntfyTokenRefLabel', group: 'secrets' },
       { key: 'pushplusTokenRef', labelKey: 'settings.pushplusTokenRefLabel', group: 'secrets' },
       { key: 'giteaTokenRef', labelKey: 'settings.giteaTokenRefLabel', group: 'secrets' },
+      // The external API is the one surface where a typed secret is the point:
+      // a CI job cannot present a credential reference (#54).
+      { key: 'apiToken', labelKey: 'settings.apiTokenLabel', placeholderKey: 'settings.apiTokenPlaceholder', group: 'secrets' },
       { key: 'discordWebhookUrl', labelKey: 'settings.discordLabel', group: 'channels' },
       { key: 'slackWebhookUrl', labelKey: 'settings.slackLabel', group: 'channels' },
       { key: 'ntfyUrl', labelKey: 'settings.ntfyUrlLabel', group: 'channels' },
@@ -656,6 +663,7 @@ window.__ModuleLoader__.load({
       .dsh-cron-stat-val { font-size: 18px; font-weight: 700; color: var(--dsw-alias-label-primary, #fff); }
       .dsh-cron-stat-lbl { font-size: 12px; color: var(--dsw-alias-label-secondary, #777); margin-top: 0; }
       .dsh-cron-oneshot-tag { display: inline-flex; align-items: center; font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--dsh-cron-accent); background: var(--dsh-cron-accent-bg); color: var(--dsh-cron-accent); font-weight: 500; }
+      .dsh-cron-config-tag { display: inline-flex; align-items: center; font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--dsw-alias-border-l2, #444); color: var(--dsw-alias-label-secondary, #ccc); font-weight: 500; }
       .dsh-cron-cost-tag { display: inline-flex; align-items: center; font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--dsh-cron-success); background: var(--dsh-cron-success-bg); color: var(--dsh-cron-success); font-weight: 500; }
       .dsh-cron-tokens-tag { display: inline-flex; align-items: center; font-size: 11px; padding: 2px 8px; border-radius: 999px; border: 1px solid var(--dsh-cron-info); background: var(--dsh-cron-info-bg); color: var(--dsh-cron-info); }
       .dsh-cron-checkbox-row { display: flex; align-items: center; gap: 8px; font-size: 13px; color: var(--dsw-alias-label-secondary, #ccc); cursor: pointer; user-select: none; }
@@ -805,6 +813,16 @@ window.__ModuleLoader__.load({
       if (status === 'timeout') return T_KEY(t, 'history.statusTimeout');
       return T_KEY(t, 'history.statusFailed');
     }
+
+    /**
+     * A config-declared task is owned by the profile config file (#50): the
+     * panel shows it, but editing, pausing or deleting it here would be undone
+     * at the next start, so the row keeps the source label instead of the
+     * actions that cannot stick.
+     */
+    function isConfigManaged(task) {
+      return Boolean(task) && task.managedBy === 'config';
+    }
     function T_KEY(t, key, vars) {
       return (typeof t === 'function' ? t : translate)(key, vars);
     }
@@ -1734,18 +1752,19 @@ window.__ModuleLoader__.load({
                     key: task.id,
                     className: 'dsh-cron-task-item',
                     'data-task-id': task.id,
-                    role: 'button',
-                    tabIndex: 0,
+                    role: isConfigManaged(task) ? undefined : 'button',
+                    tabIndex: isConfigManaged(task) ? undefined : 0,
                     'aria-label': task.title,
-                    onClick: () => openEditModal(task),
-                    onKeyDown: (e) => {
+                    style: isConfigManaged(task) ? { cursor: 'default' } : undefined,
+                    onClick: isConfigManaged(task) ? undefined : () => openEditModal(task),
+                    onKeyDown: isConfigManaged(task) ? undefined : (e) => {
                       if (e.key === 'Enter' || e.key === ' ') {
                         e.preventDefault();
                         openEditModal(task);
                       }
                     }
                   },
-                    React.createElement('button', {
+                    isConfigManaged(task) ? null : React.createElement('button', {
                       type: 'button',
                       className: 'dsh-cron-task-status-btn' + (task.running ? ' dsh-cron-pulse' : ''),
                       'data-active': task.status === 'active' ? 'true' : undefined,
@@ -1764,6 +1783,10 @@ window.__ModuleLoader__.load({
                         }, task.type === 'script' ? T_KEY(t, 'list.typeShell') : T_KEY(t, 'list.typeLlm')),
                         task.model ? React.createElement('span', { className: 'dsh-cron-task-model-tag' }, task.model.split('/').pop()) : null,
                         task.oneShot ? React.createElement('span', { className: 'dsh-cron-oneshot-tag' }, T_KEY(t, 'list.oneShot')) : null,
+                        isConfigManaged(task) ? React.createElement('span', {
+                          className: 'dsh-cron-config-tag',
+                          title: T_KEY(t, 'list.configManagedHint')
+                        }, T_KEY(t, 'list.configManaged')) : null,
                         task.totalCostUsd > 0 ? React.createElement('span', { className: 'dsh-cron-cost-tag' }, '$' + task.totalCostUsd.toFixed(4)) : null,
                         task.totalTokens > 0 ? React.createElement('span', { className: 'dsh-cron-tokens-tag' }, (task.totalTokens > 1000 ? Math.round(task.totalTokens / 1000) + 'k' : task.totalTokens) + ' tok') : null
                       ),
@@ -1789,28 +1812,28 @@ window.__ModuleLoader__.load({
                         title: T_KEY(t, 'actions.runNow'),
                         onClick: () => handleRunNow(task.id)
                       }, T_KEY(t, 'actions.runNowShort')),
-                      React.createElement('button', {
+                      isConfigManaged(task) ? null : React.createElement('button', {
                         type: 'button',
                         className: 'dsh-cron-icon-btn',
                         title: T_KEY(t, 'actions.edit'),
                         'aria-label': T_KEY(t, 'actions.edit'),
                         onClick: () => openEditModal(task)
                       }, React.createElement('span', svgProps(ICON_EDIT))),
-                      React.createElement('button', {
+                      isConfigManaged(task) ? null : React.createElement('button', {
                         type: 'button',
                         className: 'dsh-cron-icon-btn',
                         title: T_KEY(t, 'actions.tuneWithDsh'),
                         'aria-label': T_KEY(t, 'actions.tuneWithDsh'),
                         onClick: () => handleTuneWithDsh(task)
                       }, React.createElement('span', svgProps(ICON_TUNE))),
-                      React.createElement('button', {
+                      isConfigManaged(task) ? null : React.createElement('button', {
                         type: 'button',
                         className: 'dsh-cron-icon-btn',
                         title: T_KEY(t, 'actions.duplicate'),
                         'aria-label': T_KEY(t, 'actions.duplicate'),
                         onClick: () => handleDuplicate(task)
                       }, React.createElement('span', svgProps(ICON_COPY))),
-                      React.createElement('button', {
+                      isConfigManaged(task) ? null : React.createElement('button', {
                         type: 'button',
                         className: 'dsh-cron-icon-btn dsh-cron-danger',
                         title: T_KEY(t, 'actions.delete'),

package/lib/config-jobs.js

@@ -0,0 +1,206 @@
+/**
+ * Jobs declared in the profile config (#50, ADR-0001).
+ *
+ * The config file owns the jobs it declares: at startup every declared job is
+ * created or updated, and a job that disappears from the config is removed.
+ * Tasks created by a user through the UI, the REST API or an agent tool are
+ * never touched — when a declared id collides with one of them the entry is
+ * skipped and reported, because silently overwriting a user's task is worse
+ * than a visible conflict.
+ *
+ * Entries are validated one by one with a precise message, so one broken job
+ * cannot take the plugin down or stop the remaining jobs from syncing.
+ */
+
+import { normalizeTaskType, CODE_EXECUTING_TYPES } from './runtimes.js';
+import { parseScheduleExpression } from './scheduler.js';
+import { unknownChannelIds } from './channels.js';
+import { PATCHABLE_TASK_FIELDS, validateTaskType } from './task-transfer.js';
+import { pickPatchableFields } from './http-utils.js';
+
+/** Marker that makes a task owned by the config (#50). */
+export const MANAGED_BY_CONFIG = 'config';
+
+/**
+ * One message for every surface that refuses to change a config-owned task, so
+ * the panel, the REST routes, the tools and the external API all say the same
+ * thing about where the task really lives.
+ */
+export function configOwnedMessage(id) {
+  return 'Task "' + id + '" is declared in the profile config (config.jobs); change the config file instead';
+}
+
+/** True when a stored task is owned by the config file. */
+export function isConfigOwned(task) {
+  return Boolean(task) && task.managedBy === MANAGED_BY_CONFIG;
+}
+
+/**
+ * Fields an entry may pass through, minus the ones the sync handles itself:
+ * identity, the parsed schedule and the derived one-shot flag.
+ */
+const PASSTHROUGH_FIELDS = PATCHABLE_TASK_FIELDS.filter(
+  (key) => !['title', 'schedule', 'prompt', 'type', 'status', 'oneShot'].includes(key)
+);
+
+/**
+ * Task types whose payload is the prompt itself (see validateTaskType).
+ * ssh and docker are included because their dedicated fields only describe how
+ * to connect or which image to use — without a prompt the runner executes
+ * `true`, which reports success while doing nothing. http is excluded on
+ * purpose: it accepts the target in httpUrl.
+ */
+const PROMPT_TYPES = ['script', 'node', 'python', 'ssh', 'docker', 'llm', 'skill', 'workflow'];
+
+function reject(index, message) {
+  return { ok: false, error: 'config.jobs[' + index + ']: ' + message };
+}
+
+/**
+ * Validate one declared job and turn it into a task record. Returns
+ * `{ ok: false, error }` with the entry index so the operator can find it.
+ */
+export function buildConfigJob(entry, index = 0) {
+  if (!entry || typeof entry !== 'object') return reject(index, 'entry must be an object');
+
+  const id = String(entry.id || '').trim();
+  if (!id) return reject(index, 'id is required');
+  if (!String(entry.title || '').trim()) return reject(index, 'title is required');
+  if (!String(entry.schedule || '').trim()) return reject(index, 'schedule is required');
+
+  const unknown = unknownChannelIds(entry.channels);
+  if (unknown.length) return reject(index, 'unknown channel ids: ' + unknown.join(', '));
+
+  const type = normalizeTaskType(entry.type || 'llm');
+  // These types carry their payload in the prompt: a job declared without one
+  // would be created, armed and report success while doing nothing.
+  if (PROMPT_TYPES.includes(type) && !String(entry.prompt || '').trim()) {
+    return reject(index, type + ' jobs require a non-empty prompt (the command or instruction to run)');
+  }
+  let parsed;
+  try {
+    parsed = parseScheduleExpression(entry.schedule);
+  } catch (err) {
+    return reject(index, 'invalid schedule: ' + err.message);
+  }
+
+  const job = {
+    ...pickPatchableFields(entry, PASSTHROUGH_FIELDS),
+    id,
+    title: String(entry.title),
+    type,
+    status: entry.status === 'paused' ? 'paused' : 'active',
+    schedule: parsed.cronPattern || String(entry.schedule).trim(),
+    scheduleText: parsed.humanText,
+    oneShot: Boolean(parsed.isOneShot),
+    managedBy: MANAGED_BY_CONFIG,
+  };
+  if (entry.prompt !== undefined) job.prompt = String(entry.prompt);
+
+  const typeError = validateTaskType(type, job);
+  if (typeError) return reject(index, typeError);
+  return { ok: true, job };
+}
+
+/**
+ * Names of the config-owned fields in which the stored task differs from the
+ * declared job. An empty list means the stored task is already in sync.
+ */
+export function diffConfigJob(stored, declared) {
+  const changed = [];
+  for (const key of Object.keys(declared)) {
+    if (key === 'id' || key === 'managedBy') continue;
+    const next = declared[key];
+    const prev = stored ? stored[key] : undefined;
+    const same = Array.isArray(next)
+      ? Array.isArray(prev) && next.length === prev.length && next.every((value, i) => value === prev[i])
+      : next === prev;
+    if (!same) changed.push(key);
+  }
+  return changed;
+}
+
+/** Decide what the sync would create, update and remove. Pure, for tests. */
+export function planConfigSync(entries, existingTasks) {
+  const list = Array.isArray(entries) ? entries : [];
+  const existing = new Map((Array.isArray(existingTasks) ? existingTasks : []).map((task) => [task.id, task]));
+  const plan = { create: [], update: [], remove: [], skipped: [], warnings: [] };
+  const declaredIds = new Set();
+
+  list.forEach((entry, index) => {
+    // An entry keeps its id "declared" even when the rest of it is invalid:
+    // otherwise one typo in a schedule would look like "the job was removed
+    // from the config" and the sync would delete the working task.
+    const rawId = entry && typeof entry === 'object' && entry.id !== undefined ? String(entry.id).trim() : '';
+    if (rawId) declaredIds.add(rawId);
+
+    const built = buildConfigJob(entry, index);
+    if (!built.ok) {
+      plan.skipped.push({ index, error: built.error });
+      return;
+    }
+    const job = built.job;
+    declaredIds.add(job.id);
+
+    const stored = existing.get(job.id);
+    if (!stored) {
+      plan.create.push(job);
+    } else if (stored.managedBy !== MANAGED_BY_CONFIG) {
+      plan.skipped.push({
+        index,
+        id: job.id,
+        error: 'config.jobs[' + index + ']: a task with id "' + job.id + '" exists but is not managed by the config; it was left untouched',
+      });
+    } else {
+      const changed = diffConfigJob(stored, job);
+      if (changed.length) plan.update.push({ job, changed });
+    }
+
+    if (CODE_EXECUTING_TYPES.includes(job.type)) {
+      plan.warnings.push('job "' + job.id + '" executes code (' + job.type + '); the config file is its only source');
+    }
+  });
+
+  for (const task of existing.values()) {
+    if (task.managedBy === MANAGED_BY_CONFIG && !declaredIds.has(task.id)) plan.remove.push(task.id);
+  }
+  return plan;
+}
+
+/**
+ * Apply the plan: create, update and remove tasks, then arm or pause them.
+ * Never throws for a single bad entry — that entry is reported and skipped.
+ */
+export function applyConfigSync({ store, scheduler, entries, log = console }) {
+  const plan = planConfigSync(entries, store.list({ status: 'all' }));
+  for (const warning of plan.warnings) log.warn('[dsh-cron] config jobs: ' + warning);
+  for (const entry of plan.skipped) log.error('[dsh-cron] config jobs: skipped: ' + entry.error);
+
+  let created = 0;
+  let updated = 0;
+  let removed = 0;
+
+  for (const job of plan.create) {
+    const task = store.set({ ...job });
+    if (task.status === 'active') scheduler.scheduleTask(task);
+    created += 1;
+  }
+
+  for (const item of plan.update) {
+    const current = store.get(item.job.id);
+    const task = store.set({ ...current, ...item.job, id: item.job.id });
+    if (task.status === 'active') scheduler.scheduleTask(task);
+    else scheduler.pauseTask(task.id);
+    updated += 1;
+    log.log('[dsh-cron] config job "' + task.id + '" updated: ' + item.changed.join(', '));
+  }
+
+  for (const id of plan.remove) {
+    scheduler.pauseTask(id);
+    store.delete(id);
+    removed += 1;
+    log.log('[dsh-cron] config job "' + id + '" removed: it is no longer declared');
+  }
+
+  return { created, updated, removed, skipped: plan.skipped.length };
+}

package/lib/external-api.js

@@ -0,0 +1,74 @@
+/**
+ * External REST surface under /dsh-cron/api/* (#54, ADR-0001).
+ *
+ * Everything a browser panel needs stays on the local, cross-origin-protected
+ * routes; this prefix exists for CI and host-side automation, so it is the only
+ * surface guarded by a bearer token. The token lives in the plugin settings as
+ * a masked value: an unconfigured token disables the surface (503) instead of
+ * leaving it open, and a wrong token is answered with 401.
+ *
+ * The operations themselves are shared with the panel routes (lib/api.js), so
+ * the confirmation gate for code-executing tasks and the config-owned refusals
+ * apply here exactly as they do over HTTP from the UI.
+ */
+
+import { timingSafeEqual } from 'node:crypto';
+import { sendJson } from './http-utils.js';
+import { handleExternalTaskRequest } from './api.js';
+
+/** Settings key that holds the bearer token. */
+export const API_TOKEN_SETTING_KEY = 'apiToken';
+
+/** Route prefix owned by this surface. */
+export const EXTERNAL_API_PREFIX = '/dsh-cron/api';
+
+/**
+ * Constant-time token comparison. Length is compared first because
+ * timingSafeEqual throws on buffers of different sizes; a length mismatch is
+ * not a secret worth hiding for a fixed-length token.
+ */
+export function tokenMatches(expected, provided) {
+  if (!expected || !provided) return false;
+  const a = Buffer.from(String(expected), 'utf8');
+  const b = Buffer.from(String(provided), 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** Bearer token of a request, or an empty string when there is none. */
+export function readBearerToken(req) {
+  const header = String((req.headers && req.headers.authorization) || '');
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Guard the external prefix, then hand the request to the shared task
+ * operations. `getToken` is read per request so a settings change applies
+ * without a restart.
+ */
+export function createExternalApiHandler({ store, scheduler, getToken }) {
+  return async function handleExternalApi(req, res) {
+    const expected = typeof getToken === 'function' ? getToken() : '';
+    if (!expected) {
+      sendJson(res, 503, {
+        ok: false,
+        error: 'External API is disabled: set the "' + API_TOKEN_SETTING_KEY + '" setting to enable it',
+      });
+      return;
+    }
+    if (!tokenMatches(expected, readBearerToken(req))) {
+      sendJson(res, 401, { ok: false, error: 'Unauthorized' });
+      return;
+    }
+    const url = new URL(req.url, 'http://127.0.0.1');
+    // `url` must be inside the try: a malformed body (an unparseable schedule,
+    // for example) surfaces as a thrown error from the shared handlers, and an
+    // unhandled rejection here would answer nothing at all.
+    try {
+      await handleExternalTaskRequest({ store, scheduler, req, res, url });
+    } catch (err) {
+      sendJson(res, (err && err.statusCode) || 500, { ok: false, error: (err && err.message) || String(err) });
+    }
+  };
+}