@gitpagedocs/cli 0.0.1

package/data/theme-colors.mjs

@@ -0,0 +1,444 @@
+export const THEME_COLORS = {
+  "duet-light": {
+    background: "#FFFFFF", primary: "#000000", secondary: "#5E5E5E", text: "#000000",
+    textSecondary: "#5E5E5E", cardBackground: "#FFFFFF", cardBorder: "#E2E2E2", error: "#000000", success: "#000000",
+  },
+  "duet-dark": {
+    background: "#000000", primary: "#FFFFFF", secondary: "#AFAFAF", text: "#FFFFFF",
+    textSecondary: "#AFAFAF", cardBackground: "#282828", cardBorder: "#4B4B4B", error: "#FFFFFF", success: "#FFFFFF",
+  },
+  "matrix-dark": {
+    background: "#030606",
+    primary: "#22C55E",
+    secondary: "#4ADE80",
+    text: "#DCFCE7",
+    textSecondary: "#86EFAC",
+    cardBackground: "#04120A",
+    cardBorder: "#14532D",
+    error: "#F87171",
+    success: "#22C55E",
+  },
+  "matrix-light": {
+    background: "#F0FDF4",
+    primary: "#15803D",
+    secondary: "#16A34A",
+    text: "#052E16",
+    textSecondary: "#166534",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#BBF7D0",
+    error: "#DC2626",
+    success: "#16A34A",
+  },
+  default: {
+    background: "#FFFFFF",
+    primary: "#0EA5E9",
+    secondary: "#2563EB",
+    text: "#0F172A",
+    textSecondary: "#334155",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#E2E8F0",
+    error: "#DC2626",
+    success: "#16A34A",
+  },
+  "github-dark": {
+    background: "#0D1117",
+    primary: "#58A6FF",
+    secondary: "#2EA043",
+    text: "#E6EDF3",
+    textSecondary: "#8B949E",
+    cardBackground: "#161B22",
+    cardBorder: "#30363D",
+    error: "#F85149",
+    success: "#3FB950",
+  },
+  "github-light": {
+    background: "#FFFFFF",
+    primary: "#0969DA",
+    secondary: "#1A7F37",
+    text: "#1F2328",
+    textSecondary: "#57606A",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#D0D7DE",
+    error: "#D1242F",
+    success: "#1A7F37",
+  },
+  "cyberpunk-dark": {
+    background: "#090014",
+    primary: "#F472B6",
+    secondary: "#22D3EE",
+    text: "#F5D0FE",
+    textSecondary: "#C4B5FD",
+    cardBackground: "#160024",
+    cardBorder: "#7E22CE",
+    error: "#FB7185",
+    success: "#2DD4BF",
+  },
+  "cyberpunk-light": {
+    background: "#FFF1F8",
+    primary: "#DB2777",
+    secondary: "#0891B2",
+    text: "#4A044E",
+    textSecondary: "#6D28D9",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#F5D0FE",
+    error: "#E11D48",
+    success: "#0D9488",
+  },
+  "aurora-dark": {
+    background: "#070A14",
+    primary: "#7C3AED",
+    secondary: "#22D3EE",
+    text: "#E5E7EB",
+    textSecondary: "#B8C3D6",
+    cardBackground: "#101726",
+    cardBorder: "#334155",
+    error: "#FB7185",
+    success: "#34D399",
+  },
+  "aurora-light": {
+    background: "#F8FAFC",
+    primary: "#6D28D9",
+    secondary: "#0891B2",
+    text: "#0F172A",
+    textSecondary: "#475569",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#E2E8F0",
+    error: "#E11D48",
+    success: "#059669",
+  },
+  "nord-dark": {
+    background: "#2E3440",
+    primary: "#88C0D0",
+    secondary: "#81A1C1",
+    text: "#ECEFF4",
+    textSecondary: "#D8DEE9",
+    cardBackground: "#3B4252",
+    cardBorder: "#4C566A",
+    error: "#BF616A",
+    success: "#A3BE8C",
+  },
+  "nord-light": {
+    background: "#ECEFF4",
+    primary: "#5E81AC",
+    secondary: "#81A1C1",
+    text: "#2E3440",
+    textSecondary: "#4C566A",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#D8DEE9",
+    error: "#BF616A",
+    success: "#5E81AC",
+  },
+  "sunset-dark": {
+    background: "#1A0F0C",
+    primary: "#FB923C",
+    secondary: "#F472B6",
+    text: "#FFE4D6",
+    textSecondary: "#FDBA74",
+    cardBackground: "#2A1611",
+    cardBorder: "#7C2D12",
+    error: "#FB7185",
+    success: "#4ADE80",
+  },
+  "sunset-light": {
+    background: "#FFF7ED",
+    primary: "#EA580C",
+    secondary: "#DB2777",
+    text: "#431407",
+    textSecondary: "#9A3412",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#FED7AA",
+    error: "#E11D48",
+    success: "#16A34A",
+  },
+  "mono-dark": {
+    background: "#0B0F0C",
+    primary: "#A3E635",
+    secondary: "#65A30D",
+    text: "#ECFCCB",
+    textSecondary: "#BEF264",
+    cardBackground: "#141A16",
+    cardBorder: "#365314",
+    error: "#F87171",
+    success: "#84CC16",
+  },
+  "mono-light": {
+    background: "#F7FEE7",
+    primary: "#4D7C0F",
+    secondary: "#65A30D",
+    text: "#1A2E05",
+    textSecondary: "#3F6212",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#D9F99D",
+    error: "#DC2626",
+    success: "#4D7C0F",
+  },
+  "oceanic-dark": {
+    background: "#06121A",
+    primary: "#0EA5E9",
+    secondary: "#22D3EE",
+    text: "#DDF6FF",
+    textSecondary: "#9CC5D8",
+    cardBackground: "#0C1C27",
+    cardBorder: "#1E3A4B",
+    error: "#F87171",
+    success: "#34D399",
+  },
+  "oceanic-light": {
+    background: "#F0F9FF",
+    primary: "#0284C7",
+    secondary: "#0891B2",
+    text: "#0C4A6E",
+    textSecondary: "#1D4E89",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#BAE6FD",
+    error: "#DC2626",
+    success: "#0F766E",
+  },
+  "rose-dark": {
+    background: "#1B0B13",
+    primary: "#F43F5E",
+    secondary: "#FB7185",
+    text: "#FFE4EA",
+    textSecondary: "#F9A8D4",
+    cardBackground: "#28111C",
+    cardBorder: "#7A1F3D",
+    error: "#FB7185",
+    success: "#34D399",
+  },
+  "rose-light": {
+    background: "#FFF1F5",
+    primary: "#E11D48",
+    secondary: "#DB2777",
+    text: "#7A1733",
+    textSecondary: "#9D174D",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#FBCFE8",
+    error: "#DC2626",
+    success: "#059669",
+  },
+  "forest-dark": {
+    background: "#0A140F",
+    primary: "#22C55E",
+    secondary: "#4ADE80",
+    text: "#DCFCE7",
+    textSecondary: "#86EFAC",
+    cardBackground: "#122017",
+    cardBorder: "#275A3F",
+    error: "#F87171",
+    success: "#22C55E",
+  },
+  "forest-light": {
+    background: "#F3FFF5",
+    primary: "#15803D",
+    secondary: "#16A34A",
+    text: "#14532D",
+    textSecondary: "#166534",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#BBF7D0",
+    error: "#DC2626",
+    success: "#15803D",
+  },
+  "graphite-dark": {
+    background: "#0B0F14",
+    primary: "#60A5FA",
+    secondary: "#93C5FD",
+    text: "#E5E7EB",
+    textSecondary: "#9CA3AF",
+    cardBackground: "#141A22",
+    cardBorder: "#2A3442",
+    error: "#F87171",
+    success: "#34D399",
+  },
+  "graphite-light": {
+    background: "#F8FAFC",
+    primary: "#2563EB",
+    secondary: "#3B82F6",
+    text: "#0F172A",
+    textSecondary: "#475569",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#CBD5E1",
+    error: "#DC2626",
+    success: "#059669",
+  },
+  "lava-dark": {
+    background: "#1A0D08",
+    primary: "#F97316",
+    secondary: "#FB923C",
+    text: "#FFE7D5",
+    textSecondary: "#FDBA74",
+    cardBackground: "#2B1610",
+    cardBorder: "#7C2D12",
+    error: "#FB7185",
+    success: "#4ADE80",
+  },
+  "lava-light": {
+    background: "#FFF7ED",
+    primary: "#EA580C",
+    secondary: "#F97316",
+    text: "#7C2D12",
+    textSecondary: "#9A3412",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#FED7AA",
+    error: "#DC2626",
+    success: "#16A34A",
+  },
+  "skyline-dark": {
+    background: "#080E1E",
+    primary: "#3B82F6",
+    secondary: "#22D3EE",
+    text: "#E0E7FF",
+    textSecondary: "#93C5FD",
+    cardBackground: "#101A2F",
+    cardBorder: "#2B3A67",
+    error: "#F87171",
+    success: "#34D399",
+  },
+  "skyline-light": {
+    background: "#EFF6FF",
+    primary: "#2563EB",
+    secondary: "#0EA5E9",
+    text: "#1E3A8A",
+    textSecondary: "#1D4ED8",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#BFDBFE",
+    error: "#DC2626",
+    success: "#059669",
+  },
+  "emerald-dark": {
+    background: "#07150F",
+    primary: "#10B981",
+    secondary: "#34D399",
+    text: "#D1FAE5",
+    textSecondary: "#6EE7B7",
+    cardBackground: "#10231A",
+    cardBorder: "#1F6A4C",
+    error: "#F87171",
+    success: "#10B981",
+  },
+  "emerald-light": {
+    background: "#ECFDF5",
+    primary: "#059669",
+    secondary: "#10B981",
+    text: "#064E3B",
+    textSecondary: "#065F46",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#A7F3D0",
+    error: "#DC2626",
+    success: "#059669",
+  },
+  "violet-dark": {
+    background: "#12081F",
+    primary: "#8B5CF6",
+    secondary: "#A78BFA",
+    text: "#EDE9FE",
+    textSecondary: "#C4B5FD",
+    cardBackground: "#1E1033",
+    cardBorder: "#4C1D95",
+    error: "#FB7185",
+    success: "#34D399",
+  },
+  "violet-light": {
+    background: "#F5F3FF",
+    primary: "#7C3AED",
+    secondary: "#8B5CF6",
+    text: "#4C1D95",
+    textSecondary: "#5B21B6",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#DDD6FE",
+    error: "#DC2626",
+    success: "#059669",
+  },
+  "amber-dark": {
+    background: "#1A1306",
+    primary: "#F59E0B",
+    secondary: "#FBBF24",
+    text: "#FEF3C7",
+    textSecondary: "#FCD34D",
+    cardBackground: "#2A1E0D",
+    cardBorder: "#7C5B13",
+    error: "#FB7185",
+    success: "#4ADE80",
+  },
+  "amber-light": {
+    background: "#FFFBEB",
+    primary: "#D97706",
+    secondary: "#F59E0B",
+    text: "#78350F",
+    textSecondary: "#92400E",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#FDE68A",
+    error: "#DC2626",
+    success: "#16A34A",
+  },
+  "slate-dark": {
+    background: "#0B1120",
+    primary: "#64748B",
+    secondary: "#94A3B8",
+    text: "#E2E8F0",
+    textSecondary: "#CBD5E1",
+    cardBackground: "#111827",
+    cardBorder: "#334155",
+    error: "#F87171",
+    success: "#34D399",
+  },
+  "slate-light": {
+    background: "#F8FAFC",
+    primary: "#475569",
+    secondary: "#64748B",
+    text: "#1E293B",
+    textSecondary: "#334155",
+    cardBackground: "#FFFFFF",
+    cardBorder: "#CBD5E1",
+    error: "#DC2626",
+    success: "#16A34A",
+  },
+  "vscode-dark": {
+    background: "#1E1E1E",
+    primary: "#007ACC",
+    secondary: "#4EC9B0",
+    text: "#D4D4D4",
+    textSecondary: "#858585",
+    cardBackground: "#252526",
+    cardBorder: "#3C3C3C",
+    error: "#F14C4C",
+    success: "#4EC9B0",
+  },
+  "vscode-light": {
+    background: "#FFFFFF",
+    primary: "#005FB8",
+    secondary: "#267F99",
+    text: "#1E1E1E",
+    textSecondary: "#6E6E6E",
+    cardBackground: "#F3F3F3",
+    cardBorder: "#E5E5E5",
+    error: "#CD3131",
+    success: "#098658",
+  },
+
+  // --- 25 modern layouts (see MODERN_LAYOUTS in cli/data/layouts.mjs) ---
+  "midnight-dark": { background: "#0A0E27", primary: "#4F7CFF", secondary: "#38BDF8", text: "#E2E8F5", textSecondary: "#94A3C8", cardBackground: "#111634", cardBorder: "#25305C", error: "#FB7185", success: "#34D399" },
+  "carbon-dark": { background: "#0A0A0A", primary: "#FFFFFF", secondary: "#A3A3A3", text: "#EDEDED", textSecondary: "#8A8A8A", cardBackground: "#161616", cardBorder: "#2E2E2E", error: "#FF6B6B", success: "#5EEAD4" },
+  "neon-noir-dark": { background: "#0B0014", primary: "#FF2E97", secondary: "#00E5FF", text: "#F5E9FF", textSecondary: "#B388D9", cardBackground: "#160022", cardBorder: "#3A0F52", error: "#FF3D71", success: "#2BFFC6" },
+  "ember-dark": { background: "#1A0F0A", primary: "#FF7A18", secondary: "#FFB347", text: "#FBE8DC", textSecondary: "#C99A82", cardBackground: "#261610", cardBorder: "#4A2A1A", error: "#FF5252", success: "#74D680" },
+  "cobalt-dark": { background: "#021024", primary: "#2563EB", secondary: "#38BDF8", text: "#DCE7FF", textSecondary: "#8FA8D6", cardBackground: "#061A3A", cardBorder: "#14315E", error: "#FB7185", success: "#34D399" },
+  "plum-dark": { background: "#15091F", primary: "#A855F7", secondary: "#F472B6", text: "#F0E4FA", textSecondary: "#B294C9", cardBackground: "#221033", cardBorder: "#3F1D5C", error: "#FB7185", success: "#4ADE80" },
+  "obsidian-dark": { background: "#060A0A", primary: "#14B8A6", secondary: "#2DD4BF", text: "#E0F2F1", textSecondary: "#8FB5B2", cardBackground: "#0E1817", cardBorder: "#1E3331", error: "#F87171", success: "#2DD4BF" },
+  "lagoon-dark": { background: "#041E26", primary: "#06B6D4", secondary: "#22D3EE", text: "#D8F3F8", textSecondary: "#84B6C0", cardBackground: "#07303A", cardBorder: "#0F4D5C", error: "#FB7185", success: "#2DD4BF" },
+  "orchid-dark": { background: "#1A0B1E", primary: "#D946EF", secondary: "#F0ABFC", text: "#F7E6FA", textSecondary: "#C792D0", cardBackground: "#2A1230", cardBorder: "#4C2256", error: "#FB7185", success: "#4ADE80" },
+  "steel-dark": { background: "#0E1116", primary: "#60A5FA", secondary: "#93C5FD", text: "#E5EAF0", textSecondary: "#98A4B5", cardBackground: "#181D26", cardBorder: "#2C3440", error: "#F87171", success: "#34D399" },
+  "moss-dark": { background: "#0D1410", primary: "#84CC16", secondary: "#A3E635", text: "#E6F0D9", textSecondary: "#9CB088", cardBackground: "#161F18", cardBorder: "#2A3A26", error: "#F87171", success: "#84CC16" },
+  "indigo-dark": { background: "#0B0B2B", primary: "#6366F1", secondary: "#818CF8", text: "#E4E4FB", textSecondary: "#9999CC", cardBackground: "#14143F", cardBorder: "#262668", error: "#FB7185", success: "#34D399" },
+  "verdant-dark": { background: "#04140D", primary: "#10B981", secondary: "#34D399", text: "#DCF5E8", textSecondary: "#84B89E", cardBackground: "#07241A", cardBorder: "#0F3D2C", error: "#FB7185", success: "#10B981" },
+  "crimson-dark": { background: "#1A0508", primary: "#EF4444", secondary: "#FB7185", text: "#FBE2E5", textSecondary: "#C98F95", cardBackground: "#260A0E", cardBorder: "#4A161C", error: "#EF4444", success: "#34D399" },
+  "velvet-dark": { background: "#15071A", primary: "#7C3AED", secondary: "#FBBF24", text: "#EFE6F5", textSecondary: "#B499C4", cardBackground: "#220F2B", cardBorder: "#3E1D4C", error: "#FB7185", success: "#FBBF24" },
+  "sakura-light": { background: "#FFF5F7", primary: "#EC4899", secondary: "#F472B6", text: "#3D1A2B", textSecondary: "#8A5C70", cardBackground: "#FFFFFF", cardBorder: "#FBD0E0", error: "#E11D48", success: "#10B981" },
+  "arctic-light": { background: "#F4F9FF", primary: "#0284C7", secondary: "#38BDF8", text: "#0F2A3D", textSecondary: "#4D6B80", cardBackground: "#FFFFFF", cardBorder: "#D6E8F5", error: "#E11D48", success: "#059669" },
+  "sage-light": { background: "#F6F8F2", primary: "#4D7C4F", secondary: "#84A98C", text: "#24331F", textSecondary: "#5C6B54", cardBackground: "#FFFFFF", cardBorder: "#DCE5D0", error: "#DC2626", success: "#4D7C4F" },
+  "mint-light": { background: "#F0FBF6", primary: "#10B981", secondary: "#34D399", text: "#0F3326", textSecondary: "#4D7A66", cardBackground: "#FFFFFF", cardBorder: "#C8EDDB", error: "#DC2626", success: "#10B981" },
+  "coral-light": { background: "#FFF6F2", primary: "#F97316", secondary: "#FB923C", text: "#3D2317", textSecondary: "#8A6553", cardBackground: "#FFFFFF", cardBorder: "#FBD9C8", error: "#E11D48", success: "#059669" },
+  "marigold-light": { background: "#FFFBF0", primary: "#D97706", secondary: "#F59E0B", text: "#3D2E0F", textSecondary: "#8A7444", cardBackground: "#FFFFFF", cardBorder: "#FBEBC0", error: "#DC2626", success: "#059669" },
+  "tangerine-light": { background: "#FFF7F0", primary: "#EA580C", secondary: "#FB923C", text: "#3D2410", textSecondary: "#8A6240", cardBackground: "#FFFFFF", cardBorder: "#FBDCC0", error: "#DC2626", success: "#059669" },
+  "blush-light": { background: "#FFF5F8", primary: "#DB2777", secondary: "#F472B6", text: "#3D1A29", textSecondary: "#8A5A6E", cardBackground: "#FFFFFF", cardBorder: "#FBD4E2", error: "#E11D48", success: "#10B981" },
+  "azure-light": { background: "#F2F8FF", primary: "#2563EB", secondary: "#60A5FA", text: "#11243D", textSecondary: "#4D6488", cardBackground: "#FFFFFF", cardBorder: "#D0E2FB", error: "#E11D48", success: "#059669" },
+  "sand-light": { background: "#FBF7F0", primary: "#B45309", secondary: "#D97706", text: "#332814", textSecondary: "#786A4D", cardBackground: "#FFFFFF", cardBorder: "#ECE0C8", error: "#DC2626", success: "#4D7C4F" },
+};

package/data/urls.mjs

@@ -0,0 +1,12 @@
+/** Official layout URLs for git-page-docs repository.
+ * The canonical home is the root `gitpagelayouts/` folder; the legacy
+ * `gitpagedocs/layouts/` folder stays online for older deployments. */
+
+export const OFFICIAL_LAYOUTS_CONFIG_URL =
+  "https://github.com/Vidigal-code/git-page-docs/blob/main/gitpagelayouts/layoutsConfig.json";
+
+export const OFFICIAL_LAYOUTS_TEMPLATES_URL =
+  "https://github.com/Vidigal-code/git-page-docs/blob/main/gitpagelayouts/templates";
+
+export const LEGACY_OFFICIAL_LAYOUTS_CONFIG_URL =
+  "https://github.com/Vidigal-code/git-page-docs/blob/main/gitpagedocs/layouts/layoutsConfig.json";

package/data/version-constants.mjs

@@ -0,0 +1,3 @@
+/** Document version identifiers for gitpagedocs */
+
+export { DOC_VERSIONS } from "../contracts/doc-versions.mjs";

package/domain/models/cli-options.ts

@@ -0,0 +1,33 @@
+export type CliMode = "home" | "full" | "config-only" | "ai";
+
+/**
+ * Values the user supplied explicitly on the command line. Interactive mode
+ * only asks for what is missing, so an explicit flag is never re-asked.
+ */
+export interface CliExplicitFlags {
+  useLocalLayoutConfig: boolean;
+  layoutsDir: boolean;
+  githubOwner: boolean;
+  githubRepo: boolean;
+  outputDir: boolean;
+}
+
+export interface CliOptions {
+  isBuild: boolean;
+  isServe: boolean;
+  mode: CliMode;
+  aiCommand?: string;
+  outputDir: string;
+  /** Standalone layouts home (repo-relative); local layouts are generated here. */
+  layoutsDir: string;
+  useLocalLayoutConfig: boolean;
+  shouldPush: boolean;
+  githubOwner: string;
+  githubRepo: string;
+  docsPath: string;
+  basePath: string;
+  repositorySearch?: boolean;
+  isInteractive: boolean;
+  hasArgs: boolean;
+  explicit: CliExplicitFlags;
+}

package/domain/services/layouts-migration.d.mts

@@ -0,0 +1,15 @@
+/** A planned move from the legacy layouts folder to the standalone home. */
+export interface LayoutsMigrationPlan {
+  required: boolean;
+  from: string;
+  to: string;
+  files: string[];
+  overwrites: string[];
+}
+
+export declare function planLayoutsMigration(options: {
+  outputDir: string;
+  layoutsDir: string;
+  legacyFiles?: string[];
+  targetFiles?: string[];
+}): LayoutsMigrationPlan;

package/domain/services/layouts-migration.mjs

@@ -0,0 +1,74 @@
+/**
+ * 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(compareCodeUnits);
+}
+
+/**
+ * Plain UTF-16 code-unit order (what `sort()` does by default), spelled out so
+ * a plan 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;
+}

package/domain/services/sanitize-segment.mjs

@@ -0,0 +1,7 @@
+/** Domain-level sanitization for owner/repo/path segments */
+
+export function sanitizeSegment(value) {
+  if (!value) return "";
+  const normalized = value.trim();
+  return /^[A-Za-z0-9._-]+$/.test(normalized) ? normalized : "";
+}

package/home/constants.mjs

@@ -0,0 +1,4 @@
+/** Constants for home distribution */
+
+export const STATIC_OUTPUT_DIR = "frontend/out";
+export const ARTIFACTS_DIR = "gitpagedocs";

package/home/home-file-writer.mjs

@@ -0,0 +1,19 @@
+/** Write .env, Dockerfile, README to home output directory */
+
+import path from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { getEnvTemplate, getDockerfileTemplate, getReadmeTemplate } from "./templates.mjs";
+
+/**
+ * @param {string} root
+ * @param {string} outputDir - e.g. gitpagedocshome or .
+ * @param {{ repositorySearch?: boolean; basePath?: string }} opts
+ */
+export async function writeHomeFiles(root, outputDir, opts = {}) {
+  const basePath = outputDir === "." || outputDir === "./" ? root : path.join(root, outputDir);
+  await mkdir(basePath, { recursive: true });
+
+  await writeFile(path.join(basePath, ".env"), getEnvTemplate(opts), "utf-8");
+  await writeFile(path.join(basePath, "Dockerfile"), getDockerfileTemplate(), "utf-8");
+  await writeFile(path.join(basePath, "README.md"), getReadmeTemplate(), "utf-8");
+}

package/home/templates.mjs

@@ -0,0 +1,51 @@
+/** Template content for home distribution files */
+
+export function getEnvTemplate({ repositorySearch = false, basePath = "" }) {
+  const pathLine = basePath
+    ? `GITPAGEDOCS_PATH=${basePath}`
+    : `# GITPAGEDOCS_PATH=gi-page-docs`;
+  return `# GitPageDocs - Local development
+# Set to "true" to enable the search aggregator home.
+GITPAGEDOCS_REPOSITORY_SEARCH=${String(repositorySearch)}
+
+# Base path (when GITPAGEDOCS_REPOSITORY_SEARCH=false).
+# Example: localhost:3000/gi-page-docs
+${pathLine}
+`;
+}
+
+export function getDockerfileTemplate() {
+  return `FROM nginx:alpine
+COPY . /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`;
+}
+
+/**
+ * README shipped next to the static export. Every command runs from the
+ * folder the file lives in, so it never needs to know the output dir name.
+ */
+export function getReadmeTemplate() {
+  return `# GitPageDocs Home
+
+Pre-built GitPageDocs static site by Vidigal-code.
+
+## Quick start
+
+\`\`\`bash
+npx serve .
+\`\`\`
+
+## Docker
+
+\`\`\`bash
+docker build -t gitpagedocshome .
+docker run -p 3000:80 gitpagedocshome
+\`\`\`
+
+## Credits
+
+Powered by Vidigal-code - https://github.com/Vidigal-code/git-page-docs
+`;
+}