modules/admin: refactor migration with polling-based progress UI

- Add dedicated /admin/migrate page with real-time log viewer
- Create migration-state.server.ts for server-side state management
- Add shared types in $lib/shared/types/migration.ts
- Implement polling mechanism for progress updates
- Remove migration button from QuickActions (use dedicated page)
- Use valibot validation instead of type assertions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: aster-void

src/lib/components/admin-dashboard/QuickActions.svelte

@@ -1,45 +1,5 @@
 <script lang="ts">
-  import { Zap, UserPlus, Pencil, Folder, DatabaseBackup, Loader2 } from "lucide-svelte";
-  import { runMigration } from "$lib/data/private/migration.remote";
-
-  let migrationState = $state<"idle" | "running" | "success" | "error">("idle");
-  let migrationResult = $state<string>("");
-
-  async function handleMigration() {
-    if (
-      !confirm("Import data from the old utcode.net repository?\nExisting entries will be skipped.")
-    ) {
-      return;
-    }
-
-    migrationState = "running";
-    migrationResult = "";
-
-    try {
-      const result = await runMigration();
-      migrationState = "success";
-      migrationResult = [
-        `Members: ${result.members.created} created, ${result.members.skipped} skipped`,
-        `Articles: ${result.articles.created} created, ${result.articles.skipped} skipped`,
-        `Projects: ${result.projects.created} created, ${result.projects.skipped} skipped`,
-      ].join("\n");
-
-      const allErrors = [
-        ...result.members.errors,
-        ...result.articles.errors,
-        ...result.projects.errors,
-      ];
-      if (allErrors.length > 0) {
-        migrationResult += `\n\nErrors:\n${allErrors.slice(0, 5).join("\n")}`;
-        if (allErrors.length > 5) {
-          migrationResult += `\n... and ${allErrors.length - 5} more`;
-        }
-      }
-    } catch (e) {
-      migrationState = "error";
-      migrationResult = e instanceof Error ? e.message : String(e);
-    }
-  }
+  import { Zap, UserPlus, Pencil, Folder } from "lucide-svelte";
 </script>
 
 <section class="animate-fade-slide-in stagger-5">
@@ -71,28 +31,5 @@
       <Folder class="h-4 w-4" />
       New Project
     </a>
-    <button
-      onclick={handleMigration}
-      disabled={migrationState === "running"}
-      class="btn gap-2 border-base-300 bg-base-100 font-medium transition-all hover:border-warning/30 hover:bg-warning/5 hover:text-warning disabled:opacity-50"
-    >
-      {#if migrationState === "running"}
-        <Loader2 class="h-4 w-4 animate-spin" />
-        Migrating...
-      {:else}
-        <DatabaseBackup class="h-4 w-4" />
-        Import Legacy Data
-      {/if}
-    </button>
   </div>
-
-  {#if migrationResult}
-    <div
-      class="mt-4 rounded-lg p-4 text-sm whitespace-pre-wrap {migrationState === 'success'
-        ? 'bg-success/10 text-success'
-        : 'bg-error/10 text-error'}"
-    >
-      {migrationResult}
-    </div>
-  {/if}
 </section>

src/lib/data/private/migration.remote.ts

@@ -1,8 +1,23 @@
-import { command } from "$app/server";
+import { command, query } from "$app/server";
 import { requireUtCodeMember } from "$lib/server/database/auth.server";
-import { runDataMigration, type MigrationResult } from "$lib/server/services/migration.server";
+import { startDataMigration } from "$lib/server/services/migration.server";
+import {
+  getMigrationState,
+  resetMigration,
+  type MigrationState,
+} from "$lib/server/services/migration-state.server";
 
-export const runMigration = command(async (): Promise<MigrationResult> => {
+export const start = command(async (): Promise<{ started: boolean; message: string }> => {
   await requireUtCodeMember();
-  return runDataMigration();
+  return startDataMigration();
+});
+
+export const getStatus = query(async (): Promise<MigrationState> => {
+  await requireUtCodeMember();
+  return getMigrationState();
+});
+
+export const reset = command(async (): Promise<void> => {
+  await requireUtCodeMember();
+  resetMigration();
 });

src/lib/server/services/migration-state.server.ts

@@ -0,0 +1,58 @@
+/**
+ * Migration state manager - holds stdout/stderr buffer for polling
+ */
+
+import type { MigrationState } from "$lib/shared/types/migration";
+
+export type { MigrationState };
+
+const initialState: MigrationState = {
+  status: "idle",
+  logs: [],
+  startedAt: null,
+  completedAt: null,
+  result: null,
+  error: null,
+};
+
+// Singleton state
+let state: MigrationState = { ...initialState };
+
+export function getMigrationState(): MigrationState {
+  return { ...state, logs: [...state.logs] };
+}
+
+export function isRunning(): boolean {
+  return state.status === "running";
+}
+
+export function startMigration(): void {
+  state = {
+    status: "running",
+    logs: [],
+    startedAt: new Date(),
+    completedAt: null,
+    result: null,
+    error: null,
+  };
+}
+
+export function log(message: string): void {
+  state.logs.push(`[${new Date().toISOString().slice(11, 19)}] ${message}`);
+}
+
+export function completeMigration(result: MigrationState["result"]): void {
+  state.status = "completed";
+  state.completedAt = new Date();
+  state.result = result;
+}
+
+export function failMigration(error: string): void {
+  state.status = "error";
+  state.completedAt = new Date();
+  state.error = error;
+}
+
+export function resetMigration(): void {
+  state = { ...initialState };
+}

src/lib/server/services/migration.server.ts

@@ -20,15 +20,16 @@ import {
   projectMember,
   type ProjectCategory,
 } from "$lib/shared/models/schema";
+import {
+  log,
+  startMigration,
+  completeMigration,
+  failMigration,
+  isRunning,
+} from "./migration-state.server";
 
 const REPO_URL = "https://github.com/ut-code/utcode.net.git";
 
-export interface MigrationResult {
-  members: { created: number; skipped: number; errors: string[] };
-  articles: { created: number; skipped: number; errors: string[] };
-  projects: { created: number; skipped: number; errors: string[] };
-}
-
 async function runCommand(cmd: string, args: string[], cwd?: string): Promise<void> {
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, { cwd, stdio: "pipe" });
@@ -46,7 +47,9 @@ async function runCommand(cmd: string, args: string[], cwd?: string): Promise<vo
 
 async function cloneRepo(): Promise<string> {
   const tempDir = join(tmpdir(), `utcode-migration-${Date.now()}`);
+  log(`Cloning ${REPO_URL}...`);
   await runCommand("git", ["clone", "--depth", "1", REPO_URL, tempDir]);
+  log("Repository cloned successfully");
   return tempDir;
 }
 
@@ -99,12 +102,15 @@ const MemberFrontmatterSchema = v.object({
 
 async function migrateMembers(
   repoPath: string,
-): Promise<{ created: number; skipped: number; errors: string[] }> {
+): Promise<{ created: number; skipped: number; errors: number }> {
+  log("--- Migrating Members ---");
   const membersPath = join(repoPath, "contents/members");
   const files = await findMarkdownFiles(membersPath);
+  log(`Found ${files.length} member files`);
+
   let created = 0;
   let skipped = 0;
-  const errors: string[] = [];
+  let errorCount = 0;
 
   for (const file of files) {
     const relPath = file.replace(membersPath + "/", "");
@@ -124,6 +130,7 @@ async function migrateMembers(
         .limit(1);
 
       if (existing.length > 0) {
+        log(`  ⊘ Skipped: ${slug} (already exists)`);
         skipped++;
         continue;
       }
@@ -143,13 +150,17 @@ async function migrateMembers(
         pageContent: body || null,
       });
 
+      log(`  ✓ Created: ${slug} (${frontmatter.nameJa})`);
       created++;
     } catch (e) {
-      errors.push(`${slug}: ${e instanceof Error ? e.message : String(e)}`);
+      const msg = e instanceof Error ? e.message : String(e);
+      log(`  ✗ Error: ${slug} - ${msg}`);
+      errorCount++;
     }
   }
 
-  return { created, skipped, errors };
+  log(`Members: ${created} created, ${skipped} skipped, ${errorCount} errors`);
+  return { created, skipped, errors: errorCount };
 }
 
 // Article migration
@@ -185,12 +196,15 @@ function generateExcerpt(content: string, maxLength = 200): string {
 
 async function migrateArticles(
   repoPath: string,
-): Promise<{ created: number; skipped: number; errors: string[] }> {
+): Promise<{ created: number; skipped: number; errors: number }> {
+  log("--- Migrating Articles ---");
   const articlesPath = join(repoPath, "contents/articles");
   const files = await findMarkdownFiles(articlesPath);
+  log(`Found ${files.length} article files`);
+
   let created = 0;
   let skipped = 0;
-  const errors: string[] = [];
+  let errorCount = 0;
 
   for (const file of files) {
     const relPath = file.replace(articlesPath + "/", "");
@@ -208,6 +222,7 @@ async function migrateArticles(
         .limit(1);
 
       if (existing.length > 0) {
+        log(`  ⊘ Skipped: ${slug} (already exists)`);
         skipped++;
         continue;
       }
@@ -238,13 +253,17 @@ async function migrateArticles(
         viewCount: 0,
       });
 
+      log(`  ✓ Created: ${slug}`);
       created++;
     } catch (e) {
-      errors.push(`${slug}: ${e instanceof Error ? e.message : String(e)}`);
+      const msg = e instanceof Error ? e.message : String(e);
+      log(`  ✗ Error: ${slug} - ${msg}`);
+      errorCount++;
     }
   }
 
-  return { created, skipped, errors };
+  log(`Articles: ${created} created, ${skipped} skipped, ${errorCount} errors`);
+  return { created, skipped, errors: errorCount };
 }
 
 // Project migration
@@ -279,12 +298,15 @@ function mapCategory(kind: string | undefined): ProjectCategory {
 
 async function migrateProjects(
   repoPath: string,
-): Promise<{ created: number; skipped: number; errors: string[] }> {
+): Promise<{ created: number; skipped: number; errors: number }> {
+  log("--- Migrating Projects ---");
   const projectsPath = join(repoPath, "contents/projects");
   const files = await findMarkdownFiles(projectsPath);
+  log(`Found ${files.length} project files`);
+
   let created = 0;
   let skipped = 0;
-  const errors: string[] = [];
+  let errorCount = 0;
 
   for (const file of files) {
     const dirPath = dirname(file);
@@ -303,6 +325,7 @@ async function migrateProjects(
         .limit(1);
 
       if (existing.length > 0) {
+        log(`  ⊘ Skipped: ${slug} (already exists)`);
         skipped++;
         continue;
       }
@@ -344,16 +367,34 @@ async function migrateProjects(
         }
       }
 
+      log(`  ✓ Created: ${slug} (${name})`);
       created++;
     } catch (e) {
-      errors.push(`${slug}: ${e instanceof Error ? e.message : String(e)}`);
+      const msg = e instanceof Error ? e.message : String(e);
+      log(`  ✗ Error: ${slug} - ${msg}`);
+      errorCount++;
     }
   }
 
-  return { created, skipped, errors };
+  log(`Projects: ${created} created, ${skipped} skipped, ${errorCount} errors`);
+  return { created, skipped, errors: errorCount };
+}
+
+export function startDataMigration(): { started: boolean; message: string } {
+  if (isRunning()) {
+    return { started: false, message: "Migration already in progress" };
+  }
+
+  startMigration();
+  log("=== Data Migration Started ===");
+
+  // Run migration in background (fire and forget with proper error handling)
+  runMigrationAsync().catch(console.error);
+
+  return { started: true, message: "Migration started" };
 }
 
-export async function runDataMigration(): Promise<MigrationResult> {
+async function runMigrationAsync(): Promise<void> {
   let repoPath: string | null = null;
 
   try {
@@ -365,10 +406,16 @@ export async function runDataMigration(): Promise<MigrationResult> {
     const articles = await migrateArticles(repoPath);
     const projects = await migrateProjects(repoPath);
 
-    return { members, articles, projects };
+    log("=== Migration Complete ===");
+    completeMigration({ members, articles, projects });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    log(`=== Migration Failed: ${msg} ===`);
+    failMigration(msg);
   } finally {
     // Cleanup
     if (repoPath) {
+      log("Cleaning up temporary files...");
       await rm(repoPath, { recursive: true, force: true }).catch(() => {});
     }
   }

src/lib/shared/types/migration.ts

@@ -0,0 +1,14 @@
+export type MigrationStatus = "idle" | "running" | "completed" | "error";
+
+export interface MigrationState {
+  status: MigrationStatus;
+  logs: string[];
+  startedAt: Date | null;
+  completedAt: Date | null;
+  result: {
+    members: { created: number; skipped: number; errors: number };
+    articles: { created: number; skipped: number; errors: number };
+    projects: { created: number; skipped: number; errors: number };
+  } | null;
+  error: string | null;
+}