swallowkit 2.0.0-alpha.1 → 2.0.0-alpha.10

package/src/cli/commands/provision.ts

@@ -1,7 +1,142 @@
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import prompts from "prompts";
 import { ensureSwallowKitProject } from "../../core/config";
-import { applyProvisionOperation, planProvisionOperation } from "../../core/operations/provision-operations";
+import {
+  INTERACTIVE_PROVISION_RETRY_HINT,
+  ApplyProvisionResult,
+  ProvisionPlanData,
+  applyProvisionOperation,
+  executeProvisionPlan,
+  inspectProvisionOperation,
+  planProvisionOperation,
+} from "../../core/operations/provision-operations";
+import { MachineCommandError } from "../../machine/errors";
+import { formatAzureDiagnostic } from "../../utils/azure-diagnostics";
+import { runAzCliAsync } from "../../utils/azure-cli";
+
+function humanProvisionMessage(message: string): string {
+  return message
+    .replace(/swallowkit machine inspect provision --plan/g, "swallowkit provision --status")
+    .replace(/swallowkit machine apply provision --plan/g, "swallowkit provision --resume")
+    .replace(/plan provision/g, "swallowkit provision")
+    .replace(/\b[Pp]lan\b/g, "Execution")
+    .replace(/preview/g, "deployment preparation")
+    .replace(/after approval/g, "")
+    .replace(/--approve/g, "")
+    .replace(/ {2,}/g, " ");
+}
+
+export function formatProvisionError(error: unknown): string {
+  if (!(error instanceof MachineCommandError)) return error instanceof Error ? error.message : String(error);
+  const message = error.code === "azure-deployment-failed" ? error.message : humanProvisionMessage(error.message);
+  const lines = [...new Set(message.split("\n"))];
+  const details = error.details as Partial<ApplyProvisionResult> | undefined;
+  if (details?.deployment) {
+    lines.push(`Deployment: ${details.deployment.reference.name}; state: ${details.deployment.state}`);
+  }
+  for (const diagnostic of details?.diagnostics ?? []) {
+    if (diagnostic.failureKind || diagnostic.outputTruncated) lines.push(formatAzureDiagnostic(diagnostic));
+  }
+  const runId = details?.runId;
+  if (runId) {
+    lines.push(`Check: swallowkit provision --status ${runId}`);
+    if (error.code !== "azure-deployment-failed") lines.push(`Resume: swallowkit provision --resume ${runId}`);
+    else lines.push("Azure reported a terminal failure. Resuming only observes that failed deployment; correct its cause before explicitly deploying again.");
+  } else {
+    for (const action of error.nextActions ?? []) {
+      const command = humanProvisionMessage(action.command);
+      if (!command.includes("machine ")) lines.push(command);
+    }
+  }
+  return lines.join("\n");
+}
+
+async function printProvisionSetup(result: ApplyProvisionResult): Promise<void> {
+  if (!result.deployment || result.status !== "complete") return;
+  const reference = result.deployment.reference;
+  const fields = ["staticWebAppName", "staticWebAppUrl", "functionsAppName", "functionsAppUrl", "cosmosDbAccountName", "cosmosDatabaseName"] as const;
+  let outputs: Record<string, unknown>;
+  try {
+    const response = await runAzCliAsync(
+      [
+        "deployment",
+        "group",
+        "show",
+        "--name",
+        reference.name.startsWith("swallowkit-migration-") ? "swallowkit-baseline" : reference.name,
+        "--resource-group",
+        reference.resourceGroup,
+        "--subscription",
+        reference.subscription,
+        "--query",
+        `{${fields.map((field) => `${field}:properties.outputs.${field}.value`).join(",")}}`,
+        "-o",
+        "json",
+      ],
+      { timeout: 30_000 }
+    );
+    if (response.status !== 0 || response.failureKind || response.stdoutTruncated) throw new Error("Output query did not complete.");
+    const parsed: unknown = JSON.parse(response.stdout);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Invalid resource output.");
+    outputs = parsed as Record<string, unknown>;
+  } catch {
+    console.warn(
+      "Deployment succeeded, but resource information could not be read. Inspect the deployment's named outputs in Azure Portal; do not redeploy just to retrieve them."
+    );
+    return;
+  }
+  console.log("\nResource information:");
+  for (const field of fields) {
+    if (typeof outputs[field] === "string") console.log(`  ${field}: ${outputs[field]}`);
+  }
+  const swaName = typeof outputs.staticWebAppName === "string" ? outputs.staticWebAppName : "<swa-name>";
+  const functionsAppName = typeof outputs.functionsAppName === "string" ? outputs.functionsAppName : "<functions-app-name>";
+  const target = ["--resource-group", reference.resourceGroup, "--subscription", reference.subscription];
+  const swaTokenArgs = ["staticwebapp", "secrets", "list", "--name", swaName, ...target, "--query", "properties.apiKey", "-o", "tsv"];
+  const publishProfileArgs = ["webapp", "deployment", "list-publishing-profiles", "--name", functionsAppName, ...target, "--xml"];
+
+  console.log("\nCI/CD settings (save these as secrets in GitHub Actions or Azure Pipelines):\n");
+  console.log("  [AZURE_STATIC_WEB_APPS_API_TOKEN]");
+  console.log(await readCiCdSecret(swaTokenArgs, typeof outputs.staticWebAppName === "string"));
+  console.log("  [AZURE_FUNCTIONAPP_NAME]");
+  console.log(`    ${functionsAppName}\n`);
+  console.log("  [AZURE_FUNCTIONAPP_PUBLISH_PROFILE]");
+  console.log(await readCiCdSecret(publishProfileArgs, typeof outputs.functionsAppName === "string"));
+  console.log("  These values are shown only in this terminal; SwallowKit does not store them. Treat them as secrets.");
+  console.log("  Next: configure your CI/CD pipeline and manually trigger the first deployment (later pushes deploy automatically).");
+}
+
+// Reads a CI/CD credential for display in the human terminal only. The value is
+// never written to checkpoints, the ledger, or machine/MCP responses.
+async function readCiCdSecret(args: string[], resourceKnown: boolean): Promise<string> {
+  const manual = `    Run manually: az ${args.map((arg) => (/[\s"]/.test(arg) ? `"${arg}"` : arg)).join(" ")}\n`;
+  if (!resourceKnown) return `    ⚠️ The resource name was not in the deployment outputs.\n${manual}`;
+  try {
+    const response = await runAzCliAsync(args, { timeout: 60_000 });
+    const value = response.stdout.trim();
+    if (response.status === 0 && !response.failureKind && !response.stdoutTruncated && value) return `    ${value}\n`;
+  } catch {
+    // Fall through to the manual command; deployment itself already succeeded.
+  }
+  return `    ⚠️ Could not retrieve automatically.\n${manual}`;
+}
+
+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.`;
+    case "recover":
+      return `The existing baseline deployment in ${plan.resourceGroup} will be observed and its migration tag/ledger completed after Azure Succeeded. Bicep will not be submitted again.`;
+    default:
+      return `Resource group ${plan.resourceGroup}:`;
+  }
+}
 
 const PRIMARY_REGIONS = [
   { title: "Japan East (japaneast)", value: "japaneast" },
@@ -24,7 +159,7 @@ const SWA_REGIONS = [
 ];
 
 interface ProvisionCliOptions {
-  resourceGroup: string;
+  resourceGroup?: string;
   subscription?: string;
   location?: string;
   swaLocation?: string;
@@ -33,6 +168,40 @@ interface ProvisionCliOptions {
   baseline?: string;
   reconcile?: boolean;
   approve?: boolean;
+  resume?: string;
+  status?: string;
+  resumeDeployment?: string;
+  waitSeconds?: string;
+}
+
+export function formatProvisionResult(result: ApplyProvisionResult): string {
+  const outcome =
+    result.outcome === "succeeded"
+      ? "✅ Provisioning completed, including migration tags and the local ledger."
+      : result.outcome === "in-progress"
+        ? "⏳ Azure deployment is still in progress. The local wait ended; this is not an Azure failure."
+        : result.outcome === "partial"
+          ? "⚠️ Provisioning is partially complete. Finish migration bookkeeping from the checkpoint; do not redeploy the baseline."
+          : result.outcome === "failed"
+            ? "❌ Azure deployment reached a failed/cancelled terminal state."
+            : "⚠️ Azure deployment result is unknown. A local az interruption does not prove an Azure failure.";
+  const lines = [outcome, `Resource group: ${result.resourceGroup}`];
+  if (result.deployment) {
+    const reference = result.deployment.reference;
+    lines.push(`Deployment: ${reference.name}; subscription: ${reference.subscription}; state: ${result.deployment.state}${reference.id ? `; ID: ${reference.id}` : ""}`);
+    for (const error of result.deployment.errors) lines.push(`${error.code}: ${error.message}`);
+  }
+  for (const warning of result.warnings) lines.push(`Warning: ${humanProvisionMessage(warning)}`);
+  for (const diagnostic of result.diagnostics.filter((entry) => entry.failureKind || entry.outputTruncated)) {
+    lines.push(formatAzureDiagnostic(diagnostic));
+  }
+  if (result.status !== "complete") {
+    lines.push(`Check status: swallowkit provision --status ${result.runId}`);
+    if (result.outcome !== "failed") lines.push(`Resume and wait until completion: swallowkit provision --resume ${result.runId}`);
+    if (result.outcome !== "failed") lines.push("Azure may continue after Ctrl+C or process termination. No Azure cancellation or deletion is performed.");
+    else lines.push("Azure reported a terminal failure. Correct its cause before explicitly deploying again; resuming does not repair a failed deployment.");
+  }
+  return lines.join("\n");
 }
 
 async function resolveLocations(options: ProvisionCliOptions): Promise<{ location: string; swaLocation: string }> {
@@ -64,61 +233,130 @@ async function resolveLocations(options: ProvisionCliOptions): Promise<{ locatio
   return { location, swaLocation };
 }
 
-export const provisionCommand = new Command("provision")
-  .description("Bootstrap, adopt, migrate, or explicitly reconcile Azure resources")
-  .requiredOption("-g, --resource-group <name>", "Resource group name")
-  .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("--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)
-  .action(async (options: ProvisionCliOptions) => {
-    ensureSwallowKitProject("provision");
-    const locations = await resolveLocations(options);
-    const baseline = options.baseline === undefined ? undefined : Number(options.baseline);
-    const plan = await planProvisionOperation({
-      resourceGroup: options.resourceGroup,
-      subscription: options.subscription,
-      location: locations.location,
-      swaLocation: locations.swaLocation,
-      whatIf: options.whatIf,
-      adoptExisting: options.adoptExisting,
-      baseline,
-      reconcile: options.reconcile,
-    });
+export function createProvisionCommand(): Command {
+  return new Command("provision")
+    .description("Deploy Azure infrastructure and show resource information and CI/CD setup")
+    .option("-g, --resource-group <name>", "Resource group name (required for deployment)")
+    .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", "Check Azure what-if before deployment", 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)
+    .addOption(new Option("--approve", "Compatibility option; invoking provision already requests execution").hideHelp())
+    .option("--status <runId>", "Read an existing execution checkpoint and Azure deployment state without writes")
+    .option("--resume <runId>", "Continue the original execution without resubmitting attempted deployments")
+    .option("--resume-deployment <name>", "Recover an older untracked baseline deployment after verifying its template and parameters")
+    .addOption(new Option("--wait-seconds <seconds>", "Optional limit on waiting, 0-3600 seconds (default: wait until Azure finishes; status: 0)").hideHelp())
+    .action(async (options: ProvisionCliOptions) => {
+      try {
+        ensureSwallowKitProject("provision");
+        const waitSeconds = options.waitSeconds === undefined ? undefined : Number(options.waitSeconds);
+        if (
+          (options.resume && options.status) ||
+          ((options.resume || options.status) &&
+            (options.resourceGroup ||
+              options.resumeDeployment ||
+              options.reconcile ||
+              options.adoptExisting ||
+              options.subscription ||
+              options.location ||
+              options.swaLocation ||
+              options.whatIf ||
+              options.baseline !== undefined))
+        ) {
+          throw new MachineCommandError(
+            "invalid-arguments",
+            "Use --status or --resume with the checkpoint ID alone; its original Azure target and reviewed files are preserved.",
+            undefined,
+            "blocked"
+          );
+        }
+        if (options.status) {
+          const result = await inspectProvisionOperation({
+            planId: options.status,
+            waitSeconds,
+          });
+          console.log(formatProvisionResult(result));
+          if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+          return;
+        }
+        if (options.resume) {
+          const result = await applyProvisionOperation({
+            planId: options.resume,
+            approve: true,
+            waitSeconds,
+            waitUntilComplete: waitSeconds === undefined,
+          });
+          console.log(formatProvisionResult(result));
+          await printProvisionSetup(result);
+          if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+          return;
+        }
+        if (!options.resourceGroup) throw new MachineCommandError("invalid-arguments", "Provision requires --resource-group.", undefined, "blocked");
+        const locations = await resolveLocations(options);
+        const baseline = options.baseline === undefined ? undefined : Number(options.baseline);
+        // 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,
+            swaLocation: locations.swaLocation,
+            whatIf: options.whatIf,
+            adoptExisting: options.adoptExisting,
+            baseline,
+            reconcile: options.reconcile,
+            resumeDeployment: options.resumeDeployment,
+          },
+          { 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 command of plan.commands) console.log(`  ${command}`);
+        for (const warning of preview.warnings) console.warn(`Warning: ${warning}`);
 
-    if (plan.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 === "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;
+        }
+
+        if (preview.mode === "adoption-required") {
+          throw new Error(
+            "The existing resource group has no migration tag. For an interrupted baseline use --resume-deployment <original-name> to verify/observe it without redeploying. Legacy adoption applies only to a legacy manifest; do not replace an existing manifest."
+          );
+        }
+
+        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("Deploying Azure infrastructure. Azure resources may incur charges.");
+        console.log("Waiting for the Azure deployment to finish. This often takes 10-20 minutes; resource information and CI/CD settings are shown when it completes.");
 
-    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.");
+        const result = await executeProvisionPlan(preview, {
+          approve: true,
+          retryHint: INTERACTIVE_PROVISION_RETRY_HINT,
+          waitSeconds,
+          waitUntilComplete: waitSeconds === undefined,
+        });
+        console.log(formatProvisionResult(result));
+        await printProvisionSetup(result);
+        if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+      } catch (error) {
+        throw new Error(formatProvisionError(error));
       }
-      const answer = await prompts({
-        type: "confirm",
-        name: "approved",
-        message: `Apply the ${plan.mode} plan?`,
-        initial: false,
-      });
-      approved = answer.approved === true;
-    }
-    if (!approved) {
-      console.log("Provision cancelled.");
-      return;
-    }
+    });
+}
 
-    const result = await applyProvisionOperation({ planId: plan.planId, approve: true });
-    console.log(`Provision completed (${plan.mode}). ${result.executedCommands.length} command(s) executed.`);
-  });
+export const provisionCommand = createProvisionCommand();

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.",
+    }]
+  );
+}
+
 /**
  * モデルファイルのパスを解決
  */