swallowkit 1.1.2 → 2.0.0-alpha.10

package/src/__tests__/home-page.test.ts

@@ -0,0 +1,50 @@
+import { buildHomePage } from "../core/project/home-page";
+import { adaptReactPage } from "../core/scaffold/react-ui-generator";
+
+describe("shared home page presentation", () => {
+  it.each(["npm", "pnpm"] as const)(
+    "differs only in framework label and routing with %s",
+    (pm) => {
+      const next = buildHomePage("nextjs", pm);
+      const react = buildHomePage("react", pm);
+      const adaptedNext = adaptReactPage(next)
+        .replace("export const dynamic = 'force-dynamic';\n\n", "")
+        .replace("Next.js on Azure", "React on Azure");
+
+      expect(react).toBe(adaptedNext);
+      expect(react).toContain("Welcome to SwallowKit");
+      expect(react).toContain("Your Models");
+      expect(react).toContain("Get Started");
+      expect(react).toContain("Built with SwallowKit");
+      expect(react).toContain(
+        `${pm === "npm" ? "npx" : "pnpm exec"} swallowkit scaffold shared/models/your-model.ts`
+      );
+    }
+  );
+
+  it("keeps Next.js-only directives out of the SPA", () => {
+    const next = buildHomePage("nextjs", "pnpm");
+    const react = buildHomePage("react", "pnpm");
+
+    expect(next).toContain("'use client'");
+    expect(next).toContain("export const dynamic = 'force-dynamic'");
+    expect(next).toContain("href={model.path}");
+    expect(react).not.toMatch(/next\/|use client|force-dynamic/);
+    expect(react).toContain("import { Link } from 'react-router-dom'");
+    expect(react).toContain("to={model.path}");
+  });
+
+  it.each(["nextjs", "react"] as const)(
+    "preserves connection states and same-origin requests for %s",
+    (frontend) => {
+      const source = buildHomePage(frontend, "pnpm");
+      expect(source).toContain("fetch('/api/greet?name=SwallowKit')");
+      expect(source).toContain("disabled={greetingStatus === 'loading'}");
+      expect(source).toContain("setGreetingStatus('success')");
+      expect(source).toContain("setGreetingStatus('error')");
+      expect(source).toContain('role="status"');
+      expect(source).toContain('role="alert"');
+      expect(source).not.toMatch(/BACKEND_FUNCTIONS_|VITE_/);
+    }
+  );
+});

package/src/__tests__/init.test.ts

@@ -16,6 +16,7 @@ import {
   getAzureFunctionsPipeline,
   getGitHubFunctionsWorkflow,
   injectSwallowKitNextConfig,
+  ensureNextTailwindPostcssConfig,
   parseIgnoredBuilds,
   buildCosmosDbFreeTierBicepSource,
   buildFunctionsHostKeyBicepExpression,
@@ -25,6 +26,8 @@ import {
   getStaticWebAppSku,
   withNpmLockfileSafeManifests,
 } from "../cli/commands/init";
+import { generateModelContainerMigration, initializeLegacyMigrations } from "../core/operations/migration-generator";
+import { FileOperationSession } from "../core/operations/file-session";
 
 describe("injectSwallowKitNextConfig", () => {
   it("adds standalone settings without deprecated experimental options", () => {
@@ -40,6 +43,8 @@ export default nextConfig;
     const updated = injectSwallowKitNextConfig(original, "sample-app");
 
     expect(updated).toContain("output: 'standalone'");
+    expect(updated).toContain("cacheComponents: false");
+    expect(updated).not.toContain("partialPrefetching");
     expect(updated).toContain("agentRules: false");
     expect(updated).toContain("transpilePackages: ['@sample-app/shared']");
     expect(updated).toContain("serverExternalPackages: ['applicationinsights', 'diagnostic-channel-publishers']");
@@ -60,6 +65,26 @@ module.exports = nextConfig;
     expect(updated).toContain("transpilePackages: ['@sample-app/shared']");
     expect(updated).toContain("agentRules: false");
     expect(updated).toContain("module.exports = nextConfig;");
+    expect(updated).toContain("cacheComponents: false");
+  });
+
+  it.each([true, false])("disables create-next-app Cache Components without duplicate keys (initially %s)", (enabled) => {
+    const original = `import type { NextConfig } from 'next';
+const nextConfig: NextConfig = {
+  cacheComponents: ${enabled},
+  partialPrefetching: true,
+  reactCompiler: true,
+};
+export default nextConfig;
+`;
+    const updated = injectSwallowKitNextConfig(original, "sample-app");
+    expect(updated).toContain("cacheComponents: false");
+    expect(updated).not.toContain("cacheComponents: true");
+    expect(updated).toContain("partialPrefetching: false");
+    expect(updated.match(/\bpartialPrefetching\s*:/g)).toHaveLength(1);
+    expect(updated.match(/\bcacheComponents\s*:/g)).toHaveLength(1);
+    expect(updated).toContain("reactCompiler: true");
+    expect(updated).toContain("output: 'standalone'");
   });
 
   it("generates a C# Program.cs compatible with the current worker packages", () => {
@@ -87,6 +112,13 @@ module.exports = nextConfig;
     expect(source).toContain('<None Remove="generated\\**\\bin\\**;generated\\**\\obj\\**" />');
   });
 
+  it("uses a current Cosmos SDK with binary query response fixes", () => {
+    const source = buildCSharpFunctionsProjectSource();
+
+    expect(source).toContain('<PackageReference Include="Microsoft.Azure.Cosmos" Version="3.63.2" />');
+    expect(source).not.toContain('Version="3.47.0"');
+  });
+
   it("builds swallowkit.config.js without a local swallowkit package type import", () => {
     const source = buildSwallowKitConfigSource("typescript");
 
@@ -133,9 +165,43 @@ module.exports = nextConfig;
 
     expect(devDependencies).toEqual({
       swallowkit: expect.stringMatching(/.+/),
+      "@tailwindcss/postcss": "^4.0.0",
     });
   });
 
+  it("does not add the Next.js PostCSS plugin to React projects", () => {
+    expect(buildGeneratedProjectDevDependencies("react")).not.toHaveProperty("@tailwindcss/postcss");
+  });
+
+  it("configures Tailwind for webpack even when create-next-app only configured Turbopack", () => {
+    const project = fs.mkdtempSync(path.join(process.cwd(), ".tmp-postcss-"));
+    try {
+      ensureNextTailwindPostcssConfig(project);
+      const config = path.join(project, "postcss.config.mjs");
+      expect(fs.readFileSync(config, "utf8")).toContain('"@tailwindcss/postcss": {}');
+      fs.writeFileSync(config, "export default { plugins: { custom: {} } };");
+      ensureNextTailwindPostcssConfig(project);
+      expect(fs.readFileSync(config, "utf8")).toBe("export default { plugins: { custom: {} } };");
+    } finally {
+      fs.rmSync(project, { recursive: true, force: true });
+    }
+  });
+
+  it.each(["postcss.config.js", "postcss.config.cjs", "postcss.config.json"])(
+    "preserves an existing %s",
+    file => {
+      const project = fs.mkdtempSync(path.join(process.cwd(), ".tmp-postcss-"));
+      try {
+        fs.writeFileSync(path.join(project, file), "{}");
+        ensureNextTailwindPostcssConfig(project);
+        expect(fs.existsSync(path.join(project, "postcss.config.mjs"))).toBe(false);
+        expect(fs.readFileSync(path.join(project, file), "utf8")).toBe("{}");
+      } finally {
+        fs.rmSync(project, { recursive: true, force: true });
+      }
+    }
+  );
+
   it("builds a project-scoped MCP config that resolves the configured swallowkit-mcp version", () => {
     const source = buildSwallowKitMcpProjectConfigSource();
     const parsed = JSON.parse(source) as {
@@ -310,9 +376,81 @@ describe("Infrastructure generation", () => {
       });
     },
   );
+
+  it("derives globally unique Cosmos DB and Function App names from the resource group", async () => {
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-infra-names-"));
+    try {
+      await createInfrastructure(projectDir, "sample-app", {
+        cosmosDbMode: "freetier", vnetOption: "none", swaPlan: "free",
+      }, "typescript");
+      const mainBicep = fs.readFileSync(path.join(projectDir, "infra", "main.bicep"), "utf-8");
+
+      expect(mainBicep).toContain("var resourceSuffix = take(uniqueString(resourceGroup().id, projectName), 6)");
+      expect(mainBicep).toContain("var cosmosAccountName = 'cosmos-${take(toLower(projectName), 30)}-${resourceSuffix}'");
+      expect(mainBicep).toContain("var functionsAppName = 'func-${take(projectName, 40)}-${resourceSuffix}'");
+      expect(mainBicep.match(/accountName: cosmosAccountName/g)).toHaveLength(2);
+      expect(mainBicep).toContain("name: functionsAppName");
+      expect(mainBicep).not.toContain("'cosmos-${projectName}'");
+      expect(mainBicep).not.toContain("'func-${projectName}'");
+      // Azure limits: Cosmos DB account <= 44 chars, Function App <= 60 chars.
+      expect("cosmos-".length + 30 + 1 + 6).toBeLessThanOrEqual(44);
+      expect("func-".length + 40 + 1 + 6).toBeLessThanOrEqual(60);
+
+      const migration = generateModelContainerMigration(
+        { name: "Todo", partitionKey: "/id" },
+        new FileOperationSession("commit", projectDir)
+      );
+      const migrationBicep = fs.readFileSync(path.join(projectDir, migration!.template), "utf-8");
+      expect(migrationBicep).toContain(
+        "name: 'cosmos-${take(toLower(projectName), 30)}-${take(uniqueString(resourceGroup().id, projectName), 6)}'"
+      );
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps the original Cosmos DB account name in model migrations for projects without suffixed names", async () => {
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-infra-legacy-names-"));
+    try {
+      await createInfrastructure(projectDir, "sample-app", {
+        cosmosDbMode: "freetier", vnetOption: "none", swaPlan: "free",
+      }, "typescript");
+      const mainPath = path.join(projectDir, "infra", "main.bicep");
+      const legacyMain = fs.readFileSync(mainPath, "utf-8")
+        .replace(/^var (resourceSuffix|cosmosAccountName|functionsAppName) = .*\r?\n/gm, "")
+        .replace(/accountName: cosmosAccountName/g, "accountName: 'cosmos-${projectName}'")
+        .replace("name: functionsAppName", "name: 'func-${projectName}'");
+      fs.writeFileSync(mainPath, legacyMain);
+      initializeLegacyMigrations(projectDir);
+
+      const migration = generateModelContainerMigration(
+        { name: "Todo", partitionKey: "/id" },
+        new FileOperationSession("commit", projectDir)
+      );
+      const migrationBicep = fs.readFileSync(path.join(projectDir, migration!.template), "utf-8");
+      expect(migrationBicep).toContain("name: 'cosmos-${projectName}'");
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("GitHub Actions workflow generation", () => {
+  it("keeps Python deployment and both CI providers on the same GA runtime", async () => {
+    expect(getGitHubFunctionsWorkflow("npm", "python")).toContain("python-version: '3.14'");
+    expect(getAzureFunctionsPipeline("npm", "python")).toContain("versionSpec: '3.14'");
+    const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-python-infra-"));
+    try {
+      await createInfrastructure(projectDir, "sample-app", {
+        cosmosDbMode: "serverless", vnetOption: "none", swaPlan: "free",
+      }, "python");
+      const source = fs.readFileSync(path.join(projectDir, "infra", "main.bicep"), "utf8");
+      expect(source).toContain("functionsRuntimeVersion: '3.14'");
+    } finally {
+      fs.rmSync(projectDir, { recursive: true, force: true });
+    }
+  });
+
   it("only enables setup-node caching when no package-manager conversion is needed", () => {
     expect(buildGitHubSwaWorkflow("npm")).toContain("Select Node.js 22 for SWA");
     expect(buildGitHubSwaWorkflow("npm")).toContain("app_build_command: 'npm run build'");
@@ -411,11 +549,13 @@ describe("SWA npm compatibility with pnpm projects", () => {
         scripts: { prestart: "pnpm run build" },
       });
       const env = { ...process.env, npm_config_cache: path.join(dir, "cache") };
+      const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+      const npmOptions = { cwd: dir, env, encoding: "utf8" as const, shell: process.platform === "win32" };
       // setup-node's npm cache lookup is an npm command too, before any install.
-      const cacheBefore = spawnSync("npm", ["config", "get", "cache"], { cwd: dir, env, encoding: "utf8" });
+      const cacheBefore = spawnSync(npmCommand, ["config", "get", "cache"], npmOptions);
       expect(cacheBefore.status).not.toBe(0);
       expect(cacheBefore.stderr).toContain("EBADDEVENGINES");
-      const before = spawnSync("npm", ["run", "probe"], { cwd: dir, env, encoding: "utf8" });
+      const before = spawnSync(npmCommand, ["run", "probe"], npmOptions);
       expect(before.status).not.toBe(0);
       expect(before.stderr).toContain("EBADDEVENGINES");
 
@@ -430,7 +570,7 @@ describe("SWA npm compatibility with pnpm projects", () => {
       }
       const runtimeCommand = workflow.match(/node -e "const fs=require\('fs'\);const p=JSON.parse[^\n]+/);
       expect(runtimeCommand).not.toBeNull();
-      execFileSync("bash", ["-c", runtimeCommand![0]], { cwd: dir });
+      execFileSync(process.execPath, ["-e", runtimeCommand![0].slice('node -e "'.length, -1)], { cwd: dir });
       const match = workflow.match(/node <<'NODE'\n([\s\S]*?)\n\s+NODE/);
       expect(match).not.toBeNull();
       execFileSync(process.execPath, ["-e", match![1]], { cwd: dir });
@@ -441,9 +581,9 @@ describe("SWA npm compatibility with pnpm projects", () => {
       expect(normalized.devEngines.runtime.version).toBe(">=22.14.0");
       expect(normalized.workspaces).toEqual(hasFunctions ? ["shared", "functions"] : ["shared"]);
       expect(normalized.dependencies["@sample/shared"]).toBe("file:shared");
-      const cacheAfter = execFileSync("npm", ["config", "get", "cache"], { cwd: dir, env, encoding: "utf8" });
+      const cacheAfter = execFileSync(npmCommand, ["config", "get", "cache"], npmOptions);
       expect(cacheAfter.trim()).toBe(env.npm_config_cache);
-      const after = execFileSync("npm", ["run", "probe"], { cwd: dir, env, encoding: "utf8" });
+      const after = execFileSync(npmCommand, ["run", "probe"], npmOptions);
       expect(after).toContain("npm/");
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });

package/src/__tests__/mcp-version.test.ts

@@ -0,0 +1,262 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { compareSemver, isPrerelease, parseSemver } from "../utils/semver";
+import {
+  MCP_DELEGATED_FROM_ENV,
+  buildPinnedUpdateNotice,
+  decideMcpLaunch,
+  resolveProjectSwallowKit,
+} from "../mcp/version-selection";
+import { readMcpConfigVersion, resolveMcpPinVersion } from "../core/project/mcp-config";
+import { configureMcp } from "../cli/commands/configure-mcp";
+import { buildSwallowKitMcpProjectConfigSource, selectInitialMcpVersion } from "../cli/commands/init";
+import { getSwallowKitVersion } from "../version";
+
+const repositoryRoot = path.resolve(__dirname, "..", "..");
+const builtMcpEntrypoint = path.join(repositoryRoot, "dist", "mcp", "index.js");
+const itWhenBuilt = fs.existsSync(builtMcpEntrypoint) ? it : it.skip;
+
+function createProject(version: string | null, options: { mcpScript?: string } = {}): string {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), "swallowkit-mcp-version-"));
+  fs.writeFileSync(path.join(project, "package.json"), JSON.stringify({ name: "sample", devEngines: { packageManager: { name: "pnpm" } } }));
+  fs.writeFileSync(path.join(project, ".mcp.json"), buildSwallowKitMcpProjectConfigSource("pnpm"));
+  if (version) {
+    const root = path.join(project, "node_modules", "swallowkit");
+    fs.mkdirSync(path.join(root, "dist", "mcp"), { recursive: true });
+    fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({
+      name: "swallowkit",
+      version,
+      bin: { swallowkit: "dist/cli/index.js", "swallowkit-mcp": "dist/mcp/index.js" },
+    }));
+    fs.writeFileSync(path.join(root, "dist", "mcp", "index.js"), options.mcpScript ?? "");
+  }
+  return project;
+}
+
+describe("semantic version precedence", () => {
+  it.each([
+    ["2.0.0-alpha.3", "1.1.2", 1],
+    ["2.0.0-alpha.3", "2.0.0", -1],
+    ["2.0.0", "2.0.0-alpha.3", 1],
+    ["2.0.0-alpha.3", "2.0.0-alpha.3", 0],
+    ["2.0.0-alpha.3", "2.0.0-alpha.10", -1],
+    ["2.0.0-alpha.3", "2.0.0-beta.1", -1],
+    ["2.0.0-beta.1", "2.0.0-rc.1", -1],
+    ["2.0.0-alpha", "2.0.0-alpha.1", -1],
+    ["2.0.0-1", "2.0.0-alpha", -1],
+    ["1.10.0", "1.9.9", 1],
+    ["1.0.0+build.1", "1.0.0", 0],
+  ])("compares %s with %s", (left, right, expected) => {
+    expect(compareSemver(left, right)).toBe(expected);
+    expect(compareSemver(right, left)).toBe(-expected || 0);
+  });
+
+  it("rejects values that are not semantic versions", () => {
+    expect(parseSemver("latest")).toBeNull();
+    expect(parseSemver("1.2")).toBeNull();
+    expect(parseSemver("01.2.3")).toBeNull();
+    expect(compareSemver("latest", "1.0.0")).toBeNull();
+    expect(isPrerelease("2.0.0-alpha.3")).toBe(true);
+    expect(isPrerelease("2.0.0")).toBe(false);
+  });
+});
+
+describe("MCP launch version selection", () => {
+  const selfPackageRoot = path.join(os.tmpdir(), "published-swallowkit");
+  const project = (version: string, entrypoint: string | null = "/project/node_modules/swallowkit/dist/mcp/index.js") => ({
+    version,
+    packageRoot: "/project/node_modules/swallowkit",
+    mcpEntrypoint: entrypoint,
+  });
+
+  it("delegates when the project install is newer than the latest launcher", () => {
+    const decision = decideMcpLaunch({
+      selfVersion: "1.1.2",
+      selfPackageRoot,
+      env: { SWALLOWKIT_MCP_VERSION: "latest" },
+      project: project("2.0.0-alpha.3"),
+    });
+    expect(decision).toEqual({
+      action: "delegate",
+      entrypoint: "/project/node_modules/swallowkit/dist/mcp/index.js",
+      fromVersion: "1.1.2",
+      toVersion: "2.0.0-alpha.3",
+    });
+  });
+
+  it("treats an unset version like latest", () => {
+    expect(decideMcpLaunch({ selfVersion: "1.1.2", selfPackageRoot, env: {}, project: project("2.0.0-alpha.3") }).action)
+      .toBe("delegate");
+  });
+
+  it.each([
+    ["latest caught up with a stable release", "2.0.0", "2.0.0-alpha.3"],
+    ["same version", "2.0.0-alpha.3", "2.0.0-alpha.3"],
+    ["latest is newer", "2.1.0", "2.0.0"],
+  ])("keeps the launcher when %s", (_label, selfVersion, projectVersion) => {
+    const decision = decideMcpLaunch({ selfVersion, selfPackageRoot, env: { SWALLOWKIT_MCP_VERSION: "latest" }, project: project(projectVersion) });
+    expect(decision.action).toBe("serve");
+    if (decision.action !== "serve") return;
+    expect(decision.context).toMatchObject({ mcpVersion: selfVersion, projectVersion, selection: "running-version", delegated: false, warnings: [] });
+  });
+
+  it("serves the launcher when SwallowKit is not installed in the project", () => {
+    const decision = decideMcpLaunch({ selfVersion: "1.1.2", selfPackageRoot, env: { SWALLOWKIT_MCP_VERSION: "latest" }, project: null });
+    expect(decision).toMatchObject({ action: "serve", context: { projectVersion: null, warnings: [], selection: "running-version" } });
+  });
+
+  it("honors an explicit pin and warns, without delegating, when the pin is older than the project", () => {
+    const decision = decideMcpLaunch({
+      selfVersion: "2.0.0-alpha.3",
+      selfPackageRoot,
+      env: { SWALLOWKIT_MCP_VERSION: "2.0.0-alpha.3" },
+      project: project("2.0.0-alpha.4"),
+      execCommand: "pnpm exec",
+    });
+    expect(decision.action).toBe("serve");
+    if (decision.action !== "serve") return;
+    expect(decision.context.selection).toBe("pinned");
+    expect(decision.context.warnings[0]).toMatch(/^mcp-older-than-project: swallowkit-mcp 2\.0\.0-alpha\.3 is older than the project's swallowkit 2\.0\.0-alpha\.4/);
+    expect(decision.context.nextActions.map((action) => action.command)).toEqual([
+      "pnpm exec swallowkit machine inspect capabilities",
+      "pnpm exec swallowkit configure-mcp",
+    ]);
+  });
+
+  it("does not delegate again inside a delegated process", () => {
+    const decision = decideMcpLaunch({
+      selfVersion: "2.0.0-alpha.3",
+      selfPackageRoot,
+      env: { SWALLOWKIT_MCP_VERSION: "latest", [MCP_DELEGATED_FROM_ENV]: "1.1.2" },
+      project: project("2.0.0-alpha.3"),
+    });
+    expect(decision).toMatchObject({
+      action: "serve",
+      context: { selection: "project-version", delegated: true, delegatedFrom: "1.1.2", mcpVersion: "2.0.0-alpha.3" },
+    });
+  });
+
+  it("warns instead of delegating when the newer project install has no MCP entrypoint", () => {
+    const decision = decideMcpLaunch({ selfVersion: "1.1.2", selfPackageRoot, env: {}, project: project("2.0.0-alpha.3", null) });
+    expect(decision.action).toBe("serve");
+    if (decision.action === "serve") expect(decision.context.warnings).toHaveLength(1);
+  });
+
+  it("reports a pinned launcher once published latest catches up", () => {
+    const context = {
+      mcpVersion: "2.0.0-alpha.3", requestedVersion: "2.0.0-alpha.3", projectVersion: "2.0.0-alpha.3",
+      selection: "pinned" as const, delegated: false, warnings: [], nextActions: [],
+    };
+    expect(buildPinnedUpdateNotice(context, "1.1.2")).toBeNull();
+    expect(buildPinnedUpdateNotice(context, null)).toBeNull();
+    const notice = buildPinnedUpdateNotice(context, "2.0.0", "pnpm exec");
+    expect(notice?.warning).toMatch(/pinned to 2\.0\.0-alpha\.3, but published latest is 2\.0\.0/);
+    expect(notice?.nextAction.command).toBe("pnpm exec swallowkit configure-mcp");
+    expect(buildPinnedUpdateNotice({ ...context, selection: "running-version" }, "2.0.0")).toBeNull();
+  });
+
+  it("finds the project-installed package and its MCP entrypoint", () => {
+    const directory = createProject("2.0.0-alpha.3");
+    const empty = createProject(null);
+    try {
+      const install = resolveProjectSwallowKit(directory);
+      expect(install?.version).toBe("2.0.0-alpha.3");
+      expect(install?.mcpEntrypoint).toBe(path.join(fs.realpathSync(directory), "node_modules", "swallowkit", "dist", "mcp", "index.js"));
+      expect(resolveProjectSwallowKit(empty)).toBeNull();
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true });
+      fs.rmSync(empty, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("MCP launcher version in .mcp.json", () => {
+  it.each([
+    ["2.0.0-alpha.3", "1.1.2", "2.0.0-alpha.3"],
+    ["2.0.0-alpha.3", "2.0.0", "latest"],
+    ["2.0.0-alpha.3", "2.0.0-alpha.3", "latest"],
+    ["1.1.2", "1.1.2", "latest"],
+    ["1.1.1", "1.1.2", "latest"],
+    ["2.0.0-alpha.3", null, "2.0.0-alpha.3"],
+    ["1.1.2", null, "latest"],
+  ])("project %s with published latest %s uses %s", (projectVersion, latest, expected) => {
+    expect(resolveMcpPinVersion(projectVersion, latest).version).toBe(expected);
+  });
+
+  it("selects the init value from this CLI version and the registry", () => {
+    const current = getSwallowKitVersion();
+    expect(selectInitialMcpVersion(() => current).version).toBe("latest");
+    expect(selectInitialMcpVersion(() => "0.0.1").version).toBe(current);
+  });
+
+  it("re-selects and preserves the rest of .mcp.json with configure-mcp", () => {
+    const directory = createProject("2.0.0-alpha.3");
+    try {
+      expect(configureMcp({ cwd: directory }, () => "1.1.2")).toMatchObject({ previousVersion: "latest", version: "2.0.0-alpha.3" });
+      expect(readMcpConfigVersion(directory)).toBe("2.0.0-alpha.3");
+      expect(configureMcp({ cwd: directory }, () => "2.0.0")).toMatchObject({ previousVersion: "2.0.0-alpha.3", version: "latest" });
+      expect(configureMcp({ cwd: directory, version: "2.0.0-alpha.3" }).version).toBe("2.0.0-alpha.3");
+      expect(configureMcp({ cwd: directory, version: "latest" }).version).toBe("latest");
+      expect(() => configureMcp({ cwd: directory, version: "next" })).toThrow(/auto/);
+      const config = JSON.parse(fs.readFileSync(path.join(directory, ".mcp.json"), "utf8"));
+      expect(config.mcpServers.swallowkit.args).toEqual(["dlx", "--package", "swallowkit@${SWALLOWKIT_MCP_VERSION}", "swallowkit-mcp"]);
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("built MCP entrypoint version delegation", () => {
+  const runEntrypoint = (cwd: string, env: NodeJS.ProcessEnv, until = /version: .*selection/) =>
+    new Promise<{ stderr: string; code: number | null }>((resolve, reject) => {
+      const child = spawn(process.execPath, [builtMcpEntrypoint], {
+        cwd,
+        env: { ...process.env, SWALLOWKIT_MCP_UPDATE_CHECK: "0", ...env },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      let stderr = "";
+      const timer = setTimeout(() => child.kill(), 10000);
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+        if (until.test(stderr)) child.kill();
+      });
+      child.on("error", reject);
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        resolve({ stderr, code });
+      });
+    });
+
+  itWhenBuilt("hands the session to a newer project install", async () => {
+    const directory = createProject("999.0.0-alpha.1", {
+      mcpScript: `process.stderr.write("project-mcp delegatedFrom=" + process.env.${MCP_DELEGATED_FROM_ENV} + "\\n");`,
+    });
+    try {
+      const result = await runEntrypoint(directory, { SWALLOWKIT_MCP_VERSION: "latest" });
+      expect(result.stderr).toContain("delegating to the project-installed swallowkit-mcp 999.0.0-alpha.1");
+      expect(result.stderr).toContain(`project-mcp delegatedFrom=${getSwallowKitVersion()}`);
+      expect(result.code).toBe(0);
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true });
+    }
+  }, 20000);
+
+  itWhenBuilt("keeps serving when the project install is older or the version is pinned", async () => {
+    const older = createProject("0.0.1", { mcpScript: "process.stderr.write('should-not-run');" });
+    const newer = createProject("999.0.0", { mcpScript: "process.stderr.write('should-not-run');" });
+    try {
+      const fromOlder = await runEntrypoint(older, { SWALLOWKIT_MCP_VERSION: "latest" });
+      expect(fromOlder.stderr).toContain(`version: ${getSwallowKitVersion()} (selection: running-version)`);
+      expect(fromOlder.stderr).not.toContain("should-not-run");
+      const pinned = await runEntrypoint(newer, { SWALLOWKIT_MCP_VERSION: getSwallowKitVersion() }, /mcp-older-than-project/);
+      expect(pinned.stderr).toContain("(selection: pinned)");
+      expect(pinned.stderr).toContain("mcp-older-than-project");
+      expect(pinned.stderr).not.toContain("should-not-run");
+    } finally {
+      fs.rmSync(older, { recursive: true, force: true });
+      fs.rmSync(newer, { recursive: true, force: true });
+    }
+  }, 30000);
+});