@gitpagedocs/cli 0.0.1

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

@@ -0,0 +1,76 @@
+import { AI_MODEL_DEFAULTS, type AiProviderId } from "../../config";
+import type { AiCliConfig } from "./ai-cli-config";
+
+type SupportedLanguage = AiCliConfig["ai"]["languages"][number];
+
+const SUPPORTED_PROVIDERS: ReadonlySet<string> = new Set(Object.keys(AI_MODEL_DEFAULTS));
+const SUPPORTED_LANGUAGES: ReadonlySet<string> = new Set<SupportedLanguage>(["pt", "en", "es"]);
+
+/** Fallbacks for optional fields, mirroring the interactive prompt defaults. */
+const DEFAULT_LANGUAGES: AiCliConfig["ai"]["languages"] = ["en", "pt", "es"];
+const DEFAULT_OUTPUT_DIR = "gitpagedocs/docs";
+const DEFAULT_FILE_PREFIX = "ai-generated";
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return isString(value) ? value : undefined;
+}
+
+function asStringWithDefault(value: unknown, fallback: string): string {
+  return isString(value) ? value : fallback;
+}
+
+function asPaths(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter(isString) : [];
+}
+
+function asLanguages(value: unknown): AiCliConfig["ai"]["languages"] {
+  const languages = Array.isArray(value)
+    ? value.filter((language): language is SupportedLanguage => isString(language) && SUPPORTED_LANGUAGES.has(language))
+    : [];
+  return languages.length > 0 ? languages : [...DEFAULT_LANGUAGES];
+}
+
+function asProviderId(value: unknown): AiProviderId | null {
+  return isString(value) && SUPPORTED_PROVIDERS.has(value) ? (value as AiProviderId) : null;
+}
+
+/**
+ * Validate an untrusted `.gitpagedocsconfig` payload. Tolerant by design so
+ * hand-edited configs keep working: only the version-1 envelope and a known
+ * provider are required; every other field falls back to the interactive
+ * prompt defaults. Returns a sanitized {@link AiCliConfig} with only known
+ * fields, or `null` when the payload cannot identify a provider.
+ */
+export function parseAiCliConfig(raw: unknown): AiCliConfig | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const candidate = raw as Partial<AiCliConfig>;
+  if (candidate.version !== 1) return null;
+
+  const ai = candidate.ai;
+  if (typeof ai !== "object" || ai === null) return null;
+  const provider = asProviderId(ai.provider);
+  if (!provider) return null;
+
+  const model = asOptionalString(ai.model)?.trim() || AI_MODEL_DEFAULTS[provider];
+  const apiKey = asOptionalString(ai.apiKey);
+  const baseUrl = asOptionalString(ai.baseUrl);
+
+  return {
+    version: 1,
+    ai: {
+      provider,
+      model,
+      ...(apiKey !== undefined ? { apiKey } : {}),
+      ...(baseUrl !== undefined ? { baseUrl } : {}),
+      paths: asPaths(ai.paths),
+      languages: asLanguages(ai.languages),
+      outputDir: asStringWithDefault(ai.outputDir, DEFAULT_OUTPUT_DIR),
+      filePrefix: asStringWithDefault(ai.filePrefix, DEFAULT_FILE_PREFIX),
+      contextPrompt: asStringWithDefault(ai.contextPrompt, ""),
+    },
+  };
+}

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,101 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveUserConfigDir } from "@gitpagedocs/tools";
+import {
+  AI_CLI_CONFIG_FILENAME,
+  type AiCliConfig,
+} from "../core/models/ai-cli-config";
+import { parseAiCliConfig } from "../core/models/parse-ai-cli-config";
+
+/** Owner-only directory/file permissions (no-op on Windows, enforced on POSIX). */
+const CONFIG_DIR_MODE = 0o700;
+const CONFIG_FILE_MODE = 0o600;
+
+export interface AiConfigFileRepositoryOptions {
+  /** Working directory searched for a legacy `<cwd>/.gitpagedocsconfig`. */
+  cwd?: string;
+  /** Destination directory; defaults to the per-user OS config directory. */
+  configDir?: string;
+  /** Notified after a legacy config is moved into the user config directory. */
+  onMigrate?: (fromPath: string, toPath: string) => void;
+}
+
+/**
+ * Stores `.gitpagedocsconfig` in the per-user OS config directory
+ * (`%APPDATA%\gitpagedocs` on Windows, `~/Library/Application Support/gitpagedocs`
+ * on macOS, `$XDG_CONFIG_HOME/gitpagedocs` elsewhere) with owner-only
+ * permissions, so the API key never lives inside a repository checkout.
+ * A legacy `<cwd>/.gitpagedocsconfig` is migrated automatically on first read.
+ */
+export class AiConfigFileRepository {
+  private readonly cwd: string;
+  private readonly configDir: string;
+  private readonly onMigrate?: (fromPath: string, toPath: string) => void;
+
+  constructor(options: AiConfigFileRepositoryOptions = {}) {
+    this.cwd = options.cwd ?? process.cwd();
+    this.configDir = options.configDir ?? resolveUserConfigDir();
+    this.onMigrate = options.onMigrate;
+  }
+
+  getConfigPath(): string {
+    return path.join(this.configDir, AI_CLI_CONFIG_FILENAME);
+  }
+
+  getLegacyConfigPath(): string {
+    return path.join(this.cwd, AI_CLI_CONFIG_FILENAME);
+  }
+
+  async read(): Promise<AiCliConfig | null> {
+    const current = await this.readFrom(this.getConfigPath());
+    if (current) return current;
+    return this.migrateLegacyConfig();
+  }
+
+  /** Delete the stored configuration (secure and legacy locations), wiping
+   * any saved credentials. Returns the paths that were actually removed. */
+  async clear(): Promise<string[]> {
+    const removed: string[] = [];
+    const candidates = new Set([this.getConfigPath(), this.getLegacyConfigPath()].map((p) => path.resolve(p)));
+    for (const configPath of candidates) {
+      try {
+        await fs.rm(configPath);
+        removed.push(configPath);
+      } catch {
+        // Missing file: nothing to remove at this location.
+      }
+    }
+    return removed;
+  }
+
+  async write(config: AiCliConfig): Promise<void> {
+    const configPath = this.getConfigPath();
+    await fs.mkdir(path.dirname(configPath), { recursive: true, mode: CONFIG_DIR_MODE });
+    const data = `${JSON.stringify(config, null, 2)}\n`;
+    await fs.writeFile(configPath, data, { encoding: "utf-8", mode: CONFIG_FILE_MODE });
+  }
+
+  private async readFrom(configPath: string): Promise<AiCliConfig | null> {
+    try {
+      const content = await fs.readFile(configPath, "utf-8");
+      return parseAiCliConfig(JSON.parse(content));
+    } catch {
+      return null;
+    }
+  }
+
+  private async migrateLegacyConfig(): Promise<AiCliConfig | null> {
+    const legacyPath = this.getLegacyConfigPath();
+    if (path.resolve(legacyPath) === path.resolve(this.getConfigPath())) return null;
+    const legacy = await this.readFrom(legacyPath);
+    if (!legacy) return null;
+    try {
+      await this.write(legacy);
+      await fs.rm(legacyPath, { force: true });
+      this.onMigrate?.(legacyPath, this.getConfigPath());
+    } catch {
+      // Migration is best-effort: keep serving the legacy config on failure.
+    }
+    return legacy;
+  }
+}

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

@@ -0,0 +1,85 @@
+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 {
+    constructor(private readonly baseDir: string = process.cwd()) {}
+
+    splitExistingDirectories(targetDirectories: string[]): { existing: string[]; missing: string[] } {
+        const existing: string[] = [];
+        const missing: string[] = [];
+
+        for (const targetDirectory of targetDirectories) {
+            const absolutePath = path.resolve(this.baseDir, 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(this.baseDir, 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(this.baseDir, 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;
+  }
+}

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 };
+}