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

package/src/cli/index.ts

@@ -5,9 +5,11 @@ import { readFileSync } from "fs";
 import * as path from "path";
 import { Command } from "commander";
 import { initCommand, devCommand, devSeedsCommand, scaffoldCommand, createModelCommand } from "./commands";
-import { provisionCommand } from "./commands/provision";
+import { createProvisionCommand } 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";
 import { addConnectorCommand } from "./commands/add-connector";
 import { addAuthCommand } from "./commands/add-auth";
 import { planScaffoldOperation } from "../core/operations/scaffold-plan";
@@ -15,6 +17,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;
@@ -137,9 +140,10 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
   program.addCommand(devCommandOverride);
   program.addCommand(devSeedsCommand);
 
-  program.addCommand(provisionCommand);
+  program.addCommand(createProvisionCommand());
   program.addCommand(migrationsCommand);
   program.addCommand(createMigrationCommand);
+  program.addCommand(configureMcpCommand);
 
   program
     .command("create-model <names...>")
@@ -160,6 +164,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 +173,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
           functionsDir: options.functionsDir,
           apiDir: options.apiDir,
           apiOnly: options.apiOnly,
+          skipInfra: options.skipInfra,
         });
         return;
       }
@@ -177,6 +183,7 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
         functionsDir: options.functionsDir,
         apiDir: options.apiDir,
         apiOnly: options.apiOnly,
+        skipInfra: options.skipInfra,
       });
     });
 
@@ -217,8 +224,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 +233,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 +271,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 +358,35 @@ 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(", ")}`);
+      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) {
+    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;
     }
   }

package/src/core/operations/migration-generator.ts

@@ -152,6 +152,19 @@ param location string
   return migration;
 }
 
+const SUFFIXED_COSMOS_ACCOUNT_NAME = "'cosmos-${take(toLower(projectName), 30)}-${take(uniqueString(resourceGroup().id, projectName), 6)}'";
+const LEGACY_COSMOS_ACCOUNT_NAME = "'cosmos-${projectName}'";
+
+// Projects initialized before resource-group suffixes keep their original
+// account name so model migrations target the account their baseline created.
+function cosmosAccountNameExpression(session: FileOperationSession): string {
+  const mainBicep = path.join(session.rootDirectory, "infra", "main.bicep");
+  if (session.fileExists(mainBicep) && /var\s+resourceSuffix\s*=/.test(session.readFile(mainBicep))) {
+    return SUFFIXED_COSMOS_ACCOUNT_NAME;
+  }
+  return LEGACY_COSMOS_ACCOUNT_NAME;
+}
+
 export function generateModelContainerMigration(
   model: { name: string; partitionKey: string },
   session: FileOperationSession = new FileOperationSession("commit")
@@ -175,7 +188,7 @@ param projectName string
 param location string
 
 resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' existing = {
-  name: 'cosmos-\${projectName}'
+  name: ${cosmosAccountNameExpression(session)}
 }
 
 resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2023-11-15' existing = {

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

@@ -0,0 +1,52 @@
+/**
+ * Generate only the Cosmos DB container migration for a model. Used after
+ * `scaffold --skip-infra`, when infrastructure changes become allowed.
+ */
+
+import { resolveModelPath } from "../../cli/commands/scaffold";
+import { MachineCommandError } from "../../machine/errors";
+import { parseModelFile } from "../scaffold/model-parser";
+import { recordSessionOperations } from "../project/artifacts";
+import { FileOperationSession } from "./file-session";
+import { generateModelContainerMigration } from "./migration-generator";
+
+export interface ModelMigrationResult {
+  model: string;
+  dryRun: boolean;
+  migration: { version: number; template: string } | null;
+  reason?: string;
+  operations: Array<{ path: string; action: string }>;
+}
+
+export async function addModelContainerMigration(
+  modelInput: string,
+  options: { dryRun?: boolean; projectRoot?: string } = {}
+): Promise<ModelMigrationResult> {
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const modelInfo = await parseModelFile(resolveModelPath(modelInput));
+  if (modelInfo.connectorConfig) {
+    throw new MachineCommandError(
+      "connector-model-has-no-container",
+      `${modelInfo.name} uses connector ${modelInfo.connectorConfig.connector}; connector models do not get a Cosmos DB container.`,
+      undefined,
+      "failed"
+    );
+  }
+
+  const session = new FileOperationSession(options.dryRun ? "collect" : "commit", projectRoot);
+  const migration = generateModelContainerMigration(modelInfo, session);
+  if (!options.dryRun) {
+    recordSessionOperations(session.operations, {
+      schemaHash: modelInfo.semanticFingerprint,
+      sourceModel: modelInfo.name,
+    }, projectRoot);
+  }
+
+  return {
+    model: modelInfo.name,
+    dryRun: Boolean(options.dryRun),
+    migration: migration ? { version: migration.version, template: migration.template } : null,
+    ...(migration ? {} : { reason: "The container is already owned by the legacy migration baseline." }),
+    operations: session.operations.map((operation) => ({ path: operation.path, action: operation.action })),
+  };
+}

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

@@ -0,0 +1,183 @@
+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;
+/** Consecutive transient state-read failures tolerated while the human CLI waits for a terminal state. */
+export const UNBOUNDED_WAIT_TRANSIENT_RETRIES = 24;
+
+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;
+    /**
+     * Consecutive non-terminal "unknown" reads (query failure, not yet visible) to keep polling through.
+     * Required for an unbounded deadline so a missing deployment cannot be polled forever.
+     */
+    transientRetries?: number;
+  }
+): Promise<DeploymentObservation> {
+  let observation: DeploymentObservation;
+  let unknownReads = 0;
+  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") {
+      unknownReads += 1;
+      const retryable = observation.reason === "not-yet-observed" || observation.reason === "not-found"
+        || (options.transientRetries !== undefined && (observation.reason === "query-failed" || observation.reason === "invalid-response"));
+      if (!retryable) return observation;
+      if (!Number.isFinite(options.deadline) && unknownReads > (options.transientRetries ?? 0)) return observation;
+    } else {
+      unknownReads = 0;
+    }
+    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) };
+}