@gitpagedocs/cli 1.1.44

package/README.md

@@ -0,0 +1,169 @@
+# gitpagedocs (CLI)
+
+The **published npm package** of the [Git Page Docs](../README.md) monorepo. It scaffolds the `gitpagedocs/` docs contract, generates docs with AI, configures GitHub Pages, and runs the MCP server.
+
+```bash
+npm install -g gitpagedocs   # global
+gitpagedocs                  # generate gitpagedocs/ config (config-only)
+
+# or one-off, no install:
+npx gitpagedocs
+```
+
+> This package ships its TypeScript sources and runs them via `tsx`; it depends on the workspace packages `@gitpagedocs/tools` and `@gitpagedocs/mcp` (published alongside it).
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `gitpagedocs` | Generate `gitpagedocs/` config + versioned docs (config-only) |
+| `gitpagedocs --layoutconfig` | Also emit local layout templates in `gitpagedocs/layouts/` |
+| `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 provider [id]` · `models [provider]` | List AI providers / catalog models |
+| `gitpagedocs document[:repo\|:file\|:folder]` | Generate documentation with AI |
+| `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 |
+| `gitpagedocs mcp start` | Start the MCP server over stdio |
+
+The AI-CLI implementation lives in `cli/ai/` (relocated from the frontend so the published package is self-contained).
+
+# CLI Architecture (Clean Architecture + SOLID)
+
+## Layer Overview
+
+```
+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
+```
+
+## SOLID Principles
+
+| Principle | Application |
+|-----------|-------------|
+| **SRP** | `application/report` only formats messages; handlers only orchestrate |
+| **OCP** | New runtime implementations can be injected through ports |
+| **LSP** | `dispatch-mode` works with any runner implementing `CliCommandRunner` |
+| **ISP** | Split runtime contracts (`ConfigOnlyRuntimePort`, `HomeRuntimePort`) |
+| **DIP** | Use-cases depend on `application/ports`, not concrete fs/git/exec |
+
+## Clean Architecture
+
+- **Interfaces/Presentation**: parse CLI args, resolve mode, wire dependencies in `presentation/index.ts`
+- **Application**: orchestrate flows with explicit ports, without direct fs/git/exec imports
+- **Domain**: sanitize and core rules with no infrastructure dependencies
+- **Infrastructure**: concrete adapters for runtime side effects
+- **Contracts**: `tools/smoke` consumes `cli/contracts` instead of internal CLI modules
+
+## Authorized Routes Pipeline
+
+The CLI now generates authorized-route docs and config entries in PT/EN/ES.
+
+- Source content: `cli/content/docs.mjs` (`authorizedRoutes` key per language)
+- Route metadata: `cli/data/route-metas.mjs` (`ROUTE_META_ID6`)
+- Route path mapping: `cli/data/path-mappings.mjs` (`authorized-routes.md`)
+- Version config composition: `cli/builders/version-config-builder.mjs`
+- Doc key resolution: `cli/runtime/doc-path-resolver.mjs`
+
+Generated artifacts include:
+
+- `gitpagedocs/docs/versions/<version>/config.json` with `auth` and route `authorization`
+- `gitpagedocs/docs/versions/<version>/{pt,en,es}/authorized-routes.md`
+- `menus-header-md` entry dedicated to Authorized Routes
+
+## GitHub Pages Push Paths
+
+- Default project-site publish (`--push` without `--path`) targets `/<repo>/`.
+- Custom project subpath publish (`--push --path <segment>`) targets `/<repo>/<segment>/`.
+- `--path` accepts a single sanitized segment (letters, numbers, `.`, `_`, `-`).
+
+Example:
+
+```bash
+npx gitpagedocs --owner vidigal-code --repo energy-bill-ai-parser --path git-docs --push
+```
+
+Expected URL after deployment:
+
+```text
+https://vidigal-code.github.io/energy-bill-ai-parser/git-docs/
+```
+
+## AI CLI (interactive + config file)
+
+The CLI now includes a dedicated interactive AI mode:
+
+```bash
+npx gitpagedocs ai
+```
+
+### What it does
+
+- 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`
+- optionally persists config in `.gitpagedocsconfig`
+- optionally runs standard `gitpagedocs` scaffolding after AI generation
+
+### `.gitpagedocsconfig` (manual mode)
+
+You can create/edit this file manually and then run `npx gitpagedocs ai`:
+
+```json
+{
+	"version": 1,
+	"ai": {
+		"provider": "openai",
+		"model": "gpt-4o-mini",
+		"apiKey": "<YOUR_API_KEY>",
+		"paths": ["src", "cli", "../another-repo/src"],
+		"languages": ["pt", "en", "es"],
+		"outputDir": "gitpagedocs/docs",
+		"filePrefix": "ai-generated",
+		"contextPrompt": "Você é um redator técnico sênior..."
+	}
+}
+```
+
+For Ollama, use `baseUrl` instead of `apiKey`.
+
+### Interactive fallback
+
+If a directory is not found, CLI offers fallback choices:
+
+- fix paths and retry
+- skip missing paths and continue
+- abort safely

package/ai/application/ai-command.ts

@@ -0,0 +1,24 @@
+/**
+ * @file ai-command.ts
+ * @description Application service for running AI commands. Decoupled from concrete LLMs.
+ */
+import { ILLMProvider } from '../core/ports/illm-provider';
+
+export class AiCommandService {
+    constructor(private provider: ILLMProvider) { }
+
+    /**
+     * Executes the AI Documentation Generation for a specific content
+     */
+    async runGeneration(content: string, contextPrompt?: string): Promise<string> {
+        return await this.provider.generateDocumentation(content, contextPrompt);
+    }
+
+    /**
+     * Executes a CLI chat prompt
+     */
+    async runChat(prompt: string): Promise<string> {
+        const messages = [{ role: 'user' as const, content: prompt }];
+        return await this.provider.chat(messages);
+    }
+}

package/ai/application/ai-provider-factory.ts

@@ -0,0 +1,22 @@
+import type { AiProviderId } from "../config";
+import type { ILLMProvider } from "../core/ports/illm-provider";
+import { ToolsLlmProvider } from "../infrastructure/llm/tools-llm-provider";
+
+/**
+ * Creates the CLI LLM provider. Backed by the shared @gitpagedocs/tools AI core
+ * (one registry-driven implementation for every provider) — no per-provider
+ * switch. The legacy provider id (openai/claude/gemini/ollama) is mapped to the
+ * catalog inside ToolsLlmProvider.
+ */
+export function createAiProvider(input: {
+  provider: AiProviderId;
+  model: string;
+  apiKey?: string;
+  baseUrl?: string;
+}): ILLMProvider {
+  return new ToolsLlmProvider(input.provider, {
+    model: input.model,
+    apiKey: input.apiKey,
+    baseUrl: input.baseUrl,
+  });
+}

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

@@ -0,0 +1,136 @@
+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";
+import {
+  AiConfigFileRepository,
+} from "../infrastructure/ai-config-file";
+import type { AiCliRunPlan, AiCliRunSummary } from "../core/models/ai-cli-config";
+import { promptMissingDirectories, runAiInteractivePrompt } from "../presentation/ai-prompts";
+
+const LANGUAGE_TO_LABEL: Record<string, string> = {
+  pt: "Portuguese",
+  en: "English",
+  es: "Español",
+};
+
+function aggregateFilesPayload(files: FilePayload[]): string {
+  return files
+    .map((file) => `\n\n--- FILE: ${file.filePath} ---\n\n${file.content}`)
+    .join("");
+}
+
+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.`;
+}
+
+async function collectFilesWithInteractiveFallback(
+  fileSystem: FileSystemAdapter,
+  initialPaths: string[],
+): Promise<{ files: FilePayload[]; scanned: string[]; skipped: string[] }> {
+  let queue = [...initialPaths];
+  let scanned: string[] = [];
+  let skipped: string[] = [];
+  const files: FilePayload[] = [];
+
+  while (queue.length > 0) {
+    const { existing, missing } = fileSystem.splitExistingDirectories(queue);
+    scanned = [...scanned, ...existing];
+
+    for (const directory of existing) {
+      const directoryFiles = await fileSystem.readDirectoryRecursively(directory);
+      files.push(...directoryFiles);
+    }
+
+    if (!missing.length) break;
+
+    const fallback = await promptMissingDirectories(missing);
+    if (fallback.abort) {
+      skipped = [...skipped, ...missing];
+      break;
+    }
+
+    if (!fallback.replacementPaths.length) {
+      skipped = [...skipped, ...missing];
+      break;
+    }
+
+    queue = fallback.replacementPaths;
+  }
+
+  return {
+    files,
+    scanned,
+    skipped,
+  };
+}
+
+async function runPlan(plan: AiCliRunPlan): Promise<AiCliRunSummary> {
+  const provider = createAiProvider({
+    provider: plan.config.ai.provider,
+    model: plan.config.ai.model,
+    apiKey: plan.config.ai.apiKey,
+    baseUrl: plan.config.ai.baseUrl,
+  });
+
+  const aiService = new AiCommandService(provider);
+  const fileSystem = new FileSystemAdapter();
+
+  const { files, scanned, skipped } = await collectFilesWithInteractiveFallback(
+    fileSystem,
+    plan.config.ai.paths,
+  );
+
+  if (!files.length) {
+    return {
+      scannedDirectories: scanned,
+      skippedDirectories: skipped,
+      scannedFilesCount: 0,
+      outputs: [],
+    };
+  }
+
+  const payload = aggregateFilesPayload(files);
+  const outputs: string[] = [];
+
+  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);
+  }
+
+  return {
+    scannedDirectories: scanned,
+    skippedDirectories: skipped,
+    scannedFilesCount: files.length,
+    outputs,
+  };
+}
+
+export async function runAiCliCommand(options: {
+  cwd: string;
+  onInfo?: (message: string) => void;
+}): Promise<{ summary: AiCliRunSummary; runConfigScaffold: boolean }> {
+  const logInfo = options.onInfo ?? (() => undefined);
+  const configRepo = new AiConfigFileRepository(options.cwd);
+
+  const existingConfig = await configRepo.read();
+  const plan = await runAiInteractivePrompt(existingConfig);
+
+  if (plan.saveConfig) {
+    await configRepo.write(plan.config);
+    logInfo(`[gitpagedocs:ai] Configuration saved to ${configRepo.getConfigPath()}`);
+  }
+
+  const summary = await runPlan(plan);
+  return {
+    summary,
+    runConfigScaffold: plan.runConfigScaffold,
+  };
+}

package/ai/config.ts

@@ -0,0 +1,22 @@
+/**
+ * @file config.ts
+ * @description Provider constants for the AI CLI. Co-located in cli/ so the
+ * published `gitpagedocs` package does not reach into the frontend app. The
+ * browser keeps its own copy at frontend/src/shared/config/ai-config.ts.
+ */
+
+/** Legacy 4-provider id used by the interactive CLI (mapped to the 14-provider
+ * catalog in @gitpagedocs/tools via legacyProviderToCatalogId). */
+export type AiProviderId = 'openai' | 'claude' | 'gemini' | 'ollama';
+
+export const AI_MODEL_DEFAULTS: Readonly<Record<AiProviderId, string>> = {
+  openai: 'gpt-4o-mini',
+  claude: 'claude-3-5-sonnet-20240620',
+  gemini: 'gemini-1.5-flash',
+  ollama: 'llama3',
+};
+
+export const DEFAULT_AI_DOC_PROMPT =
+  'You are a senior tech writer. Describe the provided code.';
+
+export const OLLAMA_DEFAULT_BASE_URL = 'http://localhost:11434';

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

@@ -0,0 +1,31 @@
+import type { AiProviderId } from "../../config";
+
+export const AI_CLI_CONFIG_FILENAME = ".gitpagedocsconfig";
+
+export interface AiCliConfig {
+  version: 1;
+  ai: {
+    provider: AiProviderId;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+    paths: string[];
+    languages: Array<"pt" | "en" | "es">;
+    outputDir: string;
+    filePrefix: string;
+    contextPrompt: string;
+  };
+}
+
+export interface AiCliRunPlan {
+  config: AiCliConfig;
+  saveConfig: boolean;
+  runConfigScaffold: boolean;
+}
+
+export interface AiCliRunSummary {
+  scannedDirectories: string[];
+  skippedDirectories: string[];
+  scannedFilesCount: number;
+  outputs: string[];
+}

package/ai/core/ports/illm-provider.ts

@@ -0,0 +1,32 @@
+/**
+ * @file illm-provider.ts
+ * @description Contract for all LLM implementations ensuring OCP and DIP.
+ * Isolates the AI logic from the specific LLM providers (OpenAI, Claude, Ollama, etc.).
+ */
+
+export interface ChatMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    type?: 'text' | 'image' | 'audio'; // Supporting multimedia as requested
+}
+
+export interface ILLMProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+}
+
+export interface ILLMProvider {
+    /**
+     * Generates markdown documentation based on file content.
+     * @param fileContent Raw content of the source file
+     * @param contextPrompt Optional instructions to guide the generation (e.g., FSD standard)
+     */
+    generateDocumentation(fileContent: string, contextPrompt?: string): Promise<string>;
+
+    /**
+     * Conversational chat support.
+     * @param messages Array of chat messages (system context, user history, etc.)
+     */
+    chat(messages: ChatMessage[]): Promise<string>;
+}

package/ai/infrastructure/ai-config-file.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  AI_CLI_CONFIG_FILENAME,
+  type AiCliConfig,
+} from "../core/models/ai-cli-config";
+
+export class AiConfigFileRepository {
+  constructor(private readonly cwd: string = process.cwd()) {}
+
+  getConfigPath(): string {
+    return path.join(this.cwd, AI_CLI_CONFIG_FILENAME);
+  }
+
+  async read(): Promise<AiCliConfig | null> {
+    const configPath = this.getConfigPath();
+    try {
+      const content = await fs.readFile(configPath, "utf-8");
+      const parsed = JSON.parse(content) as Partial<AiCliConfig>;
+      if (!parsed || parsed.version !== 1 || !parsed.ai) return null;
+      return parsed as AiCliConfig;
+    } catch {
+      return null;
+    }
+  }
+
+  async write(config: AiCliConfig): Promise<void> {
+    const configPath = this.getConfigPath();
+    const data = JSON.stringify(config, null, 2);
+    await fs.writeFile(configPath, `${data}\n`, "utf-8");
+  }
+}

package/ai/infrastructure/file-system-adapter.ts

@@ -0,0 +1,83 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { statSync } from 'node:fs';
+
+export interface FilePayload {
+    filePath: string;
+    content: string;
+}
+
+export class FileSystemAdapter {
+    splitExistingDirectories(targetDirectories: string[]): { existing: string[]; missing: string[] } {
+        const existing: string[] = [];
+        const missing: string[] = [];
+
+        for (const targetDirectory of targetDirectories) {
+            const absolutePath = path.resolve(process.cwd(), targetDirectory);
+            try {
+                const stat = statSync(absolutePath);
+                if (stat.isDirectory()) {
+                    existing.push(targetDirectory);
+                } else {
+                    missing.push(targetDirectory);
+                }
+            } catch {
+                missing.push(targetDirectory);
+            }
+        }
+
+        return { existing, missing };
+    }
+
+    async readDirectoryRecursively(targetDirectory: string): Promise<FilePayload[]> {
+        const absolutePath = path.resolve(process.cwd(), targetDirectory);
+        const resolvedFiles: FilePayload[] = [];
+
+        try {
+            await this.traverse(absolutePath, resolvedFiles);
+        } catch (error) {
+        }
+
+        return resolvedFiles;
+    }
+
+    private async traverse(currentPath: string, payloadList: FilePayload[]): Promise<void> {
+        let stats;
+        try {
+            stats = await fs.stat(currentPath);
+        } catch {
+            return;
+        }
+
+        if (stats.isDirectory()) {
+            const basename = path.basename(currentPath);
+            if (['node_modules', '.git', '.next', 'out', 'dist'].includes(basename)) {
+                return;
+            }
+
+            const entries = await fs.readdir(currentPath);
+            for (const entry of entries) {
+                await this.traverse(path.join(currentPath, entry), payloadList);
+            }
+        } else if (stats.isFile()) {
+            const ext = path.extname(currentPath);
+            const validExtensions = ['.ts', '.tsx', '.js', '.jsx', '.json', '.md', '.css'];
+            if (validExtensions.includes(ext)) {
+                try {
+                    const content = await fs.readFile(currentPath, 'utf-8');
+                    payloadList.push({
+                        filePath: currentPath,
+                        content: content
+                    });
+                } catch {
+                }
+            }
+        }
+    }
+
+    async writeDocumentationOutput(outputContent: string, targetPath: string = "documentation-output.md"): Promise<void> {
+        const absoluteDest = path.resolve(process.cwd(), targetPath);
+        await fs.mkdir(path.dirname(absoluteDest), { recursive: true });
+        await fs.writeFile(absoluteDest, outputContent, 'utf-8');
+    }
+}

package/ai/infrastructure/llm/tools-llm-provider.ts

@@ -0,0 +1,54 @@
+import { createDefaultFactory, legacyProviderToCatalogId } from "@gitpagedocs/tools/ai";
+import type { AiMessage, ProviderConfig } from "@gitpagedocs/tools/ports";
+import type { ILLMProvider, ChatMessage, ILLMProviderConfig } from "../../core/ports/illm-provider";
+import { DEFAULT_AI_DOC_PROMPT, type AiProviderId } from "../../config";
+
+const factory = createDefaultFactory();
+
+/**
+ * Single CLI LLM provider backed by the shared @gitpagedocs/tools AI core.
+ * Replaces the four duplicated CLI provider classes (OpenAI/Claude/Gemini/
+ * Ollama) with one adapter over the registry/factory, preserving the
+ * ILLMProvider contract used by the AI documentation flow.
+ */
+export class ToolsLlmProvider implements ILLMProvider {
+  private readonly providerId;
+  private readonly model: string;
+  private readonly apiKey?: string;
+  private readonly baseUrl?: string;
+
+  constructor(legacyProvider: AiProviderId, config: ILLMProviderConfig) {
+    this.providerId = legacyProviderToCatalogId(legacyProvider);
+    this.model = config.model ?? "";
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl;
+  }
+
+  async generateDocumentation(fileContent: string, contextPrompt?: string): Promise<string> {
+    return this.chat([
+      { role: "system", content: contextPrompt || DEFAULT_AI_DOC_PROMPT },
+      { role: "user", content: fileContent },
+    ]);
+  }
+
+  async chat(messages: ChatMessage[]): Promise<string> {
+    const system = messages
+      .filter((m) => m.role === "system")
+      .map((m) => m.content)
+      .join("\n");
+    const aiMessages: AiMessage[] = messages
+      .filter((m) => m.role !== "system")
+      .map((m) => ({ role: m.role as AiMessage["role"], content: m.content }));
+
+    const config: ProviderConfig = {
+      providerId: this.providerId,
+      model: this.model,
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+    };
+    const response = await factory
+      .create(this.providerId)
+      .generate({ messages: aiMessages, system: system || undefined, maxTokens: 4000 }, config);
+    return response.text;
+  }
+}