@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.271e503382da352a

package/dist/migration/migration-routes.js

@@ -0,0 +1,1233 @@
+import { access, mkdir, readFile, readdir, rm, writeFile, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import bodyParser from "body-parser";
+import { parse as parseYaml } from "yaml";
+import { RESTART_EXIT_CODE, RESTART_SUPERVISED_ENV, } from "@superblocksteam/library-shared/restart-contract";
+import { LanguagePluginID } from "@superblocksteam/shared";
+import { getTelemetryInstance, isTelemetryInitialized, } from "@superblocksteam/telemetry";
+import { API_MIGRATION_ORIGINS, clearChecklist, clearChecklistItemsByOrigin, markChecklistCompleted, readPersistedChecklist, retryFailedSeedApiItemsFromChecklist, updateChecklistItem, } from "../ai-service/checklist/persisted-checklist-store.js";
+import { clearMigrationTurnsLog, getNormalMigrationTurnSummary, } from "../ai-service/migration-turns-log.js";
+import { getErrorMeta } from "../util/logger.js";
+import { getFullstackTemplateDir } from "./get-fullstack-template-dir.js";
+import { parseIntegrationWritePolicy } from "./integration-write-policy.js";
+import { classifyIntegrationMutations } from "./migration-classifier.js";
+import { endMigrationRunSpan, markMigrationRunStage, recordMigrationStage, startMigrationRunSpan, } from "./migration-metrics.js";
+import { isMigrationScratchRehydrateInFlight, reconcileMigrationSessionOnBoot, rehydrateMigrationScratchOnBoot, } from "./migration-session-reconcile.js";
+import { clearVerificationHistory } from "./migration-verification.js";
+import { migrateToFullstack, restoreFromV2Backup } from "./restructure.js";
+import { detectUnsupportedIntegrations } from "./unsupported-integrations.js";
+import { forEachYamlStep } from "./yaml-walk.js";
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function extractBearerJwt(authorizationHeader) {
+    const raw = Array.isArray(authorizationHeader)
+        ? authorizationHeader[0]
+        : authorizationHeader;
+    if (!raw?.startsWith("Bearer ")) {
+        return undefined;
+    }
+    const jwt = raw.slice("Bearer ".length).trim();
+    return jwt.length > 0 ? jwt : undefined;
+}
+const TARGET_TEMPLATE_NAME = "app-fullstack";
+// Re-exported so this module's tests keep importing RESTART_EXIT_CODE from here;
+// the canonical contract lives in
+// `@superblocksteam/library-shared/restart-contract`.
+export { RESTART_EXIT_CODE };
+const MIGRATION_STATE_FILE = "migration-state.json";
+const SCRATCH_DIR_NAME = "scratch";
+/** Upper bound on the pre-exit telemetry drain so a wedged collector can never
+ * hang the restart: we would rather lose a few spans than leave the pod stuck. */
+const RESTART_TELEMETRY_FLUSH_TIMEOUT_MS = 2000;
+/**
+ * Drain the OTel pipeline before the self-restart `process.exit`.
+ *
+ * `process.exit()` tears down the event loop synchronously, so anything still
+ * buffered in the batch span/metric/log exporters is dropped on the floor. That
+ * is exactly why the in-place restart was invisible in Datadog: the
+ * "Self-restarting…" log, the server-side flip-disposition metric, and the
+ * boot metric all rode in those buffers. Shutting telemetry down here
+ * force-flushes the exporters first. Bounded by a timeout (and tolerant of any
+ * flush error) so observability is best-effort and never blocks the restart.
+ */
+async function flushTelemetryBeforeExit(logger) {
+    if (!isTelemetryInitialized()) {
+        return;
+    }
+    let timer;
+    try {
+        await Promise.race([
+            getTelemetryInstance().shutdown(),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, RESTART_TELEMETRY_FLUSH_TIMEOUT_MS);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    catch (error) {
+        logger.warn("[migrate-route] Failed to flush telemetry before self-restart; exiting anyway", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Single exit seam for the in-place dev-server restart. Runs shared teardown
+ * (same as `/_sb_disconnect` with `isRestart: true`), drains telemetry, then
+ * exits with RESTART_EXIT_CODE so the parent supervisor respawns the child
+ * with the flipped template (the editor reconnects to the same pod/port).
+ *
+ * The *server-facing* half of the handshake -- the "will self-restart" signal
+ * that tells the server to skip pod termination -- is sent earlier, on the flip
+ * RPC (`flipTemplate({ selfRestart: true })`), not here.
+ */
+async function requestSelfRestart(logger, prepareInPlaceRestart) {
+    logger.info("[migrate-route] Self-restarting dev server process after template flip (in-place restart)");
+    try {
+        if (prepareInPlaceRestart) {
+            await prepareInPlaceRestart({ flipRestart: true });
+        }
+        await flushTelemetryBeforeExit(logger);
+    }
+    catch (error) {
+        logger.error("[migrate-route] teardown before self-restart failed; exiting anyway", getErrorMeta(error));
+    }
+    process.exit(RESTART_EXIT_CODE);
+}
+let inMemoryStatus = { state: "idle" };
+let migrationCompleteCommitInFlight = false;
+/**
+ * Recursively finds all api.yaml/api.yml files inside `apis/` directories
+ * under `rootDir`. Used to scan the live app tree before migration starts
+ * (before a v2-backup exists).
+ */
+async function findLiveApiYamls(rootDir) {
+    const results = [];
+    const stack = [rootDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name === SCRATCH_DIR_NAME || entry.name === "node_modules") {
+                continue;
+            }
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(abs);
+            }
+            else if (entry.isFile() &&
+                (entry.name === "api.yaml" || entry.name === "api.yml")) {
+                // Only treat files inside an `apis/` directory as v2 API definitions.
+                const rel = abs.substring(rootDir.length + 1);
+                if (rel.split("/").includes("apis")) {
+                    results.push(abs);
+                }
+            }
+        }
+    }
+    return results.sort();
+}
+const LANGUAGE_PLUGIN_IDS = new Set(Object.values(LanguagePluginID));
+/**
+ * Extracts integration entries from a set of api.yaml paths by parsing each
+ * file and classifying its steps.
+ *
+ * v2 YAML structure: `blocks[].step.integration`, but `step` may live at any
+ * depth — control-flow blocks (conditional / tryCatch / foreach / parallel)
+ * nest their children. We walk every node so an integration referenced only
+ * inside a `tryCatch.try.blocks` entry isn't silently dropped from the modal.
+ *
+ * Language-runtime "integrations" (`javascript`, `python`) are excluded:
+ * they are inline code, not data integrations, so the user has no meaningful
+ * write-policy decision to make about them.
+ */
+async function extractIntegrationsFromYamls(yamlPaths) {
+    const integrationSteps = new Map();
+    for (const yamlPath of yamlPaths) {
+        try {
+            const raw = await readFile(yamlPath, "utf-8");
+            const parsed = parseYaml(raw);
+            forEachYamlStep(parsed, (step) => {
+                const integrationId = step["integration"];
+                if (typeof integrationId !== "string" || integrationId.length === 0) {
+                    return;
+                }
+                const existing = integrationSteps.get(integrationId) ?? [];
+                existing.push(step);
+                integrationSteps.set(integrationId, existing);
+            });
+        }
+        catch {
+            // Skip unreadable YAMLs
+        }
+    }
+    return Array.from(integrationSteps.entries())
+        .filter(([id]) => !LANGUAGE_PLUGIN_IDS.has(id))
+        .map(([id, steps]) => ({
+        id,
+        displayName: id,
+        defaultPolicy: "deny",
+        mutationKind: classifyIntegrationMutations(steps),
+    }));
+}
+async function collectMigrationIntegrations(appRootDir) {
+    const backupDir = join(appRootDir, SCRATCH_DIR_NAME, "v2-backup");
+    const yamlPaths = await findLiveApiYamls(backupDir);
+    return extractIntegrationsFromYamls(yamlPaths);
+}
+/**
+ * Scans the live (pre-migration) app tree for v2 API YAML files and
+ * classifies the integrations they reference. Called when there is no
+ * v2-backup yet (i.e., the migration has not started) so the write-policy
+ * modal can be shown before the user clicks Migrate.
+ */
+async function collectPreMigrationIntegrations(appRootDir) {
+    const yamlPaths = await findLiveApiYamls(appRootDir);
+    return extractIntegrationsFromYamls(yamlPaths);
+}
+/**
+ * Resolve the phase a browser should see.
+ *
+ * If the in-memory status is actively driving the three-step flow
+ * (`backup` | `restructure` | `flip`) it wins — those phases are only ever
+ * live during the synchronous handler, so in-memory is the freshest truth.
+ *
+ * Otherwise we derive from disk: migration-state.json presence + the
+ * checklist. Failed checklist items with `origin === "seed_api"` drive the
+ * `done_with_unresolved` terminal phase. Disk is the single source of truth
+ * and the only thing that survives a dev-server restart mid-translation.
+ */
+async function resolveStatus(appRootDir, opts = {}) {
+    const ignoreInMemory = opts.ignoreInMemory ?? false;
+    const stateFilePath = join(appRootDir, SCRATCH_DIR_NAME, MIGRATION_STATE_FILE);
+    const [hasV2Backup, hasMigrationStateFile] = await Promise.all([
+        pathExists(join(appRootDir, SCRATCH_DIR_NAME, "v2-backup")),
+        pathExists(stateFilePath),
+    ]);
+    const [checklist, integrations, initialTurn] = await Promise.all([
+        readPersistedChecklist(appRootDir),
+        hasV2Backup
+            ? collectMigrationIntegrations(appRootDir)
+            : collectPreMigrationIntegrations(appRootDir),
+        getNormalMigrationTurnSummary(appRootDir),
+    ]);
+    const checklistPayload = checklist
+        ? {
+            overallStatus: checklist.overallStatus,
+            items: checklist.items,
+            lastUpdated: checklist.lastUpdated,
+        }
+        : undefined;
+    if (!ignoreInMemory &&
+        (inMemoryStatus.state === "backup" ||
+            inMemoryStatus.state === "restructure" ||
+            inMemoryStatus.state === "flip" ||
+            (inMemoryStatus.state === "failed" && !hasMigrationStateFile))) {
+        return {
+            ...inMemoryStatus,
+            hasV2Backup,
+            initialTurn,
+            checklist: checklistPayload,
+            ...(integrations !== undefined && { integrations }),
+        };
+    }
+    if (!hasMigrationStateFile) {
+        const unsupportedStatus = await detectUnsupportedIntegrations(appRootDir);
+        return {
+            state: isMigrationScratchRehydrateInFlight() ? "translating" : "idle",
+            hasV2Backup,
+            initialTurn,
+            ...unsupportedStatus,
+            checklist: checklistPayload,
+            ...(integrations !== undefined && { integrations }),
+        };
+    }
+    const persistedState = await readPersistedMigrationState(stateFilePath);
+    const startedAt = inMemoryStatus.startedAt ?? persistedState.startedAt;
+    const backupCommitId = inMemoryStatus.backupCommitId ?? persistedState.backupCommitId;
+    const migrationCommitId = inMemoryStatus.migrationCommitId ?? persistedState.migrationCommitId;
+    const integrationWritePolicy = persistedState.integrationWritePolicy;
+    // Migration state is durable on disk, but checklist writes can be briefly
+    // delayed during startup/restart windows. Never report "done" until a
+    // checklist payload is available with at least one row.
+    if (!checklist || checklist.items.length === 0) {
+        const isActiveSyncPhase = !ignoreInMemory &&
+            (inMemoryStatus.state === "backup" ||
+                inMemoryStatus.state === "restructure" ||
+                inMemoryStatus.state === "flip");
+        if (!backupCommitId && !isActiveSyncPhase) {
+            return {
+                state: "idle",
+                startedAt,
+                backupCommitId,
+                migrationCommitId,
+                hasV2Backup,
+                initialTurn,
+                checklist: checklistPayload,
+                ...(integrations !== undefined && { integrations }),
+                ...(integrationWritePolicy !== undefined && { integrationWritePolicy }),
+            };
+        }
+        return {
+            state: "translating",
+            startedAt,
+            backupCommitId,
+            migrationCommitId,
+            hasV2Backup,
+            initialTurn,
+            checklist: checklistPayload,
+            ...(integrations !== undefined && { integrations }),
+            ...(integrationWritePolicy !== undefined && { integrationWritePolicy }),
+        };
+    }
+    const seedApiItems = checklist.items.filter((item) => API_MIGRATION_ORIGINS.has(item.origin));
+    const pendingCount = seedApiItems.filter((item) => item.status === "pending" || item.status === "in_progress").length;
+    const failedCount = seedApiItems.filter((item) => item.status === "failed").length;
+    if (checklist?.overallStatus === "completed") {
+        return {
+            state: "done",
+            startedAt,
+            backupCommitId,
+            migrationCommitId,
+            hasV2Backup,
+            initialTurn,
+            checklist: checklistPayload,
+            ...(integrations !== undefined && { integrations }),
+            ...(integrationWritePolicy !== undefined && { integrationWritePolicy }),
+        };
+    }
+    if (pendingCount > 0) {
+        return {
+            state: "translating",
+            startedAt,
+            backupCommitId,
+            migrationCommitId,
+            hasV2Backup,
+            initialTurn,
+            checklist: checklistPayload,
+            ...(integrations !== undefined && { integrations }),
+            ...(integrationWritePolicy !== undefined && { integrationWritePolicy }),
+        };
+    }
+    return {
+        state: failedCount > 0 ? "done_with_unresolved" : "done",
+        startedAt,
+        backupCommitId,
+        migrationCommitId,
+        hasV2Backup,
+        initialTurn,
+        checklist: checklistPayload,
+        ...(integrations !== undefined && { integrations }),
+        ...(integrationWritePolicy !== undefined && { integrationWritePolicy }),
+    };
+}
+async function readPersistedMigrationState(stateFilePath) {
+    try {
+        const raw = await readFile(stateFilePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : undefined,
+            sourceTemplateName: typeof parsed.sourceTemplateName === "string"
+                ? parsed.sourceTemplateName
+                : undefined,
+            backupDirPath: typeof parsed.backupDirPath === "string"
+                ? parsed.backupDirPath
+                : undefined,
+            backupCommitId: typeof parsed.backupCommitId === "string"
+                ? parsed.backupCommitId
+                : undefined,
+            migrationCommitId: typeof parsed.migrationCommitId === "string"
+                ? parsed.migrationCommitId
+                : undefined,
+            integrationWritePolicy: parsed.integrationWritePolicy !== null &&
+                typeof parsed.integrationWritePolicy === "object" &&
+                !Array.isArray(parsed.integrationWritePolicy)
+                ? parsed.integrationWritePolicy
+                : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+async function persistMigrationStateMetadata(stateFilePath, metadata) {
+    let parsed = {};
+    try {
+        const raw = await readFile(stateFilePath, "utf-8");
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        await mkdir(dirname(stateFilePath), { recursive: true });
+        if (metadata.startedAt) {
+            parsed.startedAt = metadata.startedAt;
+        }
+    }
+    if (metadata.backupCommitId) {
+        parsed.backupCommitId = metadata.backupCommitId;
+    }
+    if (metadata.migrationCommitId) {
+        parsed.migrationCommitId = metadata.migrationCommitId;
+    }
+    await writeFile(stateFilePath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+}
+function setupCorsAndValidateMethod({ req, res, allowedMethod, allowHeaders, }) {
+    if (req.method !== allowedMethod && req.method !== "OPTIONS") {
+        res.statusCode = 405;
+        res.end("Method not allowed");
+        return false;
+    }
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", `${allowedMethod}, OPTIONS`);
+    if (allowHeaders) {
+        res.setHeader("Access-Control-Allow-Headers", allowHeaders);
+    }
+    if (req.method === "OPTIONS") {
+        res.statusCode = 204;
+        res.end();
+        return false;
+    }
+    return true;
+}
+export function registerMigrationRoutes(server, options) {
+    const { appRootDir, checkAuthorization, getIsInitialized, syncService, logger, inPlaceTemplateRestartEnabled = false, getAiService, prepareInPlaceRestart, } = options;
+    // --- GET /sb-migration-status: checklist + verification artifacts only --
+    // Lifecycle authority is the server migration session; GET always derives
+    // state from disk (ignoreInMemory) so backup/restructure/flip never leak.
+    server.middlewares.use("/sb-migration-status", (req, res, next) => {
+        if (!getIsInitialized())
+            return next();
+        if (!setupCorsAndValidateMethod({ req, res, allowedMethod: "GET" })) {
+            return;
+        }
+        res.setHeader("Content-Type", "application/json");
+        void resolveStatus(appRootDir, { ignoreInMemory: true })
+            .then((status) => {
+            res.statusCode = 200;
+            res.end(JSON.stringify(status));
+        })
+            .catch((error) => {
+            logger.error("[migrate-route] /sb-migration-status failed", getErrorMeta(error));
+            res.statusCode = 500;
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    });
+    server.middlewares.use("/sb-migrate-to-fullstack", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-restore-context", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-restore-context", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized()) {
+                return next();
+            }
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type, Authorization",
+            })) {
+                return;
+            }
+            const authorization = await checkAuthorization(req.headers.authorization);
+            if (!authorization.success) {
+                res.statusCode = authorization.status;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: authorization.error }));
+                return;
+            }
+            const body = req.body;
+            const { applicationId, branchName, commitId } = body;
+            if (typeof applicationId !== "string" ||
+                typeof branchName !== "string" ||
+                typeof commitId !== "string") {
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: "Invalid restore-context payload" }));
+                return;
+            }
+            const aiService = getAiService?.();
+            if (!aiService) {
+                res.statusCode = 503;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: "AI service unavailable" }));
+                return;
+            }
+            const jwt = extractBearerJwt(req.headers.authorization);
+            if (!jwt) {
+                res.statusCode = 401;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: "Authorization required" }));
+                return;
+            }
+            const jwtAccepted = aiService.updateClarkJwt(jwt);
+            let cleared = false;
+            try {
+                await aiService.clearMigrationAbortLocalContext();
+                cleared = true;
+            }
+            catch (error) {
+                logger.warn("[migrate-route] migration context clear failed", getErrorMeta(error));
+            }
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ ok: true, cleared, jwtAccepted }));
+        })().catch((error) => {
+            logger.error("[migrate-route] /sb-migration-restore-context failed", getErrorMeta(error));
+            res.statusCode = 500;
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    });
+    server.middlewares.use("/sb-migration-reset-state", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-reset-state", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized()) {
+                return next();
+            }
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type",
+            })) {
+                return;
+            }
+            const scratchDirPath = join(appRootDir, SCRATCH_DIR_NAME);
+            const stateFilePath = join(scratchDirPath, MIGRATION_STATE_FILE);
+            const backupDirPath = join(scratchDirPath, "v2-backup");
+            const verificationDirPath = join(scratchDirPath, "migration-verification");
+            let autoSyncPaused = false;
+            let shouldResumeAutoSync = true;
+            let diskRestored = false;
+            try {
+                if (syncService) {
+                    syncService.pauseAutoSync();
+                    autoSyncPaused = true;
+                }
+                const hadV2Backup = await pathExists(backupDirPath);
+                if (hadV2Backup) {
+                    // Abort will terminate this pod; do not resume autosync if restore
+                    // fails mid-way either — re-uploading a partial v3 tree is worse than
+                    // staying paused until the pod is recycled.
+                    shouldResumeAutoSync = false;
+                    const restoreResult = await restoreFromV2Backup({
+                        appRootDirPath: appRootDir,
+                        logger,
+                    });
+                    diskRestored = restoreResult.restored;
+                    await clearChecklist({ appRootDirPath: appRootDir });
+                }
+                else {
+                    // Also clear the per-API verification directory so stale `.diff.json`
+                    // and `.history.json` files from the prior run don't poison the next
+                    // attempt — without this, a re-run would inherit the previous attempt
+                    // count and could trip the verification exhaustion cap immediately.
+                    await Promise.all([
+                        rm(stateFilePath, { force: true }),
+                        clearChecklist({ appRootDirPath: appRootDir }),
+                        clearMigrationTurnsLog(appRootDir),
+                        rm(verificationDirPath, { recursive: true, force: true }),
+                    ]);
+                }
+            }
+            finally {
+                if (autoSyncPaused && shouldResumeAutoSync) {
+                    try {
+                        syncService?.resumeAutoSync();
+                    }
+                    catch (error) {
+                        logger.warn("[migrate-route] Failed to resume autosync after migration state reset", getErrorMeta(error));
+                    }
+                }
+            }
+            const aiService = getAiService?.();
+            if (aiService) {
+                try {
+                    await aiService.clearMigrationAbortLocalContext();
+                }
+                catch (error) {
+                    logger.warn("[migrate-route] migration state reset could not clear LLM context", getErrorMeta(error));
+                }
+            }
+            inMemoryStatus = { state: "idle" };
+            const status = await resolveStatus(appRootDir, { ignoreInMemory: true });
+            logger.info("[migrate-route] migration state reset requested", {
+                diskRestored,
+                state: status.state,
+                hasV2Backup: status.hasV2Backup,
+            });
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                ok: true,
+                diskRestored,
+                status,
+            }));
+        })().catch((error) => {
+            logger.error("[migrate-route] /sb-migration-reset-state failed", getErrorMeta(error));
+            res.statusCode = 500;
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    });
+    server.middlewares.use("/sb-migrate-to-fullstack", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized()) {
+                return next();
+            }
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type",
+            })) {
+                return;
+            }
+            logger.info("[migrate-route] /sb-migrate-to-fullstack requested");
+            res.setHeader("Content-Type", "application/json");
+            const body = req.body;
+            const migrationGeneration = body?.generation;
+            if (migrationGeneration === undefined ||
+                typeof migrationGeneration !== "number" ||
+                !Number.isInteger(migrationGeneration) ||
+                migrationGeneration < 1) {
+                res.statusCode = 400;
+                res.end(JSON.stringify({
+                    error: "generation is required (positive integer from POST /migration/start)",
+                }));
+                return;
+            }
+            const parsedWritePolicy = parseIntegrationWritePolicy(body?.integrationWritePolicy);
+            if (!parsedWritePolicy.ok) {
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: parsedWritePolicy.error }));
+                return;
+            }
+            const integrationWritePolicy = parsedWritePolicy.policy;
+            if (!syncService) {
+                res.statusCode = 503;
+                res.end(JSON.stringify({
+                    error: "Upgrade is unavailable: the dev server was started without a SyncService (no Superblocks credentials?).",
+                }));
+                return;
+            }
+            if (await isAlreadyOnFullstack(appRootDir)) {
+                res.statusCode = 409;
+                res.end(JSON.stringify({
+                    error: `App appears to already be on template '${TARGET_TEMPLATE_NAME}' (client/ and server/apis/index.ts exist). Upgrade is a one-way transition; refusing to run again.`,
+                }));
+                return;
+            }
+            if (inMemoryStatus.state !== "idle" &&
+                inMemoryStatus.state !== "done" &&
+                inMemoryStatus.state !== "done_with_unresolved" &&
+                inMemoryStatus.state !== "failed") {
+                res.statusCode = 409;
+                res.end(JSON.stringify({
+                    error: `An upgrade is already in progress (state: ${inMemoryStatus.state}). Please wait for it to complete.`,
+                }));
+                return;
+            }
+            // Decide up front whether this process will restart itself in place after
+            // the flip. This is deterministic (flag + presence of a restart
+            // supervisor), so it is safe to evaluate before the flip -- and we MUST,
+            // because the decision is carried *on* the flip RPC so the server can skip
+            // terminating the pod within the same transaction (the self-restart
+            // handshake). Warm-claimed single-process pods have no supervisor and fall
+            // through to today's pod-swap behavior (merge-independence guard).
+            const willSelfRestart = inPlaceTemplateRestartEnabled &&
+                process.env[RESTART_SUPERVISED_ENV] === "1";
+            // Trace the origin of the handshake so oncall can tell, from the dev
+            // server side, whether a migration was expected to self-restart in place
+            // or fall through to a pod swap (flag on but supervisor absent, etc.).
+            logger.info("[migrate-route] willSelfRestart decision", {
+                willSelfRestart,
+                inPlaceTemplateRestartEnabled,
+                supervised: process.env[RESTART_SUPERVISED_ENV] === "1",
+            });
+            res.statusCode = 202;
+            res.end(JSON.stringify({
+                accepted: true,
+                // Surfaced synchronously so the editor can decide whether to skip its
+                // one-shot post-flip `/disconnect` -- that disconnect would otherwise
+                // gracefully shut the dev server down (exit 0) and kill the very pod
+                // we are keeping alive for the in-place restart. Omitted entirely on
+                // the pod-swap fallback so the editor preserves today's disconnect.
+                ...(willSelfRestart ? { willSelfRestart: true } : {}),
+                message: "Upgrade started. The editor will reconnect automatically when the new runtime is ready.",
+            }));
+            const stateFilePath = join(appRootDir, SCRATCH_DIR_NAME, MIGRATION_STATE_FILE);
+            let backupCommitId;
+            let restructured = false;
+            let autoSyncPaused = false;
+            let watcherPaused = false;
+            // Gates the actual `process.exit` below. Set only after a *successful*
+            // flip so a thrown flip never triggers an in-place restart.
+            let shouldSelfRestart = false;
+            const runSpan = startMigrationRunSpan({
+                generation: migrationGeneration,
+                willSelfRestart,
+            });
+            let runFailedStage;
+            let runError;
+            inMemoryStatus = {
+                state: "backup",
+                startedAt: new Date().toISOString(),
+            };
+            try {
+                logger.info("[migrate-route] Step 1: pre-migration backup commit", {
+                    migrationGeneration,
+                });
+                const backup = await syncService.backupCurrentDirectory({
+                    migrationGeneration,
+                });
+                backupCommitId = backup.commitId;
+                if (!backupCommitId) {
+                    const msg = "Pre-upgrade backup did not produce a commitId; aborting.";
+                    logger.error("[migrate-route] " + msg);
+                    recordMigrationStage("backup", "failure");
+                    markMigrationRunStage(runSpan, "backup", "failure");
+                    runFailedStage = "backup";
+                    inMemoryStatus = { state: "failed", error: msg };
+                    return;
+                }
+                logger.info("[migrate-route] Backup commit created", {
+                    backupCommitId,
+                });
+                recordMigrationStage("backup", "success");
+                markMigrationRunStage(runSpan, "backup", "success");
+                await persistMigrationStateMetadata(stateFilePath, {
+                    backupCommitId,
+                    startedAt: inMemoryStatus.startedAt,
+                });
+                inMemoryStatus = {
+                    state: "restructure",
+                    backupCommitId,
+                    startedAt: inMemoryStatus.startedAt,
+                };
+                syncService.pauseAutoSync();
+                autoSyncPaused = true;
+                logger.info("[migrate-route] Pausing Vite file watcher");
+                server.watcher.unwatch(appRootDir);
+                watcherPaused = true;
+                logger.info("[migrate-route] Step 2: restructuring local tree");
+                await migrateToFullstack({
+                    appRootDirPath: appRootDir,
+                    templateSourceDirPath: getFullstackTemplateDir(),
+                    logger,
+                    ...(integrationWritePolicy !== undefined && {
+                        integrationWritePolicy,
+                    }),
+                });
+                restructured = true;
+                await persistMigrationStateMetadata(stateFilePath, {
+                    backupCommitId,
+                });
+                logger.info("[migrate-route] Local restructure complete");
+                recordMigrationStage("restructure", "success");
+                markMigrationRunStage(runSpan, "restructure", "success");
+                inMemoryStatus = {
+                    state: "flip",
+                    backupCommitId,
+                    startedAt: inMemoryStatus.startedAt,
+                };
+                logger.info("[migrate-route] Step 3: atomic server-side template flip");
+                const flip = await syncService.flipTemplate({
+                    targetTemplateName: TARGET_TEMPLATE_NAME,
+                    migrationGeneration,
+                    ...(willSelfRestart ? { selfRestart: true } : {}),
+                });
+                // Promote the exit gate the instant the flip commits -- BEFORE any
+                // further bookkeeping. With `selfRestart: true` the server has already
+                // skipped pod termination inside the flip transaction, so this process
+                // is now the only thing that can bring up the new template. If a later
+                // step here throws (e.g. the metadata persist below), the catch path
+                // must still fall through to `process.exit(98)`; otherwise the app row
+                // sits on the new template while the pod keeps the old runtime and
+                // nothing respawns it. Set after the flip *await* so a thrown flip
+                // (which never skipped termination) still leaves this false -- the pod
+                // stays on the pre-flip template instead of respawning half-migrated.
+                shouldSelfRestart = willSelfRestart;
+                await persistMigrationStateMetadata(stateFilePath, {
+                    backupCommitId,
+                    migrationCommitId: flip.commitId,
+                });
+                logger.info("[migrate-route] Template flip complete", {
+                    migrationCommitId: flip.commitId,
+                });
+                recordMigrationStage("flip", "success");
+                markMigrationRunStage(runSpan, "flip", "success");
+                // After the flip, the SABS pod restarts and this process is
+                // replaced. If by chance we survive, leave in-memory status at
+                // `done` — the GET endpoint will derive `translating` /
+                // `done_with_unresolved` from disk once Clark starts work.
+                inMemoryStatus = {
+                    state: "done",
+                    backupCommitId,
+                    migrationCommitId: flip.commitId,
+                    startedAt: inMemoryStatus.startedAt,
+                };
+            }
+            catch (error) {
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                const failedStage = restructured
+                    ? "flip"
+                    : backupCommitId
+                        ? "restructure"
+                        : "backup";
+                logger.error("[migrate-route] Migration failed", getErrorMeta(error));
+                logger.info("[migrate-route] Migration context", {
+                    stage: failedStage,
+                    backupCommitId,
+                    restructured,
+                });
+                recordMigrationStage(failedStage, "failure");
+                markMigrationRunStage(runSpan, failedStage, "failure");
+                runFailedStage = failedStage;
+                runError = error;
+                inMemoryStatus = {
+                    state: "failed",
+                    error: `Upgrade failed at ${failedStage} stage: ${errorMsg}`,
+                    backupCommitId,
+                    startedAt: inMemoryStatus.startedAt,
+                };
+            }
+            finally {
+                endMigrationRunSpan(runSpan, {
+                    failedStage: runFailedStage,
+                    error: runError,
+                });
+                if (!shouldSelfRestart) {
+                    if (autoSyncPaused) {
+                        try {
+                            syncService.resumeAutoSync();
+                        }
+                        catch (error) {
+                            logger.warn("[migrate-route] Failed to resume autosync after migration attempt", {
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                    }
+                    if (watcherPaused) {
+                        try {
+                            server.watcher.add(appRootDir);
+                        }
+                        catch (error) {
+                            logger.warn("[migrate-route] Failed to rewatch app root after migration attempt", {
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                    }
+                }
+            }
+            // Trigger the in-place restart after the try/finally. When self-restarting,
+            // autosync and the watcher stay paused so we do not enqueue work during exit.
+            // The 202 response was already sent and all migration-state writes were
+            // awaited, so exiting here loses no data. The CLI parent supervisor respawns
+            // the child with the flipped template; the editor reconnects to the same
+            // pod/port.
+            if (shouldSelfRestart) {
+                await requestSelfRestart(logger, prepareInPlaceRestart);
+            }
+        })();
+    });
+    server.middlewares.use("/sb-migration-retry-unresolved", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-retry-unresolved", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized())
+                return next();
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type",
+            })) {
+                return;
+            }
+            res.setHeader("Content-Type", "application/json");
+            try {
+                const result = await retryFailedSeedApiItemsFromChecklist(appRootDir);
+                // Wipe each retried API's on-disk verification history so the next
+                // runMigrationVerification call doesn't immediately return
+                // `kind: "exhausted"` from the prior cap-hit run, making this retry
+                // a no-op. Best-effort: missing files are not an error.
+                await Promise.all(result.retriedApiNames.map((apiName) => clearVerificationHistory(appRootDir, apiName)));
+                logger.info("[migrate-route] retry-unresolved flipped items", {
+                    retriedCount: result.retriedCount,
+                    retriedApiNames: result.retriedApiNames,
+                });
+                const status = await resolveStatus(appRootDir, {
+                    ignoreInMemory: true,
+                });
+                res.statusCode = 200;
+                res.end(JSON.stringify({
+                    ok: true,
+                    retriedCount: result.retriedCount,
+                    status,
+                }));
+            }
+            catch (error) {
+                logger.error("[migrate-route] /sb-migration-retry-unresolved failed", getErrorMeta(error));
+                res.statusCode = 500;
+                res.end(JSON.stringify({
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+        })();
+    });
+    server.middlewares.use("/sb-migration-complete", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-complete", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized()) {
+                return next();
+            }
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type",
+            })) {
+                return;
+            }
+            if (!syncService) {
+                res.statusCode = 503;
+                res.end(JSON.stringify({
+                    error: "Upgrade completion is unavailable: the dev server was started without a SyncService.",
+                }));
+                return;
+            }
+            const status = await resolveStatus(appRootDir, { ignoreInMemory: true });
+            logger.info("[migrate-route] completion precheck status", {
+                state: status.state,
+                hasV2Backup: status.hasV2Backup,
+            });
+            if (migrationCompleteCommitInFlight) {
+                res.statusCode = 409;
+                res.end(JSON.stringify({
+                    error: "Upgrade completion is already in progress.",
+                }));
+                return;
+            }
+            // Idempotent completion. A prior finalize removes the v2 backup and
+            // scratch on disk *before* its slow completion commit, so the HTTP
+            // response can time out (504) after the migration already landed.
+            // Re-issuing the request must not 409/404 (the checklist may be gone) or
+            // trip the "nothing to commit" guard below — either would strand the user
+            // on a stuck migration banner with no way to close out. When the backup
+            // is already gone and the app is on the fullstack template, the migration
+            // has landed: acknowledge completion so the client can safely retry and
+            // close its server session. Skip while a completion commit is in flight
+            // so a concurrent retry does not return success before the commit lands.
+            if (!status.hasV2Backup && (await isAlreadyOnFullstack(appRootDir))) {
+                logger.info("[migrate-route] completion is a no-op; migration already finalized");
+                recordMigrationStage("complete", "success");
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({
+                    ok: true,
+                    alreadyComplete: true,
+                    completionCommitId: status.migrationCommitId,
+                    status,
+                }));
+                return;
+            }
+            if (status.state !== "done") {
+                res.statusCode = 409;
+                res.end(JSON.stringify({
+                    error: "Upgrade can only be completed after all APIs are upgraded successfully.",
+                    state: status.state,
+                }));
+                return;
+            }
+            // Connection-independent backstop for APPS-5109. The UI greys out the
+            // Finish CTA while Clark is mid-turn, but a stale client (slow socket)
+            // can still fire this request during the inter-turn gap and race Clark's
+            // in-flight post-migration verification. The dev server holds Clark's
+            // authoritative FSM state, so refuse completion while a turn is active
+            // or while an interactive prompt / tool permission is unresolved.
+            // Do not block on bare `AwaitingUser` — that is Clark's resting state
+            // after a completed turn while the UI shows IDLE/COMPLETED.
+            const aiService = getAiService?.();
+            if (aiService?.isBusy() || aiService?.isAwaitingInteractiveResponse()) {
+                res.statusCode = 409;
+                res.end(JSON.stringify({
+                    error: aiService?.isAwaitingInteractiveResponse()
+                        ? "Clark is waiting for your reply. Resolve the prompt in the chat before finishing the migration."
+                        : "Clark is still finishing the migration. Try again in a moment.",
+                    state: status.state,
+                }));
+                return;
+            }
+            const checklist = await readPersistedChecklist(appRootDir);
+            if (!checklist) {
+                res.statusCode = 404;
+                res.end(JSON.stringify({
+                    error: "Upgrade checklist not found.",
+                }));
+                return;
+            }
+            const shouldMarkChecklistCompleted = checklist.overallStatus !== "completed";
+            if (shouldMarkChecklistCompleted) {
+                await markChecklistCompleted({
+                    appRootDirPath: appRootDir,
+                });
+                logger.info("[migrate-route] marked checklist as completed");
+            }
+            const clearedUpgradeItems = await clearChecklistItemsByOrigin({
+                appRootDirPath: appRootDir,
+                origins: Array.from(API_MIGRATION_ORIGINS),
+            });
+            const checklistAfterCompletion = await readPersistedChecklist(appRootDir);
+            if (clearedUpgradeItems.removedCount > 0) {
+                logger.info("[migrate-route] removed API migration checklist items", {
+                    removedCount: clearedUpgradeItems.removedCount,
+                    remainingCount: clearedUpgradeItems.remainingCount,
+                });
+            }
+            await rm(join(appRootDir, SCRATCH_DIR_NAME, "v2-backup"), {
+                recursive: true,
+                force: true,
+            });
+            await rm(join(appRootDir, SCRATCH_DIR_NAME), {
+                recursive: true,
+                force: true,
+            });
+            logger.info("[migrate-route] removed scratch directory");
+            migrationCompleteCommitInFlight = true;
+            let completionCommit;
+            try {
+                completionCommit =
+                    await syncService.commitLocalDraftChanges("migrate:complete");
+            }
+            finally {
+                migrationCompleteCommitInFlight = false;
+            }
+            if (!completionCommit?.commitId) {
+                throw new Error("Upgrade completion checkpoint was not created; aborting completion flow.");
+            }
+            logger.info("[migrate-route] Completion checkpoint created", {
+                completionCommitId: completionCommit.commitId,
+            });
+            recordMigrationStage("complete", "success");
+            inMemoryStatus = {
+                state: "done",
+                startedAt: status.startedAt,
+                backupCommitId: status.backupCommitId,
+                migrationCommitId: status.migrationCommitId,
+            };
+            const updatedStatus = {
+                state: "done",
+                startedAt: status.startedAt,
+                backupCommitId: status.backupCommitId,
+                migrationCommitId: status.migrationCommitId,
+                hasV2Backup: false,
+                ...(checklistAfterCompletion && {
+                    checklist: {
+                        overallStatus: checklistAfterCompletion.overallStatus,
+                        items: checklistAfterCompletion.items,
+                        lastUpdated: checklistAfterCompletion.lastUpdated,
+                    },
+                }),
+            };
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({
+                ok: true,
+                completionCommitId: completionCommit.commitId,
+                status: updatedStatus,
+            }));
+        })().catch((error) => {
+            recordMigrationStage("complete", "failure");
+            logger.error("[migrate-route] /sb-migration-complete failed", getErrorMeta(error));
+            res.statusCode = 500;
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    });
+    server.middlewares.use("/sb-migration-set-write-policy", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-set-write-policy", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized())
+                return next();
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type",
+            }))
+                return;
+            const body = req.body;
+            const parsedPolicy = parseIntegrationWritePolicy(body?.policy, {
+                required: true,
+            });
+            if (!parsedPolicy.ok) {
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({ error: parsedPolicy.error }));
+                return;
+            }
+            const scratchDirPath = join(appRootDir, SCRATCH_DIR_NAME);
+            const stateFilePath = join(scratchDirPath, MIGRATION_STATE_FILE);
+            let parsed;
+            try {
+                parsed = JSON.parse(await readFile(stateFilePath, "utf-8"));
+            }
+            catch {
+                parsed = {};
+            }
+            parsed.integrationWritePolicy = parsedPolicy.policy;
+            await mkdir(scratchDirPath, { recursive: true });
+            await writeFile(stateFilePath, JSON.stringify(parsed, null, 2) + "\n", "utf-8");
+            const status = await resolveStatus(appRootDir);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ ok: true, status }));
+        })().catch((error) => {
+            logger.error("[migrate-route] /sb-migration-set-write-policy failed", getErrorMeta(error));
+            res.statusCode = 500;
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    });
+    server.middlewares.use("/sb-migration-set-verification-outcome", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-set-verification-outcome", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized())
+                return next();
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type",
+            }))
+                return;
+            const body = req.body;
+            const { apiName, outcome } = body ?? {};
+            if (typeof apiName !== "string" ||
+                !/^[a-zA-Z0-9_-]+$/.test(apiName) ||
+                (outcome !== "user_manually_verified" &&
+                    outcome !== "diverged_user_accepted")) {
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({
+                    error: "apiName (string) and outcome ('user_manually_verified' | 'diverged_user_accepted') required",
+                }));
+                return;
+            }
+            // User-driven outcomes (manual verify, accept divergence) are terminal
+            // resolutions of the verification step. Force the item to "completed"
+            // so `classifyItem` puts it in the verified group and the Finish
+            // Migration gate unblocks. Without this, a `failed` item that the user
+            // accepts via "Accept divergence" would stay in `needs_review` because
+            // `classifyItem` short-circuits on `status === "failed"` before
+            // inspecting `verificationOutcome`.
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                status: "completed",
+                verificationOutcome: outcome,
+                ...(outcome === "user_manually_verified" && {
+                    verificationSkippedReason: null,
+                }),
+                lastVerificationAt: new Date().toISOString(),
+            });
+            const status = await resolveStatus(appRootDir);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ ok: true, status }));
+        })().catch((error) => {
+            logger.error("[migrate-route] /sb-migration-set-verification-outcome failed", getErrorMeta(error));
+            res.statusCode = 500;
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    });
+    server.middlewares.use("/sb-migration-retry-api", bodyParser.json({ strict: true }));
+    server.middlewares.use("/sb-migration-retry-api", (req, res, next) => {
+        void (async () => {
+            if (!getIsInitialized())
+                return next();
+            if (!setupCorsAndValidateMethod({
+                req,
+                res,
+                allowedMethod: "POST",
+                allowHeaders: "Content-Type",
+            }))
+                return;
+            const body = req.body;
+            const apiName = body?.apiName;
+            if (typeof apiName !== "string" || !/^[a-zA-Z0-9_-]+$/.test(apiName)) {
+                res.statusCode = 400;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({
+                    error: "apiName must be a non-empty string containing only letters, digits, hyphens, or underscores",
+                }));
+                return;
+            }
+            await updateChecklistItem({
+                appRootDirPath: appRootDir,
+                itemId: `api_${apiName}`,
+                status: "pending",
+                verificationOutcome: null,
+                verificationSkippedReason: null,
+                lastVerificationAt: new Date().toISOString(),
+            });
+            // Wipe this API's verification history so the next
+            // runMigrationVerification call starts from a clean slate. Without
+            // this, an item that hit MAX_VERIFICATION_ATTEMPTS would immediately
+            // return `kind: "exhausted"` on retry and the click would be a no-op.
+            await clearVerificationHistory(appRootDir, apiName);
+            const status = await resolveStatus(appRootDir);
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ ok: true, status }));
+        })().catch((error) => {
+            logger.error("[migrate-route] /sb-migration-retry-api failed", getErrorMeta(error));
+            res.statusCode = 500;
+            res.end(JSON.stringify({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    });
+    void rehydrateMigrationScratchOnBoot({
+        appRootDir,
+        syncService,
+        logger,
+    });
+    void reconcileMigrationSessionOnBoot({
+        appRootDir,
+        syncService,
+        logger,
+    });
+}
+async function isAlreadyOnFullstack(appRootDir) {
+    const [hasClient, hasServerApisIndex] = await Promise.all([
+        pathExists(join(appRootDir, "client")),
+        pathExists(join(appRootDir, "server", "apis", "index.ts")),
+    ]);
+    return hasClient && hasServerApisIndex;
+}
+//# sourceMappingURL=migration-routes.js.map