@yemi33/minions 0.1.1901 → 0.1.1903

package/engine/watch-actions.js

@@ -33,6 +33,12 @@ const {
   WATCH_ACTION_TYPE, WI_STATUS, WORK_TYPE, DONE_STATUSES, PLAN_STATUS,
   log, ts, uid, mutateWorkItems, mutateJsonFileLocked, projectWorkItemsPath,
 } = shared;
+// P-w7c5d8b3 — Phase 3.2: optional guard expressions on action steps.
+// safe-expr.evaluate() never throws and returns Boolean(...) on success or
+// `false` on parse/eval errors (with a `[safe-expr]` warn). That contract
+// is what keeps the "invalid expression skips + warns" acceptance criterion
+// a one-liner here — we trust safe-expr to do the logging.
+const safeExpr = require('./safe-expr');
 
 // ── Action registry ──────────────────────────────────────────────────────────
 
@@ -78,16 +84,20 @@ function listActionTypes() {
  * Substitute {{var}} placeholders in `value` with values from `ctx`.
  * Operates on strings; recurses one level into plain objects/arrays so action
  * params like { headers: { 'X-Foo': '{{prNumber}}' } } work transparently.
- * Unknown vars are left as `{{var}}` so callers can detect them downstream.
+ *
+ * Supports dotted paths so chain step N can reference earlier results, e.g.
+ * `{{steps.0.result.dispatchedItemId}}` or `{{tags.1}}`. Each segment may be
+ * a property name or a numeric array index. Lookup walks `ctx` segment-by-
+ * segment; if any segment is missing, undefined, or null, the placeholder is
+ * left intact (`{{path}}`) so callers can detect unresolved templates.
  */
 function substituteTemplate(value, ctx) {
   if (value == null) return value;
   if (typeof value === 'string') {
     return value.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (match, key) => {
-      if (ctx && Object.prototype.hasOwnProperty.call(ctx, key) && ctx[key] !== undefined && ctx[key] !== null) {
-        return String(ctx[key]);
-      }
-      return match;
+      const resolved = _resolvePath(ctx, key);
+      if (resolved === undefined || resolved === null) return match;
+      return String(resolved);
     });
   }
   if (Array.isArray(value)) return value.map(v => substituteTemplate(v, ctx));
@@ -99,6 +109,34 @@ function substituteTemplate(value, ctx) {
   return value;
 }
 
+/**
+ * Internal: resolve a dotted path (e.g. "steps.0.result.dispatchedItemId")
+ * against a context object. Bare keys (no dots) preserve the original
+ * `hasOwnProperty` semantics for back-compat with the pre-Phase-4 behavior.
+ * Returns undefined on any miss; null intermediate values short-circuit to
+ * undefined so the caller can leave the placeholder in place.
+ */
+function _resolvePath(ctx, key) {
+  if (!ctx || typeof ctx !== 'object') return undefined;
+  if (key.indexOf('.') === -1) {
+    return Object.prototype.hasOwnProperty.call(ctx, key) ? ctx[key] : undefined;
+  }
+  const segments = key.split('.');
+  let cursor = ctx;
+  for (const seg of segments) {
+    if (cursor === null || cursor === undefined) return undefined;
+    if (typeof cursor !== 'object') return undefined;
+    if (Array.isArray(cursor)) {
+      const idx = Number(seg);
+      if (!Number.isInteger(idx) || idx < 0 || idx >= cursor.length) return undefined;
+      cursor = cursor[idx];
+    } else {
+      cursor = Object.prototype.hasOwnProperty.call(cursor, seg) ? cursor[seg] : undefined;
+    }
+  }
+  return cursor;
+}
+
 /**
  * Build the trigger context passed to action handlers and used for templating.
  * Pulls type-specific extras from the entity captured for the watch (e.g. PR
@@ -156,15 +194,53 @@ function buildTriggerContext(watch, opts = {}) {
 /**
  * Run a watch's configured action — async, error-isolated.
  * Returns a result object the caller persists on `watch._lastActionResult`.
+ *
+ * P-w7c5d8b3 — Phase 3.2: an action may carry an optional
+ * `guard: { expr: '<safe-expr string>' }` that is evaluated against the
+ * trigger context BEFORE the handler is invoked. Falsy/invalid guards
+ * short-circuit to `{ ok: true, skipped: true, summary: 'guard false' }`
+ * — the caller treats that as a successful no-op so future action chains
+ * (Phase 4) can continue past it without aborting.
+ */
+/**
+ * Run a watch's configured action — async, error-isolated.
+ * Returns a result object the caller persists on `watch._lastActionResult`.
+ *
+ * P-w7c5d8b3 — Phase 3.2: an action may carry an optional
+ * `guard: { expr: '<safe-expr string>' }` that is evaluated against the
+ * trigger context BEFORE the handler is invoked. Falsy/invalid guards
+ * short-circuit to `{ ok: true, skipped: true, summary: 'guard false' }`
+ * — the caller treats that as a successful no-op so future action chains
+ * (Phase 4) can continue past it without aborting.
+ *
+ * P-w8e9b1f4 — Phase 4: when `watch.action` is an array, this delegates to
+ * `runWatchActionChain` which executes the steps sequentially, exposes
+ * progressive `ctx.steps` so step N can template against earlier results
+ * (e.g. `{{steps.0.result.dispatchedItemId}}`), aborts on the first non-
+ * skipped failure, and returns an aggregate `{ ok, summary, steps:[…],
+ * aborted }` shape.
  */
 async function runWatchAction(watch, ctx) {
   const action = watch && watch.action;
+  if (Array.isArray(action)) return runWatchActionChain(watch, ctx);
   if (!action || typeof action !== 'object') return { ok: false, summary: 'no action configured', skipped: true };
   const type = String(action.type || '').toLowerCase();
   if (!type) return { ok: false, summary: 'action.type missing' };
   const spec = ACTION_TYPES[type];
   if (!spec) return { ok: false, summary: `unknown action type: ${type}` };
 
+  // Evaluate optional guard against the trigger context. safe-expr returns
+  // false on parse/eval errors (and logs a [safe-expr] warn), so invalid
+  // expressions naturally fall into the "skipped" branch. Empty / non-string
+  // expr is also invalid per safe-expr's contract.
+  if (action.guard && typeof action.guard === 'object' && !Array.isArray(action.guard)) {
+    const expr = action.guard.expr;
+    const passed = safeExpr.evaluate(expr, ctx || {});
+    if (!passed) {
+      return { ok: true, skipped: true, summary: 'guard false', guard: { expr: typeof expr === 'string' ? expr : null } };
+    }
+  }
+
   const params = substituteTemplate(action.params || {}, ctx);
   try {
     const result = await spec.handler(watch, { ...ctx, params });
@@ -177,24 +253,96 @@ async function runWatchAction(watch, ctx) {
   }
 }
 
+/**
+ * Run an array-form `watch.action` as an ordered chain of steps.
+ *
+ * Each step is a single-action object (`{type, params?, guard?}`). Steps
+ * execute sequentially; the per-step result is appended to `ctx.steps` BEFORE
+ * the next step is templated, so step N can reference earlier outputs via
+ * dotted paths (e.g. `{{steps.0.result.dispatchedItemId}}`). The chain
+ * aborts on the first step that returns `ok:false` AND is not `skipped`;
+ * guard-skipped steps are treated as successful no-ops (chain continues).
+ *
+ * Returns an aggregate `{ ok, summary, steps, aborted }`. Each `steps[i]`
+ * entry has shape `{type, ok, skipped, summary, result}` where `result`
+ * holds the full per-step return value so downstream templating can reach
+ * any field the handler exposed.
+ */
+async function runWatchActionChain(watch, ctx) {
+  const steps = Array.isArray(watch && watch.action) ? watch.action : [];
+  const stepResults = [];
+  // Mutate-in-place so substituteTemplate() sees freshly-completed steps on
+  // the next iteration without rebuilding ctx each time.
+  const baseCtx = ctx && typeof ctx === 'object' ? ctx : {};
+  const chainCtx = { ...baseCtx, steps: stepResults };
+  let chainOk = true;
+  let aborted = false;
+  let lastSummary = '';
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    if (!step || typeof step !== 'object' || Array.isArray(step)) {
+      stepResults.push({ type: null, ok: false, skipped: false, summary: `step ${i} is not an object`, result: null });
+      chainOk = false;
+      aborted = true;
+      lastSummary = `step ${i} invalid`;
+      break;
+    }
+    const stepWatch = { ...watch, action: step };
+    const result = await runWatchAction(stepWatch, chainCtx);
+    const entry = {
+      type: step.type ? String(step.type).toLowerCase() : null,
+      ok: !!(result && result.ok),
+      skipped: !!(result && result.skipped),
+      summary: (result && result.summary) || '',
+      result: result || null,
+    };
+    stepResults.push(entry);
+    lastSummary = entry.summary;
+    if (!entry.ok) {
+      chainOk = false;
+      aborted = true;
+      break;
+    }
+    if (entry.ok && !entry.skipped) {
+      // chainOk stays true; continue
+    }
+  }
+  const ranCount = stepResults.filter(s => s.ok && !s.skipped).length;
+  const skippedCount = stepResults.filter(s => s.skipped).length;
+  const summary = aborted
+    ? `chain aborted at step ${stepResults.length} of ${steps.length}: ${lastSummary || 'failure'}`
+    : `chain ok (${stepResults.length} step${stepResults.length === 1 ? '' : 's'}: ${ranCount} ran, ${skippedCount} skipped)`;
+  return { ok: chainOk, summary, steps: stepResults, aborted };
+}
+
 // ── Built-in action handlers ─────────────────────────────────────────────────
 
 // notify — explicit no-op redundant with the watch.notify field. Useful when a
 // caller wants to set notify=none and still configure the alert via the action
 // surface (e.g. to template the body), or as a placeholder.
+//
+// P-w11a4c9e — Phase 6.1: NOTIFY is now the single registered code path for
+// inbox notifications. The legacy `watch.notify === 'inbox'` branch in
+// engine/watches.js no longer writes to the inbox itself — it instead
+// synthesizes an implicit `{type:'notify'}` step prepended to the action
+// chain. To keep the legacy slug shape `watch-<id>-<triggerCount>` (so
+// existing dedup / readers see no change), this handler defaults to that
+// slug. Callers can pass `params.slug` to override (e.g. when emitting
+// multiple notify steps in the same trigger).
 registerActionType(WATCH_ACTION_TYPE.NOTIFY, {
   label: 'Notify (inbox)',
-  description: 'Write a notification to the configured owner inbox. Redundant with the legacy `notify` field but useful as an explicit action.',
+  description: 'Write a notification to the configured owner inbox. Routes the legacy `notify: "inbox"` field; can also be used as an explicit action to template the body or override the slug.',
   params: [
     { key: 'owner', required: false, description: 'Override owner; defaults to watch.owner.' },
     { key: 'body', required: false, description: 'Override body; defaults to standard trigger message.' },
+    { key: 'slug', required: false, description: 'Override inbox file slug; defaults to legacy `watch-<id>-<triggerCount>`.' },
   ],
   handler: async (watch, ctx) => {
     const owner = ctx.params.owner || watch.owner;
     if (!owner) return { ok: false, summary: 'no owner — skipping notify action' };
     const body = ctx.params.body
       || `## Watch Triggered: ${watch.description || watch.id}\n\n${ctx.message || ''}\n\nWatch ID: ${watch.id} | Target: ${watch.target} | Condition: ${watch.condition}`;
-    const slug = `watch-${watch.id}-action-${watch.triggerCount || 0}-${Date.now()}`;
+    const slug = ctx.params.slug || `watch-${watch.id}-${watch.triggerCount || 0}`;
     shared.writeToInbox(owner, slug, body);
     return { ok: true, summary: `notified ${owner}` };
   },
@@ -341,6 +489,107 @@ registerActionType(WATCH_ACTION_TYPE.WEBHOOK, {
   },
 });
 
+// minions-api — first-class loopback API caller for the in-process dashboard.
+// Restricts `endpoint` to paths starting with `/api/` so a watch can't reach
+// external hosts (use `webhook` for that). Always targets
+// `http://127.0.0.1:${MINIONS_PORT||7331}${endpoint}` and sets
+// `X-Minions-Internal: 1` so dashboard handlers can recognize that the
+// request originated from the engine's own action surface (Origin/Referer
+// are intentionally absent — the dashboard's origin gate already allows
+// header-less local tooling through).
+//
+// Body is rendered through substituteTemplate by runWatchAction's templating
+// pass before the handler runs, so step refs like
+// {{steps.0.result.dispatchedItemId}} resolve into the JSON payload.
+//
+// Returns `{ ok, status, summary, response }` so chain steps can template
+// against `{{steps.N.result.response.<field>}}`.
+const _ALLOWED_API_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+function _isLoopbackApiEndpoint(value) {
+  if (typeof value !== 'string' || !value) return false;
+  // Must be a path starting with /api/ — reject anything that looks like a
+  // full URL (http://, https://, //host) so an attacker can't sneak an
+  // external host in via the endpoint field.
+  if (!value.startsWith('/api/')) return false;
+  if (value.startsWith('//')) return false;
+  return true;
+}
+registerActionType(WATCH_ACTION_TYPE.MINIONS_API, {
+  label: 'Minions API',
+  description: 'Call a Minions dashboard API endpoint via loopback (always 127.0.0.1). Endpoint must start with /api/. Use webhook for external HTTP.',
+  params: [
+    { key: 'endpoint', required: true, description: 'API path starting with /api/ (e.g. /api/work-items). Templated.' },
+    { key: 'method', required: false, description: 'HTTP method: GET (default), POST, PUT, PATCH, DELETE.' },
+    { key: 'body', required: false, description: 'Request body (object → JSON, string → raw). Templated through substituteTemplate.' },
+    { key: 'headers', required: false, description: 'Object map of extra headers. X-Minions-Internal is added automatically.' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const endpoint = String(p.endpoint || '').trim();
+    if (!endpoint) return { ok: false, summary: 'minions-api: endpoint is required' };
+    if (!_isLoopbackApiEndpoint(endpoint)) {
+      return { ok: false, summary: `minions-api: endpoint must start with /api/ (loopback only); got "${endpoint}"` };
+    }
+    const method = String(p.method || 'GET').toUpperCase();
+    if (!_ALLOWED_API_METHODS.has(method)) {
+      return { ok: false, summary: `minions-api: unsupported method ${method} (allowed: ${[..._ALLOWED_API_METHODS].join(', ')})` };
+    }
+    const port = process.env.MINIONS_PORT || 7331;
+    const headers = {
+      'User-Agent': 'minions-watch/1.0',
+      'X-Minions-Internal': '1',
+      ...(p.headers && typeof p.headers === 'object' ? p.headers : {}),
+    };
+    let body = null;
+    if (p.body !== undefined && p.body !== null && method !== 'GET' && method !== 'HEAD') {
+      if (typeof p.body === 'string') {
+        body = p.body;
+        if (!headers['Content-Type'] && !headers['content-type']) headers['Content-Type'] = 'text/plain';
+      } else {
+        body = JSON.stringify(p.body);
+        if (!headers['Content-Type'] && !headers['content-type']) headers['Content-Type'] = 'application/json';
+      }
+      headers['Content-Length'] = Buffer.byteLength(body);
+    }
+
+    return new Promise((resolve) => {
+      const req = http.request({
+        hostname: '127.0.0.1',
+        port,
+        path: endpoint,
+        method,
+        headers,
+      }, (res) => {
+        let chunks = '';
+        res.on('data', (c) => { chunks += c; });
+        res.on('end', () => {
+          let parsed = chunks;
+          const ct = String(res.headers['content-type'] || '').toLowerCase();
+          if (ct.includes('application/json') && chunks) {
+            try { parsed = JSON.parse(chunks); } catch { /* keep raw text on parse failure */ }
+          }
+          const ok = res.statusCode >= 200 && res.statusCode < 400;
+          resolve({
+            ok,
+            status: res.statusCode,
+            summary: `minions-api ${method} ${endpoint} → ${res.statusCode}`,
+            response: parsed,
+          });
+        });
+      });
+      req.on('error', (err) => {
+        resolve({ ok: false, summary: `minions-api ${method} ${endpoint} failed: ${err.message}` });
+      });
+      // 10s safety timeout — watches must not hang the tick.
+      req.setTimeout(10000, () => {
+        req.destroy(new Error('timeout'));
+      });
+      if (body !== null) req.write(body);
+      req.end();
+    });
+  },
+});
+
 // cancel-work-item — flip a WI to CANCELLED across project + central files.
 registerActionType(WATCH_ACTION_TYPE.CANCEL_WORK_ITEM, {
   label: 'Cancel Work Item',
@@ -472,7 +721,23 @@ registerActionType(WATCH_ACTION_TYPE.RESUME_PLAN, {
  */
 function validateAction(action) {
   if (action === null || action === undefined) return null; // optional field
-  if (typeof action !== 'object' || Array.isArray(action)) return 'action must be an object';
+  // P-w8e9b1f4 — Phase 4: array-form action chains. Each entry must itself
+  // be a valid single-action object. Validate per-step so the error names
+  // the failing index. An empty array is rejected — a chain with no steps
+  // would silently no-op at trigger time, which is almost never intended.
+  if (Array.isArray(action)) {
+    if (action.length === 0) return 'action chain (array) must contain at least one step';
+    for (let i = 0; i < action.length; i++) {
+      const step = action[i];
+      if (!step || typeof step !== 'object' || Array.isArray(step)) {
+        return `action[${i}] must be a step object (got ${Array.isArray(step) ? 'array' : typeof step})`;
+      }
+      const err = validateAction(step);
+      if (err) return `action[${i}]: ${err}`;
+    }
+    return null;
+  }
+  if (typeof action !== 'object') return 'action must be an object or an array of step objects';
   const type = String(action.type || '').toLowerCase();
   if (!type) return 'action.type is required';
   const spec = ACTION_TYPES[type];
@@ -486,6 +751,21 @@ function validateAction(action) {
       return `action.params.${p.key} is required for action type ${type}`;
     }
   }
+  // P-w7c5d8b3 — Phase 3.2: optional `guard` field. Shape is locked here
+  // (object with a string `expr`), but the expression itself is NOT
+  // pre-parsed at validation time — safe-expr.evaluate is the single
+  // source of truth, and a malformed expression is handled at run time
+  // (skips the action + logs a [safe-expr] warn). Pre-parsing would
+  // duplicate the parser surface and risk false-rejecting expressions
+  // whose context vars only exist at trigger time.
+  if (action.guard !== undefined && action.guard !== null) {
+    if (typeof action.guard !== 'object' || Array.isArray(action.guard)) {
+      return 'action.guard must be an object of shape { expr: string }';
+    }
+    if (typeof action.guard.expr !== 'string' || action.guard.expr.trim() === '') {
+      return 'action.guard.expr must be a non-empty string';
+    }
+  }
   // Extra validation for webhook URL — fail fast on unsupported schemes.
   if (type === WATCH_ACTION_TYPE.WEBHOOK && params.url) {
     const url = String(params.url);
@@ -499,6 +779,31 @@ function validateAction(action) {
       } catch { return `webhook url is invalid: ${url}`; }
     }
   }
+  // Extra validation for minions-api endpoint + method. The endpoint must
+  // be a loopback /api/ path; full URLs and other prefixes are rejected so
+  // the action can never reach external hosts (use webhook for that). The
+  // method allowlist matches the runtime handler's allowlist so misspelled
+  // methods fail at createWatch time instead of at first trigger.
+  if (type === WATCH_ACTION_TYPE.MINIONS_API) {
+    const endpoint = String(params.endpoint || '');
+    // Allow templated endpoints (containing {{...}}) — re-validated at runtime.
+    if (!/\{\{/.test(endpoint)) {
+      if (!endpoint.startsWith('/api/') || endpoint.startsWith('//')) {
+        return `minions-api endpoint must start with /api/ (loopback only); got "${endpoint}"`;
+      }
+    }
+    if (params.method !== undefined && params.method !== null && params.method !== '') {
+      const m = String(params.method).toUpperCase();
+      const allowed = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+      if (!allowed.has(m)) {
+        return `minions-api method must be one of GET, POST, PUT, PATCH, DELETE; got ${params.method}`;
+      }
+    }
+    if (params.headers !== undefined && params.headers !== null
+        && (typeof params.headers !== 'object' || Array.isArray(params.headers))) {
+      return 'minions-api headers must be an object map of header → value';
+    }
+  }
   return null;
 }
 
@@ -507,6 +812,7 @@ module.exports = {
   getActionType,
   listActionTypes,
   runWatchAction,
+  runWatchActionChain,
   buildTriggerContext,
   substituteTemplate,
   validateAction,