@skyramp/mcp 0.2.9 → 0.2.10-rc.1

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -23,11 +23,12 @@ const initializeWorkspaceSchema = z.object({
         .describe("Array of services discovered by skyramp_init_scan. Must contain at least one service."),
     scanToken: z
         .string()
-        .describe("Token returned by skyramp_init_scan. Required to confirm the repo was scanned before initializing."),
+        .optional()
+        .describe("Token returned by skyramp_init_scan. Required on a fresh init (no existing .skyramp/workspace.yml) to confirm the repo was scanned before initializing. Omit when editing an existing workspace.yml — pair `force: true` with the full updated `services` array instead."),
     force: z
         .boolean()
         .default(false)
-        .describe("Set to true to overwrite an existing workspace file. Use when the user explicitly requests it, or when recovering from a workspace validation failure (schema mismatch, unknown fields). Default is false."),
+        .describe("Set to true to overwrite an existing workspace.yml. Use for edits (e.g. updating `runtimeDetails.serverStartCommand` after generating SUT files): pass the full updated `services` array — this is an overwrite, not a merge, so any field not present is dropped. Also use when recovering from a validation failure. Required when `scanToken` is omitted. Default is false."),
     merge: z
         .boolean()
         .default(false)
@@ -49,8 +50,11 @@ async function writeWorkspaceConfig(manager, config) {
 }
 export function registerInitializeWorkspaceTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: "PREREQUISITE: Call skyramp_init_scan first to get a scanToken and discover services. " +
-            "Then call this tool to write .skyramp/workspace.yml with the discovered services and scanToken.",
+        description: "Write or update .skyramp/workspace.yml. Always use this tool for any change to that file — do NOT use Edit/Write directly. " +
+            "1. Fresh init: PREREQUISITE: Call skyramp_init_scan first to get a scanToken and discover services. " +
+            "Then call this tool to write .skyramp/workspace.yml with the discovered services and scanToken. " +
+            "2. Edit existing workspace.yml: omit scanToken, set force: true, and pass the FULL updated services array (overwrite, not merge — fields not in the array are dropped). " +
+            "The services schema is strict: any field not in the schema (e.g. inventing `serverStopCommand` on `runtimeDetails`) fails validation and the call is rejected.",
         inputSchema: initializeWorkspaceSchema.shape,
         _meta: {
             keywords: [
@@ -88,17 +92,33 @@ export function registerInitializeWorkspaceTool(server) {
                     isError: false,
                 };
             }
-            // Validate scan token
-            if (!validateAndConsumeScanToken(params.scanToken)) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "Invalid or expired scanToken. Call skyramp_init_scan first to get a valid scanToken and scanning instructions.",
-                        },
-                    ],
-                    isError: true,
-                };
+            // scanToken is required for fresh init; for edits (force:true on an
+            // existing workspace.yml) the caller supplies the full services array
+            // directly and we skip the token check.
+            const isEdit = alreadyExists && params.force;
+            if (!isEdit) {
+                if (!params.scanToken) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "scanToken is required for a fresh init. Call skyramp_init_scan first to get a scanToken and scanning instructions. To edit an existing workspace.yml, set force: true and omit scanToken.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (!validateAndConsumeScanToken(params.scanToken)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Invalid or expired scanToken. Call skyramp_init_scan first to get a valid scanToken and scanning instructions.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
             }
             if (!params.services || params.services.length === 0) {
                 return {

package/build/types/FrontendIntegration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Frontend component integration check types — SKYR-3855.
+ *
+ * Produced by `checkFrontendFileIntegration` (src/utils/frontendIntegration.ts)
+ * and surfaced to the agent as `uiContext.frontendFileIntegration` in the
+ * `skyramp_analyze_changes` output and state file.
+ */
+/** String enum so the JSON wire format (state file, tool output) stays unchanged. */
+export declare enum IntegrationReason {
+    /** Framework route/page/entrypoint file — reachable by convention, grep skipped. */
+    RouteOrEntrypoint = "route-or-entrypoint",
+    /** At least one production file imports/references the component's module path. */
+    Imported = "imported",
+    /** No production importer found — the component has no DOM presence in the running app. */
+    NoImporters = "no-importers",
+    /** The check could not run (missing file, scan failure) — reported integrated (fail-open). */
+    ScanError = "scan-error"
+}
+export interface FrontendFileIntegration {
+    file: string;
+    integrated: boolean;
+    /** Production files that import/reference the component, relative to repositoryPath. Capped at 10. */
+    importers: string[];
+    reason: IntegrationReason;
+}

package/build/types/FrontendIntegration.js

@@ -0,0 +1,19 @@
+/**
+ * Frontend component integration check types — SKYR-3855.
+ *
+ * Produced by `checkFrontendFileIntegration` (src/utils/frontendIntegration.ts)
+ * and surfaced to the agent as `uiContext.frontendFileIntegration` in the
+ * `skyramp_analyze_changes` output and state file.
+ */
+/** String enum so the JSON wire format (state file, tool output) stays unchanged. */
+export var IntegrationReason;
+(function (IntegrationReason) {
+    /** Framework route/page/entrypoint file — reachable by convention, grep skipped. */
+    IntegrationReason["RouteOrEntrypoint"] = "route-or-entrypoint";
+    /** At least one production file imports/references the component's module path. */
+    IntegrationReason["Imported"] = "imported";
+    /** No production importer found — the component has no DOM presence in the running app. */
+    IntegrationReason["NoImporters"] = "no-importers";
+    /** The check could not run (missing file, scan failure) — reported integrated (fail-open). */
+    IntegrationReason["ScanError"] = "scan-error";
+})(IntegrationReason || (IntegrationReason = {}));

package/build/types/RepositoryAnalysis.d.ts

@@ -1195,7 +1195,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1232,7 +1232,7 @@ export declare const draftedScenarioSchema: z.ZodObject<{
     description: string;
     priority: "high" | "medium" | "low";
     scenarioName: string;
-    category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
     steps: {
         path: string;
         method: string;
@@ -1644,7 +1644,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1681,7 +1681,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1724,7 +1724,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -1767,7 +1767,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2629,7 +2629,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;
@@ -2831,7 +2831,7 @@ export declare const repositoryAnalysisSchema: z.ZodObject<{
             description: string;
             priority: "high" | "medium" | "low";
             scenarioName: string;
-            category: "breaking_change" | "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+            category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
             steps: {
                 path: string;
                 method: string;

package/build/types/TestAnalysis.d.ts

@@ -1,45 +1,10 @@
 import { TestExecutionResult } from "./TestExecution.js";
+import { TestType } from "./TestTypes.js";
 export declare enum RecommendationPriority {
     High = "high",
     Medium = "medium",
     Low = "low"
 }
-export declare enum IssueSeverity {
-    Low = "low",
-    Medium = "medium",
-    High = "high",
-    Critical = "critical"
-}
-export declare enum DriftChangeType {
-    EndpointAdded = "endpoint_added",
-    EndpointRemoved = "endpoint_removed",
-    EndpointRenamed = "endpoint_renamed",
-    EndpointModified = "endpoint_modified",
-    AuthenticationChanged = "authentication_changed",
-    SchemaChanges = "schema_changes",
-    RouteChanged = "route_changed",
-    RouteAdded = "route_added",
-    RouteRemoved = "route_removed",
-    UiComponentAdded = "ui_component_added",
-    UiComponentRemoved = "ui_component_removed",
-    UiComponentModified = "ui_component_modified",
-    UiComponentRestructured = "ui_component_restructured",
-    DependencyChanged = "dependency_changed",
-    FunctionChanged = "function_changed",
-    ClassChanged = "class_changed",
-    BreakingChange = "breaking_change",
-    CodeChange = "code_change"
-}
-export interface DriftChange {
-    type: DriftChangeType;
-    file: string;
-    description: string;
-    severity: IssueSeverity;
-    details?: string;
-}
-export interface AffectedFiles {
-    files: string[];
-}
 /** Origin of a test file — whether it was generated by Skyramp or is user/third-party maintained. */
 export declare enum TestSource {
     Skyramp = "skyramp",
@@ -59,15 +24,23 @@ export declare enum EstimatedWork {
     Medium = "Medium",
     Large = "Large"
 }
+/** The maintenance-decision fields shared by every stage of the test-maintenance
+ *  pipeline (skyramp_actions' recommendations, the state's maintenanceVerdicts, and
+ *  the report's testMaintenance rows) — one canonical shape instead of each stage
+ *  redeclaring the same five fields under its own name. */
+export interface MaintenanceActionCore {
+    testFilePath: string;
+    action: DriftAction;
+    testType: TestType;
+    endpoint: string;
+    rationale: string;
+}
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
-export interface DriftRecommendation {
-    testFile: string;
+export interface DriftRecommendation extends MaintenanceActionCore {
     /** When selectors are abstracted into a page object, pomFile is the POM path to edit.
-     *  testFile remains the spec (for catalog lookup and report); pomFile is what gets patched. */
+     *  testFilePath remains the spec (for catalog lookup and report); pomFile is what gets patched. */
     pomFile?: string;
-    action: DriftAction;
     priority: RecommendationPriority;
-    rationale: string;
     estimatedWork: EstimatedWork;
     updateInstructions: string;
     renamedEndpoints: Array<{
@@ -83,18 +56,11 @@ export interface DriftRecommendation {
  */
 export interface TestAnalysisResult {
     testFile: string;
-    testType: string;
+    testType: TestType;
     language: string;
     framework: string;
-    apiSchema?: string;
     apiEndpoint?: string;
-    /** Origin of this test. Defaults to TestSource.Skyramp for backwards compatibility
-     *  with existing state files. */
-    source?: TestSource;
-    drift?: {
-        changes: DriftChange[];
-        affectedFiles: AffectedFiles;
-    };
+    source: TestSource;
     executionBefore?: TestExecutionResult;
     executionAfter?: TestExecutionResult;
 }

package/build/types/TestAnalysis.js

@@ -4,34 +4,6 @@ export var RecommendationPriority;
     RecommendationPriority["Medium"] = "medium";
     RecommendationPriority["Low"] = "low";
 })(RecommendationPriority || (RecommendationPriority = {}));
-export var IssueSeverity;
-(function (IssueSeverity) {
-    IssueSeverity["Low"] = "low";
-    IssueSeverity["Medium"] = "medium";
-    IssueSeverity["High"] = "high";
-    IssueSeverity["Critical"] = "critical";
-})(IssueSeverity || (IssueSeverity = {}));
-export var DriftChangeType;
-(function (DriftChangeType) {
-    DriftChangeType["EndpointAdded"] = "endpoint_added";
-    DriftChangeType["EndpointRemoved"] = "endpoint_removed";
-    DriftChangeType["EndpointRenamed"] = "endpoint_renamed";
-    DriftChangeType["EndpointModified"] = "endpoint_modified";
-    DriftChangeType["AuthenticationChanged"] = "authentication_changed";
-    DriftChangeType["SchemaChanges"] = "schema_changes";
-    DriftChangeType["RouteChanged"] = "route_changed";
-    DriftChangeType["RouteAdded"] = "route_added";
-    DriftChangeType["RouteRemoved"] = "route_removed";
-    DriftChangeType["UiComponentAdded"] = "ui_component_added";
-    DriftChangeType["UiComponentRemoved"] = "ui_component_removed";
-    DriftChangeType["UiComponentModified"] = "ui_component_modified";
-    DriftChangeType["UiComponentRestructured"] = "ui_component_restructured";
-    DriftChangeType["DependencyChanged"] = "dependency_changed";
-    DriftChangeType["FunctionChanged"] = "function_changed";
-    DriftChangeType["ClassChanged"] = "class_changed";
-    DriftChangeType["BreakingChange"] = "breaking_change";
-    DriftChangeType["CodeChange"] = "code_change";
-})(DriftChangeType || (DriftChangeType = {}));
 /** Origin of a test file — whether it was generated by Skyramp or is user/third-party maintained. */
 export var TestSource;
 (function (TestSource) {

package/build/types/TestTypes.d.ts

@@ -15,7 +15,9 @@ export declare enum TestType {
     INTEGRATION = "integration",
     E2E = "e2e",
     UI = "ui",
-    MOCK = "mock"
+    MOCK = "mock",
+    UNIT = "unit",
+    UNKNOWN = "unknown"
 }
 export declare enum HttpMethod {
     GET = "GET",

package/build/types/TestTypes.js

@@ -18,6 +18,8 @@ export var TestType;
     TestType["E2E"] = "e2e";
     TestType["UI"] = "ui";
     TestType["MOCK"] = "mock";
+    TestType["UNIT"] = "unit";
+    TestType["UNKNOWN"] = "unknown";
 })(TestType || (TestType = {}));
 export var HttpMethod;
 (function (HttpMethod) {
@@ -80,7 +82,7 @@ export const baseSchema = z.object({
         "Common values: 'Authorization' (Bearer/Basic/Token auth), 'X-Api-Key', 'X-Auth-Token', 'Cookie'. " +
         "Other accepted values: 'X-Access-Token', 'X-OAuth-Token', 'X-Client-ID', 'X-Client-Secret', 'X-Client-Token', " +
         "'X-GitHub-Token', 'X-Firebase-AppCheck', 'Proxy-Authorization', 'Fastly-Key', 'Heroku-Bearer'. " +
-        "Pass empty string to skip auth entirely for unauthenticated endpoints. " +
+        "Pass empty string to document an unauthenticated endpoint in the generated test's assertions. " +
         "This is the header KEY name (e.g., 'X-Api-Key'), NOT the token value."),
     authScheme: z
         .string()

package/build/utils/AnalysisStateManager.d.ts

@@ -1,8 +1,9 @@
-import { TestAnalysisResult } from "../types/TestAnalysis.js";
+import { TestAnalysisResult, MaintenanceActionCore } from "../types/TestAnalysis.js";
 import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.js";
 import { PRTestContext } from "./pr-comment-parser.js";
 import { ParsedDiffEndpoint } from "./routeParsers.js";
 import type { CandidateUiPage } from "./uiPageEnumerator.js";
+import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
 export type { CandidateUiPage } from "./uiPageEnumerator.js";
 export declare function setTestsRepoDir(dir: string | undefined): void;
 export declare function getTestsRepoDir(): string | undefined;
@@ -57,6 +58,12 @@ export interface UiAnalysisContext {
      * Empty when no resolvable frontend baseUrl — agent falls back to prose-driven enumeration.
      */
     candidateUiPages: CandidateUiPage[];
+    /**
+     * Per-file production-importer check (SKYR-3855) — server-computed so the
+     * "is this component actually integrated?" skip decision doesn't rely on
+     * the agent running its own grep mid-task. Same order as changedFrontendFiles.
+     */
+    frontendFileIntegration?: FrontendFileIntegration[];
 }
 /**
  * Unified state data combining test discovery + endpoint scanning
@@ -74,6 +81,11 @@ export interface UnifiedAnalysisState {
      * Absent on backend-only PRs.
      */
     uiContext?: UiAnalysisContext;
+    /** Existing-test fileNames skyramp_actions assessed and decided need no action. */
+    ignoredTestFiles?: string[];
+    /** Maintenance actions applied via skyramp_actions — skyramp_submit_report derives
+     *  testMaintenance from this. */
+    maintenanceVerdicts?: MaintenanceActionCore[];
 }
 /**
  * State file metadata

package/build/utils/docker.test.js

@@ -55,7 +55,7 @@ describe("dockerImageExistsLocally", () => {
     });
 });
 describe("pullDockerImage", () => {
-    const IMAGE = "skyramp/executor:v1.3.30";
+    const IMAGE = "skyramp/executor:v1.3.32";
     beforeEach(() => jest.clearAllMocks());
     describe("on amd64 host", () => {
         const originalArch = process.arch;

package/build/utils/featureFlags.d.ts

@@ -31,7 +31,7 @@
  */
 export declare function isContractConsumerModeEnabled(): boolean;
 /**
- * Returns true when running inside a TestBot environment
+ * Returns true when running inside a Testbot environment
  * (SKYRAMP_FEATURE_TESTBOT=1).
  */
 export declare function isTestbotEnabled(): boolean;

package/build/utils/featureFlags.js

@@ -33,7 +33,7 @@ export function isContractConsumerModeEnabled() {
     return process.env.SKYRAMP_FEATURE_CONTRACT_CONSUMER_MODE === "1";
 }
 /**
- * Returns true when running inside a TestBot environment
+ * Returns true when running inside a Testbot environment
  * (SKYRAMP_FEATURE_TESTBOT=1).
  */
 export function isTestbotEnabled() {

package/build/utils/frontendIntegration.d.ts

@@ -0,0 +1,9 @@
+import { FrontendFileIntegration } from "../types/FrontendIntegration.js";
+export type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
+/**
+ * Checks each changed frontend file for a production importer — the
+ * deterministic version of the grep the testbot prompt used to ask the
+ * agent to run mid-task. See module doc for the signature-based approach
+ * and the fail-open rationale.
+ */
+export declare function checkFrontendFileIntegration(repositoryPath: string, changedFrontendFiles: string[]): FrontendFileIntegration[];