@goodandready/dsh-cron 0.2.51 → 0.3.0

package/lib/api.js

@@ -1,3 +1,4 @@
+import { approvalManager } from './approval.js';
 import { sanitizeValidators } from './validators.js';
 /**
  * REST surface of the plugin: the /dsh-cron/tasks and /dsh-cron/action route
@@ -371,6 +372,65 @@ async function handleItemPost({ store, scheduler, req, res, url, id, action }) {
     sendJson(res, 200, { ok: true, delivery, run });
     return true;
   }
+  if (action === 'approve' || action === 'reject') {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return true;
+    }
+    const body = await readBodyJson(req).catch(() => ({}));
+    const proposalId = body.proposalId || url.searchParams.get('proposalId');
+    const proposal = proposalId
+      ? approvalManager.getProposal(proposalId)
+      : approvalManager.getPendingProposalForTask(id);
+
+    if (!proposal) {
+      sendJson(res, 404, { ok: false, error: 'No pending approval proposal found for this task' });
+      return true;
+    }
+
+    const decision = action === 'approve' ? 'approve' : 'reject';
+    const result = approvalManager.decide(proposal.id, decision, {
+      decidedBy: body.decidedBy || 'web-user',
+      reason: body.reason || '',
+    });
+
+    if (!result.ok) {
+      sendJson(res, 400, result);
+      return true;
+    }
+
+    if (decision === 'approve') {
+      scheduler.runTask(id, { approvedBy: body.decidedBy || 'web-user' }).catch(() => {});
+    }
+
+    sendJson(res, 200, { ok: true, proposal: result.proposal });
+    return true;
+  }
+  if (action === 'resolve-uncertain') {
+    const task = store.get(id);
+    if (!task) {
+      sendJson(res, 404, NOT_FOUND);
+      return true;
+    }
+    const body = await readBody(req).then(b => JSON.parse(b || '{}')).catch(() => ({}));
+    const runId = body.runId || url.searchParams.get('runId');
+    if (!runId) {
+      sendJson(res, 400, { ok: false, error: 'runId is required' });
+      return true;
+    }
+    const result = store.durableJournal.resolveUncertain(id, runId, {
+      decision: body.decision || 'mark_failed',
+      note: body.note || '',
+      resolvedBy: body.resolvedBy || 'user',
+    });
+    if (!result.ok) {
+      sendJson(res, 400, result);
+      return true;
+    }
+    sendJson(res, 200, result);
+    return true;
+  }
   if (action === 'run') {
     if (!store.get(id)) {
       sendJson(res, 404, NOT_FOUND);

package/lib/approval.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { logger } from './logger.js';
+
+/**
+ * Human-in-the-Loop Action Approval Engine (#318).
+ * Manages action approval proposals before execution, ensuring
+ * no dangerous side effects execute without authorized human confirmation.
+ */
+
+export const APPROVAL_STATES = {
+  PENDING: 'pending',
+  APPROVED: 'approved',
+  REJECTED: 'rejected',
+  EXPIRED: 'expired',
+  CANCELLED: 'cancelled',
+};
+
+/**
+ * Clean proposal object for storage and API responses.
+ */
+export function sanitizeProposal(proposal) {
+  if (!proposal || typeof proposal !== 'object') return null;
+  return {
+    id: String(proposal.id || randomUUID()),
+    taskId: String(proposal.taskId || ''),
+    runId: proposal.runId ? String(proposal.runId) : null,
+    actionType: String(proposal.actionType || 'execute'),
+    summary: String(proposal.summary || ''),
+    details: proposal.details && typeof proposal.details === 'object' ? proposal.details : {},
+    requestedAt: Number(proposal.requestedAt) || Date.now(),
+    expiresAt: Number(proposal.expiresAt) || (Date.now() + 3600000), // Default 1 hour
+    state: Object.values(APPROVAL_STATES).includes(proposal.state) ? proposal.state : APPROVAL_STATES.PENDING,
+    decidedAt: proposal.decidedAt ? Number(proposal.decidedAt) : null,
+    decidedBy: proposal.decidedBy ? String(proposal.decidedBy) : null,
+    reason: proposal.reason ? String(proposal.reason) : null,
+  };
+}
+
+/**
+ * In-memory / persistent registry for task proposals.
+ */
+export class ApprovalManager {
+  constructor() {
+    this.proposals = new Map();
+  }
+
+  /**
+   * Create a new pending approval proposal for a task.
+   */
+  createProposal(taskId, runId, { actionType = 'execute', summary = '', details = {}, timeoutMs = 3600000 } = {}) {
+    // If an existing pending proposal exists for this task, invalidate it as superseded
+    for (const [id, prop] of this.proposals.entries()) {
+      if (prop.taskId === taskId && prop.state === APPROVAL_STATES.PENDING) {
+        prop.state = APPROVAL_STATES.CANCELLED;
+        prop.decidedAt = Date.now();
+        prop.reason = 'Superseded by newer proposal';
+      }
+    }
+
+    const proposal = sanitizeProposal({
+      id: 'appr_' + randomUUID().replace(/-/g, '').slice(0, 12),
+      taskId,
+      runId,
+      actionType,
+      summary,
+      details,
+      requestedAt: Date.now(),
+      expiresAt: Date.now() + (Number(timeoutMs) > 0 ? Number(timeoutMs) : 3600000),
+      state: APPROVAL_STATES.PENDING,
+    });
+
+    this.proposals.set(proposal.id, proposal);
+    logger.info(`[dsh-cron] created approval proposal "${proposal.id}" for task "${taskId}": ${summary}`);
+    return proposal;
+  }
+
+  getProposal(proposalId) {
+    const prop = this.proposals.get(proposalId);
+    if (!prop) return null;
+    // Check expiration on read
+    if (prop.state === APPROVAL_STATES.PENDING && Date.now() > prop.expiresAt) {
+      prop.state = APPROVAL_STATES.EXPIRED;
+      prop.decidedAt = Date.now();
+      prop.reason = 'Approval expired';
+    }
+    return prop;
+  }
+
+  getPendingProposalForTask(taskId) {
+    for (const prop of this.proposals.values()) {
+      if (prop.taskId === taskId && prop.state === APPROVAL_STATES.PENDING) {
+        if (Date.now() > prop.expiresAt) {
+          prop.state = APPROVAL_STATES.EXPIRED;
+          prop.decidedAt = Date.now();
+          prop.reason = 'Approval expired';
+          continue;
+        }
+        return prop;
+      }
+    }
+    return null;
+  }
+
+  listProposals({ taskId = null, state = null } = {}) {
+    const list = [];
+    const now = Date.now();
+    for (const prop of this.proposals.values()) {
+      if (prop.state === APPROVAL_STATES.PENDING && now > prop.expiresAt) {
+        prop.state = APPROVAL_STATES.EXPIRED;
+        prop.decidedAt = now;
+        prop.reason = 'Approval expired';
+      }
+      if (taskId && prop.taskId !== taskId) continue;
+      if (state && prop.state !== state) continue;
+      list.push({ ...prop });
+    }
+    return list.sort((a, b) => b.requestedAt - a.requestedAt);
+  }
+
+  /**
+   * Decide on a proposal (approve or reject) with replay and double-click protection.
+   */
+  decide(proposalId, decision, { decidedBy = 'user', reason = '' } = {}) {
+    const prop = this.getProposal(proposalId);
+    if (!prop) {
+      return { ok: false, error: 'Proposal not found' };
+    }
+    if (prop.state !== APPROVAL_STATES.PENDING) {
+      return { ok: false, error: `Proposal already resolved with state: ${prop.state}`, proposal: prop };
+    }
+
+    const state = decision === 'approve' ? APPROVAL_STATES.APPROVED : APPROVAL_STATES.REJECTED;
+    prop.state = state;
+    prop.decidedAt = Date.now();
+    prop.decidedBy = decidedBy;
+    prop.reason = reason;
+
+    logger.info(`[dsh-cron] proposal "${proposalId}" ${state} by ${decidedBy}${reason ? ': ' + reason : ''}`);
+    return { ok: true, proposal: prop };
+  }
+}
+
+export const approvalManager = new ApprovalManager();

package/lib/artifacts.js

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const SAFE_MIME_TYPES = {
+  '.csv': 'text/csv; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.log': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+};
+
+export class ArtifactManager {
+  constructor(baseDir) {
+    this.baseDir = baseDir || path.join(process.cwd(), 'artifacts');
+    this.maxArtifactBytes = 10 * 1024 * 1024; // 10 MiB per artifact
+    this.defaultRetentionDays = 7;
+    this.maxTotalStorageBytes = 50 * 1024 * 1024; // 50 MiB total quota
+  }
+
+  ensureDir() {
+    if (!fs.existsSync(this.baseDir)) {
+      fs.mkdirSync(this.baseDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Sanitizes a requested filename to prevent path traversal (#321)
+   */
+  sanitizeFilename(name) {
+    if (!name || typeof name !== 'string') return 'artifact.txt';
+    const clean = path.basename(name).replace(/[\0\r\n\\\/]/g, '_');
+    return clean || 'artifact.txt';
+  }
+
+  getFilePath(artifactId, filename) {
+    if (!filename || filename.includes('..') || path.isAbsolute(filename)) {
+      throw new Error('Path traversal attempt detected in artifact storage');
+    }
+    const safeName = this.sanitizeFilename(filename);
+    const target = path.resolve(this.baseDir, `${artifactId}_${safeName}`);
+    // Security check: ensure path stays strictly within baseDir
+    if (!target.startsWith(path.resolve(this.baseDir) + path.sep)) {
+      throw new Error('Path traversal attempt detected in artifact storage');
+    }
+    return target;
+  }
+
+  /**
+   * Resolves safe MIME type for download/preview
+   */
+  resolveMimeType(filename) {
+    const ext = path.extname(filename).toLowerCase();
+    // Neutralize dangerous web formats to prevent XSS / script execution
+    if (ext === '.html' || ext === '.htm' || ext === '.svg' || ext === '.js') {
+      return 'text/plain; charset=utf-8';
+    }
+    return SAFE_MIME_TYPES[ext] || 'application/octet-stream';
+  }
+
+  /**
+   * Saves a new artifact file bound to a run (#321)
+   */
+  saveArtifact(runId, taskId, filename, contentBuffer) {
+    this.ensureDir();
+    const buf = Buffer.isBuffer(contentBuffer) ? contentBuffer : Buffer.from(contentBuffer || '', 'utf8');
+
+    if (buf.length > this.maxArtifactBytes) {
+      throw new Error(`Artifact size (${buf.length} bytes) exceeds limit of ${this.maxArtifactBytes} bytes`);
+    }
+
+    const artifactId = 'art_' + randomUUID().replace(/-/g, '').slice(0, 16);
+    const safeName = this.sanitizeFilename(filename);
+    const filePath = this.getFilePath(artifactId, safeName);
+
+    fs.writeFileSync(filePath, buf);
+
+    const sha256 = createHash('sha256').update(buf).digest('hex');
+    const mimeType = this.resolveMimeType(safeName);
+
+    return {
+      id: artifactId,
+      name: safeName,
+      sizeBytes: buf.length,
+      mimeType,
+      sha256,
+      runId,
+      taskId,
+      createdAt: Date.now(),
+      status: 'available',
+    };
+  }
+
+  /**
+   * Reads an artifact file buffer
+   */
+  readArtifact(artifactId, filename) {
+    const filePath = this.getFilePath(artifactId, filename);
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    return fs.readFileSync(filePath);
+  }
+
+  /**
+   * Generates a safe preview of the artifact content (first 64 KiB)
+   */
+  generatePreview(artifactId, filename) {
+    const buf = this.readArtifact(artifactId, filename);
+    if (!buf) return { ok: false, error: 'Artifact file not found on disk' };
+
+    const ext = path.extname(filename).toLowerCase();
+    const isText = ['.txt', '.csv', '.json', '.log', '.md'].includes(ext);
+
+    if (isText) {
+      const slice = buf.subarray(0, 64 * 1024);
+      return {
+        ok: true,
+        kind: 'text',
+        mimeType: this.resolveMimeType(filename),
+        content: slice.toString('utf8'),
+        truncated: buf.length > slice.length,
+        sizeBytes: buf.length,
+      };
+    }
+
+    return {
+      ok: true,
+      kind: 'binary',
+      mimeType: this.resolveMimeType(filename),
+      sizeBytes: buf.length,
+      preview: `[Binary file: ${filename} (${buf.length} bytes)]`,
+    };
+  }
+
+  /**
+   * Cleans up expired artifacts and enforces size quotas (#321)
+   */
+  cleanupArtifacts(store, { retentionDays = this.defaultRetentionDays, maxTotalBytes = this.maxTotalStorageBytes } = {}) {
+    if (!fs.existsSync(this.baseDir)) return { removedCount: 0, freedBytes: 0 };
+
+    const cutoff = Date.now() - retentionDays * 86400000;
+    let files = fs.readdirSync(this.baseDir);
+    let totalBytes = 0;
+    const fileStats = [];
+
+    for (const f of files) {
+      const p = path.join(this.baseDir, f);
+      try {
+        const stat = fs.statSync(p);
+        totalBytes += stat.size;
+        fileStats.push({ path: p, filename: f, mtime: stat.mtimeMs, size: stat.size });
+      } catch (e) {
+        // file unlinked concurrently
+      }
+    }
+
+    let removedCount = 0;
+    let freedBytes = 0;
+
+    // 1. Remove files older than retentionDays
+    for (const item of fileStats) {
+      if (item.mtime < cutoff) {
+        try {
+          fs.unlinkSync(item.path);
+          removedCount++;
+          freedBytes += item.size;
+          totalBytes -= item.size;
+        } catch (e) {
+          void e;
+        }
+      }
+    }
+
+    // 2. Enforce quota: remove oldest files if totalBytes > maxTotalBytes
+    if (totalBytes > maxTotalBytes) {
+      fileStats.sort((a, b) => a.mtime - b.mtime);
+      for (const item of fileStats) {
+        if (totalBytes <= maxTotalBytes) break;
+        if (fs.existsSync(item.path)) {
+          try {
+            fs.unlinkSync(item.path);
+            removedCount++;
+            freedBytes += item.size;
+            totalBytes -= item.size;
+          } catch (e) {
+          void e;
+        }
+        }
+      }
+    }
+
+    return { removedCount, freedBytes };
+  }
+}

package/lib/chain-checkpoints.js

@@ -0,0 +1,125 @@
+/**
+ * Chain Checkpoint and Step Replay Manager (#319)
+ */
+
+export class ChainCheckpointManager {
+  constructor(store) {
+    this.store = store;
+    this.activeRetries = new Set();
+  }
+
+  /**
+   * Records a snapshot of a completed or failed chain step
+   */
+  recordStepSnapshot(chainRunId, stepTaskId, snapshot) {
+    if (!chainRunId || !stepTaskId) return;
+    this.store.chainCheckpoints = this.store.chainCheckpoints || {};
+    this.store.chainCheckpoints[chainRunId] = this.store.chainCheckpoints[chainRunId] || [];
+
+    const list = this.store.chainCheckpoints[chainRunId];
+    const existingIndex = list.findIndex((s) => s.stepTaskId === stepTaskId);
+
+    const record = {
+      chainRunId,
+      stepTaskId,
+      status: snapshot.status || 'completed',
+      input: snapshot.input || {},
+      output: snapshot.output || '',
+      at: Date.now(),
+      durationMs: snapshot.durationMs || 0,
+      retryCount: (existingIndex >= 0 ? (list[existingIndex].retryCount || 0) + 1 : 0),
+    };
+
+    if (existingIndex >= 0) {
+      list[existingIndex] = record;
+    } else {
+      list.push(record);
+    }
+
+    this.store.scheduleSave(50);
+    return record;
+  }
+
+  /**
+   * Retrieves all step snapshots for a given chain run
+   */
+  getChainSnapshots(chainRunId) {
+    if (!chainRunId || !this.store.chainCheckpoints) return [];
+    return this.store.chainCheckpoints[chainRunId] || [];
+  }
+
+  /**
+   * Checks whether a step can be retried in a chain run
+   */
+  canRetryFromStep(chainRunId, stepTaskId) {
+    if (!chainRunId || !stepTaskId) return { ok: false, error: 'Missing chainRunId or stepTaskId' };
+
+    const lockKey = `${chainRunId}:${stepTaskId}`;
+    if (this.activeRetries.has(lockKey)) {
+      return { ok: false, error: 'Retry already in progress for this step' };
+    }
+
+    const snapshots = this.getChainSnapshots(chainRunId);
+    const stepSnapshot = snapshots.find((s) => s.stepTaskId === stepTaskId);
+    if (!stepSnapshot) {
+      return { ok: false, error: `No checkpoint found for step "${stepTaskId}" in chain "${chainRunId}"` };
+    }
+
+    if (stepSnapshot.status === 'success' || stepSnapshot.status === 'completed') {
+      return { ok: false, error: 'Step already completed successfully; cannot retry a successful step' };
+    }
+
+    const task = this.store.get(stepTaskId);
+    if (!task) {
+      return { ok: false, error: `Task "${stepTaskId}" was deleted or no longer exists` };
+    }
+
+    return { ok: true, task, stepSnapshot };
+  }
+
+  /**
+   * Retries chain execution from the specified failed step (#319)
+   * Reuses upstream outputs without re-executing successful upstream steps.
+   */
+  async retryChainFromStep(scheduler, chainRunId, stepTaskId) {
+    const check = this.canRetryFromStep(chainRunId, stepTaskId);
+    if (!check.ok) return check;
+
+    const lockKey = `${chainRunId}:${stepTaskId}`;
+    this.activeRetries.add(lockKey);
+
+    try {
+      const snapshots = this.getChainSnapshots(chainRunId);
+      // Find the nearest successful preceding step snapshot
+      const stepIndex = snapshots.findIndex((s) => s.stepTaskId === stepTaskId);
+      let prevSnapshot = null;
+      for (let i = stepIndex - 1; i >= 0; i--) {
+        if (snapshots[i].status === 'success' || snapshots[i].status === 'completed') {
+          prevSnapshot = snapshots[i];
+          break;
+        }
+      }
+
+      const prevOutput = prevSnapshot ? prevSnapshot.output : '';
+      const prevTaskId = prevSnapshot ? prevSnapshot.stepTaskId : '';
+
+      // Execute only the failed step, passing reconstructed chain context
+      const runFn = (scheduler.runTask || scheduler.runNow).bind(scheduler);
+      const res = await runFn(stepTaskId, {
+        chainRunId,
+        chainPrevOutput: prevOutput,
+        chainPrevTaskId: prevTaskId,
+        isRetry: true,
+      });
+
+      return {
+        ok: true,
+        chainRunId,
+        stepTaskId,
+        result: res,
+      };
+    } finally {
+      this.activeRetries.delete(lockKey);
+    }
+  }
+}