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

package/src/cli/commands/configure-mcp.ts

@@ -0,0 +1,54 @@
+import { Command } from "commander";
+import { ensureSwallowKitProject } from "../../core/config";
+import {
+  MCP_CONFIG_PATH,
+  MCP_LATEST,
+  lookupPublishedLatestVersion,
+  readMcpConfigVersion,
+  resolveMcpPinVersion,
+  writeMcpConfigVersion,
+} from "../../core/project/mcp-config";
+import { resolveProjectSwallowKit } from "../../mcp/version-selection";
+import { parseSemver } from "../../utils/semver";
+import { getSwallowKitVersion } from "../../version";
+
+export interface ConfigureMcpResult {
+  previousVersion: string | null;
+  version: string;
+  reason: string;
+}
+
+export function configureMcp(
+  options: { version?: string; cwd?: string },
+  lookupLatest: (packageName: string) => string | null = lookupPublishedLatestVersion
+): ConfigureMcpResult {
+  const cwd = options.cwd ?? process.cwd();
+  const requested = (options.version ?? "auto").trim();
+  const previousVersion = readMcpConfigVersion(cwd);
+
+  let decision: { version: string; reason: string };
+  if (requested === "auto") {
+    const projectVersion = resolveProjectSwallowKit(cwd)?.version ?? getSwallowKitVersion();
+    decision = resolveMcpPinVersion(projectVersion, lookupLatest("swallowkit"));
+  } else if (requested === MCP_LATEST) {
+    decision = { version: MCP_LATEST, reason: "Explicitly requested latest." };
+  } else if (parseSemver(requested)) {
+    decision = { version: requested, reason: "Explicitly pinned version." };
+  } else {
+    throw new Error(`--version must be "auto", "latest", or a semantic version (got "${requested}").`);
+  }
+
+  writeMcpConfigVersion(cwd, decision.version);
+  return { previousVersion, ...decision };
+}
+
+export const configureMcpCommand = new Command("configure-mcp")
+  .description(`Select the SwallowKit MCP version used by ${MCP_CONFIG_PATH} (auto: latest unless the project is newer)`)
+  .option("--version <version>", "auto | latest | <semver>", "auto")
+  .action((options: { version?: string }) => {
+    ensureSwallowKitProject("configure-mcp");
+    const result = configureMcp({ version: options.version });
+    console.log(`${MCP_CONFIG_PATH}: SWALLOWKIT_MCP_VERSION ${result.previousVersion ?? "(unset)"} -> ${result.version}`);
+    console.log(`Reason: ${result.reason}`);
+    console.log("Restart the MCP server (or reload your agent) to apply the change.");
+  });

package/src/cli/commands/init.ts

@@ -1,4 +1,4 @@
-import * as fs from "fs";
+import * as fs from "fs";
 import * as path from "path";
 import { spawn, execSync } from "child_process";
 import prompts from "prompts";
@@ -27,6 +27,7 @@ import {
 } from "../../core/scaffold/native-schema-generator";
 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;
@@ -802,7 +803,7 @@ export function ensureNextTailwindPostcssConfig(projectDir: string): void {
 `);
 }
 
-export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm'): string {
+export function buildSwallowKitMcpProjectConfigSource(pm: PackageManager = 'pnpm', mcpVersion: string = MCP_LATEST): string {
   const { name } = getSwallowKitPackageMetadata();
   return JSON.stringify(
     {
@@ -814,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,
           },
         },
       },
@@ -824,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,
@@ -1204,7 +1214,7 @@ export async function register() {
   createAiAgentFiles(projectDir, projectName, backendLanguage, pm, frontend);
 }
 
-async function createSharedPackage(projectDir: string, projectName: string) {
+export async function createSharedPackage(projectDir: string, projectName: string) {
   console.log('📦 Creating shared workspace package for Zod models...\n');
 
   const sharedDir = path.join(projectDir, 'shared');
@@ -1244,7 +1254,7 @@ async function createSharedPackage(projectDir: string, projectName: string) {
   // shared/index.ts (empty re-export file, scaffold will add entries)
   fs.writeFileSync(
     path.join(sharedDir, 'index.ts'),
-    `// Shared Zod models — auto-managed by SwallowKit scaffold command\n// Do not edit the export list below manually\n`
+    `// Shared Zod models. SwallowKit create-model/scaffold append missing model exports.\n// You may add exports manually; existing exports and comments are preserved. No managed markers.\n`
   );
 
   // shared/.gitignore
@@ -1256,7 +1266,7 @@ async function createSharedPackage(projectDir: string, projectName: string) {
   console.log('✅ Shared package created\n');
 }
 
-async function createAzureFunctionsProject(
+export async function createAzureFunctionsProject(
   projectDir: string,
   pm: PackageManager = 'pnpm',
   backendLanguage: BackendLanguage = 'typescript'
@@ -1939,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)');

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.`);  });

package/src/cli/commands/scaffold.ts

@@ -54,6 +54,7 @@ import {
 } from "../../core/operations/file-session";
 import { generateModelContainerMigration } from "../../core/operations/migration-generator";
 import { recordSessionOperations } from "../../core/project/artifacts";
+import { updateSharedIndex } from "../../core/operations/create-model";
 
 const SCAFFOLD_GENERATOR = "scaffold";
 
@@ -62,9 +63,35 @@ interface ScaffoldOptions {
   functionsDir?: string; // Azure Functions のディレクトリ（デフォルト: "functions"）
   apiDir?: string; // BFF directory (Next.js: app/api, React: bff)
   apiOnly?: boolean; // true の場合、UI を生成しない（デフォルト: false）
+  skipInfra?: boolean; // true の場合、infra/ 配下（コンテナー migration）を変更しない
   expectedSchemaAnalysis?: SchemaAnalysisSnapshot;
 }
 
+export function buildInfraSkippedWarning(modelName: string, modelArgument: string): string {
+  return `infra-skipped: The Cosmos DB container migration for ${modelName} was not generated (--skip-infra); infra/ was left unchanged. ` +
+    `Generate it later with "swallowkit migrations add-model ${modelArgument}", or re-plan scaffold without --skip-infra.`;
+}
+
+const USER_SCOPE_FIELD = /^(user|owner|learner|member|account|customer|student|author|creator|profile|person|employee|patient)Id$/i;
+
+function isAuthenticationConfigured(authConfig: AuthConfig | undefined): boolean {
+  if (!authConfig || authConfig.provider === "none") return false;
+  return Boolean(authConfig.provider) || Object.keys(authConfig.schemes ?? {}).length > 0;
+}
+
+/** Warn when a model looks per-user (partition key or owner-like id field) but no authentication is configured. */
+export function buildUserScopedDataWarning(modelInfo: ModelInfo, authConfig: AuthConfig | undefined): string | undefined {
+  if (isAuthenticationConfigured(authConfig)) return undefined;
+  const partitionField = modelInfo.partitionKey.replace(/^\//, "");
+  const fieldNames = modelInfo.fields.filter((field) => field.type === "string" && !field.isArray).map((field) => field.name);
+  const ownerField = [partitionField, ...fieldNames].find((name) => USER_SCOPE_FIELD.test(name) && fieldNames.includes(name));
+  if (!ownerField) return undefined;
+  const reason = ownerField === partitionField ? `is the partition key and looks like a per-user owner id` : `looks like a per-user owner id`;
+  return `user-scoped-data-without-auth: ${modelInfo.name}.${ownerField} ${reason}, but authentication is not configured. ` +
+    `Generated CRUD does not scope data to a principal, so any caller can read and write every ${modelInfo.name} document. ` +
+    `Add authentication with "plan auth", restrict or remove the generated write endpoints, and add ai-authored endpoints that derive ${ownerField} from the verified principal instead of the request body.`;
+}
+
 function getMachineAwareStdio(): "inherit" | "pipe" {
   return process.env.SWALLOWKIT_MACHINE_OUTPUT === "1" ? "pipe" : "inherit";
 }
@@ -132,6 +159,17 @@ export async function scaffoldCommand(options: ScaffoldOptions) {
     session.setSchemaAnalysis(schemaAnalysis);
     console.log(`✅ Model parsed: ${modelInfo.name} (${modelInfo.schemaName})`);
 
+    // Validate policy prerequisites before any generated artifacts are written.
+    resolveAuthPolicy(modelInfo, getAuthConfig());
+    for (const configName of ["swallowkit.config.js", "swallowkit.config.json", ".swallowkitrc.json"]) {
+      session.registerInput(path.join(process.cwd(), configName));
+    }
+    const userScopeWarning = buildUserScopedDataWarning(modelInfo, getAuthConfig());
+    if (userScopeWarning) {
+      session.addWarning(userScopeWarning);
+      console.warn(`⚠️  ${userScopeWarning}`);
+    }
+
     const backendLanguage = getBackendLanguage();
     const frontend = getFrontendFramework();
     const apiDir = options.apiDir || (frontend === "react" ? "bff" : "app/api");
@@ -185,6 +223,8 @@ export async function scaffoldCommand(options: ScaffoldOptions) {
       console.log("ℹ️  --api-only skips UI generation only; Functions, BFF routes, OpenAPI, and native schema assets are still updated.");
     }
 
+    updateSharedIndex(modelPath, modelInfo.schemaName, session);
+
     // 5. Generate BFF callFunction helper
     await generateCallFunctionHelper(session, apiDir);
 
@@ -210,9 +250,15 @@ export async function scaffoldCommand(options: ScaffoldOptions) {
       await generateBFFRoutes(modelInfo, apiDir, sharedPackageName, session);
     }
 
-    // 8. Generate Cosmos DB container Bicep file (skip for connector models)
+    // 8. Generate Cosmos DB container Bicep file (skip for connector models or when infra changes are excluded)
     if (!isConnectorModel) {
-      await generateCosmosContainer(modelInfo, session);
+      if (options.skipInfra) {
+        const warning = buildInfraSkippedWarning(modelInfo.name, toKebabCase(modelInfo.name));
+        session.addWarning(warning);
+        console.warn(`\n⚠️  ${warning}`);
+      } else {
+        await generateCosmosContainer(modelInfo, session);
+      }
     }
 
     // 9. Generate UI components (unless --api-only)
@@ -294,10 +340,43 @@ function applyExternalTokenFetchToGeneratedUi(modelInfo: ModelInfo, session: Fil
 export function resolveAuthPolicy(modelInfo: ModelInfo, authConfig: AuthConfig | undefined): ModelAuthPolicy | undefined {
   // モデルに明示的な authPolicy がある場合はそれを使用
   if (modelInfo.authPolicy) {
+    if (!isAuthenticationConfigured(authConfig)) {
+      throw new MachineCommandError(
+        "auth-policy-without-auth",
+        `Model '${modelInfo.name}' declares authPolicy, but authentication is not configured. No artifacts were written. Run plan auth and apply auth before scaffolding this model.`,
+        { model: modelInfo.name },
+        "blocked",
+        [{
+          command: "swallowkit machine plan auth --provider <custom-jwt|swa|external-token>",
+          description: "Choose an authentication provider, review and apply its plan, then re-plan scaffold.",
+        }]
+      );
+    }
     const normalized = normalizeAuthConfig(authConfig);
+    const usesNamedPolicy = Boolean(modelInfo.authPolicy.policy ||
+      typeof modelInfo.authPolicy.read === "string" || typeof modelInfo.authPolicy.write === "string");
+    // Guards resolve each operation independently: a string selects the named router, an array (or
+    // the roles fallback) selects the single-provider helper. Named schemes only have the router.
+    const operationIsNamed = (selected: string | string[] | undefined) =>
+      typeof selected === "string" || (selected === undefined && Boolean(modelInfo.authPolicy!.policy));
+    const everyOperationNamed = operationIsNamed(modelInfo.authPolicy.read) && operationIsNamed(modelInfo.authPolicy.write) &&
+      !modelInfo.authPolicy.roles;
+    if (authConfig?.schemes && !authConfig.provider && !everyOperationNamed) {
+      throw new MachineCommandError(
+        "auth-policy-requires-named-policy",
+        `Model '${modelInfo.name}' declares an authPolicy whose read or write operation does not resolve to a named policy, but authentication uses named schemes. Use authPolicy = { policy: '<name>' } or name both read and write policies (role arrays are not supported with named schemes); no artifacts were written.`,
+        { model: modelInfo.name },
+        "blocked",
+        [{
+          command: "swallowkit machine inspect capabilities",
+          description: "Define a named authorization policy selecting the required schemes/roles, reference it from the model, then re-plan scaffold.",
+        }]
+      );
+    }
     for (const policyName of [modelInfo.authPolicy.policy, typeof modelInfo.authPolicy.read === 'string' ? modelInfo.authPolicy.read : undefined, typeof modelInfo.authPolicy.write === 'string' ? modelInfo.authPolicy.write : undefined].filter((value): value is string => Boolean(value))) {
       if (!normalized?.authorization.policies[policyName]) throw new Error(`Model '${modelInfo.name}' references undefined auth policy '${policyName}'. Define auth.authorization.policies.${policyName}.`);
     }
+    if (usesNamedPolicy) assertNamedSchemesConfigured(modelInfo.name, "authPolicy", authConfig);
     return modelInfo.authPolicy;
   }
 
@@ -312,12 +391,35 @@ export function resolveAuthPolicy(modelInfo: ModelInfo, authConfig: AuthConfig |
     return {}; // 空のポリシー = 認証のみ、ロール制限なし
   }
 
-  if (defaultPolicy !== 'anonymous') return { policy: defaultPolicy };
+  if (defaultPolicy !== 'anonymous') {
+    assertNamedSchemesConfigured(modelInfo.name, `auth.authorization.defaultPolicy '${defaultPolicy}'`, authConfig);
+    return { policy: defaultPolicy };
+  }
 
   // defaultPolicy が 'anonymous' なら認証不要
   return undefined;
 }
 
+/**
+ * Named authorization policies are enforced by the generated multi-scheme router and scheme-specific
+ * client contexts, which exist only for named auth.schemes. A single-provider configuration
+ * (auth.provider) has no router, so referencing a named policy would generate code that cannot build.
+ */
+function assertNamedSchemesConfigured(modelName: string, source: string, authConfig: AuthConfig | undefined): void {
+  if (Object.keys(authConfig?.schemes ?? {}).some((name) => name !== "default")) return;
+  throw new MachineCommandError(
+    "auth-named-policy-requires-named-scheme",
+    `Model '${modelName}' uses a named authorization policy via ${source}, but authentication is configured with a single auth.provider. ` +
+      `Named policies require named auth.schemes; no artifacts were written. Use role lists (authPolicy = { roles: [...] } or read/write role arrays) with auth.provider, or add a named scheme.`,
+    { model: modelName, source },
+    "blocked",
+    [{
+      command: "swallowkit machine plan auth --provider <swa|external-token|custom-jwt> --scheme <name>",
+      description: "Add a named scheme and reference it from auth.authorization.policies, or switch the model to role lists; then re-plan scaffold.",
+    }]
+  );
+}
+
 /**
  * モデルファイルのパスを解決
  */

package/src/cli/index.ts

@@ -8,6 +8,7 @@ import { initCommand, devCommand, devSeedsCommand, scaffoldCommand, createModelC
 import { provisionCommand } from "./commands/provision";
 import { createMigrationCommand } from "./commands/create-migration";
 import { migrationsCommand } from "./commands/migrations";
+import { configureMcpCommand } from "./commands/configure-mcp";
 import { addConnectorCommand } from "./commands/add-connector";
 import { addAuthCommand } from "./commands/add-auth";
 import { planScaffoldOperation } from "../core/operations/scaffold-plan";
@@ -15,6 +16,7 @@ import { inspectArtifacts } from "../core/project/artifacts";
 import { detectDrift } from "../core/project/drift";
 import { runVerify } from "../core/verify";
 import { isMachineCommand, runMachineCli } from "../machine";
+import { MachineCommandError } from "../machine/errors";
 
 const packageJsonPath = path.resolve(__dirname, "../../package.json");
 export const CLI_VERSION = JSON.parse(readFileSync(packageJsonPath, "utf8")).version as string;
@@ -140,6 +142,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
   program.addCommand(provisionCommand);
   program.addCommand(migrationsCommand);
   program.addCommand(createMigrationCommand);
+  program.addCommand(configureMcpCommand);
 
   program
     .command("create-model <names...>")
@@ -160,6 +163,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
     .option("--functions-dir <dir>", "Azure Functions directory", "functions")
     .option("--api-dir <dir>", "BFF routes directory (Next.js: app/api; React: bff)")
     .option("--api-only", "Skip UI components; still update Functions, BFF routes, OpenAPI, and native schema assets", false)
+    .option("--skip-infra", "Do not create or update anything under infra/ (generate the container migration later with migrations add-model)", false)
     .option("--dry-run", "Show planned file changes without writing anything", false)
     .action(async (model, options) => {
       if (options.dryRun) {
@@ -168,6 +172,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
           functionsDir: options.functionsDir,
           apiDir: options.apiDir,
           apiOnly: options.apiOnly,
+          skipInfra: options.skipInfra,
         });
         return;
       }
@@ -177,6 +182,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
         functionsDir: options.functionsDir,
         apiDir: options.apiDir,
         apiOnly: options.apiOnly,
+        skipInfra: options.skipInfra,
       });
     });
 
@@ -217,8 +223,8 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
 
   program
     .command("verify")
-    .description("Run verification checks (structure, drift, typecheck)")
-    .option("--checks <ids>", "Comma-separated check ids to run (structure,drift,typecheck)")
+    .description("Run verification checks (structure, drift, typecheck, backend-build)")
+    .option("--checks <ids>", "Comma-separated check ids (structure,drift,typecheck,backend-build,build,lint,test); quote CSV values in PowerShell")
     .action(async (options) => {
       await runVerifyCommand({ checks: options.checks });
     });
@@ -226,7 +232,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
   return program;
 }
 
-async function runScaffoldDryRun(options: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean }): Promise<void> {
+async function runScaffoldDryRun(options: { model: string; functionsDir?: string; apiDir?: string; apiOnly?: boolean; skipInfra?: boolean }): Promise<void> {
   console.log("🔍 Scaffold dry-run — no files will be written.\n");
 
   const plan = await planScaffoldOperation(options);
@@ -264,7 +270,7 @@ async function runScaffoldDryRun(options: { model: string; functionsDir?: string
     console.log(`⚠️  ${plan.conflicts.length} file(s) were modified after generation and would be overwritten.`);
     console.log(`   Review the conflicts, then run: swallowkit scaffold ${options.model} (or machine apply scaffold --plan ${plan.planId} --approve)`);
   } else {
-    console.log(`   Run without --dry-run to apply: swallowkit scaffold ${options.model}`);
+    console.log(`   Run without --dry-run to apply: swallowkit scaffold ${options.model}${options.skipInfra ? " --skip-infra" : ""}`);
   }
 }
 
@@ -351,9 +357,26 @@ export async function runCli(argv: string[] = process.argv): Promise<void> {
   await createProgram().parseAsync(normalizeDevCommandArgv(argv));
 }
 
+/** Human-readable error output for regular CLI commands (machine commands print JSON). */
+export function formatCliError(error: unknown): string {
+  if (error instanceof MachineCommandError) {
+    const lines = [`❌ ${error.message}`, `   (code: ${error.code})`];
+    const details = error.details as Record<string, unknown> | undefined;
+    if (details && typeof details === "object") {
+      if (typeof details.nextAction === "string") lines.push(`   Next: ${details.nextAction}`);
+      if (Array.isArray(details.changedFiles)) lines.push(`   Changed files: ${details.changedFiles.join(", ")}`);
+    }
+    return lines.join("\n");
+  }
+  if (error instanceof Error) {
+    return process.env.SWALLOWKIT_DEBUG ? String(error.stack ?? error.message) : `❌ ${error.message}`;
+  }
+  return `❌ ${String(error)}`;
+}
+
 if (require.main === module) {
   void runCli().catch((error) => {
-    console.error(error);
+    console.error(formatCliError(error));
     process.exitCode = 1;
   });
 }

package/src/core/operations/create-model.ts

@@ -1,4 +1,5 @@
 import * as path from "path";
+import * as ts from "typescript";
 import { ensureSwallowKitProject, loadConfig } from "../config";
 import { toPascalCase } from "../scaffold/model-parser";
 import { syncProjectManifest } from "../project/manifest";
@@ -90,21 +91,58 @@ export const connectorConfig = {
 `;
 }
 
-function updateSharedIndex(kebabName: string, pascalName: string, session: FileOperationSession): boolean {
+export function updateSharedIndex(modelPath: string, schemaName: string, session: FileOperationSession): boolean {
   const indexPath = path.join(process.cwd(), "shared", "index.ts");
-
-  if (!session.fileExists(indexPath)) {
-    return false;
+  session.registerInput(indexPath);
+  const content = session.fileExists(indexPath) ? session.readFile(indexPath) : "";
+  const modulePath = `./${path.relative(path.dirname(indexPath), modelPath).replace(/\\/g, "/").replace(/\.ts$/, "")}`;
+  const source = ts.createSourceFile(indexPath, content, ts.ScriptTarget.Latest, true);
+  // Text edits that turn a type-only re-export of this schema into nothing (a value export of the same
+  // name also exports its type); keeping both would be a duplicate-identifier error.
+  const edits: Array<{ start: number; end: number; text: string }> = [];
+  let hasValueExport = false;
+  for (const statement of source.statements) {
+    if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    const exportedPath = statement.moduleSpecifier.text.replace(/\.(ts|js)$/, "");
+    if (exportedPath !== modulePath) continue;
+    if (!statement.exportClause) {
+      if (!statement.isTypeOnly) hasValueExport = true;
+      continue;
+    }
+    if (!ts.isNamedExports(statement.exportClause)) continue;
+    const elements = statement.exportClause.elements;
+    const matches = elements.filter((element) =>
+      element.name.text === schemaName && (element.propertyName?.text ?? element.name.text) === schemaName);
+    for (const element of matches) {
+      if (!statement.isTypeOnly && !element.isTypeOnly) {
+        hasValueExport = true;
+      } else if (!statement.isTypeOnly) {
+        // export { type Todo } -> export { Todo }
+        edits.push({ start: element.getStart(source), end: element.getEnd(), text: schemaName });
+        hasValueExport = true;
+      } else if (elements.length === 1) {
+        let end = statement.getEnd();
+        if (content.slice(end, end + 2) === "\r\n") end += 2;
+        else if (content[end] === "\n") end += 1;
+        edits.push({ start: statement.getStart(source), end, text: "" });
+      } else {
+        const index = elements.indexOf(element);
+        const start = index === 0 ? element.getStart(source) : elements[index - 1].getEnd();
+        const end = index === 0 ? elements[index + 1].getStart(source) : element.getEnd();
+        edits.push({ start, end, text: "" });
+      }
+    }
   }
-
-  const content = session.readFile(indexPath);
-  const exportLine = `export { ${pascalName} } from './models/${kebabName}';`;
-
-  if (content.includes(exportLine)) {
-    return false;
+  let updated = content;
+  for (const edit of edits.sort((left, right) => right.start - left.start)) {
+    updated = `${updated.slice(0, edit.start)}${edit.text}${updated.slice(edit.end)}`;
   }
-
-  session.writeFile(indexPath, `${content}${exportLine}\n`, {
+  if (hasValueExport && updated === content) return false;
+  if (!hasValueExport) {
+    const exportLine = `export { ${schemaName} } from '${modulePath}';`;
+    updated = `${updated}${updated && !updated.endsWith("\n") ? "\n" : ""}${exportLine}\n`;
+  }
+  session.writeFile(indexPath, updated, {
     ownership: "extension-point",
     generator: CREATE_MODEL_GENERATOR,
   });
@@ -172,7 +210,7 @@ export async function createModelOperation(options: CreateModelOperationOptions)
     });
     createdFiles.push(filePath.replace(/\\/g, "/"));
 
-    if (updateSharedIndex(kebabName, pascalName, session)) {
+    if (updateSharedIndex(resolveFromRoot(filePath), pascalName, session)) {
       updatedIndex = true;
     }
   }