@supacloud/compiler 0.19.1 → 0.21.0

package/dist/cli.js

@@ -2575,9 +2575,9 @@ var init_graphql = __esm(() => {
 });
 
 // src/graphql-schema.ts
-import { mkdir as mkdir5, readFile as readFile10 } from "node:fs/promises";
+import { mkdir as mkdir5, readFile as readFile11 } from "node:fs/promises";
 import { createHash as createHash9 } from "node:crypto";
-import { dirname as dirname10, resolve as resolve14 } from "node:path";
+import { dirname as dirname10, resolve as resolve15 } from "node:path";
 async function pullGraphqlSchema(options) {
   assertGraphqlOptions({ schema: options.output });
   const endpoint = new URL(options.url);
@@ -2617,7 +2617,7 @@ async function pullGraphqlSchema(options) {
     throw new Error("GraphQL schema export failed. Verify caller grants and enable introspection only in the intended development environment.");
   }
   const schema = lexicographicSortSchema(buildClientSchema(data));
-  const path = resolve14(options.output);
+  const path = resolve15(options.output);
   const content = path.endsWith(".json") ? JSON.stringify(introspectionFromSchema(schema), null, 2) + `
 ` : `# GENERATED BY supacloud-compiler graphql-schema. DO NOT EDIT.
 # Database First: change database declarations, apply migrations, then re-export for the intended role.
@@ -2625,7 +2625,7 @@ async function pullGraphqlSchema(options) {
 `;
   let previous;
   try {
-    previous = await readFile10(path, "utf8");
+    previous = await readFile11(path, "utf8");
   } catch (error) {
     if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
       throw error;
@@ -2644,8 +2644,8 @@ var init_graphql_schema = __esm(() => {
 });
 
 // src/cli.ts
-import { resolve as resolve15 } from "node:path";
-import { readFile as readFile11 } from "node:fs/promises";
+import { resolve as resolve16 } from "node:path";
+import { readFile as readFile12 } from "node:fs/promises";
 
 // src/analyze.ts
 import { createHash as createHash3 } from "node:crypto";
@@ -11857,9 +11857,44 @@ async function buildDeliveryProject(options, delivery) {
 }
 
 // src/migrations.ts
-import { rename as rename5, readFile as readFile8, writeFile as writeFile4 } from "node:fs/promises";
-import { relative as relative11, resolve as resolve12 } from "node:path";
+import { rename as rename5, readFile as readFile9, writeFile as writeFile4, rm as rm3 } from "node:fs/promises";
+import { relative as relative11, resolve as resolve13 } from "node:path";
 import * as ts10 from "@typescript/typescript6";
+
+// src/migration-policy.ts
+import { readFile as readFile8 } from "node:fs/promises";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { resolve as resolve12 } from "node:path";
+function compilerVersion() {
+  const manifest = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8"));
+  if (!manifest || typeof manifest !== "object" || !("version" in manifest) || typeof manifest.version !== "string") {
+    throw new Error("Cannot determine executing compiler version");
+  }
+  return manifest.version;
+}
+var migrationDependencies = {
+  "@supacloud/app": "0.14.0",
+  "@supacloud/compiler": compilerVersion(),
+  "@supacloud/elysia": "0.16.0",
+  elysia: "1.4.30",
+  typescript: "7.0.2"
+};
+async function checkMigrationDependencies(rootDir) {
+  const problems = [];
+  for (const [name, expected] of Object.entries(migrationDependencies)) {
+    try {
+      const manifest = JSON.parse(await readFile8(resolve12(rootDir, "node_modules", name, "package.json"), "utf8"));
+      if (!manifest || typeof manifest !== "object" || !("name" in manifest) || manifest.name !== name || !("version" in manifest) || manifest.version !== expected) {
+        problems.push(`${name}: requires tested installed version ${expected}`);
+      }
+    } catch {
+      problems.push(`${name}: install tested version ${expected} in the project node_modules first`);
+    }
+  }
+  return problems;
+}
+
+// src/migrations.ts
 var ROUTE_DECORATORS2 = new Set(["Get", "Post", "Put", "Patch", "Delete", "Head", "Options"]);
 var MIGRATION_COMPILER_OPTIONS = {
   target: ts10.ScriptTarget.ES2022,
@@ -11961,10 +11996,10 @@ function createMigrationProgram(fileNames, sourceOverrides, rootDir) {
   const fileExists = host.fileExists.bind(host);
   const readFile = host.readFile.bind(host);
   const currentDirectory = host.getCurrentDirectory.bind(host);
-  host.fileExists = (fileName) => sourceOverrides.has(resolve12(fileName)) || fileExists(fileName);
-  host.readFile = (fileName) => sourceOverrides.get(resolve12(fileName)) ?? readFile(fileName);
+  host.fileExists = (fileName) => sourceOverrides.has(resolve13(fileName)) || fileExists(fileName);
+  host.readFile = (fileName) => sourceOverrides.get(resolve13(fileName)) ?? readFile(fileName);
   host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
-    const source = sourceOverrides.get(resolve12(fileName));
+    const source = sourceOverrides.get(resolve13(fileName));
     return source === undefined ? getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile) : ts10.createSourceFile(fileName, source, languageVersion, true);
   };
   host.getCurrentDirectory = () => rootDir ?? currentDirectory();
@@ -11990,7 +12025,7 @@ function planRouteResponseMigration(sourceFiles, checker, rootDir, includedFiles
     issues.push(issue);
   };
   for (const sourceFile of sourceFiles) {
-    const sourcePath = resolve12(sourceFile.fileName);
+    const sourcePath = resolve13(sourceFile.fileName);
     if (!includedFiles.has(sourcePath))
       continue;
     const visit = (node) => {
@@ -11998,7 +12033,7 @@ function planRouteResponseMigration(sourceFiles, checker, rootDir, includedFiles
         const options = node.arguments[1];
         const object = options && resolveStaticObjectLiteral2(options, checker);
         if (object) {
-          const objectPath = resolve12(object.getSourceFile().fileName);
+          const objectPath = resolve13(object.getSourceFile().fileName);
           const properties = routeResponseProperties(object);
           if (properties.response) {
             if (!includedFiles.has(objectPath)) {
@@ -12041,13 +12076,13 @@ function planRouteResponseMigration(sourceFiles, checker, rootDir, includedFiles
         line: lineOf2(sourceFile, response)
       });
     } else {
-      const replacements = replacementsByFile.get(resolve12(sourceFile.fileName)) ?? [];
+      const replacements = replacementsByFile.get(resolve13(sourceFile.fileName)) ?? [];
       replacements.push({
         start: response.getStart(sourceFile),
         end: response.getEnd(),
         text: `responses: { 200: ${response.initializer.getText(sourceFile)} }`
       });
-      replacementsByFile.set(resolve12(sourceFile.fileName), replacements);
+      replacementsByFile.set(resolve13(sourceFile.fileName), replacements);
     }
   }
   return { replacementsByFile, issues };
@@ -12060,7 +12095,7 @@ function applyReplacements(source, replacements) {
   return content;
 }
 function migrateRouteResponse(source, fileName) {
-  const absoluteFile = resolve12(fileName);
+  const absoluteFile = resolve13(fileName);
   const sourceOverrides = new Map([[absoluteFile, source]]);
   const program = createMigrationProgram([absoluteFile], sourceOverrides);
   const sourceFile = program.getSourceFile(absoluteFile);
@@ -12076,7 +12111,7 @@ function migrateRouteResponse(source, fileName) {
       }]
     };
   }
-  const plan = planRouteResponseMigration([sourceFile], program.getTypeChecker(), resolve12("."), new Set([absoluteFile]));
+  const plan = planRouteResponseMigration([sourceFile], program.getTypeChecker(), resolve13("."), new Set([absoluteFile]));
   const replacements = plan.replacementsByFile.get(absoluteFile) ?? [];
   return {
     changed: replacements.length > 0,
@@ -12086,7 +12121,7 @@ function migrateRouteResponse(source, fileName) {
   };
 }
 function migrateRouteResponseProject(files, rootDir, sourceByPath) {
-  const absoluteFiles = files.map((file) => resolve12(file));
+  const absoluteFiles = files.map((file) => resolve13(file));
   const program = createMigrationProgram(absoluteFiles, sourceByPath, rootDir);
   const sourceFiles = absoluteFiles.map((file) => program.getSourceFile(file)).filter((file) => file !== undefined);
   const plan = planRouteResponseMigration(sourceFiles, program.getTypeChecker(), rootDir, new Set(absoluteFiles));
@@ -12099,11 +12134,11 @@ function migrateRouteResponseProject(files, rootDir, sourceByPath) {
       changed: replacements.length > 0,
       content: applyReplacements(source, replacements),
       replacements: replacements.length,
-      issues: plan.issues.filter((issue) => resolve12(rootDir, issue.file) === file)
+      issues: plan.issues.filter((issue) => resolve13(rootDir, issue.file) === file)
     });
   }
   for (const issue of plan.issues) {
-    const path = resolve12(rootDir, issue.file);
+    const path = resolve13(rootDir, issue.file);
     if (!results.has(path) && sourceByPath.has(path)) {
       results.set(path, {
         changed: false,
@@ -12125,17 +12160,59 @@ var SUPACLOUD_MIGRATIONS = [
   }
 ];
 async function writeAtomically(path, content) {
-  const temporary = `${path}.supacloud-migrate-${process.pid}`;
-  await writeFile4(temporary, content, "utf8");
-  await rename5(temporary, path);
+  const temporary = `${path}.supacloud-migrate-${process.pid}-${crypto.randomUUID()}`;
+  try {
+    await writeFile4(temporary, content, "utf8");
+    await rename5(temporary, path);
+  } finally {
+    await rm3(temporary, { force: true });
+  }
 }
 async function migrateProject(options) {
-  const rootDir = resolve12(options.rootDir);
+  const rootDir = resolve13(options.rootDir);
+  let migrations = SUPACLOUD_MIGRATIONS;
+  const preflightIssues = [];
+  if (options.fromVersion !== undefined || options.toVersion !== undefined) {
+    migrations = [];
+    const checkpoints = new Set(SUPACLOUD_MIGRATIONS.flatMap(({ from, to }) => [from, to]));
+    let current = options.fromVersion;
+    if (!current || !options.toVersion || !checkpoints.has(current) || !checkpoints.has(options.toVersion)) {
+      preflightIssues.push({
+        code: "migration-version-unsupported",
+        file: "package.json",
+        message: `Supply both supported source-format checkpoints: ${[...checkpoints].join(", ")}`
+      });
+    } else {
+      const visited = new Set;
+      while (current !== options.toVersion) {
+        const next = SUPACLOUD_MIGRATIONS.filter((migration) => migration.from === current);
+        if (visited.has(current) || next.length !== 1 || !next[0]) {
+          preflightIssues.push({
+            code: "migration-path-unavailable",
+            file: "package.json",
+            message: `No unambiguous forward migration from ${current} to ${options.toVersion}`
+          });
+          break;
+        }
+        visited.add(current);
+        migrations.push(next[0]);
+        current = next[0].to;
+      }
+    }
+    if (preflightIssues.length === 0) {
+      for (const message of await checkMigrationDependencies(rootDir)) {
+        preflightIssues.push({ code: "migration-dependency-incompatible", file: "package.json", message });
+      }
+    }
+    if (preflightIssues.length > 0) {
+      return { write: options.write === true, migrations: [], files: [], changedFiles: [], issues: preflightIssues };
+    }
+  }
   const include = options.include ?? ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"];
   const files = ts10.sys.readDirectory(rootDir, [".ts", ".tsx", ".mts", ".cts"], ["node_modules", "dist", "generated"], include).sort();
   const results = [];
   const issues = [];
-  const pendingWrites = [];
+  const pendingWrites = new Map;
   const sourceByPath = new Map;
   const issueKeys = new Set;
   const appendIssues = (items) => {
@@ -12148,14 +12225,16 @@ async function migrateProject(options) {
     }
   };
   for (const filePath of files) {
-    sourceByPath.set(resolve12(filePath), await readFile8(filePath, "utf8"));
+    sourceByPath.set(resolve13(filePath), await readFile9(filePath, "utf8"));
   }
-  for (const migration of SUPACLOUD_MIGRATIONS) {
+  const originalSources = new Map(sourceByPath);
+  const writtenFiles = new Set;
+  for (const migration of migrations) {
     const projectResults = migration.id === "route-response-to-responses" ? migrateRouteResponseProject(files, rootDir, sourceByPath) : undefined;
     if (projectResults)
       appendIssues(projectResults.issues);
     for (const filePath of files) {
-      const absoluteFile = resolve12(filePath);
+      const absoluteFile = resolve13(filePath);
       const file = relative11(rootDir, absoluteFile) || absoluteFile;
       const before = sourceByPath.get(absoluteFile);
       if (before === undefined)
@@ -12163,7 +12242,7 @@ async function migrateProject(options) {
       const result = projectResults?.results.get(absoluteFile) ?? migration.apply(before, file);
       sourceByPath.set(absoluteFile, result.content);
       if (result.changed && result.issues.length === 0) {
-        pendingWrites.push({ path: filePath, content: result.content });
+        pendingWrites.set(absoluteFile, result.content);
       }
       if (!projectResults)
         appendIssues(result.issues);
@@ -12178,13 +12257,36 @@ async function migrateProject(options) {
     }
   }
   if (options.write && issues.length === 0) {
-    for (const pending of pendingWrites)
-      await writeAtomically(pending.path, pending.content);
+    const written = [];
+    try {
+      for (const [path, content] of pendingWrites) {
+        if (await readFile9(path, "utf8") !== originalSources.get(path)) {
+          throw new Error(`Source changed during migration: ${path}`);
+        }
+        await writeAtomically(path, content);
+        written.push(path);
+        writtenFiles.add(path);
+      }
+    } catch (error) {
+      appendIssues([{ code: "migration-write-failed", file: rootDir, message: String(error) }]);
+      for (const path of written.reverse()) {
+        try {
+          const original = originalSources.get(path);
+          if (original === undefined || await readFile9(path, "utf8") !== pendingWrites.get(path)) {
+            throw new Error("File changed after migration; refusing to overwrite concurrent edits");
+          }
+          await writeAtomically(path, original);
+          writtenFiles.delete(path);
+        } catch (rollbackError) {
+          appendIssues([{ code: "migration-rollback-failed", file: path, message: String(rollbackError) }]);
+        }
+      }
+    }
   }
-  const changedFiles = options.write && issues.length > 0 ? [] : results.filter((result) => result.changed && result.issues.length === 0).map((result) => result.file);
+  const changedFiles = options.write && issues.length > 0 ? [...writtenFiles].map((file) => relative11(rootDir, file)) : [...new Set(results.filter((result) => result.changed && result.issues.length === 0).map((result) => result.file))];
   return {
     write: options.write === true,
-    migrations: SUPACLOUD_MIGRATIONS.map(({ id, from, to, description }) => ({ id, from, to, description })),
+    migrations: migrations.map(({ id, from, to, description }) => ({ id, from, to, description })),
     files: results,
     changedFiles,
     issues
@@ -12192,8 +12294,8 @@ async function migrateProject(options) {
 }
 
 // src/openapi-tools.ts
-import { mkdir as mkdir4, readFile as readFile9, rename as rename6, unlink as unlink3, writeFile as writeFile5 } from "node:fs/promises";
-import { dirname as dirname9, resolve as resolve13 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile10, rename as rename6, unlink as unlink3, writeFile as writeFile5 } from "node:fs/promises";
+import { dirname as dirname9, resolve as resolve14 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 
 class OpenApiDocumentError extends Error {
@@ -12584,7 +12686,7 @@ function serializeOpenApiJson(document, space = 2) {
 }
 async function readOpenApiJson(path) {
   try {
-    const value = JSON.parse(await readFile9(resolve13(path), "utf8"));
+    const value = JSON.parse(await readFile10(resolve14(path), "utf8"));
     return parseOpenApiDocument(value);
   } catch (error) {
     if (error instanceof OpenApiDocumentError)
@@ -12593,11 +12695,11 @@ async function readOpenApiJson(path) {
   }
 }
 async function writeOpenApiJson(document, outputPath, space = 2) {
-  const path = resolve13(outputPath);
+  const path = resolve14(outputPath);
   const content = serializeOpenApiJson(document, space);
   await mkdir4(dirname9(path), { recursive: true });
   try {
-    if (await readFile9(path, "utf8") === content)
+    if (await readFile10(path, "utf8") === content)
       return { path, written: false };
   } catch {}
   const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
@@ -12614,7 +12716,7 @@ async function writeOpenApiJson(document, outputPath, space = 2) {
 }
 async function loadGeneratedOpenApiDocument(modulePath) {
   try {
-    const moduleUrl = pathToFileURL2(resolve13(modulePath));
+    const moduleUrl = pathToFileURL2(resolve14(modulePath));
     moduleUrl.searchParams.set("supacloud-openapi-export", "1");
     const loaded = await import(moduleUrl.href);
     if (!isRecord(loaded))
@@ -12757,6 +12859,8 @@ Options:
   --delivery <file>   plan/build-delivery: validated JSON configuration (overrides config.delivery)
   --dry-run           Preview a fix without writing the target file
   --write             Apply a fix or migration to disk (preview-only by default)
+  --from-version      Migration source-format checkpoint (requires --to-version)
+  --to-version        Migration target checkpoint; verifies installed dependencies
   --preset, -p <name> Architecture preset ('modular-monolith' | 'angular-enterprise' | 'clean-architecture')
   --help, -h          Show this help
 `);
@@ -12784,6 +12888,8 @@ async function run() {
   let query;
   let json = false;
   let dryRun = true;
+  let fromVersion;
+  let toVersion;
   let noGraphql = false;
   let projectUrl;
   let keyEnv;
@@ -12897,6 +13003,16 @@ async function run() {
       if (command === "plan")
         throw new Error("plan is read-only; --write is not supported");
       dryRun = false;
+    } else if (arg === "--from-version" || arg === "--to-version") {
+      if (command !== "migrate")
+        throw new Error(`${arg} is only supported by migrate`);
+      const value = args[++i];
+      if (!value || value.startsWith("-"))
+        throw new Error(`${arg} requires a version`);
+      if (arg === "--from-version")
+        fromVersion = value;
+      else
+        toVersion = value;
     } else if (arg === "--preset" || arg === "-p") {
       const presetArg = args[++i];
       if (!isModuleBoundaryPresetName(presetArg)) {
@@ -12927,7 +13043,7 @@ async function run() {
     const currentPath = openApiDiffPaths[1];
     if (!basePath || !currentPath)
       throw new Error("openapi-diff requires two JSON file paths");
-    const result = diffOpenApiDocuments(await readOpenApiJson(resolve15(process.cwd(), basePath)), await readOpenApiJson(resolve15(process.cwd(), currentPath)));
+    const result = diffOpenApiDocuments(await readOpenApiJson(resolve16(process.cwd(), basePath)), await readOpenApiJson(resolve16(process.cwd(), currentPath)));
     console.log(json ? JSON.stringify(result, null, 2) : formatOpenApiDiff(result));
     if (!result.ok)
       process.exitCode = 1;
@@ -12942,8 +13058,8 @@ async function run() {
     if (!modulePath || !outputPath)
       throw new Error("openapi-export requires an OpenAPI module and output path");
     const result = await exportGeneratedOpenApiJson({
-      modulePath: resolve15(process.cwd(), modulePath),
-      outputPath: resolve15(process.cwd(), outputPath),
+      modulePath: resolve16(process.cwd(), modulePath),
+      outputPath: resolve16(process.cwd(), outputPath),
       ...openApiExportSpace === undefined ? {} : { space: openApiExportSpace }
     });
     console.log(json ? JSON.stringify({ ok: true, ...result }, null, 2) : result.written ? `OpenAPI JSON written: ${result.path}` : `OpenAPI JSON matches: ${result.path}`);
@@ -12951,8 +13067,10 @@ async function run() {
   }
   if (command === "migrate") {
     const result = await migrateProject({
-      rootDir: rootDir ? resolve15(process.cwd(), rootDir) : process.cwd(),
-      write: !dryRun
+      rootDir: rootDir ? resolve16(process.cwd(), rootDir) : process.cwd(),
+      write: !dryRun,
+      ...fromVersion === undefined ? {} : { fromVersion },
+      ...toVersion === undefined ? {} : { toVersion }
     });
     if (json) {
       console.log(JSON.stringify(result, null, 2));
@@ -12961,9 +13079,9 @@ async function run() {
       const lines = [`${action} ${result.changedFiles.length} file(s)`];
       for (const file of result.files) {
         lines.push(`  ${file.file}: ${file.replacements} replacement(s)`);
-        for (const issue of file.issues)
-          lines.push(`  ${issue.file}:${issue.line ?? 0} ${issue.code}: ${issue.message}`);
       }
+      for (const issue of result.issues)
+        lines.push(`  ${issue.file}:${issue.line ?? 0} ${issue.code}: ${issue.message}`);
       if (result.changedFiles.length === 0 && result.issues.length === 0)
         lines.push("  no migrations required");
       console.log(lines.join(`
@@ -12977,8 +13095,8 @@ async function run() {
   if (checkSchema && command !== "graphql-schema")
     throw new Error("--check is only supported by graphql-schema");
   const defaults = resolveSupacloudConfig(loadedConfig, process.cwd());
-  const resolvedRoot = rootDir ? resolve15(process.cwd(), rootDir) : defaults.rootDir;
-  const resolvedOut = outDir ? resolve15(process.cwd(), outDir) : defaults.outDir;
+  const resolvedRoot = rootDir ? resolve16(process.cwd(), rootDir) : defaults.rootDir;
+  const resolvedOut = outDir ? resolve16(process.cwd(), outDir) : defaults.outDir;
   const configured = compileOptionsFromConfig({
     ...loadedConfig,
     root: resolvedRoot,
@@ -12997,7 +13115,7 @@ async function run() {
     let delivery = loadedConfig.delivery;
     if (deliveryPath !== undefined) {
       try {
-        delivery = JSON.parse(await readFile11(resolve15(process.cwd(), deliveryPath), "utf8"));
+        delivery = JSON.parse(await readFile12(resolve16(process.cwd(), deliveryPath), "utf8"));
       } catch {
         throw new DeliveryConfigurationError;
       }
@@ -13044,7 +13162,7 @@ ${item.suggestion ?? ""}`).join(`
   } else if (command === "fix") {
     if (!query)
       throw new Error("fix requires a JSON file containing one DiagnosticFix");
-    const fix = JSON.parse(await readFile11(resolve15(process.cwd(), query), "utf8"));
+    const fix = JSON.parse(await readFile12(resolve16(process.cwd(), query), "utf8"));
     const result = await applyDiagnosticFix(fix, { rootDir: resolvedRoot, dryRun });
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
   } else if (command === "compile") {

package/dist/index.js

@@ -2574,9 +2574,9 @@ var init_graphql = __esm(() => {
 });
 
 // src/graphql-schema.ts
-import { mkdir as mkdir5, readFile as readFile10 } from "node:fs/promises";
+import { mkdir as mkdir5, readFile as readFile11 } from "node:fs/promises";
 import { createHash as createHash9 } from "node:crypto";
-import { dirname as dirname10, resolve as resolve14 } from "node:path";
+import { dirname as dirname10, resolve as resolve15 } from "node:path";
 async function pullGraphqlSchema(options) {
   assertGraphqlOptions({ schema: options.output });
   const endpoint = new URL(options.url);
@@ -2616,7 +2616,7 @@ async function pullGraphqlSchema(options) {
     throw new Error("GraphQL schema export failed. Verify caller grants and enable introspection only in the intended development environment.");
   }
   const schema = lexicographicSortSchema(buildClientSchema(data));
-  const path = resolve14(options.output);
+  const path = resolve15(options.output);
   const content = path.endsWith(".json") ? JSON.stringify(introspectionFromSchema(schema), null, 2) + `
 ` : `# GENERATED BY supacloud-compiler graphql-schema. DO NOT EDIT.
 # Database First: change database declarations, apply migrations, then re-export for the intended role.
@@ -2624,7 +2624,7 @@ async function pullGraphqlSchema(options) {
 `;
   let previous;
   try {
-    previous = await readFile10(path, "utf8");
+    previous = await readFile11(path, "utf8");
   } catch (error) {
     if (!(error instanceof Error && ("code" in error) && error.code === "ENOENT"))
       throw error;
@@ -11434,9 +11434,44 @@ function watchProject(options) {
   };
 }
 // src/migrations.ts
-import { rename as rename5, readFile as readFile8, writeFile as writeFile4 } from "node:fs/promises";
-import { relative as relative10, resolve as resolve11 } from "node:path";
+import { rename as rename5, readFile as readFile9, writeFile as writeFile4, rm as rm3 } from "node:fs/promises";
+import { relative as relative10, resolve as resolve12 } from "node:path";
 import * as ts10 from "@typescript/typescript6";
+
+// src/migration-policy.ts
+import { readFile as readFile8 } from "node:fs/promises";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { resolve as resolve11 } from "node:path";
+function compilerVersion() {
+  const manifest = JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8"));
+  if (!manifest || typeof manifest !== "object" || !("version" in manifest) || typeof manifest.version !== "string") {
+    throw new Error("Cannot determine executing compiler version");
+  }
+  return manifest.version;
+}
+var migrationDependencies = {
+  "@supacloud/app": "0.14.0",
+  "@supacloud/compiler": compilerVersion(),
+  "@supacloud/elysia": "0.16.0",
+  elysia: "1.4.30",
+  typescript: "7.0.2"
+};
+async function checkMigrationDependencies(rootDir) {
+  const problems = [];
+  for (const [name, expected] of Object.entries(migrationDependencies)) {
+    try {
+      const manifest = JSON.parse(await readFile8(resolve11(rootDir, "node_modules", name, "package.json"), "utf8"));
+      if (!manifest || typeof manifest !== "object" || !("name" in manifest) || manifest.name !== name || !("version" in manifest) || manifest.version !== expected) {
+        problems.push(`${name}: requires tested installed version ${expected}`);
+      }
+    } catch {
+      problems.push(`${name}: install tested version ${expected} in the project node_modules first`);
+    }
+  }
+  return problems;
+}
+
+// src/migrations.ts
 var ROUTE_DECORATORS2 = new Set(["Get", "Post", "Put", "Patch", "Delete", "Head", "Options"]);
 var MIGRATION_COMPILER_OPTIONS = {
   target: ts10.ScriptTarget.ES2022,
@@ -11538,10 +11573,10 @@ function createMigrationProgram(fileNames, sourceOverrides, rootDir) {
   const fileExists = host.fileExists.bind(host);
   const readFile = host.readFile.bind(host);
   const currentDirectory = host.getCurrentDirectory.bind(host);
-  host.fileExists = (fileName) => sourceOverrides.has(resolve11(fileName)) || fileExists(fileName);
-  host.readFile = (fileName) => sourceOverrides.get(resolve11(fileName)) ?? readFile(fileName);
+  host.fileExists = (fileName) => sourceOverrides.has(resolve12(fileName)) || fileExists(fileName);
+  host.readFile = (fileName) => sourceOverrides.get(resolve12(fileName)) ?? readFile(fileName);
   host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
-    const source = sourceOverrides.get(resolve11(fileName));
+    const source = sourceOverrides.get(resolve12(fileName));
     return source === undefined ? getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile) : ts10.createSourceFile(fileName, source, languageVersion, true);
   };
   host.getCurrentDirectory = () => rootDir ?? currentDirectory();
@@ -11567,7 +11602,7 @@ function planRouteResponseMigration(sourceFiles, checker, rootDir, includedFiles
     issues.push(issue);
   };
   for (const sourceFile of sourceFiles) {
-    const sourcePath = resolve11(sourceFile.fileName);
+    const sourcePath = resolve12(sourceFile.fileName);
     if (!includedFiles.has(sourcePath))
       continue;
     const visit = (node) => {
@@ -11575,7 +11610,7 @@ function planRouteResponseMigration(sourceFiles, checker, rootDir, includedFiles
         const options = node.arguments[1];
         const object = options && resolveStaticObjectLiteral2(options, checker);
         if (object) {
-          const objectPath = resolve11(object.getSourceFile().fileName);
+          const objectPath = resolve12(object.getSourceFile().fileName);
           const properties = routeResponseProperties(object);
           if (properties.response) {
             if (!includedFiles.has(objectPath)) {
@@ -11618,13 +11653,13 @@ function planRouteResponseMigration(sourceFiles, checker, rootDir, includedFiles
         line: lineOf2(sourceFile, response)
       });
     } else {
-      const replacements = replacementsByFile.get(resolve11(sourceFile.fileName)) ?? [];
+      const replacements = replacementsByFile.get(resolve12(sourceFile.fileName)) ?? [];
       replacements.push({
         start: response.getStart(sourceFile),
         end: response.getEnd(),
         text: `responses: { 200: ${response.initializer.getText(sourceFile)} }`
       });
-      replacementsByFile.set(resolve11(sourceFile.fileName), replacements);
+      replacementsByFile.set(resolve12(sourceFile.fileName), replacements);
     }
   }
   return { replacementsByFile, issues };
@@ -11637,7 +11672,7 @@ function applyReplacements(source, replacements) {
   return content;
 }
 function migrateRouteResponse(source, fileName) {
-  const absoluteFile = resolve11(fileName);
+  const absoluteFile = resolve12(fileName);
   const sourceOverrides = new Map([[absoluteFile, source]]);
   const program = createMigrationProgram([absoluteFile], sourceOverrides);
   const sourceFile = program.getSourceFile(absoluteFile);
@@ -11653,7 +11688,7 @@ function migrateRouteResponse(source, fileName) {
       }]
     };
   }
-  const plan = planRouteResponseMigration([sourceFile], program.getTypeChecker(), resolve11("."), new Set([absoluteFile]));
+  const plan = planRouteResponseMigration([sourceFile], program.getTypeChecker(), resolve12("."), new Set([absoluteFile]));
   const replacements = plan.replacementsByFile.get(absoluteFile) ?? [];
   return {
     changed: replacements.length > 0,
@@ -11663,7 +11698,7 @@ function migrateRouteResponse(source, fileName) {
   };
 }
 function migrateRouteResponseProject(files, rootDir, sourceByPath) {
-  const absoluteFiles = files.map((file) => resolve11(file));
+  const absoluteFiles = files.map((file) => resolve12(file));
   const program = createMigrationProgram(absoluteFiles, sourceByPath, rootDir);
   const sourceFiles = absoluteFiles.map((file) => program.getSourceFile(file)).filter((file) => file !== undefined);
   const plan = planRouteResponseMigration(sourceFiles, program.getTypeChecker(), rootDir, new Set(absoluteFiles));
@@ -11676,11 +11711,11 @@ function migrateRouteResponseProject(files, rootDir, sourceByPath) {
       changed: replacements.length > 0,
       content: applyReplacements(source, replacements),
       replacements: replacements.length,
-      issues: plan.issues.filter((issue) => resolve11(rootDir, issue.file) === file)
+      issues: plan.issues.filter((issue) => resolve12(rootDir, issue.file) === file)
     });
   }
   for (const issue of plan.issues) {
-    const path = resolve11(rootDir, issue.file);
+    const path = resolve12(rootDir, issue.file);
     if (!results.has(path) && sourceByPath.has(path)) {
       results.set(path, {
         changed: false,
@@ -11702,17 +11737,59 @@ var SUPACLOUD_MIGRATIONS = [
   }
 ];
 async function writeAtomically(path, content) {
-  const temporary = `${path}.supacloud-migrate-${process.pid}`;
-  await writeFile4(temporary, content, "utf8");
-  await rename5(temporary, path);
+  const temporary = `${path}.supacloud-migrate-${process.pid}-${crypto.randomUUID()}`;
+  try {
+    await writeFile4(temporary, content, "utf8");
+    await rename5(temporary, path);
+  } finally {
+    await rm3(temporary, { force: true });
+  }
 }
 async function migrateProject(options) {
-  const rootDir = resolve11(options.rootDir);
+  const rootDir = resolve12(options.rootDir);
+  let migrations = SUPACLOUD_MIGRATIONS;
+  const preflightIssues = [];
+  if (options.fromVersion !== undefined || options.toVersion !== undefined) {
+    migrations = [];
+    const checkpoints = new Set(SUPACLOUD_MIGRATIONS.flatMap(({ from, to }) => [from, to]));
+    let current = options.fromVersion;
+    if (!current || !options.toVersion || !checkpoints.has(current) || !checkpoints.has(options.toVersion)) {
+      preflightIssues.push({
+        code: "migration-version-unsupported",
+        file: "package.json",
+        message: `Supply both supported source-format checkpoints: ${[...checkpoints].join(", ")}`
+      });
+    } else {
+      const visited = new Set;
+      while (current !== options.toVersion) {
+        const next = SUPACLOUD_MIGRATIONS.filter((migration) => migration.from === current);
+        if (visited.has(current) || next.length !== 1 || !next[0]) {
+          preflightIssues.push({
+            code: "migration-path-unavailable",
+            file: "package.json",
+            message: `No unambiguous forward migration from ${current} to ${options.toVersion}`
+          });
+          break;
+        }
+        visited.add(current);
+        migrations.push(next[0]);
+        current = next[0].to;
+      }
+    }
+    if (preflightIssues.length === 0) {
+      for (const message of await checkMigrationDependencies(rootDir)) {
+        preflightIssues.push({ code: "migration-dependency-incompatible", file: "package.json", message });
+      }
+    }
+    if (preflightIssues.length > 0) {
+      return { write: options.write === true, migrations: [], files: [], changedFiles: [], issues: preflightIssues };
+    }
+  }
   const include = options.include ?? ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"];
   const files = ts10.sys.readDirectory(rootDir, [".ts", ".tsx", ".mts", ".cts"], ["node_modules", "dist", "generated"], include).sort();
   const results = [];
   const issues = [];
-  const pendingWrites = [];
+  const pendingWrites = new Map;
   const sourceByPath = new Map;
   const issueKeys = new Set;
   const appendIssues = (items) => {
@@ -11725,14 +11802,16 @@ async function migrateProject(options) {
     }
   };
   for (const filePath of files) {
-    sourceByPath.set(resolve11(filePath), await readFile8(filePath, "utf8"));
+    sourceByPath.set(resolve12(filePath), await readFile9(filePath, "utf8"));
   }
-  for (const migration of SUPACLOUD_MIGRATIONS) {
+  const originalSources = new Map(sourceByPath);
+  const writtenFiles = new Set;
+  for (const migration of migrations) {
     const projectResults = migration.id === "route-response-to-responses" ? migrateRouteResponseProject(files, rootDir, sourceByPath) : undefined;
     if (projectResults)
       appendIssues(projectResults.issues);
     for (const filePath of files) {
-      const absoluteFile = resolve11(filePath);
+      const absoluteFile = resolve12(filePath);
       const file = relative10(rootDir, absoluteFile) || absoluteFile;
       const before = sourceByPath.get(absoluteFile);
       if (before === undefined)
@@ -11740,7 +11819,7 @@ async function migrateProject(options) {
       const result = projectResults?.results.get(absoluteFile) ?? migration.apply(before, file);
       sourceByPath.set(absoluteFile, result.content);
       if (result.changed && result.issues.length === 0) {
-        pendingWrites.push({ path: filePath, content: result.content });
+        pendingWrites.set(absoluteFile, result.content);
       }
       if (!projectResults)
         appendIssues(result.issues);
@@ -11755,13 +11834,36 @@ async function migrateProject(options) {
     }
   }
   if (options.write && issues.length === 0) {
-    for (const pending of pendingWrites)
-      await writeAtomically(pending.path, pending.content);
+    const written = [];
+    try {
+      for (const [path, content] of pendingWrites) {
+        if (await readFile9(path, "utf8") !== originalSources.get(path)) {
+          throw new Error(`Source changed during migration: ${path}`);
+        }
+        await writeAtomically(path, content);
+        written.push(path);
+        writtenFiles.add(path);
+      }
+    } catch (error) {
+      appendIssues([{ code: "migration-write-failed", file: rootDir, message: String(error) }]);
+      for (const path of written.reverse()) {
+        try {
+          const original = originalSources.get(path);
+          if (original === undefined || await readFile9(path, "utf8") !== pendingWrites.get(path)) {
+            throw new Error("File changed after migration; refusing to overwrite concurrent edits");
+          }
+          await writeAtomically(path, original);
+          writtenFiles.delete(path);
+        } catch (rollbackError) {
+          appendIssues([{ code: "migration-rollback-failed", file: path, message: String(rollbackError) }]);
+        }
+      }
+    }
   }
-  const changedFiles = options.write && issues.length > 0 ? [] : results.filter((result) => result.changed && result.issues.length === 0).map((result) => result.file);
+  const changedFiles = options.write && issues.length > 0 ? [...writtenFiles].map((file) => relative10(rootDir, file)) : [...new Set(results.filter((result) => result.changed && result.issues.length === 0).map((result) => result.file))];
   return {
     write: options.write === true,
-    migrations: SUPACLOUD_MIGRATIONS.map(({ id, from, to, description }) => ({ id, from, to, description })),
+    migrations: migrations.map(({ id, from, to, description }) => ({ id, from, to, description })),
     files: results,
     changedFiles,
     issues
@@ -12051,8 +12153,8 @@ function exportGraphDot(graph) {
 init_generate();
 
 // src/openapi-tools.ts
-import { mkdir as mkdir4, readFile as readFile9, rename as rename6, unlink as unlink3, writeFile as writeFile5 } from "node:fs/promises";
-import { dirname as dirname9, resolve as resolve12 } from "node:path";
+import { mkdir as mkdir4, readFile as readFile10, rename as rename6, unlink as unlink3, writeFile as writeFile5 } from "node:fs/promises";
+import { dirname as dirname9, resolve as resolve13 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 class OpenApiDocumentError extends Error {
@@ -12443,7 +12545,7 @@ function serializeOpenApiJson(document, space = 2) {
 }
 async function readOpenApiJson(path) {
   try {
-    const value = JSON.parse(await readFile9(resolve12(path), "utf8"));
+    const value = JSON.parse(await readFile10(resolve13(path), "utf8"));
     return parseOpenApiDocument(value);
   } catch (error) {
     if (error instanceof OpenApiDocumentError)
@@ -12452,11 +12554,11 @@ async function readOpenApiJson(path) {
   }
 }
 async function writeOpenApiJson(document, outputPath, space = 2) {
-  const path = resolve12(outputPath);
+  const path = resolve13(outputPath);
   const content = serializeOpenApiJson(document, space);
   await mkdir4(dirname9(path), { recursive: true });
   try {
-    if (await readFile9(path, "utf8") === content)
+    if (await readFile10(path, "utf8") === content)
       return { path, written: false };
   } catch {}
   const temporaryPath = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
@@ -12473,7 +12575,7 @@ async function writeOpenApiJson(document, outputPath, space = 2) {
 }
 async function loadGeneratedOpenApiDocument(modulePath) {
   try {
-    const moduleUrl = pathToFileURL(resolve12(modulePath));
+    const moduleUrl = pathToFileURL(resolve13(modulePath));
     moduleUrl.searchParams.set("supacloud-openapi-export", "1");
     const loaded = await import(moduleUrl.href);
     if (!isRecord(loaded))
@@ -12557,7 +12659,7 @@ function formatOpenApiDiff(result) {
 // src/config.ts
 init_graphql_options();
 import { existsSync as existsSync5 } from "node:fs";
-import { join as join8, resolve as resolve13 } from "node:path";
+import { join as join8, resolve as resolve14 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 var DEFAULT_SUPACLOUD_CONFIG = {
   graphql: false,
@@ -12643,8 +12745,8 @@ function validateGovernanceConfig(config) {
 function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
   const resolved = defineSupacloudConfig(config);
   return {
-    rootDir: resolve13(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
-    outDir: resolve13(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
+    rootDir: resolve14(cwd, resolved.root ?? DEFAULT_SUPACLOUD_CONFIG.root),
+    outDir: resolve14(cwd, resolved.outDir ?? DEFAULT_SUPACLOUD_CONFIG.outDir),
     include: resolved.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
     strict: resolved.strict ?? DEFAULT_SUPACLOUD_CONFIG.strict,
     requireRouteContracts: resolved.requireRouteContracts ?? DEFAULT_SUPACLOUD_CONFIG.requireRouteContracts,
@@ -12662,7 +12764,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders,
     graphql: resolved.graphql ? {
       ...resolved.graphql,
-      schema: resolve13(cwd, resolved.graphql.schema)
+      schema: resolve14(cwd, resolved.graphql.schema)
     } : undefined
   };
 }

package/dist/migration-policy.d.ts

@@ -0,0 +1,2 @@
+export declare const migrationDependencies: Readonly<Record<string, string>>;
+export declare function checkMigrationDependencies(rootDir: string): Promise<string[]>;

package/dist/migrations.d.ts

@@ -21,6 +21,9 @@ export interface MigrateProjectOptions {
     rootDir: string;
     include?: string[];
     write?: boolean;
+    /** Source-format checkpoints, not npm package versions. Both are required together. */
+    fromVersion?: string;
+    toVersion?: string;
 }
 export interface MigrateFileResult {
     file: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/compiler",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Static compiler for @supacloud/app metadata: builds the application graph from AST, validates it, and generates reflection-free factory code",
   "type": "module",
   "main": "./dist/index.js",