swipium 1.0.0

package/dist/services/smoke.js

@@ -0,0 +1,120 @@
+// Smoke service (hardening P0.1) — the server-side smoke loop, extracted from the qa_smoke tool so
+// BOTH the tool and qa_test_this execute mode run the exact same path (no MCP-over-transport). It
+// launches the app, runs the deterministic baseline (snapshot quality + health + evidence shot),
+// then runs every saved flow, recording a structured qa_note per workflow.
+import { readFileSync } from 'node:fs';
+import { parseSnapshot, signature } from '../snapshot/parse.js';
+import { settle } from '../snapshot/settle.js';
+import { checkHealth } from '../oracle/health.js';
+import { recordHealthFindings } from '../oracle/record.js';
+import { listFlowFiles } from '../flows/discover.js';
+import { parseFlow } from '../flows/schema.js';
+import { runFlow } from '../flows/run.js';
+import { ciMutatingSteps } from '../ci/preflight.js';
+function externalProviderSteps(flow) {
+    const out = [];
+    [...flow.setup, ...flow.steps, ...flow.teardown].forEach((step, index) => {
+        if (step.kind === 'tapOcrText' || step.kind === 'assertOcrText')
+            out.push({ step: index + 1, kind: step.kind });
+    });
+    return out;
+}
+export async function runSmoke(sessions, session, d, opts = {}) {
+    const note = (n) => sessions.addNote(session, { at: Date.now(), ...n });
+    const doLaunch = opts.launch ?? !!session.appId;
+    const baseline = {};
+    // ---- baseline: launch → snapshot quality → health → evidence screenshot ----
+    try {
+        if (doLaunch && session.appId) {
+            await d.launchApp(session.appId);
+            await settle(d, { timeoutMs: 8000 });
+        }
+        let quality;
+        if (session.mode !== 'visual-fallback') {
+            try {
+                const parsed = parseSnapshot(await d.dumpXml());
+                session.lastSnapshot = { fullByRef: parsed.fullByRef, signatures: new Set(parsed.elements.map(signature)), allNodes: parsed.allNodes };
+                quality = parsed.quality.verdict;
+            }
+            catch {
+                /* visual-only screen — health + screenshot still run */
+            }
+        }
+        const health = await checkHealth(d, session.appId);
+        await recordHealthFindings(sessions, session, health.findings, d, health.foreground);
+        let shotUri;
+        try {
+            const png = await d.screenshot();
+            shotUri = sessions.saveArtifact(session, 'screenshot', `smoke-baseline-${Date.now()}.png`, png, 'image/png', 'qa_smoke baseline evidence');
+            sessions.bump(session, 'screenshots');
+        }
+        catch {
+            /* best-effort */
+        }
+        const outcome = !health.nativeHealthy || health.appStatus === 'error' ? 'fail' : 'pass';
+        note({
+            workflow: 'launch_smoke',
+            outcome,
+            category: outcome === 'fail' ? 'app_bug' : undefined,
+            reason: `native=${health.nativeHealthy ? 'ok' : health.nativeStatus} app=${health.appStatus}` + (quality ? ` quality=${quality}` : ''),
+            artifactUris: shotUri ? [shotUri] : undefined,
+        });
+        baseline.launch = { outcome, nativeHealth: health.nativeHealthy ? 'ok' : health.nativeStatus, appHealth: health.appStatus, quality, screenshotUri: shotUri };
+    }
+    catch (e) {
+        note({ workflow: 'launch_smoke', outcome: 'fail', category: 'mcp_limitation', reason: `baseline failed: ${String(e)}` });
+        baseline.launch = { outcome: 'fail', error: String(e) };
+    }
+    // ---- run saved flows ----
+    const flowResults = [];
+    if (opts.runFlows ?? true) {
+        for (const f of listFlowFiles(session.root)) {
+            const stop = sessions.budgetStop(session);
+            if (stop) {
+                note({ workflow: f.name, outcome: 'skipped', category: 'intentionally_skipped', reason: `budget: ${stop}` });
+                flowResults.push({ name: f.name, passed: false, reason: `skipped (budget)` });
+                continue;
+            }
+            const { flow, errors } = parseFlow(readFileSync(f.path, 'utf8'));
+            if (errors.length || !flow) {
+                note({ workflow: f.name, outcome: 'blocked', category: 'other', reason: `flow invalid: ${errors[0] ?? 'parse error'}`, requiredState: 'a valid flow file' });
+                flowResults.push({ name: f.name, passed: false, reason: 'invalid flow' });
+                continue;
+            }
+            const mutatingSteps = ciMutatingSteps(flow);
+            if (mutatingSteps.length) {
+                const reason = `mutating flow requires explicit qa_flow_run consent or CI policy: ${mutatingSteps.map((m) => `${m.step}:${m.kind}`).join(', ')}`;
+                note({ workflow: f.name, outcome: 'blocked', category: 'destructive_refused', reason, recommendedSetup: 'Run this flow with qa_flow_run and approve the flow_mutation_run consent, or run it through a CI policy that allowlists the mutation.' });
+                flowResults.push({ name: f.name, passed: false, reason });
+                continue;
+            }
+            const providerSteps = externalProviderSteps(flow);
+            if (providerSteps.length) {
+                const reason = `external visual-provider flow requires explicit qa_flow_run consent: ${providerSteps.map((m) => `${m.step}:${m.kind}`).join(', ')}`;
+                note({ workflow: f.name, outcome: 'blocked', category: 'destructive_refused', reason, recommendedSetup: 'Run this flow with qa_flow_run and approve the provider consent, or run it through reviewed CI configuration.' });
+                flowResults.push({ name: f.name, passed: false, reason });
+                continue;
+            }
+            let r;
+            try {
+                r = await runFlow(sessions, session, d, flow, { variables: opts.variables });
+            }
+            catch (e) {
+                note({ workflow: f.name, outcome: 'fail', category: 'mcp_limitation', reason: `flow run error: ${String(e)}` });
+                flowResults.push({ name: f.name, passed: false, reason: String(e) });
+                continue;
+            }
+            const failShot = r.steps.find((s) => s.screenshotUri)?.screenshotUri;
+            note({
+                workflow: f.name,
+                outcome: r.passed ? 'pass' : 'fail',
+                category: r.passed ? undefined : 'app_bug',
+                reason: r.passed ? `${r.steps.length} steps in ${r.durationSec}s` : `failed at step ${r.failedAtStep}: ${r.reason}`,
+                artifactUris: failShot ? [failShot] : undefined,
+            });
+            flowResults.push({ name: f.name, passed: r.passed, failedAtStep: r.failedAtStep, reason: r.reason });
+        }
+    }
+    return { baseline, flows: flowResults, flowsPassed: flowResults.filter((f) => f.passed).length, flowsTotal: flowResults.length };
+}
+//# sourceMappingURL=smoke.js.map

package/dist/services/smoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smoke.js","sourceRoot":"","sources":["../../src/services/smoke.ts"],"names":[],"mappings":"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"}

package/dist/services/suiteGenerate.js

@@ -0,0 +1,123 @@
+// Suite generation service (Phase 3.2 Milestone C) — generate POM files + test cases from a
+// session's recorded actions, write them under .swipium/, and (optionally) compile them to runnable
+// Flow V2. Shared by qa_suite_generate and qa_test_this execute so the autopilot
+// produces REAL files (not a note). Honest: when there are no recorded actions it returns a typed
+// `skipped` result rather than pretending a suite was created.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { generatePom } from '../suite/pom.js';
+import { generateTestCases } from '../suite/testcase.js';
+import { compileSuite } from '../suite/compile.js';
+import { parseFlow } from '../flows/schema.js';
+import { loadProjectConfig } from '../cli/scan.js';
+import { readinessForSession } from '../report/readiness.js';
+export function appIdOf(session) {
+    return session.appId ?? (loadProjectConfig(session.root)?.appId ?? undefined);
+}
+/** Write generated files under .swipium/, returning absolute paths written. */
+export function writeSuiteFiles(session, files) {
+    const base = join(session.root, '.swipium');
+    const written = [];
+    for (const f of files) {
+        const abs = join(base, f.path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, f.content);
+        written.push(abs);
+    }
+    return written;
+}
+/** Build the POM (+ flowName) for a session's recorded actions. */
+export function pomForSession(session, name, actions = session.recordedActions) {
+    const appId = appIdOf(session);
+    const flowName = (name ?? `${(appId ?? 'app').split('.').pop()}-smoke`).replace(/[^\w.-]+/g, '-');
+    const pom = generatePom(actions, { name: flowName, appId, budgetProfile: session.budgetProfile });
+    return { pom, flowName };
+}
+/**
+ * Generate (and optionally compile) a full suite from the session's recorded actions.
+ * Returns `skipped:true` honestly when there is nothing to record.
+ */
+export function generateAndCompileSuite(sessions, session, opts = {}) {
+    const actions = opts.actions ?? session.recordedActions;
+    if (!actions.length) {
+        return {
+            skipped: true,
+            skippedReason: 'no recorded actions',
+            recommendation: 'Drive the app with qa_act, qa_smoke, or qa_explore so a suite can be recorded.',
+            written: [],
+            compiledFlows: [],
+            suiteRunnable: false,
+            readinessLabels: [],
+        };
+    }
+    const save = opts.save ?? true;
+    const compile = opts.compile ?? true;
+    const { pom, flowName } = pomForSession(session, opts.name, actions);
+    const tc = generateTestCases(pom, { appId: appIdOf(session), fixtures: session.fixtures, notes: session.notes, budgetProfile: session.budgetProfile });
+    const files = [
+        ...pom.files,
+        { path: `testcases/${flowName}.cases.yaml`, content: tc.yaml },
+        { path: `testcases/${flowName}.cases.md`, content: tc.markdown },
+    ];
+    const written = save ? writeSuiteFiles(session, files) : [];
+    // Compile to runnable Flow V2 (needs the page objects on disk).
+    const compiledFlows = [];
+    if (save && compile) {
+        const result = compileSuite(session.root, 'suites/smoke.yaml');
+        const flowsDir = join(session.root, '.swipium', 'flows');
+        const compiledDir = join(session.root, '.swipium', 'compiled');
+        mkdirSync(flowsDir, { recursive: true });
+        mkdirSync(compiledDir, { recursive: true });
+        for (const f of result.flows) {
+            const slug = f.name.replace(/[^\w.-]+/g, '-');
+            const parse = f.yaml ? parseFlow(f.yaml) : { errors: ['empty'] };
+            const ok = !!f.yaml && parse.errors.length === 0 && f.errors.length === 0;
+            let flowPath;
+            let compiledPath;
+            if (ok) {
+                flowPath = join(flowsDir, `${slug}.yaml`);
+                compiledPath = join(compiledDir, `${slug}.flow.yaml`);
+                writeFileSync(flowPath, f.yaml);
+                writeFileSync(compiledPath, f.yaml);
+                written.push(flowPath, compiledPath);
+            }
+            compiledFlows.push({ name: f.name, slug, ok, flowPath, compiledPath, errors: [...f.errors, ...parse.errors] });
+        }
+    }
+    const suiteRunnable = compiledFlows.length > 0 && compiledFlows.every((c) => c.ok);
+    const readinessLabels = readinessForSession(session, { suiteRunnable });
+    if (!readinessLabels.includes('generated'))
+        readinessLabels.push('generated');
+    if (suiteRunnable && !readinessLabels.includes('compiled'))
+        readinessLabels.push('compiled');
+    let manifestPath;
+    if (save) {
+        manifestPath = join(session.root, '.swipium', 'suites', 'smoke.manifest.json');
+        writeFileSync(manifestPath, JSON.stringify({
+            schema: 'swipium.suite.manifest.v1',
+            generatedAt: new Date(session.createdAt).toISOString(),
+            name: flowName,
+            suiteFile: 'suites/smoke.yaml',
+            readinessLabels,
+            suiteRunnable,
+            compiledFlows: compiledFlows.map((f) => ({ name: f.name, slug: f.slug, ok: f.ok, errors: f.errors, flowPath: f.flowPath ?? null, compiledPath: f.compiledPath ?? null })),
+            audit: pom.audit,
+            variables: pom.variables,
+        }, null, 2));
+        written.push(manifestPath);
+    }
+    return {
+        skipped: false,
+        name: flowName,
+        pages: pom.pages.map((p) => p.name),
+        written,
+        compiledFlows,
+        suiteRunnable,
+        readinessLabels,
+        manifestPath,
+        audit: pom.audit,
+        variables: pom.variables,
+        testCases: tc.cases,
+    };
+}
+//# sourceMappingURL=suiteGenerate.js.map

package/dist/services/suiteGenerate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suiteGenerate.js","sourceRoot":"","sources":["../../src/services/suiteGenerate.ts"],"names":[],"mappings":"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"}

package/dist/services/testSuiteKnowledge.js

@@ -0,0 +1,150 @@
+// Vision Gap Fix 9 — the single "suite knowledge merge" service. The vision requires the persistent
+// suite (.swipium/test-suite.json) to stay current after EVERY flow that observes or creates QA
+// knowledge — exploration, automation generation, and report — without depending on
+// a later qa_report or a manual suite generation. Each flow funnels its cases through here so stable
+// ids, dedup, provenance, and the run ledger are enforced in ONE place (store.applyMerge), and a merge
+// failure is returned as a WARNING (best-effort) rather than failing an otherwise-valid QA run.
+import { applyMerge, suiteDelta, suiteResourceUri, suiteJsonPath, loadSuite } from '../testSuite/store.js';
+import { loadAppMap, saveAppMap } from '../appMap/store.js';
+import { detectFramework } from '../context/detect.js';
+import { casesFromExploration, caseFromPom } from '../testSuite/generator.js';
+import { pomForSession } from './suiteGenerate.js';
+import { join } from 'node:path';
+import { log } from '../lib/logger.js';
+const EMPTY = { ok: true, created: [], updated: [], deprecated: [], written: [], caseIds: [] };
+function fallbackProject(root) {
+    const fw = detectFramework(root);
+    return { root, gitRemote: null, packageName: null, workspaceTarget: null, framework: fw, platforms: fw === 'native-android' ? ['android'] : fw === 'native-ios' ? ['ios'] : ['android', 'ios'] };
+}
+/**
+ * Mirror a COMPACT index of the persistent suite into the app map's testSuite section so the durable
+ * map (and qa_app_map_query / feature scoping) reflect the growing suite — the "map + suite as one
+ * growing QA business context" loop the vision requires. Best-effort: no map yet ⇒ no-op.
+ */
+function mirrorSuiteIndexToMap(root, now) {
+    try {
+        const loaded = loadAppMap(root, fallbackProject(root), now);
+        if (!loaded.map)
+            return; // no durable map yet — feature scope still reads the suite directly
+        const suite = loadSuite(root);
+        const refs = suite.cases.map((c) => ({
+            id: c.id,
+            title: c.title,
+            featureId: c.featureId,
+            status: c.actualResult.status,
+            source: 'test-suite',
+            lastRun: c.actualResult.lastRunAt,
+            stale: c.status === 'deprecated',
+        }));
+        loaded.map.testSuite = { cases: refs };
+        loaded.map.coverage.staleTests = refs.filter((r) => r.stale).length;
+        loaded.map.updatedAt = now;
+        saveAppMap(root, loaded.map);
+    }
+    catch {
+        /* best-effort: a mirror failure never fails the suite merge */
+    }
+}
+/** Core: merge already-canonical cases into the suite. Best-effort — never throws. */
+export function mergeCanonical(root, cases, ctx) {
+    if (!cases.length)
+        return EMPTY;
+    try {
+        const applied = applyMerge(root, cases, { source: ctx.source, mode: ctx.mode ?? 'update', now: ctx.now, runId: ctx.runId, sourceUri: ctx.sourceUri, liveFeatureIds: ctx.liveFeatureIds }, ctx.appId);
+        const delta = suiteDelta(applied.result.suite, applied.result);
+        const caseIds = [...applied.result.created, ...applied.result.updated];
+        // Keep the durable app map's suite index in sync with the persistent suite (Fix #3).
+        mirrorSuiteIndexToMap(root, ctx.now);
+        return {
+            ok: true,
+            created: applied.result.created,
+            updated: applied.result.updated,
+            deprecated: applied.result.deprecated,
+            delta,
+            suiteUri: ctx.sessionId ? suiteResourceUri(ctx.sessionId) : `file://${suiteJsonPath(root)}`,
+            written: applied.written,
+            caseIds,
+        };
+    }
+    catch (e) {
+        log('warn', 'suite knowledge merge failed', { source: ctx.source, err: String(e) });
+        return { ...EMPTY, ok: false, warning: `suite merge failed: ${String(e)}` };
+    }
+}
+/** Merge exploration-derived feature coverage cases into the persistent suite. */
+export function mergeFromExploration(root, exploration, ctx) {
+    if (!exploration?.summary?.featureCoverage)
+        return EMPTY;
+    let cases;
+    try {
+        cases = casesFromExploration({ exploration, source: 'exploration', now: ctx.now, appId: ctx.appId });
+    }
+    catch (e) {
+        return { ...EMPTY, ok: false, warning: `exploration→canonical conversion failed: ${String(e)}` };
+    }
+    return mergeCanonical(root, cases, { ...ctx, source: 'exploration' });
+}
+function readinessGrade(brittlePct) {
+    if (brittlePct <= 0)
+        return 'A';
+    if (brittlePct < 25)
+        return 'B';
+    if (brittlePct < 50)
+        return 'C';
+    return 'D';
+}
+/**
+ * Fix 7 — merge automation metadata into the persistent suite. Converts the generated POM smoke flow
+ * into a canonical case carrying the real page-object/test-file paths, framework, locator readiness and
+ * automation status, AND (Fix #4) upgrades the automation link of EXISTING suite cases whose app-map
+ * feature/screen links overlap the generated suite — so a prior feature case is marked automated
+ * instead of a parallel POM-only case silently superseding it.
+ */
+export function mergeFromAutomation(root, session, input, ctx) {
+    const { assembled, links } = input;
+    let cases;
+    try {
+        const framework = assembled.profile.automationLanguage === 'python' ? 'appium_python' : 'appium_js';
+        const pageObjects = assembled.files.filter((f) => /page|screen|pages\//i.test(f.path)).map((f) => join(assembled.outputDir, f.path));
+        const testFiles = assembled.files.filter((f) => /test|spec|smoke|\.e2e\./i.test(f.path)).map((f) => join(assembled.outputDir, f.path));
+        const status = !input.validationOk ? 'partial' : assembled.model.audit.brittle > 0 ? 'partial' : 'automated';
+        const automation = { status, framework, pageObjects, testFiles, locatorReadiness: readinessGrade(assembled.model.audit.brittlePct), replayStatus: 'not_replayed' };
+        const { pom } = pomForSession(session);
+        const platforms = [assembled.profile.platforms.android.level !== 'none' ? 'android' : null, assembled.profile.platforms.ios.level !== 'none' ? 'ios' : null].filter(Boolean);
+        const base = caseFromPom({ pom, appId: session.appId, source: 'generate', now: ctx.now, platforms: platforms.length ? platforms : ['android'] });
+        if (!base)
+            return EMPTY;
+        // Group the POM case under the linked map feature so it doesn't fork from existing feature cases.
+        if (links?.featureIds.length) {
+            base.featureId = links.featureIds[0];
+            base.mapLinks = [
+                ...links.featureIds.map((id) => ({ kind: 'feature', id })),
+                ...links.screenIds.map((id) => ({ kind: 'screen', id })),
+                ...base.mapLinks.filter((l) => l.kind !== 'feature'),
+            ];
+        }
+        base.automation = automation;
+        cases = [base];
+        // Enrich EXISTING cases linked to the same feature/screen ids (Fix #4): re-emit them with their
+        // own id + upgraded automation so applyMerge updates (never duplicates) them. mergeAutomation only
+        // ever raises status/readiness, so this can't regress a stronger existing link.
+        if (links && (links.featureIds.length || links.screenIds.length)) {
+            const feat = new Set(links.featureIds);
+            const scr = new Set(links.screenIds);
+            const suite = loadSuite(root, ctx.appId);
+            for (const c of suite.cases) {
+                if (c.status === 'deprecated' || c.id === base.id)
+                    continue;
+                const overlaps = feat.has(c.featureId) || c.mapLinks.some((l) => (l.kind === 'feature' && feat.has(l.id)) || ((l.kind === 'screen' || l.kind === 'static_screen' || l.kind === 'runtime_screen') && scr.has(l.id)));
+                if (!overlaps)
+                    continue;
+                cases.push({ ...c, automation, provenance: [] });
+            }
+        }
+    }
+    catch (e) {
+        return { ...EMPTY, ok: false, warning: `automation→canonical conversion failed: ${String(e)}` };
+    }
+    return mergeCanonical(root, cases, { ...ctx, source: 'generate' });
+}
+//# sourceMappingURL=testSuiteKnowledge.js.map

package/dist/services/testSuiteKnowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testSuiteKnowledge.js","sourceRoot":"","sources":["../../src/services/testSuiteKnowledge.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,gGAAgG;AAChG,oFAAoF;AACpF,qGAAqG;AACrG,uGAAuG;AACvG,gGAAgG;AAEhG,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAmB,MAAM,uBAAuB,CAAC;AAC5H,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAIvD,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAInD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAgBvC,MAAM,KAAK,GAAqB,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAEjH,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,KAAK,gBAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC;AACnM,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAAC,IAAY,EAAE,GAAW;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,EAAE,eAAe,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,CAAC,GAAG;YAAE,OAAO,CAAC,oEAAoE;QAC7F,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAkB,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAClD,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC7B,MAAM,EAAE,YAAY;YACpB,OAAO,EAAE,CAAC,CAAC,YAAY,CAAC,SAAS;YACjC,KAAK,EAAE,CAAC,CAAC,MAAM,KAAK,YAAY;SACjC,CAAC,CAAC,CAAC;QACJ,MAAM,CAAC,GAAG,CAAC,SAAS,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;QACpE,MAAM,CAAC,GAAG,CAAC,SAAS,GAAG,GAAG,CAAC;QAC3B,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC;AAeD,sFAAsF;AACtF,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAA0B,EAAE,GAAiB;IACxF,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,UAAU,CACxB,IAAI,EACJ,KAAK,EACL,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,EAChJ,GAAG,CAAC,KAAK,CACV,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvE,qFAAqF;QACrF,qBAAqB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,OAAO;YACL,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;YAC/B,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO;YAC/B,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU;YACrC,KAAK;YACL,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,aAAa,CAAC,IAAI,CAAC,EAAE;YAC3F,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO;SACR,CAAC;IACJ,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,GAAG,CAAC,MAAM,EAAE,8BAA8B,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpF,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,uBAAuB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC9E,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,WAA0C,EAAE,GAAiB;IAC9G,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,eAAe;QAAE,OAAO,KAAK,CAAC;IACzD,IAAI,KAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,KAAK,GAAG,oBAAoB,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IACvG,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,4CAA4C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACnG,CAAC;IACD,OAAO,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,SAAS,cAAc,CAAC,UAAkB;IACxC,IAAI,UAAU,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAChC,IAAI,UAAU,GAAG,EAAE;QAAE,OAAO,GAAG,CAAC;IAChC,IAAI,UAAU,GAAG,EAAE;QAAE,OAAO,GAAG,CAAC;IAChC,OAAO,GAAG,CAAC;AACb,CAAC;AAWD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,OAAgB,EAAE,KAA2B,EAAE,GAAiB;IAChH,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACnC,IAAI,KAA0B,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,SAAS,GAAwB,SAAS,CAAC,OAAO,CAAC,kBAAkB,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC;QACzH,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACrI,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACvI,MAAM,MAAM,GAAqB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;QAC/H,MAAM,UAAU,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,YAAY,EAAE,cAAuB,EAAE,CAAC;QAE5K,MAAM,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,SAAS,GAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAA8B,CAAC;QAC3M,MAAM,IAAI,GAAG,WAAW,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACjJ,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,kGAAkG;QAClG,IAAI,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;YAC7B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACrC,IAAI,CAAC,QAAQ,GAAG;gBACd,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAkB,EAAE,EAAE,EAAE,CAAC,CAAC;gBACnE,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAiB,EAAE,EAAE,EAAE,CAAC,CAAC;gBACjE,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;aACrD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;QAEf,gGAAgG;QAChG,mGAAmG;QACnG,gFAAgF;QAChF,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACjE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACvC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACrC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YACzC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAC5B,IAAI,CAAC,CAAC,MAAM,KAAK,YAAY,IAAI,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE;oBAAE,SAAS;gBAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,eAAe,IAAI,CAAC,CAAC,IAAI,KAAK,gBAAgB,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBACpN,IAAI,CAAC,QAAQ;oBAAE,SAAS;gBACxB,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,2CAA2C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAClG,CAAC;IACD,OAAO,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/dist/session/attach.js

@@ -0,0 +1,47 @@
+// Centralized device resolution + lazy driver attach (Phase 2.1). One place decides
+// "which device" so qa_doctor / qa_prepare_target / UI tools
+// all agree: a session-bound device, the single online device, or "needs selection".
+import { adbDevices } from '../lib/android.js';
+import { DirectDriver } from '../drivers/DirectDriver.js';
+export async function resolveDevice(session, prefer) {
+    // Test-isolation hook (SWIPIUM-REQ-08 regression requirement): when set, device auto-discovery is
+    // disabled so "no device" tests assert no-device behavior even on a machine with a live emulator.
+    if (process.env.SWIPIUM_DISABLE_DEVICE_DISCOVERY) {
+        return { sessionDevice: undefined, available: [], effective: undefined, needSelection: false, source: 'none' };
+    }
+    const available = await adbDevices();
+    const sessionDevice = session.device && available.includes(session.device) ? session.device : undefined;
+    if (prefer) {
+        return available.includes(prefer)
+            ? { sessionDevice, available, effective: prefer, needSelection: false, source: 'arg' }
+            : { sessionDevice, available, effective: undefined, needSelection: false, source: 'none' };
+    }
+    if (sessionDevice)
+        return { sessionDevice, available, effective: sessionDevice, needSelection: false, source: 'session' };
+    if (available.length === 1)
+        return { sessionDevice, available, effective: available[0], needSelection: false, source: 'single-online' };
+    if (available.length > 1)
+        return { sessionDevice, available, effective: undefined, needSelection: true, source: 'none' };
+    return { sessionDevice, available, effective: undefined, needSelection: false, source: 'none' };
+}
+/** Bind a serial to the session (used after prepare/boot or single-online auto-bind). */
+export function bindDevice(session, serial) {
+    const driver = new DirectDriver(serial);
+    session.device = serial;
+    session.driver = driver;
+    return driver;
+}
+export async function getDriver(session) {
+    if (session.driver)
+        return { driver: session.driver, rehydrated: false };
+    const res = await resolveDevice(session);
+    if (res.effective) {
+        bindDevice(session, res.effective);
+        session.lastSnapshot = undefined; // refs invalid after (re)bind
+        return { driver: session.driver, rehydrated: true };
+    }
+    return { driver: undefined, rehydrated: false, needSelection: res.needSelection };
+}
+export const REHYDRATE_NOTE = 'Note: reattached the device transport after a restart — the app may not be in the ' +
+    'foreground (relaunch with qa_prepare_target) and previous @eN refs are invalid (re-run qa_snapshot).';
+//# sourceMappingURL=attach.js.map

package/dist/session/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../../src/session/attach.ts"],"names":[],"mappings":"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"}

package/dist/session/progress.js

@@ -0,0 +1,56 @@
+// Progress model helper (hardening P1.1). Long-running jobs report a consistent progress shape
+// (phase / elapsed / statusText / lastEvent / nextExpected / logUri / userActionRequired) so an
+// agent can relay status compactly. `startProgress` returns a small controller a worker uses to
+// emit events; it writes both the legacy `progress` string and the structured `progressDetail`.
+export function startProgress(sessions, session, job, phase, init = { statusText: phase }) {
+    const now = Date.now();
+    const model = {
+        phase,
+        startedAt: now,
+        updatedAt: now,
+        statusText: init.statusText,
+        nextExpected: init.nextExpected,
+        logUri: init.logUri,
+        userActionRequired: false,
+    };
+    const write = () => {
+        model.updatedAt = Date.now();
+        sessions.updateJobIfRunning(session, job, { progress: model.statusText, progressDetail: { ...model } });
+    };
+    write();
+    return {
+        elapsedSec: () => Math.round((Date.now() - model.startedAt) / 1000),
+        event(lastEvent, opts) {
+            model.lastEvent = lastEvent;
+            if (opts?.statusText)
+                model.statusText = opts.statusText;
+            if (opts?.nextExpected)
+                model.nextExpected = opts.nextExpected;
+            write();
+        },
+        setLog(logUri) {
+            model.logUri = logUri;
+            write();
+        },
+        needsUser(statusText) {
+            model.userActionRequired = true;
+            model.statusText = statusText;
+            write();
+        },
+        done(statusText) {
+            model.userActionRequired = false;
+            if (statusText)
+                model.statusText = statusText;
+            model.nextExpected = undefined;
+            write();
+        },
+    };
+}
+/** Compact one-line progress summary for qa_status / qa_job_status. */
+export function progressLine(p) {
+    if (!p)
+        return undefined;
+    const sec = Math.round((p.updatedAt - p.startedAt) / 1000);
+    return `${p.phase} (${sec}s)${p.userActionRequired ? ' ⚠ needs you' : ''}: ${p.statusText}` + (p.nextExpected ? ` → ${p.nextExpected}` : '');
+}
+//# sourceMappingURL=progress.js.map

package/dist/session/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/session/progress.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,gGAAgG;AAChG,gGAAgG;AAChG,gGAAgG;AAahG,MAAM,UAAU,aAAa,CAC3B,QAAsB,EACtB,OAAgB,EAChB,GAAc,EACd,KAAa,EACb,OAAuE,EAAE,UAAU,EAAE,KAAK,EAAE;IAE5F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,KAAK,GAAkB;QAC3B,KAAK;QACL,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG;QACd,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,kBAAkB,EAAE,KAAK;KAC1B,CAAC;IACF,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,QAAQ,CAAC,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,UAAU,EAAE,cAAc,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1G,CAAC,CAAC;IACF,KAAK,EAAE,CAAC;IACR,OAAO;QACL,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;QACnE,KAAK,CAAC,SAAS,EAAE,IAAI;YACnB,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;YAC5B,IAAI,IAAI,EAAE,UAAU;gBAAE,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;YACzD,IAAI,IAAI,EAAE,YAAY;gBAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;YAC/D,KAAK,EAAE,CAAC;QACV,CAAC;QACD,MAAM,CAAC,MAAM;YACX,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;YACtB,KAAK,EAAE,CAAC;QACV,CAAC;QACD,SAAS,CAAC,UAAU;YAClB,KAAK,CAAC,kBAAkB,GAAG,IAAI,CAAC;YAChC,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;YAC9B,KAAK,EAAE,CAAC;QACV,CAAC;QACD,IAAI,CAAC,UAAU;YACb,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC;YACjC,IAAI,UAAU;gBAAE,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC;YAC9C,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC;YAC/B,KAAK,EAAE,CAAC;QACV,CAAC;KACF,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,CAA4B;IACvD,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3D,OAAO,GAAG,CAAC,CAAC,KAAK,KAAK,GAAG,KAAK,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAC/I,CAAC"}