@gitpagedocs/cli 1.1.53 → 1.1.55

package/README.md

@@ -38,36 +38,36 @@ The AI-CLI implementation lives in `cli/ai/` (relocated from the frontend so the
 
 ```
 cli/
-├── index.mjs                          # Node entry (bootstraps TS presentation via tsx)
-├── package.json                       # the published `gitpagedocs` package
-├── ai/                                # AI documentation CLI (provider/model/paths → markdown)
-├── contracts/                         # Stable contracts for external tooling
-│   └── doc-versions.mjs
-│
-├── presentation/                      # Interface/composition root
-│   ├── index.ts
-│   ├── options/
-│   └── ui/
-│
-├── application/                       # Use-cases and ports
-│   ├── config-only/handler.mjs
-│   ├── home/handler.mjs
-│   ├── report/config-only-reporter.mjs
-│   ├── use-cases/dispatch-mode.ts
-│   └── ports/cli-runtime-ports.ts
-│
-├── domain/                            # Business rules
-│   └── services/sanitize-segment.mjs
-│
-├── infrastructure/                    # Side effects and adapters
-│   ├── config-only/runtime.mjs
-│   └── home/runtime.mjs
-│
-├── builders/                          # Pure config builders
-├── data/                              # Constants and metadata
-├── content/                           # Static docs content
-├── runtime/                           # Low-level runtime helpers
-└── home/                              # Home templates/files
+|-- index.mjs                          # Node entry (bootstraps TS presentation via tsx)
+|-- package.json                       # the published `gitpagedocs` package
+|-- ai/                                # AI documentation CLI (provider/model/paths → markdown)
+|-- contracts/                         # Stable contracts for external tooling
+|   `-- doc-versions.mjs
+|
+|-- presentation/                      # Interface/composition root
+|   |-- index.ts
+|   |-- options/
+|   `-- ui/
+|
+|-- application/                       # Use-cases and ports
+|   |-- config-only/handler.mjs
+|   |-- home/handler.mjs
+|   |-- report/config-only-reporter.mjs
+|   |-- use-cases/dispatch-mode.ts
+|   `-- ports/cli-runtime-ports.ts
+|
+|-- domain/                            # Business rules
+|   `-- services/sanitize-segment.mjs
+|
+|-- infrastructure/                    # Side effects and adapters
+|   |-- config-only/runtime.mjs
+|   `-- home/runtime.mjs
+|
+|-- builders/                          # Pure config builders
+|-- data/                              # Constants and metadata
+|-- content/                           # Static docs content
+|-- runtime/                           # Low-level runtime helpers
+`-- home/                              # Home templates/files
 ```
 
 ## SOLID Principles

package/ai/application/docs-pattern.ts

@@ -1,68 +1,68 @@
-/**
- * Parse an AI documentation response into gitpagedocs pages.
- *
- * The model is instructed (see GITPAGEDOCS_DOC_SYSTEM_PROMPT) to delimit each
- * page with a line `=== PAGE: <slug> | <Title> ===`. This splits that response
- * into individual pages. If the model ignored the format, the whole response is
- * returned as a single "ai-overview" page so content is never lost.
- */
-
-export interface AiDocPage {
-  /** lowercase-kebab, English, identical across languages (used as the filename) */
-  slug: string;
-  title: string;
-  body: string;
-}
-
-const PAGE_DELIMITER = /^===\s*PAGE:\s*(.+?)\s*\|\s*(.*?)\s*===\s*$/;
-
-/** Turn an arbitrary heading into a safe lowercase-kebab slug. */
-export function slugify(raw: string): string {
-  const slug = (raw ?? "")
-    .toLowerCase()
-    .normalize("NFKD")
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 60);
-  return slug || "page";
-}
-
-export function parseAiPages(markdown: string): AiDocPage[] {
-  const text = (markdown ?? "").replace(/\r\n/g, "\n").trim();
-  if (!text) return [];
-
-  const pages: AiDocPage[] = [];
-  let current: { slug: string; title: string; body: string[] } | null = null;
-
-  const flush = () => {
-    if (current) {
-      pages.push({ slug: current.slug, title: current.title, body: current.body.join("\n").trim() });
-    }
-  };
-
-  for (const line of text.split("\n")) {
-    const match = line.match(PAGE_DELIMITER);
-    if (match) {
-      flush();
-      const rawSlug = match[1].trim();
-      const title = match[2].trim() || rawSlug;
-      current = { slug: slugify(rawSlug), title, body: [] };
-    } else if (current) {
-      current.body.push(line);
-    }
-  }
-  flush();
-
-  const withBody = pages.filter((page) => page.body.length > 0);
-  if (withBody.length === 0) {
-    return [{ slug: "ai-overview", title: "Overview", body: text }];
-  }
-
-  // De-duplicate slugs within a single response (suffix later collisions).
-  const seen = new Map<string, number>();
-  return withBody.map((page) => {
-    const count = seen.get(page.slug) ?? 0;
-    seen.set(page.slug, count + 1);
-    return count === 0 ? page : { ...page, slug: `${page.slug}-${count + 1}` };
-  });
-}
+/**
+ * Parse an AI documentation response into gitpagedocs pages.
+ *
+ * The model is instructed (see GITPAGEDOCS_DOC_SYSTEM_PROMPT) to delimit each
+ * page with a line `=== PAGE: <slug> | <Title> ===`. This splits that response
+ * into individual pages. If the model ignored the format, the whole response is
+ * returned as a single "ai-overview" page so content is never lost.
+ */
+
+export interface AiDocPage {
+  /** lowercase-kebab, English, identical across languages (used as the filename) */
+  slug: string;
+  title: string;
+  body: string;
+}
+
+const PAGE_DELIMITER = /^===\s*PAGE:\s*(.+?)\s*\|\s*(.*?)\s*===\s*$/;
+
+/** Turn an arbitrary heading into a safe lowercase-kebab slug. */
+export function slugify(raw: string): string {
+  const slug = (raw ?? "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return slug || "page";
+}
+
+export function parseAiPages(markdown: string): AiDocPage[] {
+  const text = (markdown ?? "").replace(/\r\n/g, "\n").trim();
+  if (!text) return [];
+
+  const pages: AiDocPage[] = [];
+  let current: { slug: string; title: string; body: string[] } | null = null;
+
+  const flush = () => {
+    if (current) {
+      pages.push({ slug: current.slug, title: current.title, body: current.body.join("\n").trim() });
+    }
+  };
+
+  for (const line of text.split("\n")) {
+    const match = line.match(PAGE_DELIMITER);
+    if (match) {
+      flush();
+      const rawSlug = match[1].trim();
+      const title = match[2].trim() || rawSlug;
+      current = { slug: slugify(rawSlug), title, body: [] };
+    } else if (current) {
+      current.body.push(line);
+    }
+  }
+  flush();
+
+  const withBody = pages.filter((page) => page.body.length > 0);
+  if (withBody.length === 0) {
+    return [{ slug: "ai-overview", title: "Overview", body: text }];
+  }
+
+  // De-duplicate slugs within a single response (suffix later collisions).
+  const seen = new Map<string, number>();
+  return withBody.map((page) => {
+    const count = seen.get(page.slug) ?? 0;
+    seen.set(page.slug, count + 1);
+    return count === 0 ? page : { ...page, slug: `${page.slug}-${count + 1}` };
+  });
+}

package/ai/infrastructure/version-docs-writer.ts

@@ -1,143 +1,143 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-// @ts-expect-error .mjs runtime module is type-less in this package.
-import { buildMdRoute } from "../../builders/route-builders.mjs";
-import type { AiDocPage } from "../application/docs-pattern";
-
-const CANONICAL_LANGS = ["pt", "en", "es"] as const;
-type Lang = (typeof CANONICAL_LANGS)[number];
-
-/** AI routes/menus use a high, dedicated id range so they never clash with the
- * deterministic base routes (ids 1..N) and can be identified for idempotency. */
-const AI_ROUTE_ID_BASE = 1000;
-
-export interface VersionDocsWriteInput {
-  cwd: string;
-  versionId: string;
-  /** Pages generated per language (only the languages the user selected). */
-  pagesByLang: Partial<Record<Lang, AiDocPage[]>>;
-}
-
-export interface VersionDocsWriteResult {
-  configPath: string;
-  slugs: string[];
-  files: string[];
-}
-
-interface LangContent {
-  title: string;
-  body: string;
-}
-
-function indexBySlug(pages: AiDocPage[] | undefined): Map<string, AiDocPage> {
-  const map = new Map<string, AiDocPage>();
-  for (const page of pages ?? []) {
-    if (!map.has(page.slug)) map.set(page.slug, page);
-  }
-  return map;
-}
-
-/**
- * Write AI-generated pages into the gitpagedocs versioned structure and wire
- * them into the version config.json (routes-md + menus-header-md). Pages are
- * written for ALL three canonical languages (missing languages reuse an
- * available translation) so every route path stays valid. Idempotent: any prior
- * `aiGenerated` routes/menus are replaced, never duplicated. The base config and
- * its deterministic routes are preserved untouched.
- */
-export async function writeVersionDocs(input: VersionDocsWriteInput): Promise<VersionDocsWriteResult> {
-  const { cwd, versionId, pagesByLang } = input;
-  const base = `gitpagedocs/docs/versions/${versionId}`;
-
-  const perLang: Record<Lang, Map<string, AiDocPage>> = {
-    pt: indexBySlug(pagesByLang.pt),
-    en: indexBySlug(pagesByLang.en),
-    es: indexBySlug(pagesByLang.es),
-  };
-
-  // Ordered unique slug list (prefer en order, then pt, then es).
-  const order: string[] = [];
-  const seen = new Set<string>();
-  for (const lang of ["en", "pt", "es"] as Lang[]) {
-    for (const page of pagesByLang[lang] ?? []) {
-      if (!seen.has(page.slug)) {
-        seen.add(page.slug);
-        order.push(page.slug);
-      }
-    }
-  }
-  if (order.length === 0) {
-    throw new Error("No AI pages to write.");
-  }
-
-  const resolve = (slug: string): Record<Lang, LangContent> => {
-    const fallback = CANONICAL_LANGS.map((lang) => perLang[lang].get(slug)).find(Boolean);
-    const out = {} as Record<Lang, LangContent>;
-    for (const lang of CANONICAL_LANGS) {
-      const page = perLang[lang].get(slug) ?? fallback!;
-      out[lang] = { title: page.title, body: page.body };
-    }
-    return out;
-  };
-
-  // 1) Write the markdown files (all 3 canonical languages).
-  const writtenFiles: string[] = [];
-  for (const slug of order) {
-    const content = resolve(slug);
-    for (const lang of CANONICAL_LANGS) {
-      const rel = `${base}/${lang}/${slug}.md`;
-      const abs = path.resolve(cwd, rel);
-      await fs.mkdir(path.dirname(abs), { recursive: true });
-      await fs.writeFile(abs, `${content[lang].body}\n`, "utf-8");
-      writtenFiles.push(rel);
-    }
-  }
-
-  // 2) Patch the version config.json (raw JSON round-trip, preserve all keys).
-  const configRel = `${base}/config.json`;
-  const configAbs = path.resolve(cwd, configRel);
-  let raw: string;
-  try {
-    raw = await fs.readFile(configAbs, "utf-8");
-  } catch {
-    throw new Error(
-      `Version config not found at ${configRel}. Run the base scaffold (\`gitpagedocs\`) first.`,
-    );
-  }
-  const config = JSON.parse(raw) as Record<string, unknown>;
-
-  const routesMd = Array.isArray(config["routes-md"]) ? (config["routes-md"] as Array<Record<string, unknown>>) : [];
-  const menusMd = Array.isArray(config["menus-header-md"]) ? (config["menus-header-md"] as Array<Record<string, unknown>>) : [];
-  const keptRoutes = routesMd.filter((route) => route?.aiGenerated !== true);
-  const keptMenus = menusMd.filter((menu) => menu?.aiGenerated !== true);
-
-  const newRoutes: Array<Record<string, unknown>> = [];
-  const newMenus: Array<Record<string, unknown>> = [];
-  order.forEach((slug, index) => {
-    const content = resolve(slug);
-    const id = AI_ROUTE_ID_BASE + index + 1;
-    const pathByLang = {
-      pt: `${base}/pt/${slug}.md`,
-      en: `${base}/en/${slug}.md`,
-      es: `${base}/es/${slug}.md`,
-    };
-    const titles = { pt: content.pt.title, en: content.en.title, es: content.es.title };
-    const descriptions = { pt: "", en: "", es: "" };
-    const route = buildMdRoute(versionId, id, pathByLang, titles, descriptions, {}) as Record<string, unknown>;
-    route.aiGenerated = true;
-    newRoutes.push(route);
-    newMenus.push({
-      id,
-      aiGenerated: true,
-      pt: { title: content.pt.title, "path-click": pathByLang.pt },
-      en: { title: content.en.title, "path-click": pathByLang.en },
-      es: { title: content.es.title, "path-click": pathByLang.es },
-    });
-  });
-
-  config["routes-md"] = [...keptRoutes, ...newRoutes];
-  config["menus-header-md"] = [...keptMenus, ...newMenus];
-  await fs.writeFile(configAbs, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
-
-  return { configPath: configRel, slugs: order, files: writtenFiles };
-}
+import fs from "node:fs/promises";
+import path from "node:path";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { buildMdRoute } from "../../builders/route-builders.mjs";
+import type { AiDocPage } from "../application/docs-pattern";
+
+const CANONICAL_LANGS = ["pt", "en", "es"] as const;
+type Lang = (typeof CANONICAL_LANGS)[number];
+
+/** AI routes/menus use a high, dedicated id range so they never clash with the
+ * deterministic base routes (ids 1..N) and can be identified for idempotency. */
+const AI_ROUTE_ID_BASE = 1000;
+
+export interface VersionDocsWriteInput {
+  cwd: string;
+  versionId: string;
+  /** Pages generated per language (only the languages the user selected). */
+  pagesByLang: Partial<Record<Lang, AiDocPage[]>>;
+}
+
+export interface VersionDocsWriteResult {
+  configPath: string;
+  slugs: string[];
+  files: string[];
+}
+
+interface LangContent {
+  title: string;
+  body: string;
+}
+
+function indexBySlug(pages: AiDocPage[] | undefined): Map<string, AiDocPage> {
+  const map = new Map<string, AiDocPage>();
+  for (const page of pages ?? []) {
+    if (!map.has(page.slug)) map.set(page.slug, page);
+  }
+  return map;
+}
+
+/**
+ * Write AI-generated pages into the gitpagedocs versioned structure and wire
+ * them into the version config.json (routes-md + menus-header-md). Pages are
+ * written for ALL three canonical languages (missing languages reuse an
+ * available translation) so every route path stays valid. Idempotent: any prior
+ * `aiGenerated` routes/menus are replaced, never duplicated. The base config and
+ * its deterministic routes are preserved untouched.
+ */
+export async function writeVersionDocs(input: VersionDocsWriteInput): Promise<VersionDocsWriteResult> {
+  const { cwd, versionId, pagesByLang } = input;
+  const base = `gitpagedocs/docs/versions/${versionId}`;
+
+  const perLang: Record<Lang, Map<string, AiDocPage>> = {
+    pt: indexBySlug(pagesByLang.pt),
+    en: indexBySlug(pagesByLang.en),
+    es: indexBySlug(pagesByLang.es),
+  };
+
+  // Ordered unique slug list (prefer en order, then pt, then es).
+  const order: string[] = [];
+  const seen = new Set<string>();
+  for (const lang of ["en", "pt", "es"] as Lang[]) {
+    for (const page of pagesByLang[lang] ?? []) {
+      if (!seen.has(page.slug)) {
+        seen.add(page.slug);
+        order.push(page.slug);
+      }
+    }
+  }
+  if (order.length === 0) {
+    throw new Error("No AI pages to write.");
+  }
+
+  const resolve = (slug: string): Record<Lang, LangContent> => {
+    const fallback = CANONICAL_LANGS.map((lang) => perLang[lang].get(slug)).find(Boolean);
+    const out = {} as Record<Lang, LangContent>;
+    for (const lang of CANONICAL_LANGS) {
+      const page = perLang[lang].get(slug) ?? fallback!;
+      out[lang] = { title: page.title, body: page.body };
+    }
+    return out;
+  };
+
+  // 1) Write the markdown files (all 3 canonical languages).
+  const writtenFiles: string[] = [];
+  for (const slug of order) {
+    const content = resolve(slug);
+    for (const lang of CANONICAL_LANGS) {
+      const rel = `${base}/${lang}/${slug}.md`;
+      const abs = path.resolve(cwd, rel);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, `${content[lang].body}\n`, "utf-8");
+      writtenFiles.push(rel);
+    }
+  }
+
+  // 2) Patch the version config.json (raw JSON round-trip, preserve all keys).
+  const configRel = `${base}/config.json`;
+  const configAbs = path.resolve(cwd, configRel);
+  let raw: string;
+  try {
+    raw = await fs.readFile(configAbs, "utf-8");
+  } catch {
+    throw new Error(
+      `Version config not found at ${configRel}. Run the base scaffold (\`gitpagedocs\`) first.`,
+    );
+  }
+  const config = JSON.parse(raw) as Record<string, unknown>;
+
+  const routesMd = Array.isArray(config["routes-md"]) ? (config["routes-md"] as Array<Record<string, unknown>>) : [];
+  const menusMd = Array.isArray(config["menus-header-md"]) ? (config["menus-header-md"] as Array<Record<string, unknown>>) : [];
+  const keptRoutes = routesMd.filter((route) => route?.aiGenerated !== true);
+  const keptMenus = menusMd.filter((menu) => menu?.aiGenerated !== true);
+
+  const newRoutes: Array<Record<string, unknown>> = [];
+  const newMenus: Array<Record<string, unknown>> = [];
+  order.forEach((slug, index) => {
+    const content = resolve(slug);
+    const id = AI_ROUTE_ID_BASE + index + 1;
+    const pathByLang = {
+      pt: `${base}/pt/${slug}.md`,
+      en: `${base}/en/${slug}.md`,
+      es: `${base}/es/${slug}.md`,
+    };
+    const titles = { pt: content.pt.title, en: content.en.title, es: content.es.title };
+    const descriptions = { pt: "", en: "", es: "" };
+    const route = buildMdRoute(versionId, id, pathByLang, titles, descriptions, {}) as Record<string, unknown>;
+    route.aiGenerated = true;
+    newRoutes.push(route);
+    newMenus.push({
+      id,
+      aiGenerated: true,
+      pt: { title: content.pt.title, "path-click": pathByLang.pt },
+      en: { title: content.en.title, "path-click": pathByLang.en },
+      es: { title: content.es.title, "path-click": pathByLang.es },
+    });
+  });
+
+  config["routes-md"] = [...keptRoutes, ...newRoutes];
+  config["menus-header-md"] = [...keptMenus, ...newMenus];
+  await fs.writeFile(configAbs, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+
+  return { configPath: configRel, slugs: order, files: writtenFiles };
+}

package/builders/config-orchestrator.mjs

@@ -5,7 +5,6 @@ import { DOCS } from "../content/docs.mjs";
 import { DOC_VERSIONS } from "../data/version-constants.mjs";
 import { buildRootConfig } from "./root-config-builder.mjs";
 import { buildVersionConfig } from "./version-config-builder.mjs";
-import { generateSourceViewerHtml } from "./source-viewer.mjs";
 
 /**
  * Build all config artifacts (root, layouts, versions, docs).
@@ -19,11 +18,6 @@ export function buildConfigArtifacts(options = {}) {
   const layoutsConfig = { layouts: LAYOUTS };
   const fallbackLayoutsConfig = { layouts: FALLBACK_LAYOUTS };
 
-  const sourceViewerHtml = generateSourceViewerHtml(root);
-  const docsHtml = {
-    sourceViewer: { pt: sourceViewerHtml, en: sourceViewerHtml, es: sourceViewerHtml },
-  };
-
   const versionConfigs = {};
   for (const versionId of DOC_VERSIONS) {
     versionConfigs[versionId] = buildVersionConfig(versionId);
@@ -34,7 +28,7 @@ export function buildConfigArtifacts(options = {}) {
     layoutsConfig,
     fallbackLayoutsConfig,
     docs: DOCS,
-    docsHtml,
+    docsHtml: {},
     versionConfigs,
   };
 }

package/builders/root-config-builder.mjs

@@ -11,15 +11,16 @@ export function buildRootConfig(options = {}) {
   const useOfficialLayouts = !useLocalLayoutConfig;
   const githubOwner = options.githubOwner;
   const githubRepo = options.githubRepo;
-  const repositorySearchHome = false;
+  const repositorySearchHome = true;
   const renderingUrl =
     githubOwner && githubRepo
       ? `https://${githubOwner}.github.io/${githubRepo}/`
       : "https://vidigal-code.github.io/git-page-docs/";
-  const projectLink =
-    githubOwner && githubRepo
-      ? `https://github.com/${githubOwner}/${githubRepo}`
-      : "https://github.com/Vidigal-code/git-page-docs";
+  const projectLink =
+    githubOwner && githubRepo
+      ? `https://github.com/${githubOwner}/${githubRepo}`
+      : "https://github.com/Vidigal-code/git-page-docs";
+  const sourceViewerPath = `${projectLink}/tree/main`;
 
   const versionEntries = DOC_VERSIONS.map((id) => ({
     id,
@@ -28,10 +29,12 @@ export function buildRootConfig(options = {}) {
     PathConfig: `gitpagedocs/docs/versions/${id}/config.json`,
     PreviewProject: "",
     UpdateDate: "",
-    branch: "",
-    release: "",
-    commit: "",
-  }));
+    branch: "",
+    release: "",
+    commit: "",
+    "source-viewer": true,
+    "source-viewer-path": sourceViewerPath,
+  }));
 
   const baseSiteConfig = getDefaultSiteConfig(DOCS, projectLink);
 

package/builders/route-builders.mjs

@@ -109,3 +109,28 @@ export function buildVideoRoute(versionId, routeId, videoType, pathVideo, titles
   if (authorization !== undefined) obj.authorization = authorization;
   return obj;
 }
+
+export function buildAudioRoute(versionId, routeId, audioType, pathAudio, titles, descriptions, options = {}) {
+  const base = buildVideoRoute(versionId, routeId, audioType, pathAudio, titles, descriptions, options);
+  const audioTypeByLang = typeof audioType === "string" ? { pt: audioType, en: audioType, es: audioType } : audioType;
+  const pathAudioByLang = typeof pathAudio === "string" ? { pt: pathAudio, en: pathAudio, es: pathAudio } : pathAudio;
+  const { video, ...rest } = base;
+  return {
+    ...rest,
+    audio: { audioType: audioTypeByLang, pathAudio: pathAudioByLang },
+  };
+}
+
+export function buildSourceViewerRoute(routeId, sourceViewerPath, titles, descriptions, options = {}) {
+  const base = buildMdRoute("", routeId, {}, titles, descriptions, {
+    ...options,
+    fullscreenEnabled: false,
+    RouteguideBrand: false,
+  });
+  delete base.path;
+  return {
+    ...base,
+    "source-viewer": true,
+    "source-viewer-path": sourceViewerPath,
+  };
+}

package/builders/theme-template.mjs

@@ -9,7 +9,7 @@ export function createThemeTemplate(layout, themeColors = THEME_COLORS) {
     id: layout.id,
     name: layout.name,
     author: layout.author,
-    version: "1.0.0",
+    version: "1.1.54",
     mode: layout.mode,
     supportsLightAndDarkModes: layout.supportsLightAndDarkModes,
     colors,