@skyramp/mcp 0.1.0-rc.5 → 0.1.0

package/build/prompts/pom-aware-code-reuse.js

@@ -0,0 +1,440 @@
+import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
+const TS_UTILS_FILE = "skyrampUtils.ts";
+export function getPomAwareCodeReusePrompt(testFile) {
+    return `# POM-AWARE CODE REUSE — TYPESCRIPT/PLAYWRIGHT
+
+## COMPLIANCE RULES — READ THIS FIRST, APPLY TO EVERY STEP
+
+You are about to execute a multi-step process. These rules govern your behavior for the entire session:
+
+1. **Read the ENTIRE guidance before taking any action**
+2. **Execute steps in order** — never skip, combine, or reorder steps
+3. **Output all intermediate artifacts** (POM catalog, mapping table) to chat before proceeding to the next step
+4. **BLOCKING and MANDATORY mean hard stops** — do not proceed until that step is complete; confirm completion in a single output line then continue automatically — do NOT ask the user for confirmation
+5. **Never shortcut** — even if the pattern seems obvious from existing tests, follow every step. "Being efficient" by skipping steps is non-compliance, not optimization.
+6. **Never pause for user input** between steps — execute the full sequence autonomously from start to finish.
+
+If you catch yourself about to skip a step, stop and execute it.
+
+---
+
+## DEFINITIONS
+
+**POM-Aware Code Reuse** means refactoring a generated test to use the project's existing Page Object Model (POM) classes and methods, replacing raw inline locators and action sequences with the proper abstractions the customer already has.
+
+This is NOT the same as SkyrampUtils consolidation. Do NOT create a SkyrampUtils file on the POM path.
+
+---
+
+## STEP 1: DETECT POM CLASSES IN THE PROJECT
+
+Use the Glob tool to search for POM files starting from the directory containing \`${testFile}\`:
+- Pattern 1: \`**/pageobjects/**/*.ts\`
+- Pattern 2: \`**/page-objects/**/*.ts\`
+- Pattern 3: \`**/pages/**/*.ts\`
+- Pattern 4: \`**/*.page.ts\`
+- Pattern 5: \`**/*Page.ts\`
+- Pattern 6: \`**/pom/**/*.ts\`
+
+Exclude any file with \`test\`, \`spec\`, \`.test.\`, or \`.spec.\` in its name.
+Also exclude \`node_modules\`.
+
+**Decision:**
+- Zero matches found → **SKIP TO STEP 6 (FALLBACK)**
+- One or more matches found → continue to STEP 2
+
+---
+
+## STEP 2: READ AND CATALOG ALL REUSABLE MODULES
+
+**Step 2a: Check for existing catalog (MANDATORY FIRST STEP)**
+
+Check if \`skyramp-pom-catalog.md\` exists in the same directory as \`tsconfig.json\`:
+- **If it exists:** Read it and verify it starts with \`<!-- skyramp-pom-catalog: auto-generated -->\`
+  - Valid → Output: *"Using existing POM catalog from /path/to/skyramp-pom-catalog.md"* and **skip to STEP 2b**
+  - Invalid → Continue to full catalog generation below
+- **If it doesn't exist:** Continue to full catalog generation below
+
+---
+
+**Step 2 (full catalog generation — only if catalog doesn't exist or is invalid):**
+
+Before writing a single line of refactored code, do the following:
+
+can 1. **Read existing refactored tests** — Find any already-refactored test files in the repository and note their established conventions: how imports are grouped, what comment style sections use, and how \`waitForTimeout\`, \`waitForResponse\`, and dynamic locators are handled. Where existing tests provide a pattern, follow it exactly.
+
+2. **Read tsconfig.json / jsconfig.json** — Capture path alias conventions (e.g., \`@pageobjects/*\`, \`@common-function/*\`). All imports in the refactored test must use these aliases exactly.
+
+3. **Read every POM file found in STEP 1** — For each file, document:
+   - Class name, import path (using tsconfig aliases), and what page/component it represents
+   - Iframe selector used in the constructor (e.g. \`page.frameLocator('iframe#asset-list')\`), or "top-level page" if no iframe
+   - Every property (locator): name and its exact selector string from the constructor assignment
+   - Every method: name, parameters, what action it performs
+   - **For each method, explicitly check and record:**
+     - Any \`waitForTimeout\` or \`sleep\` calls inside the method body and their durations
+     - Any \`waitForResponse\` calls inside the method body and their URL patterns
+     - Whether the method wraps a multi-step sequence using sub-properties or components (e.g. \`searchAssetsByCondition\` internally calls \`searchConditionArea.expandWhenClosed()\`, \`clearBtn.click()\`, \`selectItemName()\`, \`valueKeyword.fill()\`, \`searchBtn.click()\`) — flag these as **wrapping methods**
+   - Flag methods as **timing-aware**, **network-aware**, or **wrapping** as appropriate — all three are high-value substitution targets
+
+4. **Write the POM catalog — MANDATORY** — Write the complete catalog to \`skyramp-pom-catalog.md\` in the same directory as \`tsconfig.json\`. This gives you a clean structured reference for STEP 2b and leaves a record for debugging.
+
+**BLOCKING: Do not proceed to STEP 2b until you have written this file and confirmed the path in a single output line:**
+*"POM catalog written to /path/to/skyramp-pom-catalog.md"*
+
+**Verification gate:** Before continuing to STEP 2b, confirm you either (a) found and used an existing catalog in Step 2a, OR (b) just wrote a new catalog in step 4 above. If neither is true, STOP and complete step 4 now.
+
+Use this exact format for the file:
+
+\`\`\`markdown
+<!-- skyramp-pom-catalog: auto-generated by skyramp_reuse_code -->
+
+## ClassName
+- **Import:** \`@pageobjects/path/to/file\`
+- **Iframe:** \`iframe#selector\` | top-level page
+- **Properties:**
+  - \`propertyName\` — selector: \`exact-selector-string\`
+- **Methods:**
+  - \`methodName(param1, param2)\` — description; ⏱ timing-aware: waitForTimeout(Xms) + sleep(Ys) | 🌐 network-aware: waitForResponse('**/pattern**') | (omit tags if neither)
+\`\`\`
+
+---
+
+## STEP 2b: BUILD AND OUTPUT A MAPPING TABLE
+
+**This step is MANDATORY. Do not write any code until it is complete.**
+
+For every raw locator and action sequence in \`${testFile}\`, find the best POM match and record it in a table. Output the complete table to chat before proceeding to STEP 3.
+
+### Matching criteria
+
+Use **selector-string evidence** as the primary signal — not naming similarity or context guessing:
+
+**PREFERRED** (highest priority — always substitute, even if raw test has explicit waits or correlations for the same sequence):
+- The POM method is **timing-aware** (has internal \`waitForTimeout\`/\`sleep\`) AND its action sequence covers the raw test's steps — the method's internal timing replaces the raw test's explicit waits for that sequence
+- The POM method is **network-aware** (has internal \`waitForResponse\`) AND its URL pattern matches or is equivalent to the raw test's correlation — the method's internal correlation replaces the raw test's explicit \`responsePromise\` block
+- When a PREFERRED method is used: drop the raw test's \`waitForTimeout\` and/or \`responsePromise\` block that fall *inside* the method's covered sequence; add a comment noting the method handles it internally
+
+**HIGH confidence** (substitute in refactored test):
+- The selector string in the raw locator appears verbatim or near-verbatim in the POM property assignment in the constructor. Example: raw test has \`locator('button:has-text("資産登録")')\` and the POM constructor has \`this.iframe.locator('button:has-text("資産登録")')\`
+- A POM method's internal steps clearly and completely cover the entire raw action sequence with no gaps
+- **HIGH via convention:** The existing refactored tests in this repository already use this POM method for the same action pattern — even if the selector strings differ between the raw test and the POM. Convention evidence from the repo's own tests overrides selector mismatch. Example: every refactored test in the repo calls \`mainMenu.assetInformation.select()\` to navigate to the asset list, so a raw test doing the same navigation with different locators should also use it.
+
+**LOW / UNCERTAIN confidence** (leave inline):
+- You can only infer the match from naming or context alone — no selector string overlap AND no convention evidence from existing refactored tests
+- The POM property's selector is different, no existing test uses this method for this action, and you are not sure the elements match
+
+**UNMAPPED** (leave inline):
+- No POM property or method found that covers this locator or action
+
+### Iframe context gate — apply BEFORE assigning any confidence
+
+Before considering any POM match, verify the iframe context matches:
+- Identify the iframe the raw locator uses (e.g., \`frameLocator('iframe#asset-list')\`)
+- Read the POM class constructor to find which iframe it scopes to
+- If the iframe IDs differ → the match is UNMAPPED regardless of selector similarity
+- **Never match a method from a different-iframe class just because it has a similar name.** Example: \`AssetListPage.searchAssetsByCondition()\` uses \`iframe#asset-list\` — it CANNOT be used for actions in \`#application-new-applied\`. For asset search inside a workflow, use \`ApplicationNewAppliedAssetSelectPage.searchAssetsSection.searchByAssetName()\` which uses \`iframe#application-new-applied\`.
+- When filtering POM candidates for a raw action, first narrow to classes whose iframe matches, then look for methods within those classes only.
+
+### Mapping table format
+
+Output the table in this format:
+
+\`\`\`
+| Raw locator / action | POM class | Property / Method | Selector evidence | Confidence |
+|---|---|---|---|---|
+| goto + fill email/password + click login | LoginPage | login(email, password) | method is timing-aware (waitForTimeout+sleep) covering login sequence | PREFERRED |
+| frameLocator('iframe#asset-list').locator('button:has-text("資産登録")') | AssetListPage | assetEntryBtn | iframe.locator('button:has-text("資産登録")') | HIGH |
+| page.locator('input[name="email"]').fill(...) | LoginPage | emailInput | getByPlaceholder('メールアドレス（半角）') | LOW |
+| frameLocator('iframe#wf-input').locator('input[name="changeQty"]') | — | — | No match | UNMAPPED |
+\`\`\`
+
+### Rules after completing the table
+
+- **PREFERRED entries MUST be substituted** — use the POM method and drop the raw test's explicit waits/correlations that fall inside the method's scope
+- **HIGH entries MUST be substituted** — use the POM method or property; do NOT write an inline locator
+- **Always prefer the highest level of abstraction available** — if a wrapping method exists that covers a multi-step sequence, use it instead of calling the individual sub-properties directly. Example: use \`searchAssetsByCondition("資産名", assetName)\` not \`searchConditionArea.expandWhenClosed()\` + \`getConditionRow(1)\` + \`selectItemName()\` etc. Use \`bulkDelete()\` not \`bulkDeleteBtn.click()\` + \`confirmDeleteDialog\` + \`noticeDialog\` inline.
+- **Do NOT upgrade LOW or UNCERTAIN** because the substitution seems reasonable
+- **Conservative default**: an incorrect substitution that breaks the test is worse than leaving something inline — when in doubt, leave it inline
+- If the table has ZERO PREFERRED or HIGH entries → **SKIP TO STEP 6 (FALLBACK)**
+- If AT LEAST ONE PREFERRED or HIGH entry exists → continue to STEP 3
+
+---
+
+## STEP 3: ANALYZE AND APPLY TRANSFORMATION RULES
+
+Read through \`${testFile}\` and apply the following rules:
+
+### 3a. Skyramp Infrastructure — PRESERVE EXACTLY, NO EXCEPTIONS
+
+The following must appear in the refactored test exactly as they are in the original. Never remove, alter, or move them:
+
+\`\`\`typescript
+// Generated by Skyramp ...
+// Command: skyramp generate ui rest \\
+//     ...
+\`\`\`
+
+\`\`\`typescript
+import { test } from '@playwright/test';
+import { newSkyrampPlaywrightPage, expect } from '@skyramp/skyramp';
+
+test.use({
+    viewport: { width: 1450, height: 900 },
+});
+
+// Inside the test body:
+test.setTimeout(1000000);
+page.setDefaultTimeout(pageTimeout);
+const skyrampPage = newSkyrampPlaywrightPage(page, testInfo);
+\`\`\`
+
+> **Note on the page variable:** Assign \`newSkyrampPlaywrightPage\` to \`skyrampPage\`. Pass \`skyrampPage\` to all module constructors and use it for all \`waitForTimeout\`, \`waitForResponse\`, \`locator\`, and \`expect\` calls. If the original test reassigns \`page\` directly, update it to use a separate \`skyrampPage\` variable instead.
+
+### 3b. Test Data — Extract to Named Constants
+
+Extract all hardcoded strings (credentials, tenant names, workflow names, asset names, URLs, etc.) to named \`const\` declarations at the top of the file, before \`test.use\`. Group them under a \`// Test data\` comment.
+
+**Uniqueness:** Any string used as the name of an entity being created, registered, or saved during the test must be made unique per run. First check whether existing refactored tests in the repository already use a convention for this. If a convention exists, follow it exactly. If not, use:
+\`\`\`typescript
+const uniqueSuffix = Date.now();
+const workflowName = "MyWorkflow_" + uniqueSuffix;
+\`\`\`
+
+After making a name dynamic, scan the entire test for any raw locator that hardcodes that same string value and replace only the hardcoded value with the variable.
+
+### 3c. Module Instantiation — Declare All Together at the Top of the Test Body
+
+All module instances must be declared together in a clearly labeled block immediately after \`skyrampPage\` is initialized, before any test actions begin. Match whatever label and comment style the repository's existing tests use. Pass \`skyrampPage\` to every constructor unless the class explicitly requires a different argument (such as a frame handle).
+
+The only exception: a module that genuinely cannot be instantiated until a dynamic value is known at that point in the flow. When this happens, instantiate it inline and add a comment explaining why.
+
+### 3d. Import Organization — Match the Repository's Conventions
+
+Match the import grouping and labeling style of the existing test files exactly:
+- Keep Skyramp imports (\`@playwright/test\` and \`@skyramp/skyramp\`) together and unchanged
+- Group POM imports separately, consistent with the repo's pattern
+- Use whatever path alias convention the repository defines — never introduce a new path style
+
+### 3e. \`waitForTimeout\` Calls
+
+**Always prefer the POM method over preserving a raw wait:**
+If an action sequence maps to a POM method at HIGH or PREFERRED confidence, **always call the method** — even if the raw test has a \`waitForTimeout\` in the middle of that sequence. Drop the raw wait that falls inside the method's covered scope. The customer's POM is the right abstraction; duplicating their code inline just to preserve a trace-recorded wait defeats the purpose of code reuse.
+
+- Call the POM method
+- Drop any \`waitForTimeout\` that falls *inside* the method's covered sequence
+- Add a comment: \`// raw waitForTimeout(Xms) dropped — POM method used instead\`
+
+**How to determine inside vs outside a method's scope:**
+- **Inside scope** = the wait appears between two actions that the POM method covers. Example: a raw test has \`fill(password)\` → \`waitForTimeout(1500)\` → \`click(loginBtn)\`. Since \`loginPage.login()\` covers both the fill and the click, the \`waitForTimeout(1500)\` is inside scope → drop it.
+- **Outside scope** = the wait appears AFTER all actions the POM method covers, as a standalone pause before the next operation. Example: \`await loginPage.login(...)\` → \`waitForTimeout(27000)\`. The login is complete; the 27000ms is waiting for the app to settle after login → this is outside scope → preserve it.
+
+**Preserve waits that fall between POM calls:**
+Any \`waitForTimeout\` that falls *outside* all POM method scopes — i.e. as a standalone wait between two POM calls — must be preserved in exact position, updated to \`await skyrampPage.waitForTimeout(...)\`.
+
+### 3f. \`waitForResponse\` Network Intercepts
+
+**If the action maps to a PREFERRED method (network-aware):**
+- Call the POM method — its internal \`waitForResponse\` handles the correlation
+- Drop the raw test's entire \`const responsePromiseN / await action / const responseN\` block
+- Add a comment: \`// method handles network correlation internally — raw responsePromise dropped\`
+
+**If no POM method is network-aware for this action:**
+- Leave the \`waitForResponse\` block inline as-is. Do NOT create a new POM method.
+
+**Side-effect endpoints — always remove regardless:**
+Remove the \`waitForResponse\` wrapper entirely (keep only the action click) for endpoints that do not correlate to the primary action. These cause flaky timeouts. Patterns to remove:
+- \`**/live/**\` — live chat / messaging (e.g. \`getAFTalkRelations\`)
+- \`**/notification/**\`, \`**/notifications/**\`
+- \`**/analytics/**\`, \`**/tracking/**\`, \`**/telemetry/**\`
+
+\`\`\`typescript
+// Before — remove this
+const responsePromise1 = skyrampPage.waitForResponse("**/live/getAFTalkRelations**");
+await someAction.click();
+const response1 = await responsePromise1;
+
+// After — just the action
+await someAction.click();
+\`\`\`
+
+### 3g. Iframe and Frame Context — Match Constructor Expectations
+
+When a module operates inside an iframe, determine the correct frame handle by reading its constructor. Pass the matching \`contentFrame()\` handle — never pass \`skyrampPage\` when the class expects a frame.
+
+**Never create standalone \`frameLocator()\` references in the test body.** If an action is UNMAPPED and must stay inline, access the frame through the POM's own \`iframe\` property (e.g. \`assetSelectPage.iframe.locator(...)\`, \`inputPage.iframe.getByRole(...)\`). Do not create a separate \`const inputPageFrame = skyrampPage.frameLocator('#application-new-applied')\` — this duplicates the frame reference that already exists in the POM.
+
+### 3h. Dynamic Locators — Prefer Positional Module Methods
+
+Before keeping a dynamic locator inline, check whether a module method exists that targets the same element by position rather than by value. If one exists, use it with the appropriate position (typically \`0\` for the first result) and add a comment noting it replaces the original dynamic locator. If no positional equivalent exists, keep the raw dynamic locator inline as-is.
+
+**Never hardcode dynamic values** (IDs, generated names, timestamps) in locators. Example: \`getByRole("link", { name: "28457681" })\` hardcodes a workflow ID that changes every run — use \`appliedListPage.wfidLinkByIndex(0)\` instead.
+
+### 3i. Checkbox Interactions — Follow Repo Pattern
+
+If the existing POM files have an established pattern for checkbox interactions, follow it. If no such pattern exists, keep the checkbox interaction inline exactly as it appears — do not invent a new abstraction.
+
+### 3j. Screenshot Assertions — Preserve Exact Position
+
+Screenshot assertions (\`toHaveScreenshot\`) must stay in their **exact original position** relative to surrounding actions from the raw test. Note what actions appear immediately before and after the screenshot in the raw test, then place the screenshot at that same relative position in the refactored test. If a POM method would move the screenshot, inline that method's steps around it with a comment: \`// POM method not used — screenshot position must be preserved\`
+
+---
+
+## STEP 4: WRITE THE REFACTORED TEST
+
+Using your catalog from STEP 2 and analysis from STEP 3, produce the refactored test.
+
+**CRITICAL — Consult the mapping table for every single action before writing it:**
+Before writing each line of refactored code, look up that action in your STEP 2b mapping table:
+- If it is marked **PREFERRED** → use the POM method and drop any raw waits/correlations inside its scope. This is the highest-value substitution.
+- If it is marked **HIGH** → you MUST use the POM method or property. Do NOT write an inline locator.
+- If it is marked **LOW / UNCERTAIN / UNMAPPED** → write it inline exactly as in the original test.
+
+Do not skip this lookup for any action. The mapping table is your source of truth — not the raw test's locators.
+
+## STEP 4b: VERIFY AGAINST MAPPING TABLE
+
+Before proceeding to STEP 5, scan your refactored test output and for each HIGH entry in the mapping table confirm the corresponding POM call is present in the output. If any HIGH entry is missing its POM call and was written as inline code instead, go back and fix it before writing the file.
+
+**Section Comments:** Divide the test body into clearly labeled sections corresponding to the logical phases of the user journey. Use the comment style from the repository's existing tests. If none exists, use \`/*----- Section Name -----*/\`.
+
+**Modularization Priority:**
+1. **Existing module method** — always preferred; replaces entire action sequences
+2. **Existing module property** — use directly in \`expect(...)\` or chained calls when no method wraps it
+3. **Inline raw locator** — only when no modular equivalent exists; keep as-is
+
+**Assertions:**
+- Module locator assertions: \`expect(module.someLocator).toBeVisible()\`
+- Screenshot assertions (\`toHaveScreenshot\`): always keep inline; if mid-method sequence, inline that method's steps around it
+- Page readiness checks: use module methods such as \`pageToBeVisible()\` if they exist
+
+**IMPORTANT:** Do NOT create a \`skyrampUtils.ts\` or any SkyrampUtils file on this path. Do NOT call \`skyramp_modularization\` after completing POM-aware code reuse — POM refactoring replaces that step.
+
+---
+
+## STEP 5: WRITE THE OUTPUT
+
+Write the complete, runnable refactored test directly to \`${testFile}\`, overwriting it in place. The file must contain every line — never use placeholder comments like \`// ...continue\` or \`// ...existing code\`. If the test is long, write it in multiple passes until the file is complete. Confirm the file path written to in a single line once done.
+
+Do not output a section breakdown, modularization summary, or any analysis to the chat. Perform all analysis internally.
+
+**Do NOT run the test. Do NOT call any other tools. Your work is complete once the file is written.**
+
+---
+
+## STEP 6: FALLBACK — STANDARD SKYRAMPUTILS PATH
+
+**You should only reach this step if:**
+- No POM files were detected in STEP 1, OR
+- Zero locators/actions in the test mapped to any existing module in STEP 2
+
+Inform the user: *"No POM layer found in this project — falling back to standard SkyrampUtils code reuse."*
+
+Then follow the standard SkyrampUtils process below exactly:
+
+---
+
+# CODE REUSE - 6 CLEAR STEPS
+**CRITICAL WARNING: VIOLATION OF THESE RULES WILL RESULT IN ERROR**
+
+## DEFINITIONS (READ FIRST):
+**What is a "Helper Function"?**
+- A helper function is a STANDALONE, DISTINCT function that is ALREADY DEFINED in the code
+- It has a clear function signature (e.g., \`async function createProduct(page, data) { ... }\`)
+- It is NOT just repetitive inline test code or patterns
+- Example of helper function: \`async function loginUser(page, email, password) { ... }\`
+- Example of NOT a helper function: Repetitive \`await page.click()\` statements scattered in test
+
+**What is "Repetitive Code Pattern"?**
+- Sequential test steps that look similar but are NOT extracted into standalone functions
+- Example: Multiple sequences of \`await page.fill()\`, \`await page.click()\` directly in test body
+- These patterns should NOT be extracted during code reuse - that's what modularization is for
+
+** CODE REUSE ≠ REFACTORING**
+- Code reuse = Finding EXISTING helper functions and reusing them
+- Refactoring = Creating NEW helper functions from patterns (handled by modularization tool)
+
+## STEP 1: READ TEST FILE
+Read ${testFile} and look for ALREADY DEFINED helper functions (not just repetitive patterns).
+
+## STEP 2: FIND EXISTING UTILS
+Use the Grep tool to search for files containing "${SKYRAMP_UTILS_HEADER}":
+- Pattern: "${SKYRAMP_UTILS_HEADER}"
+- Type: "ts"
+- Output mode: "files_with_matches"
+**CRITICAL: Only look for util files with header ${SKYRAMP_UTILS_HEADER}** - exclude test files (files with "test", "spec", ".test.", ".spec." in the name).
+Read the matching non-test files and check if any helpers can be reused in ${testFile}.
+
+## STEP 3: USE EXISTING HELPERS FROM UTILS SOURCE FILES FOUND IN STEP 2
+If helpers exist in util file that can be reused in ${testFile} without modifying them:
+- Import them into ${testFile}
+- Remove any duplicate code in ${testFile}
+- Test that ${testFile} still works without any errors and logical is same as original test file.
+
+## STEP 4: FIND LOCAL HELPERS IN OTHER TEST SOURCE FILES THAT HAS HEADER ${SKYRAMP_UTILS_HEADER}
+Use the Grep tool to search for other test files containing "${SKYRAMP_UTILS_HEADER}":
+- Pattern: "${SKYRAMP_UTILS_HEADER}"
+- Type: "ts"
+- Output mode: "files_with_matches"
+**CRITICAL: Exclude ${testFile} from the results** - only look at OTHER test files, not the current file.
+
+**STOP HERE IF NO OTHER TEST FILES FOUND**
+**IF NO OTHER TEST FILES ARE FOUND, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**
+
+If other test files are found, read those files and look for ALREADY DEFINED helper functions with clear function signatures.
+
+**How to identify helper functions in other test files:**
+ HELPER FUNCTION (move to utils):
+   - Has function signature: \`async function doSomething(params) { ... }\`
+   - Can be called multiple times with different parameters
+   - Example: \`async function fillProductForm(page, product) { ... }\`
+
+NOT A HELPER FUNCTION (do not extract):
+   - Just repetitive inline test code in test body
+   - No function definition/signature
+   - Example: Multiple \`await page.getByTestId("xyz").click()\` directly in test
+
+**IF OTHER TEST FILES ONLY CONTAIN REPETITIVE PATTERNS (NO ACTUAL HELPER FUNCTIONS), SKIP TO STEP 6**
+**IF OTHER TEST FILES ARE ESSENTIALLY IDENTICAL TO CURRENT FILE, SKIP TO STEP 6**
+
+## STEP 5: IF LOCAL HELPERS ARE FOUND IN STEP 4 THAT CAN BE REUSED in ${testFile}, MOVE THOSE LOCAL HELPERS TO UTILS SOURCE FILES AND USE THEM
+
+**ONLY PROCEED WITH STEP 5 IF ALL CONDITIONS ARE MET:**
+- You found OTHER test files in STEP 4 (not just ${testFile})
+- Those test files contain ACTUAL HELPER FUNCTIONS with function signatures (not just repetitive patterns)
+- The helper functions are ALREADY IMPLEMENTED and working in those OTHER test files
+- The helper functions are DIFFERENT from the current file (not just identical patterns)
+
+**IF ANY CONDITION IS NOT MET, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**
+
+**CRITICAL:** For helpers found in STEP 4:
+1. **CREATE** \`${TS_UTILS_FILE}\` file if it doesn't exist with the following header:
+   \`\`\`ts
+   ${generateSkyrampHeader("typescript")}
+   \`\`\`
+**CRITICAL: IF \`${TS_UTILS_FILE}\` is already big, create a new file with a different name and add the header to the new file.**
+2. **COPY** those local helper functions from original test source files to \`${TS_UTILS_FILE}\` without modifying them
+3. **DELETE** those local helper functions from test source files (REMOVE THEM COMPLETELY) WITHOUT ANY OTHER CHANGES.
+4. **IMPORT** those local helper functions from \`${TS_UTILS_FILE}\` back into test source files WITHOUT MAKING ANY OTHER CHANGE.
+5. **IMPORT** those local helper functions from \`${TS_UTILS_FILE}\` into ${testFile}
+6. **REPLACE** duplicate code in ${testFile} with calls to imported helper functions WITHOUT MAKING ANY OTHER CHANGE.
+
+**CRITICAL: DO NOT CREATE UNNECESSARY HELPER FUNCTIONS**
+**DO NOT CREATE HELPERS BASED ON PATTERNS IN THE CURRENT FILE**
+
+## STEP 6: VERIFY AND VALIDATE
+1. **BEFORE** making any changes, read the original test file and identify ALL helper functions
+2. **AFTER** copying helpers to utils, read the original file again to confirm helpers are GONE
+3. **VERIFY** that helper functions are NO LONGER in original test files
+4. **VERIFY** that the original test files only have import statements and no duplicate code
+5. **VERIFY** that both original and new test files import from utils and use the helper functions
+6. **VERIFY** that no unnecessary helper functions were created
+7. **VERIFY** that all helper functions in utils are actually imported and used in the test files
+8. **REMOVE** any helper functions that are not being used after refactoring
+9. **NEVER** refactor, reorganize, or restructure existing source test files beyond moving helpers
+10. **Do NOT run the test** — your work is complete once the file is written
+
+**Do NOT call skyramp_modularization.** Code reuse is complete. The test file has been refactored in place — no further tools should be called.
+
+SUMMARIZE THE CODE REUSE PROCESS AND THE RESULTS.
+`;
+}

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

@@ -2,7 +2,6 @@
  * Modular section builders for the Drift Analysis prompt,
  * mirroring the recommendationSections.ts pattern.
  */
-import { ENHANCE_ASSERTIONS_FOR_INTEGRATION_AND_CONTRACTPROVIDER } from "./enhanceAssertionSection.js";
 export function buildDriftScoringGuide() {
     return `## Drift Score Guide (0–100)
 
@@ -159,9 +158,12 @@ Remove the test file when ALL endpoints it covers were removed from the codebase
 Never use hardcoded resource IDs (e.g. \`order_id=1\`) in any test step, including GET or DELETE steps. Always create required resources via prior POST steps and chain IDs dynamically. Use timestamp-based unique names for created resources (e.g. \`"Product-\${int(time.time())}"\`) to prevent collisions across test runs.
 
 ### Enhance assertions after UPDATE (MANDATORY)
-Apply to **new test functions you are adding** and **existing functions that cover endpoints changed in the diff** only. Do NOT touch existing functions for endpoints unrelated to the diff.
+Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the test file you just updated, \`enhanceType: "maintenance"\`, and the matching \`testType\` based on the file you are editing:
+- **Integration test file** (multi-step chained requests): call with \`testType: "integration"\`
+- **Contract-provider test file** (single endpoint with \`beforeAll\`/\`afterAll\` setup, provider mode): call with \`testType: "contract"\`. Skip for consumer-mode contract tests.
+- **UI test file** (imports \`@playwright/test\`, uses \`page.\` calls): call with \`testType: "ui"\`
 
-${ENHANCE_ASSERTIONS_FOR_INTEGRATION_AND_CONTRACTPROVIDER}`;
+Then apply every instruction returned by the tool to the test file.`;
 }
 export function buildDriftOutputChecklist(existingTestCount, newEndpointCount, inlineMode = false, stateFile) {
     const finalStep = inlineMode

package/build/prompts/test-recommendation/analysisOutputPrompt.js

@@ -93,8 +93,18 @@ ${nextStep}`;
         ? `\n<diff>\n${p.diffContent}\n</diff>`
         : "";
     const step2 = isUIOnly
-        ? `### Step 2: Identify consumed API endpoints
-UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
+        ? `### Step 2: Identify consumed API endpoints and integration status
+UI-only PR — perform two checks:
+1. Read changed frontend files to find API calls (fetch, axios, hooks).
+2. For each changed component file (skip CSS/HTML/style-only files — they have no exported component name to search for): check whether any production source file imports, re-exports, or renders it.
+   - Search for both the component's exported name AND its module path/filename to catch aliased and default imports (e.g. \`import Foo from './CartLine'\`).
+   - Derive the exported name from the file itself: use the default export name, a named exported PascalCase component, or the PascalCase file basename when no clearer name exists.
+   - Exclude test/story files from the search: ignore matches in \`*.test.*\`, \`*.spec.*\`, \`*.stories.*\`, and \`__tests__/\` directories — only production code imports count as integration.
+
+If no production file imports, re-exports, or renders a changed component, mark it as **unintegrated** in the Execution Plan output.
+Exception: if the same PR also adds a route/page file (e.g. under Next.js \`pages/\` or \`app/\`) that imports the component, the route IS the integration point — do NOT mark it as unintegrated.
+Do NOT apply the unintegrated heuristic to route/entrypoint files themselves — those are always reachable by convention.
+An unintegrated non-route component has no DOM node in the running app and cannot be browser-tested — it qualifies as a dead-code / unintegrated-component no-surface PR regardless of how complex the component logic is.`
         : p.diffContent
             ? `### Step 2: Extract new and modified API endpoints from the diff
 Read the \`<diff>\` above and identify every new or modified API endpoint — route registrations, handler methods, controller annotations. Then use the **Router Mounting / Nesting** section above to reconstruct the full URL path for each endpoint by chaining all parent router prefixes down to the handler (e.g. a handler in a file with \`prefix="/reviews"\` that is mounted at \`/{product_id}\` under a router mounted at \`/api/v1/products\` → full path \`/api/v1/products/{product_id}/reviews\`).

package/build/prompts/test-recommendation/recommendationSections.js

@@ -1,3 +1,7 @@
+import { isContractConsumerModeEnabled } from "../../utils/featureFlags.js";
+import { WorkspaceAuthType, getAuthScheme, isAuthorizationHeaderName, AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
+// Cached at module-load — the flag is process-wide and cannot change per call.
+const CONSUMER_MODE_ENABLED = isContractConsumerModeEnabled();
 export const MAX_TESTS_TO_GENERATE = 3;
 export const MAX_RECOMMENDATIONS = 20;
 export const MAX_CRITICAL_TESTS = 3;
@@ -65,19 +69,30 @@ function serializeAuthCallParams(params) {
     }
     return parts.join(", ");
 }
-export function getAuthSnippets(authHeaderValue, authType) {
+/**
+ * Returns the authScheme snippet for a given authHeader + authType combination.
+ *
+ * Delegates scheme resolution to getAuthScheme() in workspaceAuth.ts — the single
+ * source of truth — so this file no longer maintains its own slug→scheme table.
+ */
+export function getAuthSnippets(authHeaderValue, authType, explicitScheme) {
     if (!authHeaderValue) {
         return { authSchemeSnippet: "", authTokenSnippet: "" };
     }
-    if (/^authorization$/i.test(authHeaderValue)) {
-        if (authType && authType !== "none") {
-            // Known auth type from workspace config — embed directly so the LLM doesn't need to guess.
-            const scheme = authType.charAt(0).toUpperCase() + authType.slice(1);
+    // Only Authorization headers carry an authScheme prefix.
+    if (!isAuthorizationHeaderName(authHeaderValue)) {
+        return { authSchemeSnippet: "", authTokenSnippet: "" };
+    }
+    if (authType && authType !== WorkspaceAuthType.None) {
+        // Resolve via the canonical workspaceAuth mapping, passing explicit scheme if set.
+        const wsType = authType;
+        const scheme = getAuthScheme(wsType, explicitScheme);
+        // Use !== undefined so intentionally empty scheme ("" = raw token, no prefix) is preserved.
+        if (scheme !== undefined) {
             return { authSchemeSnippet: `, authScheme: "${scheme}"`, authTokenSnippet: "" };
         }
-        return { authSchemeSnippet: ', authScheme: "<scheme e.g. Bearer, Basic, Token or empty>"', authTokenSnippet: "" };
     }
-    return { authSchemeSnippet: "", authTokenSnippet: "" };
+    return { authSchemeSnippet: ', authScheme: "<scheme e.g. Bearer, Basic, Token or empty>"', authTokenSnippet: "" };
 }
 export const PATH_PARAM_UUID_GUIDANCE = `**Path parameters:** keep the placeholder in \`endpointURL\` (e.g. \`/coupons/{coupon_id}\`). ` +
     `Pass the value via \`pathParams\` (e.g. \`coupon_id=<random-uuid-v4>\`). ` +
@@ -137,10 +152,11 @@ export function buildGenerationRules(isUIOnlyPR) {
 **Available test types:** integration, contract, E2E, UI. **No smoke or fuzz tests.**
 Choose based on what adds the most value for this PR's changes.
 
-**Contract test mode — signal-based selection:**
+${CONSUMER_MODE_ENABLED ? `**Contract test mode — signal-based selection:**
 - **Consumer contract** (\`consumerMode: true\`): Look for outbound HTTP client code (fetch, axios, httpx, requests, http.Client), service client classes, or calls to external base URLs. If an endpoint's implementation makes downstream calls, that downstream boundary is a consumer contract test candidate.
 - **Provider contract** (\`providerMode: true\`): Look for new or modified endpoint handlers, route changes, or response shape modifications. If the diff adds/changes an endpoint this service owns, that is a provider contract test candidate.
-- **Both modes** (\`providerMode: true, consumerMode: true\`) — produces the same output as omitting both flags (generates provider and consumer contract tests). Use when the diff contains BOTH provider signals (new/modified endpoint handlers) AND consumer signals (outbound HTTP client calls to another service).
+- **Both modes** (\`providerMode: true, consumerMode: true\`) — produces the same output as omitting both flags (generates provider and consumer contract tests). Use when the diff contains BOTH provider signals (new/modified endpoint handlers) AND consumer signals (outbound HTTP client calls to another service).` : `**Contract tests — provider-only:**
+Only provider-side contract tests are supported. Recommend a contract test (\`providerMode: true\`) when the diff adds or modifies an endpoint handler, route, or response shape that this service owns.`}
 
 **Scenario fidelity:** Every workflow scenario should reflect the actual resource
 relationships in the code. If the pre-drafted scenarios don't match the real data model,
@@ -152,8 +168,7 @@ Use Playwright browser tools to auto-record traces and generate UI tests.
 When no Playwright trace exists, use the Playwright browser tools (\`browser_navigate\`,
 \`browser_click\`, etc.) to record a trace, then export via \`skyramp_export_zip\` for UI tests.
 `}
-**No duplicate coverage.** If an existing test already covers an endpoint + test type,
-recommend a different test that adds new coverage.`;
+`;
 }
 export function buildVerificationChecklist(topN, maxGen) {
     const minTotal = Math.min(maxGen + 1, topN);
@@ -168,6 +183,7 @@ Before finalizing your output, verify:
 7. **scenarioFile**: \`skyramp_integration_test_generation\` uses the exact \`filePath\` returned by \`skyramp_batch_scenario_test_generation\` — not a guessed or hardcoded filename.
 8. **bugCatchingTarget**: Every GENERATE integration test that targets a business rule, formula, or constraint has a non-empty \`bugCatchingTarget\`.
 9. **FK chaining**: In multi-step integration tests, path params sourced from a prior step's response (e.g. \`order_id\` from step 1) use \`chainsFrom\` — not hardcoded IDs.
+10. **Concrete scenario names**: No GENERATE item uses a placeholder name ending in a numeric suffix (e.g. \`ui-test-for-changed-component-1\`, \`ui-test-from-trace-2\`). Derive the name from the actual changed component or flow: if the diff touches \`LinkCard.tsx\`, the scenario name should be \`link-card-pin-toggle\` or \`link-card-edit-description\`, not \`ui-test-for-changed-component-1\`. The changed file list is available above — use it.
 </verification>`;
 }
 export function buildFewShotExamples() {
@@ -222,29 +238,33 @@ Reasoning: Catches a missing 404 guard on DELETE — verifies the handler return
 </example>
 </examples>`;
 }
-export function buildToolWorkflows(authHeaderValue, authTypeValue = "") {
-    const isAuthorizationHeader = /^authorization$/i.test(authHeaderValue);
+export function buildToolWorkflows(authHeaderValue, authTypeValue = "", explicitScheme) {
+    const isAuthorizationHeader = isAuthorizationHeaderName(authHeaderValue);
     const noAuth = !authHeaderValue;
     let authGuidance;
     let authParams;
     if (noAuth) {
         authGuidance = `**Auth Verification Required:** The workspace config indicates no authentication, but you MUST verify this independently before omitting auth:
 1. **OpenAPI spec** \u2192 check \`securitySchemes\` / \`securityDefinitions\` for \`type: http\`, \`type: apiKey\`, or \`type: oauth2\`
-2. **Source code** \u2192 look for auth middleware (\`passport\`, \`jwt.verify\`, \`authMiddleware\`, \`@requires_auth\`, \`Depends(get_current_user)\`, \`@UseGuards\`), route guards, or token extraction logic
+2. **Source code** \u2192 look for known auth signals (${AUTH_MIDDLEWARE_PATTERNS_STR}).
 3. **Route definitions** \u2192 check if routes have auth decorators or middleware applied
-If you find auth requirements, pass the appropriate \`authHeader\` (e.g., "Authorization") and \`authScheme\` (e.g., "Bearer") to EVERY tool call. Only pass \`authHeader: ""\` if you confirm the API is truly unauthenticated.`;
+4. **Still unknown** \u2192 proceed with \`authHeader: ""\` and note "auth pattern unrecognized" in your recommendation description.
+If you find auth requirements, pass the appropriate \`authHeader\` and \`authScheme\` to EVERY tool call. Only pass \`authHeader: ""\` if you confirm the API is truly unauthenticated.`;
         authParams = { authHeader: "" };
     }
     else if (isAuthorizationHeader) {
+        // Use getAuthScheme (single source of truth) instead of capitalizing the raw slug.
+        // Pass explicitScheme so custom schemes from workspace.yml (e.g. "Ghost", "Hawk") are used.
+        const wsType = authTypeValue;
         const resolvedScheme = (authTypeValue && authTypeValue !== "none")
-            ? authTypeValue.charAt(0).toUpperCase() + authTypeValue.slice(1)
+            ? (getAuthScheme(wsType, explicitScheme) ?? "<scheme e.g. Bearer, Token or empty>")
             : "<scheme e.g. Bearer, Token or empty>";
         authParams = { authHeader: "Authorization", authScheme: resolvedScheme };
         if (authTypeValue) {
             authGuidance = `**Auth Scheme:** The workspace \`api.authType\` is \`"${authTypeValue}"\`.
 **Where to find the scheme** (check in order):
 1. **OpenAPI spec** \u2192 look at \`securitySchemes\` / \`securityDefinitions\` for \`type: http, scheme: bearer\` or \`type: apiKey\`
-2. **Source code** \u2192 auth middleware (\`passport.use\`, \`jwt.verify\`, \`authMiddleware\`), route guards, or header extraction logic (e.g., \`req.headers.authorization.split(" ")[1]\` means Bearer)
+2. **Source code** \u2192 auth middleware signals: ${AUTH_MIDDLEWARE_PATTERNS_STR}
 3. **Workspace config** \u2192 use \`api.authType\` value as the scheme if source is inconclusive
 Pass the prefix as \`authScheme\` (e.g., \`"Bearer"\`, \`"Token"\`, \`"Basic"\`). If the API uses raw tokens with no prefix, pass \`authScheme: ""\`.
 **Do NOT guess the scheme.**
@@ -254,7 +274,7 @@ To skip auth entirely, pass \`authHeader: ""\`.`;
             authGuidance = `**Auth Scheme:** No \`api.authType\` in workspace config.
 **Where to find the scheme** (check in order):
 1. **OpenAPI spec** \u2192 look at \`securitySchemes\` / \`securityDefinitions\` for \`type: http, scheme: bearer\` or \`type: apiKey\`
-2. **Source code** \u2192 auth middleware (\`passport.use\`, \`jwt.verify\`, \`authMiddleware\`), route guards, or header extraction logic (e.g., \`req.headers.authorization.split(" ")[1]\` means Bearer)
+2. **Source code** \u2192 auth middleware signals: ${AUTH_MIDDLEWARE_PATTERNS_STR}
 3. **Fallback** \u2192 use \`"Bearer"\` only if the project clearly uses JWT or OAuth; otherwise pass \`authScheme: ""\`
 Pass the prefix as \`authScheme\` (e.g., \`"Bearer"\`, \`"Token"\`, \`"Basic"\`). If the API uses raw tokens with no prefix, pass \`authScheme: ""\`.
 **Do NOT guess the scheme.**
@@ -321,13 +341,14 @@ If an OpenAPI spec exists, ALSO pass \`apiSchema\` — it enables schema-aware v
 Without a spec, \`endpointURL\` alone is sufficient.
 ${PATH_PARAM_UUID_GUIDANCE}
 
-**Contract test mode selection — set based on this service's role at the boundary:**
+${CONSUMER_MODE_ENABLED ? `**Contract test mode selection — set based on this service's role at the boundary:**
 - \`providerMode: true\` — this service IS the API; validates the implementation matches the spec.
   Use for new or modified endpoints this codebase owns.
 - \`consumerMode: true\` — this service CALLS another API; validates outbound requests conform to the downstream contract.
   Use when the endpoint's implementation makes HTTP calls to external services (look for fetch/axios/httpx/http.Client/service clients).
   A request-aware mock stands in for the real downstream service — no live dependency needed.
-- **Both modes** (\`providerMode: true, consumerMode: true\`) — same output as omitting both flags. Generates both consumer and provider contract tests. Use when the diff contains BOTH provider signals (new/modified endpoint handlers) AND consumer signals (outbound HTTP client calls to another service).
+- **Both modes** (\`providerMode: true, consumerMode: true\`) — same output as omitting both flags. Generates both consumer and provider contract tests. Use when the diff contains BOTH provider signals (new/modified endpoint handlers) AND consumer signals (outbound HTTP client calls to another service).` : `**Contract tests — provider-only:**
+Only provider-side contract tests are supported. Pass \`providerMode: true\` for new or modified endpoints this codebase owns.`}
 
 **For UI tests:**
 1. \`browser_navigate\` to the target URL (from workspace \`api.baseUrl\`)