@gitpagedocs/cli 1.1.68 → 1.1.70

package/presentation/commands/diagnostics.ts

@@ -1,8 +1,15 @@
 import path from "node:path";
 import { readFileSync, existsSync } from "node:fs";
-import { execSync } from "node:child_process";
 import { defaultConfigLoader } from "@gitpagedocs/tools";
 import type { CommandContext } from "./run-command";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { runExecutableCapture } from "../../runtime/exec.mjs";
+
+interface DoctorCheck {
+  label: string;
+  ok: boolean;
+  detail: string;
+}
 
 function readVersion(pkgRoot: string): string {
   try {
@@ -18,9 +25,10 @@ export async function runVersion(ctx: CommandContext): Promise<void> {
   console.log(`gitpagedocs ${readVersion(ctx.pkgRoot)} (node ${process.version})`);
 }
 
-function probe(label: string, command: string): { label: string; ok: boolean; detail: string } {
+/** Run `<program> --version` (argv array, no shell) and keep its first output line. */
+function probe(label: string, program: string): DoctorCheck {
   try {
-    const out = execSync(command, { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    const out = String(runExecutableCapture(program, ["--version"], { stdio: ["ignore", "pipe", "ignore"] }));
     return { label, ok: true, detail: out.split("\n")[0] };
   } catch {
     return { label, ok: false, detail: "not found" };
@@ -28,23 +36,24 @@ function probe(label: string, command: string): { label: string; ok: boolean; de
 }
 
 export async function runDoctor(ctx: CommandContext): Promise<void> {
-  const checks: Array<{ label: string; ok: boolean; detail: string }> = [];
-  checks.push({ label: "node", ok: true, detail: process.version });
-  checks.push(probe("git", "git --version"));
-  checks.push(probe("gh (GitHub CLI)", "gh --version"));
-  checks.push(probe("pnpm", "pnpm --version"));
-
   const configPath = await defaultConfigLoader.resolveConfigPath(ctx.cwd);
-  checks.push({
-    label: "gitpagedocs config",
-    ok: Boolean(configPath),
-    detail: configPath ? path.relative(ctx.cwd, configPath) : "not found (run `gitpagedocs init`)",
-  });
-  checks.push({
-    label: "gitpagedocs/ directory",
-    ok: existsSync(path.join(ctx.cwd, "gitpagedocs")),
-    detail: existsSync(path.join(ctx.cwd, "gitpagedocs")) ? "present" : "missing",
-  });
+  const hasDocsDirectory = existsSync(path.join(ctx.cwd, "gitpagedocs"));
+  const checks: DoctorCheck[] = [
+    { label: "node", ok: true, detail: process.version },
+    probe("git", "git"),
+    probe("gh (GitHub CLI)", "gh"),
+    probe("pnpm", "pnpm"),
+    {
+      label: "gitpagedocs config",
+      ok: Boolean(configPath),
+      detail: configPath ? path.relative(ctx.cwd, configPath) : "not found (run `gitpagedocs init`)",
+    },
+    {
+      label: "gitpagedocs/ directory",
+      ok: hasDocsDirectory,
+      detail: hasDocsDirectory ? "present" : "missing",
+    },
+  ];
 
   // eslint-disable-next-line no-console
   console.log("\n  gitpagedocs doctor\n");
@@ -53,8 +62,9 @@ export async function runDoctor(ctx: CommandContext): Promise<void> {
     console.log(`  ${c.ok ? "[ok]" : "[x] "} ${c.label.padEnd(22)} ${c.detail}`);
   }
   const failed = checks.filter((c) => !c.ok && c.label !== "gh (GitHub CLI)").length;
+  const summary = failed === 0 ? "All required checks passed." : `${failed} check(s) need attention.`;
   // eslint-disable-next-line no-console
-  console.log(`\n  ${failed === 0 ? "All required checks passed." : `${failed} check(s) need attention.`}\n`);
+  console.log(`\n  ${summary}\n`);
 }
 
 /** Used only when package.json is unreadable — the CLI's published name. */

package/presentation/commands/docs.ts

@@ -9,6 +9,12 @@ import {
 } from "@gitpagedocs/tools";
 import type { CommandContext } from "./run-command";
 
+/** Human-readable outcome of one managed-region update. */
+function describeUpdate(result: { changed: boolean; replaced: boolean }): string {
+  if (!result.changed) return "already up to date";
+  return result.replaced ? "managed region updated" : "managed region added";
+}
+
 /**
  * `gitpagedocs docs` — refresh the managed regions of the standard docs files
  * with deterministic content. Idempotent and marker-bounded: manual content
@@ -28,9 +34,8 @@ export async function runDocs(ctx: CommandContext): Promise<void> {
   // eslint-disable-next-line no-console
   console.log("");
   for (const r of results) {
-    const state = r.changed ? (r.replaced ? "managed region updated" : "managed region added") : "already up to date";
     // eslint-disable-next-line no-console
-    console.log(`  ${r.path}: ${state}.`);
+    console.log(`  ${r.path}: ${describeUpdate(r)}.`);
   }
   // eslint-disable-next-line no-console
   console.log("");

package/presentation/commands/pages.ts

@@ -5,6 +5,7 @@ import { askConfirm } from "../ui/clack";
 import { askOwnerRepo, interactivePromptsAvailable } from "../ui/prompts";
 // @ts-expect-error .mjs runtime module
 import { detectRepoFromGit, getCurrentGitBranch, tryConfigurePagesToGitHubActions } from "../../runtime/git-ops.mjs";
+import { trimSlashes } from "../../contracts/path-segments.mjs";
 
 /** Read `--name value` (or `--name=value`) from a raw arg list. */
 function readFlag(args: string[], name: string): string {
@@ -73,8 +74,9 @@ export async function runPagesDeploy(ctx: CommandContext): Promise<void> {
     repo = answered.repo;
   }
 
+  const pathSuffix = docsPath ? ` (path: ${docsPath})` : "";
   // eslint-disable-next-line no-console
-  console.log(`\n  Deploy ${owner}/${repo} to GitHub Pages via Actions${docsPath ? ` (path: ${docsPath})` : ""}.`);
+  console.log(`\n  Deploy ${owner}/${repo} to GitHub Pages via Actions${pathSuffix}.`);
   const ok = await askConfirm(
     `Generate docs + workflow, commit, push, and switch Pages to Actions for ${owner}/${repo}?`,
     false,
@@ -91,7 +93,7 @@ export async function runPagesDeploy(ctx: CommandContext): Promise<void> {
   const result = spawnSync(process.execPath, [bin, ...pushArgs], { stdio: "inherit", cwd: ctx.cwd, env: process.env });
 
   if (result.status === 0) {
-    const seg = docsPath ? `/${docsPath.replace(/^\/+|\/+$/g, "")}` : "";
+    const seg = docsPath ? `/${trimSlashes(docsPath)}` : "";
     // eslint-disable-next-line no-console
     console.log(`\n  Deployed. Final URL: https://${owner}.github.io/${repo}${seg}/\n`);
   } else {

package/presentation/options/parser.ts

@@ -1,4 +1,4 @@
-import type { CliOptions } from "../../domain/models/cli-options";
+import type { CliMode, CliOptions } from "../../domain/models/cli-options";
 import { DEFAULTS } from "./schema";
 import { normalizeLayoutsDir } from "../../contracts/layouts-paths.mjs";
 
@@ -22,6 +22,9 @@ const KNOWN_FLAGS = new Set([
   "--pages-actions",
 ]);
 
+/** Options that carry a value; `--name=value` spellings must never be read as an owner/repo. */
+const VALUE_OPTION_PREFIXES = ["--owner", "--repo", "--path", "--home", "--output", "--layouts-dir", "--search"];
+
 function readOptionValue(args: string[], optionName: string): string {
   const equalsArg = args.find((a) => a.startsWith(`${optionName}=`));
   if (equalsArg) return equalsArg.slice(optionName.length + 1).trim();
@@ -33,36 +36,50 @@ function readOptionValue(args: string[], optionName: string): string {
   return "";
 }
 
+/** Legacy `--<owner> --<repo>` spelling: every dashed arg that is not a known flag or option. */
+function readFallbackOwnerRepo(args: string[]): string[] {
+  return args
+    .filter((a) => a.startsWith("--") && !KNOWN_FLAGS.has(a))
+    .filter((a) => !VALUE_OPTION_PREFIXES.some((prefix) => a.startsWith(prefix)))
+    .map((a) => a.slice(2).trim())
+    .filter(Boolean);
+}
+
+/** New verb aliases (Phase 6) that map onto existing modes without new modes. */
+function readCommandAliases(args: string[]): { isDocument: boolean; isDeploy: boolean; aiCommand?: string } {
+  const command = args[0];
+  if (command === "ai") return { isDocument: false, isDeploy: false, aiCommand: args[1] };
+  if (command === "document") return { isDocument: true, isDeploy: false, aiCommand: args[1] ?? "repo" };
+  if (command?.startsWith("document:")) return { isDocument: true, isDeploy: false, aiCommand: command.split(":")[1] };
+  return { isDocument: false, isDeploy: command === "deploy" || command === "pages", aiCommand: undefined };
+}
+
+function resolveMode(flags: { isAi: boolean; isHome: boolean; isFull: boolean }): CliMode {
+  if (flags.isAi) return "ai";
+  if (flags.isHome) return "home";
+  if (flags.isFull) return "full";
+  return "config-only";
+}
+
+function resolveRepositorySearch(searchRaw: string, isHome: boolean): boolean | undefined {
+  if (searchRaw === "true") return true;
+  if (searchRaw === "false") return false;
+  return isHome ? DEFAULTS.home.repositorySearch : undefined;
+}
+
 export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOptions {
   const args = argv.slice(2);
 
-  let githubOwner = readOptionValue(args, "--owner");
-  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
-    .filter((a) => a.startsWith("--"))
-    .filter((a) => !KNOWN_FLAGS.has(a))
-    .filter((a) => !a.startsWith("--owner"))
-    .filter((a) => !a.startsWith("--repo"))
-    .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);
+  const fallbackDashedArgs = readFallbackOwnerRepo(args);
+  const githubOwner = readOptionValue(args, "--owner") || fallbackDashedArgs[0] || "";
+  const githubRepo = readOptionValue(args, "--repo") || fallbackDashedArgs[1] || "";
 
-  if (!githubOwner && fallbackDashedArgs[0]) githubOwner = fallbackDashedArgs[0];
-  if (!githubRepo && fallbackDashedArgs[1]) githubRepo = fallbackDashedArgs[1];
-
-  // New verb aliases (Phase 6) that map onto existing modes without new modes.
-  const command = args[0];
-  const isDocument = command === "document" || (command?.startsWith("document:") ?? false);
-  const isDeploy = command === "deploy" || command === "pages";
+  const { isDocument, isDeploy, aiCommand } = readCommandAliases(args);
 
   const isBuild = args.includes("--build") || env.GITPAGEDOCS_BUILD === "1";
   const isServe = args.includes("--serve");
@@ -70,41 +87,25 @@ export function parseCliOptions(argv: string[], env: NodeJS.ProcessEnv): CliOpti
   const shouldPush = args.includes("--push") || isDeploy;
   const isHome = args.includes("--home");
   const isInteractive = args.includes("--interactive") || args.includes("-i");
-  const isAi = command === "ai" || args.includes("--ai") || isDocument;
-  const aiCommand =
-    command === "ai"
-      ? args[1]
-      : command === "document"
-        ? args[1] ?? "repo"
-        : command?.startsWith("document:")
-          ? command.split(":")[1]
-          : undefined;
-
-  const mode: import("../../domain/models/cli-options").CliMode = isAi ? "ai" : isHome ? "home" : args.includes("--full") ? "full" : "config-only";
-  const repositorySearch =
-    searchRaw === "true"
-      ? true
-      : searchRaw === "false"
-        ? false
-        : isHome
-          ? DEFAULTS.home.repositorySearch
-          : undefined;
+  const isAi = args[0] === "ai" || args.includes("--ai") || isDocument;
 
-  const normalizedPath = docsPath.trim();
+  const mode = resolveMode({ isAi, isHome, isFull: args.includes("--full") });
+  const repositorySearch = resolveRepositorySearch(searchRaw, isHome);
+  const defaultOutputDir = isHome ? DEFAULTS.home.outputDir : DEFAULTS.outputDir;
 
   return {
     isBuild,
     isServe,
     mode,
     aiCommand,
-    outputDir: outputDir || (isHome ? DEFAULTS.home.outputDir : DEFAULTS.outputDir),
+    outputDir: outputDir || defaultOutputDir,
     layoutsDir: normalizeLayoutsDir(layoutsDir || DEFAULTS.layoutsDir),
     useLocalLayoutConfig,
     shouldPush,
     githubOwner,
     githubRepo,
-    docsPath: normalizedPath,
-    basePath: normalizedPath,
+    docsPath,
+    basePath: docsPath,
     repositorySearch,
     isInteractive,
     hasArgs: args.length > 0,

package/presentation/ui/prompts.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { execSync } from "node:child_process";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { runExecutable } from "../../runtime/exec.mjs";
 import type { CliOptions } from "../../domain/models/cli-options";
 import { DEFAULTS } from "../options/schema";
 import { askText, askConfirm, note } from "./clack";
@@ -23,7 +24,7 @@ export async function promptHomeOptions(parsed: CliOptions): Promise<CliOptions>
   const outputDir = await askText({
     message: "Output directory:",
     defaultValue: parsed.outputDir ?? DEFAULTS.home.outputDir,
-    validate: (v) => (v && v.trim() ? undefined : "Required"),
+    validate: (v) => (v?.trim() ? undefined : "Required"),
   });
   const repositorySearch = await askConfirm(
     "Enable repository search home?",
@@ -54,12 +55,12 @@ export async function askOwnerRepo(
   const owner = await askText({
     message: "GitHub owner (user or organization):",
     defaultValue: defaults?.owner || detected?.owner || "",
-    validate: (v) => (v && v.trim() ? undefined : "Owner is required."),
+    validate: (v) => (v?.trim() ? undefined : "Owner is required."),
   });
   const repo = await askText({
     message: "GitHub repository name:",
     defaultValue: defaults?.repo || detected?.repo || "",
-    validate: (v) => (v && v.trim() ? undefined : "Repository is required."),
+    validate: (v) => (v?.trim() ? undefined : "Repository is required."),
   });
   return { owner: owner.trim(), repo: repo.trim() };
 }
@@ -101,7 +102,7 @@ export async function ensureGitRepoInteractive(root: string): Promise<void> {
     return;
   }
   try {
-    execSync("git init", { cwd: root, stdio: "ignore" });
+    runExecutable("git", ["init"], { cwd: root, stdio: "ignore" });
     note("Initialized an empty git repository.", "git");
   } catch {
     note("Could not run `git init`. Initialize git manually, then retry.", "git");

package/runtime/doc-path-resolver.mjs

@@ -41,16 +41,18 @@ export function withVersionBadge(content, versionId, language) {
     return normalized;
   }
 
-  const label =
-    language === "pt"
-      ? `> Versao: ${versionId}`
-      : language === "es"
-        ? `> Version (ES): ${versionId}`
-        : `> Version: ${versionId}`;
+  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

@@ -1,22 +1,22 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { runExecutable, runExecutableCapture } from "./exec.mjs";
 
 /** Detect { owner, repo } from the git `origin` remote URL, or null. */
 export function detectRepoFromGit(root) {
   try {
-    const url = execSync("git remote get-url origin", { cwd: root, stdio: "pipe" }).toString().trim();
+    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
+    // no remote / not a repo / git not installed
   }
   return null;
 }
 
 export function tryConfigurePagesToGitHubActions(owner, repo, branch, root) {
   try {
-    execSync("gh --version", { cwd: root, stdio: "ignore" });
+    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.",
@@ -24,16 +24,19 @@ export function tryConfigurePagesToGitHubActions(owner, repo, branch, root) {
     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 = [
-    `gh api -X PUT "repos/${owner}/${repo}/pages" -f build_type=workflow`,
-    `gh api -X POST "repos/${owner}/${repo}/pages" -f build_type=workflow`,
-    `gh api -X POST "repos/${owner}/${repo}/pages" -f source[branch]=${branch} -f source[path]=/`,
-    `gh api -X PUT "repos/${owner}/${repo}/pages" -f source[branch]=${branch} -f source[path]=/ -f build_type=workflow`,
+    ["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 command of candidates) {
+  for (const args of candidates) {
     try {
-      execSync(command, { cwd: root, stdio: "ignore" });
+      runExecutable("gh", args, { cwd: root, stdio: "ignore" });
       console.log("GitHub Pages source configured for GitHub Actions.");
       return;
     } catch {
@@ -48,7 +51,7 @@ export function tryConfigurePagesToGitHubActions(owner, repo, branch, root) {
 
 export function getCurrentGitBranch(root) {
   try {
-    const branch = execSync("git branch --show-current", { cwd: root, stdio: "pipe" }).toString().trim();
+    const branch = runExecutableCapture("git", ["branch", "--show-current"], { cwd: root });
     return branch || "main";
   } catch {
     return "main";
@@ -67,17 +70,16 @@ export function runGitPushForGeneratedArtifacts(options, root, sanitizeSegment)
 
   const repoUrl = `https://github.com/${owner}/${repo}.git`;
   try {
-    execSync("git remote get-url origin", { cwd: root, stdio: "ignore" });
+    runExecutable("git", ["remote", "get-url", "origin"], { cwd: root, stdio: "ignore" });
   } catch {
-    execSync(`git remote add origin "${repoUrl}"`, { cwd: root, stdio: "inherit" });
+    runExecutable("git", ["remote", "add", "origin", repoUrl], { cwd: root, stdio: "inherit" });
   }
 
-  execSync('git add "gitpagedocs" ".github/workflows/gitpagedocs-pages.yml"', { cwd: root, stdio: "inherit" });
+  runExecutable("git", ["add", "gitpagedocs", ".github/workflows/gitpagedocs-pages.yml"], { cwd: root, stdio: "inherit" });
 
   let hasStagedChanges = false;
   try {
-    execSync("git diff --cached --quiet", { cwd: root, stdio: "ignore" });
-    hasStagedChanges = false;
+    runExecutable("git", ["diff", "--cached", "--quiet"], { cwd: root, stdio: "ignore" });
   } catch {
     hasStagedChanges = true;
   }
@@ -86,11 +88,11 @@ export function runGitPushForGeneratedArtifacts(options, root, sanitizeSegment)
     return;
   }
 
-  execSync('git commit -m "chore: setup gitpagedocs pages workflow"', { cwd: root, stdio: "inherit" });
+  runExecutable("git", ["commit", "-m", "chore: setup gitpagedocs pages workflow"], { cwd: root, stdio: "inherit" });
 
   const currentBranch = getCurrentGitBranch(root);
   try {
-    execSync(`git push -u origin ${currentBranch}`, { cwd: root, stdio: "inherit" });
+    runExecutable("git", ["push", "-u", "origin", currentBranch], { cwd: root, stdio: "inherit" });
     tryConfigurePagesToGitHubActions(owner, repo, currentBranch, root);
     return;
   } catch {
@@ -98,8 +100,8 @@ export function runGitPushForGeneratedArtifacts(options, root, sanitizeSegment)
   }
 
   try {
-    execSync(`git pull --rebase origin ${currentBranch}`, { cwd: root, stdio: "inherit" });
-    execSync(`git push -u origin ${currentBranch}`, { cwd: root, stdio: "inherit" });
+    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.`,

package/runtime/layouts-migrator.mjs

@@ -48,7 +48,21 @@ export function listFilesRecursively(absoluteDir) {
   };
 
   walk(absoluteDir, "");
-  return found.sort();
+  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;
 }
 
 /**