@gitpagedocs/cli 1.1.60 → 1.1.62

package/domain/services/layouts-migration.mjs

@@ -0,0 +1,60 @@
+/**
+ * Legacy layouts migration — planning only.
+ *
+ * Deciding *what* should move is domain logic, so it stays free of prompts and
+ * filesystem writes: callers list the two folders, ask the user, and perform
+ * the move. That keeps the rule testable with plain arrays.
+ */
+import { legacyLayoutsDir, normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
+
+/**
+ * @typedef {Object} LayoutsMigrationPlan
+ * @property {boolean} required     True when the legacy folder holds files to move.
+ * @property {string}  from         Repo-relative legacy folder.
+ * @property {string}  to           Repo-relative destination folder.
+ * @property {string[]} files       Paths relative to `from`, sorted.
+ * @property {string[]} overwrites  Subset of `files` already present at `to`.
+ */
+
+/**
+ * Plan the move from the legacy layouts folder to the standalone home.
+ *
+ * @param {Object} options
+ * @param {string} options.outputDir     Docs output dir (owns the legacy folder).
+ * @param {string} options.layoutsDir    Destination layouts folder.
+ * @param {string[]} [options.legacyFiles] Paths relative to the legacy folder.
+ * @param {string[]} [options.targetFiles] Paths relative to the destination folder.
+ * @returns {LayoutsMigrationPlan}
+ */
+export function planLayoutsMigration(options = {}) {
+  const { outputDir, layoutsDir, legacyFiles, targetFiles } = options;
+
+  const from = legacyLayoutsDir(outputDir);
+  const to = normalizeLayoutsDir(layoutsDir);
+
+  const files = toSortedPaths(legacyFiles);
+  const present = new Set(toSortedPaths(targetFiles));
+
+  return {
+    required: files.length > 0 && from !== to,
+    from,
+    to,
+    files,
+    overwrites: files.filter((file) => present.has(file)),
+  };
+}
+
+/**
+ * Normalize, de-duplicate and sort a list of relative paths so a plan is
+ * deterministic regardless of directory-read order.
+ *
+ * @param {unknown} paths
+ * @returns {string[]}
+ */
+function toSortedPaths(paths) {
+  if (!Array.isArray(paths)) return [];
+  const normalized = paths
+    .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+    .map((entry) => entry.replace(/[\\/]+/g, "/").replace(/^\/+/, ""));
+  return [...new Set(normalized)].sort();
+}

package/index.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import path from "node:path";
 import { fileURLToPath } from "node:url";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpagedocs/cli",
-  "version": "1.1.60",
+  "version": "1.1.62",
   "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
   "bin": {
     "gitpagedocs": "index.mjs"
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
-    "@gitpagedocs/mcp": "^1.1.60",
-    "@gitpagedocs/tools": "^1.1.60",
+    "@gitpagedocs/mcp": "^1.1.62",
+    "@gitpagedocs/tools": "^1.1.62",
     "tsx": "^4.21.0"
   },
   "repository": {

package/presentation/commands/diagnostics.ts

@@ -57,14 +57,108 @@ export async function runDoctor(ctx: CommandContext): Promise<void> {
   console.log(`\n  ${failed === 0 ? "All required checks passed." : `${failed} check(s) need attention.`}\n`);
 }
 
+/** Used only when package.json is unreadable — the CLI's published name. */
+const FALLBACK_PACKAGE = "@gitpagedocs/cli";
+/** The bin this package installs; shown alongside the package name. */
+const BIN_NAME = "gitpagedocs";
+
+interface PackageIdentity {
+  name: string;
+  version: string;
+}
+
+/**
+ * Read the identity from the installed package.json rather than hardcoding it,
+ * so the hint always names the package the user actually has. A hardcoded name
+ * is how `update` ended up advertising an unpublished package.
+ */
+function readPackageIdentity(pkgRoot: string): PackageIdentity {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
+    const name = typeof pkg.name === "string" && pkg.name.length > 0 ? pkg.name : FALLBACK_PACKAGE;
+    return { name, version: String(pkg.version ?? "unknown") };
+  } catch {
+    return { name: FALLBACK_PACKAGE, version: "unknown" };
+  }
+}
+
+type RegistryLookup =
+  | { status: "ok"; latest: string }
+  | { status: "missing" }
+  | { status: "unreachable" };
+
+function registryBase(): string {
+  const configured = process.env.npm_config_registry || "https://registry.npmjs.org";
+  return configured.endsWith("/") ? configured.slice(0, -1) : configured;
+}
+
+/** Resolve the dist-tag `latest` for a package. Never throws. */
+async function fetchLatest(name: string, timeoutMs = 6000): Promise<RegistryLookup> {
+  const encoded = name.split("/").map(encodeURIComponent).join("/");
+  try {
+    const response = await fetch(`${registryBase()}/${encoded}/latest`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 404) return { status: "missing" };
+    if (!response.ok) return { status: "unreachable" };
+    const body = (await response.json()) as { version?: unknown };
+    if (typeof body.version === "string" && body.version.length > 0) {
+      return { status: "ok", latest: body.version };
+    }
+    return { status: "unreachable" };
+  } catch {
+    return { status: "unreachable" };
+  }
+}
+
+/** Numeric version compare, prerelease suffix ignored. */
+function compareVersions(a: string, b: string): number {
+  const parts = (value: string): number[] =>
+    value.split("-")[0].split(".").map((piece) => Number.parseInt(piece, 10) || 0);
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
 export async function runUpdate(ctx: CommandContext): Promise<void> {
-  const current = readVersion(ctx.pkgRoot);
+  const { name, version } = readPackageIdentity(ctx.pkgRoot);
+  const lookup = await fetchLatest(name);
+  const label = name === BIN_NAME ? `${BIN_NAME} ${version}` : `${BIN_NAME} ${version}  (${name})`;
+  const lines = ["", `  Installed: ${label}`];
+
+  if (lookup.status === "ok") {
+    lines.push(`  Latest:    ${lookup.latest}`);
+  } else if (lookup.status === "missing") {
+    lines.push(`  Latest:    unavailable — the registry has no published ${name}`);
+  } else {
+    lines.push("  Latest:    unknown — could not reach the npm registry");
+  }
+
+  if (lookup.status === "missing") {
+    lines.push(
+      "",
+      "  Nothing can be installed under that name. If the package was renamed",
+      "  or unpublished, check the current one:",
+      "    https://www.npmjs.com/package/@gitpagedocs/cli",
+    );
+  } else if (lookup.status === "ok" && compareVersions(version, lookup.latest) >= 0) {
+    lines.push("", "  Already on the latest published version.");
+  } else {
+    const target = lookup.status === "ok" ? lookup.latest : "latest";
+    lines.push(
+      "",
+      "  To update the global CLI:",
+      `    npm i -g ${name}@${target}`,
+      "  Or, in a project:",
+      `    pnpm add -D ${name}@${target}`,
+    );
+  }
+
+  lines.push("");
   // eslint-disable-next-line no-console
-  console.log(
-    `\n  Installed: gitpagedocs ${current}\n` +
-      "  To update the global CLI:\n" +
-      "    npm i -g gitpagedocs@latest\n" +
-      "  Or, in a project:\n" +
-      "    pnpm add -D gitpagedocs@latest\n",
-  );
+  console.log(lines.join("\n"));
 }

package/presentation/index.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { printBanner, printCredits } from "./ui/banner";
 import { resolveOptions } from "./options/resolver";
+import { migrateLegacyLayoutsInteractive } from "./ui/layouts-prompts";
 import { runNewCommand } from "./commands/run-command";
 import { dispatchMode } from "../application/use-cases/dispatch-mode";
 import type {
@@ -57,6 +58,13 @@ async function main(): Promise<void> {
   }
 
   const options = await resolveOptions(process.argv, process.env);
+
+  // Layouts moved out of <outputDir>/layouts/. Offer to relocate anything left
+  // behind before generating, so the config written next points at one folder.
+  if (options.mode === "config-only") {
+    await migrateLegacyLayoutsInteractive(root, options);
+  }
+
   const configOnlyRuntime = createConfigOnlyRuntime() as ConfigOnlyRuntimePort;
   const homeRuntime = createHomeRuntime() as HomeRuntimePort;
   await dispatchMode(options, params, {

package/presentation/options/parser.ts

@@ -1,5 +1,6 @@
 import type { CliOptions } from "../../domain/models/cli-options";
 import { DEFAULTS } from "./schema";
+import { normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
 
 const KNOWN_FLAGS = new Set([
   "--build",
@@ -11,8 +12,12 @@ const KNOWN_FLAGS = new Set([
   "--search",
   "--path",
   "--output",
+  "--layouts-dir",
   "--interactive",
   "-i",
+  "--no-interactive",
+  "--yes",
+  "-y",
   "--ai",
   "--pages-actions",
 ]);
@@ -35,6 +40,7 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
   let githubRepo = readOptionValue(args, "--repo");
   const docsPath = readOptionValue(args, "--path");
   const outputDir = readOptionValue(args, "--output");
+  const layoutsDir = readOptionValue(args, "--layouts-dir");
   const searchRaw = readOptionValue(args, "--search");
 
   const fallbackDashedArgs = args
@@ -45,6 +51,7 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
     .filter((a) => !a.startsWith("--path"))
     .filter((a) => !a.startsWith("--home"))
     .filter((a) => !a.startsWith("--output"))
+    .filter((a) => !a.startsWith("--layouts-dir"))
     .filter((a) => !a.startsWith("--search"))
     .map((a) => a.replace(/^--/, "").trim())
     .filter(Boolean);
@@ -91,6 +98,7 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
     mode,
     aiCommand,
     outputDir: outputDir || (isHome ? DEFAULTS.home.outputDir : DEFAULTS.outputDir),
+    layoutsDir: normalizeLayoutsDir(layoutsDir || DEFAULTS.layoutsDir),
     useLocalLayoutConfig,
     shouldPush,
     githubOwner,
@@ -100,5 +108,12 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
     repositorySearch,
     isInteractive,
     hasArgs: args.length > 0,
+    explicit: {
+      useLocalLayoutConfig,
+      layoutsDir: Boolean(layoutsDir),
+      githubOwner: Boolean(githubOwner),
+      githubRepo: Boolean(githubRepo),
+      outputDir: Boolean(outputDir),
+    },
   };
 }

package/presentation/options/resolver.ts

@@ -34,15 +34,13 @@ export async function resolveOptions(argv: string[], env: NodeJS.ProcessEnv): Pr
     return resolved;
   }
 
-  const runHomeInteractive = parsed.isInteractive || (shouldRunInteractive(argv) && parsed.mode === "home");
-  if (runHomeInteractive && parsed.mode === "home") {
-    return promptHomeOptions(parsed);
-  }
+  // Every command prompts in a real terminal; shouldRunInteractive owns the
+  // CI / piped-stdin / --no-interactive opt-outs, and each prompt asks only for
+  // what the command line left unanswered.
+  if (!shouldRunInteractive(argv)) return parsed;
 
-  const runConfigInteractive = parsed.isInteractive || (shouldRunInteractive(argv) && parsed.mode === "config-only");
-  if (runConfigInteractive && parsed.mode === "config-only") {
-    return promptConfigOnlyOptions(parsed);
-  }
+  if (parsed.mode === "home") return promptHomeOptions(parsed);
+  if (parsed.mode === "config-only") return promptConfigOnlyOptions(parsed);
 
   return parsed;
 }

package/presentation/options/schema.ts

@@ -1,5 +1,9 @@
+import { DEFAULT_LAYOUTS_DIR } from "../../contracts/layouts-paths.mjs";
+
 export const DEFAULTS = {
   outputDir: "gitpagedocs",
+  /** Standalone layouts home; local layouts are generated here, never in outputDir. */
+  layoutsDir: DEFAULT_LAYOUTS_DIR as string,
   repositorySearch: false,
   basePath: "",
   home: {

package/presentation/ui/layouts-prompts.ts

@@ -0,0 +1,124 @@
+/**
+ * Layout-related prompts: where layouts come from, where they are written, and
+ * the opt-in migration away from the legacy `<outputDir>/layouts/` folder.
+ */
+import path from "node:path";
+import { askConfirm, askSelect, askText, note } from "./clack";
+import { interactivePromptsAvailable } from "./tty";
+import {
+  DEFAULT_LAYOUTS_DIR,
+  normalizeLayoutsDir,
+  legacyLayoutsDir,
+} from "../../contracts/layouts-paths.mjs";
+import { planLayoutsMigration } from "../../domain/services/layouts-migration.mjs";
+import { listFilesRecursively, executeLayoutsMigration } from "../../runtime/layouts-migrator.mjs";
+
+type LayoutsSource = "official" | "local";
+
+/** Outcome of a completed migration, for the caller to report. */
+export interface LayoutsMigrationOutcome {
+  from: string;
+  to: string;
+  movedCount: number;
+}
+
+/** Ask whether layouts come from the official remote source or a local folder. */
+export async function askLayoutsSource(useLocal: boolean): Promise<boolean> {
+  const choice = await askSelect<LayoutsSource>(
+    "Layout source",
+    [
+      {
+        value: "official",
+        label: "Official layouts (remote)",
+        hint: "nothing is written to your repository",
+      },
+      {
+        value: "local",
+        label: "Local layouts",
+        hint: `generated into ${DEFAULT_LAYOUTS_DIR}/`,
+      },
+    ],
+    useLocal ? "local" : "official",
+  );
+  return choice === "local";
+}
+
+/** Ask which folder should hold the generated layouts. */
+export async function askLayoutsDir(current: string): Promise<string> {
+  const answer = await askText({
+    message: "Layouts folder:",
+    defaultValue: normalizeLayoutsDir(current),
+    validate: (value) => (value.trim() ? undefined : "A folder name is required."),
+  });
+  return normalizeLayoutsDir(answer);
+}
+
+function toAbsolute(root: string, repoRelative: string): string {
+  return path.join(root, ...repoRelative.split("/"));
+}
+
+/**
+ * Offer to move layouts left behind in the legacy folder.
+ *
+ * Nothing is moved without an explicit confirmation. Outside a TTY the legacy
+ * folder is reported and left alone — the viewer still reads it, so declining
+ * (or automating) never breaks an existing site.
+ *
+ * @returns The outcome when files were moved, otherwise `null`.
+ */
+export async function migrateLegacyLayoutsInteractive(
+  root: string,
+  options: { outputDir: string; layoutsDir: string },
+): Promise<LayoutsMigrationOutcome | null> {
+  const from = legacyLayoutsDir(options.outputDir);
+  const to = normalizeLayoutsDir(options.layoutsDir);
+
+  const plan = planLayoutsMigration({
+    outputDir: options.outputDir,
+    layoutsDir: to,
+    legacyFiles: listFilesRecursively(toAbsolute(root, from)),
+    targetFiles: listFilesRecursively(toAbsolute(root, to)),
+  });
+
+  if (!plan.required) return null;
+
+  if (!interactivePromptsAvailable()) {
+    note(
+      `${plan.files.length} layout file(s) still live in ${plan.from}/.\n` +
+        `The viewer still reads them. Run this in a terminal to move them to ${plan.to}/.`,
+      "Legacy layouts",
+    );
+    return null;
+  }
+
+  const overwriteWarning =
+    plan.overwrites.length > 0
+      ? `\n${plan.overwrites.length} file(s) already in ${plan.to}/ would be replaced.`
+      : "";
+  note(
+    `Found ${plan.files.length} layout file(s) in ${plan.from}/.\n` +
+      `Layouts are now generated in ${plan.to}/.${overwriteWarning}`,
+    "Legacy layouts",
+  );
+
+  const confirmed = await askConfirm(
+    `Move them to ${plan.to}/ now?`,
+    plan.overwrites.length === 0,
+  );
+  if (!confirmed) {
+    note(`Left untouched — the viewer still reads ${plan.from}/.`, "Legacy layouts");
+    return null;
+  }
+
+  const result = executeLayoutsMigration(root, plan);
+
+  if (result.failed.length > 0) {
+    note(
+      `${result.failed.length} file(s) could not be moved:\n` +
+        result.failed.map((entry) => `- ${entry.file}: ${entry.reason}`).join("\n"),
+      "Migration incomplete",
+    );
+  }
+
+  return { from: plan.from, to: plan.to, movedCount: result.moved.length };
+}

package/presentation/ui/prompts.ts

@@ -4,26 +4,19 @@ import { execSync } from "node:child_process";
 import type { CliOptions } from "../../domain/models/cli-options";
 import { DEFAULTS } from "../options/schema";
 import { askText, askConfirm, note } from "./clack";
+import { interactivePromptsAvailable, promptingEnabled } from "./tty";
+import { askLayoutsSource, askLayoutsDir } from "./layouts-prompts";
 
-function isCiOrNonTty(): boolean {
-  if (process.env.CI === "true") return true;
-  if (process.env.GITHUB_ACTIONS === "true") return true;
-  if (process.stdin && !process.stdin.isTTY) return true;
-  return false;
-}
-
-/** True when clack prompts can run (interactive TTY, not CI). */
-export function interactivePromptsAvailable(): boolean {
-  return !isCiOrNonTty();
-}
+export { interactivePromptsAvailable };
 
+/**
+ * Every command prompts when it runs in a real terminal, so a bare invocation
+ * reflects what the user actually needs instead of silently taking defaults.
+ * CI, a piped stdin, and an explicit `--no-interactive` / `--yes` / `-y` opt out;
+ * `--interactive` / `-i` remains accepted and reads the same either way.
+ */
 export function shouldRunInteractive(argv: string[]): boolean {
-  if (isCiOrNonTty()) return false;
-  const args = argv.slice(2);
-  if (args.includes("--interactive") || args.includes("-i")) return true;
-  if (args.length === 0) return true;
-  if (args.length === 1 && args[0] === "--home") return true;
-  return false;
+  return promptingEnabled(argv.slice(2));
 }
 
 export async function promptHomeOptions(parsed: CliOptions): Promise<CliOptions> {
@@ -115,23 +108,38 @@ export async function ensureGitRepoInteractive(root: string): Promise<void> {
   }
 }
 
+/**
+ * Ask only for what the command line did not already answer, so an explicit
+ * flag is never second-guessed by a prompt.
+ */
 export async function promptConfigOnlyOptions(parsed: CliOptions): Promise<CliOptions> {
-  const useLocalLayoutConfig = await askConfirm(
-    "Generate local layout templates?",
-    parsed.useLocalLayoutConfig ?? false,
-  );
-  const githubOwner = await askText({
-    message: "GitHub owner (optional):",
-    defaultValue: parsed.githubOwner ?? "",
-  });
-  const githubRepo = await askText({
-    message: "GitHub repo (optional):",
-    defaultValue: parsed.githubRepo ?? "",
-  });
+  const useLocalLayoutConfig = parsed.explicit.useLocalLayoutConfig
+    ? parsed.useLocalLayoutConfig
+    : await askLayoutsSource(parsed.useLocalLayoutConfig ?? false);
+
+  const layoutsDir =
+    useLocalLayoutConfig && !parsed.explicit.layoutsDir
+      ? await askLayoutsDir(parsed.layoutsDir)
+      : parsed.layoutsDir;
+
+  const githubOwner = parsed.explicit.githubOwner
+    ? parsed.githubOwner
+    : await askText({
+        message: "GitHub owner (optional):",
+        defaultValue: parsed.githubOwner ?? "",
+      });
+
+  const githubRepo = parsed.explicit.githubRepo
+    ? parsed.githubRepo
+    : await askText({
+        message: "GitHub repo (optional):",
+        defaultValue: parsed.githubRepo ?? "",
+      });
 
   return {
     ...parsed,
     useLocalLayoutConfig,
+    layoutsDir,
     githubOwner: githubOwner?.trim() ?? "",
     githubRepo: githubRepo?.trim() ?? "",
   };

package/presentation/ui/tty.ts

@@ -0,0 +1,37 @@
+/**
+ * Terminal capability detection.
+ *
+ * Kept in its own module so every prompt module can ask "may I prompt?" without
+ * importing the prompt modules themselves (which would be circular).
+ */
+
+/** Environment variables that mark a non-interactive automated run. */
+const CI_ENV_FLAGS = ["CI", "GITHUB_ACTIONS"] as const;
+
+/** Flags that explicitly opt out of prompting. */
+export const NON_INTERACTIVE_FLAGS = ["--no-interactive", "--yes", "-y"] as const;
+
+function isCiOrNonTty(): boolean {
+  for (const flag of CI_ENV_FLAGS) {
+    if (process.env[flag] === "true") return true;
+  }
+  return Boolean(process.stdin && !process.stdin.isTTY);
+}
+
+/** True when clack prompts can run (interactive TTY, not CI). */
+export function interactivePromptsAvailable(): boolean {
+  return !isCiOrNonTty();
+}
+
+/** True when the user explicitly asked for a non-interactive run. */
+export function promptingOptedOut(args: readonly string[]): boolean {
+  return NON_INTERACTIVE_FLAGS.some((flag) => args.includes(flag));
+}
+
+/**
+ * True when prompts should run for this invocation: a real terminal, and no
+ * explicit opt-out.
+ */
+export function promptingEnabled(args: readonly string[]): boolean {
+  return interactivePromptsAvailable() && !promptingOptedOut(args);
+}

package/runtime/layouts-migrator.d.mts

@@ -0,0 +1,11 @@
+export interface LayoutsMigrationResult {
+  moved: string[];
+  failed: Array<{ file: string; reason: string }>;
+}
+
+export declare function listFilesRecursively(absoluteDir: string): string[];
+
+export declare function executeLayoutsMigration(
+  root: string,
+  plan: { from: string; to: string; files: string[] },
+): LayoutsMigrationResult;

package/runtime/layouts-migrator.mjs

@@ -0,0 +1,103 @@
+/**
+ * Filesystem side of the legacy layouts migration.
+ *
+ * The decision of *what* moves lives in the domain planner; this module only
+ * reads directories and performs the move, so both halves stay testable on
+ * their own.
+ */
+import {
+  existsSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  renameSync,
+  copyFileSync,
+  rmSync,
+} from "node:fs";
+import path from "node:path";
+
+/**
+ * List every file under a directory, as POSIX paths relative to it.
+ *
+ * @param {string} absoluteDir
+ * @returns {string[]} Empty when the directory is absent or unreadable.
+ */
+export function listFilesRecursively(absoluteDir) {
+  if (!absoluteDir || !existsSync(absoluteDir)) return [];
+
+  const found = [];
+  const walk = (currentDir, prefix) => {
+    let entries;
+    try {
+      entries = readdirSync(currentDir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const absolute = path.join(currentDir, entry);
+      const relative = prefix ? `${prefix}/${entry}` : entry;
+      let isDirectory = false;
+      try {
+        isDirectory = statSync(absolute).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDirectory) walk(absolute, relative);
+      else found.push(relative);
+    }
+  };
+
+  walk(absoluteDir, "");
+  return found.sort();
+}
+
+/**
+ * Move one file, falling back to copy + delete when rename is not possible
+ * (different volumes, or a locked handle on Windows).
+ *
+ * @param {string} fromAbsolute
+ * @param {string} toAbsolute
+ */
+function moveFile(fromAbsolute, toAbsolute) {
+  mkdirSync(path.dirname(toAbsolute), { recursive: true });
+  try {
+    renameSync(fromAbsolute, toAbsolute);
+  } catch {
+    copyFileSync(fromAbsolute, toAbsolute);
+    rmSync(fromAbsolute, { force: true });
+  }
+}
+
+/**
+ * Execute a migration plan produced by `planLayoutsMigration`.
+ *
+ * Files are moved one by one so a single failure is reported without aborting
+ * the rest; the legacy folder is removed only once it is genuinely empty.
+ *
+ * @param {string} root Project root the plan's paths are relative to.
+ * @param {{ from: string, to: string, files: string[] }} plan
+ * @returns {{ moved: string[], failed: Array<{ file: string, reason: string }> }}
+ */
+export function executeLayoutsMigration(root, plan) {
+  const moved = [];
+  const failed = [];
+
+  const fromRoot = path.join(root, ...plan.from.split("/"));
+  const toRoot = path.join(root, ...plan.to.split("/"));
+
+  for (const file of plan.files) {
+    const segments = file.split("/");
+    try {
+      moveFile(path.join(fromRoot, ...segments), path.join(toRoot, ...segments));
+      moved.push(file);
+    } catch (error) {
+      failed.push({ file, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  if (failed.length === 0 && listFilesRecursively(fromRoot).length === 0) {
+    rmSync(fromRoot, { recursive: true, force: true });
+  }
+
+  return { moved, failed };
+}