@superblocksteam/vite-plugin-file-sync 2.0.114 → 2.0.115-next.1

package/dist/migration/get-fullstack-template-dir.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Absolute path to the bundled `app-fullstack` template tree that the
+ * v2 -> v3 migration lays down locally before asking the server to flip
+ * `application_v2.template_name`.
+ *
+ * Resolution walks up from the compiled module's directory and at each
+ * level checks two candidates:
+ *   1. `migration-templates/app-fullstack` -- the bundled location
+ *      populated by
+ *      `packages/vite-plugin-file-sync/scripts/copy-migration-templates.mjs`
+ *      and by the CLI's own post-esbuild copy step. This is what the
+ *      published packages rely on.
+ *   2. `packages/demo-apps/app-fullstack` -- the monorepo dev fallback
+ *      used when tests run from source (tsx/vitest) before a bundled
+ *      copy exists.
+ *
+ * The walk handles several layouts without special-casing:
+ *   - `<pkg>/dist/migration/get-fullstack-template-dir.js` (plugin's
+ *     own compiled output) finds the bundled tree one level up.
+ *   - `<cli>/dist/chunk-XYZ.js` (esbuild-bundled into the CLI) finds
+ *     the bundled tree in the same dir, because the CLI build copies
+ *     it into `<cli>/dist/migration-templates/app-fullstack`.
+ *   - `<repo>/packages/.../src/migration/get-fullstack-template-dir.ts`
+ *     (tsx dev run) walks up to `<repo>` and finds the workspace copy.
+ *
+ * Throws if no candidate exists -- the restructure module cannot
+ * proceed without a template and it is better to fail here with a clear
+ * error than to half-migrate an app.
+ */
+export declare function getFullstackTemplateDir(): string;
+/**
+ * Pure lookup: walk up from `startDir` and return the first existing
+ * candidate. Exported for tests so we can drive the walk against a
+ * synthetic filesystem without mocking `import.meta.url`.
+ */
+export declare function findFullstackTemplate(startDir: string): string | null;
+//# sourceMappingURL=get-fullstack-template-dir.d.ts.map

package/dist/migration/get-fullstack-template-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-fullstack-template-dir.d.ts","sourceRoot":"","sources":["../../src/migration/get-fullstack-template-dir.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAahD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYrE"}

package/dist/migration/get-fullstack-template-dir.js

@@ -0,0 +1,99 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// Subdirectories to look for at each walk level. Order matters: a bundled
+// `migration-templates/app-fullstack` beats the monorepo workspace copy
+// so a published CLI/plugin does not silently fall back to a sibling
+// checkout if both happen to exist (e.g. when running tests from source
+// after `pnpm build`).
+const CANDIDATE_SUBPATHS = [
+    "migration-templates/app-fullstack",
+    "packages/demo-apps/app-fullstack",
+];
+// How far up the filesystem to walk. 12 comfortably covers the deepest
+// real layout we have today (bundled CLI dist nested inside
+// `/.npm-global/lib/node_modules/@superblocksteam/cli/dist/...`) while
+// still failing fast on a malformed FS.
+const MAX_WALK_HOPS = 12;
+/**
+ * Absolute path to the bundled `app-fullstack` template tree that the
+ * v2 -> v3 migration lays down locally before asking the server to flip
+ * `application_v2.template_name`.
+ *
+ * Resolution walks up from the compiled module's directory and at each
+ * level checks two candidates:
+ *   1. `migration-templates/app-fullstack` -- the bundled location
+ *      populated by
+ *      `packages/vite-plugin-file-sync/scripts/copy-migration-templates.mjs`
+ *      and by the CLI's own post-esbuild copy step. This is what the
+ *      published packages rely on.
+ *   2. `packages/demo-apps/app-fullstack` -- the monorepo dev fallback
+ *      used when tests run from source (tsx/vitest) before a bundled
+ *      copy exists.
+ *
+ * The walk handles several layouts without special-casing:
+ *   - `<pkg>/dist/migration/get-fullstack-template-dir.js` (plugin's
+ *     own compiled output) finds the bundled tree one level up.
+ *   - `<cli>/dist/chunk-XYZ.js` (esbuild-bundled into the CLI) finds
+ *     the bundled tree in the same dir, because the CLI build copies
+ *     it into `<cli>/dist/migration-templates/app-fullstack`.
+ *   - `<repo>/packages/.../src/migration/get-fullstack-template-dir.ts`
+ *     (tsx dev run) walks up to `<repo>` and finds the workspace copy.
+ *
+ * Throws if no candidate exists -- the restructure module cannot
+ * proceed without a template and it is better to fail here with a clear
+ * error than to half-migrate an app.
+ */
+export function getFullstackTemplateDir() {
+    const hereDir = dirname(fileURLToPath(import.meta.url));
+    const resolved = findFullstackTemplate(hereDir);
+    if (resolved)
+        return resolved;
+    const searched = enumerateSearchedPaths(hereDir);
+    throw new Error(`Could not locate the app-fullstack migration template. Searched (in order):\n${searched
+        .map((p) => `  - ${p}`)
+        .join("\n")}\nRun 'pnpm --filter @superblocksteam/vite-plugin-file-sync build' and, for the published CLI, 'pnpm --filter @superblocksteam/cli build' to populate a bundled copy, or make sure packages/demo-apps/app-fullstack is checked out.`);
+}
+/**
+ * Pure lookup: walk up from `startDir` and return the first existing
+ * candidate. Exported for tests so we can drive the walk against a
+ * synthetic filesystem without mocking `import.meta.url`.
+ */
+export function findFullstackTemplate(startDir) {
+    let current = startDir;
+    for (let hops = 0; hops < MAX_WALK_HOPS; hops++) {
+        for (const sub of CANDIDATE_SUBPATHS) {
+            const candidate = join(current, sub);
+            if (isUsableDir(candidate))
+                return candidate;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function enumerateSearchedPaths(startDir) {
+    const paths = [];
+    let current = startDir;
+    for (let hops = 0; hops < MAX_WALK_HOPS; hops++) {
+        for (const sub of CANDIDATE_SUBPATHS) {
+            paths.push(join(current, sub));
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return paths;
+}
+function isUsableDir(dirPath) {
+    try {
+        return existsSync(dirPath) && statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=get-fullstack-template-dir.js.map

package/dist/migration/get-fullstack-template-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-fullstack-template-dir.js","sourceRoot":"","sources":["../../src/migration/get-fullstack-template-dir.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,0EAA0E;AAC1E,wEAAwE;AACxE,qEAAqE;AACrE,wEAAwE;AACxE,uBAAuB;AACvB,MAAM,kBAAkB,GAAsB;IAC5C,mCAAmC;IACnC,kCAAkC;CACnC,CAAC;AAEF,uEAAuE;AACvE,4DAA4D;AAC5D,uEAAuE;AACvE,wCAAwC;AACxC,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,IAAI,KAAK,CACb,gFAAgF,QAAQ;SACrF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;SACtB,IAAI,CACH,IAAI,CACL,qOAAqO,CACzO,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,IAAI,OAAO,GAAG,QAAQ,CAAC;IACvB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC;QAChD,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;YACrC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YACrC,IAAI,WAAW,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QAC/C,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO;YAAE,MAAM;QAC9B,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,sBAAsB,CAAC,QAAgB;IAC9C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,QAAQ,CAAC;IACvB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC;QAChD,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;YACrC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO;YAAE,MAAM;QAC9B,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,OAAe;IAClC,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/migration/migration-checklist.d.ts

@@ -0,0 +1,60 @@
+import type { MigrationChecklistItem, MigrationChecklistOverallStatus, MigrationChecklistStatus } from "@superblocksteam/library-shared/types";
+export declare const MIGRATION_CHECKLIST_FILE = "migration-checklist.json";
+export declare const MIGRATION_CHECKLIST_VERSION = 1;
+export type { MigrationChecklistItem };
+export type ChecklistStatus = MigrationChecklistStatus;
+export interface MigrationChecklistState {
+    version: typeof MIGRATION_CHECKLIST_VERSION;
+    overallStatus: MigrationChecklistOverallStatus;
+    items: MigrationChecklistItem[];
+    lastUpdated: string;
+}
+export declare function isMigrationChecklistActive(appRootDirPath: string): Promise<boolean>;
+export declare function readMigrationChecklist(appRootDirPath: string): Promise<MigrationChecklistState | null>;
+export declare function seedMigrationChecklist(args: {
+    appRootDirPath: string;
+    apiChecklist: Array<{
+        name: string;
+        stubPath: string;
+    }>;
+}): Promise<MigrationChecklistState>;
+export declare function addMigrationChecklistItem(args: {
+    appRootDirPath: string;
+    content: string;
+    status?: ChecklistStatus;
+    origin?: MigrationChecklistItem["origin"];
+}): Promise<{
+    state: MigrationChecklistState;
+    item: MigrationChecklistItem;
+}>;
+export declare function updateMigrationChecklistItem(args: {
+    appRootDirPath: string;
+    itemId: string;
+    content?: string;
+    status?: ChecklistStatus;
+    failureReason?: string;
+}): Promise<{
+    state: MigrationChecklistState;
+    item: MigrationChecklistItem;
+}>;
+/**
+ * Flip every `seed_api` item currently in `failed` state back to
+ * `pending`, bump its `attemptCount`, and preserve the prior
+ * `failureReason` as `lastFailureReason` so the retry prompt can carry
+ * it. Used by `/sb-migration-retry-unresolved` to let the user trigger
+ * another pass once the auto-retry budget has been spent.
+ *
+ * Unlike `updateMigrationChecklistItem` this writes directly without
+ * going through the auto-retry transform — the user has already
+ * consented to an additional attempt, so budget enforcement doesn't
+ * apply.
+ */
+export declare function retryFailedSeedApiItems(appRootDirPath: string): Promise<{
+    state: MigrationChecklistState;
+    retriedCount: number;
+}>;
+export declare function getMigrationChecklistPath(appRootDirPath: string): string;
+export declare function markMigrationChecklistCompleted(args: {
+    appRootDirPath: string;
+}): Promise<MigrationChecklistState>;
+//# sourceMappingURL=migration-checklist.d.ts.map

package/dist/migration/migration-checklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-checklist.d.ts","sourceRoot":"","sources":["../../src/migration/migration-checklist.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,sBAAsB,EACtB,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,uCAAuC,CAAC;AAI/C,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AACnE,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAsB7C,YAAY,EAAE,sBAAsB,EAAE,CAAC;AACvC,MAAM,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAEvD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,2BAA2B,CAAC;IAC5C,aAAa,EAAE,+BAA+B,CAAC;IAC/C,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,0BAA0B,CAC9C,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,sBAAsB,CAC1C,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA0BzC;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAkBnC;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,sBAAsB,CAAC,QAAQ,CAAC,CAAC;CAC3C,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,CAAC,CA2B5E;AAED,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,CAAC,CA4C5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7E,KAAK,EAAE,uBAAuB,CAAC;IAC/B,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC,CA8BD;AAED,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAsB,+BAA+B,CAAC,IAAI,EAAE;IAC1D,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAYnC"}

package/dist/migration/migration-checklist.js

@@ -0,0 +1,230 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { OperationQueue } from "../util/operation-queue.js";
+export const MIGRATION_CHECKLIST_FILE = "migration-checklist.json";
+export const MIGRATION_CHECKLIST_VERSION = 1;
+const SCRATCH_DIR_NAME = "scratch";
+/**
+ * Per-app serialization of read-modify-write mutations on the shared
+ * migration checklist JSON. Parallel sub-agents (see
+ * `spawnCodingSubagents`) can otherwise race: two concurrent
+ * `build_manageChecklist` calls would both read the same snapshot,
+ * compute new state independently, and both write — losing one update.
+ *
+ * Reads (`readMigrationChecklist`) do not go through the queue.
+ */
+const mutationQueues = new Map();
+function getMutationQueue(appRootDirPath) {
+    let queue = mutationQueues.get(appRootDirPath);
+    if (!queue) {
+        queue = new OperationQueue();
+        mutationQueues.set(appRootDirPath, queue);
+    }
+    return queue;
+}
+export async function isMigrationChecklistActive(appRootDirPath) {
+    return (await readMigrationChecklist(appRootDirPath)) !== null;
+}
+export async function readMigrationChecklist(appRootDirPath) {
+    for (const checklistPath of getChecklistPathCandidates(appRootDirPath)) {
+        try {
+            const raw = await readFile(checklistPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed &&
+                parsed.version === MIGRATION_CHECKLIST_VERSION &&
+                Array.isArray(parsed.items)) {
+                return {
+                    version: MIGRATION_CHECKLIST_VERSION,
+                    overallStatus: parsed.overallStatus === "completed" ? "completed" : "active",
+                    items: parsed.items,
+                    lastUpdated: typeof parsed.lastUpdated === "string"
+                        ? parsed.lastUpdated
+                        : new Date().toISOString(),
+                };
+            }
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return null;
+}
+export async function seedMigrationChecklist(args) {
+    const now = new Date().toISOString();
+    const state = {
+        version: MIGRATION_CHECKLIST_VERSION,
+        overallStatus: "active",
+        lastUpdated: now,
+        items: args.apiChecklist.map((entry) => ({
+            id: `api_${entry.name}`,
+            content: `Port API: ${entry.name}`,
+            status: "pending",
+            createdAt: now,
+            origin: "seed_api",
+            apiName: entry.name,
+            stubPath: entry.stubPath,
+        })),
+    };
+    await writeMigrationChecklist(args.appRootDirPath, state);
+    return state;
+}
+export async function addMigrationChecklistItem(args) {
+    return getMutationQueue(args.appRootDirPath).enqueue(async () => {
+        const checklist = (await readMigrationChecklist(args.appRootDirPath)) ??
+            {
+                version: MIGRATION_CHECKLIST_VERSION,
+                items: [],
+                overallStatus: "active",
+                lastUpdated: new Date().toISOString(),
+            };
+        const item = {
+            id: `item_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+            content: args.content,
+            status: args.status ?? "pending",
+            createdAt: new Date().toISOString(),
+            origin: args.origin ?? "clark",
+        };
+        const state = {
+            ...checklist,
+            items: [...checklist.items, item],
+            lastUpdated: new Date().toISOString(),
+        };
+        await writeMigrationChecklist(args.appRootDirPath, state);
+        return { state, item };
+    });
+}
+export async function updateMigrationChecklistItem(args) {
+    return getMutationQueue(args.appRootDirPath).enqueue(async () => {
+        const checklist = await readMigrationChecklist(args.appRootDirPath);
+        if (!checklist) {
+            throw new Error("Migration checklist is not active");
+        }
+        const itemIndex = checklist.items.findIndex((item) => item.id === args.itemId);
+        if (itemIndex === -1) {
+            throw new Error(`Checklist item with ID "${args.itemId}" not found`);
+        }
+        const existingItem = checklist.items[itemIndex];
+        if (!existingItem) {
+            throw new Error(`Checklist item at index ${itemIndex} is undefined`);
+        }
+        const nextStatus = args.status ?? existingItem.status;
+        const nextFailureReason = args.failureReason ?? existingItem.failureReason;
+        // No automatic retry: a write that says `failed` is terminal.
+        // Recovery happens through the UI's "Fix with Clark" action, which
+        // calls `retryFailedSeedApiItems` to flip rows back to `pending`
+        // with a bumped `attemptCount` and the prior reason stashed as
+        // `lastFailureReason` for the retry prompt.
+        const item = {
+            ...existingItem,
+            content: args.content ?? existingItem.content,
+            status: nextStatus,
+            // Only keep failureReason when status is "failed"; clear it on any
+            // other transition so a retried item doesn't ship a stale reason.
+            failureReason: nextStatus === "failed" ? nextFailureReason : undefined,
+            updatedAt: new Date().toISOString(),
+        };
+        const items = [...checklist.items];
+        items[itemIndex] = item;
+        const state = {
+            ...checklist,
+            items,
+            lastUpdated: new Date().toISOString(),
+        };
+        await writeMigrationChecklist(args.appRootDirPath, state);
+        return { state, item };
+    });
+}
+/**
+ * Flip every `seed_api` item currently in `failed` state back to
+ * `pending`, bump its `attemptCount`, and preserve the prior
+ * `failureReason` as `lastFailureReason` so the retry prompt can carry
+ * it. Used by `/sb-migration-retry-unresolved` to let the user trigger
+ * another pass once the auto-retry budget has been spent.
+ *
+ * Unlike `updateMigrationChecklistItem` this writes directly without
+ * going through the auto-retry transform — the user has already
+ * consented to an additional attempt, so budget enforcement doesn't
+ * apply.
+ */
+export async function retryFailedSeedApiItems(appRootDirPath) {
+    return getMutationQueue(appRootDirPath).enqueue(async () => {
+        const checklist = await readMigrationChecklist(appRootDirPath);
+        if (!checklist) {
+            throw new Error("Migration checklist is not active");
+        }
+        let retriedCount = 0;
+        const now = new Date().toISOString();
+        const items = checklist.items.map((item) => {
+            if (item.origin !== "seed_api" || item.status !== "failed") {
+                return item;
+            }
+            retriedCount += 1;
+            return {
+                ...item,
+                status: "pending",
+                failureReason: undefined,
+                lastFailureReason: item.failureReason ?? item.lastFailureReason,
+                attemptCount: (item.attemptCount ?? 0) + 1,
+                updatedAt: now,
+            };
+        });
+        const state = {
+            ...checklist,
+            items,
+            lastUpdated: now,
+        };
+        await writeMigrationChecklist(appRootDirPath, state);
+        return { state, retriedCount };
+    });
+}
+export function getMigrationChecklistPath(appRootDirPath) {
+    return join(appRootDirPath, SCRATCH_DIR_NAME, MIGRATION_CHECKLIST_FILE);
+}
+export async function markMigrationChecklistCompleted(args) {
+    const checklist = await readMigrationChecklist(args.appRootDirPath);
+    if (!checklist) {
+        throw new Error("Migration checklist is not active");
+    }
+    const state = {
+        ...checklist,
+        overallStatus: "completed",
+        lastUpdated: new Date().toISOString(),
+    };
+    await writeMigrationChecklist(args.appRootDirPath, state);
+    return state;
+}
+async function writeMigrationChecklist(appRootDirPath, state) {
+    const checklistPath = await resolveChecklistPathForWrite(appRootDirPath);
+    await writeFile(checklistPath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+function getChecklistPathCandidates(appRootDirPath) {
+    const primary = getMigrationChecklistPath(appRootDirPath);
+    const parentCandidate = getMigrationChecklistPath(dirname(appRootDirPath));
+    if (primary === parentCandidate) {
+        return [primary];
+    }
+    return [primary, parentCandidate];
+}
+async function resolveChecklistPathForWrite(appRootDirPath) {
+    const candidates = getChecklistPathCandidates(appRootDirPath);
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            // Keep checking.
+        }
+    }
+    for (const candidate of candidates) {
+        try {
+            await access(dirname(candidate));
+            return candidate;
+        }
+        catch {
+            // Keep checking.
+        }
+    }
+    return candidates[0] ?? getMigrationChecklistPath(appRootDirPath);
+}
+//# sourceMappingURL=migration-checklist.js.map

package/dist/migration/migration-checklist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-checklist.js","sourceRoot":"","sources":["../../src/migration/migration-checklist.ts"],"names":[],"mappings":"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"}

package/dist/migration/migration-routes.d.ts

@@ -0,0 +1,23 @@
+import type { ViteDevServer } from "vite";
+import type { SyncService } from "../sync-service/index.js";
+import { type Logger } from "../util/logger.js";
+export interface MigrationRoutesOptions {
+    /**
+     * The Vite `config.root` (== the user's app root). The migration
+     * restructures this tree in place, so it MUST be the real on-disk
+     * root, not a logical alias.
+     */
+    appRootDir: string;
+    getIsInitialized: () => boolean;
+    syncService: SyncService | undefined;
+    logger: Logger;
+    /**
+     * The Vite config root (usually `appRootDir` or `appRootDir/client`).
+     * Used to unwatch/re-watch the file tree around the restructure step
+     * so Vite's chokidar watcher doesn't process thousands of interim
+     * file-change events that crash the dev server.
+     */
+    viteRoot: string;
+}
+export declare function registerMigrationRoutes(server: ViteDevServer, options: MigrationRoutesOptions): void;
+//# sourceMappingURL=migration-routes.d.ts.map

package/dist/migration/migration-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-routes.d.ts","sourceRoot":"","sources":["../../src/migration/migration-routes.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAO1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAmB9D,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC,WAAW,EAAE,WAAW,GAAG,SAAS,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0OD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CA+cN"}