@skyramp/mcp 0.2.7 → 0.2.8

package/build/index.js

@@ -26,6 +26,7 @@ import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBa
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.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");
@@ -173,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/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/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;

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

@@ -0,0 +1,292 @@
+import { buildContextBlock, buildInputsBody, buildCommonSutErrorsSection, buildLocalValidationSection, buildSutDefinitionBlock, } from "../shared.js";
+import { getPersonaPrefix } from "../../personas.js";
+import { PromptPlan } from "../../test-recommendation/promptPlan.js";
+// ── Step body builders ────────────────────────────────────────────────────────
+function buildScanComposeBody(args) {
+    const composeFile = args.sutSourceDockerComposeFile?.trim();
+    if (composeFile) {
+        return `A specific compose file was provided: \`${composeFile}\`. Use it directly — do NOT scan for other compose files and do NOT generate a new one. (Strategy in Step 2 will be REUSE with this file.)`;
+    }
+    return `Search the repository for existing docker-compose files:
+- \`docker-compose.yml\`, \`docker-compose.yaml\`, \`compose.yml\`, \`compose.yaml\` at root
+- \`docker-compose.*.yml\` variants (e.g., \`docker-compose.dev.yml\`, \`docker-compose.e2e.yml\`)
+- Compose files in subdirectories (\`deploy/\`, \`.docker/\`, etc.)
+
+For each compose file found, determine if it is:
+- **Application compose** — builds or runs the actual backend API / frontend UI (has \`build:\` directives pointing to repo source, or services that are the app's entry points). USE THIS.
+- **Infrastructure-only compose** — contains only databases, Redis, message queues, mail servers, object storage. NOT sufficient for SUT setup alone.`;
+}
+function buildDecideStrategyBody(args) {
+    const composeFile = args.sutSourceDockerComposeFile?.trim();
+    if (composeFile) {
+        return `A specific compose file was provided in Step 1 (\`${composeFile}\`). Strategy is REUSE with this file. Confirm your decision:
+
+\`\`\`
+Decision: REUSE
+Compose file: ${composeFile}
+Reason: provided by the user
+\`\`\``;
+    }
+    return `Choose between reuse and generate based on what Step 1 found:
+- If an application docker-compose file was found → strategy is REUSE.
+- If only infrastructure-only compose files exist, or no compose files found → strategy is GENERATE.
+
+Output your decision:
+\`\`\`
+Decision: REUSE | GENERATE
+Compose file: <path to file if reusing, or "none" if generating>
+Reason: <brief explanation>
+\`\`\``;
+}
+function buildPrAccurateSutSection() {
+    return `The SUT must run code from the PR branch, not a pre-built upstream image. Determine how to build the application from the PR source:
+
+1. If the repo uses Docker images for deployment (e.g., \`SERVER_IMAGE\` env var in compose), then build a local image from the PR code and use it. Do NOT use commit-SHA-tagged images from upstream registries (those only exist for the upstream repo's CI, not for forks or testbot PRs).
+2. If the repo builds from source (Go binary, Node app, Python package), then include the build step in the workflow before starting services.
+3. Use a stable base/build image (e.g., the repo's official build container or a standard runtime image).
+4. The built image or binary stays local to the runner — no registry push needed.`;
+}
+/**
+ * Build the reuse instructions body (no section header — the caller supplies it).
+ * When `composeFile` is provided the concrete path is interpolated into the
+ * `docker compose -f <path>` commands so the agent wires the given file directly;
+ * otherwise generic `<path>` placeholders are kept for the discovery flow where
+ * the agent picks the file itself.
+ */
+function getReuseDockerComposeInstructions(composeFile) {
+    const file = composeFile?.trim();
+    const ref = file ?? "<path>";
+    const intro = file
+        ? `Use the provided application docker-compose file \`${file}\` directly. Wire it as \`targetSetupCommand\`.`
+        : `You found an existing application docker-compose file. Wire it directly as \`targetSetupCommand\`.`;
+    return `${intro}
+
+1. Verify the compose file starts the application (not just infrastructure).
+2. Determine the correct command:
+   - If the compose uses \`build:\` directives: \`docker compose -f ${ref} up -d --build\`
+   - If it uses pre-built images: \`docker compose -f ${ref} up -d\`
+   - If it has builder services (one-shot build steps): run builders first, then start runtime services.
+3. Determine the health check command from the compose file's \`healthcheck:\` definitions or from known health endpoints.
+4. Determine the teardown command: \`docker compose -f ${ref} down -v\`
+5. If the compose file defines admin credentials in environment variables, create \`.skyramp/sut/get-auth-token.sh\` using those credentials.
+
+These resolved commands are wired onto the \`skyramp/testbot\` action step using the input semantics from Step 3 above.`;
+}
+/** Generate instructions used when no reusable application compose file exists. */
+const GENERATE_DOCKER_COMPOSE_INSTRUCTIONS = `No usable application docker-compose was found. Generate one from scratch.
+
+Steps:
+1. Inspect the repository to determine how to build and run the application:
+   - Does it have a Dockerfile? → Use \`build: { context: . }\`
+   - No Dockerfile but has package.json? → Use \`node:20-alpine\` base image + volume mount + npm install + start
+   - No Dockerfile but has requirements.txt/pyproject.toml? → Use \`python:3.12-slim\` base image + pip install + start
+   - No Dockerfile but has pom.xml/build.gradle? → Use appropriate JDK image + build + run
+
+2. Determine database requirements:
+   - If app references PostgreSQL → add postgres service with healthcheck
+   - If app references MongoDB → add mongo service with replica set
+   - If app references Redis → add redis service
+   - Prefer SQLite when the app supports it (simpler, no extra service)
+
+3. Generate \`.skyramp/sut/docker-compose.testbot.yml\` with:
+   - The compose file must be runnable with: \`docker compose -f .skyramp/sut/docker-compose.testbot.yml --project-directory . up -d --build\`
+   - The \`--project-directory .\` means build context is the repository root (NOT .skyramp/sut/)
+   - Healthchecks for ALL services (testbot relies on \`--wait\`)
+   - Simple testbot credentials in environment (admin@testbot.com / testbot)
+   - Generous \`start_period\` (30-120s) for CI cold builds
+   - For monorepos: may need a builder service that runs first
+
+4. Generate \`.skyramp/sut/get-auth-token.sh\` if the application requires authentication:
+   - Script must output ONLY the token to stdout (debug output to stderr)
+   - Poll health endpoint before attempting auth (300s timeout)
+   - Credentials must match what's in the docker-compose environment variables
+   - Use \`set -euo pipefail\` and \`jq\` for JSON parsing
+
+<example label="simple-single-service">
+\`\`\`yaml
+# .skyramp/sut/docker-compose.testbot.yml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8055:8055"
+    environment:
+      SECRET: testbot-secret
+      ADMIN_EMAIL: admin@testbot.com
+      ADMIN_PASSWORD: testbot
+      DB_CLIENT: sqlite3
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:8055/health"]
+      interval: 5s
+      timeout: 5s
+      retries: 24
+      start_period: 15s
+\`\`\`
+</example>
+
+<example label="service-with-postgres">
+\`\`\`yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: app
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: testbot
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  app:
+    build:
+      context: .
+    ports:
+      - "3000:3000"
+    environment:
+      DATABASE_URL: postgres://app:testbot@postgres/app
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:3000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 30s
+\`\`\`
+</example>
+
+<example label="monorepo-with-builder">
+\`\`\`yaml
+services:
+  builder:
+    image: node:20-alpine
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: sh -c "corepack enable && pnpm install --frozen-lockfile && pnpm build"
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: app
+      POSTGRES_USER: app
+      POSTGRES_PASSWORD: testbot
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  backend:
+    build: { context: . }
+    depends_on:
+      builder:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+    ports:
+      - "9000:9000"
+    environment:
+      DATABASE_URL: postgres://app:testbot@postgres/app
+      JWT_SECRET: testbot-jwt-secret
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:9000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 90s
+
+  frontend:
+    image: node:20-alpine
+    working_dir: /app/apps/web
+    volumes:
+      - .:/app
+    depends_on:
+      backend:
+        condition: service_healthy
+    ports:
+      - "3000:3000"
+    environment:
+      NEXT_PUBLIC_API_URL: http://localhost:9000
+    command: sh -c "npm run dev -- --hostname 0.0.0.0 --port 3000"
+    healthcheck:
+      test: ["CMD-SHELL", "bash -c '</dev/tcp/localhost/3000' || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 120s
+\`\`\`
+</example>
+
+<example label="source-mount-no-dockerfile">
+\`\`\`yaml
+services:
+  app:
+    image: python:3.12-slim
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: sh -c "pip install -e . && uvicorn main:app --host 0.0.0.0 --port 8000"
+    ports:
+      - "8000:8000"
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:8000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 30
+      start_period: 60s
+\`\`\`
+</example>
+`;
+function buildApplyStrategyBody(args) {
+    const composeFile = args.sutSourceDockerComposeFile?.trim();
+    if (composeFile) {
+        return `#### Reuse the provided Docker Compose file
+${getReuseDockerComposeInstructions(composeFile)}`;
+    }
+    return `Apply the strategy selected in Step 2:
+
+#### If REUSE selected — Reuse existing Docker Compose
+${getReuseDockerComposeInstructions()}
+
+#### If GENERATE selected — Generate new Docker Compose
+${GENERATE_DOCKER_COMPOSE_INSTRUCTIONS}`;
+}
+// ── PromptPlan declaration ────────────────────────────────────────────────────
+const _composePlan = new PromptPlan()
+    .addPhase("compose", "", { headerLevel: "hidden", stepFormat: "hash" })
+    .step("SCAN", "Understand the System Under Test in this repository", buildScanComposeBody)
+    .step("DECIDE", "Decide SUT setup strategy", buildDecideStrategyBody)
+    .step("INPUTS", "Plan the Testbot action inputs", () => buildInputsBody())
+    .step("BUILD", "Edit the Testbot workflow and generate SUT files", () => "")
+    .subStep("PR_ACCURATE", "Build PR-accurate SUT", buildPrAccurateSutSection)
+    .subStep("APPLY", "Apply the chosen strategy", buildApplyStrategyBody)
+    .step("VERIFY", "Verify", () => "")
+    .subStep("COMMON_ERRORS", "Common SUT errors", () => buildCommonSutErrorsSection())
+    .subStep("LOCAL_VALIDATION", "Local validation", () => buildLocalValidationSection())
+    .done();
+export function getDockerComposePrompt(args) {
+    const composeFile = args.sutSourceDockerComposeFile?.trim();
+    const taskLine = composeFile
+        ? `Your task is to find a working System Under Test (SUT) setup using the given Docker Compose file \`${composeFile}\`. You will reuse this file, validate that services start correctly, fix any errors, and wire the working commands into the testbot workflow.`
+        : `Your task is to find a working System Under Test (SUT) setup using Docker Compose that builds and deploys the services in this repository. You will either reuse an existing docker-compose file or generate a new one, validate that services start correctly, fix any errors, and wire the working commands into the testbot workflow.`;
+    const thinkingStep = composeFile
+        ? `1. Output a <thinking> block to explain how the provided compose file \`${composeFile}\` starts the application and what commands are needed to bring it up.`
+        : `1. Output a <thinking> block to explain whether you found an existing compose file, whether it is application or infrastructure-only, and your decision to reuse or generate.`;
+    return `${getPersonaPrefix()}${taskLine}
+
+${buildSutDefinitionBlock()}The testbot installer has already created a basic \`.github/workflows/skyramp-testbot.yml\` in this PR with no SUT setup commands. Manage the SUT lifecycle exclusively through inputs on the existing \`skyramp/testbot\` action step — do NOT add separate GHA setup/teardown steps and do NOT set \`skipTargetSetup\`.
+
+Before generating any files, you MUST:
+${thinkingStep}
+2. Then proceed with the instructions below.
+${buildContextBlock(args)}
+
+${_composePlan.render(args)}
+`;
+}

package/build/prompts/sut-setup/shared.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Path of the Testbot workflow file relative to the repo root. Created by the
+ * Testbot installer and edited in-place by every SUT setup mode.
+ */
+export declare const TESTBOT_WORKFLOW_PATH = ".github/workflows/skyramp-testbot.yml";
+export declare enum SutSetupMode {
+    None = "none",
+    AdaptWorkflow = "adapt_workflow",
+    DockerCompose = "docker_compose"
+}
+export interface SutPromptArgs {
+    repositoryPath: string;
+    sutSetupMode: string;
+    sutSourceWorkflowFile: string;
+    sutSourceDockerComposeFile: string;
+}
+/**
+ * Glossary block rendered right after the first mention of "SUT" in each
+ * setup prompt. Shared across modes so the LLM gets a single explicit
+ * definition rather than inferring it from context.
+ */
+export declare function buildSutDefinitionBlock(): string;
+export declare function buildContextBlock(args: SutPromptArgs): string;
+export declare function buildLocalValidationSection(): string;
+/**
+ * Returns the canonical "add to the Testbot workflow" block: every input that
+ * controls the SUT lifecycle, auth, and workflow-level setup, followed by the
+ * shared What to do / What not to do guidance (including the sutSetupMode
+ * bootstrap guard). Shared by every SUT setup mode (adapt_workflow and
+ * docker_compose) so the input semantics and rules never drift between prompts.
+ */
+export declare function buildAddToTestbotWorkflowSection(): string;
+/**
+ * `buildAddToTestbotWorkflowSection()` output with its leading
+ * `#### Testbot action inputs ...` header stripped — for use as a PromptPlan
+ * step body where the PromptPlan step header replaces the inline `####`.
+ */
+export declare function buildInputsBody(): string;
+export declare function buildCommonSutErrorsSection(): string;