@gitpagedocs/cli 0.0.1

package/builders/root-config-builder.d.mts

@@ -0,0 +1,16 @@
+/** Options that shape the generated root config. */
+export interface RootConfigOptions {
+  useLocalLayoutConfig?: boolean;
+  githubOwner?: string;
+  githubRepo?: string;
+  /** Repo-relative layouts home referenced by the generated config. */
+  layoutsDir?: string;
+}
+
+export interface RootConfig {
+  site: Record<string, unknown>;
+  VersionControl: { versions: Array<Record<string, unknown>> };
+  translations: Record<string, unknown>;
+}
+
+export declare function buildRootConfig(options?: RootConfigOptions): RootConfig;

package/builders/root-config-builder.mjs

@@ -0,0 +1,56 @@
+/** Build root config for gitpagedocs */
+import { OFFICIAL_LAYOUTS_CONFIG_URL, OFFICIAL_LAYOUTS_TEMPLATES_URL } from "../data/urls.mjs";
+import {
+  resolveProjectLink,
+  resolveRenderingUrl,
+  resolveSourceViewerPath,
+  resolveLayoutsLinks,
+} from "./project-links.mjs";
+import { DOC_VERSIONS } from "../data/version-constants.mjs";
+import { getDefaultSiteConfig } from "../data/default-site-config.mjs";
+
+export function buildRootConfig(options = {}) {
+  const useLocalLayoutConfig = Boolean(options.useLocalLayoutConfig);
+  const useOfficialLayouts = !useLocalLayoutConfig;
+  const githubOwner = options.githubOwner;
+  const githubRepo = options.githubRepo;
+  const repositorySearchHome = true;
+  const renderingUrl = resolveRenderingUrl(githubOwner, githubRepo);
+  const projectLink = resolveProjectLink(githubOwner, githubRepo);
+  const sourceViewerPath = resolveSourceViewerPath(githubOwner, githubRepo);
+  const layoutsLinks = resolveLayoutsLinks(githubOwner, githubRepo, options.layoutsDir);
+
+  const versionEntries = DOC_VERSIONS.map((id) => ({
+    id,
+    path: `gitpagedocs/docs/versions/${id}/config.json`,
+    ProjectLink: projectLink,
+    PathConfig: `gitpagedocs/docs/versions/${id}/config.json`,
+    PreviewProject: "",
+    UpdateDate: "",
+    branch: "",
+    release: "",
+    commit: "",
+    "source-viewer": true,
+    "source-viewer-path": sourceViewerPath,
+  }));
+
+  const baseSiteConfig = getDefaultSiteConfig(projectLink, options.languageToggles);
+
+  return {
+    site: {
+      ...baseSiteConfig,
+      layoutsConfigPathOficial: useOfficialLayouts,
+      layoutsConfigPathTemplatesOficial: useOfficialLayouts ? OFFICIAL_LAYOUTS_TEMPLATES_URL : "",
+      layoutsConfigPathOficialUrl: useOfficialLayouts ? OFFICIAL_LAYOUTS_CONFIG_URL : "",
+      layoutsConfigPath: useLocalLayoutConfig ? layoutsLinks.config : "",
+      layoutsConfigPathTemplates: useLocalLayoutConfig ? layoutsLinks.templates : "",
+      repositorySearchHome,
+      rendering: renderingUrl,
+      AiChatEnabled: true,
+      docsAccess: { enabled: false, publicKey: "" },
+    },
+    VersionControl: {
+      versions: versionEntries,
+    },
+  };
+}

package/builders/route-builders.mjs

@@ -0,0 +1,136 @@
+/** Build route objects for md, html, and video content types */
+
+export function buildMdRoute(versionId, routeId, pathByLang, titles, descriptions, options = {}) {
+  const {
+    titleCss = "font-size: 1.85rem; font-weight: 700;",
+    titleDarkCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
+    titleLightCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
+    titlePosition = "center",
+    titleIsVisible = true,
+    descriptionCss = "font-size: 1.2rem; font-weight: 500;",
+    descriptionDarkCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
+    descriptionLightCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
+    descriptionPosition = "center",
+    descriptionIsVisible = true,
+    fullscreenEnabled = true,
+    marginTop = "",
+    marginBottom = "",
+    blockLink = true,
+    container,
+    browseAll = false,
+    RouteguideBrand = true,
+    RouteGuideSpeciFicbrand = [],
+    RouteguideBrandPosition = "center",
+    RouteguideBrandContainerTop = false,
+    audio,
+    authorization,
+  } = options;
+  const out = {
+    id: routeId,
+    title: titles ?? { pt: "Documentação", en: "Documentation", es: "Documentación" },
+    description: descriptions ?? { pt: "Descrição da página", en: "Page description", es: "Descripción de la página" },
+    titleCss,
+    titleDarkCss,
+    titleLightCss,
+    titlePosition,
+    titleIsVisible,
+    descriptionCss,
+    descriptionDarkCss,
+    descriptionLightCss,
+    descriptionPosition,
+    descriptionIsVisible,
+    path: pathByLang,
+    fullscreenEnabled,
+    marginTop,
+    marginBottom,
+    blockLink,
+    container,
+    browseAll,
+    RouteguideBrand,
+    RouteGuideSpeciFicbrand,
+    RouteguideBrandPosition,
+    RouteguideBrandContainerTop,
+  };
+  if (container !== undefined) out.container = container;
+  if (audio !== undefined) out.audio = audio;
+  if (authorization !== undefined) out.authorization = authorization;
+  return out;
+}
+
+export function buildHtmlRoute(versionId, routeId, pathByLang, titles, descriptions, options = {}) {
+  const base = buildMdRoute(versionId, routeId, pathByLang, titles, descriptions, options);
+  return { ...base };
+}
+
+export function buildVideoRoute(versionId, routeId, videoType, pathVideo, titles, descriptions, options = {}) {
+  const {
+    titleCss = "font-size: 1.85rem; font-weight: 700;",
+    titleDarkCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
+    titleLightCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
+    titlePosition = "center",
+    titleIsVisible = true,
+    descriptionCss = "font-size: 1.2rem; font-weight: 500;",
+    descriptionDarkCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
+    descriptionLightCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
+    descriptionPosition = "center",
+    descriptionIsVisible = true,
+    fullscreenEnabled = true,
+    marginTop = "",
+    marginBottom = "",
+    blockLink = true,
+    container,
+    browseAll = false,
+    authorization,
+  } = options;
+  const videoTypeByLang = typeof videoType === "string" ? { pt: videoType, en: videoType, es: videoType } : videoType;
+  const pathVideoByLang = typeof pathVideo === "string" ? { pt: pathVideo, en: pathVideo, es: pathVideo } : pathVideo;
+  const obj = {
+    id: routeId,
+    title: titles ?? { pt: "Vídeo", en: "Video", es: "Vídeo" },
+    description: descriptions ?? { pt: "Descrição do vídeo", en: "Video description", es: "Descripción del vídeo" },
+    titleCss,
+    titleDarkCss,
+    titleLightCss,
+    titlePosition,
+    titleIsVisible,
+    descriptionCss,
+    descriptionDarkCss,
+    descriptionLightCss,
+    descriptionPosition,
+    descriptionIsVisible,
+    fullscreenEnabled,
+    marginTop,
+    marginBottom,
+    blockLink,
+    browseAll,
+    video: { videoType: videoTypeByLang, pathVideo: pathVideoByLang },
+  };
+  if (container !== undefined) obj.container = container;
+  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

@@ -0,0 +1,76 @@
+/** Build theme JSON template from layout definition */
+
+import { PACKAGE_VERSION } from "../contracts/doc-versions.mjs";
+import { THEME_COLORS } from "../data/theme-colors.mjs";
+
+export function createThemeTemplate(layout, themeColors = THEME_COLORS) {
+  const colors = themeColors[layout.id] ?? themeColors.default;
+  const dark = layout.mode === "dark";
+  return {
+    id: layout.id,
+    name: layout.name,
+    author: layout.author,
+    version: PACKAGE_VERSION,
+    mode: layout.mode,
+    supportsLightAndDarkModes: layout.supportsLightAndDarkModes,
+    colors,
+    typography: {
+      fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Inter, Roboto, Helvetica, Arial, sans-serif",
+      fontSize: {
+        small: "0.875rem",
+        base: "1rem",
+        medium: "1.125rem",
+        large: "1.25rem",
+        xlarge: "2rem",
+      },
+    },
+    components: {
+      header: {
+        height: "80px",
+        backgroundColor: dark ? "#0B1220" : "#FFFFFF",
+        borderBottom: dark ? "1px solid #334155" : "1px solid #E2E8F0",
+      },
+      footer: {
+        height: "60px",
+        backgroundColor: dark ? "#0B1220" : "#FFFFFF",
+        borderTop: dark ? "1px solid #334155" : "1px solid #E2E8F0",
+      },
+      card: {
+        borderRadius: "16px",
+        padding: "24px",
+        boxShadow: dark ? "0 18px 60px rgba(0, 0, 0, 0.45)" : "0 18px 50px rgba(15, 23, 42, 0.08)",
+      },
+      button: {
+        borderRadius: "12px",
+        padding: "10px 18px",
+        border: dark ? "1px solid #334155" : "1px solid #E2E8F0",
+        hoverGlow: dark ? "0 0 0 3px rgba(124, 58, 237, 0.18)" : "0 0 0 4px rgba(109, 40, 217, 0.15)",
+      },
+      select: {
+        borderRadius: "12px",
+        padding: "10px 40px 10px 16px",
+        border: dark ? "1px solid #334155" : "1px solid #E2E8F0",
+        backgroundColor: dark ? "#0F172A" : "#FFFFFF",
+        textAlign: "center",
+        iconColor: colors.secondary,
+        hoverBorderColor: dark ? "rgba(34, 211, 238, 0.7)" : "rgba(8, 145, 178, 0.7)",
+        focusBorderColor: dark ? "rgba(124, 58, 237, 0.8)" : "rgba(109, 40, 217, 0.8)",
+        focusGlow: dark ? "0 0 0 4px rgba(124, 58, 237, 0.18)" : "0 0 0 4px rgba(109, 40, 217, 0.15)",
+      },
+      checkbox: {
+        width: "20px",
+        height: "20px",
+        accentColor: colors.primary,
+        borderColor: dark ? "#475569" : "#CBD5E1",
+        hoverBorderColor: dark ? "rgba(34, 211, 238, 0.75)" : "rgba(8, 145, 178, 0.7)",
+        checkMarkColor: colors.background,
+        borderRadius: "6px",
+      },
+    },
+    animations: {
+      enableTypingEffect: false,
+      enableGlow: dark,
+      transitionDuration: "0.22s",
+    },
+  };
+}

package/builders/version-config-builder.mjs

@@ -0,0 +1,186 @@
+/** Build version config (routes, menus) for each doc version */
+
+import {
+  ROUTE_PATHS,
+  VIDEO_IDS,
+  AUDIO_IDS,
+  PAGE2_AUDIO,
+} from "../data/path-mappings.mjs";
+import {
+  ROUTE_META_ID1,
+  ROUTE_META_ID2,
+  ROUTE_META_ID3,
+  ROUTE_META_ID4,
+  ROUTE_META_ID5,
+  ROUTE_META_ID6,
+  VIDEO_META_ID1,
+  VIDEO_META_ID2,
+  VIDEO_META_ID3,
+  VIDEO_META_ID4,
+  AUDIO_META_ID12,
+  SOURCE_VIEWER_META,
+  DEFAULT_HIERARCHY,
+} from "../data/route-metas.mjs";
+import { buildAudioRoute, buildMdRoute, buildSourceViewerRoute, buildVideoRoute } from "./route-builders.mjs";
+import { resolveSourceViewerPath } from "./project-links.mjs";
+
+/** Demo route protections showcasing the "Authorized Routes" feature. They are
+ * applied only to the official (non-parameterized) scaffold — user sites
+ * generated with --owner/--repo stay public, since visitors of those sites
+ * have no discoverable unlock recipe. */
+const EXTERNAL_AUTH_PROVIDERS = ["authjs", "clerk", "firebase", "jwt"];
+const DOCS_ACCESS_KEY_ID = "docs-key";
+const MAINTAINER_ROLE = "maintainer";
+const VIDEO_ROUTE_AUTHORIZATION = {
+  requireExternalAuth: true,
+  allowedProviders: EXTERNAL_AUTH_PROVIDERS,
+};
+
+const ROUTE_METAS = {
+  1: ROUTE_META_ID1,
+  2: ROUTE_META_ID2,
+  3: ROUTE_META_ID3,
+  4: ROUTE_META_ID4,
+  5: ROUTE_META_ID5,
+  6: ROUTE_META_ID6,
+};
+const VIDEO_METAS = { 1: VIDEO_META_ID1, 2: VIDEO_META_ID2, 3: VIDEO_META_ID3, 4: VIDEO_META_ID4 };
+
+function buildVersionMdRoutes(versionId, includeDemoAuthorization) {
+  const base = `gitpagedocs/docs/versions/${versionId}`;
+  return [1, 2, 3, 4, 5, 6].map((id) => {
+    const paths = ROUTE_PATHS[id];
+    const meta = ROUTE_METAS[id];
+    const pathByLang = {
+      pt: `${base}/pt/${paths.pt}`,
+      en: `${base}/en/${paths.en}`,
+      es: `${base}/es/${paths.es}`,
+    };
+    const routeOptions = {
+      ...(id === 2 ? { audio: PAGE2_AUDIO } : {}),
+      ...(includeDemoAuthorization && id === 3
+        ? { authorization: { requiredRoles: [MAINTAINER_ROLE] } }
+        : {}),
+      ...(includeDemoAuthorization && id === 6
+        ? {
+            authorization: {
+              accessKeyId: DOCS_ACCESS_KEY_ID,
+              requiredRoles: [MAINTAINER_ROLE],
+              requireExternalAuth: true,
+              allowedProviders: EXTERNAL_AUTH_PROVIDERS,
+            },
+          }
+        : {}),
+    };
+    return buildMdRoute(versionId, id, pathByLang, meta.titles, meta.descriptions, routeOptions);
+  });
+}
+
+function buildVersionVideoRoutes(versionId, includeDemoAuthorization) {
+  return [1, 2, 3, 4].map((id) =>
+    buildVideoRoute(
+      versionId,
+      id + 7,
+      "youtube",
+      VIDEO_IDS[id - 1],
+      VIDEO_METAS[id].title,
+      VIDEO_METAS[id].description,
+      includeDemoAuthorization ? { authorization: VIDEO_ROUTE_AUTHORIZATION } : {},
+    )
+  );
+}
+
+function buildVersionAudioRoutes(versionId) {
+  return [
+    buildAudioRoute(
+      versionId,
+      AUDIO_META_ID12.id,
+      "youtube",
+      AUDIO_IDS[0],
+      AUDIO_META_ID12.title,
+      AUDIO_META_ID12.description,
+    ),
+  ];
+}
+
+function buildVersionSourceViewerRoutes(options = {}) {
+  return [
+    buildSourceViewerRoute(
+      SOURCE_VIEWER_META.id,
+      resolveSourceViewerPath(options.githubOwner, options.githubRepo),
+      SOURCE_VIEWER_META.titles,
+      SOURCE_VIEWER_META.descriptions,
+    ),
+  ];
+}
+
+function buildVersionMenus(versionId) {
+  const base = `gitpagedocs/docs/versions/${versionId}`;
+  const menuMd = [1, 2, 3, 4, 5, 6].map((id) => ({
+    id,
+    pt: { title: ROUTE_METAS[id].titles.pt, "path-click": `${base}/pt/${ROUTE_PATHS[id].pt}` },
+    en: { title: ROUTE_METAS[id].titles.en, "path-click": `${base}/en/${ROUTE_PATHS[id].en}` },
+    es: { title: ROUTE_METAS[id].titles.es, "path-click": `${base}/es/${ROUTE_PATHS[id].es}` },
+  }));
+  const menuVideo = [1, 2, 3, 4].map((id) => ({
+    id: id + 7,
+    pt: { title: `${VIDEO_METAS[id].title.pt.slice(0, 40)}...`, "path-click": `page:${id + 7}` },
+    en: { title: `${VIDEO_METAS[id].title.en.slice(0, 40)}...`, "path-click": `page:${id + 7}` },
+    es: { title: `${VIDEO_METAS[id].title.es.slice(0, 40)}...`, "path-click": `page:${id + 7}` },
+  }));
+  const menuAudio = [
+    {
+      id: AUDIO_META_ID12.id,
+      pt: { title: AUDIO_META_ID12.title.pt, "path-click": `page:${AUDIO_META_ID12.id}` },
+      en: { title: AUDIO_META_ID12.title.en, "path-click": `page:${AUDIO_META_ID12.id}` },
+      es: { title: AUDIO_META_ID12.title.es, "path-click": `page:${AUDIO_META_ID12.id}` },
+    },
+  ];
+  const menuSourceViewer = [
+    {
+      id: SOURCE_VIEWER_META.id,
+      pt: { title: SOURCE_VIEWER_META.titles.pt, "path-click": `page:${SOURCE_VIEWER_META.id}` },
+      en: { title: SOURCE_VIEWER_META.titles.en, "path-click": `page:${SOURCE_VIEWER_META.id}` },
+      es: { title: SOURCE_VIEWER_META.titles.es, "path-click": `page:${SOURCE_VIEWER_META.id}` },
+    },
+  ];
+  return { md: menuMd, sourceViewer: menuSourceViewer, html: [], video: menuVideo, audio: menuAudio };
+}
+
+/**
+ * Build version config for a single doc version.
+ * @param {string} versionId - e.g. "1.1.54"
+ * @param {object} [options] - { githubOwner, githubRepo } for the source-viewer link
+ * @returns {object} Version config with routes, menus, and hierarchy
+ */
+export function buildVersionConfig(versionId, options = {}) {
+  const includeDemoAuthorization = !options.githubOwner && !options.githubRepo;
+  const menus = buildVersionMenus(versionId);
+
+  return {
+    auth: {
+      accessKeys: {
+        "docs-key": "open-gitpagedocs-docs",
+      },
+      rolesStorageKey: "git-page-docs:route-auth:roles",
+      providers: [
+        { type: "authjs", enabled: true, sessionEndpoint: "/api/auth/session", rolesClaimPath: "user.roles" },
+        { type: "clerk", enabled: true, rolesClaimPath: "claims.publicMetadata.roles" },
+        { type: "firebase", enabled: true, tokenStorageKey: "git-page-docs:firebase-token", rolesClaimPath: "roles" },
+        { type: "jwt", enabled: true, tokenStorageKey: "git-page-docs:jwt-token", rolesClaimPath: "roles" },
+      ],
+    },
+    "routes-md": buildVersionMdRoutes(versionId, includeDemoAuthorization),
+    "routes-source-viewer": buildVersionSourceViewerRoutes(options),
+    "routes-html": [],
+    "routes-video": buildVersionVideoRoutes(versionId, includeDemoAuthorization),
+    "routes-audio": buildVersionAudioRoutes(versionId),
+    "menus-header-md": menus.md,
+    "menus-header-source-viewer": menus.sourceViewer,
+    "menus-header-html": menus.html,
+    "menus-header-video": menus.video,
+    "menus-header-audio": menus.audio,
+    hierarchyPage: DEFAULT_HIERARCHY,
+    hierarchyMenu: DEFAULT_HIERARCHY,
+  };
+}