swallowkit 1.0.2 → 1.1.0

package/src/cli/commands/scaffold.ts

@@ -50,6 +50,7 @@ import {
   getActiveFileSession,
   SchemaAnalysisSnapshot,
 } from "../../core/operations/file-session";
+import { generateModelContainerMigration } from "../../core/operations/migration-generator";
 import { recordSessionOperations } from "../../core/project/artifacts";
 
 const SCAFFOLD_GENERATOR = "scaffold";
@@ -842,155 +843,15 @@ async function generateBFFRoutes(
  * Generate Cosmos DB container Bicep file
  */
 export async function generateCosmosContainer(modelInfo: any, session: FileOperationSession = new FileOperationSession("commit")): Promise<void> {
-  console.log("\n🗄️  Generating Cosmos DB container Bicep file...");
+  console.log("\n🗄️  Generating Cosmos DB container migration...");
 
-  const modelKebab = toKebabCase(modelInfo.name);
-  const modelPascal = toPascalCase(modelInfo.name);
-  const cwd = process.cwd();
-
-  // Check if infra directory exists
-  const infraDir = path.join(cwd, "infra");
-  if (!fs.existsSync(infraDir)) {
+  const infraDir = path.join(process.cwd(), "infra");
+  if (!session.fileExists(infraDir) && !fs.existsSync(infraDir)) {
     console.log("ℹ️  infra directory not found. Skipping Cosmos DB container generation.");
     return;
   }
-
-  // Generate container Bicep file
-  const containersDir = path.join(infraDir, "containers");
-  const containerFileName = `${modelKebab}-container.bicep`;
-  const containerFilePath = path.join(containersDir, containerFileName);
-
-  const bicepContent = `@description('Cosmos DB account name')
-param cosmosAccountName string
-
-@description('Database name')
-param databaseName string
-
-@description('Container name')
-param containerName string = '${modelPascal}s'
-
-@description('Partition key path')
-param partitionKeyPath string = '${modelInfo.partitionKey}'
-
-// Reference existing Cosmos DB account
-resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' existing = {
-  name: cosmosAccountName
-}
-
-// Reference existing database
-resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2023-11-15' existing = {
-  parent: cosmosAccount
-  name: databaseName
-}
-
-// Container for ${modelPascal}
-resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2023-11-15' = {
-  parent: database
-  name: containerName
-  properties: {
-    resource: {
-      id: containerName
-      partitionKey: {
-        paths: [
-          partitionKeyPath
-        ]
-        kind: 'Hash'
-      }
-      indexingPolicy: {
-        automatic: true
-        indexingMode: 'consistent'
-        includedPaths: [
-          {
-            path: '/*'
-          }
-        ]
-        excludedPaths: [
-          {
-            path: '/_etag/?'
-          }
-        ]
-      }
-    }
-  }
-}
-
-output containerName string = container.name
-`;
-
-  // Write Bicep file (overwrite if exists)
-  session.writeFile(containerFilePath, bicepContent, { ownership: "managed", generator: SCAFFOLD_GENERATOR, sourceModel: modelInfo.name });
-  console.log(`✅ Created: ${containerFilePath}`);
-
-  // Update main.bicep to include this container module
-  await updateMainBicepWithContainer(modelKebab, modelPascal, session);
-}
-
-/**
- * Update main.bicep to include new container module
- */
-async function updateMainBicepWithContainer(modelKebab: string, modelPascal: string, session: FileOperationSession): Promise<void> {
-  const cwd = process.cwd();
-  const mainBicepPath = path.join(cwd, "infra", "main.bicep");
-
-  if (!session.fileExists(mainBicepPath)) {
-    console.log("ℹ️  main.bicep not found. Please manually add the container module.");
-    return;
-  }
-
-  let mainBicepContent = session.readFile(mainBicepPath);
-
-  // Check if container module already exists
-  const containerModuleName = `${modelPascal.charAt(0).toLowerCase()}${modelPascal.slice(1)}Container`;
-  if (mainBicepContent.includes(`module ${containerModuleName}`)) {
-    console.log(`ℹ️  Container module '${containerModuleName}' already exists in main.bicep`);
-    return;
-  }
-
-  // Find the position to insert the container module (after cosmosDb modules)
-  // Look for the end of both cosmosDb modules (FreeTier and Serverless)
-  const cosmosModulePattern = /module cosmosDbServerless ['"]modules\/cosmosdb-serverless\.bicep['"] = if \(cosmosDbMode == 'serverless'\) \{[\s\S]*?\n\}/;
-  const cosmosModuleMatch = mainBicepContent.match(cosmosModulePattern);
-  
-  if (!cosmosModuleMatch) {
-    console.log("⚠️  Could not find Cosmos DB Serverless module in main.bicep. Please manually add the container module:");
-    console.log(`\nmodule ${containerModuleName} 'containers/${modelKebab}-container.bicep' = {
-  name: '${modelKebab}-container'
-  params: {
-    cosmosAccountName: cosmosDbMode == 'freetier' ? cosmosDbFreeTier.outputs.accountName : cosmosDbServerless.outputs.accountName
-    databaseName: databaseName
-    cosmosDbMode: cosmosDbMode
-  }
-  dependsOn: [
-    cosmosDbFreeTier
-    cosmosDbServerless
-  ]
-}\n`);
-    return;
-  }
-
-  // Find the end of the cosmosDbServerless module
-  const insertPosition = cosmosModuleMatch.index! + cosmosModuleMatch[0].length;
-
-  // Create the container module declaration
-  const containerModule = `
-
-// ${modelPascal} Container
-module ${containerModuleName} 'containers/${modelKebab}-container.bicep' = {
-  name: '${modelKebab}-container'
-  params: {
-    cosmosAccountName: cosmosDbMode == 'freetier' ? cosmosDbFreeTier.outputs.accountName : cosmosDbServerless.outputs.accountName
-    databaseName: '\${projectName}Database'
-  }
-}`;
-
-  // Insert the module
-  mainBicepContent = 
-    mainBicepContent.slice(0, insertPosition) +
-    containerModule +
-    mainBicepContent.slice(insertPosition);
-
-  session.writeFile(mainBicepPath, mainBicepContent, { ownership: "extension-point", generator: SCAFFOLD_GENERATOR });
-  console.log(`✅ Added container module to main.bicep`);
+  const migration = generateModelContainerMigration(modelInfo, session);
+  console.log(`✅ Created migration ${migration.version}: ${migration.template}`);
 }
 
 /**

package/src/cli/index.ts

@@ -6,6 +6,8 @@ import * as path from "path";
 import { Command } from "commander";
 import { initCommand, devCommand, devSeedsCommand, scaffoldCommand, createModelCommand } from "./commands";
 import { provisionCommand } from "./commands/provision";
+import { createMigrationCommand } from "./commands/create-migration";
+import { migrationsCommand } from "./commands/migrations";
 import { addConnectorCommand } from "./commands/add-connector";
 import { addAuthCommand } from "./commands/add-auth";
 import { planScaffoldOperation } from "../core/operations/scaffold-plan";
@@ -133,6 +135,8 @@ export function createProgram(devCommandOverride: Command = devCommand): Command
   program.addCommand(devSeedsCommand);
 
   program.addCommand(provisionCommand);
+  program.addCommand(migrationsCommand);
+  program.addCommand(createMigrationCommand);
 
   program
     .command("create-model <names...>")

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

@@ -0,0 +1,188 @@
+import * as fs from "fs";
+import * as path from "path";
+import { MachineCommandError } from "../../machine/errors";
+import { FileOperationSession } from "./file-session";
+import {
+  InfrastructureMigration,
+  MIGRATION_MANIFEST_PATH,
+  MigrationManifest,
+  createMigrationManifest,
+  loadMigrationManifest,
+  saveMigrationManifest,
+  validateMigrationManifest,
+} from "../project/migrations";
+
+const GENERATOR = "infrastructure-migration";
+
+function normalizeSlug(value: string): string {
+  const slug = value
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+  if (!slug) {
+    throw new MachineCommandError("invalid-migration-slug", "Migration slug must contain letters or numbers.", undefined, "failed");
+  }
+  return slug;
+}
+
+function formatVersion(version: number): string {
+  return String(version).padStart(4, "0");
+}
+
+function readManifestForSession(session: FileOperationSession): MigrationManifest {
+  const manifestPath = path.join(session.rootDirectory, MIGRATION_MANIFEST_PATH);
+  if (!session.fileExists(manifestPath)) {
+    throw new MachineCommandError(
+      "migration-manifest-not-found",
+      `Migration manifest not found. Run "swallowkit migrations init --legacy-baseline" before scaffolding new models.`,
+      undefined,
+      "blocked"
+    );
+  }
+  try {
+    const manifest = JSON.parse(session.readFile(manifestPath)) as MigrationManifest;
+    validateMigrationManifest(manifest, session.rootDirectory);
+    return manifest;
+  } catch (error) {
+    if (error instanceof MachineCommandError) throw error;
+    throw new MachineCommandError("invalid-migration-manifest", `${MIGRATION_MANIFEST_PATH} is not valid JSON.`, undefined, "blocked");
+  }
+}
+
+function appendMigration(manifest: MigrationManifest, migration: InfrastructureMigration): MigrationManifest {
+  return {
+    ...manifest,
+    migrations: [...manifest.migrations, migration].sort((left, right) => left.version - right.version),
+  };
+}
+
+export function initializeLegacyMigrations(projectRoot: string = process.cwd()): MigrationManifest {
+  const manifest = createMigrationManifest(projectRoot, { legacy: true });
+  saveMigrationManifest(manifest, projectRoot);
+  return manifest;
+}
+
+export function initializeNewProjectMigrations(projectRoot: string): MigrationManifest {
+  const manifest = createMigrationManifest(projectRoot, { legacy: false });
+  saveMigrationManifest(manifest, projectRoot);
+  return manifest;
+}
+
+export function createCustomMigration(slugValue: string, projectRoot: string = process.cwd()): InfrastructureMigration {
+  const manifest = loadMigrationManifest(projectRoot);
+  const slug = normalizeSlug(slugValue);
+  if (manifest.migrations.some((migration) => migration.slug === slug)) {
+    throw new MachineCommandError("migration-exists", `Migration slug already exists: ${slug}`, undefined, "blocked");
+  }
+  const version = manifest.migrations.length + 1;
+  const directory = path.join("infra", "migrations", `${formatVersion(version)}-${slug}`);
+  const template = path.join(directory, "main.bicep").replace(/\\/g, "/");
+  const absoluteTemplate = path.join(projectRoot, template);
+  if (fs.existsSync(absoluteTemplate)) {
+    throw new MachineCommandError("migration-exists", `Migration path already exists: ${template}`, undefined, "blocked");
+  }
+  const source = `targetScope = 'resourceGroup'
+
+@description('SwallowKit project name')
+param projectName string
+
+@description('Azure resource location')
+param location string
+
+// Add only new or intentionally updated resources in this migration.
+// Reference existing resources with the Bicep "existing" keyword.
+`;
+  fs.mkdirSync(path.dirname(absoluteTemplate), { recursive: true });
+  fs.writeFileSync(absoluteTemplate, source, "utf-8");
+
+  const migration: InfrastructureMigration = { version, slug, template, source: "custom" };
+  const manifestPath = path.join(projectRoot, MIGRATION_MANIFEST_PATH);
+  fs.writeFileSync(manifestPath, `${JSON.stringify(appendMigration(manifest, migration), null, 2)}\n`, "utf-8");
+  return migration;
+}
+
+export function generateModelContainerMigration(
+  model: { name: string; partitionKey: string },
+  session: FileOperationSession = new FileOperationSession("commit")
+): InfrastructureMigration {
+  const manifest = readManifestForSession(session);
+  const existing = manifest.migrations.find((migration) => migration.source === "model" && migration.sourceModel === model.name);
+  const slug = normalizeSlug(`create-${model.name}-container`);
+  const version = existing?.version ?? manifest.migrations.length + 1;
+  const directory = path.join("infra", "migrations", `${formatVersion(version)}-${slug}`);
+  const template = (existing?.template ?? path.join(directory, "main.bicep")).replace(/\\/g, "/");
+  const containerName = `${model.name}s`;
+  const bicep = `targetScope = 'resourceGroup'
+
+@description('SwallowKit project name')
+param projectName string
+
+@description('Azure resource location')
+param location string
+
+resource cosmosAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' existing = {
+  name: 'cosmos-\${projectName}'
+}
+
+resource database 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases@2023-11-15' existing = {
+  parent: cosmosAccount
+  name: '\${projectName}Database'
+}
+
+resource container 'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers@2023-11-15' = {
+  parent: database
+  name: '${containerName}'
+  properties: {
+    resource: {
+      id: '${containerName}'
+      partitionKey: {
+        paths: [
+          '${model.partitionKey}'
+        ]
+        kind: 'Hash'
+      }
+      indexingPolicy: {
+        automatic: true
+        indexingMode: 'consistent'
+        includedPaths: [
+          { path: '/*' }
+        ]
+        excludedPaths: [
+          { path: '/_etag/?' }
+        ]
+      }
+    }
+  }
+}
+
+output containerName string = container.name
+`;
+  const absoluteTemplate = path.join(session.rootDirectory, template);
+  if (existing && session.fileExists(absoluteTemplate) && session.readFile(absoluteTemplate) !== bicep) {
+    throw new MachineCommandError(
+      "applied-migration-immutable",
+      `The generated migration for model ${model.name} differs from the current schema. Create a new explicit migration instead of changing container properties.`,
+      { version: existing.version, template },
+      "blocked"
+    );
+  }
+  session.writeFile(absoluteTemplate, bicep, { ownership: "generated-once", generator: GENERATOR, sourceModel: model.name });
+
+  const migration: InfrastructureMigration = existing ?? {
+    version,
+    slug,
+    template,
+    source: "model",
+    sourceModel: model.name,
+  };
+  if (!existing) {
+    session.writeFile(
+      path.join(session.rootDirectory, MIGRATION_MANIFEST_PATH),
+      `${JSON.stringify(appendMigration(manifest, migration), null, 2)}\n`,
+      { ownership: "metadata", generator: GENERATOR, sourceModel: model.name }
+    );
+  }
+  return migration;
+}