@skyramp/mcp 0.3.2-rc.pom-3 → 0.3.2

package/build/types/ReuseOutcome.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The POM code-reuse shape carried in a TestbotReport — the wire contract between
+ * this server and the consumers that render it (test-bot.git).
+ *
+ * Lives in types/ rather than beside the derivation logic in
+ * tools/code-refactor/reuse-outcome.ts, and is re-exported from types/index.ts,
+ * so consumers have exactly one definition to import. The enums matter here as
+ * VALUES, not just types: a renderer validating an incoming `verification` or
+ * `declinedBy` needs the actual members to compare against, which a structurally
+ * inherited type cannot provide.
+ *
+ * The internal record that run state keeps between the verify pass and the report
+ * step (`ReuseRecord`) deliberately stays private to the derivation module — it is
+ * not part of this contract and must never reach a report.
+ */
+/** Which gate declined a POM member. */
+export declare enum ReuseDeclinedBy {
+    /** The mapping table never promoted it — no call was ever written. */
+    NotMapped = "not-mapped",
+    /** It was substituted, then verification rejected it and the raw form was
+     *  restored. A `passed` verdict does NOT cover this: it counts only the calls
+     *  that survived. */
+    DemotedByVerify = "demoted-by-verify"
+}
+/** Outcome of the reuse verification loop for a spec. */
+export declare enum ReuseVerificationOutcome {
+    Passed = "passed",
+    Failed = "failed",
+    /** No page-object layer existed to reuse. */
+    SkippedNoPom = "skipped-no-pom"
+}
+/** A POM member the refactor did not reuse. Keyed on the member rather than the
+ *  file: a class is routinely part-reused (a property substituted while a method
+ *  from the same class is demoted), so a file-level list would show that file as
+ *  reused and lose the decline. */
+export interface ReuseSkippedEntry {
+    /** The POM file BASENAME the decline was attributed to — the name the agent
+     *  wrote in its `// kept inline: <file basename> — <reason>` comment, which is
+     *  what the decline is parsed out of. A class name appears only in `member`. */
+    pageObject: string;
+    /** `<binding>.<member>` as the verification report names it. Absent when the
+     *  decline cannot be attributed to one member — a file with several declines
+     *  gives no way to say which is which. */
+    member?: string;
+    declinedBy?: ReuseDeclinedBy;
+    reason: string;
+}
+/**
+ * What lands in a report's `reuse` field, for a UI test whose generation ran POM
+ * code reuse. Every member is optional: consumers must render from whatever
+ * subset is present, and omit the summary entirely when the object is absent (as
+ * it is for non-UI tests, and in reports from versions predating the field).
+ *
+ * `candidatesDetected` counts FILES while the call counts count CALLS — an
+ * indicator, never a fraction. Do not render the pair as a ratio or percentage.
+ */
+export interface ReuseOutcome {
+    candidatesDetected?: number;
+    callsReused?: number;
+    callsVerified?: number;
+    verification?: ReuseVerificationOutcome;
+    skipped?: ReuseSkippedEntry[];
+}

package/build/types/ReuseOutcome.js

@@ -0,0 +1,33 @@
+/**
+ * The POM code-reuse shape carried in a TestbotReport — the wire contract between
+ * this server and the consumers that render it (test-bot.git).
+ *
+ * Lives in types/ rather than beside the derivation logic in
+ * tools/code-refactor/reuse-outcome.ts, and is re-exported from types/index.ts,
+ * so consumers have exactly one definition to import. The enums matter here as
+ * VALUES, not just types: a renderer validating an incoming `verification` or
+ * `declinedBy` needs the actual members to compare against, which a structurally
+ * inherited type cannot provide.
+ *
+ * The internal record that run state keeps between the verify pass and the report
+ * step (`ReuseRecord`) deliberately stays private to the derivation module — it is
+ * not part of this contract and must never reach a report.
+ */
+/** Which gate declined a POM member. */
+export var ReuseDeclinedBy;
+(function (ReuseDeclinedBy) {
+    /** The mapping table never promoted it — no call was ever written. */
+    ReuseDeclinedBy["NotMapped"] = "not-mapped";
+    /** It was substituted, then verification rejected it and the raw form was
+     *  restored. A `passed` verdict does NOT cover this: it counts only the calls
+     *  that survived. */
+    ReuseDeclinedBy["DemotedByVerify"] = "demoted-by-verify";
+})(ReuseDeclinedBy || (ReuseDeclinedBy = {}));
+/** Outcome of the reuse verification loop for a spec. */
+export var ReuseVerificationOutcome;
+(function (ReuseVerificationOutcome) {
+    ReuseVerificationOutcome["Passed"] = "passed";
+    ReuseVerificationOutcome["Failed"] = "failed";
+    /** No page-object layer existed to reuse. */
+    ReuseVerificationOutcome["SkippedNoPom"] = "skipped-no-pom";
+})(ReuseVerificationOutcome || (ReuseVerificationOutcome = {}));

package/build/types/TestExecution.d.ts

@@ -44,6 +44,7 @@ export interface TestExecutionOptions {
     token?: string;
     timeout?: number;
     playwrightSaveStoragePath?: string;
+    dockerNetwork?: string;
     useHostNetwork?: boolean;
 }
 /**

package/build/types/TestTypes.d.ts

@@ -15,10 +15,19 @@ export declare enum TestType {
     INTEGRATION = "integration",
     E2E = "e2e",
     UI = "ui",
-    MOCK = "mock",
     UNIT = "unit",
     UNKNOWN = "unknown"
 }
+/**
+ * Mock is not a test type — mock files are deployed via apply_mock(),
+ * not executed as tests. Kept as a standalone constant for mock generation.
+ */
+export declare const MOCK_TYPE: "mock";
+export declare enum MockProtocol {
+    Rest = "rest",
+    Grpc = "grpc",
+    Kafka = "kafka"
+}
 export declare enum HttpMethod {
     GET = "GET",
     POST = "POST",
@@ -31,7 +40,16 @@ export declare enum HttpMethod {
 export declare enum RuntimeEnvironment {
     LOCAL = "local",
     DOCKER = "docker",
-    KUBERNETES = "kubernetes"
+    KUBERNETES = "k8s"
+}
+export declare const runtimeEnvironmentSchema: z.ZodNativeEnum<typeof RuntimeEnvironment>;
+export declare const runtimeEnvironmentInputSchema: z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>;
+export declare function normalizeRuntimeEnvironment(value: RuntimeEnvironment | "kubernetes"): RuntimeEnvironment;
+export interface TestConfig {
+    testType: TestType;
+    toolName: string;
+    description: string;
+    additionalFields?: Record<string, z.ZodSchema>;
 }
 export declare const languageSchema: z.ZodObject<{
     language: z.ZodNativeEnum<typeof ProgrammingLanguage>;
@@ -45,7 +63,7 @@ export declare const languageSchema: z.ZodObject<{
 }>;
 export declare const baseSchema: z.ZodObject<{
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodNativeEnum<typeof RuntimeEnvironment>>;
+    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -87,7 +105,7 @@ export declare const baseSchema: z.ZodObject<{
     outputDir: string;
     prompt: string;
     deployDashboard?: boolean | undefined;
-    runtime?: RuntimeEnvironment | undefined;
+    runtime?: unknown;
     dockerNetwork?: string | undefined;
     dockerWorkerPort?: number | undefined;
     k8sNamespace?: string | undefined;
@@ -125,7 +143,7 @@ export declare const basePlaywrightSchema: z.ZodObject<{
 }>;
 export declare const baseTraceSchema: z.ZodObject<{
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodNativeEnum<typeof RuntimeEnvironment>>;
+    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;
@@ -174,7 +192,7 @@ export declare const baseTraceSchema: z.ZodObject<{
     prompt: string;
     trace: string;
     deployDashboard?: boolean | undefined;
-    runtime?: RuntimeEnvironment | undefined;
+    runtime?: unknown;
     dockerNetwork?: string | undefined;
     dockerWorkerPort?: number | undefined;
     k8sNamespace?: string | undefined;
@@ -192,7 +210,7 @@ export declare const baseTraceSchema: z.ZodObject<{
 }>;
 export declare const baseTestSchema: {
     deployDashboard: z.ZodDefault<z.ZodBoolean>;
-    runtime: z.ZodDefault<z.ZodNativeEnum<typeof RuntimeEnvironment>>;
+    runtime: z.ZodDefault<z.ZodEffects<z.ZodNativeEnum<typeof RuntimeEnvironment>, RuntimeEnvironment, unknown>>;
     dockerNetwork: z.ZodDefault<z.ZodString>;
     dockerWorkerPort: z.ZodDefault<z.ZodNumber>;
     k8sNamespace: z.ZodDefault<z.ZodString>;

package/build/types/TestTypes.js

@@ -18,10 +18,20 @@ export var TestType;
     TestType["INTEGRATION"] = "integration";
     TestType["E2E"] = "e2e";
     TestType["UI"] = "ui";
-    TestType["MOCK"] = "mock";
     TestType["UNIT"] = "unit";
     TestType["UNKNOWN"] = "unknown";
 })(TestType || (TestType = {}));
+/**
+ * Mock is not a test type — mock files are deployed via apply_mock(),
+ * not executed as tests. Kept as a standalone constant for mock generation.
+ */
+export const MOCK_TYPE = "mock";
+export var MockProtocol;
+(function (MockProtocol) {
+    MockProtocol["Rest"] = "rest";
+    MockProtocol["Grpc"] = "grpc";
+    MockProtocol["Kafka"] = "kafka";
+})(MockProtocol || (MockProtocol = {}));
 export var HttpMethod;
 (function (HttpMethod) {
     HttpMethod["GET"] = "GET";
@@ -36,8 +46,13 @@ export var RuntimeEnvironment;
 (function (RuntimeEnvironment) {
     RuntimeEnvironment["LOCAL"] = "local";
     RuntimeEnvironment["DOCKER"] = "docker";
-    RuntimeEnvironment["KUBERNETES"] = "kubernetes";
+    RuntimeEnvironment["KUBERNETES"] = "k8s";
 })(RuntimeEnvironment || (RuntimeEnvironment = {}));
+export const runtimeEnvironmentSchema = z.nativeEnum(RuntimeEnvironment);
+export const runtimeEnvironmentInputSchema = z.preprocess((value) => (value === "kubernetes" ? RuntimeEnvironment.KUBERNETES : value), runtimeEnvironmentSchema);
+export function normalizeRuntimeEnvironment(value) {
+    return value === "kubernetes" ? RuntimeEnvironment.KUBERNETES : value;
+}
 export const languageSchema = z.object({
     language: z
         .nativeEnum(ProgrammingLanguage)
@@ -53,10 +68,9 @@ export const baseSchema = z.object({
         .boolean()
         .default(false)
         .describe("Whether to deploy the Skyramp dashboard for test monitoring"),
-    runtime: z
-        .nativeEnum(RuntimeEnvironment)
+    runtime: runtimeEnvironmentInputSchema
         .default(RuntimeEnvironment.LOCAL)
-        .describe("Runtime environment (docker, kubernetes, local)"),
+        .describe("Runtime environment (local, docker, or k8s; accepts kubernetes as an alias)"),
     dockerNetwork: z
         .string()
         .default("")
@@ -201,7 +215,9 @@ export const baseTestSchema = {
     queryParams: z
         .string()
         .default("")
-        .describe("MUST be string of comma separated values like 'id=1,name=John' for URL query parameters"),
+        .describe("MUST be string of comma separated values like 'id=1,name=John' for URL query parameters. "
+        + "Workspace-configured api.defaultQueryParams (if set) are merged in automatically — "
+        + "no need to repeat them here. An explicit value for the same key here overrides the workspace default."),
     formParams: z
         .string()
         .default("")

package/build/types/TestbotReport.d.ts

@@ -1,6 +1,7 @@
 import type { DriftAction } from "./TestAnalysis.js";
 import type { TestExecutionStatus } from "./TestExecution.js";
 import type { HttpMethod, TestType } from "./TestTypes.js";
+import type { ReuseOutcome } from "./ReuseOutcome.js";
 /**
  * Shape of the JSON report written by skyramp_submit_report and read by testbot
  * for rendering as Markdown. All fields mirror the corresponding Zod schemas in
@@ -18,6 +19,12 @@ export interface TestbotReport {
         scenarioFile?: string;
         traceFile?: string;
         frontendTrace?: string;
+        /** UI tests only: POM code-reuse outcome, present when skyramp_reuse_code ran
+         *  for this test. Server-derived — imported from its source of truth rather
+         *  than re-declared, since that module already exports a plain interface (the
+         *  rest of this file mirrors Zod schemas by hand, which is why only this field
+         *  is imported). Absent in reports from MCP versions predating it. */
+        reuse?: ReuseOutcome;
     }[];
     /** Omitted when no existing tests were found (agent omits the field). */
     testMaintenance?: {

package/build/types/index.d.ts

@@ -2,3 +2,5 @@ export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
 export type { TestbotReport } from "./TestbotReport.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";
+export type { ReuseOutcome, ReuseSkippedEntry } from "./ReuseOutcome.js";

package/build/types/index.js

@@ -1,3 +1,4 @@
 export { TestExecutionStatus } from "./TestExecution.js";
 export { DriftAction } from "./TestAnalysis.js";
 export { TestType, HttpMethod } from "./TestTypes.js";
+export { ReuseDeclinedBy, ReuseVerificationOutcome } from "./ReuseOutcome.js";

package/build/utils/AnalysisStateManager.d.ts

@@ -1,3 +1,4 @@
+import type { ReuseRecord } from "../tools/code-refactor/reuse-outcome.js";
 import { TestAnalysisResult, MaintenanceActionCore } from "../types/TestAnalysis.js";
 import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
 import { PRTestContext } from "./pr-comment-parser.js";
@@ -9,10 +10,30 @@ import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
 export type { CandidateUiPage } from "./uiPageEnumerator.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
+/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+ *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
+ *  which LOOKS there cannot drift apart. */
+export declare const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
 export declare function setActiveRunStatePath(stateFilePath: string): void;
 export declare function getActiveRunStatePath(): string | undefined;
 /** Reset the run anchor — for tests, and as a safety hook between runs. */
 export declare function clearActiveRunStatePath(): void;
+/**
+ * The run's state-file path, for tools that need to read or amend it without the
+ * agent naming it.
+ *
+ * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
+ * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
+ * path is still deterministic in CI: the StateManager constructor above roots
+ * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
+ * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
+ *
+ * Lives here rather than in each caller so the convention has one home: this is
+ * the module that decides where the file goes, so it is the module that should
+ * decide where to look for it.
+ */
+export declare function resolveRunStatePath(explicitPath?: string): string | undefined;
 export declare function registerSession(sessionId: string, stateFilePath: string): void;
 export declare function getSessionFilePath(sessionId: string): string | undefined;
 export declare function getRegisteredSessions(): ReadonlyMap<string, string>;
@@ -140,6 +161,11 @@ export interface UnifiedAnalysisState {
      * CONFIRMED failures from here instead of guessing. Absent until the tool runs.
      */
     externalTestResults?: ExternalTestRunRecord[];
+    /** POM code-reuse outcome per generated UI spec, keyed by test-file BASENAME
+     *  (what `newTestsCreated[].fileName` carries). Written by skyramp_reuse_code,
+     *  which computes every value in-process; skyramp_submit_report merges it into
+     *  the report's `reuse` field. Never supplied by the LLM. */
+    reuseOutcomes?: Record<string, ReuseRecord>;
 }
 /**
  * State file metadata

package/build/utils/AnalysisStateManager.js

@@ -35,6 +35,10 @@ export function getTestsRepoDir() {
  * Single-repo / standalone calls (no `repository`) never set or read this.
  */
 let _activeRunStatePath;
+/** Filename of the run-scoped analysis state file under `<RUNNER_TEMP>/skyramp/`.
+ *  Single-sourced so the constructor that WRITES there and `resolveRunStatePath`
+ *  which LOOKS there cannot drift apart. */
+export const RUN_STATE_FILE_NAME = "analyze-changes-state.json";
 export function setActiveRunStatePath(stateFilePath) {
     _activeRunStatePath = stateFilePath;
 }
@@ -45,6 +49,32 @@ export function getActiveRunStatePath() {
 export function clearActiveRunStatePath() {
     _activeRunStatePath = undefined;
 }
+/**
+ * The run's state-file path, for tools that need to read or amend it without the
+ * agent naming it.
+ *
+ * `setActiveRunStatePath` is only called by skyramp_analyze_changes on multi-repo
+ * runs (the ones carrying a `repository` param), but a single-repo Testbot run's
+ * path is still deterministic in CI: the StateManager constructor above roots
+ * "analysis" state under `$RUNNER_TEMP/skyramp/`. Falling back to that covers
+ * single-repo runs without a new anchor mechanism. Standalone/IDE usage has no
+ * RUNNER_TEMP and resolves to undefined — correct, since there is no run state.
+ *
+ * Lives here rather than in each caller so the convention has one home: this is
+ * the module that decides where the file goes, so it is the module that should
+ * decide where to look for it.
+ */
+export function resolveRunStatePath(explicitPath) {
+    if (explicitPath)
+        return explicitPath;
+    const anchored = getActiveRunStatePath();
+    if (anchored)
+        return anchored;
+    if (process.env.RUNNER_TEMP) {
+        return path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
+    }
+    return undefined;
+}
 /**
  * In-memory session store: sessionId → { data, storedAt }.
  * Eliminates the need for the LLM to read/write state files on disk.
@@ -149,7 +179,7 @@ export class StateManager {
             // (see getTestbotPrompt TODO). RUNNER_TEMP is GitHub Actions-specific; other CI systems
             // (Jenkins, GitLab, Buildkite) must set it explicitly. Once merged, path flows through
             // summaryOutputFile which is already testbot-controlled and CI-agnostic.
-            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", "analyze-changes-state.json");
+            this.stateFile = path.join(process.env.RUNNER_TEMP, "skyramp", RUN_STATE_FILE_NAME);
         }
         else {
             const baseDir = stateDir || os.tmpdir();

package/build/utils/analyze-openapi.js

@@ -1,5 +1,10 @@
 import { SkyrampClient } from "@skyramp/skyramp";
 import { IsValidKeyValueList } from "./utils.js";
+import { logger } from "./logger.js";
+function isOpenApiRuntimeFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|socket hang up|connection refused|unavailable|timed? out)/i.test(message);
+}
 // Analyze OpenAPI to check for required path params
 export async function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput, uriInput, pathParamsInput) {
     const client = new SkyrampClient();
@@ -7,7 +12,19 @@ export async function analyzeOpenAPIWithGivenEndpoint(apiSchemaInput, uriInput,
         apiSchema: apiSchemaInput,
         uri: uriInput,
     };
-    const pathParamRequired = await client.analyzeOpenapi(analyzeOpenapiOptions);
+    let pathParamRequired;
+    try {
+        pathParamRequired = await client.analyzeOpenapi(analyzeOpenapiOptions);
+    }
+    catch (e) {
+        if (isOpenApiRuntimeFailure(e)) {
+            logger.warning("Skipping OpenAPI path-param validation because schema analysis is unavailable", {
+                error: e instanceof Error ? e.message : String(e),
+            });
+            return null;
+        }
+        throw e;
+    }
     if (IsValidKeyValueList(pathParamRequired)) {
         const requiredPathParams = pathParamRequired
             ? pathParamRequired.split(",").map((p) => p.trim())

package/build/utils/branchDiff.d.ts

@@ -15,4 +15,20 @@ export interface BranchDiffData {
  * Always uses the `b/` form so renames return the new path.
  */
 export declare function parseChangedFilesFromDiff(rawDiff: string): string[];
-export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string): Promise<BranchDiffData>;
+/**
+ * Normalize and validate a caller-provided base branch/ref before passing it
+ * to git. Reject option-like or ambiguous values so the ref is always treated
+ * as a revision name, not as a command-line flag.
+ */
+export declare function normalizeProvidedBaseRef(providedBaseBranch?: string): string | undefined;
+/**
+ * Compute the diff between a base reference and the current state.
+ *
+ * @param repositoryPath  Absolute path to the git repository.
+ * @param providedBaseBranch  A branch name, tag, or commit SHA to diff against.
+ *   When omitted, the remote default branch is auto-detected.
+ * @param includeUncommitted  When true, diffs against the working tree so
+ *   uncommitted/unstaged changes are included. Defaults to false (CI mode
+ *   that only considers committed changes via the three-dot form).
+ */
+export declare function computeBranchDiff(repositoryPath: string, providedBaseBranch?: string, includeUncommitted?: boolean): Promise<BranchDiffData>;

package/build/utils/branchDiff.js

@@ -14,6 +14,9 @@ export function parseChangedFilesFromDiff(rawDiff) {
     return out;
 }
 /** Parse diff headers to find newly created and deleted files. */
+function isShaLikeRef(ref) {
+    return /^[0-9a-f]{7,40}$/i.test(ref);
+}
 function parseNewAndDeletedFiles(rawDiff) {
     const newFiles = [];
     const deletedFiles = [];
@@ -34,24 +37,87 @@ function parseNewAndDeletedFiles(rawDiff) {
     }
     return { newFiles, deletedFiles };
 }
-async function tryDiff(git, ref) {
+/**
+ * Normalize and validate a caller-provided base branch/ref before passing it
+ * to git. Reject option-like or ambiguous values so the ref is always treated
+ * as a revision name, not as a command-line flag.
+ */
+export function normalizeProvidedBaseRef(providedBaseBranch) {
+    if (providedBaseBranch === undefined)
+        return undefined;
+    const trimmed = providedBaseBranch.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("-")) {
+        throw new Error(`Invalid base branch/ref "${providedBaseBranch}": refs must not start with '-'.`);
+    }
+    if (/\s/.test(trimmed) || trimmed.includes("\0")) {
+        throw new Error(`Invalid base branch/ref "${providedBaseBranch}": refs must not contain whitespace or NUL characters.`);
+    }
+    if (trimmed.includes("..")) {
+        throw new Error(`Invalid base branch/ref "${providedBaseBranch}": range syntax (".."/""..."") is not allowed — provide a single ref.`);
+    }
+    return trimmed;
+}
+async function tryDiff(git, ref, includeUncommitted = false) {
     try {
-        const changedFilesRaw = await git.diff([`${ref}...HEAD`, "--name-only"]);
+        // When includeUncommitted is true, diff the ref directly against the
+        // working tree so uncommitted/unstaged local changes are captured.
+        const diffRange = includeUncommitted ? ref : `${ref}...HEAD`;
+        const changedFilesRaw = await git.diff([diffRange, "--name-only"]);
         const changedFiles = changedFilesRaw
             .split("\n")
             .map((f) => f.trim())
             .filter((f) => f.length > 0);
-        const diffStat = await git.diff([`${ref}...HEAD`, "--stat"]);
-        const fullDiff = await git.diff([`${ref}...HEAD`]);
+        const diffStat = await git.diff([diffRange, "--stat"]);
+        const fullDiff = await git.diff([diffRange]);
         const { newFiles, deletedFiles } = parseNewAndDeletedFiles(fullDiff);
-        return { changedFiles, diffContent: fullDiff, diffStat, newFiles, deletedFiles };
+        // git diff does not include untracked files. Include them as both changed
+        // and new so endpoint classification treats newly created local files as new.
+        if (includeUncommitted) {
+            const statusResult = await git.status();
+            const untrackedFiles = statusResult.not_added ?? [];
+            if (untrackedFiles.length > 0) {
+                const changedSet = new Set(changedFiles);
+                const newSet = new Set(newFiles);
+                for (const file of untrackedFiles) {
+                    if (!changedSet.has(file)) {
+                        changedFiles.push(file);
+                        changedSet.add(file);
+                    }
+                    if (!newSet.has(file)) {
+                        newFiles.push(file);
+                        newSet.add(file);
+                    }
+                }
+            }
+        }
+        return {
+            changedFiles,
+            diffContent: fullDiff,
+            diffStat,
+            newFiles,
+            deletedFiles,
+        };
     }
     catch (err) {
-        logger.debug(`tryDiff against ${ref} failed`, { error: err instanceof Error ? err.message : String(err) });
+        logger.debug(`tryDiff against ${ref} failed`, {
+            error: err instanceof Error ? err.message : String(err),
+        });
         return undefined;
     }
 }
-export async function computeBranchDiff(repositoryPath, providedBaseBranch) {
+/**
+ * Compute the diff between a base reference and the current state.
+ *
+ * @param repositoryPath  Absolute path to the git repository.
+ * @param providedBaseBranch  A branch name, tag, or commit SHA to diff against.
+ *   When omitted, the remote default branch is auto-detected.
+ * @param includeUncommitted  When true, diffs against the working tree so
+ *   uncommitted/unstaged changes are included. Defaults to false (CI mode
+ *   that only considers committed changes via the three-dot form).
+ */
+export async function computeBranchDiff(repositoryPath, providedBaseBranch, includeUncommitted = false) {
     const git = simpleGit(repositoryPath);
     const isRepo = await git.checkIsRepo();
     if (!isRepo) {
@@ -60,14 +126,32 @@ export async function computeBranchDiff(repositoryPath, providedBaseBranch) {
     const branchInfo = await git.branch();
     const currentBranch = branchInfo.current || "HEAD";
     // Build candidate base refs in priority order:
-    // 1. Provided branch name (most specific)
-    // 2. Remote default branch auto-detected from available remotes
-    // 3. FETCH_HEAD — present in base_commit repos (git fetch --depth 1 origin <sha>)
+    // 1. Provided value used directly (supports SHAs, local branches, tags)
+    // 2. Provided value with origin/ prefix (remote branch)
+    // 3. Remote default branch auto-detected from available remotes
+    // 4. FETCH_HEAD — present in base_commit repos (git fetch --depth 1 origin <sha>)
     //    where no remote tracking branch is created
-    // 4. HEAD~1 — last resort for repos with no remote at all
+    // 5. HEAD~1 — last resort for repos with no remote at all
     const candidates = [];
-    if (providedBaseBranch) {
-        candidates.push(`origin/${providedBaseBranch}`);
+    const normalizedBaseBranch = normalizeProvidedBaseRef(providedBaseBranch);
+    if (normalizedBaseBranch) {
+        const isRemoteQualified = normalizedBaseBranch.startsWith("origin/");
+        const looksLikeSimpleBranch = !isRemoteQualified &&
+            !isShaLikeRef(normalizedBaseBranch) &&
+            !/[~^:@]/.test(normalizedBaseBranch);
+        if (includeUncommitted && looksLikeSimpleBranch) {
+            // Local-dev diffs should prefer the remote base branch when available;
+            // a developer's local main may be ahead of origin/main.
+            candidates.push(`origin/${normalizedBaseBranch}`);
+            candidates.push(normalizedBaseBranch);
+        }
+        else {
+            // Try the raw value first — handles commit SHAs, tags, and explicit local refs.
+            candidates.push(normalizedBaseBranch);
+            if (!isRemoteQualified) {
+                candidates.push(`origin/${normalizedBaseBranch}`);
+            }
+        }
     }
     // Auto-detect remote default branch
     try {
@@ -89,12 +173,13 @@ export async function computeBranchDiff(repositoryPath, providedBaseBranch) {
     // Final fallback
     candidates.push("HEAD~1");
     for (const ref of candidates) {
-        const result = await tryDiff(git, ref);
+        const result = await tryDiff(git, ref, includeUncommitted);
         if (result) {
             logger.info("Branch diff computed", {
                 currentBranch,
                 baseBranch: ref,
                 changedFiles: result.changedFiles.length,
+                includeUncommitted,
             });
             return { currentBranch, baseBranch: ref, ...result };
         }

package/build/utils/featureFlags.d.ts

@@ -35,3 +35,34 @@ export declare function isContractConsumerModeEnabled(): boolean;
  * (SKYRAMP_FEATURE_TESTBOT=1).
  */
 export declare function isTestbotEnabled(): boolean;
+/**
+ * Returns true when the local-dev workflow is enabled
+ * (SKYRAMP_FEATURE_LOCAL_DEV=1).
+ *
+ * The local-dev workflow registers the `skyramp_local_dev` prompt and
+ * one-click routing, which diffs from a base commit against the current
+ * working state, generates mock configurations and backend tests, executes
+ * them locally, and reports results — without requiring a pull request or
+ * CI environment.
+ */
+export declare function isLocalDevEnabled(): boolean;
+/**
+ * Returns true when general one-click workflows are enabled
+ * (SKYRAMP_FEATURE_ONE_CLICK=1).
+ */
+export declare function isOneClickEnabled(): boolean;
+/**
+ * Gates the POM-aware path of `skyramp_reuse_code`
+ * (SKYRAMP_FEATURE_POM_REUSE=1).
+ *
+ * When OFF (default), TypeScript/JavaScript + Playwright targets are treated
+ * like every other target: `skyramp_reuse_code` returns the SkyrampUtils
+ * consolidation prompt, and none of the POM machinery runs — no deterministic
+ * POM pre-scoping, no POM catalog / mapping-table workflow, no `verify: true`
+ * compliance gates, and consequently no `reuse` summary on the report (nothing
+ * records an outcome to re-derive).
+ *
+ * When ON, the test is refactored against the repo's existing page objects and
+ * the verification gates apply.
+ */
+export declare function isPomReuseEnabled(): boolean;