swallowkit 2.0.0-alpha.3 → 2.0.0-alpha.5

package/src/mcp/index.ts

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
 
+import { spawn } from "child_process";
 import * as path from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as z from "zod/v4";
-import type { MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
+import type { MachineErrorResponse, MachineNextAction, MachineOperationStatus, MachineResponse } from "../machine/contracts";
 import { getSwallowKitVersion } from "../version";
+import { detectFromProject, getCommands } from "../utils/package-manager";
+import {
+  MCP_DELEGATED_FROM_ENV,
+  McpVersionContext,
+  buildPinnedUpdateNotice,
+  decideMcpLaunch,
+  resolveProjectSwallowKit,
+} from "./version-selection";
 
 interface MachineSuccessPayload<TData> {
   ok: true;
@@ -16,7 +25,12 @@ interface MachineSuccessPayload<TData> {
 }
 
 type MachineCliRunner = (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>;
-type ToolContentResult = { content: Array<{ type: "text"; text: string }> };
+type ToolContentResult = { content: Array<{ type: "text"; text: string }>; isError?: boolean };
+class MachineCliError extends Error {
+  constructor(message: string, readonly response: MachineErrorResponse) {
+    super(message);
+  }
+}
 type ToolDefinition = {
   name: string;
   description: string;
@@ -64,12 +78,35 @@ async function executeMachineCommand<TData>(
     const detailsSuffix =
       parsed.error.details !== undefined ? `\ndetails: ${JSON.stringify(parsed.error.details)}` : "";
     const statusSuffix = parsed.status ? ` (status: ${parsed.status})` : "";
-    throw new Error(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`);
+    throw new MachineCliError(`[${parsed.error.code}] ${parsed.error.message}${statusSuffix}${detailsSuffix}`, parsed);
   }
 
   return parsed;
 }
 
+function defaultVersionContext(): McpVersionContext {
+  return {
+    mcpVersion: getSwallowKitVersion(),
+    requestedVersion: "latest",
+    projectVersion: null,
+    selection: "running-version",
+    delegated: false,
+    warnings: [],
+    nextActions: [],
+  };
+}
+
+function mergeNextActions(
+  first: MachineNextAction[] | undefined,
+  second: MachineNextAction[]
+): MachineNextAction[] {
+  const merged = [...(first ?? [])];
+  for (const action of second) {
+    if (!merged.some((existing) => existing.command === action.command)) merged.push(action);
+  }
+  return merged;
+}
+
 function withOperationStatus<TData>(response: MachineSuccessPayload<TData>): Record<string, unknown> {
   const data = response.data && typeof response.data === "object"
     ? (response.data as Record<string, unknown>)
@@ -92,25 +129,41 @@ function jsonTextContent(value: unknown): { content: Array<{ type: "text"; text:
   };
 }
 
-function withSwallowKitMetadata<TData>(data: TData): TData & { metadata: Record<string, unknown> } {
-  const value = data && typeof data === "object" ? data as Record<string, unknown> : { data };
+function withVersionMetadata(data: unknown, context: McpVersionContext): Record<string, unknown> {
+  const value = data && typeof data === "object" && !Array.isArray(data)
+    ? data as Record<string, unknown>
+    : { data };
   const metadata = value.metadata && typeof value.metadata === "object"
     ? value.metadata as Record<string, unknown>
     : {};
+  const existingNextActions = Array.isArray(value.nextActions) ? value.nextActions as MachineNextAction[] : undefined;
+  const nextActions = mergeNextActions(existingNextActions, context.nextActions);
 
   return {
     ...value,
+    ...(nextActions.length > 0 ? { nextActions } : {}),
     metadata: {
       ...metadata,
-      swallowkitVersion: getSwallowKitVersion(),
+      swallowkitVersion: context.mcpVersion,
+      mcp: {
+        version: context.mcpVersion,
+        requestedVersion: context.requestedVersion,
+        projectVersion: context.projectVersion,
+        selection: context.selection,
+        delegated: context.delegated,
+        ...(context.delegatedFrom ? { delegatedFrom: context.delegatedFrom } : {}),
+      },
+      ...(context.warnings.length > 0 ? { warnings: [...context.warnings] } : {}),
     },
-  } as TData & { metadata: Record<string, unknown> };
+  };
 }
 
 export function buildSwallowKitToolDefinitions(
-  runMachineCli: MachineCliRunner = defaultMachineCliRunner
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner,
+  versionContext: McpVersionContext = defaultVersionContext()
 ): ToolDefinition[] {
-  return [
+  const withSwallowKitMetadata = (data: unknown) => withVersionMetadata(data, versionContext);
+  const definitions: ToolDefinition[] = [
     {
       name: "swallowkit_inspect_project",
       description: "Return framework-owned SwallowKit project metadata.",
@@ -169,8 +222,9 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Do not create or update anything under infra/; the container migration stays pending."),
       }),
-      handler: async ({ model, functionsDir, apiDir, apiOnly }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, functionsDir, apiDir, apiOnly, skipInfra }: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
       const args = ["generate", "scaffold", model];
       if (functionsDir) {
         args.push("--functions-dir", functionsDir);
@@ -181,6 +235,9 @@ export function buildSwallowKitToolDefinitions(
       if (apiOnly) {
         args.push("--api-only");
       }
+      if (skipInfra) {
+        args.push("--skip-infra");
+      }
 
       const response = await executeMachineCommand(args, runMachineCli);
       return jsonTextContent(response.data);
@@ -195,14 +252,16 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Exclude all infra/ changes (container migration) from the plan."),
       }),
-      handler: async ({ model, models, functionsDir, apiDir, apiOnly }: { model?: string; models?: string[]; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, models, functionsDir, apiDir, apiOnly, skipInfra }: { model?: string; models?: string[]; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
         const targets = models && models.length > 0 ? models : model ? [model] : [];
         if (targets.length === 0) throw new Error("Provide model or models.");
         const args = ["plan", "scaffold", ...targets];
         if (functionsDir) args.push("--functions-dir", functionsDir);
         if (apiDir) args.push("--api-dir", apiDir);
         if (apiOnly) args.push("--api-only");
+        if (skipInfra) args.push("--skip-infra");
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -218,8 +277,9 @@ export function buildSwallowKitToolDefinitions(
         functionsDir: z.string().optional(),
         apiDir: z.string().optional(),
         apiOnly: z.boolean().optional(),
+        skipInfra: z.boolean().optional().describe("Do not create or update anything under infra/ (defaults to the plan's setting)."),
       }),
-      handler: async ({ model, planId, approve, functionsDir, apiDir, apiOnly }: { model?: string; planId?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean }) => {
+      handler: async ({ model, planId, approve, functionsDir, apiDir, apiOnly, skipInfra }: { model?: string; planId?: string; approve?: boolean; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }) => {
         const args = ["apply", "scaffold"];
         if (model) args.push(model);
         if (planId) args.push("--plan", planId);
@@ -227,6 +287,7 @@ export function buildSwallowKitToolDefinitions(
         if (functionsDir) args.push("--functions-dir", functionsDir);
         if (apiDir) args.push("--api-dir", apiDir);
         if (apiOnly) args.push("--api-only");
+        if (skipInfra) args.push("--skip-infra");
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));
@@ -252,7 +313,7 @@ export function buildSwallowKitToolDefinitions(
     },
     {
       name: "swallowkit_verify_project",
-      description: "Run verification checks (structure, drift, typecheck by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. summary.done=true means the project passed all checks. Set compact=true to suppress info-severity findings and keep the output small.",
+      description: "Run verification checks (structure, drift, typecheck, backend-build by default; build, lint, test and custom checks from swallowkit.config verify.checks are also available) and return machine-readable evidence. backend-build compiles standalone C#/TypeScript Functions or checks Python syntax; unavailable toolchains are skipped with a reason. summary.done=true means no checks failed, not that skipped checks were validated or runtime/auth flows work. Set compact=true to suppress info-severity findings and keep the output small.",
       inputSchema: z.object({
         checks: z.array(z.string()).optional(),
         compact: z.boolean().optional(),
@@ -391,16 +452,36 @@ export function buildSwallowKitToolDefinitions(
       },
     },
   ];
+
+  // Every response reports which SwallowKit version answered and why it was selected.
+  return definitions.map((definition) => ({
+    ...definition,
+    handler: async (input: unknown) => {
+      try {
+        const result = await definition.handler(input);
+        return jsonTextContent(withSwallowKitMetadata(JSON.parse(result.content[0].text)));
+      } catch (error) {
+        // Prerequisite failures carry nextActions; keep them structured so agents can follow them.
+        if (error instanceof MachineCliError && error.response.nextActions?.length) {
+          return { ...jsonTextContent(withSwallowKitMetadata(error.response)), isError: true };
+        }
+        throw error;
+      }
+    },
+  }));
 }
 
-export function createSwallowKitMcpServer(runMachineCli: MachineCliRunner = defaultMachineCliRunner): McpServer {
-  const version = getSwallowKitVersion();
+export function createSwallowKitMcpServer(
+  runMachineCli: MachineCliRunner = defaultMachineCliRunner,
+  versionContext: McpVersionContext = defaultVersionContext()
+): McpServer {
+  const version = versionContext.mcpVersion;
   const server = new McpServer({
     name: "swallowkit-mcp",
     version,
   });
 
-  for (const tool of buildSwallowKitToolDefinitions(runMachineCli)) {
+  for (const tool of buildSwallowKitToolDefinitions(runMachineCli, versionContext)) {
     server.registerTool(
       tool.name,
       {
@@ -414,9 +495,83 @@ export function createSwallowKitMcpServer(runMachineCli: MachineCliRunner = defa
   return server;
 }
 
+function resolveExecCommand(cwd: string): string {
+  try {
+    return getCommands(detectFromProject(cwd)).exec;
+  } catch {
+    return "npx";
+  }
+}
+
+async function fetchPublishedLatest(): Promise<string | null> {
+  if (process.env.SWALLOWKIT_MCP_UPDATE_CHECK === "0") return null;
+  const registry = (process.env.npm_config_registry || "https://registry.npmjs.org").replace(/\/+$/, "");
+  try {
+    const response = await fetch(`${registry}/swallowkit/latest`, { signal: AbortSignal.timeout(3000) });
+    if (!response.ok) return null;
+    const body = await response.json() as { version?: unknown };
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function delegateToProjectMcp(entrypoint: string, fromVersion: string): void {
+  const child = spawn(process.execPath, [entrypoint], {
+    stdio: "inherit",
+    env: { ...process.env, [MCP_DELEGATED_FROM_ENV]: fromVersion },
+  });
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.on("error", (error) => {
+    console.error(`[swallowkit-mcp] failed to start the project-installed MCP: ${error.message}`);
+    process.exitCode = 1;
+  });
+  child.on("exit", (code, signal) => {
+    process.exitCode = code ?? (signal ? 1 : 0);
+  });
+}
+
 export async function runMcpServer(): Promise<void> {
-  console.error(`[swallowkit-mcp] version: ${getSwallowKitVersion()}`);
-  const server = createSwallowKitMcpServer();
+  const selfVersion = getSwallowKitVersion();
+  const cwd = process.cwd();
+  const execCommand = resolveExecCommand(cwd);
+  const decision = decideMcpLaunch({
+    selfVersion,
+    selfPackageRoot: path.resolve(__dirname, "..", ".."),
+    env: process.env,
+    project: resolveProjectSwallowKit(cwd),
+    execCommand,
+  });
+
+  if (decision.action === "delegate") {
+    console.error(
+      `[swallowkit-mcp] version: ${selfVersion}; delegating to the project-installed swallowkit-mcp ${decision.toVersion} (newer than the launcher).`
+    );
+    delegateToProjectMcp(decision.entrypoint, decision.fromVersion);
+    return;
+  }
+
+  const context = decision.context;
+  // One write keeps the version line and its warnings together for log readers.
+  console.error([
+    `[swallowkit-mcp] version: ${selfVersion} (selection: ${context.selection}${context.delegatedFrom ? `, delegated from ${context.delegatedFrom}` : ""})`,
+    ...context.warnings.map((warning) => `[swallowkit-mcp] warning: ${warning}`),
+  ].join("\n"));
+
+  if (context.selection === "pinned") {
+    void fetchPublishedLatest().then((latest) => {
+      const notice = buildPinnedUpdateNotice(context, latest, execCommand);
+      if (notice) {
+        context.warnings.push(notice.warning);
+        context.nextActions.push(notice.nextAction);
+        console.error(`[swallowkit-mcp] warning: ${notice.warning}`);
+      }
+    });
+  }
+
+  const server = createSwallowKitMcpServer(defaultMachineCliRunner, context);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/mcp/version-selection.ts

@@ -0,0 +1,163 @@
+/**
+ * Runtime version selection for `swallowkit-mcp`.
+ *
+ * Policy: when launched as `latest` (or without an explicit version), use whichever is
+ * newer of this MCP package and the project-installed `swallowkit`. A newer project
+ * install takes over through its own `swallowkit-mcp`, so prerelease projects never get
+ * an older contract. An explicit SWALLOWKIT_MCP_VERSION is always honored.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { MachineNextAction } from "../machine/contracts";
+import { MCP_LATEST, MCP_VERSION_ENV } from "../core/project/mcp-config";
+import { compareSemver } from "../utils/semver";
+
+export const MCP_DELEGATED_FROM_ENV = "SWALLOWKIT_MCP_DELEGATED_FROM";
+
+export interface ProjectSwallowKitInstall {
+  version: string;
+  packageRoot: string;
+  mcpEntrypoint: string | null;
+}
+
+export type McpVersionSelection =
+  | "running-version"
+  | "project-version"
+  | "pinned";
+
+export interface McpVersionContext {
+  /** Version of the MCP server answering the request. */
+  mcpVersion: string;
+  /** SWALLOWKIT_MCP_VERSION as requested by the launcher (`latest` when unset). */
+  requestedVersion: string;
+  projectVersion: string | null;
+  selection: McpVersionSelection;
+  delegated: boolean;
+  delegatedFrom?: string;
+  warnings: string[];
+  nextActions: MachineNextAction[];
+}
+
+export type McpLaunchDecision =
+  | { action: "delegate"; entrypoint: string; fromVersion: string; toVersion: string }
+  | { action: "serve"; context: McpVersionContext };
+
+export interface McpLaunchInput {
+  selfVersion: string;
+  selfPackageRoot: string;
+  env: NodeJS.ProcessEnv;
+  project: ProjectSwallowKitInstall | null;
+  execCommand?: string;
+}
+
+function normalizeRoot(value: string): string {
+  const resolved = path.resolve(value);
+  try {
+    return fs.realpathSync.native(resolved).toLowerCase();
+  } catch {
+    return resolved.toLowerCase();
+  }
+}
+
+export function resolveProjectSwallowKit(cwd: string): ProjectSwallowKitInstall | null {
+  // Same lookup order as Node's node_modules resolution from the project directory.
+  let packageJsonPath: string | null = null;
+  for (let directory = path.resolve(cwd); ; directory = path.dirname(directory)) {
+    const candidate = path.join(directory, "node_modules", "swallowkit", "package.json");
+    if (fs.existsSync(candidate)) {
+      packageJsonPath = fs.realpathSync(candidate);
+      break;
+    }
+    if (path.dirname(directory) === directory) return null;
+  }
+
+  try {
+    const manifest = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) as {
+      version?: string;
+      bin?: string | Record<string, string>;
+    };
+    if (!manifest.version) return null;
+    const packageRoot = path.dirname(packageJsonPath);
+    const bin = typeof manifest.bin === "object" ? manifest.bin["swallowkit-mcp"] : undefined;
+    const candidate = path.resolve(packageRoot, bin ?? path.join("dist", "mcp", "index.js"));
+    return {
+      version: manifest.version,
+      packageRoot,
+      mcpEntrypoint: fs.existsSync(candidate) ? candidate : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function decideMcpLaunch(input: McpLaunchInput): McpLaunchDecision {
+  const { selfVersion, env, project } = input;
+  const exec = input.execCommand ?? "npx";
+  const requested = (env[MCP_VERSION_ENV] ?? "").trim() || MCP_LATEST;
+  const pinned = requested !== MCP_LATEST;
+  const delegatedFrom = (env[MCP_DELEGATED_FROM_ENV] ?? "").trim() || undefined;
+  const projectVersion = project?.version ?? null;
+  const projectNewer = projectVersion ? (compareSemver(projectVersion, selfVersion) ?? 0) > 0 : false;
+  const sameInstall = project ? normalizeRoot(project.packageRoot) === normalizeRoot(input.selfPackageRoot) : false;
+
+  if (!pinned && !delegatedFrom && project && projectNewer && !sameInstall && project.mcpEntrypoint) {
+    return { action: "delegate", entrypoint: project.mcpEntrypoint, fromVersion: selfVersion, toVersion: project.version };
+  }
+
+  const warnings: string[] = [];
+  const nextActions: MachineNextAction[] = [];
+  if (projectVersion && projectNewer) {
+    warnings.push(
+      `mcp-older-than-project: swallowkit-mcp ${selfVersion} is older than the project's swallowkit ${projectVersion}. ` +
+        "Its capabilities, boundaries, and plan/apply contracts may be outdated for this project."
+    );
+    nextActions.push({
+      command: `${exec} swallowkit machine inspect capabilities`,
+      description: "Use the project-local machine interface, which matches the installed SwallowKit version, until MCP is updated.",
+    });
+    nextActions.push({
+      command: `${exec} swallowkit configure-mcp`,
+      description: pinned
+        ? `Re-select the MCP version (${MCP_VERSION_ENV} is pinned to ${requested}), then restart the MCP server.`
+        : "Pin the MCP launcher to the project version, then restart the MCP server.",
+    });
+  }
+
+  return {
+    action: "serve",
+    context: {
+      mcpVersion: selfVersion,
+      requestedVersion: requested,
+      projectVersion,
+      selection: delegatedFrom ? "project-version" : pinned ? "pinned" : "running-version",
+      delegated: Boolean(delegatedFrom),
+      ...(delegatedFrom ? { delegatedFrom } : {}),
+      warnings,
+      nextActions,
+    },
+  };
+}
+
+/**
+ * For an explicitly pinned launcher, report when the published `latest` has caught up
+ * with or passed the pinned version so the pin can be removed.
+ */
+export function buildPinnedUpdateNotice(
+  context: McpVersionContext,
+  publishedLatest: string | null,
+  execCommand = "npx"
+): { warning: string; nextAction: MachineNextAction } | null {
+  if (context.selection !== "pinned" || !publishedLatest) return null;
+  const comparison = compareSemver(publishedLatest, context.requestedVersion);
+  if (comparison === null || comparison < 0) return null;
+  return {
+    warning:
+      `mcp-pin-outdated: ${MCP_VERSION_ENV} is pinned to ${context.requestedVersion}, but published latest is ${publishedLatest}. ` +
+      `Switch the launcher back to "${MCP_LATEST}".`,
+    nextAction: {
+      command: `${execCommand} swallowkit configure-mcp`,
+      description: `Re-select the MCP launcher version (returns to "${MCP_LATEST}" when it is at least the project version), then restart the MCP server.`,
+    },
+  };
+}

package/src/utils/azure-cli.ts

@@ -0,0 +1,154 @@
+/**
+ * Azure CLI invocation that works without a shell on every platform.
+ *
+ * On Windows `az` is a batch wrapper (az.cmd). Node cannot spawn it with `shell: false`
+ * (ENOENT for "az", EINVAL for "az.cmd"), so the wrapper is resolved explicitly:
+ * the MSI layout runs its bundled Python exactly like az.cmd does, and other wrappers
+ * run through cmd.exe with every argument quoted.
+ */
+
+import { spawnSync, SpawnSyncOptions } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+
+export interface AzCliInvocation {
+  command: string;
+  prefixArgs: string[];
+  env?: NodeJS.ProcessEnv;
+  /** Batch wrapper that must be started through cmd.exe. */
+  batchScript?: string;
+  /** Resolved executable or wrapper, for diagnostics. */
+  source: string;
+}
+
+export interface AzCliResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+}
+
+export type AzCliAvailability =
+  | { available: true; invocation: AzCliInvocation }
+  | { available: false; reason: "not-found" | "not-runnable"; detail: string };
+
+function findOnWindowsPath(name: string, env: NodeJS.ProcessEnv): string | null {
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const extensions = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((ext) => ext.toLowerCase());
+  for (const directory of pathValue.split(";").filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(directory.replace(/^"|"$/g, ""), `${name}${extension}`);
+      try {
+        if (fs.statSync(candidate).isFile()) return candidate;
+      } catch {
+        // Keep searching PATH.
+      }
+    }
+  }
+  return null;
+}
+
+export function resolveAzCliInvocation(
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform
+): AzCliInvocation | null {
+  if (platform !== "win32") return { command: "az", prefixArgs: [], source: "az" };
+
+  const resolved = findOnWindowsPath("az", env);
+  if (!resolved) return null;
+  const extension = path.extname(resolved).toLowerCase();
+  if (extension === ".exe" || extension === ".com") {
+    return { command: resolved, prefixArgs: [], source: resolved };
+  }
+
+  // MSI install: wbin\az.cmd runs "..\python.exe -IBm azure.cli %*" with AZ_INSTALLER=MSI.
+  const bundledPython = path.join(path.dirname(resolved), "..", "python.exe");
+  if (path.basename(path.dirname(resolved)).toLowerCase() === "wbin" && fs.existsSync(bundledPython)) {
+    return {
+      command: path.resolve(bundledPython),
+      prefixArgs: ["-IBm", "azure.cli"],
+      env: { AZ_INSTALLER: "MSI" },
+      source: resolved,
+    };
+  }
+
+  return { command: env.ComSpec ?? "cmd.exe", prefixArgs: [], batchScript: resolved, source: resolved };
+}
+
+/** Builds the cmd.exe /s /c payload. Rejects characters cmd.exe would reinterpret even inside quotes. */
+export function buildBatchCommandLine(script: string, args: string[]): string {
+  for (const value of [script, ...args]) {
+    if (/["%\r\n]/.test(value)) {
+      throw new Error(`Azure CLI argument cannot be passed safely through ${path.basename(script)}: ${JSON.stringify(value)}`);
+    }
+  }
+  return `"${[script, ...args].map((value) => `"${value}"`).join(" ")}"`;
+}
+
+let cachedInvocation: AzCliInvocation | null | undefined;
+
+export function getAzCliInvocation(): AzCliInvocation | null {
+  if (cachedInvocation === undefined) cachedInvocation = resolveAzCliInvocation();
+  return cachedInvocation;
+}
+
+export function resetAzCliInvocationCache(): void {
+  cachedInvocation = undefined;
+}
+
+/** Test hook: pin the resolved invocation (null = not found). */
+export function setAzCliInvocationForTesting(invocation: AzCliInvocation | null | undefined): void {
+  cachedInvocation = invocation;
+}
+
+export function runAzCli(
+  args: string[],
+  options: { timeout?: number; invocation?: AzCliInvocation | null } = {}
+): AzCliResult {
+  const invocation = options.invocation === undefined ? getAzCliInvocation() : options.invocation;
+  if (!invocation) {
+    return { status: null, stdout: "", stderr: "", error: Object.assign(new Error("az was not found on PATH"), { code: "ENOENT" }) };
+  }
+  const spawnOptions: SpawnSyncOptions = {
+    shell: false,
+    encoding: "utf-8",
+    timeout: options.timeout ?? 300_000,
+    env: invocation.env ? { ...process.env, ...invocation.env } : process.env,
+  };
+  let result;
+  try {
+    result = invocation.batchScript
+      ? spawnSync(invocation.command, ["/d", "/s", "/v:off", "/c", buildBatchCommandLine(invocation.batchScript, args)], {
+        ...spawnOptions,
+        windowsVerbatimArguments: true,
+      })
+      : spawnSync(invocation.command, [...invocation.prefixArgs, ...args], spawnOptions);
+  } catch (error) {
+    return { status: null, stdout: "", stderr: "", error: error instanceof Error ? error : new Error(String(error)) };
+  }
+  return {
+    status: result.status,
+    stdout: String(result.stdout ?? ""),
+    stderr: String(result.stderr ?? ""),
+    ...(result.error ? { error: result.error } : {}),
+  };
+}
+
+export function checkAzCliAvailability(): AzCliAvailability {
+  const invocation = getAzCliInvocation();
+  if (!invocation) {
+    return { available: false, reason: "not-found", detail: "az was not found on PATH." };
+  }
+  const result = runAzCli(["--version"], { timeout: 60_000, invocation });
+  if (result.status === 0) return { available: true, invocation };
+  const errorCode = (result.error as NodeJS.ErrnoException | undefined)?.code;
+  if (errorCode === "ENOENT") {
+    return { available: false, reason: "not-found", detail: "az was not found on PATH." };
+  }
+  const output = `${result.stderr || result.stdout}`.trim().split(/\r?\n/).slice(-3).join(" ");
+  return {
+    available: false,
+    reason: "not-runnable",
+    detail: `${invocation.source} could not run "az --version" (${result.error?.message ?? `exit ${result.status}`})${output ? `: ${output}` : ""}`,
+  };
+}

package/src/utils/semver.ts

@@ -0,0 +1,59 @@
+export interface ParsedSemver {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: Array<string | number>;
+}
+
+const SEMVER_PATTERN =
+  /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export function parseSemver(value: string | null | undefined): ParsedSemver | null {
+  const match = typeof value === "string" ? SEMVER_PATTERN.exec(value.trim()) : null;
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4]
+      ? match[4].split(".").map((identifier) => (/^\d+$/.test(identifier) ? Number(identifier) : identifier))
+      : [],
+  };
+}
+
+export function isPrerelease(value: string): boolean {
+  return (parseSemver(value)?.prerelease.length ?? 0) > 0;
+}
+
+/**
+ * Compares versions by SemVer 2.0 precedence. Build metadata is ignored.
+ * Returns null when either value is not a valid version.
+ */
+export function compareSemver(left: string, right: string): number | null {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return null;
+
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
+  }
+
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    if (a.prerelease.length === b.prerelease.length) return 0;
+    return a.prerelease.length === 0 ? 1 : -1;
+  }
+
+  const length = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let index = 0; index < length; index++) {
+    const leftId = a.prerelease[index];
+    const rightId = b.prerelease[index];
+    if (leftId === undefined) return -1;
+    if (rightId === undefined) return 1;
+    if (leftId === rightId) continue;
+    if (typeof leftId === "number" && typeof rightId === "number") return leftId < rightId ? -1 : 1;
+    if (typeof leftId === "number") return -1;
+    if (typeof rightId === "number") return 1;
+    return leftId < rightId ? -1 : 1;
+  }
+  return 0;
+}