@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/init.ts

@@ -0,0 +1,1011 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+import { type CommandContext, type CommandResult } from "./registry";
+
+type MigrationFramework = "next" | "remix" | "sveltekit";
+type InitMode = "incremental" | "side-by-side";
+type InitBridge = "react" | "none";
+type InitFormat = "text" | "json";
+
+interface InitOptions {
+  framework: MigrationFramework;
+  mode: InitMode;
+  bridge: InitBridge;
+  outDir: string;
+  dryRun: boolean;
+  format: InitFormat;
+}
+
+interface RouteMapping {
+  sourcePath: string;
+  frameworkPath: string;
+  auroraPath: string;
+  targetFiles: readonly string[];
+  convention: string;
+}
+
+interface MigrationChecklistItem {
+  id: string;
+  text: string;
+}
+
+interface MigrationScanResult {
+  framework: MigrationFramework;
+  routes: readonly RouteMapping[];
+  loaderCandidates: number;
+  actionCandidates: number;
+  warnings: readonly string[];
+}
+
+interface GeneratedScaffoldFile {
+  path: string;
+  content: string;
+}
+
+interface InitMigrationReport {
+  mode: "init-migration";
+  projectRoot: string;
+  framework: MigrationFramework;
+  migrationMode: InitMode;
+  bridge: InitBridge;
+  outDir: string;
+  dryRun: boolean;
+  detectedRoutes: number;
+  loaderCandidates: number;
+  actionCandidates: number;
+  mappedRoutes: readonly RouteMapping[];
+  checklist: readonly MigrationChecklistItem[];
+  warnings: readonly string[];
+  generatedFiles: readonly string[];
+}
+
+const VALID_FRAMEWORKS: readonly MigrationFramework[] = ["next", "remix", "sveltekit"];
+const VALID_MODES: readonly InitMode[] = ["incremental", "side-by-side"];
+const VALID_BRIDGES: readonly InitBridge[] = ["react", "none"];
+const DEFAULT_OUT_DIR = ".aurora/migration";
+const CODE_FILE_PATTERN = /\.[cm]?[jt]sx?$/;
+const IGNORED_DIRECTORIES = new Set([
+  ".git",
+  ".next",
+  ".nuxt",
+  ".aurora",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "target",
+]);
+
+function parseFramework(value: string | undefined): MigrationFramework | CommandResult {
+  if (!value) {
+    return {
+      exitCode: 2,
+      stderr: `aurora init: --from requires ${VALID_FRAMEWORKS.join("|")}`,
+    };
+  }
+
+  if (VALID_FRAMEWORKS.includes(value as MigrationFramework)) {
+    return value as MigrationFramework;
+  }
+
+  return {
+    exitCode: 2,
+    stderr: `aurora init: invalid --from value '${value}'. Expected ${VALID_FRAMEWORKS.join(", ")}`,
+  };
+}
+
+function parseMode(value: string | undefined): InitMode | CommandResult {
+  if (!value) {
+    return {
+      exitCode: 2,
+      stderr: `aurora init: --mode requires ${VALID_MODES.join("|")}`,
+    };
+  }
+
+  if (VALID_MODES.includes(value as InitMode)) {
+    return value as InitMode;
+  }
+
+  return {
+    exitCode: 2,
+    stderr: `aurora init: invalid --mode '${value}'. Expected ${VALID_MODES.join(", ")}`,
+  };
+}
+
+function parseBridge(value: string | undefined): InitBridge | CommandResult {
+  if (!value) {
+    return {
+      exitCode: 2,
+      stderr: `aurora init: --bridge requires ${VALID_BRIDGES.join("|")}`,
+    };
+  }
+
+  if (VALID_BRIDGES.includes(value as InitBridge)) {
+    return value as InitBridge;
+  }
+
+  return {
+    exitCode: 2,
+    stderr: `aurora init: invalid --bridge '${value}'. Expected ${VALID_BRIDGES.join(", ")}`,
+  };
+}
+
+function parseFormat(value: string | undefined): InitFormat | CommandResult {
+  if (!value) {
+    return {
+      exitCode: 2,
+      stderr: "aurora init: --format requires 'text' or 'json'",
+    };
+  }
+
+  if (value === "text" || value === "json") {
+    return value;
+  }
+
+  return {
+    exitCode: 2,
+    stderr: `aurora init: invalid format '${value}'. Expected 'text' or 'json'`,
+  };
+}
+
+function parseInitOptions(args: ReadonlyArray<string>): InitOptions | CommandResult {
+  const parsed: Partial<InitOptions> = {
+    mode: "incremental",
+    bridge: "react",
+    outDir: DEFAULT_OUT_DIR,
+    dryRun: false,
+    format: "text",
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--from") {
+      const framework = parseFramework(args[index + 1]);
+      if (typeof framework !== "string") {
+        return framework;
+      }
+      parsed.framework = framework;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--mode") {
+      const mode = parseMode(args[index + 1]);
+      if (typeof mode !== "string") {
+        return mode;
+      }
+      parsed.mode = mode;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--bridge") {
+      const bridge = parseBridge(args[index + 1]);
+      if (typeof bridge !== "string") {
+        return bridge;
+      }
+      parsed.bridge = bridge;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--out-dir") {
+      const value = args[index + 1];
+      if (!value || value.trim().length === 0) {
+        return {
+          exitCode: 2,
+          stderr: "aurora init: --out-dir requires a non-empty path",
+        };
+      }
+
+      parsed.outDir = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      parsed.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--format") {
+      const format = parseFormat(args[index + 1]);
+      if (typeof format !== "string") {
+        return format;
+      }
+      parsed.format = format;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      return {
+        exitCode: 2,
+        stderr: `aurora init: unknown option '${arg}'`,
+      };
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora init: unexpected positional argument '${arg}'`,
+    };
+  }
+
+  if (!parsed.framework) {
+    return {
+      exitCode: 2,
+      stderr: "aurora init: --from is required (next|remix|sveltekit)",
+    };
+  }
+
+  return parsed as InitOptions;
+}
+
+function normalizeRelativePath(path: string): string {
+  return path.replaceAll("\\", "/");
+}
+
+function fileBaseName(path: string): string {
+  const normalized = normalizeRelativePath(path);
+  const lastSeparator = normalized.lastIndexOf("/");
+  return lastSeparator >= 0 ? normalized.slice(lastSeparator + 1) : normalized;
+}
+
+function collectFiles(rootPath: string): string[] {
+  if (!existsSync(rootPath)) {
+    return [];
+  }
+
+  const collected: string[] = [];
+
+  function visit(directory: string): void {
+    const entries = readdirSync(directory, { withFileTypes: true }).sort((left, right) =>
+      left.name.localeCompare(right.name),
+    );
+
+    for (const entry of entries) {
+      const absolutePath = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRECTORIES.has(entry.name)) {
+          continue;
+        }
+        visit(absolutePath);
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      collected.push(absolutePath);
+    }
+  }
+
+  visit(rootPath);
+  return collected;
+}
+
+function readTextIfExists(path: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function stripCodeExtension(path: string): string {
+  return path.replace(/\.[cm]?[jt]sx?$/i, "");
+}
+
+function mapBracketSegment(segment: string): string {
+  const catchAll = segment.match(/^\[\.\.\.(.+)\]$/);
+  if (catchAll) {
+    return `*${catchAll[1]}`;
+  }
+
+  const optionalCatchAll = segment.match(/^\[\[\.\.\.(.+)\]\]$/);
+  if (optionalCatchAll) {
+    return `*${optionalCatchAll[1]}`;
+  }
+
+  const dynamic = segment.match(/^\[(.+)\]$/);
+  if (dynamic) {
+    return `:${dynamic[1]}`;
+  }
+
+  return segment;
+}
+
+function toRoutePathFromSegments(segments: readonly string[]): string {
+  const normalized = segments.filter((segment) => segment.length > 0);
+  if (normalized.length === 0) {
+    return "/";
+  }
+
+  return `/${normalized.join("/")}`;
+}
+
+function nextPagesRouteFromRelative(relativeFilePath: string): string | undefined {
+  const withoutExt = stripCodeExtension(normalizeRelativePath(relativeFilePath));
+  if (withoutExt.startsWith("api/")) {
+    return undefined;
+  }
+
+  const base = fileBaseName(withoutExt);
+  if (base === "_app" || base === "_document" || base === "_error") {
+    return undefined;
+  }
+
+  const parts = withoutExt.split("/");
+  const routeSegments: string[] = [];
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index];
+    const isLast = index === parts.length - 1;
+    if (isLast && part === "index") {
+      continue;
+    }
+    routeSegments.push(mapBracketSegment(part));
+  }
+
+  return toRoutePathFromSegments(routeSegments);
+}
+
+function nextAppRouteFromRelative(relativeFilePath: string): string | undefined {
+  const normalized = normalizeRelativePath(relativeFilePath);
+  if (!normalized.endsWith("/page.tsx") && !normalized.endsWith("/page.ts") &&
+      !normalized.endsWith("/page.jsx") && !normalized.endsWith("/page.js")) {
+    return undefined;
+  }
+
+  const dir = dirname(normalized);
+  if (dir === ".") {
+    return "/";
+  }
+
+  const routeSegments = dir
+    .split("/")
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0)
+    .filter((segment) => !(segment.startsWith("(") && segment.endsWith(")")))
+    .map((segment) => mapBracketSegment(segment));
+
+  return toRoutePathFromSegments(routeSegments);
+}
+
+function remixRouteFromRelative(relativeFilePath: string): string {
+  const normalized = stripCodeExtension(normalizeRelativePath(relativeFilePath));
+  const rawSegments = normalized.split("/");
+  const routeSegments: string[] = [];
+
+  for (const rawSegment of rawSegments) {
+    const parts = rawSegment.split(".");
+    for (const part of parts) {
+      if (part === "index" || part === "_index") {
+        continue;
+      }
+
+      if (part.startsWith("_")) {
+        continue;
+      }
+
+      if (part === "$") {
+        routeSegments.push("*");
+        continue;
+      }
+
+      if (part.startsWith("$")) {
+        routeSegments.push(`:${part.slice(1)}`);
+        continue;
+      }
+
+      routeSegments.push(part);
+    }
+  }
+
+  return toRoutePathFromSegments(routeSegments);
+}
+
+function sveltekitRouteFromRelative(relativeFilePath: string): string | undefined {
+  const normalized = normalizeRelativePath(relativeFilePath);
+  if (
+    !normalized.endsWith("/+page.svelte") &&
+    !normalized.endsWith("/+page.ts") &&
+    !normalized.endsWith("/+page.js") &&
+    !normalized.endsWith("/+page.tsx") &&
+    !normalized.endsWith("/+page.jsx")
+  ) {
+    return undefined;
+  }
+
+  const dir = dirname(normalized);
+  if (dir === ".") {
+    return "/";
+  }
+
+  const routeSegments = dir
+    .split("/")
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0)
+    .filter((segment) => !(segment.startsWith("(") && segment.endsWith(")")))
+    .map((segment) => mapBracketSegment(segment));
+
+  return toRoutePathFromSegments(routeSegments);
+}
+
+function toAuroraRouteDirectory(auroraPath: string): string {
+  if (auroraPath === "/") {
+    return "index";
+  }
+
+  return auroraPath
+    .slice(1)
+    .split("/")
+    .map((segment) => {
+      if (segment.startsWith(":")) {
+        return `[${segment.slice(1)}]`;
+      }
+      if (segment.startsWith("*")) {
+        const label = segment.slice(1).length > 0 ? segment.slice(1) : "all";
+        return `[...${label}]`;
+      }
+      return segment;
+    })
+    .join("/");
+}
+
+function toRouteBaseName(auroraPath: string): string {
+  if (auroraPath === "/") {
+    return "index";
+  }
+
+  const segments = auroraPath.slice(1).split("/");
+  const last = segments[segments.length - 1] ?? "route";
+  const normalized = last
+    .replace(/^[:*]/, "")
+    .replace(/[^a-zA-Z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return normalized.length > 0 ? normalized : "route";
+}
+
+function toRouteTargetFiles(auroraPath: string): string[] {
+  const routeDir = toAuroraRouteDirectory(auroraPath);
+  const baseName = toRouteBaseName(auroraPath);
+  const prefix = join("aurora-routes", routeDir).replaceAll("\\", "/");
+
+  return [
+    `${prefix}/page.tsx`,
+    `${prefix}/${baseName}.client.tsx`,
+    `${prefix}/${baseName}.server.ts`,
+  ];
+}
+
+function dedupeMappings(
+  mappings: readonly Omit<RouteMapping, "targetFiles">[],
+): { unique: RouteMapping[]; warnings: string[] } {
+  const byAuroraPath = new Map<string, RouteMapping>();
+  const warnings: string[] = [];
+
+  for (const entry of mappings) {
+    const existing = byAuroraPath.get(entry.auroraPath);
+    if (existing) {
+      warnings.push(
+        `duplicate mapping for '${entry.auroraPath}' from '${entry.sourcePath}' (keeping '${existing.sourcePath}')`,
+      );
+      continue;
+    }
+
+    byAuroraPath.set(entry.auroraPath, {
+      ...entry,
+      targetFiles: toRouteTargetFiles(entry.auroraPath),
+    });
+  }
+
+  return {
+    unique: [...byAuroraPath.values()].sort((left, right) =>
+      left.auroraPath.localeCompare(right.auroraPath),
+    ),
+    warnings,
+  };
+}
+
+function detectNextMappings(context: CommandContext): MigrationScanResult {
+  const pagesRoot = resolve(context.cwd, "pages");
+  const appRoot = resolve(context.cwd, "app");
+  const sourceFiles = [
+    ...collectFiles(pagesRoot),
+    ...collectFiles(appRoot),
+  ].filter((path) => CODE_FILE_PATTERN.test(path));
+
+  const rawMappings: Omit<RouteMapping, "targetFiles">[] = [];
+
+  for (const absolutePath of collectFiles(pagesRoot)) {
+    if (!CODE_FILE_PATTERN.test(absolutePath)) {
+      continue;
+    }
+    const relativeFromPages = normalizeRelativePath(relative(pagesRoot, absolutePath));
+    const mappedPath = nextPagesRouteFromRelative(relativeFromPages);
+    if (!mappedPath) {
+      continue;
+    }
+    rawMappings.push({
+      sourcePath: normalizeRelativePath(relative(context.cwd, absolutePath)),
+      frameworkPath: mappedPath,
+      auroraPath: mappedPath,
+      convention: "next-pages",
+    });
+  }
+
+  for (const absolutePath of collectFiles(appRoot)) {
+    if (!CODE_FILE_PATTERN.test(absolutePath)) {
+      continue;
+    }
+    const relativeFromApp = normalizeRelativePath(relative(appRoot, absolutePath));
+    const mappedPath = nextAppRouteFromRelative(relativeFromApp);
+    if (!mappedPath) {
+      continue;
+    }
+    rawMappings.push({
+      sourcePath: normalizeRelativePath(relative(context.cwd, absolutePath)),
+      frameworkPath: mappedPath,
+      auroraPath: mappedPath,
+      convention: "next-app",
+    });
+  }
+
+  const loaderCandidates = sourceFiles.reduce((count, filePath) => {
+    const source = readTextIfExists(filePath);
+    const hasLoader = /getServerSideProps|getStaticProps|getInitialProps/.test(source);
+    return count + (hasLoader ? 1 : 0);
+  }, 0);
+  const actionCandidates = sourceFiles.reduce((count, filePath) => {
+    const normalized = normalizeRelativePath(filePath);
+    const source = readTextIfExists(filePath);
+    const hasAction =
+      normalized.includes("/pages/api/") ||
+      /export\s+async\s+function\s+(POST|PUT|PATCH|DELETE)/.test(source);
+    return count + (hasAction ? 1 : 0);
+  }, 0);
+
+  const deduped = dedupeMappings(rawMappings);
+  const warnings = [...deduped.warnings];
+  if (deduped.unique.length === 0) {
+    warnings.push("no Next.js routes were detected under pages/ or app/");
+  }
+
+  return {
+    framework: "next",
+    routes: deduped.unique,
+    loaderCandidates,
+    actionCandidates,
+    warnings,
+  };
+}
+
+function detectRemixMappings(context: CommandContext): MigrationScanResult {
+  const routesRoot = resolve(context.cwd, "app/routes");
+  const routeFiles = collectFiles(routesRoot).filter((filePath) => CODE_FILE_PATTERN.test(filePath));
+
+  const rawMappings: Omit<RouteMapping, "targetFiles">[] = routeFiles.map((absolutePath) => {
+    const relativeFromRoutes = normalizeRelativePath(relative(routesRoot, absolutePath));
+    const mappedPath = remixRouteFromRelative(relativeFromRoutes);
+    return {
+      sourcePath: normalizeRelativePath(relative(context.cwd, absolutePath)),
+      frameworkPath: mappedPath,
+      auroraPath: mappedPath,
+      convention: "remix-routes",
+    };
+  });
+
+  const loaderCandidates = routeFiles.reduce((count, filePath) => {
+    const source = readTextIfExists(filePath);
+    return count + (/export\s+(async\s+)?(function\s+)?loader\b|export\s+const\s+loader\b/.test(source) ? 1 : 0);
+  }, 0);
+  const actionCandidates = routeFiles.reduce((count, filePath) => {
+    const source = readTextIfExists(filePath);
+    return count + (/export\s+(async\s+)?(function\s+)?action\b|export\s+const\s+action\b/.test(source) ? 1 : 0);
+  }, 0);
+
+  const deduped = dedupeMappings(rawMappings);
+  const warnings = [...deduped.warnings];
+  if (deduped.unique.length === 0) {
+    warnings.push("no Remix routes were detected under app/routes/");
+  }
+
+  return {
+    framework: "remix",
+    routes: deduped.unique,
+    loaderCandidates,
+    actionCandidates,
+    warnings,
+  };
+}
+
+function detectSveltekitMappings(context: CommandContext): MigrationScanResult {
+  const routesRoot = resolve(context.cwd, "src/routes");
+  const routeFiles = collectFiles(routesRoot).filter((filePath) =>
+    CODE_FILE_PATTERN.test(filePath) || filePath.endsWith(".svelte"),
+  );
+
+  const rawMappings: Omit<RouteMapping, "targetFiles">[] = [];
+  for (const absolutePath of routeFiles) {
+    const relativeFromRoutes = normalizeRelativePath(relative(routesRoot, absolutePath));
+    const mappedPath = sveltekitRouteFromRelative(relativeFromRoutes);
+    if (!mappedPath) {
+      continue;
+    }
+    rawMappings.push({
+      sourcePath: normalizeRelativePath(relative(context.cwd, absolutePath)),
+      frameworkPath: mappedPath,
+      auroraPath: mappedPath,
+      convention: "sveltekit-page",
+    });
+  }
+
+  const loaderCandidates = routeFiles.reduce((count, filePath) => {
+    const source = readTextIfExists(filePath);
+    return count + (/export\s+(async\s+)?function\s+load\b|export\s+const\s+load\b/.test(source) ? 1 : 0);
+  }, 0);
+  const actionCandidates = routeFiles.reduce((count, filePath) => {
+    const source = readTextIfExists(filePath);
+    return count + (/export\s+const\s+actions\b/.test(source) ? 1 : 0);
+  }, 0);
+
+  const deduped = dedupeMappings(rawMappings);
+  const warnings = [...deduped.warnings];
+  if (deduped.unique.length === 0) {
+    warnings.push("no SvelteKit +page routes were detected under src/routes/");
+  }
+
+  return {
+    framework: "sveltekit",
+    routes: deduped.unique,
+    loaderCandidates,
+    actionCandidates,
+    warnings,
+  };
+}
+
+function detectFrameworkProject(
+  options: InitOptions,
+  context: CommandContext,
+): MigrationScanResult {
+  if (options.framework === "next") {
+    return detectNextMappings(context);
+  }
+
+  if (options.framework === "remix") {
+    return detectRemixMappings(context);
+  }
+
+  return detectSveltekitMappings(context);
+}
+
+function buildChecklist(options: InitOptions): MigrationChecklistItem[] {
+  const items: MigrationChecklistItem[] = [
+    {
+      id: "route-map",
+      text: "Validate generated route map against existing URLs and dynamic params.",
+    },
+    {
+      id: "data-hooks",
+      text: "Port framework loaders/actions into Aurora query/action modules with explicit auth + input contracts.",
+    },
+    {
+      id: "run-doctor",
+      text: "Run `aurora doctor` and resolve migration/security/performance findings before cutover.",
+    },
+    {
+      id: "test-parity",
+      text: "Add integration checks for route parity and mutation behavior before traffic switching.",
+    },
+  ];
+
+  if (options.mode === "incremental") {
+    items.push({
+      id: "incremental-mount",
+      text: "Mount generated Aurora handler under a sub-path and shift traffic route-by-route.",
+    });
+  }
+
+  if (options.bridge === "react") {
+    items.push({
+      id: "react-interop",
+      text: "Wrap legacy React components via `fromReact(...)` only where migration bridging is required.",
+    });
+  }
+
+  return items;
+}
+
+function renderRoutePageStub(mapping: RouteMapping): string {
+  return [
+    `// Source: ${mapping.sourcePath}`,
+    `// Convention: ${mapping.convention}`,
+    "",
+    `export const routePath = "${mapping.auroraPath}";`,
+    "",
+    "export default function Page(): string {",
+    `  return \"TODO: migrate ${mapping.sourcePath} to Aurora route contract.\";`,
+    "}",
+    "",
+  ].join("\n");
+}
+
+function renderRouteClientStub(mapping: RouteMapping): string {
+  return [
+    `// Source: ${mapping.sourcePath}`,
+    "",
+    "export function RouteClientView(): string {",
+    `  return \"TODO: client interop for ${mapping.auroraPath}\";`,
+    "}",
+    "",
+  ].join("\n");
+}
+
+function renderRouteServerStub(mapping: RouteMapping): string {
+  return [
+    `// Source: ${mapping.sourcePath}`,
+    "",
+    `export const auth = "user";`,
+    "",
+    "export async function loadRouteData(): Promise<Record<string, unknown>> {",
+    "  return {",
+    `    migratedFrom: ${JSON.stringify(mapping.sourcePath)},`,
+    `    frameworkPath: ${JSON.stringify(mapping.frameworkPath)},`,
+    "  };",
+    "}",
+    "",
+  ].join("\n");
+}
+
+function buildScaffoldFiles(
+  report: Omit<InitMigrationReport, "generatedFiles">,
+): GeneratedScaffoldFile[] {
+  const files: GeneratedScaffoldFile[] = [];
+  const checklistMarkdown = [
+    "# Aurora Migration Checklist",
+    "",
+    `Framework source: ${report.framework}`,
+    `Mode: ${report.migrationMode}`,
+    `Bridge: ${report.bridge}`,
+    "",
+    "## Tasks",
+    ...report.checklist.map((item) => `- [ ] (${item.id}) ${item.text}`),
+    "",
+    "## Route Summary",
+    `- detected routes: ${report.detectedRoutes}`,
+    `- loader candidates: ${report.loaderCandidates}`,
+    `- action candidates: ${report.actionCandidates}`,
+    "",
+    "## Warnings",
+    ...(report.warnings.length > 0 ? report.warnings.map((warning) => `- ${warning}`) : ["- none"]),
+    "",
+  ].join("\n");
+
+  files.push({
+    path: "migration-checklist.md",
+    content: checklistMarkdown,
+  });
+  files.push({
+    path: "route-map.json",
+    content: JSON.stringify(report.mappedRoutes, null, 2),
+  });
+  files.push({
+    path: "migration-report.json",
+    content: JSON.stringify(
+      {
+        mode: report.mode,
+        framework: report.framework,
+        migrationMode: report.migrationMode,
+        bridge: report.bridge,
+        detectedRoutes: report.detectedRoutes,
+        loaderCandidates: report.loaderCandidates,
+        actionCandidates: report.actionCandidates,
+        warnings: report.warnings,
+        generatedAt: "init-runtime",
+      },
+      null,
+      2,
+    ),
+  });
+  files.push({
+    path: "README.md",
+    content: [
+      "# Aurora Migration Scaffold",
+      "",
+      "Generated by `aurora init`.",
+      "",
+      "Folders:",
+      "- `aurora-routes/` route stubs mapped to Aurora 3-file conventions",
+      "- `incremental/` mount helper for gradual rollout",
+      "- `interop/` React bridge example for migration-period reuse",
+      "",
+    ].join("\n"),
+  });
+
+  for (const mapping of report.mappedRoutes) {
+    const [pagePath, clientPath, serverPath] = mapping.targetFiles;
+    files.push({
+      path: pagePath,
+      content: renderRoutePageStub(mapping),
+    });
+    files.push({
+      path: clientPath,
+      content: renderRouteClientStub(mapping),
+    });
+    files.push({
+      path: serverPath,
+      content: renderRouteServerStub(mapping),
+    });
+  }
+
+  if (report.migrationMode === "incremental") {
+    files.push({
+      path: "incremental/mount.server.ts",
+      content: [
+        'import { createAuroraHandler } from "@aurora/adapter-node";',
+        "",
+        "export const auroraMount = createAuroraHandler({",
+        '  basePath: "/aurora",',
+        '  routes: "./aurora-routes",',
+        "  async authBridge() {",
+        "    // TODO: map existing session context into Aurora auth shape.",
+        "    return { role: \"user\", permissions: [] };",
+        "  },",
+        "});",
+        "",
+      ].join("\n"),
+    });
+  }
+
+  if (report.bridge === "react") {
+    files.push({
+      path: "interop/react-bridge.tsx",
+      content: [
+        'import { fromReact } from "@aurora/runtime-interop";',
+        'import { DatePicker } from "existing-react-library";',
+        "",
+        "export const AuroraDatePicker = fromReact(DatePicker);",
+        "",
+      ].join("\n"),
+    });
+  }
+
+  return files;
+}
+
+function isNonEmptyDirectory(path: string): boolean {
+  if (!existsSync(path)) {
+    return false;
+  }
+
+  try {
+    return readdirSync(path).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function ensureParentDirectory(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+function buildReport(
+  options: InitOptions,
+  context: CommandContext,
+): InitMigrationReport | CommandResult {
+  const scan = detectFrameworkProject(options, context);
+  const checklist = buildChecklist(options);
+  const baseReport: Omit<InitMigrationReport, "generatedFiles"> = {
+    mode: "init-migration",
+    projectRoot: context.cwd,
+    framework: options.framework,
+    migrationMode: options.mode,
+    bridge: options.bridge,
+    outDir: options.outDir,
+    dryRun: options.dryRun,
+    detectedRoutes: scan.routes.length,
+    loaderCandidates: scan.loaderCandidates,
+    actionCandidates: scan.actionCandidates,
+    mappedRoutes: scan.routes,
+    checklist,
+    warnings: scan.warnings,
+  };
+
+  const scaffoldFiles = buildScaffoldFiles(baseReport);
+  const generatedFiles = scaffoldFiles.map((file) => file.path);
+  const outputRoot = resolve(context.cwd, options.outDir);
+
+  if (!options.dryRun) {
+    if (isNonEmptyDirectory(outputRoot)) {
+      return {
+        exitCode: 2,
+        stderr:
+          `aurora init: out-dir already exists and is not empty: ${options.outDir}\n` +
+          "Use --out-dir <new-path> or run with --dry-run first.",
+      };
+    }
+
+    for (const file of scaffoldFiles) {
+      const absolutePath = resolve(outputRoot, file.path);
+      ensureParentDirectory(absolutePath);
+      writeFileSync(absolutePath, file.content, "utf8");
+    }
+  }
+
+  return {
+    ...baseReport,
+    generatedFiles,
+  };
+}
+
+function renderTextReport(report: InitMigrationReport): string {
+  const lines = [
+    "aurora init migration report",
+    `project_root: ${report.projectRoot}`,
+    `framework: ${report.framework}`,
+    `mode: ${report.migrationMode}`,
+    `bridge: ${report.bridge}`,
+    `out_dir: ${report.outDir}`,
+    `dry_run: ${report.dryRun}`,
+    `detected_routes: ${report.detectedRoutes}`,
+    `loader_candidates: ${report.loaderCandidates}`,
+    `action_candidates: ${report.actionCandidates}`,
+    `generated_files: ${report.generatedFiles.length}`,
+    `warnings: ${report.warnings.length}`,
+    "",
+    "mapped_routes:",
+  ];
+
+  if (report.mappedRoutes.length === 0) {
+    lines.push("- none");
+  } else {
+    for (const mapping of report.mappedRoutes) {
+      lines.push(
+        `- ${mapping.sourcePath} -> ${mapping.auroraPath} (${mapping.convention})`,
+      );
+    }
+  }
+
+  lines.push("", "checklist:");
+  for (const item of report.checklist) {
+    lines.push(`- (${item.id}) ${item.text}`);
+  }
+
+  lines.push("", "output_files:");
+  for (const file of report.generatedFiles) {
+    lines.push(`- ${file}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function runInitCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseInitOptions(args);
+  if ("exitCode" in options) {
+    return options;
+  }
+
+  const report = buildReport(options, context);
+  if ("exitCode" in report) {
+    return report;
+  }
+
+  if (options.format === "json") {
+    return {
+      exitCode: 0,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: renderTextReport(report),
+  };
+}