@delt/tester-mcp 0.1.0

package/dist/run/buildPrompt.js

@@ -0,0 +1,84 @@
+import { renderStep } from "../scenario/actions.js";
+export const SYSTEM_CONTRACT = `You are a screen integration-test executor. Execute ONLY the given scenario steps, in order. Be fast and simple — act on the given selector, look as little as possible, and bail immediately if you can't.
+
+[Tab isolation — parallel safety (do this FIRST)]
+- You share one Chrome with other executors. Your very first action: create your OWN new tab with tabs_create_mcp. Never reuse an existing tab that tabs_context shows (another executor may be using it). Remember that new tab_id and do EVERY action (navigate/click/fill/find/screenshot) ONLY in that tab_id.
+- If the current tab's URL is unrelated to your scenario (= you landed on someone else's tab), end immediately with NOT_TESTED and record "tab mix-up: observed URL=…" in handoff_notes. Do not keep working on someone else's tab.
+
+[Finding elements — selector first]
+- Try the strategies given in the step's target, in order (css → placeholder → label → text → role → description), ONCE.
+- Do not grope around the page. The target is the answer.
+
+[Read minimally]
+- No full-page reads: do not call read_page (full accessibility tree) or a full get_page_text.
+- Use a targeted find to see only that element. assert_visible checks only that element.
+
+[Screenshots — evidence only, not the verdict]
+- Decide PASS/FAIL by assert (text/DOM). A screenshot is human-facing evidence, not the basis for the verdict.
+- Take a screenshot only when the scenario has a screenshot action, best-effort, once. If you can't capture it (element gone, capture failed, timeout), just skip and move on. NEVER loop re-triggering/resizing/scrolling/re-capturing. A failed screenshot is not a test failure.
+
+[Ephemeral (auto-dismissing) UI]
+- For short-lived elements (toast, snackbar), check IMMEDIATELY and ONCE right after the trigger (the fastest way: a JS text/DOM assertion). Do not chain fallbacks (JS → find → read_page) — the element vanishes mid-chain.
+- Do not screenshot an ephemeral element. The assertion is the proof.
+
+[Fast self-bail — once]
+- If you can't find the target in one attempt, or a browser tool returns no/empty response once, end immediately with NOT_TESTED. Do not retry the same heavy call.
+- One failure means the scenario (selector) is wrong — don't try to recover, hand it to the builder.
+
+[Status labels] status is exactly one of four:
+- PASS: behaved as expected (verified)
+- PARTIAL: only partly verified, or a non-critical difference
+- FAIL: behaved differently than expected (a bug)
+- NOT_TESTED: couldn't trigger — must include not_tested_reason and handoff_notes
+
+[handoff_notes — fuel for the ping-pong] On NOT_TESTED, must include:
+- the failed step number
+- the target strategies you tried
+- what you actually observed on screen (a single targeted query at the failure point is allowed to write this — full dumps are still forbidden)
+- a fix suggestion for the builder (e.g. css \`#login-btn\` does not exist, observed \`.p-button[aria-label='Войти']\` → suggest replacing target.css)
+
+[Safety — forbidden]
+- Never do anything outside the scenario (especially delete/publish/send).
+- Avoid clicks that raise a JS alert/confirm/prompt (they freeze the session). If unavoidable, NOT_TESTED.
+- No absolute claims like "100% safe". Do not mix verified facts with assumptions.
+- Never write entered secrets (passwords etc.) into evidence/output verbatim — mask them as '***'.
+
+[Output] Emit the result as a JSON object only in the last message (a code fence is allowed). No free-form prose.`;
+const LANG_MAP = { kg: "lng_type_1", ru: "lng_type_2", kr: "lng_type_3" };
+export function localeToLanguageType(locale) {
+    return LANG_MAP[locale];
+}
+// resolveValue: caller injects the secrets resolver (mocked in tests).
+export function buildUserPrompt(scenario, targets, resolveValue) {
+    const locale = scenario.locale ?? "ru";
+    const langType = localeToLanguageType(locale);
+    const checklist = scenario.steps
+        .map((s) => {
+        const resolved = s.action === "fill" ? { ...s, value: resolveValue(s.value) } : s;
+        return renderStep(resolved);
+    })
+        .map((line, i) => `${i + 1}. ${line}`)
+        .join("\n");
+    const ephemeralNote = scenario.ephemeral
+        ? "\n- ⚠ ephemeral check: this screen vanishes quickly (toast etc.). Assert ONCE immediately after the trigger; no fallback chain, no screenshot."
+        : "";
+    return `# Project context
+- App (frontend): ${targets.frontend}
+- Stack: Vue 3 + PrimeVue. Targets are pre-resolved from source by the author — use them as-is. If a target is wrong or missing, don't grope; record the actual element you observed in handoff_notes and end with NOT_TESTED.${ephemeralNote}
+
+# Locale pin (deterministic test)
+Before starting, run localStorage.setItem('languageType', '${langType}') in the browser console, then reload the page. (locale=${locale})
+
+# Scenario: ${scenario.title} (id: ${scenario.id})
+Run the steps below in order. URLs are relative to the frontend base:
+${checklist}
+
+# Output format (JSON only in the last message)
+{
+  "status": "PASS | PARTIAL | FAIL | NOT_TESTED",
+  "evidence": ["basis — the text/structure/screenshot you saw"],
+  "steps": [{ "index": 1, "action": "navigate", "status": "PASS" }],
+  "not_tested_reason": "only when NOT_TESTED",
+  "handoff_notes": "where you got stuck / next start point"
+}`;
+}

package/dist/run/runScenario.d.ts

@@ -0,0 +1,18 @@
+import type { Scenario } from "../scenario/types.js";
+import type { Environment, ScenarioResult } from "../result/types.js";
+import { type StreamSpawner } from "./spawnExecutor.js";
+export interface RunScenarioOptions {
+    runId: string;
+    targets: {
+        frontend: string;
+    };
+    model: string;
+    env: Environment;
+    resolveValue: (v: string) => string;
+    now?: () => Date;
+    timeoutMs?: number;
+    spawner?: StreamSpawner;
+    logLine?: (line: string) => void;
+    executorLog?: string;
+}
+export declare function runScenario(scenario: Scenario, opts: RunScenarioOptions): Promise<ScenarioResult>;

package/dist/run/runScenario.js

@@ -0,0 +1,26 @@
+import { buildUserPrompt, SYSTEM_CONTRACT } from "./buildPrompt.js";
+import { spawnExecutor } from "./spawnExecutor.js";
+import { parseExecutorResult } from "../result/parseExecutorResult.js";
+export async function runScenario(scenario, opts) {
+    const now = opts.now ?? (() => new Date());
+    const startedAt = now();
+    const { envelope, state, killedReason } = await spawnExecutor({ prompt: buildUserPrompt(scenario, opts.targets, opts.resolveValue), systemPrompt: SYSTEM_CONTRACT, model: opts.model }, { spawner: opts.spawner, logLine: opts.logLine, timeoutMs: opts.timeoutMs });
+    const common = {
+        run_id: opts.runId, scenario_id: scenario.id,
+        started_at: startedAt.toISOString(), duration_ms: now().getTime() - startedAt.getTime(),
+        environment: opts.env,
+        last_tool: state.lastTool, tool_count: state.toolCount, executor_log: opts.executorLog,
+    };
+    if (!envelope) {
+        const why = killedReason === "stall" ? "무응답(스톨)" : killedReason === "timeout" ? "하드 타임아웃" : "executor가 결과를 방출하지 않음";
+        const lastBit = state.lastTool ? ` — 마지막 도구 '${state.lastTool}' (호출 ${state.toolCount}회)` : " — 도구 호출 0회";
+        return { ...common, status: "NOT_TESTED", not_tested_reason: `${why}${lastBit}`, steps: [] };
+    }
+    const parsed = parseExecutorResult(envelope.result);
+    return {
+        ...common, status: parsed.status, not_tested_reason: parsed.not_tested_reason,
+        pattern_inference: parsed.pattern_inference, evidence: parsed.evidence,
+        steps: parsed.steps ?? [], handoff_notes: parsed.handoff_notes,
+        raw_executor_text: parsed.raw_executor_text,
+    };
+}

package/dist/run/runScenarios.d.ts

@@ -0,0 +1,11 @@
+import type { Scenario } from "../scenario/types.js";
+import type { ScenarioResult } from "../result/types.js";
+import { type RunScenarioOptions } from "./runScenario.js";
+export declare const MAX_CONCURRENCY = 10;
+export declare function clampConcurrency(requested: number | undefined, scenarioCount: number): number;
+export interface RunScenariosLogging {
+    verbose?: boolean;
+    secretValues?: string[];
+    outDir?: string;
+}
+export declare function runScenarios(scenarios: Scenario[], opts: RunScenarioOptions, concurrency: number, logging?: RunScenariosLogging): Promise<ScenarioResult[]>;

package/dist/run/runScenarios.js

@@ -0,0 +1,47 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { runScenario } from "./runScenario.js";
+import { redactString } from "../secrets/redactSecrets.js";
+import { summarizeLine } from "./summarizeLine.js";
+// Hard ceiling on parallel executors. The orchestrating AI may *request* fewer
+// (its judgment), but the CLI never spawns more than this many `claude` processes
+// at once — keeps API rate-limit / browser-tab-group contention bounded.
+// (Verified: 10 parallel claude --chrome runs completed with 0 tab collisions.)
+export const MAX_CONCURRENCY = 10;
+// Resolve the effective concurrency: clamp the requested value into [1, MAX_CONCURRENCY],
+// defaulting to min(scenarioCount, MAX) when nothing valid is requested.
+export function clampConcurrency(requested, scenarioCount) {
+    const fallback = Math.max(1, Math.min(scenarioCount, MAX_CONCURRENCY));
+    if (requested === undefined || !Number.isFinite(requested))
+        return fallback;
+    return Math.max(1, Math.min(Math.floor(requested), MAX_CONCURRENCY));
+}
+// Run scenarios with a bounded worker pool. Each scenario spawns its own executor
+// process (via runScenario → spawnExecutor); `concurrency` caps how many run at once.
+// Results keep input order regardless of completion order.
+export async function runScenarios(scenarios, opts, concurrency, logging) {
+    const results = new Array(scenarios.length);
+    const workers = Math.max(1, Math.min(concurrency, scenarios.length || 1));
+    let next = 0;
+    const base = logging?.outDir ?? "runs";
+    const dir = join(base, opts.runId);
+    mkdirSync(dir, { recursive: true });
+    const worker = async () => {
+        for (let i = next++; i < scenarios.length; i = next++) {
+            const id = scenarios[i].id;
+            const logPath = join(dir, `${id}.log`);
+            const logLine = (line) => {
+                const safe = redactString(line, logging?.secretValues ?? []);
+                appendFileSync(logPath, safe + "\n");
+                if (logging?.verbose) {
+                    const sum = summarizeLine(safe);
+                    if (sum)
+                        console.log(`[${id}] ${sum}`);
+                }
+            };
+            results[i] = await runScenario(scenarios[i], { ...opts, executorLog: logPath, logLine });
+        }
+    };
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+    return results;
+}

package/dist/run/spawnExecutor.d.ts

@@ -0,0 +1,34 @@
+import { type ExecutorArgsOptions } from "./buildExecutorArgs.js";
+import { type StreamState } from "./streamParser.js";
+export interface Envelope {
+    result: string;
+    session_id?: string;
+    total_cost_usd?: number;
+}
+export declare function parseEnvelope(stdout: string): Envelope;
+export interface SpawnHandle {
+    kill(signal: NodeJS.Signals): void;
+}
+export interface StreamSpawner {
+    (cmd: string, args: string[], handlers: {
+        onLine: (line: string) => void;
+        onStderrLine?: (line: string) => void;
+        onClose: (code: number | null, signal: string | null) => void;
+    }): SpawnHandle;
+}
+export interface SpawnExecutorResult {
+    envelope?: Envelope;
+    state: StreamState;
+    killedReason?: "stall" | "timeout";
+}
+export interface SpawnExecutorDeps {
+    spawner?: StreamSpawner;
+    logLine?: (line: string) => void;
+    now?: () => number;
+    timeoutMs?: number;
+    stallMs?: number;
+    tickMs?: number;
+    killGraceMs?: number;
+    forceResolveMs?: number;
+}
+export declare function spawnExecutor(opts: ExecutorArgsOptions, deps?: SpawnExecutorDeps): Promise<SpawnExecutorResult>;

package/dist/run/spawnExecutor.js

@@ -0,0 +1,93 @@
+import { spawn } from "node:child_process";
+import { buildExecutorArgs } from "./buildExecutorArgs.js";
+import { makeStreamAccumulator } from "./streamParser.js";
+export function parseEnvelope(stdout) {
+    try {
+        const o = JSON.parse(stdout);
+        if (o && typeof o.result === "string")
+            return o;
+    }
+    catch { /* fall through */ }
+    return { result: stdout };
+}
+// Default streaming spawner: spawn + newline buffering (stdout → onLine, stderr → onStderrLine), \r-stripped.
+const defaultSpawner = (cmd, args, h) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const lineBuf = (emit) => {
+        let buf = "";
+        return {
+            push(d) {
+                buf += d.toString();
+                let nl;
+                while ((nl = buf.indexOf("\n")) >= 0) {
+                    emit(buf.slice(0, nl).replace(/\r$/, ""));
+                    buf = buf.slice(nl + 1);
+                }
+            },
+            flush() { if (buf.trim())
+                emit(buf.replace(/\r$/, "")); },
+        };
+    };
+    const out = lineBuf(h.onLine);
+    const err = lineBuf((l) => h.onStderrLine?.(l));
+    child.stdout.on("data", (d) => out.push(d));
+    child.stderr.on("data", (d) => err.push(d));
+    child.on("close", (code, signal) => { out.flush(); err.flush(); h.onClose(code, signal); });
+    child.on("error", () => h.onClose(null, null));
+    return { kill: (sig) => { try {
+            child.kill(sig);
+        }
+        catch { /* already dead */ } } };
+};
+export function spawnExecutor(opts, deps = {}) {
+    const spawner = deps.spawner ?? defaultSpawner;
+    const logLine = deps.logLine ?? (() => { });
+    const now = deps.now ?? (() => Date.now());
+    const stallMs = deps.stallMs ?? 60_000;
+    const tickMs = deps.tickMs ?? 5_000;
+    const killGraceMs = deps.killGraceMs ?? 5_000;
+    const forceResolveMs = deps.forceResolveMs ?? 5_000;
+    const acc = makeStreamAccumulator(now);
+    return new Promise((resolve) => {
+        let lastEvent = now();
+        let killedReason;
+        let done = false;
+        let killing = false;
+        const intervals = [];
+        const timeouts = [];
+        const clearAll = () => { intervals.forEach(clearInterval); timeouts.forEach(clearTimeout); };
+        const settle = () => {
+            if (done)
+                return;
+            done = true;
+            clearAll();
+            const snap = acc.snapshot();
+            resolve({ envelope: snap.envelope, state: snap, killedReason });
+        };
+        let handle;
+        // SIGTERM, then escalate to SIGKILL, then force-resolve if close never fires (hung child can't hang the run).
+        const killEscalate = (reason) => {
+            if (killing || done)
+                return;
+            killing = true;
+            killedReason = reason;
+            handle.kill("SIGTERM");
+            timeouts.push(setTimeout(() => { if (!done)
+                handle.kill("SIGKILL"); }, killGraceMs));
+            timeouts.push(setTimeout(settle, killGraceMs + forceResolveMs));
+        };
+        handle = spawner("claude", buildExecutorArgs(opts), {
+            onLine: (line) => { lastEvent = now(); acc.push(line); logLine(line); },
+            onStderrLine: (line) => { logLine("[stderr] " + line); },
+            onClose: () => settle(),
+        });
+        intervals.push(setInterval(() => {
+            if (!done && !killing && now() - lastEvent > stallMs)
+                killEscalate("stall");
+        }, tickMs));
+        if (deps.timeoutMs) {
+            timeouts.push(setTimeout(() => { if (!done && !killing)
+                killEscalate("timeout"); }, deps.timeoutMs));
+        }
+    });
+}

package/dist/run/streamParser.d.ts

@@ -0,0 +1,17 @@
+import type { Envelope } from "./spawnExecutor.js";
+export interface TrailItem {
+    t_ms: number;
+    phase: "use" | "result";
+    tool?: string;
+    is_error?: boolean;
+}
+export interface StreamState {
+    envelope?: Envelope;
+    trail: TrailItem[];
+    lastTool?: string;
+    toolCount: number;
+}
+export declare function makeStreamAccumulator(now?: () => number): {
+    push: (line: string) => void;
+    snapshot: () => StreamState;
+};

package/dist/run/streamParser.js

@@ -0,0 +1,51 @@
+// Parses stream-json lines into a diagnostic snapshot. Stores ONLY event
+// types / tool names / timing — never tool inputs or assistant text (which
+// may contain secrets). `now` is injected for deterministic timing in tests.
+export function makeStreamAccumulator(now = () => Date.now()) {
+    const t0 = now();
+    const state = { trail: [], toolCount: 0 };
+    function handleContent(content) {
+        if (!Array.isArray(content))
+            return;
+        for (const c of content) {
+            if (c?.type === "tool_use") {
+                const tool = typeof c.name === "string" ? c.name : undefined;
+                state.trail.push({ t_ms: now() - t0, phase: "use", tool });
+                state.lastTool = tool;
+                state.toolCount++;
+            }
+            else if (c?.type === "tool_result") {
+                state.trail.push({ t_ms: now() - t0, phase: "result", is_error: !!c.is_error });
+            }
+            // text / input deltas are intentionally ignored (secret-safe).
+        }
+    }
+    function push(line) {
+        const s = line.trim();
+        if (!s)
+            return;
+        let ev;
+        try {
+            ev = JSON.parse(s);
+        }
+        catch {
+            return;
+        }
+        const t = ev.type;
+        if (t === "assistant" || t === "user") {
+            handleContent(ev.message?.content);
+        }
+        else if (t === "result") {
+            // NOTE: result is the model's final text, stored RAW. It can contain secrets; redaction is the downstream layer's job (see redactSecrets). The trail/lastTool above never store raw text/inputs — only result does.
+            state.envelope = {
+                result: typeof ev.result === "string" ? ev.result : "",
+                session_id: typeof ev.session_id === "string" ? ev.session_id : undefined,
+                total_cost_usd: typeof ev.total_cost_usd === "number" ? ev.total_cost_usd : undefined,
+            };
+        }
+    }
+    function snapshot() {
+        return { envelope: state.envelope, trail: [...state.trail], lastTool: state.lastTool, toolCount: state.toolCount };
+    }
+    return { push, snapshot };
+}

package/dist/run/summarizeLine.d.ts

@@ -0,0 +1 @@
+export declare function summarizeLine(line: string): string | undefined;

package/dist/run/summarizeLine.js

@@ -0,0 +1,29 @@
+// Condense one stream-json line into a terse console summary for --verbose.
+// Returns undefined for non-tool events (narration/system) so the console
+// shows only tool activity. Never includes inputs/text (secret-safe).
+export function summarizeLine(line) {
+    const s = line.trim();
+    if (!s)
+        return undefined;
+    let ev;
+    try {
+        ev = JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+    if (ev.type === "result")
+        return "■ RESULT";
+    if (ev.type === "assistant" || ev.type === "user") {
+        const content = ev.message?.content;
+        if (!Array.isArray(content))
+            return undefined;
+        for (const c of content) {
+            if (c?.type === "tool_use")
+                return `→ ${String(c.name ?? "").replace("mcp__claude-in-chrome__", "")}`;
+            if (c?.type === "tool_result")
+                return c.is_error ? "✗ error" : "← ok";
+        }
+    }
+    return undefined;
+}

package/dist/scenario/actions.d.ts

@@ -0,0 +1,5 @@
+import type { Step, ActionName, Target } from "./types.js";
+export declare function describeTarget(t: Target): string;
+export declare const KNOWN_ACTIONS: ActionName[];
+export declare function isKnownAction(name: string): name is ActionName;
+export declare function renderStep(step: Step): string;

package/dist/scenario/actions.js

@@ -0,0 +1,33 @@
+// Priority order matches design §7: css/id > placeholder/label > text > role > description.
+export function describeTarget(t) {
+    const parts = [];
+    if (t.css)
+        parts.push(`css ${t.css}`);
+    if (t.placeholder)
+        parts.push(`placeholder "${t.placeholder}"`);
+    if (t.label)
+        parts.push(`label "${t.label}"`);
+    if (t.text)
+        parts.push(`text "${t.text}"`);
+    if (t.role)
+        parts.push(`role ${t.role}`);
+    if (t.description)
+        parts.push(`description "${t.description}"`);
+    return parts.join(" / ") || "(no target)";
+}
+// [확장1] Single source of truth for actions + prompt rendering.
+const RENDERERS = {
+    navigate: (s) => `Navigate: ${s.url}`,
+    fill: (s) => `Fill: [${describeTarget(s.target)}] ← "${s.value}"`,
+    click: (s) => `Click: [${describeTarget(s.target)}]${s.destructive ? " (destructive)" : ""}`,
+    wait_for: (s) => `Wait for: [${describeTarget(s.target)}] to appear${s.timeout_ms ? ` (${s.timeout_ms}ms)` : ""}`,
+    assert_visible: (s) => `Assert visible: [${describeTarget(s.target)}]`,
+    screenshot: (s) => `Screenshot${s.name ? `: ${s.name}` : ""}`,
+};
+export const KNOWN_ACTIONS = Object.keys(RENDERERS);
+export function isKnownAction(name) {
+    return KNOWN_ACTIONS.includes(name);
+}
+export function renderStep(step) {
+    return RENDERERS[step.action](step);
+}

package/dist/scenario/expandScenarioPaths.d.ts

@@ -0,0 +1 @@
+export declare function expandScenarioPaths(inputs: string[]): string[];

package/dist/scenario/expandScenarioPaths.js

@@ -0,0 +1,31 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+const YAML_RE = /\.ya?ml$/i;
+// Expand CLI scenario inputs into a sorted, de-duplicated list of resolved file paths.
+// - a directory  → all *.yaml/*.yml directly inside it (sorted by name)
+// - a file        → itself
+// Shells typically pre-expand globs; this only needs to handle files + dirs.
+export function expandScenarioPaths(inputs) {
+    const out = [];
+    for (const input of inputs) {
+        const p = resolve(input);
+        let st;
+        try {
+            st = statSync(p);
+        }
+        catch {
+            throw new Error(`시나리오 경로 없음: ${input}`);
+        }
+        if (st.isDirectory()) {
+            const files = readdirSync(p).filter((f) => YAML_RE.test(f)).sort();
+            if (files.length === 0)
+                throw new Error(`디렉토리에 시나리오(.yaml/.yml) 없음: ${input}`);
+            for (const f of files)
+                out.push(join(p, f));
+        }
+        else {
+            out.push(p);
+        }
+    }
+    return [...new Set(out)];
+}

package/dist/scenario/parseScenario.d.ts

@@ -0,0 +1,2 @@
+import type { Scenario } from "./types.js";
+export declare function parseScenario(yamlText: string): Scenario;

package/dist/scenario/parseScenario.js

@@ -0,0 +1,37 @@
+import { parse as parseYaml } from "yaml";
+import { isKnownAction } from "./actions.js";
+const LOCALES = ["kg", "ru", "kr"];
+export function parseScenario(yamlText) {
+    const raw = parseYaml(yamlText);
+    if (!raw || typeof raw !== "object")
+        throw new Error("시나리오 YAML 파싱 실패: 빈 문서");
+    if (typeof raw.id !== "string")
+        throw new Error("시나리오 필수 필드 누락: id");
+    if (!/^[A-Za-z0-9._-]+$/.test(raw.id)) {
+        throw new Error(`잘못된 시나리오 id '${raw.id}' — 영문/숫자/.-_ 만 허용 (경로 주입 방지)`);
+    }
+    if (typeof raw.title !== "string")
+        throw new Error("시나리오 필수 필드 누락: title");
+    if (!Array.isArray(raw.steps) || raw.steps.length === 0)
+        throw new Error("시나리오 필수 필드 누락: steps");
+    const steps = raw.steps.map((st, i) => {
+        if (!st || typeof st.action !== "string")
+            throw new Error(`step[${i}]: action 누락`);
+        if (!isKnownAction(st.action))
+            throw new Error(`step[${i}]: 알 수 없는 액션 "${st.action}" (이 슬라이스는 화면 액션만)`);
+        return st;
+    });
+    const locale = LOCALES.includes(raw.locale) ? raw.locale : undefined;
+    return {
+        id: raw.id,
+        title: raw.title,
+        steps,
+        locale,
+        login_as: typeof raw.login_as === "string" ? raw.login_as : undefined,
+        on_failure: raw.on_failure === "continue" ? "continue" : "stop",
+        optional: raw.optional === true,
+        defaults: raw.defaults ?? undefined,
+        precondition: typeof raw.precondition === "string" ? raw.precondition : undefined,
+        ephemeral: typeof raw.ephemeral === "boolean" ? raw.ephemeral : false,
+    };
+}

package/dist/scenario/types.d.ts

@@ -0,0 +1,47 @@
+export interface Target {
+    css?: string;
+    placeholder?: string;
+    label?: string;
+    text?: string;
+    role?: string;
+    description?: string;
+}
+export type Locale = "kg" | "ru" | "kr";
+export type Step = {
+    action: "navigate";
+    url: string;
+} | {
+    action: "fill";
+    target: Target;
+    value: string;
+} | {
+    action: "click";
+    target: Target;
+    destructive?: boolean;
+} | {
+    action: "wait_for";
+    target: Target;
+    timeout_ms?: number;
+} | {
+    action: "assert_visible";
+    target: Target;
+} | {
+    action: "screenshot";
+    name?: string;
+    save?: boolean;
+};
+export type ActionName = Step["action"];
+export interface Scenario {
+    id: string;
+    title: string;
+    steps: Step[];
+    locale?: Locale;
+    login_as?: string;
+    on_failure?: "stop" | "continue";
+    optional?: boolean;
+    defaults?: {
+        timeout_ms?: number;
+    };
+    precondition?: string;
+    ephemeral?: boolean;
+}

package/dist/scenario/types.js

@@ -0,0 +1 @@
+export {};

package/dist/secrets/loadSecretsFile.d.ts

@@ -0,0 +1 @@
+export declare function loadSecretsFile(path: string): Record<string, unknown>;

package/dist/secrets/loadSecretsFile.js

@@ -0,0 +1,10 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+// Load the gitignored secrets file (tester-mcp.secrets.yaml). File-first: if it
+// exists, parse YAML → object; if missing, return {} (env SECRET_* is the fallback).
+export function loadSecretsFile(path) {
+    if (!existsSync(path))
+        return {};
+    const parsed = parseYaml(readFileSync(path, "utf8"));
+    return (parsed ?? {});
+}

package/dist/secrets/redactSecrets.d.ts

@@ -0,0 +1,6 @@
+export declare function collectSecretValues(opts?: {
+    secrets?: Record<string, unknown>;
+    env?: Record<string, string | undefined>;
+}): string[];
+export declare function redactString(text: string, values: string[]): string;
+export declare function redactSecrets<T>(obj: T, secretValues: string[]): T;

package/dist/secrets/redactSecrets.js

@@ -0,0 +1,46 @@
+// Deterministic redaction of secret values from a result object before it is
+// written/printed. The CLI knows the resolved secret values (from the secrets file
+// and/or env SECRET_*), so we scrub them regardless of what the executor echoed.
+// Defense-in-depth alongside the system-prompt instruction not to echo secrets.
+function leafStrings(obj, out) {
+    if (typeof obj === "string") {
+        out.push(obj);
+    }
+    else if (Array.isArray(obj)) {
+        for (const v of obj)
+            leafStrings(v, out);
+    }
+    else if (obj && typeof obj === "object") {
+        for (const v of Object.values(obj))
+            leafStrings(v, out);
+    }
+}
+export function collectSecretValues(opts = {}) {
+    const env = opts.env ?? {};
+    const values = [];
+    // All string leaf values from the secrets object (recurse).
+    leafStrings(opts.secrets, values);
+    // Plus all env values whose key starts with SECRET_.
+    for (const [k, v] of Object.entries(env)) {
+        if (k.startsWith("SECRET_") && typeof v === "string")
+            values.push(v);
+    }
+    // Guard against over-redaction: only scrub values long enough to be real secrets; dedupe.
+    return [...new Set(values.filter((v) => v.length >= 4))];
+}
+export function redactString(text, values) {
+    let out = text;
+    for (const v of values)
+        if (v)
+            out = out.split(v).join("***");
+    return out;
+}
+export function redactSecrets(obj, secretValues) {
+    if (secretValues.length === 0)
+        return obj;
+    let json = JSON.stringify(obj);
+    for (const s of secretValues) {
+        json = json.split(s).join("***");
+    }
+    return JSON.parse(json);
+}