@gitpagedocs/cli 0.0.1

package/runtime/doc-path-resolver.mjs

@@ -0,0 +1,59 @@
+/** Map doc paths to content keys and apply version badges */
+
+export function parseDocFileToKey(fileName) {
+  if (fileName === "index.md") return "index";
+  if (fileName === "getting-started.md") return "gettingStarted";
+  if (fileName === "configuration.md") return "configuration";
+  if (fileName === "deployment.md") return "deployment";
+  if (fileName === "architecture.md") return "architecture";
+  if (fileName === "themes.md") return "themes";
+  if (fileName === "faq.md") return "faq";
+  if (fileName === "project-overview.md") return "projectOverview";
+  if (fileName === "functionalities.md") return "functionalities";
+  if (fileName === "github-issues-projects.md") return "githubIssuesProjects";
+  if (fileName === "git-introduction.md") return "gitIntroduction";
+  if (fileName === "authorized-routes.md") return "authorizedRoutes";
+  return undefined;
+}
+
+export function parseHtmlFileToKey(fileName) {
+  const base = fileName.replace(/\.html$/, "");
+  if (base === "source-viewer") return "sourceViewer";
+  return undefined;
+}
+
+export function extractLanguageFromPath(docPath) {
+  const match = docPath.match(/\/(pt|en|es)\//);
+  return match?.[1];
+}
+
+export function withVersionBadge(content, versionId, language) {
+  const normalized = typeof content === "string" ? content : "";
+  if (!normalized.trim()) {
+    return normalized;
+  }
+
+  const alreadyTagged =
+    normalized.includes(`Version: ${versionId}`) ||
+    normalized.includes(`Versao: ${versionId}`) ||
+    normalized.includes(`Version (ES): ${versionId}`);
+  if (alreadyTagged) {
+    return normalized;
+  }
+
+  const label = `> ${versionLabelPrefix(language)}: ${versionId}`;
+
+  return `${normalized.trimEnd()}\n\n${label}\n`;
+}
+
+/** Badge wording per language; every other language reads the English form. */
+const VERSION_LABEL_PREFIXES = { pt: "Versao", es: "Version (ES)" };
+
+function versionLabelPrefix(language) {
+  return VERSION_LABEL_PREFIXES[language] ?? "Version";
+}
+
+export function normalizeToOutputPath(outputDir, configPath) {
+  const normalized = configPath.replace(/^gitpagedocs\//, "");
+  return `${outputDir}/${normalized}`;
+}

package/runtime/exec.mjs

@@ -0,0 +1,168 @@
+import { accessSync, constants, statSync } from "node:fs";
+import path from "node:path";
+import { execFileSync, spawn } from "node:child_process";
+
+/**
+ * Child-process helpers that never rely on the OS resolving a bare command
+ * name through PATH at spawn time and never build a shell command string.
+ *
+ * Every entry point takes the program name (e.g. "git"), resolves it to an
+ * absolute path up front by walking PATH ourselves, and hands that absolute
+ * path plus an argument ARRAY to `execFileSync`/`spawn`. Owner, repo, branch
+ * and URL values therefore reach the child as discrete argv entries instead of
+ * being interpolated into a shell string.
+ */
+
+const IS_WINDOWS = process.platform === "win32";
+
+/** Windows extensions that CreateProcess/cmd.exe can actually launch. */
+const WINDOWS_EXECUTABLE_EXTENSIONS = [".COM", ".EXE", ".BAT", ".CMD"];
+
+/** Batch launchers are not executables: Windows runs them through cmd.exe. */
+const CMD_SHELL_EXTENSIONS = new Set([".cmd", ".bat"]);
+
+function readEnvVar(env, name) {
+  if (env[name] !== undefined) return env[name];
+  if (!IS_WINDOWS) return undefined;
+  // A plain object spread from `process.env` on Windows keeps the original
+  // casing ("Path"), so the case-insensitive lookup `process.env` offers is
+  // lost. Restore it for the two variables PATH resolution depends on.
+  const wanted = name.toUpperCase();
+  const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === wanted);
+  return key === undefined ? undefined : env[key];
+}
+
+function pathDirectories(env) {
+  return (readEnvVar(env, "PATH") ?? "").split(path.delimiter).filter(Boolean);
+}
+
+function windowsExtensions(env) {
+  const configured = (readEnvVar(env, "PATHEXT") ?? "")
+    .split(";")
+    .map((ext) => ext.trim().toUpperCase())
+    .filter((ext) => WINDOWS_EXECUTABLE_EXTENSIONS.includes(ext));
+  return configured.length > 0 ? configured : WINDOWS_EXECUTABLE_EXTENSIONS;
+}
+
+function isExecutableFile(candidate) {
+  try {
+    if (!statSync(candidate).isFile()) return false;
+    if (!IS_WINDOWS) accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function candidateFileNames(name, env) {
+  if (!IS_WINDOWS) return [name];
+  const upper = name.toUpperCase();
+  const extensions = windowsExtensions(env);
+  if (extensions.some((ext) => upper.endsWith(ext))) return [name];
+  return extensions.map((ext) => `${name}${ext}`);
+}
+
+function usesCmdShell(file) {
+  return IS_WINDOWS && CMD_SHELL_EXTENSIONS.has(path.extname(file).toLowerCase());
+}
+
+function quoteForCmd(value) {
+  const text = String(value);
+  if (/["\r\n]/.test(text)) {
+    throw new Error(`Cannot pass ${JSON.stringify(text)} through a .cmd/.bat launcher: quotes and line breaks are not supported.`);
+  }
+  return `"${text}"`;
+}
+
+/**
+ * Resolve `name` to the absolute path of the executable that PATH points at.
+ *
+ * Directories are scanned in PATH order. On Windows the PATHEXT executable
+ * extensions are tried in their configured order (.COM, .EXE, .BAT, .CMD by
+ * default), so `git` resolves to `git.exe` before any `git.cmd` shim. A name
+ * that already contains a path separator is only checked, never searched.
+ *
+ * @param {string} name Program name such as "git", "gh" or "npx".
+ * @param {{ env?: NodeJS.ProcessEnv }} [options] Environment whose PATH/PATHEXT drive the lookup (defaults to `process.env`).
+ * @returns {string} Absolute path of the executable.
+ * @throws {Error} When nothing on PATH matches, with an actionable message.
+ */
+export function resolveExecutable(name, options = {}) {
+  if (typeof name !== "string" || name.trim() === "") {
+    throw new TypeError("resolveExecutable(name) requires a non-empty program name.");
+  }
+  const env = options.env ?? process.env;
+
+  if (name.includes("/") || name.includes("\\")) {
+    const direct = path.resolve(name);
+    if (isExecutableFile(direct)) return direct;
+    throw new Error(`\`${name}\` is not an executable file (looked at ${direct}).`);
+  }
+
+  const fileNames = candidateFileNames(name, env);
+  for (const directory of pathDirectories(env)) {
+    for (const fileName of fileNames) {
+      const candidate = path.join(directory, fileName);
+      if (isExecutableFile(candidate)) return path.resolve(candidate);
+    }
+  }
+
+  throw new Error(
+    `\`${name}\` was not found on PATH. Install it and make sure the directory that contains it is listed in the PATH environment variable, then retry.`,
+  );
+}
+
+function launchOptions(file, args, options) {
+  if (usesCmdShell(file)) {
+    // Node refuses to spawn .cmd/.bat files without a shell (EINVAL, see
+    // CVE-2024-27980) because only cmd.exe can interpret them. The launcher path
+    // is already absolute and every argument is individually quoted, so cmd.exe
+    // receives a fixed command line rather than one assembled from user input.
+    return { file: quoteForCmd(file), args: args.map(quoteForCmd), options: { ...options, shell: true } };
+  }
+  return { file, args, options: { ...options, shell: false } };
+}
+
+/**
+ * Run `name` synchronously with an argument array and wait for it to finish.
+ * Same contract as `execFileSync` (throws on a non-zero exit, returns stdout).
+ *
+ * @param {string} name Program name such as "git".
+ * @param {readonly string[]} [args] Arguments passed verbatim, one argv entry each.
+ * @param {import("node:child_process").ExecFileSyncOptions} [options] Forwarded to `execFileSync` (cwd, env, stdio, ...).
+ * @returns {Buffer | string} stdout, as `execFileSync` returns it.
+ */
+export function runExecutable(name, args = [], options = {}) {
+  const resolved = resolveExecutable(name, { env: options.env });
+  const launch = launchOptions(resolved, args, options);
+  return execFileSync(launch.file, launch.args, launch.options);
+}
+
+/**
+ * Run `name` synchronously and return its trimmed stdout as a string.
+ * Uses `stdio: "pipe"` unless the caller overrides it.
+ *
+ * @param {string} name Program name such as "git".
+ * @param {readonly string[]} [args] Arguments passed verbatim, one argv entry each.
+ * @param {import("node:child_process").ExecFileSyncOptions} [options] Forwarded to `execFileSync`.
+ * @returns {string} Trimmed stdout.
+ */
+export function runExecutableCapture(name, args = [], options = {}) {
+  const output = runExecutable(name, args, { stdio: "pipe", ...options });
+  // execFileSync yields null when the caller routes stdout away from "pipe".
+  return output == null ? "" : output.toString().trim();
+}
+
+/**
+ * Start `name` asynchronously (like `spawn`) with an argument array.
+ *
+ * @param {string} name Program name such as "npx".
+ * @param {readonly string[]} [args] Arguments passed verbatim, one argv entry each.
+ * @param {import("node:child_process").SpawnOptions} [options] Forwarded to `spawn` (cwd, env, stdio, ...).
+ * @returns {import("node:child_process").ChildProcess} The spawned child.
+ */
+export function spawnExecutable(name, args = [], options = {}) {
+  const resolved = resolveExecutable(name, { env: options.env });
+  const launch = launchOptions(resolved, args, options);
+  return spawn(launch.file, launch.args, launch.options);
+}

package/runtime/git-ops.mjs

@@ -0,0 +1,112 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { runExecutable, runExecutableCapture } from "./exec.mjs";
+
+/** Detect { owner, repo } from the git `origin` remote URL, or null. */
+export function detectRepoFromGit(root) {
+  try {
+    const url = runExecutableCapture("git", ["remote", "get-url", "origin"], { cwd: root });
+    const match = url.match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?$/);
+    if (match) return { owner: match[1], repo: match[2] };
+  } catch {
+    // no remote / not a repo / git not installed
+  }
+  return null;
+}
+
+export function tryConfigurePagesToGitHubActions(owner, repo, branch, root) {
+  try {
+    runExecutable("gh", ["--version"], { cwd: root, stdio: "ignore" });
+  } catch {
+    console.warn(
+      "GitHub CLI (gh) not found. Could not auto-configure Pages source. Set GitHub Pages source to 'GitHub Actions' manually in repository settings.",
+    );
+    return;
+  }
+
+  // Each candidate is an argv array: owner/repo/branch travel as discrete
+  // arguments, never through a shell string.
+  const pagesEndpoint = `repos/${owner}/${repo}/pages`;
+  const candidates = [
+    ["api", "-X", "PUT", pagesEndpoint, "-f", "build_type=workflow"],
+    ["api", "-X", "POST", pagesEndpoint, "-f", "build_type=workflow"],
+    ["api", "-X", "POST", pagesEndpoint, "-f", `source[branch]=${branch}`, "-f", "source[path]=/"],
+    ["api", "-X", "PUT", pagesEndpoint, "-f", `source[branch]=${branch}`, "-f", "source[path]=/", "-f", "build_type=workflow"],
+  ];
+
+  for (const args of candidates) {
+    try {
+      runExecutable("gh", args, { cwd: root, stdio: "ignore" });
+      console.log("GitHub Pages source configured for GitHub Actions.");
+      return;
+    } catch {
+      // Try next candidate endpoint.
+    }
+  }
+
+  console.warn(
+    "Could not auto-configure Pages source through GitHub API. Set repository Pages source to 'GitHub Actions' manually.",
+  );
+}
+
+export function getCurrentGitBranch(root) {
+  try {
+    const branch = runExecutableCapture("git", ["branch", "--show-current"], { cwd: root });
+    return branch || "main";
+  } catch {
+    return "main";
+  }
+}
+
+export function runGitPushForGeneratedArtifacts(options, root, sanitizeSegment) {
+  const owner = sanitizeSegment(options.githubOwner);
+  const repo = sanitizeSegment(options.githubRepo);
+  if (!owner || !repo) {
+    throw new Error("`--push` requires owner and repo. Use `--owner <owner> --repo <repo>` or `--<owner> --<repo>`.");
+  }
+  if (!existsSync(path.join(root, ".git"))) {
+    throw new Error("Current directory is not a git repository. Initialize git before using --push.");
+  }
+
+  const repoUrl = `https://github.com/${owner}/${repo}.git`;
+  try {
+    runExecutable("git", ["remote", "get-url", "origin"], { cwd: root, stdio: "ignore" });
+  } catch {
+    runExecutable("git", ["remote", "add", "origin", repoUrl], { cwd: root, stdio: "inherit" });
+  }
+
+  runExecutable("git", ["add", "gitpagedocs", ".github/workflows/gitpagedocs-pages.yml"], { cwd: root, stdio: "inherit" });
+
+  let hasStagedChanges = false;
+  try {
+    runExecutable("git", ["diff", "--cached", "--quiet"], { cwd: root, stdio: "ignore" });
+  } catch {
+    hasStagedChanges = true;
+  }
+
+  if (!hasStagedChanges) {
+    return;
+  }
+
+  runExecutable("git", ["commit", "-m", "chore: setup gitpagedocs pages workflow"], { cwd: root, stdio: "inherit" });
+
+  const currentBranch = getCurrentGitBranch(root);
+  try {
+    runExecutable("git", ["push", "-u", "origin", currentBranch], { cwd: root, stdio: "inherit" });
+    tryConfigurePagesToGitHubActions(owner, repo, currentBranch, root);
+    return;
+  } catch {
+    console.warn("Initial push failed. Trying automatic rebase with remote branch...");
+  }
+
+  try {
+    runExecutable("git", ["pull", "--rebase", "origin", currentBranch], { cwd: root, stdio: "inherit" });
+    runExecutable("git", ["push", "-u", "origin", currentBranch], { cwd: root, stdio: "inherit" });
+  } catch {
+    throw new Error(
+      `Failed to push after automatic rebase on branch '${currentBranch}'. Resolve conflicts and run 'git push -u origin ${currentBranch}' manually.`,
+    );
+  }
+
+  tryConfigurePagesToGitHubActions(owner, repo, currentBranch, root);
+}

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,117 @@
+/**
+ * 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(compareCodeUnits);
+}
+
+/**
+ * Plain UTF-16 code-unit order (what `sort()` does by default), spelled out so
+ * the listing never depends on the runtime locale.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function compareCodeUnits(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+/**
+ * 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 };
+}

package/runtime/output.mjs

@@ -0,0 +1,201 @@
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  parseDocFileToKey,
+  parseHtmlFileToKey,
+  extractLanguageFromPath,
+  withVersionBadge,
+  normalizeToOutputPath,
+} from "./doc-path-resolver.mjs";
+import { layoutsArtifactPaths } from "../contracts/layouts-paths.mjs";
+import { languageArtifactPaths } from "../contracts/langs-paths.mjs";
+import { SUPPORTED_LANGUAGES } from "../contracts/languages.mjs";
+
+const DEFAULT_ICON_SVG = `<?xml version="1.0" encoding="utf-8"?>
+<svg width="800px" height="800px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path opacity="0.1" fill-rule="evenodd" clip-rule="evenodd" d="M12 3C4.5885 3 3 4.5885 3 12C3 19.4115 4.5885 21 12 21C19.4115 21 21 19.4115 21 12C21 4.5885 19.4115 3 12 3ZM14.2695 9.03471C15.1872 8.34452 15.7204 8.25293 15.9299 8.25017C16.1326 8.86788 16.1588 9.54654 16.0042 10.1835C15.9945 10.2234 15.9842 10.263 15.9731 10.3025C15.941 10.4168 15.9647 10.5393 16.0366 10.6333L16.0377 10.6347C16.0521 10.6537 16.0664 10.6728 16.0805 10.6922C16.5194 11.2949 16.7603 12.0687 16.7497 12.8714L16.7496 12.8747C16.7496 14.5738 16.3076 15.5644 15.6994 16.1583C15.0859 16.7572 14.2627 16.9938 13.4137 17.0968L13.3898 17.0997L13.3777 17.1014C12.443 17.2601 11.5456 17.2688 10.6078 17.1286L10.604 17.1281L10.5687 17.1233C9.72415 17.0085 8.90483 16.7616 8.29455 16.1566C7.68912 15.5564 7.25036 14.5643 7.25038 12.8747L7.25034 12.8714C7.23972 12.0687 7.48056 11.2949 7.91949 10.6922C7.93482 10.6711 7.9504 10.6503 7.96621 10.6297C8.03648 10.538 8.05962 10.4184 8.02812 10.3068L8.02599 10.2993C8.01523 10.2608 8.00513 10.2222 7.99569 10.1834C7.84087 9.54684 7.86561 8.86863 8.0659 8.25016C8.27679 8.2528 8.81228 8.34432 9.73045 9.03473C9.76619 9.0616 9.80249 9.08937 9.83937 9.11807C9.93139 9.19 10.0529 9.21205 10.1644 9.17703L10.1657 9.17661C10.2268 9.15768 10.2882 9.13972 10.3496 9.12272C11.4349 8.82255 12.5651 8.82255 13.6504 9.12272C13.7088 9.13888 13.7671 9.15592 13.8253 9.17382L13.8277 9.17457C13.9431 9.21015 14.0704 9.18836 14.1678 9.11252C14.2022 9.08578 14.2361 9.05985 14.2695 9.03471Z" fill="#323232"/>
+<path d="M13.717 8.88177C12.5881 8.56954 11.4119 8.56954 10.283 8.88177C10.2637 8.8871 10.2444 8.89254 10.2252 8.89808C10.1067 8.93218 9.97923 8.909 9.8807 8.83491V8.83491C8.69311 7.94193 8.07278 7.98181 7.91927 8.01161V8.01161C7.8946 8.0164 7.87585 8.03481 7.86732 8.05844C7.86516 8.06441 7.86303 8.07038 7.8609 8.07636C7.61639 8.76505 7.57904 9.52813 7.75277 10.2425C7.76289 10.2841 7.77371 10.3255 7.78525 10.3667C7.78601 10.3694 7.78677 10.3721 7.78753 10.3748C7.79754 10.4102 7.7902 10.4483 7.7678 10.4776V10.4776C7.75074 10.4998 7.73394 10.5223 7.71741 10.545C7.24479 11.1939 6.98907 12.0213 7.00036 12.8747C7.00036 16.3399 8.80396 17.1358 10.535 17.3711L10.5708 17.3758C11.5347 17.5199 12.4587 17.511 13.4195 17.3479L13.4438 17.345C15.1832 17.1339 16.9996 16.3587 16.9996 12.8747C17.0109 12.0213 16.7552 11.1939 16.2826 10.545C16.2674 10.5242 16.252 10.5035 16.2364 10.483C16.236 10.4825 16.2356 10.482 16.2352 10.4815C16.211 10.4498 16.203 10.4085 16.2138 10.3701V10.3701C16.2257 10.3277 16.2368 10.2852 16.2471 10.2425C16.421 9.52611 16.3815 8.76076 16.1329 8.07176C16.1313 8.06753 16.1298 8.06331 16.1283 8.05909C16.1195 8.03503 16.1004 8.01628 16.0752 8.01142V8.01142C15.921 7.98164 15.3041 7.94381 14.1193 8.83491V8.83491C14.0208 8.90896 13.8933 8.93197 13.7748 8.89804C13.7556 8.89252 13.7363 8.8871 13.717 8.88177Z" stroke="#323232" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M3 12C3 4.5885 4.5885 3 12 3C19.4115 3 21 4.5885 21 12C21 19.4115 19.4115 21 12 21C4.5885 21 3 19.4115 3 12Z" stroke="#323232" stroke-width="2"/>
+</svg>
+`;
+
+function listExistingVersionIds(root, outputDir) {
+  const versionsRoot = path.join(root, outputDir, "docs", "versions");
+  if (!existsSync(versionsRoot)) return [];
+  return readdirSync(versionsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
+function removeLegacySourceViewerFiles(root, outputDir) {
+  const versionIds = listExistingVersionIds(root, outputDir);
+  for (const versionId of versionIds) {
+    for (const language of SUPPORTED_LANGUAGES) {
+      for (const fileName of ["source-viewer", "source-viewer.html"]) {
+        const legacyPath = path.join(root, outputDir, "docs", "versions", versionId, language, fileName);
+        if (existsSync(legacyPath)) {
+          rmSync(legacyPath, { force: true });
+        }
+      }
+    }
+  }
+}
+
+async function writeJson(root, relativePath, data) {
+  const absolutePath = path.join(root, relativePath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+}
+
+export async function writeText(root, relativePath, data) {
+  const absolutePath = path.join(root, relativePath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, data, "utf-8");
+}
+
+/**
+ * Write the local layout artifacts into the standalone layouts home.
+ *
+ * No layouts folder is ever deleted here. The legacy `<outputDir>/layouts/`
+ * folder can hold hand-edited templates and the viewer still reads it, so
+ * relocating it is an explicit, confirmed migration rather than a side effect of
+ * generating. Switching back to official layouts likewise leaves an existing
+ * layouts home in place: `layoutsConfigPathOficial` already decides which source
+ * the viewer uses, so the files are inert rather than harmful.
+ */
+async function writeLayoutArtifacts(options) {
+  const { root, layoutsDir, useLocalLayoutConfig, layouts, artifacts, createThemeTemplate } = options;
+
+  if (!useLocalLayoutConfig) return;
+
+  const paths = layoutsArtifactPaths(layoutsDir);
+  await writeJson(root, paths.config, artifacts.layoutsConfig);
+  await writeJson(root, paths.fallbackConfig, artifacts.fallbackLayoutsConfig);
+  for (const layout of layouts) {
+    await writeJson(root, `${paths.root}/${layout.file}`, createThemeTemplate(layout));
+  }
+}
+
+/**
+ * Write one UI-strings bundle per shipped language. Which ones are on is
+ * `site.languages` in config.json, so the 1.1.68 `langs.json` manifest is
+ * removed: a stale copy would only mislead.
+ */
+async function writeLanguageArtifacts(root, outputDir, artifacts) {
+  const paths = languageArtifactPaths(outputDir);
+  rmSync(path.join(root, paths.legacyManifest), { force: true });
+  for (const [language, bundle] of Object.entries(artifacts.languageBundles)) {
+    await writeJson(root, paths.bundle(language), bundle);
+  }
+}
+
+/** Keep only versioned docs output in docs/, removing legacy root language folders. */
+function removeLegacyLanguageDirs(root, outputDir) {
+  for (const legacyLanguageDir of SUPPORTED_LANGUAGES) {
+    const legacyPath = path.join(root, outputDir, "docs", legacyLanguageDir);
+    if (existsSync(legacyPath)) {
+      rmSync(legacyPath, { recursive: true, force: true });
+    }
+  }
+}
+
+async function writeVersionConfigs(root, outputDir, versionConfigs) {
+  for (const [versionId, versionConfig] of Object.entries(versionConfigs)) {
+    await writeJson(root, `${outputDir}/docs/versions/${versionId}/config.json`, versionConfig);
+  }
+}
+
+async function writeMarkdownDoc(root, outputDir, versionId, docPath, docs) {
+  const key = parseDocFileToKey(path.basename(docPath));
+  const language = extractLanguageFromPath(docPath);
+  const content = key && language ? docs?.[language]?.[key] : undefined;
+  if (!content) return;
+  const versionedContent = withVersionBadge(content, versionId, language);
+  await writeText(root, normalizeToOutputPath(outputDir, docPath), versionedContent);
+}
+
+async function writeVersionMarkdownDocs(root, outputDir, versionId, versionConfig, docs) {
+  const versionRoutesMd = versionConfig["routes-md"] ?? versionConfig.routes ?? [];
+  for (const route of versionRoutesMd) {
+    for (const docPath of Object.values(route.path ?? {})) {
+      await writeMarkdownDoc(root, outputDir, versionId, docPath, docs);
+    }
+  }
+}
+
+async function writeHtmlDoc(root, outputDir, docPath, docsHtml) {
+  const key = parseHtmlFileToKey(path.basename(docPath));
+  const language = extractLanguageFromPath(docPath);
+  const content = key && language ? docsHtml[key]?.[language] : undefined;
+  if (!content) return;
+  const normalizedHtmlPath = normalizeToOutputPath(outputDir, docPath);
+  await writeText(root, normalizedHtmlPath, content);
+  // Backward-compatible alias for tools or users that still expect ".html".
+  if (!path.extname(docPath)) {
+    await writeText(root, `${normalizedHtmlPath}.html`, content);
+  }
+}
+
+async function writeVersionHtmlDocs(root, outputDir, versionConfig, docsHtml) {
+  const versionRoutesHtml = versionConfig["routes-html"] ?? [];
+  for (const route of versionRoutesHtml) {
+    if (route.url) continue;
+    for (const docPath of Object.values(route.path ?? {})) {
+      await writeHtmlDoc(root, outputDir, docPath, docsHtml);
+    }
+  }
+}
+
+/** Ensure version folders always include an index file. */
+async function writeVersionFallbackIndexes(root, outputDir, versionId, docs) {
+  for (const language of SUPPORTED_LANGUAGES) {
+    const fallbackIndex = docs?.[language]?.index;
+    if (!fallbackIndex) continue;
+    const versionIndexPath = `${outputDir}/docs/versions/${versionId}/${language}/index.md`;
+    if (!existsSync(path.join(root, versionIndexPath))) {
+      const versionedFallbackIndex = withVersionBadge(fallbackIndex, versionId, language);
+      await writeText(root, versionIndexPath, versionedFallbackIndex);
+    }
+  }
+}
+
+async function writeVersionedDocs(root, outputDir, artifacts) {
+  const docsHtml = artifacts.docsHtml ?? {};
+  for (const [versionId, versionConfig] of Object.entries(artifacts.versionConfigs)) {
+    await writeVersionMarkdownDocs(root, outputDir, versionId, versionConfig, artifacts.docs);
+    await writeVersionHtmlDocs(root, outputDir, versionConfig, docsHtml);
+    await writeVersionFallbackIndexes(root, outputDir, versionId, artifacts.docs);
+  }
+}
+
+export async function writeConfigOnlyOutput(options) {
+  const {
+    root,
+    outputDir,
+    artifacts,
+    useLocalLayoutConfig,
+    layoutsDir,
+    layouts,
+    createThemeTemplate,
+  } = options;
+
+  removeLegacyLanguageDirs(root, outputDir);
+
+  await writeJson(root, `${outputDir}/config.json`, artifacts.rootConfig);
+  await writeLanguageArtifacts(root, outputDir, artifacts);
+  await writeText(root, `${outputDir}/icon.svg`, DEFAULT_ICON_SVG);
+  await writeLayoutArtifacts({
+    root,
+    layoutsDir,
+    useLocalLayoutConfig,
+    layouts,
+    artifacts,
+    createThemeTemplate,
+  });
+  await writeVersionConfigs(root, outputDir, artifacts.versionConfigs);
+
+  removeLegacySourceViewerFiles(root, outputDir);
+
+  await writeVersionedDocs(root, outputDir, artifacts);
+}