@yemi33/minions 0.1.2424 → 0.1.2425

package/engine/qa-runners/maestro.js

@@ -61,13 +61,15 @@ function generateBrief(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 testDir = opts.testDir || `engine/qa-tests/${sessionId}`;
+  const testFile = opts.testFile || path.join(testDir, 'flow.yaml');
   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:`,
+    `Write a single Maestro flow file at \`${testFile}\` that exercises:`,
     '',
     flows.trim(),
     '',
@@ -92,12 +94,14 @@ function generateBrief(opts) {
 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 testDir = opts.testDir || `engine/qa-tests/${sessionId}`;
+  const testFile = opts.testFile || path.join(testDir, 'flow.yaml');
   const capture = opts.capture || {};
-  const outputDir = `engine/qa-artifacts/${sessionId}`;
+  const outputDir = opts.artifactsDir || `engine/qa-artifacts/${sessionId}`;
+  const resultSidecar = opts.resultSidecar || 'agents/<your-id>/qa-run-result.json';
 
-  const cmdFlags = [`--output ${outputDir}`];
-  if (capture.logs) cmdFlags.push(`--debug-output ${outputDir}/maestro-debug`);
+  const cmdFlags = [`--output "${outputDir}"`];
+  if (capture.logs) cmdFlags.push(`--debug-output "${path.join(outputDir, 'maestro-debug')}"`);
   // `maestro test` does not support video; surface the limitation in the
   // brief body rather than silently dropping the capture request.
 
@@ -107,10 +111,10 @@ function executeBrief(opts) {
     'Run the drafted flow against the live managed-spawn:',
     '',
     '```bash',
-    `maestro test ${testFile} ${cmdFlags.join(' ')}`,
+    `maestro test "${testFile}" ${cmdFlags.join(' ')}`,
     '```',
     '',
-    `Write the result sidecar to \`agents/<your-id>/qa-run-result.json\` referencing artifacts under \`${outputDir}/\`.`,
+    `Write the result sidecar to \`${resultSidecar}\` after storing 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.'
       : '',

package/engine/qa-runners/playwright.js

@@ -16,6 +16,7 @@
  */
 
 const fs = require('fs');
+const path = require('path');
 
 const NAME = 'playwright';
 const PRIORITY = 50;
@@ -48,20 +49,25 @@ function generateBrief(opts) {
   const ports = _portsLabel(opts.spawnInfo);
   const flows = opts.flowsRaw || '(no flows provided)';
   const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const testDir = opts.testDir || `engine/qa-tests/${sessionId}`;
+  const testFile = opts.testFile || path.join(testDir, 'test.spec.js');
   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:`,
+    `Write a single Playwright test at \`${testFile}\` that exercises:`,
     '',
     flows.trim(),
     '',
     '### Required structure',
     '',
     '```js',
-    "const { test, expect } = require('@playwright/test');",
+    "const { createRequire } = require('module');",
+    "const path = require('path');",
+    "const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));",
+    "const { test, expect } = projectRequire('@playwright/test');",
     '',
     "test('qa-session flow', async ({ page }) => {",
     baseUrl
@@ -79,22 +85,30 @@ function generateBrief(opts) {
     '',
     '### 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).',
+    `Requested artifacts: ${captureSummary}. The EXECUTE phase writes Playwright \`use.video\`, ` +
+      '`use.screenshot`, and `use.trace` options into its runner config. The test file itself should NOT hard-code recording.',
   ].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 testDir = opts.testDir || `engine/qa-tests/${sessionId}`;
+  const testFile = opts.testFile || path.join(testDir, '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 outputDir = opts.artifactsDir || `engine/qa-artifacts/${sessionId}`;
+  const resultSidecar = opts.resultSidecar || 'agents/<your-id>/qa-run-result.json';
+  const configPath = path.join(testDir, 'playwright.config.cjs');
+  const use = {};
+  if (capture.video) use.video = 'on';
+  if (capture.screenshots) use.screenshot = 'on';
+  if (capture.logs) use.trace = 'on';
+  const configSource = `module.exports = ${JSON.stringify({
+    testDir,
+    outputDir,
+    reporter: 'json',
+    use,
+  }, null, 2)};`;
 
   const artifactTypes = [];
   if (capture.video) artifactTypes.push('`video` (webm)');
@@ -105,13 +119,22 @@ function executeBrief(opts) {
   return [
     '## Playwright execute',
     '',
-    'Run the drafted test against the live managed-spawn:',
+    `Write this Playwright config to \`${configPath}\`:`,
+    '',
+    '```js',
+    configSource,
+    '```',
+    '',
+    'Then run the drafted test from the target project worktree against the live managed-spawn:',
     '',
     '```bash',
-    `npx playwright test ${testFile} ${flags.join(' ')}`,
+    `npx playwright test --config "${configPath}"`,
     '```',
     '',
-    `Write the result sidecar to \`agents/<your-id>/qa-run-result.json\` referencing artifacts under \`${outputDir}/\`.`,
+    `Drafted file: \`${testFile}\`. The config scopes discovery to this QA session.`,
+    '',
+    `Write the result sidecar to \`${resultSidecar}\` after storing artifacts under \`${outputDir}\`.`,
+    `Record artifact paths relative to \`${outputDir}\`, preserving any nested Playwright output directories.`,
     '',
     `Artifact types: ${artifactTypes.join(', ')}`,
   ].join('\n');

package/engine/qa-runners.js

@@ -11,22 +11,21 @@
  *
  *   detect(target, project)          → boolean. Inspect the target/project
  *                                      and return true when this runner is
- *                                      the right choice (e.g. a Playwright
- *                                      adapter returns true when the project
- *                                      has playwright.config.* in its repo).
+ *                                      the right choice.
  *   generateBrief(opts)              → string|object. Produces the
  *                                      instructions handed to the DRAFT
  *                                      agent so it emits a runner-native
  *                                      test file under engine/qa-tests/<id>/.
  *   executeBrief(opts)               → result. Produces the instructions /
- *                                      command the EXECUTE agent runs to
- *                                      invoke the drafted test against the
- *                                      live managed-spawn target.
+ *                                      command the EXECUTE agent runs from
+ *                                      opts.testDir (opts.testFile identifies
+ *                                      the draft), writing to opts.artifactsDir
+ *                                      and opts.resultSidecar.
  *   validateOutputDir(dir)           → { ok: boolean, errors: string[] }.
- *                                      Called after DRAFT lands a test file
- *                                      to confirm the runner-native artifact
- *                                      is present before allowing EXECUTE
- *                                      to schedule.
+ *                                      Available to callers that want to
+ *                                      validate a drafted runner artifact;
+ *                                      the core DRAFT transition does not
+ *                                      invoke it automatically today.
  *   installHint                      → string. Human-readable instructions
  *                                      shown to the user when detect()
  *                                      returns true but the runner CLI is

package/engine/qa-runs.js

@@ -8,7 +8,7 @@
  * Persistence: SQLite (engine/state.db, `qa_runs` table). 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>.
+ * through GET /api/qa/artifacts/<runId>/<path>.
  *
  * Concurrency: every mutation goes through shared.mutateQaRuns, which routes
  * to small-state-store.applyQaRunsMutation inside a SQLite transaction
@@ -37,6 +37,10 @@ const { mutateQaRuns, uid, ts, log } = shared;
 // threshold; terminal-status runs that have already shipped completion
 // notifications are safe to drop.
 const QA_RUNS_MAX_RECORDS = 2000;
+const QA_RUN_ID_MAX = 128;
+const QA_ARTIFACT_PATH_MAX = 2048;
+const QA_ARTIFACT_SEGMENT_MAX = 255;
+const QA_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
 const QA_RUN_STATUS = Object.freeze({
   PENDING: 'pending',
@@ -85,9 +89,87 @@ function qaArtifactsDir() {
 }
 
 function qaArtifactsDirForRun(runId) {
+  if (!_isSafeRunId(runId)) throw new Error('qa-runs: invalid artifact run id: ' + runId);
   return path.join(qaArtifactsDir(), runId);
 }
 
+function resultSidecarPath(agentId) {
+  const segment = typeof agentId === 'string' ? agentId : '';
+  if (!segment || segment.length > 128 || !/^[a-zA-Z0-9._-]+$/.test(segment)
+      || segment === '.' || segment === '..') {
+    throw new Error(`qa-runs: invalid agent id for result sidecar: ${agentId}`);
+  }
+  return path.join(shared.MINIONS_DIR, 'agents', segment, 'qa-run-result.json');
+}
+
+function prepareResultSidecar(agentId, runId) {
+  if (!_isSafeRunId(runId)) {
+    throw new Error(`qa-runs: invalid run id for result sidecar: ${runId}`);
+  }
+  const filePath = resultSidecarPath(agentId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  try {
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw new Error(`qa-runs: could not clear result sidecar for ${runId}: ${err.message}`);
+    }
+  }
+  return filePath;
+}
+
+function consumeResultSidecar(agentId, expectedRunId) {
+  if (!_isSafeRunId(expectedRunId)) {
+    throw new Error(`qa-runs: invalid expected run id for result sidecar: ${expectedRunId}`);
+  }
+  const filePath = resultSidecarPath(agentId);
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return {
+      ok: false,
+      reason: err.code === 'ENOENT' ? 'missing' : 'read-error',
+      detail: err.code === 'ENOENT' ? '' : err.message,
+      filePath,
+    };
+  }
+
+  let outcome;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      outcome = { ok: false, reason: 'malformed', detail: 'expected a JSON object', filePath };
+    } else if (parsed.runId !== expectedRunId) {
+      outcome = {
+        ok: false,
+        reason: 'run-id-mismatch',
+        actualRunId: parsed.runId,
+        expectedRunId,
+        filePath,
+      };
+    } else if (!TERMINAL_STATUSES.has(parsed.status)) {
+      outcome = {
+        ok: false,
+        reason: 'invalid-status',
+        status: parsed.status,
+        filePath,
+      };
+    } else {
+      outcome = { ok: true, parsed, filePath };
+    }
+  } catch (err) {
+    outcome = { ok: false, reason: 'malformed', detail: err.message, filePath };
+  }
+
+  try {
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') outcome.cleanupError = err.message;
+  }
+  return outcome;
+}
+
 function isValidStatus(status) {
   return Object.values(QA_RUN_STATUS).includes(status);
 }
@@ -114,6 +196,16 @@ function normalizeArtifact(a) {
   };
 }
 
+function createRunId() {
+  return 'qarun-' + uid();
+}
+
+function _trimRunsToLimit(runs) {
+  if (runs.length <= QA_RUNS_MAX_RECORDS) return runs;
+  runs.sort((a, b) => ((a && a.createdAt) || '').localeCompare((b && b.createdAt) || ''));
+  return runs.slice(runs.length - QA_RUNS_MAX_RECORDS);
+}
+
 /**
  * Create a new run record in 'pending' status. Also pre-creates the per-run
  * artifact directory so the agent can drop files into it.
@@ -125,12 +217,14 @@ function normalizeArtifact(a) {
  * @param {string} [opts.workItemId] - originating work-item id (optional)
  * @returns {object} the created run record
  */
-function createRun({ runbookId, targetName, project, workItemId } = {}) {
+function createRun({ id, runbookId, targetName, project, workItemId, deferRotation = false } = {}) {
   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 runId = id || createRunId();
+  if (!_isSafeRunId(runId)) throw new Error('qa-runs: invalid run id: ' + runId);
 
   const run = {
-    id: 'qarun-' + uid(),
+    id: runId,
     runbookId,
     targetName,
     project: project || null,
@@ -143,17 +237,19 @@ function createRun({ runbookId, targetName, project, workItemId } = {}) {
     createdAt: ts(),
   };
 
+  let duplicate = false;
   mutateQaRuns((runs) => {
     if (!Array.isArray(runs)) runs = [];
+    if (runs.some(existing => existing && existing.id === run.id)) {
+      duplicate = true;
+      return runs;
+    }
     runs.push(run);
     // Rotation: drop oldest-by-createdAt when over the cap. Cheap because
     // this runs only on createRun, not on every read.
-    if (runs.length > QA_RUNS_MAX_RECORDS) {
-      runs.sort((a, b) => ((a && a.createdAt) || '').localeCompare((b && b.createdAt) || ''));
-      runs = runs.slice(runs.length - QA_RUNS_MAX_RECORDS);
-    }
-    return runs;
+    return deferRotation ? runs : _trimRunsToLimit(runs);
   });
+  if (duplicate) throw new Error('qa-runs: run id already exists: ' + run.id);
 
   // Pre-create the artifact directory outside the lock — directory creation
   // is idempotent and slow file I/O must never run while holding the lock.
@@ -164,6 +260,17 @@ function createRun({ runbookId, targetName, project, workItemId } = {}) {
   return run;
 }
 
+function pruneRunsToLimit() {
+  let removed = 0;
+  mutateQaRuns((runs) => {
+    if (!Array.isArray(runs)) return [];
+    const trimmed = _trimRunsToLimit(runs);
+    removed = runs.length - trimmed.length;
+    return trimmed;
+  });
+  return removed;
+}
+
 /**
  * Transition pending -> running. Stamps startedAt. Throws on illegal source state.
  * @param {string} id
@@ -321,12 +428,12 @@ function setRunWorkItemId(id, workItemId) {
 // DELETE endpoints take ids from URL paths, so every callsite re-validates.
 function _isSafeRunId(id) {
   if (!id || typeof id !== 'string') return false;
-  if (id.length > 128) return false;
+  if (id.length > QA_RUN_ID_MAX) return false;
   if (id.indexOf('\0') >= 0) return false;
   if (id.indexOf('/') >= 0 || id.indexOf('\\') >= 0) return false;
   if (id.indexOf('..') >= 0) return false;
   if (/^[a-zA-Z]:/.test(id)) return false;
-  return true;
+  return QA_RUN_ID_RE.test(id);
 }
 
 /**
@@ -372,7 +479,7 @@ function deleteQaRun(id) {
     const dir = qaArtifactsDirForRun(id);
     const base = path.resolve(qaArtifactsDir());
     const resolved = path.resolve(dir);
-    if (resolved.startsWith(base + path.sep) || resolved === base) {
+    if (resolved.startsWith(base + path.sep)) {
       if (fs.existsSync(resolved)) {
         fs.rmSync(resolved, { recursive: true, force: true });
         artifactsRemoved = true;
@@ -412,7 +519,10 @@ module.exports = {
   ALLOWED_TRANSITIONS,
   qaArtifactsDir,
   qaArtifactsDirForRun,
+  resultSidecarPath, prepareResultSidecar, consumeResultSidecar, // exported for testing
   createRun,
+  createRunId,
+  pruneRunsToLimit,
   markRunning,
   completeRun,
   setRunWorkItemId,
@@ -426,4 +536,7 @@ module.exports = {
   validateTransition,
   isValidStatus,
   QA_RUNS_MAX_RECORDS,
+  QA_RUN_ID_MAX,
+  QA_ARTIFACT_PATH_MAX,
+  QA_ARTIFACT_SEGMENT_MAX,
 };