swallowkit 2.0.0-alpha.5 → 2.0.0-alpha.6

package/src/cli/commands/provision.ts

@@ -3,10 +3,15 @@ import prompts from "prompts";
 import { ensureSwallowKitProject } from "../../core/config";
 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";
 
 export function describeProvisionAction(plan: Pick<ProvisionPlanData, "mode" | "resourceGroup" | "location" | "pendingMigrations">): string {
   switch (plan.mode) {
@@ -18,6 +23,8 @@ export function describeProvisionAction(plan: Pick<ProvisionPlanData, "mode" | "
       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}:`;
   }
@@ -44,7 +51,7 @@ const SWA_REGIONS = [
 ];
 
 interface ProvisionCliOptions {
-  resourceGroup: string;
+  resourceGroup?: string;
   subscription?: string;
   location?: string;
   swaLocation?: string;
@@ -53,6 +60,34 @@ 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, `Run: ${result.runId}; 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: ${warning}`);
+  for (const diagnostic of result.diagnostics.filter((entry) => entry.failureKind || entry.outputTruncated)) {
+    lines.push(formatAzureDiagnostic(diagnostic));
+  }
+  if (result.status !== "complete") {
+    lines.push(`Check/wait: swallowkit provision --status ${result.runId} --wait-seconds 300`);
+    lines.push(`Resume after approval: swallowkit provision --resume ${result.runId} --approve`);
+    lines.push("Azure may continue after Ctrl+C or process termination. No Azure cancellation or deletion is performed.");
+  }
+  return lines.join("\n");
 }
 
 async function resolveLocations(options: ProvisionCliOptions): Promise<{ location: string; swaLocation: string }> {
@@ -86,7 +121,7 @@ async function resolveLocations(options: ProvisionCliOptions): Promise<{ locatio
 
 export const provisionCommand = new Command("provision")
   .description("Bootstrap, adopt, migrate, or explicitly reconcile Azure resources")
-  .requiredOption("-g, --resource-group <name>", "Resource group name")
+  .option("-g, --resource-group <name>", "Resource group name (required for a new preview)")
   .option("--subscription <id>", "Azure subscription ID")
   .option("--location <region>", "Primary location for Functions and Cosmos DB")
   .option("--swa-location <region>", "Static Web App location")
@@ -95,8 +130,34 @@ export const provisionCommand = new Command("provision")
   .option("--baseline <version>", "Baseline version for adoption (currently 0)")
   .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
   .option("--approve", "Run the displayed Azure commands without the confirmation prompt", false)
+  .option("--status <runId>", "Read an existing execution checkpoint and Azure deployment state without writes")
+  .option("--resume <runId>", "Resume an approved checkpoint without resubmitting attempted deployments")
+  .option("--resume-deployment <name>", "Recover an older untracked baseline deployment after verifying its template and parameters")
+  .option("--wait-seconds <seconds>", "Bounded state wait, 0-3600 seconds (default: 300; status: 0)")
   .action(async (options: ProvisionCliOptions) => {
     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) {
+      let approved = options.approve === true;
+      if (!approved && process.stdin.isTTY && process.stdout.isTTY) {
+        const answer = await prompts({ type: "confirm", name: "approved", message: "Resume the original reviewed run and finish pending steps? This requires explicit approval.", initial: false });
+        approved = answer.approved === true;
+      }
+      const result = await applyProvisionOperation({ planId: options.resume, approve: approved, waitSeconds });
+      console.log(formatProvisionResult(result));
+      if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+      return;
+    }
+    if (!options.resourceGroup) throw new MachineCommandError("invalid-arguments", "New provision previews require --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.
@@ -109,6 +170,7 @@ export const provisionCommand = new Command("provision")
       adoptExisting: options.adoptExisting,
       baseline,
       reconcile: options.reconcile,
+      resumeDeployment: options.resumeDeployment,
     }, { persist: false });
 
     for (const warning of preview.warnings) console.warn(`Warning: ${warning}`);
@@ -126,7 +188,7 @@ export const provisionCommand = new Command("provision")
     }
 
     if (preview.mode === "adoption-required") {
-      throw new Error('Existing resource group requires: migrations init --legacy-baseline, then provision --adopt-existing --baseline 0 --what-if.');
+      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") {
@@ -156,5 +218,7 @@ export const provisionCommand = new Command("provision")
       return;
     }
 
-    const result = await executeProvisionPlan(preview, { approve: true, retryHint: INTERACTIVE_PROVISION_RETRY_HINT });
-    console.log(`✅ Provisioning completed. ${result.executedCommands.length} Azure CLI command(s) ran.`);  });
+    const result = await executeProvisionPlan(preview, { approve: true, retryHint: INTERACTIVE_PROVISION_RETRY_HINT, waitSeconds });
+    console.log(formatProvisionResult(result));
+    if (result.status === "blocked" || result.status === "failed") process.exitCode = 1;
+  });

package/src/cli/index.ts

@@ -6,6 +6,7 @@ import * as path from "path";
 import { Command } from "commander";
 import { initCommand, devCommand, devSeedsCommand, scaffoldCommand, createModelCommand } from "./commands";
 import { provisionCommand } from "./commands/provision";
+import { AzureCliDiagnostic, formatAzureDiagnostic } from "../utils/azure-diagnostics";
 import { createMigrationCommand } from "./commands/create-migration";
 import { migrationsCommand } from "./commands/migrations";
 import { configureMcpCommand } from "./commands/configure-mcp";
@@ -365,7 +366,16 @@ export function formatCliError(error: unknown): string {
     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(", ")}`);
+      if (typeof details.runId === "string") lines.push(`   Run: ${details.runId}`);
+      if (details.deployment && typeof details.deployment === "object") {
+        const deployment = details.deployment as { state?: string; reference?: { name?: string; id?: string; resourceGroup?: string; subscription?: string } };
+        lines.push(`   Deployment: ${deployment.reference?.id ?? deployment.reference?.name ?? "unknown"}; state: ${deployment.state ?? "unknown"}`);
+      }
+      if (Array.isArray(details.diagnostics)) {
+        for (const diagnostic of details.diagnostics as AzureCliDiagnostic[]) lines.push(formatAzureDiagnostic(diagnostic));
+      }
     }
+    for (const action of error.nextActions ?? []) lines.push(`   Next: ${action.command} — ${action.description}`);
     return lines.join("\n");
   }
   if (error instanceof Error) {

package/src/core/operations/provision-deployment.ts

@@ -0,0 +1,167 @@
+import { runAzCliAsync } from "../../utils/azure-cli";
+import { AzureCliDiagnostic, azureCliDiagnostic, redactAzureText } from "../../utils/azure-diagnostics";
+
+export const DEPLOYMENT_QUERY = "{id:id,name:name,state:properties.provisioningState,correlationId:properties.correlationId,templateHash:properties.templateHash,timestamp:properties.timestamp,error:properties.error}";
+export const DEFAULT_PROVISION_WAIT_SECONDS = 300;
+export const MAX_PROVISION_WAIT_SECONDS = 3_600;
+
+export interface DeploymentReference {
+  subscription: string;
+  resourceGroup: string;
+  name: string;
+  id?: string;
+  correlationId?: string;
+  templateHash?: string;
+  /** Do not mistake a previous deployment under the same name for this submission. */
+  previousCorrelationId?: string;
+}
+
+export interface AzureDeploymentError {
+  code: string;
+  message: string;
+}
+
+export interface DeploymentObservation {
+  state: "Accepted" | "Running" | "Succeeded" | "Failed" | "Canceled" | "unknown";
+  reference: DeploymentReference;
+  reason?: "not-found" | "query-failed" | "invalid-response" | "identity-changed" | "not-yet-observed" | "cancelled";
+  errors: AzureDeploymentError[];
+  diagnostic: AzureCliDiagnostic;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+export function extractAzureErrors(value: unknown, secretValues: readonly string[] = []): AzureDeploymentError[] {
+  const result: AzureDeploymentError[] = [];
+  const visit = (entry: unknown, depth: number) => {
+    if (depth > 8 || result.length >= 20) return;
+    if (typeof entry === "string") {
+      try { visit(JSON.parse(entry), depth + 1); } catch { /* Only structured Azure errors are projected. */ }
+      return;
+    }
+    const item = record(entry);
+    if (!item) return;
+    if (typeof item.code === "string" && typeof item.message === "string") {
+      result.push({ code: redactAzureText(item.code, secretValues).slice(0, 200), message: redactAzureText(item.message, secretValues).slice(0, 2_000) });
+    }
+    if (item.error) visit(item.error, depth + 1);
+    if (Array.isArray(item.details)) item.details.forEach((detail) => visit(detail, depth + 1));
+  };
+  visit(value, 0);
+  return result;
+}
+
+export function deploymentId(reference: DeploymentReference): string {
+  return reference.id ?? `/subscriptions/${reference.subscription}/resourceGroups/${reference.resourceGroup}/providers/Microsoft.Resources/deployments/${reference.name}`;
+}
+
+export async function queryAzureDeployment(
+  reference: DeploymentReference,
+  options: { timeoutMs?: number; signal?: AbortSignal; secretValues?: readonly string[] } = {}
+): Promise<DeploymentObservation> {
+  const result = await runAzCliAsync([
+    "deployment", "group", "show", "--name", reference.name,
+    "--resource-group", reference.resourceGroup, "--subscription", reference.subscription,
+    "--query", DEPLOYMENT_QUERY, "-o", "json",
+  ], { timeout: options.timeoutMs ?? 30_000, signal: options.signal });
+  const diagnostic = azureCliDiagnostic(result, "deployment-state", options.secretValues);
+  const unknown = (reason: DeploymentObservation["reason"]): DeploymentObservation => ({
+    state: "unknown", reference, reason, errors: [], diagnostic,
+  });
+  if (result.status !== 0 || result.failureKind) {
+    if (result.failureKind === "cancelled") return unknown("cancelled");
+    return unknown(/DeploymentNotFound|ResourceGroupNotFound/i.test(`${result.stderr}\n${result.stdout}`) ? "not-found" : "query-failed");
+  }
+  if (result.stdoutTruncated) return unknown("invalid-response");
+  let parsed: Record<string, unknown> | null;
+  try { parsed = record(JSON.parse(result.stdout)); } catch { return unknown("invalid-response"); }
+  if (!parsed || typeof parsed.id !== "string" || typeof parsed.state !== "string" || typeof parsed.correlationId !== "string") {
+    return unknown("invalid-response");
+  }
+  if (parsed.id.toLowerCase() !== deploymentId(reference).toLowerCase()
+    || (reference.correlationId && parsed.correlationId !== reference.correlationId)
+    || (reference.templateHash && parsed.templateHash !== reference.templateHash)) {
+    return unknown("identity-changed");
+  }
+  if (reference.previousCorrelationId && parsed.correlationId === reference.previousCorrelationId) {
+    return unknown("not-yet-observed");
+  }
+  const states: Record<string, DeploymentObservation["state"]> = {
+    accepted: "Accepted", running: "Running", creating: "Running", updating: "Running",
+    succeeded: "Succeeded", failed: "Failed", canceled: "Canceled", cancelled: "Canceled",
+  };
+  const state = states[parsed.state.toLowerCase()];
+  if (!state) return unknown("invalid-response");
+  return {
+    state,
+    reference: {
+      ...reference,
+      id: parsed.id,
+      correlationId: parsed.correlationId,
+      ...(typeof parsed.templateHash === "string" ? { templateHash: parsed.templateHash } : {}),
+    },
+    errors: extractAzureErrors(parsed.error, options.secretValues),
+    diagnostic,
+  };
+}
+
+export async function waitForAzureDeployment(
+  reference: DeploymentReference,
+  options: {
+    deadline: number;
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+    onObservation?: (observation: DeploymentObservation) => void;
+    secretValues?: readonly string[];
+    queryTimeoutMs?: number;
+  }
+): Promise<DeploymentObservation> {
+  let observation: DeploymentObservation;
+  do {
+    const remaining = options.deadline - Date.now();
+    // Even when the wait budget is exhausted, one bounded read can identify an accepted submission.
+    observation = await queryAzureDeployment(reference, {
+      timeoutMs: remaining > 0 ? Math.min(options.queryTimeoutMs ?? 30_000, remaining) : options.queryTimeoutMs ?? 30_000,
+      signal: options.signal,
+      secretValues: options.secretValues,
+    });
+    if (observation.state !== "unknown") reference = observation.reference;
+    options.onObservation?.(observation);
+    if (observation.state === "Succeeded" || observation.state === "Failed" || observation.state === "Canceled") return observation;
+    if (observation.state === "unknown" && observation.reason !== "not-yet-observed" && observation.reason !== "not-found") return observation;
+    if (Date.now() >= options.deadline || options.signal?.aborted) return observation;
+    await new Promise<void>((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", done);
+        resolve();
+      };
+      const timer = setTimeout(done, Math.min(options.pollIntervalMs ?? 5_000, Math.max(options.deadline - Date.now(), 0)));
+      options.signal?.addEventListener("abort", done, { once: true });
+      if (options.signal?.aborted) done();
+    });
+  } while (!options.signal?.aborted);
+  return observation;
+}
+
+export async function queryDeploymentOperationErrors(reference: DeploymentReference, secretValues: readonly string[] = [], signal?: AbortSignal): Promise<{
+  errors: AzureDeploymentError[];
+  diagnostic: AzureCliDiagnostic;
+}> {
+  const result = await runAzCliAsync([
+    "deployment", "operation", "group", "list",
+    "--resource-group", reference.resourceGroup, "--name", reference.name, "--subscription", reference.subscription,
+    "--query", "[?properties.provisioningState=='Failed' || properties.provisioningState=='Canceled'].{error:properties.statusMessage}",
+    "-o", "json",
+  ], { timeout: 30_000, signal });
+  const errors: AzureDeploymentError[] = [];
+  if (result.status === 0 && !result.failureKind && !result.stdoutTruncated) {
+    try {
+      const parsed: unknown = JSON.parse(result.stdout);
+      if (Array.isArray(parsed)) parsed.slice(0, 20).forEach((item) => errors.push(...extractAzureErrors(item, secretValues)));
+    } catch { /* The separate diagnostic explicitly records an unreadable operations response. */ }
+  }
+  return { errors: errors.slice(0, 20), diagnostic: azureCliDiagnostic(result, "deployment-operations", secretValues) };
+}