@flowspec-qa/runner-core 0.1.0

package/dist/suite-manager.d.ts

@@ -0,0 +1,25 @@
+export interface LocalSuite {
+    runId: string;
+    entityId: string;
+    framework: 'playwright' | 'cypress' | 'maestro';
+    suiteDir: string;
+    downloadedAt: Date;
+}
+/**
+ * Download a suite ZIP from FlowSpecQA SaaS and unzip it to the local cache.
+ * Returns the path to the unzipped suite directory.
+ */
+export declare function downloadSuite(suiteId: string, entityId: string, framework: string): Promise<LocalSuite>;
+/**
+ * List all locally cached suites.
+ */
+export declare function listCachedSuites(): Array<{
+    entityId: string;
+    runId: string;
+    suiteDir: string;
+}>;
+/**
+ * Remove a cached suite directory.
+ */
+export declare function evictSuite(entityId: string, runId: string): void;
+//# sourceMappingURL=suite-manager.d.ts.map

package/dist/suite-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite-manager.d.ts","sourceRoot":"","sources":["../src/suite-manager.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,YAAY,GAAG,SAAS,GAAG,SAAS,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,IAAI,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA4B7G;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAa/F;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGhE"}

package/dist/suite-manager.js

@@ -0,0 +1,60 @@
+import AdmZip from 'adm-zip';
+import fs from 'fs';
+import path from 'path';
+import { config } from './config.js';
+import { FlowSpecQAApi } from './api-client.js';
+/**
+ * Download a suite ZIP from FlowSpecQA SaaS and unzip it to the local cache.
+ * Returns the path to the unzipped suite directory.
+ */
+export async function downloadSuite(suiteId, entityId, framework) {
+    const cacheDir = config.get('suiteCacheDir');
+    const suiteDir = path.join(cacheDir, entityId, suiteId);
+    // Avoid re-downloading if already cached
+    if (fs.existsSync(path.join(suiteDir, 'package.json'))) {
+        return {
+            runId: suiteId,
+            entityId,
+            framework: framework,
+            suiteDir,
+            downloadedAt: fs.statSync(suiteDir).mtime,
+        };
+    }
+    const zipBuffer = await FlowSpecQAApi.downloadSuiteZip(suiteId);
+    fs.mkdirSync(suiteDir, { recursive: true });
+    const zip = new AdmZip(zipBuffer);
+    zip.extractAllTo(suiteDir, /* overwrite */ true);
+    return {
+        runId: suiteId,
+        entityId,
+        framework: framework,
+        suiteDir,
+        downloadedAt: new Date(),
+    };
+}
+/**
+ * List all locally cached suites.
+ */
+export function listCachedSuites() {
+    const cacheDir = config.get('suiteCacheDir');
+    if (!fs.existsSync(cacheDir))
+        return [];
+    const result = [];
+    for (const entityId of fs.readdirSync(cacheDir)) {
+        const entityDir = path.join(cacheDir, entityId);
+        if (!fs.statSync(entityDir).isDirectory())
+            continue;
+        for (const runId of fs.readdirSync(entityDir)) {
+            result.push({ entityId, runId, suiteDir: path.join(entityDir, runId) });
+        }
+    }
+    return result;
+}
+/**
+ * Remove a cached suite directory.
+ */
+export function evictSuite(entityId, runId) {
+    const suiteDir = path.join(config.get('suiteCacheDir'), entityId, runId);
+    fs.rmSync(suiteDir, { recursive: true, force: true });
+}
+//# sourceMappingURL=suite-manager.js.map

package/dist/suite-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite-manager.js","sourceRoot":"","sources":["../src/suite-manager.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAUhD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe,EAAE,QAAgB,EAAE,SAAiB;IACtF,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAExD,yCAAyC;IACzC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO;YACL,KAAK,EAAE,OAAO;YACd,QAAQ;YACR,SAAS,EAAE,SAAoC;YAC/C,QAAQ;YACR,YAAY,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK;SAC1C,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAChE,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE5C,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC;IAClC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC;IAEjD,OAAO;QACL,KAAK,EAAE,OAAO;QACd,QAAQ;QACR,SAAS,EAAE,SAAoC;QAC/C,QAAQ;QACR,YAAY,EAAE,IAAI,IAAI,EAAE;KACzB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IAExC,MAAM,MAAM,GAAiE,EAAE,CAAC;IAChF,KAAK,MAAM,QAAQ,IAAI,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAChD,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;YAAE,SAAS;QACpD,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9C,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,KAAa;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IACzE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AACxD,CAAC"}

package/dist/uploader.d.ts

@@ -0,0 +1,16 @@
+import type { ExecutionResult } from './executor.js';
+export interface UploadOptions {
+    runId: string;
+    entityId: string;
+    framework: string;
+    envLabel: string;
+    skipSecurityCheck?: boolean;
+}
+/**
+ * Sanitize + upload test results to FlowSpecQA SaaS.
+ * Returns the exec_id assigned by the server.
+ */
+export declare function uploadResults(execution: ExecutionResult, options: UploadOptions): Promise<{
+    execId: string;
+}>;
+//# sourceMappingURL=uploader.d.ts.map

package/dist/uploader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploader.d.ts","sourceRoot":"","sources":["../src/uploader.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIrD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAuB7B"}

package/dist/uploader.js

@@ -0,0 +1,29 @@
+import { FlowSpecQAApi } from './api-client.js';
+import { sanitizeResults, assertNoSecrets } from './result-sanitizer.js';
+const RUNNER_VERSION = '0.1.0';
+/**
+ * Sanitize + upload test results to FlowSpecQA SaaS.
+ * Returns the exec_id assigned by the server.
+ */
+export async function uploadResults(execution, options) {
+    // Step 1: Sanitize — strip URLs, IPs, tokens from error messages
+    const sanitized = sanitizeResults(execution.results);
+    // Step 2: Belt-and-suspenders security check
+    if (!options.skipSecurityCheck) {
+        assertNoSecrets(sanitized);
+    }
+    // Step 3: Build payload
+    const payload = {
+        run_id: options.runId,
+        entity_id: options.entityId,
+        framework: options.framework,
+        env_label: options.envLabel,
+        results: sanitized,
+        started_at: execution.startedAt.toISOString(),
+        finished_at: execution.finishedAt.toISOString(),
+        runner_version: RUNNER_VERSION,
+    };
+    const response = await FlowSpecQAApi.submitRunResult(payload);
+    return { execId: response.exec_id };
+}
+//# sourceMappingURL=uploader.js.map

package/dist/uploader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uploader.js","sourceRoot":"","sources":["../src/uploader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAyB,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGzE,MAAM,cAAc,GAAG,OAAO,CAAC;AAU/B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,SAA0B,EAC1B,OAAsB;IAEtB,iEAAiE;IACjE,MAAM,SAAS,GAAG,eAAe,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAErD,6CAA6C;IAC7C,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;QAC/B,eAAe,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,wBAAwB;IACxB,MAAM,OAAO,GAAqB;QAChC,MAAM,EAAE,OAAO,CAAC,KAAK;QACrB,SAAS,EAAE,OAAO,CAAC,QAAQ;QAC3B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,QAAQ;QAC3B,OAAO,EAAE,SAAS;QAClB,UAAU,EAAE,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE;QAC7C,WAAW,EAAE,SAAS,CAAC,UAAU,CAAC,WAAW,EAAE;QAC/C,cAAc,EAAE,cAAc;KAC/B,CAAC;IAEF,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IAC9D,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;AACtC,CAAC"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@flowspec-qa/runner-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Core modules for FlowSpecQA Runner — auth, suite download, execution, upload",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.10",
+    "axios": "^1.6.0",
+    "chalk": "^5.3.0",
+    "conf": "^12.0.0",
+    "execa": "^8.0.1",
+    "fast-xml-parser": "^5.5.8"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.5"
+  }
+}

package/src/api-client.ts

@@ -0,0 +1,118 @@
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+import { config } from './config.js';
+
+// Lazy singleton — created on first use so baseUrl is read after config is loaded
+let _client: AxiosInstance | null = null;
+
+function getClient(): AxiosInstance {
+  if (!_client) {
+    _client = axios.create({
+      baseURL: config.get('baseUrl'),
+      timeout: 30_000,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    // Attach Bearer token (API Key) to every request
+    _client.interceptors.request.use((req) => {
+      const apiKey = config.get('apiKey');
+      if (apiKey) {
+        req.headers['Authorization'] = `Bearer ${apiKey}`;
+      }
+      return req;
+    });
+
+    // Normalize error messages
+    _client.interceptors.response.use(
+      (res) => res,
+      (err) => {
+        const msg = err.response?.data?.detail || err.response?.data?.message || err.message;
+        return Promise.reject(new Error(msg));
+      }
+    );
+  }
+  return _client;
+}
+
+export const apiClient = {
+  async get<T>(url: string, cfg?: AxiosRequestConfig): Promise<T> {
+    const res = await getClient().get<T>(url, cfg);
+    return res.data;
+  },
+  async post<T>(url: string, data?: unknown, cfg?: AxiosRequestConfig): Promise<T> {
+    const res = await getClient().post<T>(url, data, cfg);
+    return res.data;
+  },
+  async getStream(url: string): Promise<NodeJS.ReadableStream> {
+    const res = await getClient().get(url, { responseType: 'stream' });
+    return res.data as NodeJS.ReadableStream;
+  },
+  async getArrayBuffer(url: string): Promise<Buffer> {
+    const res = await getClient().get(url, { responseType: 'arraybuffer' });
+    return Buffer.from(res.data as ArrayBuffer);
+  },
+
+  /** Update base URL at runtime (e.g. pointing to a self-hosted instance) */
+  setBaseUrl(url: string): void {
+    config.set('baseUrl', url);
+    _client = null; // force recreation
+  },
+};
+
+// ─── Typed API methods ─────────────────────────────────────────────────────
+
+export interface Project {
+  id: string;
+  name: string;
+  entity_count?: number;
+}
+
+export interface Suite {
+  entity_id: string;
+  entity_title: string;
+  suite_id: string;          // TestSuite.id — used to download files
+  framework: 'playwright' | 'cypress' | 'maestro';
+  mode?: string;
+  status?: string;
+  created_at?: string;
+}
+
+export const FlowSpecQAApi = {
+  async listProjects(): Promise<Project[]> {
+    return apiClient.get<Project[]>('/api/config/projects');
+  },
+
+  async listSuites(entityId?: string): Promise<Suite[]> {
+    const url = entityId
+      ? `/api/automation/suites?entity_id=${entityId}`
+      : '/api/automation/suites';
+    const resp = await apiClient.get<{ suites: Suite[]; total: number }>(url);
+    return resp.suites ?? [];
+  },
+
+  /** Download the ZIP of generated test files for a suite (suite_id = TestSuite.id) */
+  async downloadSuiteZip(suiteId: string): Promise<Buffer> {
+    return apiClient.getArrayBuffer(`/api/automation/download-suite/${suiteId}`);
+  },
+
+  async submitRunResult(payload: RunResultPayload): Promise<{ ok: boolean; exec_id: string }> {
+    return apiClient.post('/api/automation/submit-run-result', payload);
+  },
+};
+
+export interface RunResultPayload {
+  run_id: string;
+  entity_id: string;
+  framework: string;
+  env_label: string;
+  results: TestResultItem[];
+  started_at: string;
+  finished_at: string;
+  runner_version: string;
+}
+
+export interface TestResultItem {
+  name: string;
+  status: 'pass' | 'fail' | 'skip';
+  duration_ms: number;
+  error?: string | null;
+}

package/src/auth.ts

@@ -0,0 +1,45 @@
+import { config } from './config.js';
+
+export interface AuthStatus {
+  authenticated: boolean;
+  maskedKey?: string;
+}
+
+/**
+ * Store the API Key locally and test it against the SaaS.
+ * Keys use the format: sk-smrt-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ */
+export async function login(apiKey: string): Promise<void> {
+  if (!apiKey.startsWith('sk-smrt-')) {
+    throw new Error('Invalid API Key format. Keys should start with "sk-smrt-"');
+  }
+  config.set('apiKey', apiKey);
+  // Validate immediately by making a test call
+  const { apiClient } = await import('./api-client.js');
+  await apiClient.get('/api/config/projects'); // throws if key is invalid
+}
+
+export function logout(): void {
+  config.set('apiKey', undefined);
+}
+
+export function getAuthStatus(): AuthStatus {
+  const apiKey = config.get('apiKey');
+  if (!apiKey) return { authenticated: false };
+  return {
+    authenticated: true,
+    maskedKey: apiKey.slice(0, 12) + '*'.repeat(Math.max(0, apiKey.length - 12)),
+  };
+}
+
+/**
+ * Return the API Key to use as Bearer token.
+ * The SaaS get_api_key_context dependency accepts: Authorization: Bearer sk-smrt-xxx
+ */
+export function getBearerToken(): string {
+  const apiKey = config.get('apiKey');
+  if (!apiKey) {
+    throw new Error('Not authenticated. Run: flowspecqa auth login');
+  }
+  return apiKey;
+}

package/src/config.ts

@@ -0,0 +1,52 @@
+import Conf from 'conf';
+import path from 'path';
+import os from 'os';
+
+export interface RunnerConfig {
+  apiKey?: string;
+  runnerToken?: string;
+  runnerTokenExpiry?: string; // ISO date
+  baseUrl: string;
+  suiteCacheDir: string;
+  sanitizerPatterns: string[];
+}
+
+const DEFAULT_CONFIG: RunnerConfig = {
+  baseUrl: 'https://www.flowspecqa.com',
+  suiteCacheDir: path.join(os.homedir(), '.flowspecqa', 'suites'),
+  sanitizerPatterns: [
+    // Strip URLs, IPs, auth tokens from error messages before upload
+    'https?://[^\\s]+',
+    '\\b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\b',
+    'Bearer\\s+[A-Za-z0-9.\\-_]+',
+    'Authorization:\\s*[^\\r\\n]+',
+    'password["\']?\\s*[:=]\\s*["\']?[^"\'\\s&]+',
+  ],
+};
+
+const conf = new Conf<RunnerConfig>({
+  projectName: 'flowspecqa-runner',
+  defaults: DEFAULT_CONFIG,
+});
+
+export const config = {
+  get<K extends keyof RunnerConfig>(key: K): RunnerConfig[K] {
+    return conf.get(key) as RunnerConfig[K];
+  },
+
+  set<K extends keyof RunnerConfig>(key: K, value: RunnerConfig[K]): void {
+    conf.set(key, value);
+  },
+
+  getAll(): RunnerConfig {
+    return conf.store as RunnerConfig;
+  },
+
+  clear(): void {
+    conf.clear();
+  },
+
+  get configPath(): string {
+    return conf.path;
+  },
+};

package/src/executor.ts

@@ -0,0 +1,275 @@
+import { execa, ExecaError } from 'execa';
+import path from 'path';
+import { existsSync } from 'fs';
+import type { TestResultItem } from './api-client.js';
+
+export interface ExecutionOptions {
+  env?: Record<string, string>;   // Environment vars (base URLs, tokens — stay local, never uploaded)
+  timeout?: number;               // ms, default 10 min
+  workers?: number;               // Playwright workers
+  headed?: boolean;               // Run headed (useful for debugging)
+  reporter?: string;              // Playwright reporter override
+  grepPattern?: string;           // Run only matching tests
+}
+
+export interface ExecutionResult {
+  exitCode: number;
+  results: TestResultItem[];
+  startedAt: Date;
+  finishedAt: Date;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Execute a Playwright test suite and parse the results.
+ */
+export async function executePlaywright(
+  suiteDir: string,
+  options: ExecutionOptions = {}
+): Promise<ExecutionResult> {
+  const startedAt = new Date();
+
+  // Install deps if node_modules missing
+  if (!isNodeModulesPresent(suiteDir)) {
+    await execa('npm', ['install', '--prefer-offline'], {
+      cwd: suiteDir,
+      env: { ...process.env, ...(options.env ?? {}) },
+    });
+  }
+
+  const args = ['playwright', 'test',
+    '--reporter=json',
+    ...(options.workers ? [`--workers=${options.workers}`] : []),
+    ...(options.headed ? ['--headed'] : []),
+    ...(options.grepPattern ? [`--grep`, options.grepPattern] : []),
+  ];
+
+  let stdout = '';
+  let stderr = '';
+  let exitCode = 0;
+
+  try {
+    const result = await execa('npx', args, {
+      cwd: suiteDir,
+      env: { ...process.env, ...(options.env ?? {}) },
+      timeout: options.timeout ?? 600_000,
+      reject: false, // don't throw on test failures
+    });
+    stdout = result.stdout;
+    stderr = result.stderr;
+    exitCode = result.exitCode ?? 1;
+  } catch (err) {
+    const e = err as ExecaError;
+    stdout = e.stdout ?? '';
+    stderr = e.stderr ?? e.message;
+    exitCode = e.exitCode ?? 1;
+  }
+
+  const finishedAt = new Date();
+  const results = parsePlaywrightJson(stdout);
+
+  return { exitCode, results, startedAt, finishedAt, stdout, stderr };
+}
+
+/**
+ * Execute a Cypress test suite.
+ */
+export async function executeCypress(
+  suiteDir: string,
+  options: ExecutionOptions = {}
+): Promise<ExecutionResult> {
+  const startedAt = new Date();
+
+  if (!isNodeModulesPresent(suiteDir)) {
+    await execa('npm', ['install', '--prefer-offline'], { cwd: suiteDir });
+  }
+
+  const args = ['cypress', 'run', '--reporter=json',
+    ...(options.headed ? ['--headed'] : ['--headless']),
+  ];
+
+  let stdout = '';
+  let stderr = '';
+  let exitCode = 0;
+
+  try {
+    const result = await execa('npx', args, {
+      cwd: suiteDir,
+      env: { ...process.env, ...(options.env ?? {}) },
+      timeout: options.timeout ?? 600_000,
+      reject: false,
+    });
+    stdout = result.stdout;
+    stderr = result.stderr;
+    exitCode = result.exitCode ?? 1;
+  } catch (err) {
+    const e = err as ExecaError;
+    stdout = e.stdout ?? '';
+    stderr = e.stderr ?? e.message;
+    exitCode = e.exitCode ?? 1;
+  }
+
+  const finishedAt = new Date();
+  return { exitCode, results: parseCypressJson(stdout), startedAt, finishedAt, stdout, stderr };
+}
+
+// ─── Parsers ─────────────────────────────────────────────────────────────────
+
+function parsePlaywrightJson(stdout: string): TestResultItem[] {
+  try {
+    // Playwright --reporter=json outputs JSON on stdout
+    const json = extractJson(stdout);
+    if (!json) return [];
+    const suites = json.suites ?? [];
+    const items: TestResultItem[] = [];
+    collectPlaywrightSpecs(suites, items);
+    return items;
+  } catch {
+    return [];
+  }
+}
+
+function collectPlaywrightSpecs(suites: any[], items: TestResultItem[]): void {
+  for (const suite of suites) {
+    for (const spec of suite.specs ?? []) {
+      for (const test of spec.tests ?? []) {
+        const result = test.results?.[0];
+        items.push({
+          name: spec.title,
+          status: result?.status === 'passed' ? 'pass' : result?.status === 'skipped' ? 'skip' : 'fail',
+          duration_ms: result?.duration ?? 0,
+          error: result?.error?.message ?? null,
+        });
+      }
+    }
+    collectPlaywrightSpecs(suite.suites ?? [], items);
+  }
+}
+
+function parseCypressJson(stdout: string): TestResultItem[] {
+  try {
+    const json = extractJson(stdout);
+    if (!json) return [];
+    return (json.results ?? []).flatMap((r: any) =>
+      (r.tests ?? []).map((t: any) => ({
+        name: t.fullTitle ?? t.title,
+        status: t.state === 'passed' ? 'pass' : t.state === 'pending' ? 'skip' : 'fail',
+        duration_ms: t.duration ?? 0,
+        error: t.err?.message ?? null,
+      }))
+    );
+  } catch {
+    return [];
+  }
+}
+
+function extractJson(text: string): any | null {
+  const match = text.match(/\{[\s\S]*\}/);
+  if (!match) return null;
+  return JSON.parse(match[0]);
+}
+
+function isNodeModulesPresent(dir: string): boolean {
+  return existsSync(path.join(dir, 'node_modules'));
+}
+
+/**
+ * Execute a Maestro test suite (iOS/Android YAML flows) and parse JUnit XML results.
+ * Requires: Maestro CLI installed globally (`curl -Ls 'https://get.maestro.mobile.dev' | bash`)
+ * No npm install step — Maestro uses its own runtime.
+ */
+export async function executeMaestro(
+  suiteDir: string,
+  options: ExecutionOptions = {}
+): Promise<ExecutionResult> {
+  const startedAt = new Date();
+  const reportPath = path.join(suiteDir, 'report.xml');
+  const flowsDir = path.join(suiteDir, 'flows');
+
+  const args = [
+    'test',
+    '--format', 'junit',
+    '--output', reportPath,
+    existsSync(flowsDir) ? flowsDir : suiteDir,
+  ];
+
+  let stdout = '';
+  let stderr = '';
+  let exitCode = 0;
+
+  try {
+    const proc = await execa('maestro', args, {
+      cwd: suiteDir,
+      env: { ...process.env, ...(options.env ?? {}) },
+      reject: false,
+      timeout: options.timeout ?? 10 * 60 * 1000,
+    });
+    stdout = proc.stdout ?? '';
+    stderr = proc.stderr ?? '';
+    exitCode = proc.exitCode ?? 0;
+  } catch (err) {
+    const execaErr = err as ExecaError;
+    stdout = execaErr.stdout ?? '';
+    stderr = execaErr.stderr ?? '';
+    exitCode = execaErr.exitCode ?? 1;
+  }
+
+  const finishedAt = new Date();
+  const results = parseMaestroXml(reportPath);
+
+  return { exitCode, results, startedAt, finishedAt, stdout, stderr };
+}
+
+/**
+ * Parse Maestro JUnit XML report into TestResultItem[].
+ * Format: <testsuite><testcase name="..." time="2.3"><failure message="..."/></testcase></testsuite>
+ */
+function parseMaestroXml(reportPath: string): TestResultItem[] {
+  if (!existsSync(reportPath)) return [];
+
+  try {
+    const { XMLParser } = require('fast-xml-parser');
+    const { readFileSync } = require('fs');
+    const xml = readFileSync(reportPath, 'utf-8');
+    const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_' });
+    const doc = parser.parse(xml);
+
+    // Support both <testsuites> (wrapper) and bare <testsuite>
+    const suites = doc?.testsuites?.testsuite ?? doc?.testsuite;
+    const suiteArray = Array.isArray(suites) ? suites : suites ? [suites] : [];
+
+    const items: TestResultItem[] = [];
+
+    for (const suite of suiteArray) {
+      const testcases = suite?.testcase;
+      const cases = Array.isArray(testcases) ? testcases : testcases ? [testcases] : [];
+
+      for (const tc of cases) {
+        const name: string = tc['@_name'] ?? tc['@_classname'] ?? 'unknown';
+        const timeStr: string = tc['@_time'] ?? '0';
+        const duration_ms = Math.round(parseFloat(timeStr) * 1000);
+
+        const hasFailure = tc.failure !== undefined;
+        const hasSkipped = tc.skipped !== undefined;
+        const failureMsg: string | null =
+          typeof tc.failure === 'object'
+            ? tc.failure['@_message'] ?? null
+            : typeof tc.failure === 'string'
+            ? tc.failure
+            : null;
+
+        items.push({
+          name,
+          status: hasFailure ? 'fail' : hasSkipped ? 'skip' : 'pass',
+          duration_ms,
+          error: hasFailure ? failureMsg : null,
+        });
+      }
+    }
+
+    return items;
+  } catch {
+    return [];
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// @flowspec-qa/runner-core — public API
+export { config, type RunnerConfig } from './config.js';
+export { login, logout, getAuthStatus, getBearerToken, type AuthStatus } from './auth.js';
+export { apiClient, FlowSpecQAApi, type Project, type Suite, type RunResultPayload, type TestResultItem } from './api-client.js';
+export { downloadSuite, listCachedSuites, evictSuite, type LocalSuite } from './suite-manager.js';
+export { executePlaywright, executeCypress, executeMaestro, type ExecutionOptions, type ExecutionResult } from './executor.js';
+export { sanitizeResults, assertNoSecrets } from './result-sanitizer.js';
+export { uploadResults, type UploadOptions } from './uploader.js';