@skyramp/mcp 0.2.8 → 0.2.150-rc.ldw

package/build/tools/workspace/initializeWorkspaceTool.test.js

@@ -36,7 +36,9 @@ describe("initializeWorkspaceTool", () => {
         // Build a mock WorkspaceConfigManager
         mockManager = {
             exists: jest.fn().mockResolvedValue(false),
-            getConfigPath: jest.fn().mockReturnValue(path.join(tmpDir, ".skyramp/workspace.yml")),
+            getConfigPath: jest
+                .fn()
+                .mockReturnValue(path.join(tmpDir, ".skyramp/workspace.yml")),
             initialize: jest.fn().mockResolvedValue({ workspace: {}, services: [] }),
             updateMetadata: jest.fn().mockImplementation(async (data) => ({
                 workspace: {},
@@ -95,7 +97,6 @@ describe("initializeWorkspaceTool", () => {
         expect(result.content[0].text).toContain("Workspace initialized");
         expect(mockManager.initialize).toHaveBeenCalled();
         expect(mockManager.updateMetadata).toHaveBeenCalledWith(expect.objectContaining({
-            mcpVersion: expect.any(String),
             executorVersion: expect.any(String),
         }));
     });
@@ -103,7 +104,9 @@ describe("initializeWorkspaceTool", () => {
         mockManager.exists.mockResolvedValue(true);
         const result = await handler({
             workspacePath: tmpDir,
-            services: [{ serviceName: "svc", language: "python", testDirectory: "tests" }],
+            services: [
+                { serviceName: "svc", language: "python", testDirectory: "tests" },
+            ],
             scanToken: "valid-token",
             force: false,
         });
@@ -114,7 +117,9 @@ describe("initializeWorkspaceTool", () => {
         validateAndConsumeScanToken.mockReturnValue(false);
         const result = await handler({
             workspacePath: tmpDir,
-            services: [{ serviceName: "svc", language: "python", testDirectory: "tests" }],
+            services: [
+                { serviceName: "svc", language: "python", testDirectory: "tests" },
+            ],
             scanToken: "bad-token",
             force: false,
         });

package/build/types/OneClickCommands.d.ts

@@ -4,7 +4,7 @@
  * and executed by the coding assistant following the workflow instructions.
  */
 /** Unique identifier for a one-click command */
-export type OneClickCommandId = "test_given_endpoint_comprehensively" | "full_repo_scan_recommend_generate_and_execute_top_n_tests";
+export type OneClickCommandId = "test_given_endpoint_comprehensively" | "full_repo_scan_recommend_generate_and_execute_top_n_tests" | "local_dev_test_changes";
 /** Metadata for intent recognition by coding assistants */
 export interface CommandIntentMetadata {
     /** Context indicators describing when to use and when NOT to use this workflow */

package/build/types/RepositoryAnalysis.d.ts

@@ -145,6 +145,22 @@ export interface BranchDiffContext {
     affectedServices: string[];
     summary?: string;
 }
+export interface RouteDiscoveryInfo {
+    /** Files the LLM should inspect to infer endpoint methods and paths from source. */
+    candidateFiles: string[];
+    /** Static scanner output. Best-effort hints only, not an authoritative catalog. */
+    staticHints: Array<{
+        path: string;
+        methods: string[];
+        sourceFile: string;
+    }>;
+    /** OpenAPI paths from workspace config. Authoritative when specFetchSucceeded is true. */
+    openApiPaths: string[];
+    /** Router/module entry points that help the LLM reconstruct full mounted paths. */
+    routerMountContext: string[];
+    /** Full diff file path when available; read this to ground endpoint extraction in changed code. */
+    diffFilePath?: string;
+}
 export interface RepositoryAnalysis {
     metadata: AnalysisMetadata;
     projectClassification: ProjectClassification;
@@ -155,6 +171,7 @@ export interface RepositoryAnalysis {
     authentication: AuthenticationInfo;
     infrastructure: InfrastructureInfo;
     existingTests: ExistingTestInfo;
+    routeDiscovery?: RouteDiscoveryInfo;
     branchDiffContext?: BranchDiffContext;
 }
 export interface AnalysisMetadata {
@@ -1423,6 +1440,45 @@ export declare const branchDiffContextSchema: z.ZodObject<{
     }[] | undefined;
     summary?: string | undefined;
 }>;
+export declare const routeDiscoveryInfoSchema: z.ZodObject<{
+    candidateFiles: z.ZodArray<z.ZodString, "many">;
+    staticHints: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        methods: z.ZodArray<z.ZodString, "many">;
+        sourceFile: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }, {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }>, "many">;
+    openApiPaths: z.ZodArray<z.ZodString, "many">;
+    routerMountContext: z.ZodArray<z.ZodString, "many">;
+    diffFilePath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    candidateFiles: string[];
+    staticHints: {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }[];
+    openApiPaths: string[];
+    routerMountContext: string[];
+    diffFilePath?: string | undefined;
+}, {
+    candidateFiles: string[];
+    staticHints: {
+        path: string;
+        sourceFile: string;
+        methods: string[];
+    }[];
+    openApiPaths: string[];
+    routerMountContext: string[];
+    diffFilePath?: string | undefined;
+}>;
 export declare const analysisMetadataSchema: z.ZodObject<{
     repositoryName: z.ZodString;
     analysisDate: z.ZodString;
@@ -2440,6 +2496,45 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         estimatedCoverage?: number | undefined;
         relevantExternalTestPaths?: string[] | undefined;
     }>;
+    routeDiscovery: z.ZodOptional<z.ZodObject<{
+        candidateFiles: z.ZodArray<z.ZodString, "many">;
+        staticHints: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            methods: z.ZodArray<z.ZodString, "many">;
+            sourceFile: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }, {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }>, "many">;
+        openApiPaths: z.ZodArray<z.ZodString, "many">;
+        routerMountContext: z.ZodArray<z.ZodString, "many">;
+        diffFilePath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    }, {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    }>>;
     branchDiffContext: z.ZodOptional<z.ZodObject<{
         currentBranch: z.ZodString;
         baseBranch: z.ZodString;
@@ -2768,6 +2863,17 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         estimatedCoverage?: number | undefined;
         relevantExternalTestPaths?: string[] | undefined;
     };
+    routeDiscovery?: {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    } | undefined;
     branchDiffContext?: {
         currentBranch: string;
         baseBranch: string;
@@ -2970,6 +3076,17 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
         estimatedCoverage?: number | undefined;
         relevantExternalTestPaths?: string[] | undefined;
     };
+    routeDiscovery?: {
+        candidateFiles: string[];
+        staticHints: {
+            path: string;
+            sourceFile: string;
+            methods: string[];
+        }[];
+        openApiPaths: string[];
+        routerMountContext: string[];
+        diffFilePath?: string | undefined;
+    } | undefined;
     branchDiffContext?: {
         currentBranch: string;
         baseBranch: string;

package/build/types/RepositoryAnalysis.js

@@ -128,17 +128,30 @@ export const branchDiffContextSchema = z.object({
             changeType: z.enum(["added", "modified", "removed"]),
         })),
     })),
-    removedEndpoints: z.array(z.object({
+    removedEndpoints: z
+        .array(z.object({
         path: z.string(),
         methods: z.array(z.object({
             method: z.string(),
             sourceFile: z.string(),
             changeType: z.literal("removed"),
         })),
-    })).optional(),
+    }))
+        .optional(),
     affectedServices: z.array(z.string()),
     summary: z.string().optional(),
 });
+export const routeDiscoveryInfoSchema = z.object({
+    candidateFiles: z.array(z.string()),
+    staticHints: z.array(z.object({
+        path: z.string(),
+        methods: z.array(z.string()),
+        sourceFile: z.string(),
+    })),
+    openApiPaths: z.array(z.string()),
+    routerMountContext: z.array(z.string()),
+    diffFilePath: z.string().optional(),
+});
 export const analysisMetadataSchema = z.object({
     repositoryName: z.string(),
     analysisDate: z.string(),
@@ -239,5 +252,6 @@ export const repositoryAnalysisSchema = z.object({
         estimatedCoverage: z.number().optional(),
         relevantExternalTestPaths: z.array(z.string()).optional(),
     }),
+    routeDiscovery: routeDiscoveryInfoSchema.optional(),
     branchDiffContext: branchDiffContextSchema.optional(),
 });

package/build/types/TestExecution.d.ts

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

package/build/types/TestTypes.d.ts

@@ -14,8 +14,17 @@ export declare enum TestType {
     LOAD = "load",
     INTEGRATION = "integration",
     E2E = "e2e",
-    UI = "ui",
-    MOCK = "mock"
+    UI = "ui"
+}
+/**
+ * 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",
@@ -29,8 +38,11 @@ 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;
@@ -49,7 +61,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>;
@@ -91,7 +103,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;
@@ -129,7 +141,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>;
@@ -178,7 +190,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;
@@ -196,7 +208,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

@@ -17,8 +17,18 @@ export var TestType;
     TestType["INTEGRATION"] = "integration";
     TestType["E2E"] = "e2e";
     TestType["UI"] = "ui";
-    TestType["MOCK"] = "mock";
 })(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";
@@ -33,8 +43,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)
@@ -49,10 +64,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("")

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/analyze-openapi.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/utils/analyze-openapi.test.js

@@ -0,0 +1,19 @@
+import { jest, describe, it, expect, beforeEach } from "@jest/globals";
+const analyzeOpenapi = jest.fn();
+jest.unstable_mockModule("@skyramp/skyramp", () => ({
+    SkyrampClient: jest.fn(() => ({ analyzeOpenapi })),
+}));
+const { analyzeOpenAPIWithGivenEndpoint } = await import("./analyze-openapi.js");
+describe("analyzeOpenAPIWithGivenEndpoint", () => {
+    beforeEach(() => {
+        analyzeOpenapi.mockReset();
+    });
+    it("skips path-param validation for runtime connectivity failures", async () => {
+        analyzeOpenapi.mockRejectedValue(new Error("gRPC unavailable: connection refused"));
+        await expect(analyzeOpenAPIWithGivenEndpoint("schema.yaml", "/users/{id}", "")).resolves.toBeNull();
+    });
+    it("rethrows schema errors instead of silently disabling validation", async () => {
+        analyzeOpenapi.mockRejectedValue(new Error("invalid apiSchema path: missing.yaml"));
+        await expect(analyzeOpenAPIWithGivenEndpoint("missing.yaml", "/users/{id}", "")).rejects.toThrow("invalid apiSchema path");
+    });
+});

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,84 @@ 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.`);
+    }
+    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 +123,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 +170,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/branchDiff.test.d.ts

@@ -0,0 +1 @@
+export {};