swallowkit 1.1.2 → 2.0.0-alpha.10

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,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();