@skyramp/mcp 0.2.6 → 0.2.150-rc.mntnc

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;

package/build/prompts/sut-setup/shared.js

@@ -0,0 +1,132 @@
+/**
+ * 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 const TESTBOT_WORKFLOW_PATH = ".github/workflows/skyramp-testbot.yml";
+export var SutSetupMode;
+(function (SutSetupMode) {
+    SutSetupMode["None"] = "none";
+    SutSetupMode["AdaptWorkflow"] = "adapt_workflow";
+    SutSetupMode["DockerCompose"] = "docker_compose";
+})(SutSetupMode || (SutSetupMode = {}));
+/**
+ * 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 function buildSutDefinitionBlock() {
+    return `**System Under Test (SUT)** — the application services this workflow brings up so Testbot can exercise them end-to-end. The SUT is what runs the PR's source code: backend services (REST/gRPC APIs), their supporting infrastructure (databases, queues, caches), and any frontend UI under test. The SUT does NOT include the test runner itself or Testbot. Bringing up the SUT means building from PR source, starting all required services, seeding any data tests rely on, and exposing a health check that proves the system is ready for traffic.
+
+`;
+}
+export function buildContextBlock(args) {
+    const lines = [];
+    lines.push(`<context>`);
+    lines.push(`Repository path: ${args.repositoryPath}`);
+    lines.push(`Setup mode: ${args.sutSetupMode}`);
+    if (args.sutSourceWorkflowFile)
+        lines.push(`Source workflow file: ${args.sutSourceWorkflowFile}`);
+    if (args.sutSourceDockerComposeFile)
+        lines.push(`Source docker-compose file: ${args.sutSourceDockerComposeFile}`);
+    lines.push(`</context>`);
+    return lines.join("\n");
+}
+export function buildLocalValidationSection() {
+    return `Before reporting success, exercise the adapted workflow locally. Testbot's external fix loop only retries when SUT lifecycle commands are set on the Testbot action. When the SUT is brought up by surrounding GHA steps (skipTargetSetup: 'true'), the fix loop is skipped — so the local check below is the only safety net before the workflow is committed.
+Run commands one at a time in your shell — individual execution pinpoints failures far faster than running the whole workflow at once. Any non-zero exit is a fix-needed signal: adjust the workflow, re-run the failing command, and do not proceed until it passes.
+1. Validate build scripts and helper programs first — run these before anything else so build and auth failures surface cheaply:
+   a. Every helper script the workflow calls (e.g., \`./scripts/*.sh\`, \`make <target>\`, \`./gradlew <task>\`) — run each and confirm exit 0.
+   b. \`.skyramp/sut/get-auth-token.sh\` if present — run it and confirm it prints a non-empty token to stdout.
+   c. Validate any standalone Dockerfile referenced by GHA \`steps:\` (not by a compose service) with \`docker build\`. Do NOT also run \`docker build\` on Dockerfiles that belong to a compose service — \`docker compose build\` (next step) already builds them in one BuildKit graph; doubling up wastes ~5-10 GB of cache per service.
+   d. Every docker-compose file the workflow references — run \`docker compose -f <path> config\` to validate the YAML, then \`docker compose -f <path> build\`.
+   e. **Disk hygiene between heavy builds.** Between any two build commands (Dockerfile, compose, helper scripts that build), if the runner is under ~5 GB free or you see \`no space left on device\`, run \`docker builder prune -af -f && docker image prune -af\` before the next build. This frees BuildKit cache + dangling images without losing the running stack. Skipping this on heavy SUTs (medusa, calcom, mattermost, supabase) exhausts the ~14 GB \`ubuntu-latest\` disk mid-validation.
+2. Validate the SUT lifecycle — choose the branch that matches the chosen pattern:
+   a. If lifecycle commands are set on the Testbot action (skipTargetSetup is unset):
+      i. Run \`targetSetupCommand\` — confirm exit 0.
+      ii. Poll \`targetReadyCheckCommand\` until it exits 0 within \`targetReadyCheckTimeout\` seconds.
+      iii. Run \`targetTeardownCommand\` — confirm cleanup and exit 0.
+   b. If GHA steps wrap the Testbot action (skipTargetSetup: 'true'):
+      i. Extract the shell body of each SETUP step and run them in order. If a step depends entirely on a \${{ secrets.* }} value your shell cannot resolve, note it in <thinking> and skip — do not fabricate a value.
+      ii. Poll \`targetReadyCheckCommand\` until it exits 0.
+      iii. Extract and run each TEARDOWN step's body in order so the next iteration starts clean.
+Only proceed to the success report once setup → health check → teardown all pass.`;
+}
+/**
+ * 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 function buildAddToTestbotWorkflowSection() {
+    return `#### Testbot action inputs - Add target lifecycle commands and auth to Testbot Workflow
+For the full Testbot action input reference (defaults, edge cases, advanced options beyond the ones called out below), see the Testbot README: https://github.com/letsramp/testbot#inputs
+
+Target lifecycle inputs (control how Testbot starts, validates, and stops the SUT):
+1. \`targetSetupCommand\` — shell command that builds and starts all SUT services. Testbot runs this before tests.
+   a. Default when unset: \`docker compose up -d\` (starts existing images, does NOT build).
+   b. For PR-source builds use \`docker compose up -d --build\` or the equivalent for helm/script-based SUTs.
+   c. With a dedicated compose file (reused or generated), point at it explicitly: \`docker compose -f .skyramp/sut/docker-compose.testbot.yml --project-directory . up -d --build\`.
+   d. Override whenever the source workflow's start sequence differs from the default.
+2. \`targetReadyCheckCommand\` — polling command (e.g., \`curl -sf http://localhost:8080/health\`) that Testbot runs repeatedly after setup until it exits 0 (service is ready) or the timeout is reached.
+   a. **CRITICAL: Always set this to a valid target readiness check command.** Required in every pattern: when \`targetSetupCommand\` is explicit, when relying on the \`docker compose up -d\` default, AND when surrounding GHA steps bring the SUT up before the Testbot action (\`skipTargetSetup: 'true'\`). Testbot's fail-early gate throws \`Unable to verify service readiness\` when no readiness signal is available (neither this nor a workspace service \`baseUrl\`) and the action exits non-zero. It is also what gates a backgrounded \`targetSetupCommand\` — without it Testbot can't tell when the service is actually listening.
+3. \`targetReadyCheckTimeout\` — seconds to wait for \`targetReadyCheckCommand\` to succeed.
+   a. Default: \`1800\` (30 min) — sized for cold \`docker compose --build\` runs on multi-service stacks. The loop exits on the first success, so fast services pay no extra cost. Override only if you want to fail faster on stuck setups (e.g. \`'300'\` for a small single-service SUT).
+4. \`targetTeardownCommand\` — shell command that stops and cleans up the SUT after tests (e.g., \`docker compose down -v\`, or \`docker compose -f .skyramp/sut/docker-compose.testbot.yml --project-directory . down -v\` for a dedicated compose file).
+   a. Always set this so each run starts from a clean state.
+   b. Omit only when teardown is handled by surrounding GHA steps with \`if: always()\`.
+5. \`skipTargetSetup\` — when \`'true'\`, Testbot skips running \`targetSetupCommand\` entirely.
+   a. Set this only when GHA steps surrounding the Testbot action already bring the SUT up.
+   b. Leave it unset (or \`'false'\`) when Testbot should run the full lifecycle via the inputs above.
+Auth inputs (used by Testbot to authenticate against the running SUT during test recording and execution):
+6. \`authTokenCommand\` — shell command whose stdout is the auth credential for REST/gRPC API testing (e.g., a Bearer token, API key, or session cookie). Testbot captures the output and injects it as the \`Authorization\` header.
+   a. Set this when the SUT requires authentication for API calls.
+   b. If the source workflow exports a token via a step output or script, wire that same script here (e.g., \`bash .skyramp/sut/get-auth-token.sh\`).
+   c. If the workflow seeds a test user during setup, create \`.skyramp/sut/get-auth-token.sh\` that logs in with those credentials and prints the token.
+   d. Omit when the SUT APIs are unauthenticated.
+7. \`uiCredentials\` — \`username:password\` pair typed into the browser login form during UI test recording (format: \`myuser:mypassword\`).
+   a. Set for any frontend service that requires browser-based login.
+   b. Use \`\${{ secrets.SKYRAMP_UI_CREDENTIALS }}\` if the secret exists, otherwise use credentials seeded during SUT setup.
+Workflow / job level settings (set on the workflow or job, not as \`skyramp/testbot\` action inputs):
+8. Secrets / environment variables — pass every secret/env var the setup needs into the workflow via an \`env:\` block or \`secrets: inherit\`, and add any dependency-resolution steps/jobs the SUT requires.
+9. \`runs-on\` runner label — switch to a larger runner when the SUT needs more disk or memory: heavy Docker builds, large dependency installs, or a multi-service (3+) compose stack. Standard runners run out of disk and crash with \`No space left on device\`. Runner names vary by org — do not hardcode \`large-ubuntu\`. Pick the label by (a) preserving whatever larger label the source workflow already uses (never downgrade to \`ubuntu-latest\`), (b) reusing the label adjacent heavy or integration jobs in \`.github/workflows/\` already use, or (c) falling back to a known GitHub-hosted large label such as \`ubuntu-latest-large\`.
+
+#### What to do
+Edit \`${TESTBOT_WORKFLOW_PATH}\` in place (already created by the Testbot installer) — do NOT recreate it. Add only what the SUT needs onto the existing \`skyramp/testbot\` action step, alongside the inputs the installer already added:
+1. The 4 target lifecycle inputs — \`targetSetupCommand\`, \`targetReadyCheckCommand\`, \`targetReadyCheckTimeout\`, \`targetTeardownCommand\`.
+2. The 2 auth inputs when the SUT needs them — \`authTokenCommand\` and/or \`uiCredentials\`.
+3. Any secrets / environment variables and dependency-resolution steps/jobs the setup needs (input 8).
+4. The \`runs-on\` runner label, if a larger runner is needed (input 9).
+5. Use a daemon/detached form for \`targetSetupCommand\` — \`docker compose up -d --build\`, \`nohup npm start &\`, \`./server &\`, \`pnpm --prefix ./apps/studio start &\`. The command should launch the service and exit; \`targetReadyCheckCommand\` is what gates readiness. Testbot backgrounds foreground-blocking commands (\`npm start\`, \`python app.py\`, \`./server\`) automatically after a 5-minute timeout as a safety net, so they will eventually work — but daemon mode is faster (no 5-minute wait) and surfaces startup crashes clearly via the command's exit code. If no daemon form is available and the repo has no \`docker-compose.yml\`, wrap the foreground command in compose (a \`Dockerfile\` + \`docker-compose.yml\` running \`npm start\`) so it can be launched with \`docker compose up -d --build\`. Only fall back to a GHA pre-step with \`&\` (e.g. \`run: npm start &\`) if Docker is not feasible.
+
+#### What not to do
+1. IMPORTANT — do NOT remove or change the existing \`sutSetupMode\` input (nor \`sutSourceWorkflowFile\` / \`sutSourceDockerComposeFile\`). Leave \`sutSetupMode\` exactly as provided: Testbot flips it to \`none\` automatically after validation succeeds, and the committed \`sutSetupMode\` value is the signal that tells the next CI run to validate this adapted workflow rather than run tests. Deleting it or setting it to \`none\` breaks the bootstrap/validation cycle.
+2. Do not point the SUT at a prebuilt upstream image (e.g. \`image: org/app:latest\` or a fixed commit SHA from \`main\`) for any application service under test. The image will lag the PR and Testbot will validate stale code.
+3. Do not point the SUT at a remote staging or production environment for application services under test. Staging code drifts from PR source and turns Testbot's results into noise. External infra is acceptable only for sidecar dependencies the PR does not change (e.g. a managed test database).
+4. Do not use a foreground-blocking command as \`targetSetupCommand\` (e.g. \`npm start\`, \`pnpm --prefix ./apps/studio start\`, \`python app.py\`, \`prefect server start\`, \`./server\`) — see input 5 in "What to do" above for daemon forms and the compose-wrap fallback.
+5. Do not leave server processes running between fix-loop retries. If \`targetSetupCommand\` starts a direct process (not \`docker compose\`), always set \`targetTeardownCommand\` to kill it (e.g. \`pkill -f "node dist/index.js"\` or \`docker compose down\`). Without teardown, retried setup attempts will fail with \`EADDRINUSE\` because the previous process still holds the port.
+`;
+}
+/**
+ * `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 function buildInputsBody() {
+    const text = buildAddToTestbotWorkflowSection();
+    const firstNewline = text.indexOf("\n");
+    return text.slice(firstNewline + 1);
+}
+export function buildCommonSutErrorsSection() {
+    return `Before finishing, verify the adapted Testbot workflow setup against common errors seen during SUT setup:
+1. port_conflict — another container is already using the port. Pick a free host port or stop the conflicting container.
+2. image_not_found / build_failed — the referenced image does not exist for this SHA, or the build step has the wrong context/Dockerfile path. Build from PR source, do not rely on upstream commit-SHA tags.
+3. healthcheck_timeout — the service is slow to come up. Use \`targetReadyCheckTimeout >= 120\` and ensure the health endpoint actually exists.
+4. connection_refused — the service is not listening on the expected host/port (often binding to 127.0.0.1 inside the container; bind to 0.0.0.0).
+5. dependency_error — required service (DB, cache, queue) is missing from compose or not healthy before the app starts. Add \`depends_on\` with \`condition: service_healthy\`.
+6. permission_denied — script is not executable (\`chmod +x\`) or volume mount has wrong ownership.
+7. auth_endpoint_404 / auth_credentials_invalid — the auth script hits a wrong path, or the database has no seeded user. The auth script must create the user before login when starting from a fresh DB.
+8. missing env vars / secrets — required env vars are unset on the runner. Either default them in the script or pass them through workflow \`env:\`.
+9. no_space_left — the runner ran out of disk space (\`No space left on device\`). This happens on standard runners when the SUT involves large Docker builds, many npm packages, or multiple compose services that pull large images. Switch \`runs-on\` to a larger runner — runner names vary by org, do not hardcode \`large-ubuntu\`. Pick the label by (a) preserving whatever larger label the source workflow already uses, (b) reusing the label adjacent heavy or integration jobs in \`.github/workflows/\` already use, or (c) falling back to a known GitHub-hosted large label such as \`ubuntu-latest-large\`. Indicator: source workflow already specifies a large runner, or the SUT has multi-stage Docker builds / a compose file with 3+ services.
+Do not add an in-prompt fix loop — Testbot's external validator will retry with concrete error context if any of these occur.`;
+}

package/build/prompts/test-maintenance/actionsInstructions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Prompt language for skyramp_actions output — the LLM_INSTRUCTIONS block
+ * emitted to the agent that applies UPDATE and REGENERATE edits.
+ *
+ * Kept separate from actionsTool.ts so prompt text is co-located with other
+ * maintenance prompts and can be reviewed/edited without touching tool logic.
+ */
+export interface RenameEntry {
+    oldPath: string;
+    newPath: string;
+    method: string;
+}
+/** Strategy string for URL-path find-and-replace updates. */
+export declare function buildRenameStrategy(): string;
+/** Strategy string for file renames after path substitution. */
+export declare function buildFileRenameStrategy(): string;
+/** Strategy string for in-place UPDATE edits. */
+export declare function buildUpdateStrategy(): string;
+/** Strategy string for REGENERATE — call generation tool to overwrite the file. */
+export declare function buildRegenerateStrategy(): string;
+/** Per-file instruction block for a single UPDATE recommendation. */
+export declare function buildUpdateFileInstruction(params: {
+    testFile: string;
+    renames: RenameEntry[];
+    suggestedNewFile?: string;
+    updateInstructions?: string;
+    rationale?: string;
+}): string;
+/** Per-file instruction block for a single REGENERATE recommendation. */
+export declare function buildRegenerateFileInstruction(params: {
+    testFile: string;
+    updateInstructions?: string;
+    outputDir: string;
+    outputFile: string;
+}): string;

package/build/prompts/test-maintenance/drift-analysis-prompt.d.ts

@@ -0,0 +1,4 @@
+export declare function buildDriftAnalysisPrompt(stateFile?: string, existingTests?: Array<{
+    testFile: string;
+    source?: string;
+}>): string;

package/build/prompts/test-maintenance/driftAnalysisSections.d.ts

@@ -0,0 +1,13 @@
+export declare function buildActionDecisionTree(): string;
+/** @deprecated use the individual check functions; this function is no longer part of the prompt */
+export declare function buildBreakingChangePatterns(): string;
+export declare function buildCheckEndpointExistence(): string;
+export declare function buildCheckResponseShape(): string;
+export declare function buildCheckAuthAndAuthorization(): string;
+export declare function buildCheckBehavioralContract(): string;
+export declare function buildCheckAssignAction(): string;
+export declare function buildCheckAdditiveFields(): string;
+export declare function buildDriftOutputChecklist(stateFile?: string, existingTests?: Array<{
+    testFile: string;
+    source?: string;
+}>): string;

package/build/prompts/test-maintenance/driftAnalysisSections.js

@@ -136,7 +136,9 @@ Actions:
 **UPDATE vs REGENERATE — the deciding question is whether the root response wrapper changed:**
 - **REGENERATE** only when a new top-level envelope object wraps the entire payload or the root key is renamed so that essentially every existing assertion must change.
 - **UPDATE** for everything else. If you can describe the fix as "patch these N assertion paths", it is UPDATE regardless of how many paths there are.
-- When every assertion in the file is invalid, it is REGENERATE. When you can still patch individual paths, it is UPDATE.`;
+- When every assertion in the file is invalid, it is REGENERATE. When you can still patch individual paths, it is UPDATE.
+
+**Non-test consumer check:** When the diff removes or renames response fields, also grep the repository for non-test source files that import or reference the changed schema type (e.g. \`grep -r "WorkQueueStatusDetail" src/\`). If any client model, SDK class, or serializer references the old field names, add a VERIFY entry for each such file in your recommendations so the developer is alerted — these are not test files but they will break at runtime.`;
 }
 export function buildCheckAuthAndAuthorization() {
     return `Has the authentication or authorization for this endpoint changed?
@@ -180,7 +182,7 @@ export function buildCheckAssignAction() {
 **Every action requires a specific rationale — including IGNORE:**
 - UPDATE / REGENERATE / DELETE: quote the specific diff line that triggered it.
 - VERIFY: name the uncertain element (e.g. "model-only change, cannot confirm field is exposed without checking the output layer").
-- IGNORE: name the specific reason the changed code cannot reach this test's endpoint (e.g. "diff only touches \`auth/session-service.js\` — this test targets \`/api/v1/orders\` which has no session dependency"). Generic "unrelated endpoint" or "service boundary" without a diff reference is not sufficient.
+- IGNORE: name the changed file(s) from the diff AND explain why they cannot reach this test's endpoint (e.g. "diff only touches \`auth/session-service.js\` — this test targets \`/api/v1/orders\` which has no session dependency"). You must reference at least one specific changed file from the diff. Generic "unrelated endpoint" or "service boundary" without naming the changed file is not sufficient.
 
 - If the Additive Fields check flagged a new field with output layer signal confirmed in the diff → action is UPDATE. If the Additive Fields check returned VERIFY (model-only signal, no output layer change) → action remains VERIFY.
 - **Scope gate:** If the changed code is clearly not reachable through the service or base URL this test targets, assign IGNORE.
@@ -222,12 +224,16 @@ export function buildDriftOutputChecklist(stateFile, existingTests) {
     const noTestsNote = !hasTests
         ? `\nNo existing tests were found. Call \`skyramp_actions\` with \`recommendations: []\` and explain in your report why no maintenance was needed (e.g. "no existing tests cover the changed endpoints" or "PR adds a new endpoint with no prior coverage").\n`
         : "";
+    const symbolDiscoveryStep = hasTests
+        ? `**Symbol import discovery (before assessing tests):** If the diff adds or modifies class, function, or type definitions, grep the repository for test files that import those symbol names. Add any matched test files not already in the list below to your assessment — these files may need updating even if their path doesn't match the changed resource name. Include all discovered files in the \`recommendations[]\` passed to \`skyramp_actions\` — do NOT edit them directly without going through \`skyramp_actions\` first.`
+        : "";
     const existingTestSection = `**Existing tests (${existingTests?.length ?? 0} total) — assess ALL of the following:**
 ${testList}
 ${noTestsNote}
 **UPDATE scope notes:**
 - UPDATE is an in-place edit — do not recommend creating a new file for an already-tested endpoint.
 - If a new HTTP method is added to a resource, emit a separate UPDATE entry for every existing test file that covers that resource (contract, integration, UI).
+- **When multiple test files cover the same changed resource, prefer the most resource-specific file** (e.g. a file whose name directly reflects the changed resource) over a generic shared test file. Only UPDATE both if the change affects base types shared across both files.
 
 For each test above, output one entry:
 - **IGNORE**: \`{testFile} — IGNORE: {reason the diff cannot reach this test's endpoint}\`
@@ -253,7 +259,7 @@ Rationale: DELETE because {quoted diff signal}; all covered endpoints removed
 \`\`\`
 Include ALL actions — IGNORE, VERIFY, UPDATE, REGENERATE, DELETE — in the \`recommendations[]\` passed to \`skyramp_actions\`. For \`[external]\` tests: \`skyramp_actions\` will apply UPDATE edits and surface REGENERATE/DELETE as report-only findings.
 Be concise — one line per IGNORE/VERIFY entry.`;
-    const sections = [existingTestSection, finalStep];
+    const sections = [symbolDiscoveryStep, existingTestSection, finalStep].filter(Boolean);
     return `<output_format>
 Complete ALL of the following: