@gitpagedocs/cli 1.1.67 → 1.1.69

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;
 }
 
 /**

package/runtime/output.mjs

@@ -9,6 +9,8 @@ import {
   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">
@@ -29,7 +31,7 @@ function listExistingVersionIds(root, outputDir) {
 function removeLegacySourceViewerFiles(root, outputDir) {
   const versionIds = listExistingVersionIds(root, outputDir);
   for (const versionId of versionIds) {
-    for (const language of ["pt", "en", "es"]) {
+    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)) {
@@ -75,10 +77,101 @@ async function writeLayoutArtifacts(options) {
   }
 }
 
+/**
+ * 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,
-    pkgRoot,
     outputDir,
     artifacts,
     useLocalLayoutConfig,
@@ -87,15 +180,10 @@ export async function writeConfigOnlyOutput(options) {
     createThemeTemplate,
   } = options;
 
-  // Keep only versioned docs output in docs/, removing legacy root language folders.
-  for (const legacyLanguageDir of ["en", "pt", "es"]) {
-    const legacyPath = path.join(root, outputDir, "docs", legacyLanguageDir);
-    if (existsSync(legacyPath)) {
-      rmSync(legacyPath, { recursive: true, force: true });
-    }
-  }
+  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,
@@ -105,55 +193,9 @@ export async function writeConfigOnlyOutput(options) {
     artifacts,
     createThemeTemplate,
   });
-
-  for (const [versionId, versionConfig] of Object.entries(artifacts.versionConfigs)) {
-    await writeJson(root, `${outputDir}/docs/versions/${versionId}/config.json`, versionConfig);
-  }
+  await writeVersionConfigs(root, outputDir, artifacts.versionConfigs);
 
   removeLegacySourceViewerFiles(root, outputDir);
 
-  for (const [versionId, versionConfig] of Object.entries(artifacts.versionConfigs)) {
-    const versionRoutesMd = versionConfig["routes-md"] ?? versionConfig.routes ?? [];
-    for (const route of versionRoutesMd) {
-      for (const docPath of Object.values(route.path ?? {})) {
-        const fileName = path.basename(docPath);
-        const key = parseDocFileToKey(fileName);
-        const language = extractLanguageFromPath(docPath);
-        const content = key && language ? artifacts.docs?.[language]?.[key] : undefined;
-        if (!content) continue;
-        const versionedContent = withVersionBadge(content, versionId, language);
-        await writeText(root, normalizeToOutputPath(outputDir, docPath), versionedContent);
-      }
-    }
-
-    const versionRoutesHtml = versionConfig["routes-html"] ?? [];
-    const docsHtml = artifacts.docsHtml ?? {};
-    for (const route of versionRoutesHtml) {
-      if (route.url) continue;
-      for (const docPath of Object.values(route.path ?? {})) {
-        const fileName = path.basename(docPath);
-        const key = parseHtmlFileToKey(fileName);
-        const language = extractLanguageFromPath(docPath);
-        const content = key && language ? docsHtml[key]?.[language] : undefined;
-        if (!content) continue;
-        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);
-        }
-      }
-    }
-
-    // Ensure version folders always include an index file.
-    for (const language of ["pt", "en", "es"]) {
-      const fallbackIndex = artifacts.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);
-      }
-    }
-  }
+  await writeVersionedDocs(root, outputDir, artifacts);
 }

package/runtime/workflow.mjs

@@ -1,6 +1,8 @@
+import { trimSlashes } from "../contracts/path-segments.mjs";
+
 function sanitizeDocsPath(docsPath) {
   if (!docsPath || typeof docsPath !== "string") return "";
-  const segment = docsPath.replace(/^\/+|\/+$/g, "").trim();
+  const segment = trimSlashes(docsPath).trim();
   return /^[A-Za-z0-9._-]+$/.test(segment) ? segment : "";
 }
 

package/start.mjs

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
-import { spawn } from "child_process";
+import { spawnExecutable } from "./runtime/exec.mjs";
 
 const env = { ...process.env, GITPAGEDOCS_REPOSITORY_SEARCH: "true" };
 // The Next app lives in frontend/, so `next build` emits to frontend/.next —
 // point `next start` at the same directory (matches `next build frontend`).
-const child = spawn("npx", ["next", "start", "frontend"], {
-  stdio: "inherit",
-  env,
-  shell: true,
-});
+let child;
+try {
+  child = spawnExecutable("npx", ["next", "start", "frontend"], { stdio: "inherit", env });
+} catch (error) {
+  console.error(`[gitpagedocs] ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
 child.on("exit", (code) => process.exit(code ?? 0));