swallowkit 2.0.0-alpha.1 → 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", () => {
@@ -109,6 +112,13 @@ export default 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");
 
@@ -155,9 +165,43 @@ export default 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 {
@@ -332,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'");

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);
+});

package/src/__tests__/mcp.test.ts

@@ -8,6 +8,77 @@ const builtMcpEntrypoint = path.resolve(__dirname, "..", "..", "dist", "mcp", "i
 const itWhenBuiltEntrypointExists = fs.existsSync(builtMcpEntrypoint) ? it : it.skip;
 
 describe("SwallowKit MCP tool definitions", () => {
+  it.each([
+    { status: "in-progress", outcome: "in-progress", state: "Running" },
+    { status: "blocked", outcome: "partial", state: "Succeeded" },
+  ])("does not promote $outcome provisioning to complete", async ({ status, outcome, state }) => {
+    const nextActions = [{ command: "swallowkit machine inspect provision --plan 123456789abc", description: "Read original state." }];
+    const runner = jest.fn(async () => ({
+      stdout: JSON.stringify({ ok: true, command: "apply-provision", status, nextActions, data: { outcome, deployment: { state } } }),
+      stderr: "", exitCode: 0,
+    }));
+    const tool = buildSwallowKitToolDefinitions(runner).find(candidate => candidate.name === "swallowkit_apply_provision")!;
+    const result = await tool.handler({ planId: "123456789abc", approve: true, waitSeconds: 0 });
+    expect(runner).toHaveBeenCalledWith(["apply", "provision", "--plan", "123456789abc", "--approve", "--wait-seconds", "0"]);
+    expect(JSON.parse(result.content[0].text)).toMatchObject({ status, outcome, deployment: { state }, nextActions });
+  });
+
+  it.each([
+    { status: "requires-human", code: "approval-required" },
+    { status: "failed", code: "azure-deployment-failed" },
+  ])("preserves $code and recovery actions", async ({ status, code }) => {
+    const nextActions = [{ command: "swallowkit machine apply provision --plan 123456789abc --approve", description: "Obtain human approval." }];
+    const runner = jest.fn(async () => ({
+      stdout: JSON.stringify({ ok: false, command: "apply-provision", status, error: { code, message: "Fixture error." }, nextActions }),
+      stderr: "", exitCode: 1,
+    }));
+    const tool = buildSwallowKitToolDefinitions(runner).find(candidate => candidate.name === "swallowkit_apply_provision")!;
+    const result = await tool.handler({ planId: "123456789abc" });
+    expect(runner).toHaveBeenCalledWith(["apply", "provision", "--plan", "123456789abc"]);
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0].text)).toMatchObject({ status, error: { code }, nextActions });
+  });
+
+  it.each(["swallowkit_apply_provision", "swallowkit_inspect_provision"])("forwards cancellation and preserves an unknown outcome for %s", async name => {
+    const controller = new AbortController();
+    const runner = jest.fn(async (_args: string[], signal?: AbortSignal) => {
+      expect(signal).toBe(controller.signal);
+      controller.abort();
+      return { stdout: "", stderr: "", exitCode: 143 };
+    });
+    const tool = buildSwallowKitToolDefinitions(runner).find(candidate => candidate.name === name)!;
+    const result = await tool.handler({ planId: "123456789abc", approve: true }, controller.signal);
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0].text)).toMatchObject({
+      status: "blocked", error: { code: "provision-interrupted", details: { outcome: "unknown", localFailure: "cancelled" } },
+      nextActions: expect.arrayContaining([expect.objectContaining({ command: "swallowkit machine inspect provision --plan 123456789abc" })]),
+    });
+  });
+
+  it("does not launch provision after the MCP request was already cancelled", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const runner = jest.fn(async () => ({ stdout: "", stderr: "", exitCode: 1 }));
+    const tool = buildSwallowKitToolDefinitions(runner).find(candidate => candidate.name === "swallowkit_apply_provision")!;
+    expect((await tool.handler({ planId: "123456789abc", approve: true }, controller.signal)).isError).toBe(true);
+    expect(runner).not.toHaveBeenCalled();
+  });
+
+  it("preserves blocked auth prerequisites and nextActions as structured MCP errors", async () => {
+    const nextActions = [{ command: "swallowkit machine plan auth --provider swa", description: "Configure auth first." }];
+    const runner = jest.fn(async () => ({
+      stdout: JSON.stringify({ ok: false, command: "plan-scaffold", status: "blocked",
+        error: { code: "auth-policy-without-auth", message: "Authentication is not configured." }, nextActions }),
+      stderr: "", exitCode: 1,
+    }));
+    const tool = buildSwallowKitToolDefinitions(runner).find(candidate => candidate.name === "swallowkit_plan_scaffold")!;
+    const result = await tool.handler({ model: "probe-item" });
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0].text)).toMatchObject({
+      status: "blocked", error: { code: "auth-policy-without-auth" }, nextActions,
+      metadata: { swallowkitVersion: expect.any(String) },
+    });
+  });
   it("delegates inspect_project to the machine CLI", async () => {
     const runner = jest.fn(async () => ({
       stdout: JSON.stringify({
@@ -26,10 +97,48 @@ describe("SwallowKit MCP tool definitions", () => {
     expect(runner).toHaveBeenCalledWith(["inspect", "project"]);
     expect(JSON.parse(result.content[0].text)).toEqual({
       manifestSource: "file",
-      metadata: { swallowkitVersion: expect.stringMatching(/^\d+\.\d+\.\d+/) },
+      metadata: {
+        swallowkitVersion: expect.stringMatching(/^\d+\.\d+\.\d+/),
+        mcp: expect.objectContaining({ selection: "running-version", delegated: false }),
+      },
     });
   });
 
+  it("reports delegation, the serving version, and version warnings on every tool", async () => {
+    const runner = jest.fn(async () => ({
+      stdout: JSON.stringify({ ok: true, command: "inspect-entities", data: { entities: [] } }),
+      stderr: "",
+      exitCode: 0,
+    }));
+    const context = {
+      mcpVersion: "2.0.0-alpha.3",
+      requestedVersion: "latest",
+      projectVersion: "2.0.0-alpha.4",
+      selection: "project-version" as const,
+      delegated: true,
+      delegatedFrom: "1.1.2",
+      warnings: ["mcp-older-than-project: example"],
+      nextActions: [{ command: "pnpm exec swallowkit configure-mcp", description: "Re-select." }],
+    };
+    const tools = buildSwallowKitToolDefinitions(runner as MachineCliRunner, context);
+    for (const name of ["swallowkit_inspect_entities", "swallowkit_inspect_capabilities", "swallowkit_inspect_boundaries"]) {
+      const parsed = JSON.parse((await tools.find((tool) => tool.name === name)!.handler({})).content[0].text);
+      expect(parsed.metadata).toEqual({
+        swallowkitVersion: "2.0.0-alpha.3",
+        mcp: {
+          version: "2.0.0-alpha.3",
+          requestedVersion: "latest",
+          projectVersion: "2.0.0-alpha.4",
+          selection: "project-version",
+          delegated: true,
+          delegatedFrom: "1.1.2",
+        },
+        warnings: ["mcp-older-than-project: example"],
+      });
+      expect(parsed.nextActions).toEqual(context.nextActions);
+    }
+  });
+
   it("includes the MCP version in validate_project metadata", async () => {
     const runner = jest.fn(async () => ({
       stdout: JSON.stringify({ ok: true, command: "validate-project", data: { valid: true } }),
@@ -43,7 +152,7 @@ describe("SwallowKit MCP tool definitions", () => {
     const result = await tool!.handler({});
     expect(JSON.parse(result.content[0].text)).toEqual({
       valid: true,
-      metadata: { swallowkitVersion: expect.stringMatching(/^\d+\.\d+\.\d+/) },
+      metadata: expect.objectContaining({ swallowkitVersion: expect.stringMatching(/^\d+\.\d+\.\d+/) }),
     });
   });
 
@@ -78,7 +187,10 @@ describe("SwallowKit MCP tool definitions", () => {
       "app/api",
       "--api-only",
     ]);
-    expect(JSON.parse(result.content[0].text)).toEqual({ createdFiles: ["functions/src/todo.ts"] });
+    expect(JSON.parse(result.content[0].text)).toEqual({
+      createdFiles: ["functions/src/todo.ts"],
+      metadata: expect.objectContaining({ swallowkitVersion: expect.any(String) }),
+    });
   });
 
   it("exposes the agent-loop tools (plan/apply/artifacts/drift/verify/explain)", () => {
@@ -114,6 +226,11 @@ describe("SwallowKit MCP tool definitions", () => {
     const result = await tool!.handler({ model: "todo", apiOnly: true });
 
     expect(runner).toHaveBeenCalledWith(["plan", "scaffold", "todo", "--api-only"]);
+    await tool!.handler({ model: "todo", skipInfra: true });
+    expect(runner).toHaveBeenLastCalledWith(["plan", "scaffold", "todo", "--skip-infra"]);
+    const applyTool = buildSwallowKitToolDefinitions(runner as MachineCliRunner).find((candidate) => candidate.name === "swallowkit_apply_scaffold");
+    await applyTool!.handler({ model: "todo", skipInfra: true });
+    expect(runner).toHaveBeenLastCalledWith(["apply", "scaffold", "todo", "--skip-infra"]);
     const parsed = JSON.parse(result.content[0].text);
     expect(parsed.status).toBe("requires-human");
     expect(parsed.planId).toBe("abc");