@gitpagedocs/cli 1.1.51 → 1.1.53

package/README.md

@@ -21,9 +21,10 @@ npx @gitpagedocs/cli
 | `gitpagedocs --push --owner <o> --repo <r> [--path <sub>]` | Generate, configure Pages, create workflow, commit + push |
 | `gitpagedocs --home` | Standalone distribution (`gitpagedocshome/`: static site + .env + Dockerfile) |
 | `gitpagedocs -i` / `--interactive` | Interactive prompts |
-| `gitpagedocs ai` | Interactive AI documentation generator (see below) |
+| `gitpagedocs ai` | Interactive AI documentation generator — writes pages in the gitpagedocs pattern (see below) |
 | `gitpagedocs provider [id]` · `models [provider]` | List AI providers / catalog models |
-| `gitpagedocs document[:repo\|:file\|:folder]` | Generate documentation with AI |
+| `gitpagedocs document[:repo\|:file\|:folder]` | Generate documentation with AI in the gitpagedocs pattern |
+| `gitpagedocs password` | Set a documentation access password (writes the public key to `config.json`, prints the private key) |
 | `gitpagedocs deploy` / `pages [actions\|deploy]` | Configure GitHub Pages via Actions + push |
 | `gitpagedocs docs` | Refresh managed regions of README/CONTRIBUTING/SECURITY |
 | `gitpagedocs doctor` · `version` · `update` | Diagnostics / version / update hint |
@@ -134,9 +135,18 @@ npx gitpagedocs ai
 - asks provider (`openai`, `claude`, `gemini`, `ollama`)
 - asks API key or Ollama URL
 - asks paths to scan (supports one or many paths, including other repositories)
-- generates markdown documentation in `pt`, `en`, `es`
+- generates documentation in `pt`, `en`, `es` **in the gitpagedocs pattern**
 - optionally persists config in `.gitpagedocsconfig`
-- optionally runs standard `gitpagedocs` scaffolding after AI generation
+
+### gitpagedocs pattern output
+
+The model is given a gitpagedocs-aware system prompt and returns documentation split into
+pages (delimited by `=== PAGE: <slug> | <Title> ===`). The CLI scaffolds the base
+`gitpagedocs/` structure first, then writes each page to
+`gitpagedocs/docs/versions/<latest>/<lang>/<slug>.md` for every language and **wires it into
+that version's `config.json`** (`routes-md` + `menus-header-md`) so the pages render in the
+viewer menu. Entries are tagged `aiGenerated` and idempotent (re-running replaces them). A
+later plain `gitpagedocs` rebuild drops the wiring — re-run `gitpagedocs ai` to restore.
 
 ### `.gitpagedocsconfig` (manual mode)
 

package/ai/application/docs-pattern.ts

@@ -0,0 +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}` };
+  });
+}

package/ai/application/run-ai-cli-command.ts

@@ -1,4 +1,3 @@
-import path from "node:path";
 import { AiCommandService } from "./ai-command";
 import { createAiProvider } from "./ai-provider-factory";
 import { FileSystemAdapter, type FilePayload } from "../infrastructure/file-system-adapter";
@@ -7,6 +6,11 @@ import {
 } from "../infrastructure/ai-config-file";
 import type { AiCliRunPlan, AiCliRunSummary } from "../core/models/ai-cli-config";
 import { promptMissingDirectories, runAiInteractivePrompt } from "../presentation/ai-prompts";
+import { GITPAGEDOCS_DOC_SYSTEM_PROMPT } from "../config";
+import { parseAiPages, type AiDocPage } from "./docs-pattern";
+import { writeVersionDocs } from "../infrastructure/version-docs-writer";
+// @ts-expect-error .mjs runtime module is type-less in this package.
+import { DOC_VERSIONS } from "../../contracts/doc-versions.mjs";
 
 const LANGUAGE_TO_LABEL: Record<string, string> = {
   pt: "Portuguese",
@@ -22,7 +26,13 @@ function aggregateFilesPayload(files: FilePayload[]): string {
 
 function buildLanguagePrompt(basePrompt: string, language: "pt" | "en" | "es"): string {
   const languageLabel = LANGUAGE_TO_LABEL[language] ?? language;
-  return `${basePrompt}\n\nMandatory output rules:\n- Respond 100% in ${languageLabel}.\n- Generate professional markdown for technical documentation.\n- Include architectural overview, layer responsibilities, and next steps.\n- Avoid content outside the scope of the analyzed files.`;
+  const authorGuidance = basePrompt?.trim() ? `Additional author guidance:\n${basePrompt.trim()}\n\n` : "";
+  return (
+    `${GITPAGEDOCS_DOC_SYSTEM_PROMPT}\n\n` +
+    authorGuidance +
+    `Output language: write every page Title and body 100% in ${languageLabel}. ` +
+    `Keep each page slug lowercase-kebab and in English so the languages line up.`
+  );
 }
 
 async function collectFilesWithInteractiveFallback(
@@ -66,7 +76,7 @@ async function collectFilesWithInteractiveFallback(
   };
 }
 
-async function runPlan(plan: AiCliRunPlan): Promise<AiCliRunSummary> {
+async function runPlan(plan: AiCliRunPlan, cwd: string): Promise<AiCliRunSummary> {
   const provider = createAiProvider({
     provider: plan.config.ai.provider,
     model: plan.config.ai.model,
@@ -92,30 +102,33 @@ async function runPlan(plan: AiCliRunPlan): Promise<AiCliRunSummary> {
   }
 
   const payload = aggregateFilesPayload(files);
-  const outputs: string[] = [];
+  const pagesByLang: Partial<Record<"pt" | "en" | "es", AiDocPage[]>> = {};
 
   for (const language of plan.config.ai.languages) {
     const prompt = buildLanguagePrompt(plan.config.ai.contextPrompt, language);
     const markdown = await aiService.runGeneration(payload, prompt);
-    const outputFile = path.posix.join(
-      plan.config.ai.outputDir.replace(/\\/g, "/"),
-      `${plan.config.ai.filePrefix}-${plan.config.ai.provider}-${language}.md`,
-    );
-    await fileSystem.writeDocumentationOutput(markdown, outputFile);
-    outputs.push(outputFile);
+    pagesByLang[language] = parseAiPages(markdown);
   }
 
+  // Wire the AI pages into the latest documentation version (gitpagedocs pattern).
+  const versionId = DOC_VERSIONS[DOC_VERSIONS.length - 1] as string;
+  const result = await writeVersionDocs({ cwd, versionId, pagesByLang });
+
   return {
     scannedDirectories: scanned,
     skippedDirectories: skipped,
     scannedFilesCount: files.length,
-    outputs,
+    outputs: result.files,
+    pages: result.slugs,
   };
 }
 
 export async function runAiCliCommand(options: {
   cwd: string;
   onInfo?: (message: string) => void;
+  /** Provided by the composition root to scaffold the base gitpagedocs/ tree
+   * (so the version config.json exists before AI pages are wired into it). */
+  onScaffold?: () => Promise<void>;
 }): Promise<{ summary: AiCliRunSummary; runConfigScaffold: boolean }> {
   const logInfo = options.onInfo ?? (() => undefined);
   const configRepo = new AiConfigFileRepository(options.cwd);
@@ -128,7 +141,14 @@ export async function runAiCliCommand(options: {
     logInfo(`[gitpagedocs:ai] Configuration saved to ${configRepo.getConfigPath()}`);
   }
 
-  const summary = await runPlan(plan);
+  // Build the base gitpagedocs structure BEFORE generation so the version
+  // config.json exists and the AI pages can be wired into it.
+  if (plan.runConfigScaffold && options.onScaffold) {
+    logInfo("[gitpagedocs] Generating base gitpagedocs structure...");
+    await options.onScaffold();
+  }
+
+  const summary = await runPlan(plan, options.cwd);
   return {
     summary,
     runConfigScaffold: plan.runConfigScaffold,

package/ai/config.ts

@@ -19,4 +19,32 @@ export const AI_MODEL_DEFAULTS: Readonly<Record<AiProviderId, string>> = {
 export const DEFAULT_AI_DOC_PROMPT =
   'You are a senior tech writer. Describe the provided code.';
 
+/**
+ * System prompt that teaches the model what gitpagedocs is and forces it to
+ * return documentation in the gitpagedocs pattern: a sequence of pages, each
+ * introduced by a machine-parseable delimiter line so the CLI can split the
+ * response into individual versioned markdown pages and wire them into the
+ * viewer's config.json (routes-md + menus-header-md).
+ */
+export const GITPAGEDOCS_DOC_SYSTEM_PROMPT = [
+  'You are the documentation engine for "gitpagedocs", a generator of multilingual,',
+  'versioned static documentation sites. gitpagedocs renders markdown pages from',
+  'gitpagedocs/docs/versions/<version>/<lang>/<page>.md and wires them into a viewer',
+  'through a config.json contract (routes + header menus). Your job is to analyze the',
+  'provided source code and produce clean, professional documentation that fits this',
+  'pattern so it can be dropped straight into a gitpagedocs site.',
+  '',
+  'STRICT OUTPUT FORMAT — return ONLY a sequence of pages. Begin every page with a',
+  'delimiter line on its own, exactly:',
+  '=== PAGE: <slug> | <Title> ===',
+  'followed by the page body in GitHub-flavored markdown. Rules:',
+  '- Produce 4 to 8 cohesive pages. Suggested slugs: overview, getting-started,',
+  '  architecture, configuration, usage, deployment (adapt to the project).',
+  '- <slug> MUST be lowercase-kebab-case and in ENGLISH, and identical across every',
+  '  language run, so the languages line up (only the Title and body are translated).',
+  '- Do NOT wrap the whole answer in a code fence. Do NOT add any preamble or epilogue',
+  '  outside the page blocks. The first line of your reply MUST be a "=== PAGE:" line.',
+  '- Base everything strictly on the analyzed files; do not invent features.',
+].join('\n');
+
 export const OLLAMA_DEFAULT_BASE_URL = 'http://localhost:11434';

package/ai/core/models/ai-cli-config.ts

@@ -28,4 +28,6 @@ export interface AiCliRunSummary {
   skippedDirectories: string[];
   scannedFilesCount: number;
   outputs: string[];
+  /** Slugs of the gitpagedocs pages wired into the version config (if any). */
+  pages?: string[];
 }

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

@@ -0,0 +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 };
+}

package/ai/presentation/ai-prompts.ts

@@ -141,7 +141,7 @@ export async function promptUseExistingConfig(existingConfig: AiCliConfig): Prom
     if (!useExistingConfig) return null;
 
     const runConfigScaffold = await askConfirm(
-        'After generating docs with AI, run the default gitpagedocs scaffolding?',
+        'Generate the base gitpagedocs structure first, so the AI pages are wired into the docs viewer?',
         true,
     );
 
@@ -220,7 +220,7 @@ export async function runAiInteractivePrompt(existingConfig?: AiCliConfig | null
     );
 
     const runConfigScaffold = await askConfirm(
-        'After generating docs with AI, run the default gitpagedocs scaffolding?',
+        'Generate the base gitpagedocs structure first, so the AI pages are wired into the docs viewer?',
         true,
     );
 

package/data/layouts.mjs

@@ -348,6 +348,26 @@ export const LAYOUTS = [
     supportsLightAndDarkModesReference: "slate-1",
     mode: "light",
   },
+  {
+    id: "vscode-dark",
+    name: "VSCode Dark",
+    author: "Kauan Vidigal",
+    file: "templates/vscode-dark.json",
+    preview: "Visual Studio Code Dark+ theme with editor blue accents",
+    supportsLightAndDarkModes: true,
+    supportsLightAndDarkModesReference: "vscode-1",
+    mode: "dark",
+  },
+  {
+    id: "vscode-light",
+    name: "VSCode Light",
+    author: "Kauan Vidigal",
+    file: "templates/vscode-light.json",
+    preview: "Visual Studio Code Light+ theme with clean editor tones",
+    supportsLightAndDarkModes: true,
+    supportsLightAndDarkModesReference: "vscode-1",
+    mode: "light",
+  },
 ];
 
 export const FALLBACK_LAYOUTS = LAYOUTS.filter((layout) => layout.id === "aurora-dark" || layout.id === "aurora-light");

package/data/theme-colors.mjs

@@ -384,4 +384,26 @@ export const THEME_COLORS = {
     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",
+  },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpagedocs/cli",
-  "version": "1.1.51",
+  "version": "1.1.53",
   "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
   "bin": {
     "gitpagedocs": "index.mjs"
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
-    "@gitpagedocs/mcp": "^1.1.51",
-    "@gitpagedocs/tools": "^1.1.51",
+    "@gitpagedocs/mcp": "^1.1.53",
+    "@gitpagedocs/tools": "^1.1.53",
     "tsx": "^4.21.0"
   },
   "repository": {

package/presentation/index.ts

@@ -78,11 +78,19 @@ async function main(): Promise<void> {
     },
     runAi: async (context) => {
       console.log("[gitpagedocs] Iniciando Módulo de IA na CLI...");
+      const safePrebuiltDir =
+        typeof context.prebuiltDir === "string"
+          ? context.prebuiltDir
+          : path.join(String(context.pkgRoot ?? process.cwd()), "prebuilt");
       // @ts-ignore
       const { runAiCliCommand } = await import("../ai/application/run-ai-cli-command.ts");
       const result = await runAiCliCommand({
         cwd: process.cwd(),
         onInfo: (message: string) => console.log(message),
+        // Scaffold the base gitpagedocs/ structure before AI pages are wired in.
+        onScaffold: async () => {
+          await executeConfigOnly({ ...context, prebuiltDir: safePrebuiltDir }, configOnlyRuntime);
+        },
       });
 
       if (result.summary.scannedFilesCount === 0) {
@@ -90,13 +98,13 @@ async function main(): Promise<void> {
         return;
       }
 
-      if (result.runConfigScaffold) {
-        console.log("\n[gitpagedocs] Scaffolding GitPageDocs ecosystem automatically...");
-        const safePrebuiltDir = typeof context.prebuiltDir === "string" ? context.prebuiltDir : path.join(String(context.pkgRoot ?? process.cwd()), "prebuilt");
-        await executeConfigOnly({ ...context, prebuiltDir: safePrebuiltDir }, configOnlyRuntime);
-      }
-
-      console.log(`\n🎉 Processo completo! Arquivos gerados: ${result.summary.outputs.join(", ")}`);
+      const pages = result.summary.pages ?? [];
+      console.log(
+        `\n🎉 Processo completo! Páginas no padrão gitpagedocs: ${pages.join(", ") || "(nenhuma)"}`,
+      );
+      console.log(
+        `[gitpagedocs:ai] ${result.summary.outputs.length} arquivos markdown gerados e conectados ao config.json da versão mais recente.`,
+      );
     },
   });
   printCredits();