swallowkit 1.0.2 → 1.1.0

package/src/core/project/migrations.ts

@@ -0,0 +1,274 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { MachineCommandError } from "../../machine/errors";
+import { hashContent } from "../operations/file-session";
+
+export const MIGRATION_MANIFEST_VERSION = 1;
+export const MIGRATION_MANIFEST_PATH = path.join("infra", "migrations", "manifest.json");
+
+export interface MigrationBaselineFile {
+  path: string;
+  checksum: string;
+}
+
+export interface MigrationBaseline {
+  version: 0;
+  legacy: boolean;
+  files: MigrationBaselineFile[];
+  checksum: string;
+}
+
+export interface InfrastructureMigration {
+  version: number;
+  slug: string;
+  template: string;
+  parameters?: string;
+  source: "model" | "custom";
+  sourceModel?: string;
+}
+
+export interface MigrationManifest {
+  schemaVersion: 1;
+  projectId: string;
+  baseline: MigrationBaseline;
+  migrations: InfrastructureMigration[];
+}
+
+export interface ResolvedMigration extends InfrastructureMigration {
+  checksum: string;
+  cumulativeChecksum: string;
+}
+
+export interface MigrationState {
+  schemaVersion: 1;
+  version: number;
+  checksum: string;
+}
+
+function fail(code: string, message: string, details?: unknown): never {
+  throw new MachineCommandError(code, message, details, "blocked");
+}
+
+function normalizeRelativePath(value: string): string {
+  const normalized = value.replace(/\\/g, "/");
+  if (path.posix.isAbsolute(normalized) || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+    fail("invalid-migration-manifest", `Migration path must stay inside the project: ${value}`);
+  }
+  return normalized;
+}
+
+function readRequiredFile(projectRoot: string, relativePath: string): string {
+  const normalized = normalizeRelativePath(relativePath);
+  const absolutePath = path.resolve(projectRoot, normalized);
+  const rootWithSeparator = `${path.resolve(projectRoot)}${path.sep}`;
+  if (!absolutePath.startsWith(rootWithSeparator) || !fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    fail("migration-file-not-found", `Migration file not found: ${normalized}`);
+  }
+  const realPath = fs.realpathSync(absolutePath);
+  if (!realPath.startsWith(rootWithSeparator)) {
+    fail("invalid-migration-manifest", `Migration file resolves outside the project: ${normalized}`);
+  }
+  return fs.readFileSync(absolutePath, "utf-8");
+}
+
+function checksumObject(value: unknown): string {
+  return hashContent(JSON.stringify(value));
+}
+
+export function computeBaselineChecksum(files: MigrationBaselineFile[]): string {
+  return checksumObject([...files].sort((left, right) => left.path.localeCompare(right.path)));
+}
+
+export function findBaselineDrift(manifest: MigrationManifest, projectRoot: string = process.cwd()): string[] {
+  return manifest.baseline.files
+    .filter((file) => {
+      const absolutePath = path.join(projectRoot, normalizeRelativePath(file.path));
+      return !fs.existsSync(absolutePath) || hashContent(fs.readFileSync(absolutePath, "utf-8")) !== file.checksum;
+    })
+    .map((file) => file.path);
+}
+
+export function collectLegacyBaselineFiles(projectRoot: string = process.cwd()): MigrationBaselineFile[] {
+  const infraRoot = path.join(projectRoot, "infra");
+  if (!fs.existsSync(path.join(infraRoot, "main.bicep"))) {
+    fail("infra-not-found", 'infra/main.bicep not found. Run this command from a SwallowKit project.');
+  }
+
+  const files: MigrationBaselineFile[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolutePath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "migrations") visit(absolutePath);
+      } else if (entry.isFile() && (entry.name.endsWith(".bicep") || entry.name.endsWith(".json"))) {
+        const relativePath = path.relative(projectRoot, absolutePath).replace(/\\/g, "/");
+        files.push({ path: relativePath, checksum: hashContent(fs.readFileSync(absolutePath, "utf-8")) });
+      }
+    }
+  };
+  visit(infraRoot);
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function createMigrationManifest(
+  projectRoot: string = process.cwd(),
+  options: { legacy?: boolean; projectId?: string } = {}
+): MigrationManifest {
+  const files = collectLegacyBaselineFiles(projectRoot);
+  return {
+    schemaVersion: MIGRATION_MANIFEST_VERSION,
+    projectId: options.projectId ?? crypto.randomUUID(),
+    baseline: {
+      version: 0,
+      legacy: options.legacy ?? false,
+      files,
+      checksum: computeBaselineChecksum(files),
+    },
+    migrations: [],
+  };
+}
+
+export function saveMigrationManifest(manifest: MigrationManifest, projectRoot: string = process.cwd()): void {
+  const manifestPath = path.join(projectRoot, MIGRATION_MANIFEST_PATH);
+  if (fs.existsSync(manifestPath)) {
+    fail("migration-manifest-exists", `${MIGRATION_MANIFEST_PATH} already exists.`);
+  }
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+}
+
+export function replaceMigrationManifest(manifest: MigrationManifest, projectRoot: string = process.cwd()): void {
+  validateMigrationManifest(manifest, projectRoot);
+  const manifestPath = path.join(projectRoot, MIGRATION_MANIFEST_PATH);
+  const temporaryPath = `${manifestPath}.tmp-${process.pid}`;
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+  fs.renameSync(temporaryPath, manifestPath);
+}
+
+export function loadMigrationManifest(projectRoot: string = process.cwd()): MigrationManifest {
+  const manifestPath = path.join(projectRoot, MIGRATION_MANIFEST_PATH);
+  if (!fs.existsSync(manifestPath)) {
+    fail("migration-manifest-not-found", `${MIGRATION_MANIFEST_PATH} not found. Initialize migrations first.`);
+  }
+  let manifest: MigrationManifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as MigrationManifest;
+  } catch {
+    fail("invalid-migration-manifest", `${MIGRATION_MANIFEST_PATH} is not valid JSON.`);
+  }
+  validateMigrationManifest(manifest, projectRoot);
+  return manifest;
+}
+
+export function validateMigrationManifest(manifest: MigrationManifest, projectRoot: string = process.cwd()): void {
+  if (
+    !manifest || typeof manifest !== "object" ||
+    manifest.schemaVersion !== MIGRATION_MANIFEST_VERSION ||
+    typeof manifest.projectId !== "string" || !manifest.projectId ||
+    !manifest.baseline || typeof manifest.baseline !== "object" ||
+    manifest.baseline.version !== 0 || typeof manifest.baseline.legacy !== "boolean" ||
+    !Array.isArray(manifest.baseline.files) || typeof manifest.baseline.checksum !== "string" ||
+    !Array.isArray(manifest.migrations)
+  ) {
+    fail("invalid-migration-manifest", "Unsupported or incomplete migration manifest.");
+  }
+  for (const file of manifest.baseline.files) {
+    if (!file || typeof file.path !== "string" || !/^[a-f0-9]{64}$/.test(file.checksum)) {
+      fail("invalid-migration-manifest", "Migration baseline contains an invalid file record.");
+    }
+  }
+  const baselineFiles = manifest.baseline.files.map((file) => ({
+    path: normalizeRelativePath(file.path),
+    checksum: file.checksum,
+  }));
+  if (new Set(baselineFiles.map((file) => file.path)).size !== baselineFiles.length) {
+    fail("invalid-migration-manifest", "Migration baseline contains duplicate paths.");
+  }
+  if (computeBaselineChecksum(baselineFiles) !== manifest.baseline.checksum) {
+    fail("migration-checksum-mismatch", "The migration baseline inventory was modified.");
+  }
+
+  const sorted = [...manifest.migrations].sort((left, right) => left.version - right.version);
+  for (let index = 0; index < sorted.length; index += 1) {
+    const migration = sorted[index];
+    if (!migration || !Number.isSafeInteger(migration.version) || typeof migration.slug !== "string" || typeof migration.template !== "string") {
+      fail("invalid-migration-manifest", "Migration manifest contains an invalid entry.");
+    }
+    const expectedVersion = index + 1;
+    if (migration.version !== expectedVersion || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(migration.slug)) {
+      fail("invalid-migration-manifest", `Migration versions must be contiguous and slugs must be kebab-case (expected version ${expectedVersion}).`);
+    }
+    if (migration.source !== "model" && migration.source !== "custom") {
+      fail("invalid-migration-manifest", `Migration ${migration.version} has an invalid source.`);
+    }
+    const template = normalizeRelativePath(migration.template);
+    if (!template.startsWith("infra/migrations/") || !template.endsWith(".bicep")) {
+      fail("invalid-migration-manifest", `Migration template must be a .bicep file under infra/migrations: ${template}`);
+    }
+    readRequiredFile(projectRoot, template);
+    if (migration.parameters) {
+      const parameters = normalizeRelativePath(migration.parameters);
+      if (!parameters.startsWith("infra/migrations/") || !parameters.endsWith(".json")) {
+        fail("invalid-migration-manifest", `Migration parameters must be JSON under infra/migrations: ${parameters}`);
+      }
+      readRequiredFile(projectRoot, parameters);
+    }
+  }
+}
+
+export function resolveMigrations(manifest: MigrationManifest, projectRoot: string = process.cwd()): ResolvedMigration[] {
+  validateMigrationManifest(manifest, projectRoot);
+  let cumulativeChecksum = manifest.baseline.checksum;
+  return [...manifest.migrations]
+    .sort((left, right) => left.version - right.version)
+    .map((migration) => {
+      const templateContent = readRequiredFile(projectRoot, migration.template);
+      const parametersContent = migration.parameters ? readRequiredFile(projectRoot, migration.parameters) : null;
+      const checksum = checksumObject({ migration, templateContent, parametersContent });
+      cumulativeChecksum = checksumObject({ previous: cumulativeChecksum, version: migration.version, checksum });
+      return { ...migration, checksum, cumulativeChecksum };
+    });
+}
+
+export function checksumAtVersion(manifest: MigrationManifest, version: number, projectRoot: string = process.cwd()): string {
+  if (version === 0) return manifest.baseline.checksum;
+  const migration = resolveMigrations(manifest, projectRoot).find((item) => item.version === version);
+  if (!migration) fail("migration-version-not-found", `Migration version ${version} does not exist locally.`);
+  return migration.cumulativeChecksum;
+}
+
+export function getMigrationTagKey(projectId: string): string {
+  const projectHash = crypto.createHash("sha256").update(projectId).digest("hex").slice(0, 12);
+  return `swallowkit-migration-${projectHash}`;
+}
+
+export function encodeMigrationState(state: MigrationState): string {
+  if (state.schemaVersion !== 1 || !Number.isSafeInteger(state.version) || state.version < 0 || !/^[a-f0-9]{64}$/.test(state.checksum)) {
+    fail("invalid-migration-state", "Cannot encode an invalid migration state.");
+  }
+  return `1:${state.version}:${state.checksum}`;
+}
+
+export function decodeMigrationState(value: string): MigrationState {
+  const match = /^1:(0|[1-9]\d*):([a-f0-9]{64})$/.exec(value);
+  if (!match) fail("invalid-migration-state", "The Azure migration state tag is invalid.");
+  return { schemaVersion: 1, version: Number(match[1]), checksum: match[2] };
+}
+
+export function selectPendingMigrations(
+  manifest: MigrationManifest,
+  remoteState: MigrationState,
+  projectRoot: string = process.cwd()
+): ResolvedMigration[] {
+  const latestVersion = manifest.migrations.length;
+  if (remoteState.version > latestVersion) {
+    fail("migration-state-ahead", `Azure is at migration ${remoteState.version}, but local latest is ${latestVersion}.`);
+  }
+  const expectedChecksum = checksumAtVersion(manifest, remoteState.version, projectRoot);
+  if (remoteState.checksum !== expectedChecksum) {
+    fail("migration-checksum-mismatch", `Azure migration ${remoteState.version} does not match the local history.`);
+  }
+  return resolveMigrations(manifest, projectRoot).filter((migration) => migration.version > remoteState.version);
+}

package/src/core/project/workflows.ts

@@ -187,7 +187,7 @@ Stop and ask a human when:
       "Provision Azure resources (Static Web Apps, Functions, Cosmos DB) for a SwallowKit project using the two-phase plan/apply flow with a mandatory human approval gate. Use when asked to deploy infrastructure, provision Azure, create resource groups, or run Bicep deployments.",
     content: `# Workflow: Provision Azure resources
 
-Goal: deploy the Bicep infrastructure with an explicit human approval gate.
+Goal: bootstrap Azure once, then apply only pending versioned infrastructure migrations with an explicit human approval gate.
 
 ## Rules
 
@@ -196,6 +196,8 @@ Goal: deploy the Bicep infrastructure with an explicit human approval gate.
 - Never pass \`--approve\` to \`apply provision\` unless a human explicitly
   instructed you to provision in this session.
 - Inspect infra locally first — no \`az\` calls are needed for inspection.
+- Never edit an applied migration. Create a corrective migration instead.
+- Never use \`--reconcile\` for an ordinary model or resource addition.
 
 ## Steps
 
@@ -204,8 +206,10 @@ Goal: deploy the Bicep infrastructure with an explicit human approval gate.
    - review parameters, modules, outputs, and container wiring warnings.
 2. Compute the provisioning plan (no resources are created):
    \`${runCmd} swallowkit machine plan provision -g <resource-group> --location <region>\`
-   - optional: \`--what-if\` to include an \`az deployment ... what-if\` preview.
-   - the plan lists the exact \`az\` commands that would run.
+  - the plan reports \`bootstrap\`, \`migrate\`, \`noop\`, or \`adoption-required\`.
+  - it lists only pending migrations and the exact \`az\` commands that would run.
+  - for an older untagged environment, first run \`${runCmd} swallowkit migrations init --legacy-baseline\`, then plan with \`--adopt-existing --baseline 0 --what-if\`.
+  - only intentional baseline changes use \`--reconcile --what-if\`; this can reset template-managed settings.
 3. Present the plan to the human and wait for explicit approval.
 4. Only after approval:
    \`${runCmd} swallowkit machine apply provision --plan <planId> --approve\`

package/src/core/scaffold/native-schema-generator.ts

@@ -101,6 +101,57 @@ function toPascalIdentifier(value: string): string {
   return value.charAt(0).toUpperCase() + value.slice(1);
 }
 
+interface CSharpEnumMember {
+  value: string;
+  name: string;
+}
+
+const CSHARP_RESERVED_IDENTIFIERS = new Set([
+  "abstract", "as", "base", "bool", "break", "byte", "case", "catch", "char", "checked",
+  "class", "const", "continue", "decimal", "default", "delegate", "do", "double", "else",
+  "enum", "event", "explicit", "extern", "false", "finally", "fixed", "float", "for", "foreach",
+  "goto", "if", "implicit", "in", "int", "interface", "internal", "is", "lock", "long",
+  "namespace", "new", "null", "object", "operator", "out", "override", "params", "private",
+  "protected", "public", "readonly", "ref", "return", "sbyte", "sealed", "short", "sizeof",
+  "stackalloc", "static", "string", "struct", "switch", "this", "throw", "true", "try",
+  "typeof", "uint", "ulong", "unchecked", "unsafe", "ushort", "using", "virtual", "void",
+  "volatile", "while",
+]);
+
+function toCSharpEnumMemberBase(value: string): string {
+  const encoded = Array.from(value)
+    .map((character) => {
+      if (/^[A-Za-z0-9_-]$/.test(character)) return character;
+      if (/^\s$/.test(character)) return "-";
+      return `-U${character.codePointAt(0)!.toString(16).toUpperCase()}-`;
+    })
+    .join("");
+  let identifier = toPascalIdentifier(encoded).replace(/[^A-Za-z0-9_]/g, "");
+  if (!identifier) identifier = "Value";
+  if (/^[0-9]/.test(identifier)) identifier = `Value${identifier}`;
+  if (CSHARP_RESERVED_IDENTIFIERS.has(identifier)) identifier = `Value${identifier}`;
+  return identifier;
+}
+
+function buildCSharpEnumMemberMap(values: string[], enumType: string): CSharpEnumMember[] {
+  const uniqueValues = [...new Set(values)];
+  const bases = uniqueValues.map((value) => ({ value, base: toCSharpEnumMemberBase(value) }));
+  const baseCounts = new Map<string, number>();
+  for (const entry of bases) baseCounts.set(entry.base, (baseCounts.get(entry.base) ?? 0) + 1);
+
+  return bases.map(({ value, base }) => {
+    let name = base;
+    if ((baseCounts.get(base) ?? 0) > 1 || name === enumType) {
+      name = `${base}_${Buffer.from(value, "utf-8").toString("hex").toUpperCase() || "Empty"}`;
+    }
+    return { value, name };
+  });
+}
+
+function csharpStringLiteral(value: string): string {
+  return JSON.stringify(value);
+}
+
 function isDateLikeField(field: Pick<ModelInfo["fields"][number], "name" | "type">): boolean {
   return field.type === "date" || (field.type === "string" && field.name.toLowerCase().endsWith("at"));
 }
@@ -256,23 +307,27 @@ namespace SwallowKitBackendModels.Client
 `;
 }
 
-function buildCSharpEnumMembers(values: string[]): string {
-  return values
-    .map((value, index) => `            ${toPascalIdentifier(value)} = ${index + 1}`)
+function buildCSharpEnumMembers(members: CSharpEnumMember[]): string {
+  return members
+    .map((member, index) => `            ${member.name} = ${index + 1}`)
     .join(",\n\n");
 }
 
-function buildCSharpEnumFromStringCases(field: ModelInfo["fields"][number], nullable: boolean): string {
+function buildCSharpEnumFromStringCases(
+  field: ModelInfo["fields"][number],
+  members: CSharpEnumMember[],
+  nullable: boolean
+): string {
   const enumType = `${toPascalIdentifier(field.name)}Enum`;
-  return field.enumValues!
-    .map((value) => `            if (value.Equals("${value}", StringComparison.Ordinal))\n                return ${enumType}.${toPascalIdentifier(value)};`)
+  return members
+    .map((member) => `            if (value.Equals(${csharpStringLiteral(member.value)}, StringComparison.Ordinal))\n                return ${enumType}.${member.name};`)
     .join("\n\n") + (nullable ? `\n\n            return null;` : `\n\n            throw new NotImplementedException($"Could not convert value to type ${enumType}: '{value}'");`);
 }
 
-function buildCSharpEnumToJsonCases(field: ModelInfo["fields"][number]): string {
+function buildCSharpEnumToJsonCases(field: ModelInfo["fields"][number], members: CSharpEnumMember[]): string {
   const enumType = `${toPascalIdentifier(field.name)}Enum`;
-  return field.enumValues!
-    .map((value) => `            if (value == ${enumType}.${toPascalIdentifier(value)})\n                return "${value}";`)
+  return members
+    .map((member) => `            if (value == ${enumType}.${member.name})\n                return ${csharpStringLiteral(member.value)};`)
     .join("\n\n");
 }
 
@@ -295,28 +350,29 @@ function generateLegacyCompatibleCSharpModelSource(model: ModelInfo): string {
     .filter((field) => field.enumValues?.length)
     .map((field) => {
       const enumType = `${toPascalIdentifier(field.name)}Enum`;
+      const enumMembers = buildCSharpEnumMemberMap(field.enumValues!, enumType);
       return `        /// <summary>
         /// Defines ${toPascalIdentifier(field.name)}
         /// </summary>
         [JsonConverter(typeof(JsonStringEnumConverter))]
         public enum ${enumType}
         {
-${buildCSharpEnumMembers(field.enumValues!)}
+${buildCSharpEnumMembers(enumMembers)}
         }
 
         public static ${enumType} ${enumType}FromString(string value)
         {
-${buildCSharpEnumFromStringCases(field, false)}
+${buildCSharpEnumFromStringCases(field, enumMembers, false)}
         }
 
         public static ${enumType}? ${enumType}FromStringOrDefault(string value)
         {
-${buildCSharpEnumFromStringCases(field, true)}
+${buildCSharpEnumFromStringCases(field, enumMembers, true)}
         }
 
         public static string ${enumType}ToJsonValue(${enumType}? value)
         {
-${buildCSharpEnumToJsonCases(field)}
+${buildCSharpEnumToJsonCases(field, enumMembers)}
 
             throw new NotImplementedException($"Value could not be handled: '{value}'");
         }`;

package/src/machine/index.ts

@@ -366,7 +366,10 @@ function createMachineProgram(): Command {
     .requiredOption("--swa-location <region>", "Static Web App location")
     .option("--subscription <id>", "Azure subscription GUID")
     .option("--what-if", "Run az deployment group what-if (requires az login)", false)
-    .action(async (options: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean }) => {
+    .option("--adopt-existing", "Adopt an existing untagged resource group without deploying main.bicep", false)
+    .option("--baseline <version>", "Baseline version for adoption", (value) => Number(value))
+    .option("--reconcile", "Explicitly redeploy infra/main.bicep", false)
+    .action(async (options: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean }) => {
       await handleMachineAction(
         "plan-provision",
         async () => {
@@ -377,6 +380,9 @@ function createMachineProgram(): Command {
             swaLocation: options.swaLocation,
             subscription: options.subscription,
             whatIf: options.whatIf,
+            adoptExisting: options.adoptExisting,
+            baseline: options.baseline,
+            reconcile: options.reconcile,
           });
         },
         (planData) => ({

package/src/mcp/index.ts

@@ -352,18 +352,24 @@ export function buildSwallowKitToolDefinitions(
     },
     {
       name: "swallowkit_plan_provision",
-      description: "Preflight Azure provisioning locally (Bicep analysis, az CLI availability, command preview). Never deploys. Set whatIf=true to run az what-if (requires az login). The returned plan always requires human approval.",
+      description: "Plan Azure bootstrap or pending infrastructure migrations. Existing untagged environments require explicit adoption with what-if; full main.bicep redeployment requires reconcile=true. Never deploys and always requires human approval.",
       inputSchema: z.object({
         resourceGroup: z.string(),
         location: z.string(),
         swaLocation: z.string(),
         subscription: z.string().optional(),
         whatIf: z.boolean().optional(),
+        adoptExisting: z.boolean().optional(),
+        baseline: z.number().int().nonnegative().optional(),
+        reconcile: z.boolean().optional(),
       }),
-      handler: async ({ resourceGroup, location, swaLocation, subscription, whatIf }: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean }) => {
+      handler: async ({ resourceGroup, location, swaLocation, subscription, whatIf, adoptExisting, baseline, reconcile }: { resourceGroup: string; location: string; swaLocation: string; subscription?: string; whatIf?: boolean; adoptExisting?: boolean; baseline?: number; reconcile?: boolean }) => {
         const args = ["plan", "provision", "--resource-group", resourceGroup, "--location", location, "--swa-location", swaLocation];
         if (subscription) args.push("--subscription", subscription);
         if (whatIf) args.push("--what-if");
+        if (adoptExisting) args.push("--adopt-existing");
+        if (baseline !== undefined) args.push("--baseline", String(baseline));
+        if (reconcile) args.push("--reconcile");
 
         const response = await executeMachineCommand(args, runMachineCli);
         return jsonTextContent(withOperationStatus(response));