@yemi33/minions 0.1.1993 → 0.1.1994

package/dashboard.js

@@ -8427,6 +8427,141 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return;
   }
 
+  // ── QA runs + artifact serving (W-mpeiwz6k0005bf34-b) ──────────────────────
+  // Lifecycle for QA validation runs lives in engine/qa-runs.js. These three
+  // handlers expose: list (with optional ?limit= + ?status= filters), single-
+  // record fetch, and a tightly-sandboxed artifact serving endpoint rooted at
+  // engine/qa-artifacts/.
+
+  // Extension → Content-Type for served artifacts. Anything not listed gets
+  // application/octet-stream (the SPA still renders unknown attachments via
+  // the artifact download link).
+  const _QA_ARTIFACT_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.log': 'text/plain; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+  };
+
+  function _qaArtifactContentType(filename) {
+    const ext = path.extname(filename || '').toLowerCase();
+    return _QA_ARTIFACT_MIME[ext] || 'application/octet-stream';
+  }
+
+  // Safe-segment validator for runId / file. URL segments must not contain
+  // path separators, traversal markers, null bytes, or look like an absolute
+  // path. Rejecting at the segment level (before any path.join) closes the
+  // traversal hole before resolution can normalize ".." away.
+  function _qaIsSafeSegment(s) {
+    if (typeof s !== 'string') return false;
+    if (!s || s.length > 255) return false;
+    if (s.includes('\0')) return false;
+    if (s.includes('/') || s.includes('\\')) return false;
+    if (s === '.' || s === '..') return false;
+    if (s.includes('..')) return false;
+    if (path.isAbsolute(s)) return false;
+    if (/^[a-zA-Z]:/.test(s)) return false;
+    return true;
+  }
+
+  function handleQaRunsList(req, res) {
+    try {
+      const qa = require('./engine/qa-runs');
+      const u = new URL(req.url, 'http://x');
+      const limitRaw = u.searchParams.get('limit');
+      const statusRaw = u.searchParams.get('status');
+      const opts = {};
+      if (limitRaw != null && limitRaw !== '') {
+        const n = Number(limitRaw);
+        if (!Number.isFinite(n) || n <= 0) {
+          return jsonReply(res, 400, { error: 'limit must be a positive number' }, req);
+        }
+        opts.limit = Math.floor(n);
+      }
+      if (statusRaw) {
+        if (!qa.isValidStatus(statusRaw)) {
+          return jsonReply(res, 400, {
+            error: `status must be one of ${Object.values(qa.QA_RUN_STATUS).join(', ')}`,
+          }, req);
+        }
+        opts.status = statusRaw;
+      }
+      const runs = qa.listRuns(opts);
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      return jsonReply(res, 200, { runs, generatedAt: new Date().toISOString() }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  function handleQaRunsById(req, res, match) {
+    try {
+      const qa = require('./engine/qa-runs');
+      const id = decodeURIComponent(match[1] || '');
+      if (!_qaIsSafeSegment(id)) {
+        return jsonReply(res, 400, { error: 'invalid run id' }, req);
+      }
+      const run = qa.getRun(id);
+      if (!run) return jsonReply(res, 404, { error: 'qa run not found' }, req);
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      return jsonReply(res, 200, { run }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  function handleQaArtifact(req, res, match) {
+    try {
+      const qa = require('./engine/qa-runs');
+      const runId = decodeURIComponent(match[1] || '');
+      const file = decodeURIComponent(match[2] || '');
+      // Per-segment validation rejects ../, absolute, and any embedded
+      // separator before path.join — 403 (traversal attempt) vs 404 (miss).
+      if (!_qaIsSafeSegment(runId) || !_qaIsSafeSegment(file)) {
+        return jsonReply(res, 403, { error: 'invalid artifact path (traversal attempt)' }, req);
+      }
+      const base = path.resolve(qa.qaArtifactsDir());
+      const target = path.resolve(base, runId, file);
+      // Belt-and-braces: ensure the resolved absolute path is still under
+      // base. Adding the trailing separator avoids the "/qa-artifacts2/"
+      // prefix-equality bug if a sibling directory ever shares the same
+      // leading characters.
+      const baseWithSep = base.endsWith(path.sep) ? base : base + path.sep;
+      if (target !== base && !target.startsWith(baseWithSep)) {
+        return jsonReply(res, 403, { error: 'invalid artifact path (escapes qa-artifacts root)' }, req);
+      }
+      let real;
+      try { real = fs.realpathSync(target); }
+      catch (e) {
+        if (e && e.code === 'ENOENT') return jsonReply(res, 404, { error: 'artifact not found' }, req);
+        throw e;
+      }
+      // Symlinks: realpath must still land under qa-artifacts (after resolving
+      // base symlinks too, so a legitimate symlinked base dir works).
+      const realBase = (() => { try { return fs.realpathSync(base); } catch { return base; } })();
+      const realBaseWithSep = realBase.endsWith(path.sep) ? realBase : realBase + path.sep;
+      if (real !== realBase && !real.startsWith(realBaseWithSep)) {
+        return jsonReply(res, 403, { error: 'artifact symlink points outside qa-artifacts root' }, req);
+      }
+      const stat = fs.statSync(real);
+      if (!stat.isFile()) return jsonReply(res, 404, { error: 'artifact not found' }, req);
+      res.setHeader('Content-Type', _qaArtifactContentType(file));
+      res.setHeader('Content-Length', String(stat.size));
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.statusCode = 200;
+      fs.createReadStream(real).pipe(res);
+      return;
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
   // ── Route Registry ──────────────────────────────────────────────────────────
   // Order matters: specific routes before general ones (e.g., /api/plans/approve before /api/plans/:file)
 
@@ -8497,6 +8632,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // 64KB initial tail, fs.watchFile poll for appends, auto-close when
     // the spec is removed from state.
     { method: 'GET', path: /^\/api\/managed-processes\/log-stream\/([^?]+)$/, template: '/api/managed-processes/log-stream/<name>', desc: 'SSE tail-and-stream of <log_path> for a managed spec (managed-spawn). Optional ?tail=N initial-tail-bytes (default 65536).', handler: handleManagedProcessesLogStream },
+    // QA runs + artifact serving (W-mpeiwz6k0005bf34-b). Run-record lifecycle
+    // lives in engine/qa-runs.js. Artifact serving is sandboxed to
+    // engine/qa-artifacts/ via per-segment validation + realpath check;
+    // traversal attempts return 403, missing files return 404.
+    { method: 'GET', path: '/api/qa/runs', desc: 'List QA validation runs (newest first). Optional ?limit=N and ?status=pending|running|passed|failed|errored filters.', handler: handleQaRunsList },
+    { method: 'GET', path: /^\/api\/qa\/runs\/([^/?]+)$/, template: '/api/qa/runs/<id>', desc: 'Fetch a single QA run record by id.', handler: handleQaRunsById },
+    { method: 'GET', path: /^\/api\/qa\/artifacts\/([^/?]+)\/([^?]+)$/, template: '/api/qa/artifacts/<runId>/<file>', desc: 'Serve a QA artifact file (image/video/log). Sandboxed to engine/qa-artifacts/; rejects path traversal with 403.', handler: handleQaArtifact },
     { method: 'GET', path: '/api/hot-reload', desc: 'SSE stream for dashboard hot-reload notifications', handler: (req, res) => {
       res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' });
       res.write('data: connected\n\n');

package/engine/cooldown.js

@@ -44,6 +44,8 @@ function loadCooldowns() {
   if (!saved) return;
   const now = Date.now();
   for (const [k, v] of Object.entries(saved)) {
+    // Skip malformed entries (null, primitives, missing timestamp)
+    if (!v || typeof v !== 'object' || typeof v.timestamp !== 'number') continue;
     // Prune entries older than 24 hours
     if (now - v.timestamp < 24 * 60 * 60 * 1000) {
       dispatchCooldowns.set(k, v);

package/engine/qa-runs.js

@@ -0,0 +1,278 @@
+/**
+ * engine/qa-runs.js — Lifecycle + persistence for QA validation runs.
+ *
+ * One run record represents a single dispatch of a validation runbook against
+ * a managed target. Records carry status, timing, work-item linkage, and an
+ * artifacts array (screenshots, logs, videos captured during the run).
+ *
+ * State file: engine/qa-runs.json (single file, all runs across all projects).
+ * Artifacts live on disk under engine/qa-artifacts/<runId>/ — the run record
+ * stores relative paths (`type`, `path`, `label`, `capturedAt`), and the
+ * dashboard exposes them through GET /api/qa/artifacts/<runId>/<file>.
+ *
+ * Concurrency: every mutation goes through mutateJsonFileLocked per
+ * CLAUDE.md best-practice; callbacks are synchronous and never await.
+ *
+ * Status state machine:
+ *
+ *   pending ──▶ running ──▶ passed
+ *                       ╲──▶ failed
+ *                       ╲──▶ errored
+ *
+ * Illegal transitions throw with a descriptive error. Terminal statuses
+ * (passed / failed / errored) cannot transition further.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const { mutateJsonFileLocked, uid, ts, log } = shared;
+
+const QA_RUN_STATUS = Object.freeze({
+  PENDING: 'pending',
+  RUNNING: 'running',
+  PASSED: 'passed',
+  FAILED: 'failed',
+  ERRORED: 'errored',
+});
+
+const TERMINAL_STATUSES = new Set([
+  QA_RUN_STATUS.PASSED,
+  QA_RUN_STATUS.FAILED,
+  QA_RUN_STATUS.ERRORED,
+]);
+
+// Allowed forward transitions. Anything not enumerated here is rejected.
+const ALLOWED_TRANSITIONS = {
+  [QA_RUN_STATUS.PENDING]: new Set([QA_RUN_STATUS.RUNNING]),
+  [QA_RUN_STATUS.RUNNING]: new Set([
+    QA_RUN_STATUS.PASSED,
+    QA_RUN_STATUS.FAILED,
+    QA_RUN_STATUS.ERRORED,
+  ]),
+  [QA_RUN_STATUS.PASSED]: new Set(),
+  [QA_RUN_STATUS.FAILED]: new Set(),
+  [QA_RUN_STATUS.ERRORED]: new Set(),
+};
+
+// Dynamic paths — respect MINIONS_TEST_DIR for test isolation.
+function qaRunsPath() {
+  return path.join(shared.MINIONS_DIR, 'engine', 'qa-runs.json');
+}
+
+function qaArtifactsDir() {
+  return path.join(shared.MINIONS_DIR, 'engine', 'qa-artifacts');
+}
+
+function qaArtifactsDirForRun(runId) {
+  return path.join(qaArtifactsDir(), runId);
+}
+
+function isValidStatus(status) {
+  return Object.values(QA_RUN_STATUS).includes(status);
+}
+
+function validateTransition(from, to) {
+  if (!isValidStatus(from)) throw new Error(`qa-runs: invalid source status "${from}"`);
+  if (!isValidStatus(to)) throw new Error(`qa-runs: invalid target status "${to}"`);
+  const allowed = ALLOWED_TRANSITIONS[from];
+  if (!allowed.has(to)) {
+    throw new Error(`qa-runs: illegal status transition ${from} -> ${to}`);
+  }
+}
+
+function normalizeArtifact(a) {
+  if (!a || typeof a !== 'object') return null;
+  const type = typeof a.type === 'string' ? a.type : '';
+  const p = typeof a.path === 'string' ? a.path : '';
+  if (!type || !p) return null;
+  return {
+    type,
+    path: p,
+    label: typeof a.label === 'string' ? a.label : '',
+    capturedAt: typeof a.capturedAt === 'string' && a.capturedAt ? a.capturedAt : ts(),
+  };
+}
+
+/**
+ * Create a new run record in 'pending' status. Also pre-creates the per-run
+ * artifact directory so the agent can drop files into it.
+ *
+ * @param {object} opts
+ * @param {string} opts.runbookId - id of the runbook being executed
+ * @param {string} opts.targetName - managed-spawn target name being validated
+ * @param {string} [opts.project] - project name (optional)
+ * @param {string} [opts.workItemId] - originating work-item id (optional)
+ * @returns {object} the created run record
+ */
+function createRun({ runbookId, targetName, project, workItemId } = {}) {
+  if (!runbookId || typeof runbookId !== 'string') throw new Error('qa-runs: runbookId is required');
+  if (!targetName || typeof targetName !== 'string') throw new Error('qa-runs: targetName is required');
+
+  const run = {
+    id: 'qarun-' + uid(),
+    runbookId,
+    targetName,
+    project: project || null,
+    workItemId: workItemId || null,
+    status: QA_RUN_STATUS.PENDING,
+    startedAt: null,
+    completedAt: null,
+    artifacts: [],
+    summary: null,
+    createdAt: ts(),
+  };
+
+  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+    if (!Array.isArray(runs)) runs = [];
+    runs.push(run);
+    return runs;
+  }, { defaultValue: [] });
+
+  // Pre-create the artifact directory outside the lock — directory creation
+  // is idempotent and slow file I/O must never run while holding the lock.
+  try { fs.mkdirSync(qaArtifactsDirForRun(run.id), { recursive: true }); } catch (e) {
+    log('warn', `qa-runs: mkdir artifacts dir failed for ${run.id}: ${e.message}`);
+  }
+
+  return run;
+}
+
+/**
+ * Transition pending -> running. Stamps startedAt. Throws on illegal source state.
+ * @param {string} id
+ * @returns {object} updated run
+ */
+function markRunning(id) {
+  if (!id) throw new Error('qa-runs: id is required');
+  let captured = null;
+  let transitionError = null;
+  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+    if (!Array.isArray(runs)) runs = [];
+    const run = runs.find(r => r && r.id === id);
+    if (!run) { transitionError = new Error(`qa-runs: run not found: ${id}`); return runs; }
+    try { validateTransition(run.status, QA_RUN_STATUS.RUNNING); }
+    catch (e) { transitionError = e; return runs; }
+    run.status = QA_RUN_STATUS.RUNNING;
+    run.startedAt = ts();
+    captured = run;
+    return runs;
+  }, { defaultValue: [] });
+  if (transitionError) throw transitionError;
+  return captured;
+}
+
+/**
+ * Transition running -> passed|failed|errored. Stamps completedAt, records
+ * summary, appends artifacts. Throws on illegal source state.
+ *
+ * @param {string} id
+ * @param {object} opts
+ * @param {string} opts.status - 'passed' | 'failed' | 'errored'
+ * @param {string} [opts.summary] - human-readable summary
+ * @param {Array<object>} [opts.artifacts] - artifact records {type, path, label?, capturedAt?}
+ * @returns {object} updated run
+ */
+function completeRun(id, { status, summary, artifacts } = {}) {
+  if (!id) throw new Error('qa-runs: id is required');
+  if (!TERMINAL_STATUSES.has(status)) {
+    throw new Error(`qa-runs: completeRun status must be one of ${[...TERMINAL_STATUSES].join(', ')}`);
+  }
+  const normalized = Array.isArray(artifacts)
+    ? artifacts.map(normalizeArtifact).filter(Boolean)
+    : [];
+
+  let captured = null;
+  let transitionError = null;
+  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+    if (!Array.isArray(runs)) runs = [];
+    const run = runs.find(r => r && r.id === id);
+    if (!run) { transitionError = new Error(`qa-runs: run not found: ${id}`); return runs; }
+    try { validateTransition(run.status, status); }
+    catch (e) { transitionError = e; return runs; }
+    run.status = status;
+    run.completedAt = ts();
+    if (typeof summary === 'string') run.summary = summary;
+    if (normalized.length) {
+      if (!Array.isArray(run.artifacts)) run.artifacts = [];
+      run.artifacts.push(...normalized);
+    }
+    captured = run;
+    return runs;
+  }, { defaultValue: [] });
+  if (transitionError) throw transitionError;
+  return captured;
+}
+
+/**
+ * Lookup a single run by id.
+ * @param {string} id
+ * @returns {object|null}
+ */
+function getRun(id) {
+  if (!id) return null;
+  const runs = shared.safeJsonArr(qaRunsPath());
+  const run = runs.find(r => r && r.id === id);
+  return run || null;
+}
+
+/**
+ * List runs, newest first, optionally filtered by status, capped by limit.
+ * @param {object} [opts]
+ * @param {number} [opts.limit] - max records to return (no cap when omitted)
+ * @param {string} [opts.status] - filter by status
+ * @returns {Array<object>}
+ */
+function listRuns({ limit, status } = {}) {
+  let runs = shared.safeJsonArr(qaRunsPath());
+  if (!Array.isArray(runs)) return [];
+  if (status) {
+    if (!isValidStatus(status)) return [];
+    runs = runs.filter(r => r && r.status === status);
+  }
+  // Newest first by createdAt (fallback to id for ties — uid() is monotonic).
+  runs = runs.slice().sort((a, b) => {
+    const ac = (a && a.createdAt) || '';
+    const bc = (b && b.createdAt) || '';
+    if (ac === bc) return ((b && b.id) || '').localeCompare((a && a.id) || '');
+    return ac < bc ? 1 : -1;
+  });
+  const n = Number(limit);
+  if (Number.isFinite(n) && n > 0) runs = runs.slice(0, Math.floor(n));
+  return runs;
+}
+
+/**
+ * All runs linked to a work item, newest first.
+ * @param {string} wi - work-item id
+ * @returns {Array<object>}
+ */
+function getRunsForWorkItem(wi) {
+  if (!wi) return [];
+  const runs = shared.safeJsonArr(qaRunsPath());
+  return runs
+    .filter(r => r && r.workItemId === wi)
+    .sort((a, b) => {
+      const ac = a.createdAt || '';
+      const bc = b.createdAt || '';
+      return ac < bc ? 1 : -1;
+    });
+}
+
+module.exports = {
+  QA_RUN_STATUS,
+  TERMINAL_STATUSES,
+  ALLOWED_TRANSITIONS,
+  qaRunsPath,
+  qaArtifactsDir,
+  qaArtifactsDirForRun,
+  createRun,
+  markRunning,
+  completeRun,
+  getRun,
+  listRuns,
+  getRunsForWorkItem,
+  // Exposed for tests:
+  validateTransition,
+  isValidStatus,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1993",
+  "version": "0.1.1994",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"