swallowkit 2.0.0-alpha.2 → 2.0.0-alpha.4

package/src/cli/commands/dev.ts

@@ -19,15 +19,15 @@ import {
 import { BackendLanguage } from '../../types';
 import { detectFromProject, getCommands } from '../../utils/package-manager';
 import {
-  buildProjectLocalUvEnv,
   buildProjectLocalUvInstallerEnv,
   buildUvPipInstallArgs,
-  buildUvVenvArgs,
+  ensureUvVirtualEnvironment,
   getProjectLocalUvInstallerCommand,
   getProjectLocalUvPaths,
   getPythonProjectRoot,
 } from '../../utils/python-uv';
 import { ConnectorMockServer } from '../../core/mock/connector-mock-server';
+import { buildReactDevConfigSource } from '../../utils/react-dev';
 
 export interface DevOptions {
   port?: string;
@@ -65,8 +65,8 @@ function normalizeParsedDevOptions(options: ParsedDevActionOptions): DevOptions
   };
 }
 
-export function buildFunctionsStartArgs(functionsPort: string): string[] {
-  return ['start', '--port', functionsPort];
+export function buildFunctionsStartArgs(functionsPort: string, backendLanguage: BackendLanguage = 'typescript'): string[] {
+  return [...(backendLanguage === 'csharp' ? [] : ['start']), '--port', functionsPort];
 }
 
 export function parseCoreToolsVersion(output: string): string | null {
@@ -105,15 +105,15 @@ export function buildFunctionsCoreToolsCommand(
 
     return {
       command: 'npm',
-      argsPrefix: ['exec', '--yes', NPM_CORE_TOOLS_PACKAGE, '--'],
-      label: `npm exec ${NPM_CORE_TOOLS_PACKAGE} (${reason})`,
+      argsPrefix: ['exec', '--yes', '--package', NPM_CORE_TOOLS_PACKAGE, '--', 'dotnet', 'run', '--no-launch-profile', '--'],
+      label: `dotnet run with npm ${NPM_CORE_TOOLS_PACKAGE} (${reason})`,
     };
   }
 
   return {
-    command: 'func',
-    argsPrefix: [],
-    label: installedVersion ? `func ${installedVersion}` : 'func',
+    command: backendLanguage === 'csharp' ? 'dotnet' : 'func',
+    argsPrefix: backendLanguage === 'csharp' ? ['run', '--no-launch-profile', '--'] : [],
+    label: backendLanguage === 'csharp' ? 'dotnet run' : installedVersion ? `func ${installedVersion}` : 'func',
   };
 }
 
@@ -138,8 +138,8 @@ export function buildSwaStartArgs(host: string | undefined, nextPort: string, sw
   ];
 }
 
-export function buildReactDevArgs(pm: string, port: string, host = 'localhost'): string[] {
-  const args = ['vite', '--port', port, '--host', host, '--strictPort'];
+export function buildReactDevArgs(pm: string, port: string, host = 'localhost', configPath?: string): string[] {
+  const args = ['vite', '--port', port, '--host', host, '--strictPort', ...(configPath ? ['--config', configPath] : [])];
   return pm === 'pnpm' ? ['exec', ...args] : args;
 }
 
@@ -270,7 +270,7 @@ async function checkCommand(
 }
 
 async function resolveProjectLocalUvCommand(projectRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
-  const uvEnv = buildProjectLocalUvEnv(process.env, projectRoot);
+  const uvEnv = { ...process.env };
   const { localUvExecutable } = getProjectLocalUvPaths(projectRoot);
 
   if (await checkCommand('uv', ['--version'], { shell: false })) {
@@ -471,22 +471,8 @@ async function bridgePythonCoreToolsForWindowsArm64(
 async function preparePythonFunctionsEnvironment(functionsDir: string): Promise<NodeJS.ProcessEnv> {
   const projectRoot = getPythonProjectRoot(functionsDir);
   const { command: uvCommand, env: uvEnv } = await resolveProjectLocalUvCommand(projectRoot);
-  const { venvDir, pythonExecutable } = getPythonVirtualEnvPaths(functionsDir);
-  const hasUsableVirtualEnv = fs.existsSync(pythonExecutable) && await checkCommand(pythonExecutable, ['--version'], {
-    cwd: functionsDir,
-    env: uvEnv,
-    shell: false,
-  });
-
-  if (!hasUsableVirtualEnv) {
-    const venvArgs = buildUvVenvArgs('.venv');
-    if (fs.existsSync(venvDir)) {
-      venvArgs.push('--clear');
-    }
-
-    console.log('📦 Creating Python virtual environment with uv...');
-    await runCommand(uvCommand, venvArgs, functionsDir, 'python virtual environment setup', uvEnv, false);
-  }
+  const { venvDir } = getPythonVirtualEnvPaths(functionsDir);
+  const pythonExecutable = await ensureUvVirtualEnvironment(uvCommand, venvDir, functionsDir, uvEnv);
 
   console.log('📦 Installing Python Azure Functions dependencies with uv...');
   await runCommand(
@@ -538,7 +524,7 @@ export async function assertDevPortAvailable(port: number, host: string): Promis
 }
 
 function stopDevProcesses(processes: ChildProcess[]): void {
-  const active = processes.filter(child => child.pid && !child.killed);
+  const active = processes.filter(child => child.pid && !child.killed && child.exitCode === null && child.signalCode === null);
   if (process.platform === 'win32' && active.length) {
     // Windows shell termination alone leaves Vite, Core Tools, and SWA running.
     const ids = active.map(child => child.pid).join(',');
@@ -721,6 +707,14 @@ async function startDevEnvironment(options: DevOptions) {
   const functionsBaseUrl = buildFunctionsBaseUrl(options.host, functionsPort);
   let functionsReadinessPromise: Promise<boolean> | null = null;
   let functionsReady = !!options.noFunctions;
+  let reactDevConfigDir: string | undefined;
+  const cleanupReactDevConfig = () => {
+    if (reactDevConfigDir) {
+      fs.rmSync(reactDevConfigDir, { recursive: true, force: true });
+      reactDevConfigDir = undefined;
+    }
+  };
+  process.once('exit', cleanupReactDevConfig);
 
   // Cleanup processes on Ctrl+C
   process.on('SIGINT', async () => {
@@ -939,7 +933,7 @@ async function startDevEnvironment(options: DevOptions) {
 
       // Azure Functions を起動
       const functionsCommand = functionsCoreToolsCommand ?? buildFunctionsCoreToolsCommand(backendLanguage, installedCoreToolsVersion);
-      const funcProcess = spawn(functionsCommand.command, [...functionsCommand.argsPrefix, ...buildFunctionsStartArgs(functionsPort)], {
+      const funcProcess = spawn(functionsCommand.command, [...functionsCommand.argsPrefix, ...buildFunctionsStartArgs(functionsPort, backendLanguage)], {
         cwd: functionsDir,
         shell: true,
         stdio: 'pipe', // Always pipe to capture output
@@ -987,6 +981,8 @@ async function startDevEnvironment(options: DevOptions) {
         console.error('⚠️  Azure Functions startup error:', error.message);
         console.log('💡 Please ensure Azure Functions Core Tools is installed');
         console.log(`   ${pmCmd.addGlobal} azure-functions-core-tools@4`);
+        stopDevProcesses(processes);
+        process.exit(1);
       });
 
       funcProcess.on('close', (code) => {
@@ -997,6 +993,8 @@ async function startDevEnvironment(options: DevOptions) {
             console.log('   Reinstall a matching Core Tools v4 package (Windows users should prefer the official x64/x86 MSI for their machine).');
             console.log('   SwallowKit local Python dev uses functions/.venv and requirements.txt, but Core Tools still needs its own bundled Python worker.');
           }
+          stopDevProcesses(processes);
+          process.exit(code || 1);
         }
       });
 
@@ -1083,7 +1081,17 @@ async function startDevEnvironment(options: DevOptions) {
     }
 
     // 5. Start Next.js development server
-    const nextArgs = react ? buildReactDevArgs(pm, port, options.host) : buildNextDevArgs(pm, port);
+    let reactDevConfigPath: string | undefined;
+    if (react) {
+      const stateDir = path.join(process.cwd(), '.swallowkit');
+      fs.mkdirSync(stateDir, { recursive: true });
+      reactDevConfigDir = fs.mkdtempSync(path.join(stateDir, 'vite-dev-'));
+      reactDevConfigPath = path.join(reactDevConfigDir, 'config.mjs');
+      fs.writeFileSync(reactDevConfigPath, buildReactDevConfigSource());
+    }
+    const nextArgs = react
+      ? buildReactDevArgs(pm, port, options.host, reactDevConfigPath && path.relative(process.cwd(), reactDevConfigPath))
+      : buildNextDevArgs(pm, port);
     
     // Ensure .env.local points to bffTargetPort so Next.js reads the correct backend URL.
     // When --mock-connectors is active, bffTargetPort = mock port (7072); otherwise = Functions port (7071).
@@ -1141,6 +1149,7 @@ async function startDevEnvironment(options: DevOptions) {
 
     nextProcess.on('error', (error) => {
       console.error(`❌ ${frontendLabel} startup error:`, error.message);
+      stopDevProcesses(processes);
       process.exit(1);
     });
 

package/src/cli/commands/init.ts

@@ -25,7 +25,9 @@ import {
   buildCSharpCodegenToolManifestSource,
   buildPythonCodegenRequirementsSource,
 } from "../../core/scaffold/native-schema-generator";
-import { getProjectLocalUvPaths } from "../../utils/python-uv";
+import { DEFAULT_AZURE_PYTHON_VERSION } from "../../utils/python-uv";
+import { buildHomePage } from "../../core/project/home-page";
+import { MCP_LATEST, McpPinDecision, lookupPublishedLatestVersion, resolveMcpPinVersion } from "../../core/project/mcp-config";
 
 interface InitOptions {
   name: string;
@@ -144,7 +146,7 @@ function getFunctionsRuntimeConfig(backendLanguage: BackendLanguage): { name: st
     return { name: "dotnet-isolated", version: "10.0" };
   }
   if (backendLanguage === "python") {
-    return { name: "python", version: "3.11" };
+    return { name: "python", version: DEFAULT_AZURE_PYTHON_VERSION };
   }
   return { name: "node", version: "22" };
 }
@@ -344,7 +346,7 @@ export async function initCommand(options: InitOptions) {
     const azureConfig = await promptAzureConfig(options);
 
     if (frontend === "react") {
-      createReactProject(projectDir, options.name);
+      createReactProject(projectDir, options.name, pm);
     } else {
       await createNextJsProject(options.name, pm);
       await upgradeNextJs(projectDir, options.nextVersion || 'latest', pm);
@@ -711,7 +713,7 @@ export function buildCSharpFunctionsProjectSource(): string {
     <None Remove="generated\\**\\bin\\**;generated\\**\\obj\\**" />
   </ItemGroup>
   <ItemGroup>
-    <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
+    <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.63.2" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
     <PackageReference Include="Azure.Identity" Version="1.17.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="2.52.0" />
@@ -778,14 +780,30 @@ function getSwallowKitPackageMetadata(): { name: string; version: string } {
   };
 }
 
-export function buildGeneratedProjectDevDependencies(): Record<string, string> {
+export function buildGeneratedProjectDevDependencies(frontend: FrontendFramework = "nextjs"): Record<string, string> {
   const { name, version } = getSwallowKitPackageMetadata();
   return {
     [name]: version,
+    ...(frontend === "nextjs" ? { "@tailwindcss/postcss": "^4.0.0" } : {}),
   };
 }
 
-export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm'): string {
+export function ensureNextTailwindPostcssConfig(projectDir: string): void {
+  if (["postcss.config.mjs", "postcss.config.js", "postcss.config.cjs", "postcss.config.json"]
+    .some(file => fs.existsSync(path.join(projectDir, file)))) {
+    return;
+  }
+
+  // New create-next-app templates can configure Tailwind for Turbopack only.
+  fs.writeFileSync(path.join(projectDir, "postcss.config.mjs"), `export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+`);
+}
+
+export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm', mcpVersion: string = MCP_LATEST): string {
   const { name } = getSwallowKitPackageMetadata();
   return JSON.stringify(
     {
@@ -797,7 +815,7 @@ export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm
             : ["--yes", "--package", `${name}@\${SWALLOWKIT_MCP_VERSION}`, "swallowkit-mcp"],
           cwd: ".",
           env: {
-            SWALLOWKIT_MCP_VERSION: "latest",
+            SWALLOWKIT_MCP_VERSION: mcpVersion,
           },
         },
       },
@@ -807,6 +825,15 @@ export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm
   );
 }
 
+/** latest by default; pinned to this CLI version only when it is newer than published latest. */
+export function selectInitialMcpVersion(
+  lookupLatest: (packageName: string) => string | null = lookupPublishedLatestVersion
+): McpPinDecision {
+  const { name, version } = getSwallowKitPackageMetadata();
+  if (version === MCP_LATEST) return { version: MCP_LATEST, reason: "SwallowKit package metadata is unavailable." };
+  return resolveMcpPinVersion(version, lookupLatest(name));
+}
+
 async function addSwallowKitFiles(
   projectDir: string,
   options: InitOptions,
@@ -831,7 +858,7 @@ async function addSwallowKitFiles(
   };
   packageJson.devDependencies = {
     ...packageJson.devDependencies,
-    ...buildGeneratedProjectDevDependencies(),
+    ...buildGeneratedProjectDevDependencies(frontend),
   };
 
   packageJson.scripts = {
@@ -865,6 +892,8 @@ async function addSwallowKitFiles(
   
   fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
 
+  if (frontend === "nextjs") ensureNextTailwindPostcssConfig(projectDir);
+
   // Create pnpm-workspace.yaml for local pnpm development when needed.
   if (wsConfig.type === 'file') {
     fs.writeFileSync(path.join(projectDir, wsConfig.filename), wsConfig.content + (frontend === "react" ? "  esbuild: true\n" : ""));
@@ -1492,7 +1521,6 @@ public sealed class GreetFunction
 }
 
 function createPythonFunctionsProject(projectDir: string, functionsDir: string): void {
-  fs.writeFileSync(path.join(projectDir, '.python-version'), '3.11\n');
   ensureProjectGitignoreEntry(projectDir, '.uv');
 
   fs.writeFileSync(path.join(functionsDir, 'requirements.txt'), `azure-functions>=1.20.0
@@ -1632,117 +1660,8 @@ export async function POST(request: NextRequest) {
 
 async function createHomePage(projectDir: string, pm: PackageManager = 'pnpm') {
   console.log('📦 Creating home page...\n');
-  
-  const pmCmd = getCommands(pm);
-  
-  const pageContent = `'use client'
 
-export const dynamic = 'force-dynamic';
-
-import { useState } from 'react';
-import { scaffoldConfig } from '@/lib/scaffold-config';
-
-export default function Home() {
-  const [greetingStatus, setGreetingStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
-  const [message, setMessage] = useState('');
-
-  const testConnection = async () => {
-    setGreetingStatus('loading');
-    try {
-      const response = await fetch('/api/greet?name=SwallowKit');
-      const data = await response.json();
-      if (!response.ok) {
-        throw new Error(data.error || \`Server error: \${response.status}\`);
-      }
-      setMessage(data.message);
-      setGreetingStatus('success');
-    } catch (error) {
-      setMessage(error instanceof Error ? error.message : 'Failed to connect to Azure Functions');
-      setGreetingStatus('error');
-    }
-  };
-
-  return (
-    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-50 dark:from-gray-900 dark:to-gray-800">
-      <div className="container mx-auto px-4 py-12">
-        <header className="text-center mb-16">
-          <h1 className="text-5xl font-bold text-gray-800 dark:text-white mb-4">
-            Welcome to SwallowKit
-          </h1>
-          <p className="text-xl text-gray-600 dark:text-gray-400">
-            Next.js on Azure Static Web Apps + Functions + Cosmos DB — Zod schema sharing
-          </p>
-        </header>
-
-        {/* Connection Test */}
-        <section className="max-w-2xl mx-auto mb-12">
-          <div className="bg-white dark:bg-gray-800 rounded-xl p-8 border border-gray-200 dark:border-gray-700">
-            <h2 className="text-2xl font-semibold mb-4 text-gray-900 dark:text-gray-100">
-              Test BFF → Functions Connection
-            </h2>
-            <button
-              onClick={testConnection}
-              disabled={greetingStatus === 'loading'}
-              className="px-6 py-3 bg-blue-600 hover:bg-blue-700 disabled:bg-gray-400 text-white rounded-lg font-medium transition-colors"
-            >
-              {greetingStatus === 'loading' ? 'Testing...' : 'Test Connection'}
-            </button>
-            {greetingStatus === 'success' && (
-              <div className="mt-4 p-4 bg-green-50 dark:bg-green-900/20 border border-green-200 dark:border-green-800 rounded-lg">
-                <p className="text-green-800 dark:text-green-200 font-medium">✅ Connection successful!</p>
-                <p className="text-green-700 dark:text-green-300 text-sm mt-1">{message}</p>
-              </div>
-            )}
-            {greetingStatus === 'error' && (
-              <div className="mt-4 p-4 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg">
-                <p className="text-red-800 dark:text-red-200 font-medium">❌ Connection failed</p>
-                <p className="text-red-700 dark:text-red-300 text-sm mt-1">{message}</p>
-              </div>
-            )}
-          </div>
-        </section>
-
-        {/* Scaffolded Models Menu */}
-        {scaffoldConfig.models.length > 0 ? (
-          <section className="max-w-6xl mx-auto">
-            <h2 className="text-3xl font-bold mb-8 text-gray-900 dark:text-gray-100">Your Models</h2>
-            <div className="grid gap-6 grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
-              {scaffoldConfig.models.map((model) => (
-                <a
-                  key={model.name}
-                  href={model.path}
-                  className="block p-8 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-xl hover:shadow-lg hover:border-blue-400 dark:hover:border-blue-600 transition-all"
-                >
-                  <h3 className="text-2xl font-semibold mb-2 text-gray-900 dark:text-gray-100">{model.label}</h3>
-                  <p className="text-gray-600 dark:text-gray-400">Manage {model.label.toLowerCase()}</p>
-                </a>
-              ))}
-            </div>
-          </section>
-        ) : (
-          <section className="max-w-2xl mx-auto text-center">
-            <div className="bg-white dark:bg-gray-800 rounded-xl p-12 border border-gray-200 dark:border-gray-700">
-              <h2 className="text-2xl font-semibold mb-4 text-gray-900 dark:text-gray-100">Get Started</h2>
-              <p className="text-gray-600 dark:text-gray-400 mb-6">
-                Create your first model with Zod and generate CRUD operations automatically.
-              </p>
-              <code className="block bg-gray-100 dark:bg-gray-900 p-4 rounded text-left text-sm">
-                ${pmCmd.exec} swallowkit scaffold shared/models/your-model.ts
-              </code>
-            </div>
-          </section>
-        )}
-
-        <footer className="mt-16 text-center text-gray-600 dark:text-gray-400 text-sm">
-          <p>Built with SwallowKit</p>
-        </footer>
-      </div>
-    </div>
-  );
-}
-`;
-  
-  fs.writeFileSync(path.join(projectDir, 'app', 'page.tsx'), pageContent);
+  fs.writeFileSync(path.join(projectDir, 'app', 'page.tsx'), buildHomePage("nextjs", pm));
 
   console.log('✅ Home page created\n');
   
@@ -1796,9 +1715,8 @@ function createReadme(
   const backendScaffoldNote = backendLanguage === 'typescript'
     ? '- Azure Functions CRUD endpoints'
     : `- Azure Functions ${backendLanguageLabel} CRUD handlers\n- OpenAPI export + native-generated ${backendLanguageLabel} schema assets`;
-  const pythonUvPaths = getProjectLocalUvPaths(projectDir);
   const pythonLocalDevNote = backendLanguage === 'python'
-    ? `\n**Python local dev note**: SwallowKit uses \`uv\` for Python backends and keeps the managed Python runtime under \`${path.relative(projectDir, pythonUvPaths.pythonInstallDir)}\`. Local Azure Functions runs from \`functions/.venv\`, schema generation uses \`functions/.codegen-venv\`, and \`swallowkit dev\` bootstraps a project-local \`uv\` binary automatically when needed. Keep \`functions/requirements.txt\` and \`functions/requirements.codegen.txt\` as the dependency sources of truth.\n`
+    ? `\n**Python local dev note**: SwallowKit uses normal \`uv\` interpreter discovery and settings, including installed Python, \`.python-version\`, and \`UV_PYTHON\`. It does not pin local Python to the Azure deployment version (${DEFAULT_AZURE_PYTHON_VERSION}). Local Functions uses \`functions/.venv\` and schema generation uses \`functions/.codegen-venv\`. Existing environments are preserved; explicitly recreate them with uv when switching interpreters. A missing uv binary is bootstrapped under \`.uv/bin\` without changing PATH. Keep \`functions/requirements.txt\` and \`functions/requirements.codegen.txt\` as the dependency sources of truth.\n`
     : '';
 
   const readme = `# ${projectName}
@@ -2031,11 +1949,16 @@ function createAiAgentFiles(
   console.log('  ✅ .github/copilot-instructions.md (GitHub Copilot adapter)');
   console.log('  ✅ .github/instructions/ (path-specific instructions)');
 
+  const mcpVersion = selectInitialMcpVersion();
   fs.writeFileSync(
     path.join(projectDir, '.mcp.json'),
-    buildSwallowKitMcpProjectConfigSource(pm)
+    buildSwallowKitMcpProjectConfigSource(pm, mcpVersion.version)
+  );
+  console.log(
+    mcpVersion.version === MCP_LATEST
+      ? '  ✅ .mcp.json (project-scoped MCP bootstrap, resolves latest)'
+      : `  ✅ .mcp.json (project-scoped MCP bootstrap, pinned to ${mcpVersion.version}: ${mcpVersion.reason} Run "${runCmd} swallowkit configure-mcp" to re-select later.)`
   );
-  console.log('  ✅ .mcp.json (project-scoped MCP bootstrap)');
 
   writeWorkflowDocs(projectDir, runCmd);
   console.log('  ✅ .swallowkit/workflows/ (agent-agnostic autonomous-loop runbooks)');
@@ -2949,7 +2872,7 @@ jobs:
 ${commonSetup}      - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '${DEFAULT_AZURE_PYTHON_VERSION}'
 
       - name: Install Functions dependencies
         run: |
@@ -3138,7 +3061,7 @@ variables:
 steps:
 ${commonSetup}  - task: UsePythonVersion@0
     inputs:
-      versionSpec: '3.11'
+      versionSpec: '${DEFAULT_AZURE_PYTHON_VERSION}'
     displayName: 'Install Python'
 
   - script: |

package/src/cli/commands/migrations.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { ensureSwallowKitProject } from "../../core/config";
 import { initializeLegacyMigrations } from "../../core/operations/migration-generator";
+import { addModelContainerMigration } from "../../core/operations/model-migration";
 
 export const migrationsCommand = new Command("migrations")
   .description("Manage versioned Azure infrastructure migrations");
@@ -18,3 +19,24 @@ migrationsCommand
     console.log(`Migration baseline 0 created for project ${manifest.projectId}.`);
     console.log("Commit infra/migrations/manifest.json, then run provision with --adopt-existing --baseline 0.");
   });
+
+migrationsCommand
+  .command("add-model")
+  .description("Generate only the Cosmos DB container migration for a model (e.g. after scaffold --skip-infra)")
+  .argument("<model>", "Model file or model name")
+  .option("--dry-run", "Show the planned infra changes without writing anything", false)
+  .action(async (model: string, options: { dryRun?: boolean }) => {
+    ensureSwallowKitProject("migrations add-model");
+    const result = await addModelContainerMigration(model, { dryRun: options.dryRun });
+    for (const operation of result.operations) {
+      if (operation.action !== "skip") console.log(`  ${operation.action.padEnd(7)} ${operation.path}`);
+    }
+    if (!result.migration) {
+      console.log(`No migration needed for ${result.model}: ${result.reason}`);
+    } else if (result.operations.every((operation) => operation.action === "skip")) {
+      console.log(`Migration ${result.migration.version} for ${result.model} already exists: ${result.migration.template}`);
+    } else {
+      console.log(`${result.dryRun ? "Would create" : "Created"} migration ${result.migration.version} for ${result.model}: ${result.migration.template}`);
+      if (!result.dryRun) console.log("Commit the migration, then run provision to plan and apply it.");
+    }
+  });

package/src/cli/commands/provision.ts

@@ -1,7 +1,27 @@
 import { Command } from "commander";
 import prompts from "prompts";
 import { ensureSwallowKitProject } from "../../core/config";
-import { applyProvisionOperation, planProvisionOperation } from "../../core/operations/provision-operations";
+import {
+  INTERACTIVE_PROVISION_RETRY_HINT,
+  ProvisionPlanData,
+  executeProvisionPlan,
+  planProvisionOperation,
+} from "../../core/operations/provision-operations";
+
+export function describeProvisionAction(plan: Pick<ProvisionPlanData, "mode" | "resourceGroup" | "location" | "pendingMigrations">): string {
+  switch (plan.mode) {
+    case "bootstrap":
+      return `Resource group ${plan.resourceGroup} does not exist yet. It will be created in ${plan.location} and the infrastructure in infra/main.bicep will be deployed.`;
+    case "migrate":
+      return `${plan.pendingMigrations.length} infrastructure migration(s) will be deployed to ${plan.resourceGroup}: ${plan.pendingMigrations.map((migration) => `${migration.version}-${migration.slug}`).join(", ")}.`;
+    case "adopt":
+      return `The existing resource group ${plan.resourceGroup} will be recorded as SwallowKit baseline 0. Nothing will be deployed.`;
+    case "reconcile":
+      return `infra/main.bicep will be redeployed to ${plan.resourceGroup}. Template-managed settings may be reset.`;
+    default:
+      return `Resource group ${plan.resourceGroup}:`;
+  }
+}
 
 const PRIMARY_REGIONS = [
   { title: "Japan East (japaneast)", value: "japaneast" },
@@ -70,16 +90,17 @@ export const provisionCommand = new Command("provision")
   .option("--subscription <id>", "Azure subscription ID")
   .option("--location <region>", "Primary location for Functions and Cosmos DB")
   .option("--swa-location <region>", "Static Web App location")
-  .option("--what-if", "Include Azure what-if evidence", false)
+  .option("--what-if", "Include Azure what-if evidence in the preview", false)
   .option("--adopt-existing", "Adopt an existing untagged resource group without deploying main.bicep", false)
   .option("--baseline <version>", "Baseline version for adoption (currently 0)")
   .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
-  .option("--approve", "Apply the displayed plan without an interactive confirmation", false)
+  .option("--approve", "Run the displayed Azure commands without the confirmation prompt", false)
   .action(async (options: ProvisionCliOptions) => {
     ensureSwallowKitProject("provision");
     const locations = await resolveLocations(options);
     const baseline = options.baseline === undefined ? undefined : Number(options.baseline);
-    const plan = await planProvisionOperation({
+    // Preview in memory: the same Azure checks as the agent workflow, but no saved plan file.
+    const preview = await planProvisionOperation({
       resourceGroup: options.resourceGroup,
       subscription: options.subscription,
       location: locations.location,
@@ -88,37 +109,52 @@ export const provisionCommand = new Command("provision")
       adoptExisting: options.adoptExisting,
       baseline,
       reconcile: options.reconcile,
-    });
+    }, { persist: false });
 
-    console.log(`Provision mode: ${plan.mode}`);
-    for (const warning of plan.warnings) console.warn(`Warning: ${warning}`);
-    if (plan.pendingMigrations.length > 0) {
-      console.log(`Pending migrations: ${plan.pendingMigrations.map((migration) => `${migration.version}-${migration.slug}`).join(", ")}`);
+    for (const warning of preview.warnings) console.warn(`Warning: ${warning}`);
+
+    if (preview.mode === "offline") {
+      console.log([
+        "",
+        "❌ Azure CLI is unavailable, so the current state of Azure could not be checked. Nothing was changed in Azure.",
+        "   1. Make sure `az --version` works in this terminal (install: https://aka.ms/azure-cli).",
+        "   2. Sign in with `az login` (and `az account set --subscription <id>` if needed).",
+        "   3. Run this command again.",
+      ].join("\n"));
+      process.exitCode = 1;
+      return;
     }
-    for (const command of plan.commands) console.log(`  ${command}`);
 
-    if (plan.mode === "adoption-required") {
+    if (preview.mode === "adoption-required") {
       throw new Error('Existing resource group requires: migrations init --legacy-baseline, then provision --adopt-existing --baseline 0 --what-if.');
     }
 
+    if (preview.mode === "noop") {
+      console.log(`Resource group ${preview.resourceGroup} is already up to date. Nothing to do.`);
+      return;
+    }
+
+    console.log(`\n${describeProvisionAction(preview)}`);
+    console.log("The following Azure CLI commands will run:");
+    for (const command of preview.commands) console.log(`  ${command}`);
+
     let approved = options.approve === true;
     if (!approved) {
       if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        throw new Error("Non-interactive provision requires --approve after reviewing the plan.");
+        throw new Error("Non-interactive provision requires --approve after reviewing the commands above.");
       }
       const answer = await prompts({
         type: "confirm",
         name: "approved",
-        message: `Apply the ${plan.mode} plan?`,
+        message: "Run these Azure commands? This may create billable resources.",
         initial: false,
       });
       approved = answer.approved === true;
     }
     if (!approved) {
-      console.log("Provision cancelled.");
+      console.log("Provision cancelled. Nothing was changed in Azure.");
       return;
     }
 
-    const result = await applyProvisionOperation({ planId: plan.planId, approve: true });
-    console.log(`Provision completed (${plan.mode}). ${result.executedCommands.length} command(s) executed.`);
-  });
+    const result = await executeProvisionPlan(preview, { approve: true, retryHint: INTERACTIVE_PROVISION_RETRY_HINT });
+    console.log(`✅ Provisioning completed. ${result.executedCommands.length} Azure CLI command(s) ran.`);  });