@skyramp/mcp 0.2.6 → 0.2.150-rc.mntnc

package/build/commands/commandLibrary.d.ts

@@ -0,0 +1,12 @@
+import type { OneClickCommandId, OneClickCommandDef } from "../types/OneClickCommands.js";
+export declare function getCommand(id: OneClickCommandId): OneClickCommandDef;
+export declare function getAllCommands(): OneClickCommandDef[];
+export declare function getCommandIds(): OneClickCommandId[];
+/**
+ * Look up a command by its string ID. Accepts any string so the tool handler
+ * does not need to cast; throws with a helpful message listing valid IDs if
+ * the ID is not found.
+ */
+export declare function lookupCommand(id: string): OneClickCommandDef;
+export { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
+export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";

package/build/commands/recommendTestsAndExecuteCommand.d.ts

@@ -0,0 +1,2 @@
+import type { OneClickCommandDef } from "../types/OneClickCommands.js";
+export declare const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND: OneClickCommandDef;

package/build/commands/testThisEndpointCommand.d.ts

@@ -0,0 +1,2 @@
+import type { OneClickCommandDef } from "../types/OneClickCommands.js";
+export declare const TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND: OneClickCommandDef;

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -24,8 +24,9 @@ import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerEnhanceAssertionsTool } from "./tools/code-refactor/enhanceAssertionsTool.js";
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
-import { registerAnalyzeChangesTool, registerUiAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
+import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
+import { registerSutSetupResource } from "./resources/sutSetupResource.js";
 import { registerTestbotResource } from "./resources/testbotResource.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
 import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
@@ -123,7 +124,9 @@ const prompts = [
 if (isTestbotEnabled()) {
     prompts.push(registerTestbotPrompt);
     registerTestbotResource(server);
-    logger.info("TestBot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
+    logger.info("Testbot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
+    registerSutSetupResource(server);
+    logger.info("Testbot SUT setup resource enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 prompts.forEach((registerPrompt) => registerPrompt(server));
 logger.info("All prompts registered successfully");
@@ -152,7 +155,6 @@ codeQualityTools.forEach((registerTool) => registerTool(server));
 registerAnalysisResources(server);
 registerProgressResource(server);
 // Register unified test-management tools (replaces separate test-maintenance tools)
-registerUiAnalyzeChangesTool(server);
 registerAnalyzeChangesTool(server);
 registerAnalyzeTestHealthTool(server);
 registerActionsTool(server);
@@ -174,7 +176,7 @@ const infrastructureTools = [
 ];
 if (isTestbotEnabled()) {
     infrastructureTools.push(registerSubmitReportTool);
-    logger.info("TestBot tools enabled via SKYRAMP_FEATURE_TESTBOT");
+    logger.info("Testbot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 infrastructureTools.forEach((registerTool) => registerTool(server));
 // Register Playwright browser tools (trace recording via browser automation)

package/build/playwright/PlaywrightTraceService.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Service that manages a Playwright TraceRecordingBackend instance,
+ * exposing browser tools + skyramp_export_zip for use by the Skyramp MCP.
+ *
+ * The Playwright fork is CJS; this project is ESM. We use createRequire
+ * to bridge the module systems.
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface PlaywrightTraceOptions {
+    /** Run the browser in headless mode. */
+    headless?: boolean;
+    /** Directory for output files (zip, HAR). Defaults to cwd. */
+    outputDir?: string;
+}
+export declare class PlaywrightTraceService {
+    private _backend;
+    private _tools;
+    private _options;
+    constructor(options?: PlaywrightTraceOptions);
+    initialize(): Promise<void>;
+    isInitialized(): boolean;
+    getTools(): McpTool[];
+    callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    shutdown(): Promise<void>;
+}
+export {};

package/build/playwright/index.d.ts

@@ -0,0 +1,3 @@
+export { PlaywrightTraceService, type PlaywrightTraceOptions, } from "./PlaywrightTraceService.js";
+export { registerPlaywrightTools, getPlaywrightTraceService, } from "./registerPlaywrightTools.js";
+export { registerTraceRecordingPrompt } from "./traceRecordingPrompt.js";

package/build/playwright/registerPlaywrightTools.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Registers all Playwright browser tools (+ skyramp_export_zip) as passthrough
+ * tools in the Skyramp MCP server, delegating calls to PlaywrightTraceService.
+ */
+import { PlaywrightTraceService, type PlaywrightTraceOptions } from "./PlaywrightTraceService.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function getPlaywrightTraceService(): PlaywrightTraceService | null;
+export declare function registerPlaywrightTools(server: McpServer, options?: PlaywrightTraceOptions): Promise<void>;

package/build/playwright/registerPlaywrightTools.js

@@ -26,11 +26,17 @@ export async function registerPlaywrightTools(server, options) {
     // The full set (23 tools) overwhelms the LLM and causes it to use
     // browser_evaluate/browser_run_code instead of the simpler tools.
     //
-    // The DOM Analyzer group (browser_blueprint*, browser_sitemap_*,
-    // browser_widget_contract_lookup) is referenced by skyramp_testbot's
-    // Task 1 UI Recommendation Grounding and Task 2 capture-act-capture
-    // discipline. Omitting them here would silently make the prompt's
-    // instructions uncallable.
+    // browser_blueprint is the only DOM Analyzer tool registered — it handles
+    // both full captures and same-URL deltas via the URL-cache (isFullCapture).
+    // browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
+    // 0 times in production evals and have no active call path in the testbot prompt.
+    //
+    // browser_widget_contract_lookup / browser_widget_contract_cache are
+    // intentionally excluded: the curated fingerprint library only covers
+    // test fixtures (not production widgets), and the LLM can handle custom
+    // widgets via snapshot-driven trial-and-error without the tool.
+    // The widgetType field on blueprint elements still signals "custom" to
+    // the agent — no guidance is lost.
     const ESSENTIAL_TOOLS = new Set([
         'browser_navigate',
         'browser_snapshot',
@@ -53,13 +59,8 @@ export async function registerPlaywrightTools(server, options) {
         'browser_visual_snapshot',
         'skyramp_export_zip',
         'skyramp_load_trace',
-        'browser_mouse_action',
-        // DOM Analyzer tools (Phase C)
+        // DOM Analyzer: blueprint capture (capture-act-capture pattern)
         'browser_blueprint',
-        'browser_blueprint_diff',
-        'browser_sitemap_build',
-        'browser_sitemap_query',
-        'browser_widget_contract_lookup',
     ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);

package/build/playwright/traceRecordingPrompt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP prompt that guides the LLM through the Playwright-based trace recording
+ * and Skyramp test generation flow.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface TraceRecordingPromptOpts {
+    /** Directory where zip files should be written. Defaults to same dir as test file. */
+    outputDir?: string;
+    /** Whether to run skyramp_modularization after generation. Default: true. Set false in CI. */
+    modularize?: boolean;
+}
+export declare function getTraceRecordingPromptText(opts?: TraceRecordingPromptOpts): string;
+export declare function registerTraceRecordingPrompt(server: McpServer): void;

package/build/playwright/traceRecordingPrompt.js

@@ -42,20 +42,12 @@ Then execute in strict order:
 - **No Docker required**: the \`browser_*\` tools run a local browser session managed by the MCP server. Docker is ONLY used by \`skyramp_start_trace_collection\` (manual recording mode). Never suggest or check for Docker when using AI-driven recording.
 ${modularizeNote}
 
-### Tool discipline — three concepts, don't conflate
+### Tool discipline — two concepts, don't conflate
 
-These concepts drive the DOM Analyzer capture tools (\`browser_sitemap_build\`, \`browser_sitemap_query\`, \`browser_blueprint\`) and constrain how their outputs flow into generated test code:
+These concepts drive the DOM Analyzer capture tools and constrain how their outputs flow into generated test code:
 
 - **\`browser_snapshot\` — ephemeral refs**: the \`ref=e29\` values change on every call. Use them ONLY for dispatching the next 1–2 interactions (\`browser_click\`, \`browser_type\`, etc.). **Never put refs in generated test code** — they will not exist at playback time.
-- **\`browser_blueprint\` — stable logical names**: logical names like \`add_order_btn\` and their derived \`getByRole\` locators survive page reloads and playback. Use them in generated test code. Call \`browser_blueprint\` only when the DOM has changed since the last known-good blueprint (modal opens, form submits, filter changes, mutable actions); for pure navigation to an already-crawled URL, reuse the Sitemap cache via \`browser_sitemap_query\`.
-- **\`browser_sitemap_build\` — cached once per session**: crawls the whole app into a Sitemap. Call it once at the start of a session; subsequent calls within ~30 minutes reuse the cache unless \`refresh: true\` is passed. Read already-crawled pages via \`browser_sitemap_query\` (modes: \`page\`, \`edges\`, \`mapJson\`, \`outline\`) — do not re-call \`browser_sitemap_build\` to "check."
-
-### Tool discipline — delta tools (consumers of captures)
-
-These consume the outputs of the capture tools above; they don't capture state themselves.
-
-- **\`browser_blueprint_diff\` — structured before/after delta**: takes two \`browser_blueprint\` results and returns \`elementsAdded\`, \`elementsRemoved\`, \`textChanges\`, \`repeatingCountChanges\`, \`urlChanged\`. Use it to derive assertions from observable state changes rather than guessing at what "success" looks like — capture before an action, perform the action, capture after, diff. An empty diff is itself a meaningful signal (e.g. a silent failure worth catching).
-- **\`browser_widget_contract_lookup\` — custom widget interaction recipes**: when a blueprint element has \`widgetType: "custom"\` or \`"unknown"\`, look up its interaction recipe by \`fingerprint\` + \`ref\`. On \`"found"\`, the returned contract specifies the interaction steps (e.g. for a Radix Select: click trigger → wait for portal → click option). On \`"needs_inference"\`, fall through to snapshot-driven trial clicks. Use this so generated tests interact with custom widgets through stable contracts, not brittle positional clicks.
+- **\`browser_blueprint\` — stable logical names**: logical names like \`add_order_btn\` and their derived \`getByRole\` locators survive page reloads and playback. Use them in generated test code. Call \`browser_blueprint\` before and after each meaningful action to capture state changes.
 
 ### Assertions
 Call \`browser_assert\` when assertions are needed. Always provide the \`expected\` value.

package/build/prompts/code-reuse.d.ts

@@ -0,0 +1 @@
+export declare function getCodeReusePrompt(testFile: string, language: string, framework?: string): string;

package/build/prompts/enhance-assertions/contractProviderAssertionsPrompt.d.ts

@@ -0,0 +1,2 @@
+import { EnhanceType } from "./sharedAssertionRules.js";
+export declare function getContractProviderAssertionsPrompt(testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/integrationAssertionsPrompt.d.ts

@@ -0,0 +1,2 @@
+import { EnhanceType } from "./sharedAssertionRules.js";
+export declare function getIntegrationAssertionsPrompt(testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/sharedAssertionRules.d.ts

@@ -0,0 +1,15 @@
+export type EnhanceType = "generation" | "maintenance";
+export declare const MAINTENANCE_SCOPE_NOTE = "Apply only to new test functions you are adding and existing test functions affected by changes in the diff. Do NOT modify test functions unrelated to the diff.";
+export declare function maintenanceTaskSuffix(enhanceType: EnhanceType): string;
+export interface AssertionEnrichmentExample {
+    language: string;
+    code: string;
+}
+export interface AssertionEnrichmentRule {
+    title: string;
+    description: string;
+    subPoints?: string[];
+    examples: AssertionEnrichmentExample[];
+}
+export declare function renderRule(index: number, rule: AssertionEnrichmentRule): string;
+export declare function getAssertionsPrompt(specificRules: AssertionEnrichmentRule[], scope: string, testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/uiAssertionsPrompt.d.ts

@@ -0,0 +1,2 @@
+import { EnhanceType } from "./sharedAssertionRules.js";
+export declare function getUIAssertionsPrompt(testFile: string, enhanceType: EnhanceType): string;

package/build/prompts/enhance-assertions/uiAssertionsPrompt.js

@@ -186,21 +186,40 @@ await page.context().addInitScript(() => {
 });
 \`\`\`
 
-And immediately after **every** \`page.goto()\` call in the test, add exactly these two statements — do NOT substitute a different activation approach or a different \`waitForFunction\` body:
+And immediately after **every** \`page.goto()\` call in the test, add exactly these three statements — do NOT substitute a different activation approach or different \`waitForFunction\` bodies:
 
 \`\`\`typescript
+// Wait for Flutter to bootstrap (confirms Flutter engine is ready before activating)
+await page.waitForFunction(
+    () => !!document.querySelector('flt-semantics-placeholder, flt-glass-pane, flutter-view'),
+    undefined,
+    { timeout: 30000 }
+);
 // Activate Flutter accessibility semantics by clicking the hidden placeholder
 await page.evaluate(() => { const el = document.querySelector('flt-semantics-placeholder'); if (el) el.dispatchEvent(new MouseEvent('click', { isTrusted: true, bubbles: true, cancelable: true })); });
-// Wait for Flutter semantics tree to be fully populated before interacting
+// Wait for the semantics tree to be live: the activation placeholder is gone AND
+// at least one flt-semantics node exists. Requiring a populated tree (not just the
+// placeholder's absence) guards against a vacuous pass when the bootstrap wait
+// above resolved on flt-glass-pane/flutter-view before the placeholder ever mounted.
 await page.waitForFunction(
-    () => document.querySelector('flt-semantics-host')?.children?.length > 0,
+    () => document.querySelector('flt-semantics-placeholder') === null
+        && document.querySelector('flt-semantics') !== null,
+    undefined,
     { timeout: 20000 }
 );
 \`\`\`
 
-The \`waitForFunction\` check MUST be \`children?.length > 0\` (tree populated), NOT \`!!document.querySelector('flt-semantics-host')\` (tree merely exists — it appears immediately but empty). If you see an existing body click or \`locator.click\` block after a goto, replace the entire block with the exact two statements above.
+Use exactly the three statements above. Do NOT use the two-argument form \`waitForFunction(fn, { timeout })\` — the timeout must be the third argument with \`undefined\` as the second. If you see an existing body click, \`locator.click\`, or old-style \`waitForFunction\` after a goto, replace the entire block with the exact three statements above.
+
+This is required because Flutter web renders to a \`<canvas>\` element (no traditional DOM). The first \`waitForFunction\` ensures Flutter has bootstrapped before activation; the \`dispatchEvent\` activates semantics; the second \`waitForFunction\` confirms the semantics tree is live (placeholder removed **and** \`flt-semantics\` nodes present). The combined gate handles both modes — when accessibility is pre-enabled (semantics active from frame 1, no placeholder ever shown) and when activation depends on the click — without passing prematurely on a frame where neither has happened yet.
 
-This is required because Flutter web accessibility semantics are not activated by default in headless Chromium. The \`isTrusted\` patch makes synthetic click events trusted; the \`dispatchEvent\` call triggers Flutter to build the ARIA tree; the \`children?.length > 0\` wait ensures the tree is fully populated before any \`getByRole\` queries or \`click()\` calls run. Without all three (patch + dispatchEvent + populated wait), Flutter interactions will time out in CI/Docker execution.
+**Then wait for the first element you interact with.** The gate above confirms the semantics tree *started* building, but Flutter populates it incrementally — individual widgets (a textbox, a button) can still be a beat behind when the gate passes, especially on a cold start where accessibility was not pre-enabled. The wrapped Skyramp page also enforces a short internal action timeout, so a lagging widget fails fast rather than waiting out the page default. Guard against this: immediately after the activation block (and after any later \`page.goto()\`'s block), add an explicit \`waitFor\` on the **first locator the test interacts with on that page**, before the interaction itself. Example:
+\`\`\`typescript
+// Wait for the specific target to be present before interacting (tree may still be filling in)
+await page.getByRole('textbox', { name: 'Username' }).waitFor({ state: 'visible', timeout: 20000 });
+await page.getByRole('textbox', { name: 'Username' }).fill('admin');
+\`\`\`
+Use the **same locator** that the next interaction uses — do not invent a new selector. This waits for exactly the widget the test needs, which is more reliable than any generic tree-node count (those are app-specific magic numbers); it is the per-target wait that Flutter-web automation guidance recommends over a one-size-fits-all readiness check.
 
 **Also check for brittle flt-semantic-node-* selectors:** If the test uses \`page.locator("#flt-semantic-node-N")\` for any interaction (clicks, navigations), replace it with a semantic selector (\`getByRole\`, \`getByText\`, or \`getByLabel\`) — \`flt-semantic-node-N\` IDs change between sessions and across devices, making the test brittle. Example: replace \`page.locator("#flt-semantic-node-78").click()\` with \`page.getByText("Settings").click()\` using the visible label from the same line's context.
 

package/build/prompts/fix-error-prompt.d.ts

@@ -0,0 +1 @@
+export declare function getFixErrorsPrompt(): string;

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.d.ts

@@ -0,0 +1 @@
+export declare const INIT_WORKSPACE_INSTRUCTIONS: string;

package/build/prompts/modularization/integration-test-modularization.d.ts

@@ -0,0 +1 @@
+export declare function getModularizationPrompt(filePath: string): string;

package/build/prompts/modularization/ui-test-modularization.d.ts

@@ -0,0 +1 @@
+export declare function getModularizationPrompt(filePath: string): string;

package/build/prompts/personas.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Skyramp personas injected into tool descriptions and prompts.
+ *
+ * In TestBot environments (SKYRAMP_FEATURE_TESTBOT=1), the persona is injected
+ * once via `claude --append-system-prompt` from the testbot GitHub Action
+ * (see testbot.git `src/agents/claude.ts` `loadQaPersona()`) rather than
+ * repeating it in every tool description. In that case getPersonaPrefix()
+ * returns empty string to avoid wasting context tokens. The testbot action
+ * pulls SKYRAMP_QA_PERSONA at runtime via the `@skyramp/mcp/personas` export.
+ *
+ * In IDE/MCP-direct environments, it is included in each tool description so the
+ * model has the role context available without a separate system prompt.
+ */
+export declare const SKYRAMP_QA_PERSONA = "You are acting as a Skyramp QA Automation Engineer. Your responsibility is to translate user test intent into precise, deterministic test artifacts \u2014 whether generating API tests from specs, recording browser interactions for UI flows, or maintaining existing test suites. Derive all parameters strictly from the codebase, workspace config, API schemas, and page snapshots. Never guess or hallucinate values.";
+/**
+ * Returns the persona prefix for use in tool descriptions.
+ * Returns an empty string when running inside TestBot — the testbot action
+ * appends the persona via `claude --append-system-prompt` instead, so we
+ * avoid duplicating it in every tool description.
+ */
+export declare function getPersonaPrefix(): string;

package/build/prompts/pom-aware-code-reuse.d.ts

@@ -0,0 +1 @@
+export declare function getPomAwareCodeReusePrompt(testFile: string): string;

package/build/prompts/startTraceCollectionPrompts.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerStartTraceCollectionPrompt(mcpServer: McpServer): void;

package/build/prompts/sut-setup/modes/adaptWorkflowPrompt.d.ts

@@ -0,0 +1,2 @@
+import { type SutPromptArgs } from "../shared.js";
+export declare function getAdaptWorkflowPrompt(args: SutPromptArgs): string;

package/build/prompts/sut-setup/modes/adaptWorkflowPrompt.js

@@ -0,0 +1,114 @@
+import { TESTBOT_WORKFLOW_PATH, buildContextBlock, buildCommonSutErrorsSection, buildLocalValidationSection, buildInputsBody, buildSutDefinitionBlock, } from "../shared.js";
+import { getPersonaPrefix } from "../../personas.js";
+import { PromptPlan } from "../../test-recommendation/promptPlan.js";
+// ── Step body builders ────────────────────────────────────────────────────────
+function buildReadSourcesBody(args) {
+    return args.sutSourceWorkflowFile
+        ? `Read the given source GitHub workflow file \`${args.sutSourceWorkflowFile}\` (the user's hint about which steps to lift), then ALSO read the rest of \`.github/workflows/\` and all infrastructure files (docker-compose, Kubernetes manifests, Helm charts) — the full SUT shape often lives across multiple files, so do NOT tunnel into the source workflow alone. Workflows show *how* the SUT is started; infrastructure files show *what* the SUT is. When a workflow step references an infra file (e.g., \`docker compose -f infra/compose.yml up\`, \`helm upgrade <chart>\`, \`kubectl apply -f k8s/\`), open that file too — services, ports, env vars, and dependencies live there.`
+        : `Read all GitHub workflow files in \`.github/workflows/\` AND all infrastructure files (docker-compose, Kubernetes manifests, Helm charts). Workflows show *how* the SUT is started; infrastructure files show *what* the SUT is. When a workflow step references an infra file (e.g., \`docker compose -f infra/compose.yml up\`, \`helm upgrade <chart>\`, \`kubectl apply -f k8s/\`), open that file too — services, ports, env vars, and dependencies live there. Pick the source workflow (the one whose SETUP/TEST/TEARDOWN steps will be lifted) once you have the full picture.`;
+}
+function buildClassifyStepsBody() {
+    return `From the source workflow, classify each step by its *purpose* — not by its name or surface mechanism (\`env:\`, \`with:\`, and \`\${{ secrets.* }}\` can appear on any category and do not determine it):
+a. SETUP — prepares the SUT (install, build, start services, migrate, seed, configure env or inject secrets for the SUT). Common attributes: \`env:\` blocks (e.g. \`DATABASE_URL\`, build flags), \`with:\` parameters (e.g. \`actions/cache\`, \`actions/setup-node\`), \`\${{ secrets.* }}\` references (e.g. registry login, deploy keys), dependency installs (e.g. \`npm ci\` before build).
+b. TEST — runs the test suite (will be replaced by \`skyramp/testbot\`). Common attributes: \`env:\` blocks (e.g. \`API_BASE_URL\`, \`AUTH_TOKEN\`), \`with:\` parameters (e.g. \`actions/cache\`, custom test-runner actions), \`\${{ secrets.* }}\` references (e.g. test credentials, live-integration keys), dependency installs (e.g. \`npm ci\` right before \`npm test\` in the same step).
+c. TEARDOWN — stops or cleans up.
+d. UNRELATED — does none of those (lint, format, notifications, badges).
+
+Output as:
+\`\`\`
+Step: "<step name>"  →  SETUP | TEST | TEARDOWN | UNRELATED
+\`\`\``;
+}
+function buildSummarizeBody() {
+    return `Summarize the SUT, pulling from all sources:
+a. Setup commands needed to bring up all services (may come from multiple workflows / infra files).
+b. Required secrets and env vars (with their \`\${{ secrets.* }}\` references and pass-through style — \`env:\` blocks vs. \`secrets: inherit\`).
+c. Runner needed (\`runs-on\` value; a larger runner for heavy builds — runner names vary by org, do not hardcode).
+d. How an auth token is obtained (script, step output, or secret).`;
+}
+function buildDecideIntroBody() {
+    return `The SUT must always be built from the PR's source code — Testbot reuses this workflow for every future PR, so it must validate the code in the PR being tested, not a stale snapshot. Use build: blocks in compose files (or docker build against the PR checkout) so images come from PR source. Pull-only image references and pinned upstream tags are fine for sidecars (databases, queues, caches), but the application services under test must be built locally.
+Evaluate the four patterns in strict priority order — always start with Pattern A and only escalate when it genuinely cannot express the setup. Full semantics for each lifecycle input are in the reference section below.`;
+}
+function buildPatternABody() {
+    return `Use when the entire setup — build, start, seed — can be expressed as one or two shell commands (e.g., docker compose up -d --build, make start, ./scripts/start.sh). Do NOT add any GHA steps. Set targetSetupCommand, targetReadyCheckCommand, targetReadyCheckTimeout, and targetTeardownCommand on the Testbot action; leave skipTargetSetup unset.`;
+}
+function buildPatternBBody() {
+    return `Use when the source workflow requires GHA-specific steps purely for environment or tooling (e.g., docker/setup-buildx-action, actions/cache, private registry login) but the actual service start can still be expressed as a single command. Copy only those tool/env pre-steps BEFORE the Testbot action. Set targetSetupCommand, targetReadyCheckCommand, targetReadyCheckTimeout, and targetTeardownCommand on the Testbot action; leave skipTargetSetup unset. Preserve every env:, with:, and \${{ secrets.* }} reference from the pre-steps exactly as written.`;
+}
+function buildPatternCBody() {
+    return `Use when the service startup itself requires multiple GHA steps that cannot be collapsed into a single command. Copy the source workflow's SETUP steps verbatim BEFORE the Testbot action. Set skipTargetSetup: 'true' and do not set targetSetupCommand. Set targetReadyCheckCommand and targetReadyCheckTimeout on the Testbot action. Add TEARDOWN steps AFTER the Testbot action with if: always(), or set targetTeardownCommand if a single command suffices — pick one, not both. Preserve every env:, with:, and \${{ secrets.* }} reference exactly as written.`;
+}
+function buildPatternDBody() {
+    return `Use when teardown is also too complex for a single command. Copy the SETUP steps BEFORE and TEARDOWN steps AFTER the Testbot action (with if: always()). Set skipTargetSetup: 'true'. Do not set targetSetupCommand or targetTeardownCommand. Preserve every env:, with:, and \${{ secrets.* }} reference exactly as written.`;
+}
+function buildEditWorkflowBody() {
+    return `Edit \`${TESTBOT_WORKFLOW_PATH}\` (already created by the Testbot installer):
+a. Apply the chosen pattern:
+   - Pattern A: set lifecycle inputs on the Testbot action, no GHA steps.
+   - Pattern B: add GHA tool/env pre-steps BEFORE the Testbot action, set lifecycle inputs (\`targetSetupCommand\`, \`targetReadyCheckCommand\`, \`targetTeardownCommand\`), leave \`skipTargetSetup\` unset.
+   - Pattern C: add GHA SETUP steps BEFORE the Testbot action, set \`skipTargetSetup: 'true'\`, set \`targetReadyCheckCommand\`, add TEARDOWN steps AFTER or set \`targetTeardownCommand\` — do NOT set \`targetSetupCommand\`.
+   - Pattern D: add GHA SETUP steps BEFORE and TEARDOWN steps AFTER the Testbot action, set \`skipTargetSetup: 'true'\`, do NOT set \`targetSetupCommand\` or \`targetTeardownCommand\`.
+b. Update \`runs-on\` to match the runner needed by the source workflow's setup — runner names vary by org, do not hardcode (see runner-label guidance in Step 3 above).
+c. Pass all required secrets through — reuse the same \`\${{ secrets.* }}\` references or \`secrets: inherit\`. For GHA steps (Patterns B, C, D), set secrets via \`env:\` on the individual steps that need them; for lifecycle inputs (Patterns A, B), set them on the Testbot action or at the job level.
+d. The basic file already contains the \`skyramp/testbot\` action — REPLACE the original workflow's test-run step with it, do NOT add a duplicate test runner step.`;
+}
+function buildConfigureAuthBody() {
+    return `Configure auth — use the lifecycle input reference above for full semantics of \`authTokenCommand\` and \`uiCredentials\`:
+a. If the source workflow exports or seeds an auth token, set \`authTokenCommand\` on the Testbot action (or create \`.skyramp/sut/get-auth-token.sh\`).
+b. If any service requires browser login, set \`uiCredentials\` on the Testbot action.
+c. Omit both when the SUT is unauthenticated.`;
+}
+function buildHandleShapeBody() {
+    return `Handle source-workflow shape:
+a. If the original workflow uses \`matrix\` builds, pick ONE configuration for the Testbot workflow (matrix runs would multiply Testbot invocations).
+b. If the original workflow uses \`needs:\` (job dependencies), inline the dependent job's steps into the Testbot job — Testbot runs as a single job.`;
+}
+function buildAdaptRestrictionsBody() {
+    return `Do not modify any other GitHub workflow files referenced. The only github workflow file you may edit is \`${TESTBOT_WORKFLOW_PATH}\`; every other workflow under \`.github/workflows/\` (including the source workflow) is read-only reference material.`;
+}
+// ── PromptPlan declaration ────────────────────────────────────────────────────
+const _adaptPlan = new PromptPlan()
+    .addPhase("adapt", "", { headerLevel: "hidden", stepFormat: "hash" })
+    .step("SCAN", "Understand the System Under Test in this repository", () => "")
+    .subStep("READ_SOURCES", "Read workflows and infra files", buildReadSourcesBody)
+    .subStep("CLASSIFY_STEPS", "Classify source workflow steps", buildClassifyStepsBody)
+    .subStep("SUMMARIZE", "Summarize the SUT", buildSummarizeBody)
+    .step("DECIDE", "Decide SUT setup strategy", buildDecideIntroBody)
+    .subStep("PATTERN_A", "Pattern A — Testbot lifecycle commands only (try this first, always)", buildPatternABody)
+    .subStep("PATTERN_B", "Pattern B — Hybrid: GHA pre-steps for tool/env setup + Testbot lifecycle commands for service start", buildPatternBBody)
+    .subStep("PATTERN_C", "Pattern C — GHA steps replace service startup + Testbot lifecycle validation", buildPatternCBody)
+    .subStep("PATTERN_D", "Pattern D — Fully wrapped by GHA steps", buildPatternDBody)
+    .step("INPUTS", "Plan the Testbot action inputs", () => buildInputsBody())
+    .step("ADAPT", "Edit the Testbot workflow and generate SUT files", () => "")
+    .subStep("EDIT_WORKFLOW", "Edit the workflow file", buildEditWorkflowBody)
+    .subStep("CONFIGURE_AUTH", "Configure auth", buildConfigureAuthBody)
+    .subStep("HANDLE_SHAPE", "Handle source-workflow shape", buildHandleShapeBody)
+    .subStep("RESTRICTIONS", "What not to do", buildAdaptRestrictionsBody)
+    .step("VERIFY", "Verify", () => "")
+    .subStep("COMMON_ERRORS", "Common SUT errors", () => buildCommonSutErrorsSection())
+    .subStep("LOCAL_VALIDATION", "Local validation", () => buildLocalValidationSection())
+    .done();
+// ── Goal section (static prose above the plan) ────────────────────────────────
+function buildGoalSection(args) {
+    const sourceLine = args.sutSourceWorkflowFile
+        ? `The user pointed at \`${args.sutSourceWorkflowFile}\` as the source workflow whose setup/teardown steps should be copied into the Testbot workflow. Use it as your primary source of setup steps — but still read the rest of the repo (other workflows, docker-compose, Kubernetes, Helm) to understand the full SUT shape.`
+        : `No specific source workflow was provided. Read ALL available GitHub workflows in this repository to learn how services are built, started, and authenticated, and pick the source workflow whose setup steps best match a SUT for testing (typically an e2e/integration workflow, not lint/release/security workflows).`;
+    const thinkingSourceClause = args.sutSourceWorkflowFile
+        ? `confirms you are using \`${args.sutSourceWorkflowFile}\` as the source of setup steps (or explains why a different workflow is a better fit)`
+        : `names the workflow you selected as the source of setup steps and explains why`;
+    return `### Goal
+1. Generate working System Under Test (SUT) files that enable the Skyramp Testbot workflow (\`${TESTBOT_WORKFLOW_PATH}\`) to test any PR-specific code in this repository end-to-end for the services supported (REST or gRPC service APIs, queues, frontend UIs).
+2. Source workflow: ${sourceLine}
+3. Required output:
+   a. Output a <thinking> block that: (i) ${thinkingSourceClause}, (ii) summarizes what you learned about the SUT — services, secrets, auth, runner size — pulling from ALL workflows and infrastructure files, and (iii) decides how the SUT will be brought up — prefer Testbot lifecycle commands alone (targetSetupCommand, targetReadyCheckCommand, targetTeardownCommand) when the setup can be expressed as a single shell command; add GHA pre-steps only for tooling that cannot run in a shell (Buildx, cache, registry login) while still using lifecycle commands for service start; escalate to full GHA steps replacing service startup only when a single command cannot express it; use fully wrapped GHA steps for both setup and teardown only as a last resort. State clearly which approach was chosen and why.
+   b. Adapt the Testbot workflow file (\`${TESTBOT_WORKFLOW_PATH}\`) for bringing up the system under test.`;
+}
+export function getAdaptWorkflowPrompt(args) {
+    return `${getPersonaPrefix()}${buildGoalSection(args)}
+
+${buildSutDefinitionBlock()}${buildContextBlock(args)}
+
+${_adaptPlan.render(args)}
+`;
+}

package/build/prompts/sut-setup/modes/dockerComposePrompt.d.ts

@@ -0,0 +1,2 @@
+import { type SutPromptArgs } from "../shared.js";
+export declare function getDockerComposePrompt(args: SutPromptArgs): string;