swipium 1.4.0 → 2.0.0

package/dist/tools/suite.js

@@ -1,36 +1,43 @@
-// qa_pom_generate / qa_suite_generate / qa_testcase_generate / qa_suite_lint (roadmap §6 / §7 / §12).
+// Per-run suite generation cores + qa_flow_compile.
 //
 // These turn the actions recorded during a session (qa_act) into a MAINTAINABLE POM suite under
-// .swipium/ — page objects (selectors), tests (reference elements by name), a suite, a test-case
-// catalog, and a locator audit — and lint the result for brittle/coordinate-only locators.
+// .swipium/: page objects (selectors), tests (reference elements by name), a suite, a test-case
+// catalog, and a locator audit. The generation entry points (page objects, full suite, test-case
+// catalog) are exposed through qa_generate (src/tools/generate.ts); this file registers only
+// qa_flow_compile, which compiles a generated POM suite into runnable Flow V2 for qa_flow_run.
 import { z } from 'zod';
 import { createHash } from 'node:crypto';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { qaOk, qaError } from '../lib/result.js';
+import { qaOk, qaError, unknownSessionError } from '../lib/result.js';
+import { resolveProjectRoot, unresolvedProjectRootError } from '../context/projectRoot.js';
 import { requireConsent, consumeConsent } from '../consent/consent.js';
 import { generatePom } from '../suite/pom.js';
 import { generateTestCases } from '../suite/testcase.js';
-import { lintSuitePages } from '../suite/lint.js';
 import { compileSuite } from '../suite/compile.js';
 import { parseFlow } from '../flows/schema.js';
 import { runFlow } from '../flows/run.js';
 import { loadProjectConfig } from '../cli/scan.js';
 import { generateAndCompileSuite } from '../services/suiteGenerate.js';
+import { assertNoSecretLeaks, findSecretLeaks, inputBindings, secretSafeNotes, structuralLiterals } from '../suite/secretGuard.js';
 import { getDriver } from '../session/attach.js';
 import { readinessForSession } from '../report/readiness.js';
 import { loadStateProfile, prepareStateProfile, teardownStateProfile, verifyStateProfile } from '../state/profile.js';
-import { hasStateProfileMutation, stateProfileAffects, stateRisk } from './state.js';
+import { hasStateProfileMutation, stateProfileAffects, stateRisk } from '../state/consent.js';
 function stable(value) {
     if (Array.isArray(value))
         return value.map(stable);
     if (value && typeof value === 'object') {
-        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)]));
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, stable(v)]));
     }
     return value;
 }
 function hash(value) {
-    return createHash('sha256').update(JSON.stringify(stable(value))).digest('hex');
+    return createHash('sha256')
+        .update(JSON.stringify(stable(value)))
+        .digest('hex');
 }
 function hashFile(path) {
     if (!path)
@@ -54,9 +61,9 @@ function compiledFlowIdentity(c) {
     };
 }
 function appIdOf(session) {
-    return session.appId ?? (loadProjectConfig(session.root)?.appId ?? undefined);
+    return session.appId ?? loadProjectConfig(session.root)?.appId ?? undefined;
 }
-/** Map the replay outcome to the test-case catalog's replay status (Deliverable 4 — honest plumbing). */
+/** Map the replay outcome to the test-case catalog's replay status (Deliverable 4, honest plumbing). */
 function catalogReplayStatus(mode, results, passed) {
     if (mode === 'none' || results.length === 0)
         return 'not_replayed';
@@ -79,6 +86,7 @@ function suiteDir(session) {
 }
 /** Write generated files under .swipium/, returning absolute paths written. */
 function writeFiles(session, files) {
+    assertNoSecretLeaks(files, session.secrets, 'suite generation', { structural: structuralLiterals(session.recordedActions) }); // backstop: never write a secret
     const base = suiteDir(session);
     const written = [];
     for (const f of files) {
@@ -89,12 +97,29 @@ function writeFiles(session, files) {
     }
     return written;
 }
+/** Loud refusal when generated files would carry a registered secret value (nothing is written). */
+function secretLeakError(session, files) {
+    const leaks = findSecretLeaks(files, session.secrets, { structural: structuralLiterals(session.recordedActions) });
+    if (!leaks.length)
+        return null;
+    return qaError({
+        what: `Not generated: a registered secret value would be written in plaintext (${leaks
+            .slice(0, 5)
+            .map((l) => `${l.path}:${l.line}`)
+            .join(', ')})`,
+        changedState: false,
+        retrySafe: false,
+        failureCode: 'SECRET_IN_GENERATED_OUTPUT',
+        nextSteps: ['Nothing was written. Re-record the credential step so it is captured as a ${VAR}, then regenerate.'],
+    });
+}
 function requireActions(session) {
     if (!session.recordedActions.length) {
         return qaError({
             what: 'No actions recorded in this session yet',
             changedState: false,
             retrySafe: true,
+            failureCode: 'NO_RECORDED_ACTIONS',
             nextSteps: ['Drive the app with qa_act first (each action is recorded), then regenerate the suite.'],
         });
     }
@@ -103,312 +128,389 @@ function requireActions(session) {
 function pomFor(session, name) {
     const appId = appIdOf(session);
     const flowName = (name ?? `${(appId ?? 'app').split('.').pop()}-smoke`).replace(/[^\w.-]+/g, '-');
-    const pom = generatePom(session.recordedActions, { name: flowName, appId, budgetProfile: session.budgetProfile });
+    const pom = generatePom(session.recordedActions, {
+        name: flowName,
+        appId,
+        budgetProfile: session.budgetProfile,
+        secrets: session.secrets,
+        inputs: inputBindings(session), // typed text equal to a stored input maps to its ${SWIPIUM_TEST_*} placeholder
+    });
     return { pom, flowName };
 }
-export function registerSuite(server, sessions) {
-    // ---- qa_pom_generate ----
-    server.registerTool('qa_pom_generate', {
-        title: 'Generate page objects',
-        description: 'Generate Screen/Page Object Model files from the actions recorded this session: one page object per screen with named elements (selectors hoisted out of tests), plus a locator audit (durable vs brittle, with app-code remediation). Pass save:true to write under .swipium/pages + .swipium/locators. Use qa_suite_generate for the full suite (pages + tests + suite + test cases).',
-        inputSchema: {
-            sessionId: z.string(),
-            name: z.string().optional(),
-            save: z.boolean().optional(),
-        },
-    }, async ({ sessionId, name, save }) => {
-        const session = sessions.get(sessionId);
-        if (!session)
-            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
-        const noActions = requireActions(session);
-        if (noActions)
-            return noActions;
-        const { pom } = pomFor(session, name);
-        const pageFiles = pom.files.filter((f) => f.path.startsWith('pages/') || f.path.startsWith('locators/'));
-        const written = save ? writeFiles(session, pageFiles) : [];
-        const summary = `Generated ${pom.pages.length} page object(s): ${pom.pages.map((p) => p.name).join(', ')}\n` +
-            `locator audit: ${pom.audit.durable} durable / ${pom.audit.semi} semi / ${pom.audit.brittle} brittle (${pom.audit.brittlePct}% brittle)` +
-            (save ? `\nsaved ${written.length} files under .swipium/` : `\n(not saved — pass save:true)`);
-        return qaOk({ pages: pom.pages, audit: pom.audit, files: pageFiles, written }, summary);
-    });
-    // ---- qa_suite_generate ----
-    server.registerTool('qa_suite_generate', {
-        title: 'Generate an automation suite',
-        description: 'Generate a full, committed-ready automation suite under .swipium/ from this session\'s recorded actions: page objects (pages/), a POM test (tests/), a suite (suites/), a test case catalog (testcases/), a locator audit (locators/), AND — unless compile:false — runnable Flow V2 compiled into flows/ + compiled/. Reports durability, brittle locators, and whether the suite is runnable. Pass save:false to preview without writing.',
-        inputSchema: {
-            sessionId: z.string(),
-            name: z.string().optional(),
-            save: z.boolean().optional().describe('Write files under .swipium/ (default true).'),
-            compile: z.boolean().optional().describe('Also compile to runnable Flow V2 (default true).'),
-            replay: z.enum(['none', 'dry_run', 'same_session', 'fresh_state']).optional().describe('Replay gate: dry_run validates compiled flows; same_session executes compiled flows now; fresh_state requires a state profile and is reported as blocked when absent. Default dry_run.'),
-            stateProfile: z.string().optional().describe('Required for replay:"fresh_state" so CI-ready means replay from declared state.'),
-            consentId: z.string().optional().describe('Required when replay:"fresh_state" applies a mutating state profile.'),
-            approve: z.boolean().optional().describe('Approve the exact fresh-state replay consent request.'),
-        },
-    }, async ({ sessionId, name, save, compile, replay, stateProfile, consentId, approve }) => {
-        const session = sessions.get(sessionId);
-        if (!session)
-            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
-        const noActions = requireActions(session);
-        if (noActions)
-            return noActions;
-        const res = generateAndCompileSuite(sessions, session, { name, save: save !== false, compile: compile !== false });
-        const audit = res.audit;
-        const ranOk = res.compiledFlows.filter((c) => c.ok).length;
-        const replayMode = replay ?? 'dry_run';
-        const replayResults = [];
-        const replayEvidence = {
-            stateLedgerUris: [],
-            consentRequired: false,
-            consentApproved: false,
-        };
-        if (replayMode === 'dry_run') {
-            for (const c of res.compiledFlows)
-                replayResults.push({ name: c.name, mode: replayMode, status: c.ok ? 'validated' : 'failed', reason: c.errors.join('; ') || undefined });
-        }
-        else if (replayMode === 'same_session') {
-            const { driver } = await getDriver(session);
-            if (!driver)
-                replayResults.push({ name: res.name ?? 'suite', mode: replayMode, status: 'blocked', reason: 'no driver attached for same-session replay' });
-            else {
-                for (const c of res.compiledFlows.filter((f) => f.ok && f.flowPath)) {
-                    const parsed = parseFlow(readFileSync(c.flowPath, 'utf8'));
-                    if (!parsed.flow) {
-                        replayResults.push({ name: c.name, mode: replayMode, status: 'failed', reason: parsed.errors.join('; ') });
-                        continue;
-                    }
-                    const r = await runFlow(sessions, session, driver, parsed.flow, { variables: sessions.inputVariables(session) });
-                    replayResults.push({ name: c.name, mode: replayMode, status: r.passed ? 'passed' : 'failed', reason: r.reason });
+/** Core handler for qa_generate target:"pom": page objects + locator audit from recorded actions. */
+export async function runPomGenerate(sessions, { sessionId, name, save }) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return unknownSessionError(sessionId);
+    const noActions = requireActions(session);
+    if (noActions)
+        return noActions;
+    const { pom } = pomFor(session, name);
+    const pageFiles = pom.files.filter((f) => f.path.startsWith('pages/') || f.path.startsWith('locators/'));
+    const pomLeak = secretLeakError(session, pageFiles);
+    if (pomLeak)
+        return pomLeak;
+    const written = save ? writeFiles(session, pageFiles) : [];
+    const summary = `Generated ${pom.pages.length} page object(s): ${pom.pages.map((p) => p.name).join(', ')}\n` +
+        `locator audit: ${pom.audit.durable} durable / ${pom.audit.semi} semi / ${pom.audit.brittle} brittle (${pom.audit.brittlePct}% brittle)` +
+        (save ? `\nsaved ${written.length} files under .swipium/` : `\n(not saved; pass save:true)`);
+    return qaOk({ pages: pom.pages, audit: pom.audit, files: pageFiles, written }, summary);
+}
+/**
+ * Core handler for qa_generate target:"suite": the full per-run .swipium/ suite from recorded
+ * actions: pages + tests + suite + test cases + locator audit, plus compile and replay gates.
+ */
+export async function runSuiteGenerate(sessions, { sessionId, name, save, compile, replay, stateProfile, consentId, approve }) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return unknownSessionError(sessionId);
+    const noActions = requireActions(session);
+    if (noActions)
+        return noActions;
+    const res = generateAndCompileSuite(sessions, session, { name, save: save !== false, compile: compile !== false });
+    if (res.failureCode)
+        return qaError({
+            what: `Suite not generated: ${res.skippedReason}`,
+            changedState: false,
+            retrySafe: false,
+            failureCode: 'SECRET_IN_GENERATED_OUTPUT',
+            nextSteps: [res.recommendation ?? 'Re-record the credential step so it is captured as a ${VAR}, then regenerate.'],
+        });
+    const audit = res.audit;
+    const ranOk = res.compiledFlows.filter((c) => c.ok).length;
+    const replayMode = replay ?? 'dry_run';
+    const replayResults = [];
+    const replayEvidence = {
+        stateLedgerUris: [],
+        consentRequired: false,
+        consentApproved: false,
+    };
+    if (replayMode === 'dry_run') {
+        for (const c of res.compiledFlows)
+            replayResults.push({
+                name: c.name,
+                mode: replayMode,
+                status: c.ok ? 'validated' : 'failed',
+                reason: c.errors.join('; ') || undefined,
+            });
+    }
+    else if (replayMode === 'same_session') {
+        const { driver } = await getDriver(session);
+        if (!driver)
+            replayResults.push({
+                name: res.name ?? 'suite',
+                mode: replayMode,
+                status: 'blocked',
+                reason: 'no driver attached for same-session replay',
+            });
+        else {
+            for (const c of res.compiledFlows.filter((f) => f.ok && f.flowPath)) {
+                const parsed = parseFlow(readFileSync(c.flowPath, 'utf8'));
+                if (!parsed.flow) {
+                    replayResults.push({ name: c.name, mode: replayMode, status: 'failed', reason: parsed.errors.join('; ') });
+                    continue;
                 }
+                const r = await runFlow(sessions, session, driver, parsed.flow, { variables: sessions.inputVariables(session) });
+                replayResults.push({ name: c.name, mode: replayMode, status: r.passed ? 'passed' : 'failed', reason: r.reason });
             }
         }
-        else if (replayMode === 'fresh_state') {
-            const { driver } = await getDriver(session);
-            if (!stateProfile)
-                replayResults.push({ name: res.name ?? 'suite', mode: replayMode, status: 'blocked', reason: 'stateProfile is required for fresh_state replay' });
-            else if (!driver)
-                replayResults.push({ name: res.name ?? 'suite', mode: replayMode, status: 'blocked', reason: 'no driver attached for fresh-state replay' });
+    }
+    else if (replayMode === 'fresh_state') {
+        const { driver } = await getDriver(session);
+        if (!stateProfile)
+            replayResults.push({
+                name: res.name ?? 'suite',
+                mode: replayMode,
+                status: 'blocked',
+                reason: 'stateProfile is required for fresh_state replay',
+            });
+        else if (!driver)
+            replayResults.push({
+                name: res.name ?? 'suite',
+                mode: replayMode,
+                status: 'blocked',
+                reason: 'no driver attached for fresh-state replay',
+            });
+        else {
+            const loaded = loadStateProfile(session.root, stateProfile);
+            if (!loaded.profile)
+                replayResults.push({
+                    name: res.name ?? 'suite',
+                    mode: replayMode,
+                    status: 'blocked',
+                    reason: loaded.error ?? 'could not load state profile',
+                });
             else {
-                const loaded = loadStateProfile(session.root, stateProfile);
-                if (!loaded.profile)
-                    replayResults.push({ name: res.name ?? 'suite', mode: replayMode, status: 'blocked', reason: loaded.error ?? 'could not load state profile' });
-                else {
-                    replayEvidence.stateProfile = loaded.profile.name;
-                    replayEvidence.stateProfilePath = loaded.path ?? null;
-                    const mutatingProfile = hasStateProfileMutation('prepare', loaded.profile, session) || hasStateProfileMutation('teardown', loaded.profile, session);
-                    replayEvidence.consentRequired = mutatingProfile;
-                    let mutationPayloadHash;
-                    if (mutatingProfile) {
-                        const prepareAffects = stateProfileAffects(session, 'prepare', loaded.profile, loaded.path);
-                        const teardownAffects = stateProfileAffects(session, 'teardown', loaded.profile, loaded.path);
-                        const affects = {
-                            suite: res.name ?? 'suite',
-                            replayMode,
-                            compiledFlows: res.compiledFlows.map(compiledFlowIdentity),
-                            suiteManifestPath: res.manifestPath ?? null,
-                            suiteManifestHash: hashFile(res.manifestPath),
-                            statePrepare: prepareAffects,
-                            stateTeardown: teardownAffects,
-                        };
-                        mutationPayloadHash = hash(affects);
-                        const risk = stateRisk('prepare', loaded.profile, session) === 'high' || stateRisk('teardown', loaded.profile, session) === 'high'
-                            ? 'high'
-                            : stateRisk('prepare', loaded.profile, session) === 'medium' || stateRisk('teardown', loaded.profile, session) === 'medium'
-                                ? 'medium'
-                                : 'low';
-                        const gate = consumeConsent(consentId, approve, { action: 'suite_fresh_state_replay', affects });
-                        if (!gate.approved) {
-                            sessions.recordMutation(session, {
-                                tool: 'qa_suite_generate',
-                                action: 'suite_fresh_state_replay',
-                                risk,
-                                target: affects,
-                                consent: { required: true, approved: false, payloadHash: mutationPayloadHash },
-                                status: 'requested',
-                            });
-                            return requireConsent({
-                                action: 'suite_fresh_state_replay',
-                                risk,
-                                exactCommand: `qa_suite_generate replay=fresh_state stateProfile=${loaded.profile.name}`,
-                                affects,
-                                explain: `Replay generated suite "${res.name ?? 'suite'}" from state profile "${loaded.profile.name}"? This can mutate app/device state through prepare/teardown before proving CI readiness.`,
-                            });
-                        }
-                        replayEvidence.consentApproved = true;
+                replayEvidence.stateProfile = loaded.profile.name;
+                replayEvidence.stateProfilePath = loaded.path ?? null;
+                const mutatingProfile = hasStateProfileMutation('prepare', loaded.profile, session) || hasStateProfileMutation('teardown', loaded.profile, session);
+                replayEvidence.consentRequired = mutatingProfile;
+                let mutationPayloadHash;
+                if (mutatingProfile) {
+                    const prepareAffects = stateProfileAffects(session, 'prepare', loaded.profile, loaded.path);
+                    const teardownAffects = stateProfileAffects(session, 'teardown', loaded.profile, loaded.path);
+                    const affects = {
+                        suite: res.name ?? 'suite',
+                        replayMode,
+                        compiledFlows: res.compiledFlows.map(compiledFlowIdentity),
+                        suiteManifestPath: res.manifestPath ?? null,
+                        suiteManifestHash: hashFile(res.manifestPath),
+                        statePrepare: prepareAffects,
+                        stateTeardown: teardownAffects,
+                    };
+                    mutationPayloadHash = hash(affects);
+                    const risk = stateRisk('prepare', loaded.profile, session) === 'high' || stateRisk('teardown', loaded.profile, session) === 'high'
+                        ? 'high'
+                        : stateRisk('prepare', loaded.profile, session) === 'medium' || stateRisk('teardown', loaded.profile, session) === 'medium'
+                            ? 'medium'
+                            : 'low';
+                    const gate = consumeConsent(consentId, approve, { action: 'suite_fresh_state_replay', affects });
+                    if (!gate.approved) {
                         sessions.recordMutation(session, {
-                            tool: 'qa_suite_generate',
+                            tool: 'qa_generate',
                             action: 'suite_fresh_state_replay',
                             risk,
                             target: affects,
-                            consent: { required: true, consentId, approved: true, payloadHash: mutationPayloadHash },
-                            status: 'approved',
+                            consent: { required: true, approved: false, payloadHash: mutationPayloadHash },
+                            status: 'requested',
+                        });
+                        return requireConsent({
+                            action: 'suite_fresh_state_replay',
+                            risk,
+                            exactCommand: `qa_generate target=suite replay=fresh_state stateProfile=${loaded.profile.name}`,
+                            affects,
+                            explain: `Replay generated suite "${res.name ?? 'suite'}" from state profile "${loaded.profile.name}"? This can mutate app/device state through prepare/teardown before proving CI readiness.`,
                         });
                     }
-                    const ledgers = [];
-                    const saveLedger = (action, ledger) => {
-                        const uri = sessions.saveArtifact(session, 'state', `suite-${action}-${loaded.profile.name}-${Date.now()}.json`, JSON.stringify(ledger, null, 2), 'application/json', `suite fresh-state ${action} ledger`);
-                        ledgers.push(uri);
-                        replayEvidence.stateLedgerUris.push(uri);
-                    };
-                    const prepared = await prepareStateProfile(sessions, session, driver, loaded.profile);
-                    saveLedger('prepare', prepared);
-                    if (prepared.status === 'state_refused' || prepared.status === 'state_blocked') {
-                        replayResults.push({ name: res.name ?? 'suite', mode: replayMode, status: 'blocked', reason: `state prepare ${prepared.status}; ledgers=${ledgers.join(',')}` });
+                    replayEvidence.consentApproved = true;
+                    sessions.recordMutation(session, {
+                        tool: 'qa_generate',
+                        action: 'suite_fresh_state_replay',
+                        risk,
+                        target: affects,
+                        consent: { required: true, consentId, approved: true, payloadHash: mutationPayloadHash },
+                        status: 'approved',
+                    });
+                }
+                const ledgers = [];
+                const saveLedger = (action, ledger) => {
+                    const uri = sessions.saveArtifact(session, 'state', `suite-${action}-${loaded.profile.name}-${Date.now()}.json`, JSON.stringify(ledger, null, 2), 'application/json', `suite fresh-state ${action} ledger`);
+                    ledgers.push(uri);
+                    replayEvidence.stateLedgerUris.push(uri);
+                };
+                const prepared = await prepareStateProfile(sessions, session, driver, loaded.profile);
+                saveLedger('prepare', prepared);
+                if (prepared.status === 'state_refused' || prepared.status === 'state_blocked') {
+                    replayResults.push({
+                        name: res.name ?? 'suite',
+                        mode: replayMode,
+                        status: 'blocked',
+                        reason: `state prepare ${prepared.status}; ledgers=${ledgers.join(',')}`,
+                    });
+                }
+                else {
+                    const verified = await verifyStateProfile(driver, loaded.profile);
+                    saveLedger('verify', verified);
+                    if (verified.status === 'state_blocked') {
+                        replayResults.push({
+                            name: res.name ?? 'suite',
+                            mode: replayMode,
+                            status: 'blocked',
+                            reason: `state verify blocked; ledgers=${ledgers.join(',')}`,
+                        });
                     }
                     else {
-                        const verified = await verifyStateProfile(driver, loaded.profile);
-                        saveLedger('verify', verified);
-                        if (verified.status === 'state_blocked') {
-                            replayResults.push({ name: res.name ?? 'suite', mode: replayMode, status: 'blocked', reason: `state verify blocked; ledgers=${ledgers.join(',')}` });
-                        }
-                        else {
-                            for (const c of res.compiledFlows.filter((f) => f.ok && f.flowPath)) {
-                                const parsed = parseFlow(readFileSync(c.flowPath, 'utf8'));
-                                if (!parsed.flow) {
-                                    replayResults.push({ name: c.name, mode: replayMode, status: 'failed', reason: parsed.errors.join('; ') });
-                                    continue;
-                                }
-                                const r = await runFlow(sessions, session, driver, parsed.flow, { variables: sessions.inputVariables(session) });
-                                replayResults.push({ name: c.name, mode: replayMode, status: r.passed ? 'passed' : 'failed', reason: r.reason });
+                        for (const c of res.compiledFlows.filter((f) => f.ok && f.flowPath)) {
+                            const parsed = parseFlow(readFileSync(c.flowPath, 'utf8'));
+                            if (!parsed.flow) {
+                                replayResults.push({ name: c.name, mode: replayMode, status: 'failed', reason: parsed.errors.join('; ') });
+                                continue;
                             }
+                            const r = await runFlow(sessions, session, driver, parsed.flow, { variables: sessions.inputVariables(session) });
+                            replayResults.push({ name: c.name, mode: replayMode, status: r.passed ? 'passed' : 'failed', reason: r.reason });
                         }
                     }
-                    const tornDown = await teardownStateProfile(sessions, session, driver, loaded.profile);
-                    saveLedger('teardown', tornDown);
-                    if (mutatingProfile) {
-                        const ok = replayResults.length > 0 && replayResults.every((r) => r.status === 'passed');
-                        sessions.recordMutation(session, {
-                            tool: 'qa_suite_generate',
-                            action: 'suite_fresh_state_replay',
-                            risk: stateRisk('prepare', loaded.profile, session),
-                            target: { stateProfile: loaded.profile.name, suite: res.name ?? 'suite', ledgerUris: ledgers },
-                            consent: { required: true, consentId, approved: true, payloadHash: mutationPayloadHash },
-                            status: ok ? 'executed' : 'blocked',
-                            ledgerUri: ledgers[0],
-                            detail: ok ? 'fresh_state replay passed' : 'fresh_state replay did not pass',
-                        });
-                    }
+                }
+                const tornDown = await teardownStateProfile(sessions, session, driver, loaded.profile);
+                saveLedger('teardown', tornDown);
+                if (mutatingProfile) {
+                    const ok = replayResults.length > 0 && replayResults.every((r) => r.status === 'passed');
+                    sessions.recordMutation(session, {
+                        tool: 'qa_generate',
+                        action: 'suite_fresh_state_replay',
+                        risk: stateRisk('prepare', loaded.profile, session),
+                        target: { stateProfile: loaded.profile.name, suite: res.name ?? 'suite', ledgerUris: ledgers },
+                        consent: { required: true, consentId, approved: true, payloadHash: mutationPayloadHash },
+                        status: ok ? 'executed' : 'blocked',
+                        ledgerUri: ledgers[0],
+                        detail: ok ? 'fresh_state replay passed' : 'fresh_state replay did not pass',
+                    });
                 }
             }
         }
-        const replayPassed = replayResults.length > 0 && replayResults.every((r) => r.status === 'passed' || r.status === 'validated');
-        const ciReadyGate = {
-            compiled: res.suiteRunnable,
-            freshStateReplay: replayMode === 'fresh_state' && replayResults.length > 0 && replayResults.every((r) => r.status === 'passed'),
-            declaredStateProfile: replayMode === 'fresh_state' && !!stateProfile,
-            stateEvidence: replayMode === 'fresh_state' && replayEvidence.stateLedgerUris.length >= 2,
-            stableEvidence: replayMode === 'fresh_state' && replayResults.length > 0 && replayResults.every((r) => r.status === 'passed') && replayEvidence.stateLedgerUris.length >= 2,
-        };
-        const ciReady = Object.values(ciReadyGate).every(Boolean);
-        const suiteReplayed = (replayMode === 'same_session' || replayMode === 'fresh_state') && replayPassed;
-        const readinessLabels = readinessForSession(session, { suiteRunnable: res.suiteRunnable, suiteReplayed, ciReady });
-        if (!readinessLabels.includes('generated'))
-            readinessLabels.push('generated');
-        if (res.suiteRunnable && !readinessLabels.includes('compiled'))
-            readinessLabels.push('compiled');
-        if (suiteReplayed && !readinessLabels.includes('replayed'))
-            readinessLabels.push('replayed');
-        if (ciReady && !readinessLabels.includes('ci_ready'))
-            readinessLabels.push('ci_ready');
-        const readiness = readinessLabels.at(-1) ?? 'generated';
-        const written = res.manifestPath ? [...res.written] : res.written;
-        if (res.manifestPath) {
-            writeFileSync(res.manifestPath, JSON.stringify({
-                schema: 'swipium.suite.manifest.v1',
-                generatedAt: new Date(session.createdAt).toISOString(),
-                name: res.name,
-                suiteFile: 'suites/smoke.yaml',
-                readinessLabels,
-                readiness,
-                suiteRunnable: res.suiteRunnable,
-                replay: { mode: replayMode, results: replayResults, passed: replayPassed, evidence: replayEvidence },
-                ciReady,
-                ciReadyGate,
-                compiledFlows: res.compiledFlows.map((f) => ({ name: f.name, slug: f.slug, ok: f.ok, errors: f.errors, flowPath: f.flowPath ?? null, compiledPath: f.compiledPath ?? null })),
-                audit,
-                variables: res.variables ?? [],
-            }, null, 2));
-        }
-        // Plumb the ACTUAL replay outcome back into the written catalog (review item #5): the suite
-        // service writes the catalog before replay (honest `not_replayed`); once we have a real replay
-        // result, rewrite the YAML/MD so the committed test cases reflect proven replay status.
-        let finalTestCases = res.testCases;
-        if (res.manifestPath) {
-            const replayStatus = catalogReplayStatus(replayMode, replayResults, replayPassed);
-            if (replayStatus !== 'not_replayed') {
-                const { pom, flowName } = pomFor(session, name);
-                const tc = generateTestCases(pom, {
-                    appId: appIdOf(session),
-                    fixtures: session.fixtures,
-                    notes: session.notes,
-                    budgetProfile: session.budgetProfile,
-                    replayStatus,
-                });
-                writeFiles(session, [
-                    { path: `testcases/${flowName}.cases.yaml`, content: tc.yaml },
-                    { path: `testcases/${flowName}.cases.md`, content: tc.markdown },
-                ]);
-                finalTestCases = tc.cases;
-            }
+    }
+    const replayPassed = replayResults.length > 0 && replayResults.every((r) => r.status === 'passed' || r.status === 'validated');
+    const ciReadyGate = {
+        compiled: res.suiteRunnable,
+        freshStateReplay: replayMode === 'fresh_state' && replayResults.length > 0 && replayResults.every((r) => r.status === 'passed'),
+        declaredStateProfile: replayMode === 'fresh_state' && !!stateProfile,
+        stateEvidence: replayMode === 'fresh_state' && replayEvidence.stateLedgerUris.length >= 2,
+        stableEvidence: replayMode === 'fresh_state' &&
+            replayResults.length > 0 &&
+            replayResults.every((r) => r.status === 'passed') &&
+            replayEvidence.stateLedgerUris.length >= 2,
+    };
+    const ciReady = Object.values(ciReadyGate).every(Boolean);
+    const suiteReplayed = (replayMode === 'same_session' || replayMode === 'fresh_state') && replayPassed;
+    const readinessLabels = readinessForSession(session, { suiteRunnable: res.suiteRunnable, suiteReplayed, ciReady });
+    if (!readinessLabels.includes('generated'))
+        readinessLabels.push('generated');
+    if (res.suiteRunnable && !readinessLabels.includes('compiled'))
+        readinessLabels.push('compiled');
+    if (suiteReplayed && !readinessLabels.includes('replayed'))
+        readinessLabels.push('replayed');
+    if (ciReady && !readinessLabels.includes('ci_ready'))
+        readinessLabels.push('ci_ready');
+    const readiness = readinessLabels.at(-1) ?? 'generated';
+    const written = res.manifestPath ? [...res.written] : res.written;
+    if (res.manifestPath) {
+        writeFileSync(res.manifestPath, JSON.stringify({
+            schema: 'swipium.suite.manifest.v1',
+            generatedAt: new Date(session.createdAt).toISOString(),
+            name: res.name,
+            suiteFile: 'suites/smoke.yaml',
+            readinessLabels,
+            readiness,
+            suiteRunnable: res.suiteRunnable,
+            replay: { mode: replayMode, results: replayResults, passed: replayPassed, evidence: replayEvidence },
+            ciReady,
+            ciReadyGate,
+            compiledFlows: res.compiledFlows.map((f) => ({
+                name: f.name,
+                slug: f.slug,
+                ok: f.ok,
+                errors: f.errors,
+                flowPath: f.flowPath ?? null,
+                compiledPath: f.compiledPath ?? null,
+            })),
+            audit,
+            variables: res.variables ?? [],
+        }, null, 2));
+    }
+    // Plumb the ACTUAL replay outcome back into the written catalog (review item #5): the suite
+    // service writes the catalog before replay (honest `not_replayed`); once we have a real replay
+    // result, rewrite the YAML/MD so the committed test cases reflect proven replay status.
+    let finalTestCases = res.testCases;
+    if (res.manifestPath) {
+        const replayStatus = catalogReplayStatus(replayMode, replayResults, replayPassed);
+        if (replayStatus !== 'not_replayed') {
+            const { pom, flowName } = pomFor(session, name);
+            const tc = generateTestCases(pom, {
+                appId: appIdOf(session),
+                fixtures: session.fixtures,
+                notes: secretSafeNotes(session.notes, session.secrets),
+                budgetProfile: session.budgetProfile,
+                replayStatus,
+            });
+            writeFiles(session, [
+                { path: `testcases/${flowName}.cases.yaml`, content: tc.yaml },
+                { path: `testcases/${flowName}.cases.md`, content: tc.markdown },
+            ]);
+            finalTestCases = tc.cases;
         }
-        const summary = `✅ Suite "${res.name}" generated (${res.pages?.length ?? 0} pages, ${res.testCases?.length ?? 0} test case, suite + audit).\n` +
-            `durability: ${audit.durable} durable / ${audit.semi} semi / ${audit.brittle} brittle (${audit.brittlePct}% brittle)` +
-            (res.variables?.length ? `\nvariables: ${res.variables.join(', ')}` : '') +
-            (audit.brittle ? `\n⚠ ${audit.brittle} brittle locator(s) — see locators/locator-audit.json for app-code fixes.` : '') +
-            (written.length ? `\nwrote ${written.length} files under ${suiteDir(session)}` : `\n(preview — pass save:true to write)`) +
-            (res.compiledFlows.length ? `\ncompiled ${ranOk}/${res.compiledFlows.length} runnable flow(s) → run: swipium suite run (or qa_flow_run).` : `\nNext: qa_suite_compile to produce runnable Flow V2.`) +
-            `\nreplay gate (${replayMode}): ${replayPassed ? 'passed' : replayResults.length ? 'not proven' : 'not run'}; readiness=${readiness}; labels=${readinessLabels.join(' → ')}` +
-            (ciReady ? '\nci_ready: compiled + fresh-state replay + state evidence proved' : replayMode === 'fresh_state' ? `\nci_ready missing: ${Object.entries(ciReadyGate).filter(([, ok]) => !ok).map(([k]) => k).join(', ') || 'none'}` : '');
-        return qaOk({ name: res.name, pages: res.pages, audit, variables: res.variables, testCases: finalTestCases, written, manifestPath: res.manifestPath ?? null, compiledFlows: res.compiledFlows, suiteRunnable: res.suiteRunnable, replay: { mode: replayMode, results: replayResults, passed: replayPassed, evidence: replayEvidence }, readiness, readinessLabels, ciReady, ciReadyGate }, summary);
-    });
-    // ---- qa_testcase_generate ----
-    server.registerTool('qa_testcase_generate', {
-        title: 'Generate test case docs',
-        description: 'Generate an industry-style test case catalog (TC-xxx: purpose, priority, preconditions, steps, expected, automation status, known blockers, evidence) from this session\'s recorded actions + observed outcomes. Returns YAML + Markdown. Pass save:true to write under .swipium/testcases.',
-        inputSchema: {
-            sessionId: z.string(),
-            name: z.string().optional(),
-            format: z.enum(['yaml', 'markdown', 'both']).optional(),
-            save: z.boolean().optional(),
-        },
-    }, async ({ sessionId, name, format, save }) => {
-        const session = sessions.get(sessionId);
-        if (!session)
-            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
-        const noActions = requireActions(session);
-        if (noActions)
-            return noActions;
-        const { pom, flowName } = pomFor(session, name);
-        const tc = generateTestCases(pom, { appId: appIdOf(session), fixtures: session.fixtures, notes: session.notes, budgetProfile: session.budgetProfile });
-        const fmt = format ?? 'both';
-        const files = [];
-        if (fmt !== 'markdown')
-            files.push({ path: `testcases/${flowName}.cases.yaml`, content: tc.yaml });
-        if (fmt !== 'yaml')
-            files.push({ path: `testcases/${flowName}.cases.md`, content: tc.markdown });
-        const written = save ? writeFiles(session, files) : [];
-        const summary = `Generated ${tc.cases.length} test case(s): ${tc.cases.map((c) => `${c.id} ${c.title}`).join('; ')}` + (written.length ? `\nsaved under .swipium/testcases` : '');
-        return qaOk({ cases: tc.cases, yaml: fmt !== 'markdown' ? tc.yaml : undefined, markdown: fmt !== 'yaml' ? tc.markdown : undefined, written }, summary);
+    }
+    const summary = `✅ Suite "${res.name}" generated (${res.pages?.length ?? 0} pages, ${res.testCases?.length ?? 0} test case, suite + audit).\n` +
+        `durability: ${audit.durable} durable / ${audit.semi} semi / ${audit.brittle} brittle (${audit.brittlePct}% brittle)` +
+        (res.variables?.length ? `\nvariables: ${res.variables.join(', ')}` : '') +
+        (audit.brittle ? `\n⚠ ${audit.brittle} brittle locator(s), see locators/locator-audit.json for app-code fixes.` : '') +
+        (written.length ? `\nwrote ${written.length} files under ${suiteDir(session)}` : `\n(preview; pass save:true to write)`) +
+        (res.compiledFlows.length
+            ? `\ncompiled ${ranOk}/${res.compiledFlows.length} runnable flow(s) > run: swipium suite run (or qa_flow_run).`
+            : `\nNext: qa_flow_compile to produce runnable Flow V2.`) +
+        `\nreplay gate (${replayMode}): ${replayPassed ? 'passed' : replayResults.length ? 'not proven' : 'not run'}; readiness=${readiness}; labels=${readinessLabels.join(' > ')}` +
+        (ciReady
+            ? '\nci_ready: compiled + fresh-state replay + state evidence proved'
+            : replayMode === 'fresh_state'
+                ? `\nci_ready missing: ${Object.entries(ciReadyGate)
+                    .filter(([, ok]) => !ok)
+                    .map(([k]) => k)
+                    .join(', ') || 'none'}`
+                : '');
+    return qaOk({
+        name: res.name,
+        pages: res.pages,
+        audit,
+        variables: res.variables,
+        testCases: finalTestCases,
+        written,
+        manifestPath: res.manifestPath ?? null,
+        compiledFlows: res.compiledFlows,
+        suiteRunnable: res.suiteRunnable,
+        replay: { mode: replayMode, results: replayResults, passed: replayPassed, evidence: replayEvidence },
+        readiness,
+        readinessLabels,
+        ciReady,
+        ciReadyGate,
+    }, summary);
+}
+/** Core handler for qa_generate target:"testcases": industry-style test case catalog from recorded actions. */
+export async function runTestcaseGenerate(sessions, { sessionId, name, format, save }) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return unknownSessionError(sessionId);
+    const noActions = requireActions(session);
+    if (noActions)
+        return noActions;
+    const { pom, flowName } = pomFor(session, name);
+    const tc = generateTestCases(pom, {
+        appId: appIdOf(session),
+        fixtures: session.fixtures,
+        notes: secretSafeNotes(session.notes, session.secrets),
+        budgetProfile: session.budgetProfile,
     });
-    // ---- qa_suite_compile ----
-    server.registerTool('qa_suite_compile', {
+    const fmt = format ?? 'both';
+    const files = [];
+    if (fmt !== 'markdown')
+        files.push({ path: `testcases/${flowName}.cases.yaml`, content: tc.yaml });
+    if (fmt !== 'yaml')
+        files.push({ path: `testcases/${flowName}.cases.md`, content: tc.markdown });
+    const tcLeak = secretLeakError(session, files);
+    if (tcLeak)
+        return tcLeak;
+    const written = save ? writeFiles(session, files) : [];
+    const summary = `Generated ${tc.cases.length} test case(s): ${tc.cases.map((c) => `${c.id} ${c.title}`).join('; ')}` +
+        (written.length ? `\nsaved under .swipium/testcases` : '');
+    return qaOk({ cases: tc.cases, yaml: fmt !== 'markdown' ? tc.yaml : undefined, markdown: fmt !== 'yaml' ? tc.markdown : undefined, written }, summary);
+}
+export function registerSuite(server, sessions) {
+    // ---- qa_flow_compile ----
+    server.registerTool('qa_flow_compile', {
         title: 'Compile a POM suite to runnable flows',
-        description: 'Compile the generated POM suite (.swipium/suites/<suite>.yaml → its POM tests) into Flow V2 YAML that qa_flow_run and `swipium ci` can execute. Resolves page-object element refs to selectors, carries variables/secrets, and writes runnable flows to .swipium/flows/ (+ a readable copy under .swipium/compiled/). Validates each compiled flow through parseFlow and reports any errors. This is the step that makes a generated suite runnable, not just documentation.',
+        description: 'Compile an existing POM suite on disk (.swipium/suites/<suite>.yaml, e.g. committed or hand-edited) into runnable Flow V2 ' +
+            'for qa_flow_run: resolves page-object refs to selectors, carries variables, writes .swipium/flows/<slug>.yaml (+ a copy ' +
+            'under .swipium/compiled/), and validates each flow. Needs no session or recorded actions; qa_generate target:"suite" ' +
+            'already compiles the suite it generates from a run.',
         inputSchema: {
             sessionId: z.string().optional(),
             projectRoot: z.string().optional(),
             suite: z.string().optional().describe('Suite file relative to .swipium/ (default suites/smoke.yaml).'),
         },
     }, async ({ sessionId, projectRoot, suite }) => {
-        let root;
-        if (sessionId)
-            root = sessions.get(sessionId)?.root;
-        root = root ?? projectRoot;
-        if (!root)
-            return qaError({ what: 'No project root', changedState: false, retrySafe: true, nextSteps: ['Pass sessionId or projectRoot.'] });
+        let root = sessionId ? sessions.get(sessionId)?.root : undefined;
+        if (!root) {
+            const resolved = await resolveProjectRoot(server, projectRoot);
+            if (!resolved.root)
+                return unresolvedProjectRootError(resolved);
+            root = resolved.root;
+        }
         const result = compileSuite(root, suite ?? 'suites/smoke.yaml');
         if (result.errors.length && result.flows.length === 0) {
-            return qaError({ what: `Could not compile suite: ${result.errors.join('; ')}`, changedState: false, retrySafe: true, nextSteps: ['Generate a suite first: qa_suite_generate, then qa_suite_compile.'] });
+            return qaError({
+                what: `Could not compile suite: ${result.errors.join('; ')}`,
+                changedState: false,
+                retrySafe: true,
+                nextSteps: ['Generate a suite first: qa_generate target:"suite", then qa_flow_compile.'],
+            });
         }
         const flowsDir = join(root, '.swipium', 'flows');
         const compiledDir = join(root, '.swipium', 'compiled');
@@ -421,7 +523,7 @@ export function registerSuite(server, sessions) {
             let flowPath;
             let compiledPath;
             if (ok) {
-                flowPath = join(flowsDir, `${slug}.yaml`); // discoverable by `swipium ci --flow <slug>`
+                flowPath = join(flowsDir, `${slug}.yaml`); // discoverable by qa_flow_run flow:"<slug>"
                 compiledPath = join(compiledDir, `${slug}.flow.yaml`);
                 writeFileSync(flowPath, f.yaml);
                 writeFileSync(compiledPath, f.yaml);
@@ -430,31 +532,10 @@ export function registerSuite(server, sessions) {
         });
         const okCount = compiled.filter((c) => c.ok).length;
         const summary = `Compiled ${okCount}/${compiled.length} flow(s) from ${result.suite}.\n` +
-            compiled.map((c) => `  ${c.ok ? '✓' : '✗'} ${c.name}${c.ok ? ` → flows/${c.slug}.yaml (run: swipium ci --flow ${c.slug})` : `: ${c.errors.join('; ')}`}`).join('\n');
+            compiled
+                .map((c) => `  ${c.ok ? '✓' : '✗'} ${c.name}${c.ok ? ` > flows/${c.slug}.yaml (run: qa_flow_run flow:"${c.slug}")` : `: ${c.errors.join('; ')}`}`)
+                .join('\n');
         return qaOk({ suite: result.suite, flows: compiled, okCount }, summary);
     });
-    // ---- qa_suite_lint ----
-    server.registerTool('qa_suite_lint', {
-        title: 'Lint the generated suite',
-        description: 'Lint the page objects under .swipium/pages for durability problems: missing durable locators (coordinate-only), copy/locale-fragile text selectors, and dynamic-looking selectors. Reports each with the page/element and the app-code fix. Use after qa_suite_generate, before committing or wiring CI.',
-        inputSchema: { sessionId: z.string().optional(), projectRoot: z.string().optional() },
-    }, async ({ sessionId, projectRoot }) => {
-        let root;
-        if (sessionId)
-            root = sessions.get(sessionId)?.root;
-        root = root ?? projectRoot;
-        if (!root)
-            return qaError({ what: 'No project root', changedState: false, retrySafe: true, nextSteps: ['Pass sessionId or projectRoot.'] });
-        const findings = lintSuitePages(root);
-        if (!findings.exists) {
-            return qaError({ what: 'No .swipium/pages to lint', changedState: false, retrySafe: true, nextSteps: ['Generate a suite first: qa_suite_generate.'] });
-        }
-        const errors = findings.items.filter((f) => f.severity === 'error');
-        const summary = `Linted ${findings.pageCount} page object(s): ${findings.items.length} issue(s) (${errors.length} brittle).\n` +
-            (findings.items.length
-                ? findings.items.slice(0, 20).map((i) => `  ${i.severity === 'error' ? '✗' : '⚠'} ${i.page}.${i.element}: ${i.message}`).join('\n')
-                : '  ✓ all locators are durable.');
-        return qaOk({ pageCount: findings.pageCount, items: findings.items }, summary);
-    });
 }
 //# sourceMappingURL=suite.js.map