@yemi33/minions 0.1.2071 → 0.1.2073

package/engine/pipeline.js

@@ -76,7 +76,9 @@ function getPipelineRuns() {
 function getActiveRun(pipelineId) {
   const runs = getPipelineRuns();
   const pipelineRuns = runs[pipelineId] || [];
-  return pipelineRuns.find(r => r.status === PIPELINE_STATUS.RUNNING || r.status === PIPELINE_STATUS.PAUSED);
+  return pipelineRuns.find(r => r.status === PIPELINE_STATUS.RUNNING
+    || r.status === PIPELINE_STATUS.PAUSED
+    || r.status === PIPELINE_STATUS.WAITING_HUMAN);
 }
 
 function startRun(pipelineId, pipeline) {
@@ -110,6 +112,12 @@ function startRun(pipelineId, pipeline) {
 }
 
 function updateRunStage(pipelineId, runId, stageId, updates) {
+  if (updates && Object.prototype.hasOwnProperty.call(updates, 'status')) {
+    const validStatuses = Object.values(PIPELINE_STATUS);
+    if (!validStatuses.includes(updates.status)) {
+      throw new Error(`updateRunStage: invalid status '${updates.status}' (expected one of: ${validStatuses.join('|')})`);
+    }
+  }
   mutateJsonFileLocked(PIPELINE_RUNS_PATH, (data) => {
     const runs = data[pipelineId] || [];
     const run = runs.find(r => r.runId === runId);

package/engine/playbook.js

@@ -301,6 +301,30 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // PR-context vars on non-PR tasks (implement/explore/etc.)
   'pr_id', 'pr_number', 'pr_title', 'pr_branch', 'pr_author', 'pr_url',
   'reviewer',
+  // P-e6b3c2d8 — QA Session template vars. session_id / target_kind /
+  // flows_raw / managed_spawn_name are required (declared in
+  // PLAYBOOK_REQUIRED_VARS['qa-session-setup']); these target_* sub-fields
+  // are conditional on target.kind so only one is populated per session.
+  // runner_hint / capture / target_json / session_mode / session_phase are
+  // surfaced for completeness but legitimately empty when not specified.
+  'target_pr_id',          // populated only for target.kind === 'pr'
+  'target_branch',         // populated only for target.kind === 'branch'
+  'target_sha',            // populated only for target.kind === 'commit'
+  'target_worktree',       // populated only for target.kind === 'current'
+  'target_json',           // JSON-encoded target spec (always present when session_id is)
+  'runner_hint',           // explicit runner name; empty = auto-detect
+  'capture',               // 'video,screenshots,logs' summary
+  'session_mode',          // 'confirm' | 'auto'
+  'session_phase',         // 'setup' | 'draft' | 'execute'
+  // P-f9a2e1b4 — Runner adapter briefs. engine.js calls the registered
+  // runner's generateBrief()/executeBrief() at render time and surfaces the
+  // resulting markdown strings here. Required for the DRAFT/EXECUTE
+  // playbooks (declared in PLAYBOOK_REQUIRED_VARS below); empty in the
+  // SETUP phase, which is why they live in the optional set — we don't
+  // want SETUP renders to emit unresolved-var warnings.
+  'runner_brief',          // generateBrief() output — used by qa-session-draft
+  'runner_execute_brief',  // executeBrief() output — used by qa-session-execute
+  'test_file',             // session.testFile — set after DRAFT, used by EXECUTE
 ]);
 
 const PLAYBOOK_REQUIRED_VARS = {
@@ -319,6 +343,21 @@ const PLAYBOOK_REQUIRED_VARS = {
   'docs':                 ['item_id', 'item_name'],
   'setup':                ['item_id', 'item_name', 'project_path'],
   'qa-validate':          ['item_id', 'item_name', 'qa_run_id'],
+  // P-e6b3c2d8 — QA Session SETUP phase. Required vars are session
+  // identification + target kind + flows + the deterministic managed-spawn
+  // name the engine joins back to the session on. Conditional target_*
+  // sub-fields (target_pr_id / target_branch / target_sha / target_worktree)
+  // are optional — only one is populated per target.kind.
+  'qa-session-setup':     ['session_id', 'target_kind', 'flows_raw', 'managed_spawn_name'],
+  // P-f9a2e1b4 — QA Session DRAFT phase. Required vars are the session id +
+  // flows + the live managed-spawn name + the runner adapter's
+  // generateBrief() output. The brief is computed at render time by
+  // engine.js (lazy-required qa-sessions + qa-runners + managed-spawn).
+  'qa-session-draft':     ['session_id', 'flows_raw', 'managed_spawn_name', 'runner_brief'],
+  // P-f9a2e1b4 — QA Session EXECUTE phase. Required vars are session id +
+  // live managed-spawn name + executeBrief() output + the qa-runs record id
+  // (the agent stamps it on the result sidecar so lifecycle.js can ingest it).
+  'qa-session-execute':   ['session_id', 'managed_spawn_name', 'runner_execute_brief', 'qa_run_id'],
   'work-item':            ['item_id', 'item_name'],
   'meeting-investigate':  ['meeting_title', 'agenda'],
   'meeting-debate':       ['meeting_title', 'agenda'],

package/engine/pull-requests-store.js

@@ -62,15 +62,16 @@ function _readJsonArrayFallback(scope) {
   }
 }
 
-// Track (mtime, size) per scope so back-to-back writes inside the same
-// ms tick still get detected as external edits (mtime-only checks miss
-// them on Windows because NTFS reports ms-rounded mtimeMs).
-const _lastMirrorByScope = new Map();
+// Content-hash fingerprint per scope: same-length swaps (timestamps,
+// reviewStatus enums) collide on (mtime, size) but never on SHA-1.
+const _lastMirrorHashByScope = new Map();
 
-function _statFingerprint(filePath) {
+const crypto = require('crypto');
+
+function _fileContentHash(filePath) {
   try {
-    const st = fs.statSync(filePath);
-    return { mtime: st.mtimeMs, size: st.size };
+    const buf = fs.readFileSync(filePath);
+    return crypto.createHash('sha1').update(buf).digest('hex');
   }
   catch { return null; }
 }
@@ -105,23 +106,19 @@ function _hydrateScopeFromJson(db, scope) {
 
 function _resyncScopeIfJsonDiverged(db, scope) {
   const jsonPath = _filePathForScope(scope);
-  const current = _statFingerprint(jsonPath);
-  const lastMirror = _lastMirrorByScope.get(scope);
-  if (current == null) return;
-  // In-sync iff BOTH mtime AND size match. Size catches same-ms-tick
-  // external writes that mtime alone misses. Resync is idempotent.
-  if (lastMirror != null
-    && current.mtime === lastMirror.mtime
-    && current.size === lastMirror.size) return;
-  if (lastMirror == null) {
+  const currentHash = _fileContentHash(jsonPath);
+  const lastHash = _lastMirrorHashByScope.get(scope);
+  if (currentHash == null) return;
+  if (lastHash != null && currentHash === lastHash) return;
+  if (lastHash == null) {
     const sqlHas = db.prepare('SELECT 1 FROM pull_requests WHERE scope = ? LIMIT 1').get(scope);
     if (sqlHas) {
-      _lastMirrorByScope.set(scope, current);
+      _lastMirrorHashByScope.set(scope, currentHash);
       return;
     }
   }
   _hydrateScopeFromJson(db, scope);
-  _lastMirrorByScope.set(scope, current);
+  _lastMirrorHashByScope.set(scope, currentHash);
 }
 
 function readPullRequestsForScope(scope) {
@@ -269,12 +266,23 @@ function applyPullRequestsMutation(scope, mutator) {
 function _mirrorJsonFromSql(scope, filePath) {
   try {
     const shared = require('./shared');
-    const items = readPullRequestsForScope(scope);
-    for (const pr of items) { if (pr && pr._scope) delete pr._scope; }
+    const { getDb } = require('./db');
+    // Read SQL directly for this scope — bypass JSON fallback so a
+    // mutation that empties SQL for the scope doesn't resurrect stale
+    // JSON content.
+    const db = getDb();
+    const rows = db.prepare('SELECT data FROM pull_requests WHERE scope = ? ORDER BY rowid').all(scope);
+    const items = [];
+    for (const row of rows) {
+      const pr = _parseRow(row);
+      if (!pr) continue;
+      if (pr._scope) delete pr._scope;
+      items.push(pr);
+    }
     const target = filePath || _filePathForScope(scope);
     shared.safeWrite(target, items);
-    const fp = _statFingerprint(target);
-    if (fp != null) _lastMirrorByScope.set(scope, fp);
+    const h = _fileContentHash(target);
+    if (h != null) _lastMirrorHashByScope.set(scope, h);
   } catch {
     // Mirror failures are non-fatal — SQL has already committed.
   }

package/engine/qa-runners/maestro.js

@@ -0,0 +1,152 @@
+/**
+ * engine/qa-runners/maestro.js — P-c4a9e7f3
+ *
+ * Maestro built-in runner adapter for QA Sessions. Registered at boot by
+ * engine/qa-runners.js (_registerBuiltins). Priority 80 — higher than the
+ * Playwright safe default so a project with `.maestro/` wins on tie.
+ *
+ * Detection: project.localPath (or target.worktree for kind='current') has
+ * a `.maestro/` directory. Explicit `runner: 'maestro'` is honoured directly
+ * by qa-runners.js#detectRunner before detect() runs, so it does not need
+ * a branch here.
+ *
+ * Hooks: see engine/qa-runners.js header for the contract. We return
+ * markdown strings from generateBrief / executeBrief — those flow into the
+ * qa-session-draft.md / qa-session-execute.md playbooks as {{runner_brief}}
+ * and {{runner_execute_brief}} (wired in P-f9a2e1b4).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME = 'maestro';
+const PRIORITY = 80;
+const INSTALL_HINT =
+  'Maestro CLI is required. Install via Homebrew (`brew tap mobile-dev-inc/tap && brew install maestro`) ' +
+  'on macOS/Linux, or follow https://maestro.mobile.dev/getting-started/installing-maestro for Windows / manual install. ' +
+  'Confirm with `maestro --version` before re-running the session.';
+
+function _resolveProbeRoot(target, project) {
+  if (target && target.kind === 'current' && typeof target.worktree === 'string' && target.worktree) {
+    return target.worktree;
+  }
+  if (project && typeof project.localPath === 'string' && project.localPath) {
+    return project.localPath;
+  }
+  return null;
+}
+
+function detect(target, project) {
+  const root = _resolveProbeRoot(target, project);
+  if (!root) return false;
+  try {
+    const stat = fs.statSync(path.join(root, '.maestro'));
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function _spawnUrl(spawnInfo) {
+  if (!spawnInfo) return '';
+  if (spawnInfo.attrs && typeof spawnInfo.attrs.base_url === 'string') return spawnInfo.attrs.base_url;
+  if (Array.isArray(spawnInfo.ports) && spawnInfo.ports.length > 0) {
+    return `http://localhost:${spawnInfo.ports[0]}`;
+  }
+  return '';
+}
+
+function generateBrief(opts) {
+  opts = opts || {};
+  const baseUrl = _spawnUrl(opts.spawnInfo);
+  const flows = opts.flowsRaw || '(no flows provided)';
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const capture = opts.capture || {};
+  const captureSummary = Object.entries(capture).filter(([, v]) => !!v).map(([k]) => k).join(', ') || '(none requested)';
+
+  return [
+    '## Maestro test draft',
+    '',
+    `Write a single Maestro flow file at \`engine/qa-tests/${sessionId}/flow.yaml\` that exercises:`,
+    '',
+    flows.trim(),
+    '',
+    '### Required structure',
+    '',
+    '- Top-level `appId:` set to the package id Maestro should drive (Android package or iOS bundle).',
+    '- A sequence of Maestro commands (`launchApp`, `tapOn`, `inputText`, `assertVisible`, …) that maps 1:1 to the flow above.',
+    baseUrl
+      ? `- For any HTTP step, use the live target base URL \`${baseUrl}\` (resolved from the managed-spawn).`
+      : '- The managed-spawn target did not advertise a base URL; rely on the app id alone.',
+    '- Keep the flow under 50 lines — split into named sub-flows (`runFlow:`) when the user described independent journeys.',
+    '',
+    '### Capture configuration',
+    '',
+    `Requested artifacts: ${captureSummary}. Surface them via the standard Maestro recording flags ` +
+      '(`maestro record` or `maestro test --output …`) in the EXECUTE phase; do NOT enable them inside the flow YAML itself.',
+    '',
+    'See https://maestro.mobile.dev/api-reference/commands for the command vocabulary.',
+  ].join('\n');
+}
+
+function executeBrief(opts) {
+  opts = opts || {};
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const testFile = opts.testFile || `engine/qa-tests/${sessionId}/flow.yaml`;
+  const capture = opts.capture || {};
+  const outputDir = `engine/qa-artifacts/${sessionId}`;
+
+  const cmdFlags = [`--output ${outputDir}`];
+  if (capture.logs) cmdFlags.push(`--debug-output ${outputDir}/maestro-debug`);
+  // `maestro test` does not support video; surface the limitation in the
+  // brief body rather than silently dropping the capture request.
+
+  return [
+    '## Maestro execute',
+    '',
+    'Run the drafted flow against the live managed-spawn:',
+    '',
+    '```bash',
+    `maestro test ${testFile} ${cmdFlags.join(' ')}`,
+    '```',
+    '',
+    `Write the result sidecar to \`agents/<your-id>/qa-run-result.json\` referencing artifacts under \`${outputDir}/\`.`,
+    capture.video
+      ? '\nVideo capture was requested — note in the result summary that `maestro test` does not record video and the human will need a separate `maestro record` pass if they want it.'
+      : '',
+    capture.screenshots
+      ? '\nScreenshot capture was requested — add `takeScreenshot:` steps at the key flow boundaries; Maestro writes them under the --output dir.'
+      : '',
+  ].filter(Boolean).join('\n');
+}
+
+function validateOutputDir(dir) {
+  const errors = [];
+  if (typeof dir !== 'string' || dir === '') {
+    return { ok: false, errors: ['dir must be a non-empty string'] };
+  }
+  let entries;
+  try { entries = fs.readdirSync(dir); }
+  catch (err) {
+    return { ok: false, errors: [`qa-tests dir ${dir} unreadable: ${err.message}`] };
+  }
+  const yamlFiles = entries.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+  if (yamlFiles.length === 0) {
+    errors.push(`no Maestro flow file (*.yaml) found in ${dir}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  name: NAME,
+  spec: {
+    priority: PRIORITY,
+    label: 'Maestro',
+    description: 'Mobile-first NL flows. Detects when the target project has a .maestro/ directory.',
+    installHint: INSTALL_HINT,
+    detect,
+    generateBrief,
+    executeBrief,
+    validateOutputDir,
+  },
+};

package/engine/qa-runners/playwright.js

@@ -0,0 +1,149 @@
+/**
+ * engine/qa-runners/playwright.js — P-c4a9e7f3
+ *
+ * Playwright built-in runner adapter for QA Sessions. Registered at boot by
+ * engine/qa-runners.js (_registerBuiltins). Priority 50 — the safe default
+ * for any HTTP target. Maestro (priority 80) wins on detect tie when the
+ * project has `.maestro/`.
+ *
+ * Detection: always true. Playwright is the safe-default web runner, and
+ * QA-session targets are overwhelmingly web apps with an HTTP spawn (PR
+ * preview, branch dev server, current worktree dev server, etc.). The
+ * priority gate above lets Maestro win when present; explicit
+ * `runner: '...'` overrides win before detect() runs at all.
+ *
+ * Hooks: see engine/qa-runners.js header for the contract.
+ */
+
+const fs = require('fs');
+
+const NAME = 'playwright';
+const PRIORITY = 50;
+const INSTALL_HINT =
+  'Playwright is required. From the target project run `npm i -D @playwright/test` and ' +
+  '`npx playwright install` (the second command installs the browser binaries). ' +
+  'Confirm with `npx playwright --version`.';
+
+function detect(/* target, project */) {
+  return true;
+}
+
+function _spawnUrl(spawnInfo) {
+  if (!spawnInfo) return '';
+  if (spawnInfo.attrs && typeof spawnInfo.attrs.base_url === 'string') return spawnInfo.attrs.base_url;
+  if (Array.isArray(spawnInfo.ports) && spawnInfo.ports.length > 0) {
+    return `http://localhost:${spawnInfo.ports[0]}`;
+  }
+  return '';
+}
+
+function _portsLabel(spawnInfo) {
+  if (!spawnInfo || !Array.isArray(spawnInfo.ports) || spawnInfo.ports.length === 0) return '(no ports)';
+  return spawnInfo.ports.join(', ');
+}
+
+function generateBrief(opts) {
+  opts = opts || {};
+  const baseUrl = _spawnUrl(opts.spawnInfo);
+  const ports = _portsLabel(opts.spawnInfo);
+  const flows = opts.flowsRaw || '(no flows provided)';
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const capture = opts.capture || {};
+  const captureSummary = Object.entries(capture).filter(([, v]) => !!v).map(([k]) => k).join(', ') || '(none requested)';
+
+  return [
+    '## Playwright test draft',
+    '',
+    `Write a single Playwright test at \`engine/qa-tests/${sessionId}/test.spec.js\` that exercises:`,
+    '',
+    flows.trim(),
+    '',
+    '### Required structure',
+    '',
+    '```js',
+    "const { test, expect } = require('@playwright/test');",
+    '',
+    "test('qa-session flow', async ({ page }) => {",
+    baseUrl
+      ? `  await page.goto('${baseUrl}');`
+      : '  // Managed-spawn did not advertise base_url; build the URL from the spawn port.',
+    '  // … translate each flow step into Playwright actions (locator + assertion) …',
+    '});',
+    '```',
+    '',
+    baseUrl
+      ? `- Live target: \`${baseUrl}\` (ports: ${ports}). Anchor every \`page.goto\` to this URL.`
+      : `- Live target ports: ${ports}. Build the URL from the port the dev server bound to.`,
+    '- Keep selectors resilient — prefer `getByRole`, `getByText`, `getByTestId` over CSS where possible.',
+    '- Each step the user described becomes one or more Playwright actions + a matching `expect(...).toBeVisible()` / `.toHaveURL()` / `.toHaveText()`.',
+    '',
+    '### Capture configuration',
+    '',
+    `Requested artifacts: ${captureSummary}. The EXECUTE phase wires \`--video\`, \`--screenshot\`, and trace flags ` +
+      'into the `npx playwright test` invocation. The test file itself should NOT hard-code recording (let the CLI flags drive it).',
+  ].join('\n');
+}
+
+function executeBrief(opts) {
+  opts = opts || {};
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const testFile = opts.testFile || `engine/qa-tests/${sessionId}/test.spec.js`;
+  const capture = opts.capture || {};
+  const outputDir = `engine/qa-artifacts/${sessionId}`;
+
+  const flags = [`--output ${outputDir}`, '--reporter=json'];
+  if (capture.video) flags.push('--video=on');
+  if (capture.screenshots) flags.push('--screenshot=on');
+  if (capture.logs) flags.push('--trace=on');
+
+  const artifactTypes = [];
+  if (capture.video) artifactTypes.push('`video` (webm)');
+  if (capture.screenshots) artifactTypes.push('`screenshot` (png)');
+  if (capture.logs) artifactTypes.push('`log` (trace.zip + stdout)');
+  if (artifactTypes.length === 0) artifactTypes.push('`log` (test stdout/stderr only — no capture flags requested)');
+
+  return [
+    '## Playwright execute',
+    '',
+    'Run the drafted test against the live managed-spawn:',
+    '',
+    '```bash',
+    `npx playwright test ${testFile} ${flags.join(' ')}`,
+    '```',
+    '',
+    `Write the result sidecar to \`agents/<your-id>/qa-run-result.json\` referencing artifacts under \`${outputDir}/\`.`,
+    '',
+    `Artifact types: ${artifactTypes.join(', ')}`,
+  ].join('\n');
+}
+
+function validateOutputDir(dir) {
+  const errors = [];
+  if (typeof dir !== 'string' || dir === '') {
+    return { ok: false, errors: ['dir must be a non-empty string'] };
+  }
+  let entries;
+  try { entries = fs.readdirSync(dir); }
+  catch (err) {
+    return { ok: false, errors: [`qa-tests dir ${dir} unreadable: ${err.message}`] };
+  }
+  const specFiles = entries.filter(f => /\.spec\.(js|ts|mjs|cjs)$/.test(f));
+  if (specFiles.length === 0) {
+    errors.push(`no Playwright test file (*.spec.{js,ts,mjs,cjs}) found in ${dir}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  name: NAME,
+  spec: {
+    priority: PRIORITY,
+    label: 'Playwright',
+    description: 'Safe-default web runner. Wins for any HTTP target unless a higher-priority runner detects.',
+    installHint: INSTALL_HINT,
+    detect,
+    generateBrief,
+    executeBrief,
+    validateOutputDir,
+  },
+};