@skyramp/mcp 0.3.6-rc.1 → 0.3.6

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -91,6 +91,7 @@ Create one service entry per deployable unit. You MUST include every backend/API
    - Single service: set testDirectory to tests/skyramp.
    - Multiple services or monorepos: set testDirectory to tests/skyramp/<serviceDirName>, where <serviceDirName> is the service directory name with path separators and whitespace replaced by hyphens.
    Framework config takes precedence. Use the Skyramp deterministic fallback only when no framework-configured test directory is available.
+   NEVER set testDirectory to \`.skyramp\`, to any path inside it, or to \`.\` or the repo root, whatever the framework config or existing test files say. \`.skyramp\` is the executor's own working area: it holds the run videos and executor artefacts. skyramp_init_workspace rejects all of these, and the generation tools refuse to write there.
 </basic_fields>
 
 ### API fields
@@ -160,7 +161,7 @@ Before calling skyramp_init_workspace, confirm all of the following:
 4. Every service has api.baseUrl set to a valid, discoverable URL. Use localhost for local services or the actual deployment URL for cloud or external services. Never fabricate a URL.
 5. Every service with authType apiKey has authHeader explicitly set to the actual custom header name (such as "X-API-Key" or "X-Admin-Key"). If you cannot find the header name in the source code, env vars, or README, do NOT use authType apiKey. Use authType none instead and add a YAML comment explaining auth is unresolved.
 6. framework matches language (python uses pytest or robot, typescript or javascript uses playwright, java uses junit).
-7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services).
+7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services). No service uses \`.skyramp\`, \`.\` or the repo root.
 8. If serverStartCommand is provided, it matches the runtime. If serverStopCommand is provided, runtime is "docker" and the command is a Docker command.
 9. For services in docker-compose.yml: runtime MUST be "docker" and the command MUST be a docker command such as "docker compose up -d --build <service-name>" when the service has a build context. Always include it since it is derivable from the service name.
 10. NEVER use application-level commands (uvicorn, npm, node, python, java, etc.) with runtime "docker".

package/build/services/TestGenerationService.js

@@ -11,6 +11,7 @@ import { TestType } from "../types/TestTypes.js";
 import { logger } from "../utils/logger.js";
 import { normalizeLanguageParams } from "../utils/normalizeParams.js";
 import { stageGeneratedPaths, resolveOutputDir } from "../utils/gitStaging.js";
+import { isInsideExecutorWorkDir, executorWorkDirRefusal, generationTargets, } from "../utils/executorWorkDir.js";
 import { getTestsRepoDir } from "../utils/AnalysisStateManager.js";
 import { recordReuseHandOff } from "../tools/code-refactor/reuse-state.js";
 import { isModularizeFirstTarget } from "../utils/reuseRouting.js";
@@ -73,6 +74,18 @@ export class TestGenerationService {
                 });
                 params.outputDir = resolved;
             }
+            // Every generation tool reaches the filesystem through this method, so one
+            // check here covers them all. Nothing written under `.skyramp` is delivered
+            // as a test — an observed run put 7 specs there because the only absolute
+            // path the prompt gave it was the trace-zip directory. The error names the
+            // field and the replacement so the agent can correct itself in one round trip.
+            const badTarget = generationTargets(params.outputDir, params.output).find(isInsideExecutorWorkDir);
+            if (badTarget) {
+                return {
+                    content: [{ type: "text", text: executorWorkDirRefusal(badTarget) }],
+                    isError: true,
+                };
+            }
             // Log prompt parameter using reusable utility
             logger.info("Generating test", {
                 prompt: params.prompt,

package/build/tools/generate-tests/batchMockGenerationTool.js

@@ -10,6 +10,7 @@ import { getRestMockMethodValidationError, normalizeRestMockMethod, } from "../.
 import { getGrpcMockResponseValidationError } from "../../utils/grpcMockValidation.js";
 import { validateMockCompatibility } from "../../utils/mockCompatibility.js";
 import { buildTrafficConfigOptions, validateTrafficConfig, } from "./generateMockRestTool.js";
+import { isInsideExecutorWorkDir, executorWorkDirRefusal, generationTargets, } from "../../utils/executorWorkDir.js";
 export const BATCH_MOCK_PROTOCOL_EXAMPLES = `
 <example protocol="rest">
 Batch REST item. Required fields: protocol="rest", endpointURL, method unless apiSchema is provided.
@@ -361,6 +362,15 @@ function buildGenerateOptions(spec, shared) {
 }
 export async function executeBatchMockGeneration(params) {
     const { mocks, outputDir } = params;
+    // This tool calls the client directly rather than through
+    // TestGenerationService, so it carries its own working-area check. mkdirSync
+    // below would otherwise create the directory before anything is validated.
+    if (isInsideExecutorWorkDir(outputDir)) {
+        return {
+            content: [{ type: "text", text: executorWorkDirRefusal(outputDir) }],
+            isError: true,
+        };
+    }
     fs.mkdirSync(outputDir, { recursive: true });
     const client = new SkyrampClient();
     const results = [];
@@ -402,6 +412,21 @@ export async function executeBatchMockGeneration(params) {
             continue;
         }
         const resolvedOutputDir = spec.outputDir ?? outputDir;
+        // A per-mock outputDir or output name can point back into the working area
+        // even when the batch-level one does not.
+        const badTarget = generationTargets(resolvedOutputDir, spec.output).find(isInsideExecutorWorkDir);
+        if (badTarget) {
+            results.push({
+                index: i,
+                protocol,
+                endpointURL: spec.endpointURL,
+                method,
+                topic: spec.kafkaTopic,
+                success: false,
+                error: executorWorkDirRefusal(badTarget),
+            });
+            continue;
+        }
         fs.mkdirSync(resolvedOutputDir, { recursive: true });
         // Build options and generate
         const options = buildGenerateOptions(spec, {

package/build/tools/generateEnrichedIntegrationTestTool.js

@@ -7,6 +7,7 @@ import { isAuthorizationHeaderName } from "../utils/workspaceAuth.js";
 import { WORKER_CONTROL_PORT } from "../utils/versions.js";
 import * as fs from "fs";
 import * as path from "path";
+import { isInsideExecutorWorkDir, executorWorkDirRefusal, generationTargets, } from "../utils/executorWorkDir.js";
 const TOOL_NAME = "skyramp_generate_enriched_integration_test";
 const enrichedIntegrationTestSchema = {
     scenarioFile: z
@@ -132,6 +133,15 @@ export async function executeGenerateEnrichedIntegrationTest(params) {
         if (resolvedAuthType !== undefined && isAuthorizationHeaderName(resolvedAuthHeader || "")) {
             resolvedAuthHeader = undefined;
         }
+        // This tool calls the client directly instead of going through
+        // TestGenerationService, so it needs its own copy of the working-area check.
+        const badTarget = generationTargets(outputDir, output).find(isInsideExecutorWorkDir);
+        if (badTarget) {
+            return {
+                content: [{ type: "text", text: executorWorkDirRefusal(badTarget) }],
+                isError: true,
+            };
+        }
         const client = new SkyrampClient();
         const result = await client.generateRestTest({
             traceFilePath: scenarioFile,

package/build/tools/workspace/initializeWorkspaceTool.js

@@ -1,12 +1,68 @@
 import { z } from "zod";
 import { WorkspaceConfigManager, serviceSchema, } from "../../workspace/workspace.js";
 import fs from "fs/promises";
+import fsSync from "fs";
+import path from "path";
 import yaml from "js-yaml";
 import { logger } from "../../utils/logger.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { SKYRAMP_IMAGE_VERSION } from "../../utils/versions.js";
 import { validateAndConsumeScanToken } from "./initScanWorkspaceTool.js";
 import { upsertServicesByRepo } from "./serviceUpsert.js";
+import { isInsideDir } from "../../utils/gitStaging.js";
+import { EXECUTOR_VIDEOS_DIR, EXECUTOR_WORK_DIR, isInsideExecutorWorkDir, } from "../../utils/executorWorkDir.js";
+// Test delivery stages each service's whole testDirectory with
+// `git add -- <testDirectory>`, so a testDirectory that encloses the executor's
+// videos commits every .webm. This tool runs before any test is generated, so it
+// is the only point where the choice can still be redirected.
+/**
+ * First service whose `testDirectory` collides with the executor's working area,
+ * or undefined when none does. Two ways to collide, and both have to be rejected
+ * here: the directory sits inside `.skyramp` (which the generation tools refuse
+ * to write into, so accepting it would deadlock the agent between the two
+ * checks), or it encloses `.skyramp/videos` (`.`, "" or the repo root), which
+ * makes delivery commit every video. Relative paths resolve against
+ * `workspacePath`; an absolute one is matched on its own segments, so another
+ * repo's `.skyramp` is caught too.
+ *
+ * A directory that is itself a git repository root is rejected for the same
+ * reason, whichever repo it belongs to. The enclosure test above is anchored on
+ * the PRIMARY workspace's videos path, so a multi-repo entry naming another
+ * repo's root — `/work/repo-b` while workspacePath is `/work/repo-a` — slips
+ * past it: repo A's videos are not inside repo B. The executor writes
+ * `.skyramp/videos` at a repo root, so being one is the collision.
+ */
+function badTestDirectoryResult(bad) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Service "${bad.serviceName}" sets testDirectory to "${bad.testDirectory}", which collides with ${EXECUTOR_WORK_DIR}, the executor's working area: a directory inside it is never delivered, and one that encloses ${EXECUTOR_VIDEOS_DIR}/ makes delivery commit every execution video. Use a dedicated test path — the service's framework-configured test directory, or tests/skyramp. If this service came from the existing ${EXECUTOR_WORK_DIR}/workspace.yml, re-run with force: true and the full corrected services array.`,
+            },
+        ],
+        isError: true,
+    };
+}
+/** Whether `dir` is the top of a git checkout. `.git` is a directory in a normal
+ *  clone and a file in a worktree, so existence is the test. */
+function isGitRepositoryRoot(dir) {
+    return fsSync.existsSync(path.join(dir, ".git"));
+}
+function findBadTestDirectory(workspacePath, services) {
+    const workspaceVideos = path.resolve(workspacePath, EXECUTOR_VIDEOS_DIR);
+    for (const svc of services) {
+        const dir = svc.testDirectory;
+        if (dir === undefined)
+            continue;
+        const resolved = path.resolve(workspacePath, dir);
+        if (isInsideExecutorWorkDir(resolved) ||
+            isInsideDir(workspaceVideos, resolved) ||
+            isGitRepositoryRoot(resolved)) {
+            return { serviceName: svc.serviceName, testDirectory: dir };
+        }
+    }
+    return undefined;
+}
 function getExecutorVersion() {
     return SKYRAMP_IMAGE_VERSION;
 }
@@ -92,6 +148,40 @@ export function registerInitializeWorkspaceTool(server) {
                     isError: false,
                 };
             }
+            if (!params.services || params.services.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No services provided. Follow the scanning instructions from skyramp_init_scan to discover services, then call this tool again.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Both checks above and below are input-only, so they run before
+            // validateAndConsumeScanToken: that
+            // token is single-use, and a rejection after it would make the corrected
+            // retry this error asks for fail with "Invalid or expired scanToken". It
+            // is also before initialize()/updateMetadata(), which both write
+            // workspace.yml (workspace.ts:431, :460) — a later rejection would leave
+            // an initialized file behind and the retry would then short-circuit as
+            // "already initialized".
+            const badIncoming = findBadTestDirectory(workspacePath, params.services);
+            if (badIncoming)
+                return badTestDirectoryResult(badIncoming);
+            // Merge mode writes the MERGED set, so a bad testDirectory already in the
+            // file would be re-persisted. Checked on the merge, not on the existing
+            // services alone, so replacing a bad entry with a corrected one of the
+            // same identity is still the way out. Reading the file is side-effect
+            // free, so this rejection belongs up here with the other two rather than
+            // after the token is spent.
+            const mergeInto = params.merge && alreadyExists ? await manager.read() : undefined;
+            if (mergeInto) {
+                const badMerged = findBadTestDirectory(workspacePath, upsertServicesByRepo([...(mergeInto.services ?? [])], params.services));
+                if (badMerged)
+                    return badTestDirectoryResult(badMerged);
+            }
             // 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.
@@ -120,33 +210,15 @@ export function registerInitializeWorkspaceTool(server) {
                     };
                 }
             }
-            if (!params.services || params.services.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "No services provided. Follow the scanning instructions from skyramp_init_scan to discover services, then call this tool again.",
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            // Initialize (fresh) or read (merge into existing). Merge mode preserves
-            // the existing primary repo identity + previously-registered services;
-            // initialize() would reset both, dropping other repos' services.
-            let config;
-            if (params.merge && alreadyExists) {
-                config = await manager.read();
-                config = await manager.updateMetadata({
-                    executorVersion: getExecutorVersion(),
-                });
-            }
-            else {
-                config = await manager.initialize();
-                config = await manager.updateMetadata({
-                    executorVersion: getExecutorVersion(),
-                });
-            }
+            // Merge mode skips initialize(): it preserves the existing primary repo
+            // identity + previously-registered services, both of which initialize()
+            // would reset, dropping other repos' services. The file itself was
+            // already read above, for the merged-set check.
+            if (!mergeInto)
+                await manager.initialize();
+            const config = await manager.updateMetadata({
+                executorVersion: getExecutorVersion(),
+            });
             // Batch all service upserts: update in memory, write once (direct YAML
             // write avoids N+1 reads and a mid-loop validation error). Upsert is keyed
             // on the composite (repo, serviceName) — see upsertServicesByRepo — so a

package/build/utils/executorWorkDir.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The executor's own working area inside a repo — run videos, trace zips and
+ * other per-run artefacts. Delivered test files do not belong here: the run
+ * cleans and rewrites it, and `git add -- <testDirectory>` on a directory that
+ * encloses it commits every .webm.
+ */
+export declare const EXECUTOR_WORK_DIR = ".skyramp";
+export declare const EXECUTOR_VIDEOS_DIR = ".skyramp/videos";
+/**
+ * Whether `p` is the executor's working area or sits inside it. Matches on whole
+ * path segments, so a sibling such as `.skyramp-tests` is not a hit, and on the
+ * canonical path, so a symlink pointing into `.skyramp` cannot spell its way past
+ * the check.
+ */
+export declare function isInsideExecutorWorkDir(p: string): boolean;
+/**
+ * Refusal text for a caller that asked for output inside the working area. Names
+ * the field and the replacement so the agent can correct itself without help.
+ */
+export declare function executorWorkDirRefusal(destination: string): string;
+/**
+ * Every path a generation call could write to, given an outputDir and an optional
+ * caller-supplied file name. `output` can carry `../` segments, so outputDir alone
+ * is not enough to judge.
+ *
+ * Two compositions, because the writers disagree on an ABSOLUTE `output`:
+ * `generateEnrichedIntegrationTestTool` joins it (`path.join(outputDir, output)`,
+ * which keeps outputDir as a prefix), while `path.resolve` discards outputDir
+ * entirely. A guard cannot pick one and be right for both, so it judges both and
+ * refuses if either lands in the working area.
+ *
+ * outputDir is always judged on its own as well. An `output` of `../tests/x.py`
+ * resolves clear of the working area while outputDir stays `.skyramp`, and
+ * outputDir is what codegen receives as the directory to work in.
+ */
+export declare function generationTargets(outputDir: string, output?: string): string[];

package/build/utils/executorWorkDir.js

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+/**
+ * The executor's own working area inside a repo — run videos, trace zips and
+ * other per-run artefacts. Delivered test files do not belong here: the run
+ * cleans and rewrites it, and `git add -- <testDirectory>` on a directory that
+ * encloses it commits every .webm.
+ */
+export const EXECUTOR_WORK_DIR = ".skyramp";
+export const EXECUTOR_VIDEOS_DIR = `${EXECUTOR_WORK_DIR}/videos`;
+/**
+ * Canonical form of `p`, where `p` may not exist yet: the deepest ancestor that
+ * DOES exist is resolved through symlinks and the missing remainder is appended
+ * back.
+ *
+ * `utils-verify/locate.ts` (realpath) and `code-refactor/reuse-state.ts` (canon)
+ * both fall back to the lexical path when the target is missing. A generation
+ * outputDir usually IS missing, and the lexical path is what a symlinked parent
+ * hides behind — so neither is usable here.
+ */
+function realpathAllowingMissing(p) {
+    let current = path.resolve(p);
+    const missing = [];
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(current), ...[...missing].reverse());
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(p);
+            missing.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+/**
+ * Whether `p` is the executor's working area or sits inside it. Matches on whole
+ * path segments, so a sibling such as `.skyramp-tests` is not a hit, and on the
+ * canonical path, so a symlink pointing into `.skyramp` cannot spell its way past
+ * the check.
+ */
+export function isInsideExecutorWorkDir(p) {
+    return realpathAllowingMissing(p).split(path.sep).includes(EXECUTOR_WORK_DIR);
+}
+/**
+ * Refusal text for a caller that asked for output inside the working area. Names
+ * the field and the replacement so the agent can correct itself without help.
+ */
+export function executorWorkDirRefusal(destination) {
+    return `Refusing to write into "${destination}": it is inside ${EXECUTOR_WORK_DIR}, the Skyramp executor's working area (run videos and trace zips). Files written there are not delivered as tests. Set outputDir — and any output file name — so the result lands in the testDirectory of the service under test, read from ${EXECUTOR_WORK_DIR}/workspace.yml, or tests/skyramp when that service declares none. If that testDirectory is itself inside ${EXECUTOR_WORK_DIR}, it is wrong: re-run skyramp_init_workspace with a corrected one.`;
+}
+/**
+ * Every path a generation call could write to, given an outputDir and an optional
+ * caller-supplied file name. `output` can carry `../` segments, so outputDir alone
+ * is not enough to judge.
+ *
+ * Two compositions, because the writers disagree on an ABSOLUTE `output`:
+ * `generateEnrichedIntegrationTestTool` joins it (`path.join(outputDir, output)`,
+ * which keeps outputDir as a prefix), while `path.resolve` discards outputDir
+ * entirely. A guard cannot pick one and be right for both, so it judges both and
+ * refuses if either lands in the working area.
+ *
+ * outputDir is always judged on its own as well. An `output` of `../tests/x.py`
+ * resolves clear of the working area while outputDir stays `.skyramp`, and
+ * outputDir is what codegen receives as the directory to work in.
+ */
+export function generationTargets(outputDir, output) {
+    const dir = path.resolve(outputDir);
+    if (!output)
+        return [dir];
+    return [
+        dir,
+        path.resolve(outputDir, output),
+        path.resolve(path.join(outputDir, output)),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.3.6-rc.1",
+  "version": "0.3.6",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",