@gitpagedocs/cli 1.1.44

package/ai/presentation/ai-prompts.ts

@@ -0,0 +1,239 @@
+import {
+    AI_MODEL_DEFAULTS,
+    OLLAMA_DEFAULT_BASE_URL,
+    type AiProviderId,
+} from '../config';
+import { PROVIDER_CATALOG, legacyProviderToCatalogId } from '@gitpagedocs/tools/ai';
+import type { AiCliConfig, AiCliRunPlan } from '../core/models/ai-cli-config';
+import {
+    askText,
+    askConfirm,
+    askSelect,
+    askMultiSelect,
+    intro,
+} from '../../presentation/ui/clack';
+
+export interface InteractiveCliAnswers {
+    provider: AiProviderId;
+    apiKeyOrHost: string;
+    model: string;
+    targetDirs: string[];
+    languages: Array<'pt' | 'en' | 'es'>;
+    outputDir: string;
+    filePrefix: string;
+    saveConfig: boolean;
+    runConfigScaffold: boolean;
+    contextPrompt: string;
+}
+
+function parseCommaSeparated(value: string): string[] {
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+
+function validateCommaSeparatedDirectories(value: string): string | undefined {
+    const values = parseCommaSeparated(value);
+    if (!values.length) return 'Provide at least one path.';
+    return undefined;
+}
+
+const CUSTOM_MODEL = '__custom_model__';
+
+/**
+ * Ask for the model as a SELECT of the provider's real catalog models (with the
+ * default marked), plus a "Custom" escape hatch — so an invalid id like "4.8"
+ * can't be typed by mistake and rejected later as a 404 by the provider.
+ */
+async function askModel(provider: AiProviderId): Promise<string> {
+    const catalogId = legacyProviderToCatalogId(provider);
+    const spec = catalogId ? PROVIDER_CATALOG[catalogId] : undefined;
+    const fallback = AI_MODEL_DEFAULTS[provider] || '';
+
+    if (!spec || spec.models.length === 0) {
+        return String(await askText({ message: 'Which model do you want to use?', defaultValue: fallback }));
+    }
+
+    const picked = await askSelect<string>(
+        'Which model do you want to use?',
+        [
+            ...spec.models.map((m) => ({
+                value: m.id,
+                label: m.id === spec.defaultModel ? `${m.id} (default)` : m.id,
+            })),
+            { value: CUSTOM_MODEL, label: 'Custom — enter a model id manually' },
+        ],
+        spec.defaultModel,
+    );
+
+    if (picked !== CUSTOM_MODEL) return picked;
+
+    return String(
+        await askText({
+            message: 'Enter the model id:',
+            defaultValue: spec.defaultModel,
+            validate: (value) => (value.trim() ? undefined : 'Provide a model id'),
+        }),
+    );
+}
+
+function toPlan(answers: InteractiveCliAnswers): AiCliRunPlan {
+    const config: AiCliConfig = {
+        version: 1,
+        ai: {
+            provider: answers.provider,
+            model: answers.model,
+            apiKey: answers.provider === 'ollama' ? undefined : answers.apiKeyOrHost,
+            baseUrl: answers.provider === 'ollama' ? answers.apiKeyOrHost : undefined,
+            paths: answers.targetDirs,
+            languages: answers.languages,
+            outputDir: answers.outputDir,
+            filePrefix: answers.filePrefix,
+            contextPrompt: answers.contextPrompt,
+        },
+    };
+
+    return {
+        config,
+        saveConfig: answers.saveConfig,
+        runConfigScaffold: answers.runConfigScaffold,
+    };
+}
+
+export async function promptMissingDirectories(
+    missingDirectories: string[],
+): Promise<{ replacementPaths: string[]; abort: boolean }> {
+    const recoveryMode = await askSelect(
+        `I couldn't find ${missingDirectories.length} directory(ies): ${missingDirectories.join(', ')}`,
+        [
+            { value: 'fix', label: 'Fix paths now (recommended)' },
+            { value: 'skip', label: 'Skip missing paths and continue' },
+            { value: 'abort', label: 'Abort execution' },
+        ],
+        'fix',
+    );
+
+    if (recoveryMode === 'abort') {
+        return { replacementPaths: [], abort: true };
+    }
+    if (recoveryMode === 'skip') {
+        return { replacementPaths: [], abort: false };
+    }
+
+    const fixedPaths = await askText({
+        message: 'Enter new paths (comma-separated):',
+        validate: validateCommaSeparatedDirectories,
+    });
+
+    return {
+        replacementPaths: parseCommaSeparated(String(fixedPaths || '')),
+        abort: false,
+    };
+}
+
+export async function promptUseExistingConfig(existingConfig: AiCliConfig): Promise<AiCliRunPlan | null> {
+    const useExistingConfig = await askConfirm(
+        'Found .gitpagedocsconfig. Do you want to use this configuration?',
+        true,
+    );
+
+    if (!useExistingConfig) return null;
+
+    const runConfigScaffold = await askConfirm(
+        'After generating docs with AI, run the default gitpagedocs scaffolding?',
+        true,
+    );
+
+    return {
+        config: existingConfig,
+        saveConfig: false,
+        runConfigScaffold,
+    };
+}
+
+export async function runAiInteractivePrompt(existingConfig?: AiCliConfig | null): Promise<AiCliRunPlan> {
+    intro('🤖  GitPageDocs AI CLI — interactive mode 🤖');
+
+    if (existingConfig) {
+        const existingPlan = await promptUseExistingConfig(existingConfig);
+        if (existingPlan) return existingPlan;
+    }
+
+    const provider = await askSelect<AiProviderId>(
+        'Which AI provider should be used to generate documentation?',
+        [
+            { value: 'openai', label: 'OpenAI (GPT)' },
+            { value: 'claude', label: 'Anthropic (Claude)' },
+            { value: 'gemini', label: 'Google Gemini' },
+            { value: 'ollama', label: 'Ollama (Local Open Source)' },
+        ],
+        'openai',
+    );
+
+    const apiKeyOrHost = await askText({
+        message: provider === 'ollama' ? 'Ollama host URL:' : 'Provider API key:',
+        defaultValue: provider === 'ollama' ? OLLAMA_DEFAULT_BASE_URL : undefined,
+        validate: (input) => (input.length > 0 ? undefined : 'Required field'),
+    });
+
+    const model = await askModel(provider);
+
+    const targetDirsRaw = await askText({
+        message:
+            'Paths to analyze (comma-separated). You can include multiple repositories (e.g., src,cli,../other-repo/src):',
+        defaultValue: 'src,cli',
+        validate: validateCommaSeparatedDirectories,
+    });
+
+    const languages = await askMultiSelect<'en' | 'pt' | 'es'>(
+        'Documentation languages to generate:',
+        [
+            { value: 'en', label: 'English (en)' },
+            { value: 'pt', label: 'Portuguese (pt)' },
+            { value: 'es', label: 'Español (es)' },
+        ],
+        ['en', 'pt', 'es'],
+    );
+
+    const outputDir = await askText({
+        message: 'Output directory for generated markdown files:',
+        defaultValue: 'gitpagedocs/docs',
+        validate: (value) => (value.trim() ? undefined : 'Provide an output directory'),
+    });
+
+    const filePrefix = await askText({
+        message: 'Output file prefix:',
+        defaultValue: 'ai-generated',
+        validate: (value) => (value.trim() ? undefined : 'Provide a prefix'),
+    });
+
+    const contextPrompt = await askText({
+        message: 'Extra instructions for AI (optional):',
+        defaultValue:
+            'You are a senior technical writer. Generate professional, clear documentation with architectural insight following FSD, SOLID, and Clean Code principles.',
+    });
+
+    const saveConfig = await askConfirm(
+        'Save this configuration to .gitpagedocsconfig for future manual use?',
+        true,
+    );
+
+    const runConfigScaffold = await askConfirm(
+        'After generating docs with AI, run the default gitpagedocs scaffolding?',
+        true,
+    );
+
+    return toPlan({
+        provider,
+        apiKeyOrHost,
+        model,
+        targetDirs: parseCommaSeparated(targetDirsRaw),
+        languages,
+        outputDir,
+        filePrefix,
+        contextPrompt,
+        saveConfig,
+        runConfigScaffold,
+    });
+}

package/application/config-only/handler.mjs

@@ -0,0 +1,55 @@
+/** Config-only use case - orchestrates build, write, and optional push */
+
+import { sanitizeSegment } from "../../domain/services/sanitize-segment.mjs";
+import { reportAll } from "../report/config-only-reporter.mjs";
+
+/**
+ * Execute config-only use case
+ * @param {Object} params
+ * @param {Object} params.options - Parsed CLI options
+ * @param {string} params.root - Project root
+ * @param {string} params.pkgRoot - Package root
+ * @param {string} params.prebuiltDir - Prebuilt directory path
+ * @param {Function} params.buildConfigArtifacts - Artifact builder
+ * @param {Function} params.createThemeTemplate - Theme template creator
+ * @param {Array} params.layouts - Layout definitions
+ * @param {import("../ports/cli-runtime-ports").ConfigOnlyRuntimePort} runtime
+ */
+export async function executeConfigOnly(params, runtime) {
+  if (!runtime) {
+    throw new Error("Config-only runtime is required.");
+  }
+
+  const { options, root, pkgRoot, prebuiltDir, buildConfigArtifacts, createThemeTemplate, layouts } = params;
+
+  const artifacts = buildConfigArtifacts({
+    useLocalLayoutConfig: options.useLocalLayoutConfig,
+    githubOwner: sanitizeSegment(options.githubOwner),
+    githubRepo: sanitizeSegment(options.githubRepo),
+    root,
+  });
+
+  await runtime.writeConfigOnlyOutput({
+    root,
+    pkgRoot,
+    outputDir: options.outputDir,
+    artifacts,
+    useLocalLayoutConfig: options.useLocalLayoutConfig,
+    layouts,
+    createThemeTemplate,
+  });
+
+  if (options.shouldPush) {
+    await runtime.ensureGitHubPagesWorkflow(
+      () => runtime.getCurrentGitBranch(root),
+      (relativePath, content) => runtime.writeText(root, relativePath, content),
+      options.docsPath || "",
+    );
+    runtime.runGitPushForGeneratedArtifacts(options, root, sanitizeSegment);
+  }
+
+  const reportLines = reportAll(options, runtime.hasPath(prebuiltDir));
+  for (const line of reportLines) {
+    runtime.logInfo(line);
+  }
+}

package/application/home/handler.mjs

@@ -0,0 +1,83 @@
+/** Home distribution use case - static site + auxiliary files */
+
+import { STATIC_OUTPUT_DIR, ARTIFACTS_DIR } from "../../home/constants.mjs";
+
+/**
+ * Execute home distribution use case
+ * @param {Object} params
+ * @param {Object} params.options - Parsed CLI options
+ * @param {string} params.root - Project root
+ * @param {string} params.pkgRoot - Package root
+ * @param {Function} params.buildConfigArtifacts - Artifact builder
+ * @param {Function} params.createThemeTemplate - Theme template creator
+ * @param {Array} params.layouts - Layout definitions
+ * @param {import("../ports/cli-runtime-ports").HomeRuntimePort} runtime
+ */
+export async function executeHome(params, runtime) {
+  if (!runtime) {
+    throw new Error("Home runtime is required.");
+  }
+
+  const { options, root, pkgRoot, buildConfigArtifacts, createThemeTemplate, layouts } = params;
+  const outputDir = options.outputDir || "gitpagedocshome";
+  const repositorySearch = options.repositorySearch ?? false;
+  const basePath = options.basePath ?? "";
+
+  const isCurrentDir = outputDir === "." || outputDir === "./";
+  const targetDir = isCurrentDir ? root : runtime.joinPath(root, outputDir);
+
+  if (!isCurrentDir) {
+    runtime.ensureDirEmpty(root, outputDir);
+  }
+
+  const pathSegment = basePath ? basePath.replace(/^\/+|\/+$/g, "") : "";
+  const buildEnv = {
+    ...process.env,
+    GITHUB_ACTIONS: "true",
+    GITPAGEDOCS_REPOSITORY_SEARCH: String(repositorySearch),
+    GITPAGEDOCS_BASE_PATH: pathSegment ? `/${pathSegment}` : "/",
+    GITPAGEDOCS_PATH: pathSegment,
+  };
+
+  const artifacts = buildConfigArtifacts({
+    useLocalLayoutConfig: false,
+    githubOwner: "",
+    githubRepo: "",
+    root,
+  });
+
+  await runtime.writeConfigOnlyOutput({
+    root,
+    pkgRoot,
+    outputDir: ARTIFACTS_DIR,
+    artifacts,
+    useLocalLayoutConfig: false,
+    layouts,
+    createThemeTemplate,
+  });
+
+  runtime.runNextBuild(root, buildEnv);
+
+  const outPath = runtime.joinPath(root, STATIC_OUTPUT_DIR);
+  if (!runtime.existsPath(outPath)) {
+    throw new Error(`Static export not found at ${STATIC_OUTPUT_DIR}/. Ensure next.config exports when GITHUB_ACTIONS=true.`);
+  }
+
+  const destBase = isCurrentDir ? root : targetDir;
+  if (isCurrentDir) {
+    for (const name of runtime.readDirNames(outPath)) {
+      runtime.copyRecursive(runtime.joinPath(outPath, name), runtime.joinPath(destBase, name));
+    }
+  } else {
+    runtime.copyRecursive(outPath, destBase);
+  }
+  runtime.copyRecursive(runtime.joinPath(root, ARTIFACTS_DIR), runtime.joinPath(destBase, ARTIFACTS_DIR));
+
+  await runtime.writeHomeFiles(root, isCurrentDir ? "." : outputDir, { repositorySearch, basePath });
+  await runtime.writeText(root, (isCurrentDir ? "" : outputDir + "/") + ".nojekyll", "");
+
+  const cdDir = isCurrentDir ? "." : outputDir;
+  runtime.logSuccess(`Generated: ${cdDir}/ (static site + .env + Dockerfile + README.md)`);
+  runtime.logInfo(`Serve: cd ${cdDir} && npx serve .`);
+  runtime.logInfo(`Docker: cd ${cdDir} && docker build -t gitpagedocshome . && docker run -p 3000:80 gitpagedocshome`);
+}

package/application/ports/cli-runtime-ports.ts

@@ -0,0 +1,87 @@
+import type { CliOptions } from "../../domain/models/cli-options";
+
+export interface BuildArtifactsInput {
+  useLocalLayoutConfig: boolean;
+  githubOwner: string;
+  githubRepo: string;
+  root: string;
+}
+
+export interface LayoutDefinition {
+  file: string;
+  [key: string]: unknown;
+}
+
+export interface BuiltConfigArtifacts {
+  rootConfig: unknown;
+  layoutsConfig: unknown;
+  fallbackLayoutsConfig: unknown;
+  docs?: Record<string, Record<string, string>>;
+  docsHtml?: Record<string, Record<string, string>>;
+  versionConfigs: Record<string, Record<string, unknown>>;
+}
+
+export interface CliRuntimeParams {
+  root: string;
+  pkgRoot: string;
+  prebuiltDir: string;
+  buildConfigArtifacts: (input: BuildArtifactsInput) => BuiltConfigArtifacts;
+  createThemeTemplate: (layout: LayoutDefinition) => unknown;
+  layouts: LayoutDefinition[];
+}
+
+export interface CliCommandContext extends CliRuntimeParams {
+  options: CliOptions;
+}
+
+export interface CliCommandRunner {
+  runConfigOnly: (params: CliCommandContext) => Promise<void>;
+  runHome: (params: CliCommandContext) => Promise<void>;
+  runAi: (params: CliCommandContext) => Promise<void>;
+}
+
+export interface ConfigOnlyOutputInput {
+  root: string;
+  pkgRoot: string;
+  outputDir: string;
+  artifacts: BuiltConfigArtifacts;
+  useLocalLayoutConfig: boolean;
+  layouts: LayoutDefinition[];
+  createThemeTemplate: (layout: LayoutDefinition) => unknown;
+}
+
+export interface ConfigOnlyRuntimePort {
+  hasPath: (absolutePath: string) => boolean;
+  writeConfigOnlyOutput: (input: ConfigOnlyOutputInput) => Promise<void>;
+  writeText: (root: string, relativePath: string, data: string) => Promise<void>;
+  ensureGitHubPagesWorkflow: (
+    getCurrentGitBranch: () => string,
+    writeText: (relativePath: string, content: string) => Promise<void>,
+    docsPath?: string,
+  ) => Promise<void>;
+  getCurrentGitBranch: (root: string) => string;
+  runGitPushForGeneratedArtifacts: (
+    options: CliOptions,
+    root: string,
+    sanitizeSegment: (value: string | undefined | null) => string,
+  ) => void;
+  logInfo: (message: string) => void;
+}
+
+export interface HomeRuntimePort {
+  joinPath: (...parts: string[]) => string;
+  ensureDirEmpty: (root: string, relativeDir: string) => void;
+  copyRecursive: (src: string, dest: string) => void;
+  readDirNames: (absolutePath: string) => string[];
+  existsPath: (absolutePath: string) => boolean;
+  runNextBuild: (root: string, env: NodeJS.ProcessEnv) => void;
+  writeConfigOnlyOutput: (input: ConfigOnlyOutputInput) => Promise<void>;
+  writeHomeFiles: (
+    root: string,
+    outputDir: string,
+    options: { repositorySearch?: boolean; basePath?: string },
+  ) => Promise<void>;
+  writeText: (root: string, relativePath: string, data: string) => Promise<void>;
+  logSuccess: (message: string) => void;
+  logInfo: (message: string) => void;
+}

package/application/report/config-only-reporter.mjs

@@ -0,0 +1,62 @@
+/** Config-only command output messages - SRP: single place for all report messages */
+
+export function reportConfigOnlySuccess(options) {
+  return [`Generated: ${options.outputDir}/ (config-only)`, "No index.html/index.js generated."];
+}
+
+export function reportLayoutConfig(options) {
+  if (options.useLocalLayoutConfig) {
+    return ["Local layouts generated in gitpagedocs/layouts/ (--layoutconfig)."];
+  } else {
+    return ["Using official remote layouts config by default (no local gitpagedocs/layouts generated)."];
+  }
+}
+
+export function reportRenderingUrl(options) {
+  if (options.githubOwner && options.githubRepo) {
+    return [
+      `Configured rendering URL: https://${options.githubOwner}.github.io/${options.githubRepo}/`,
+      `Official viewer remains available: https://vidigal-code.github.io/git-page-docs/${options.githubOwner}/${options.githubRepo}?modetheme=light&lang=pt`,
+    ];
+  }
+  return [];
+}
+
+export function reportPushMode() {
+  return [
+    "Generated: .github/workflows/gitpagedocs-pages.yml",
+    "Push mode enabled: committed and pushed gitpagedocs/ + workflow to origin.",
+  ];
+}
+
+export function reportBuildFlag() {
+  return ["`--build` keeps compatibility flag but output remains gitpagedocs/."];
+}
+
+export function reportFullOrServeSkipped() {
+  return ["External commands were skipped (no prebuilt copy and no local serve spawn)."];
+}
+
+export function reportPrebuiltDetected() {
+  return ["`prebuilt/` detected, but ignored by config-only generator."];
+}
+
+export function reportAll(options, prebuiltDetected) {
+  const lines = [];
+  lines.push(...reportConfigOnlySuccess(options));
+  lines.push(...reportLayoutConfig(options));
+  lines.push(...reportRenderingUrl(options));
+  if (options.shouldPush) {
+    lines.push(...reportPushMode());
+  }
+  if (options.isBuild) {
+    lines.push(...reportBuildFlag());
+  }
+  if (options.mode === "full" || options.isServe) {
+    lines.push(...reportFullOrServeSkipped());
+  }
+  if (prebuiltDetected) {
+    lines.push(...reportPrebuiltDetected());
+  }
+  return lines;
+}

package/application/use-cases/dispatch-mode.ts

@@ -0,0 +1,18 @@
+import type { CliOptions } from "../../domain/models/cli-options";
+import type { CliCommandRunner, CliRuntimeParams } from "../ports/cli-runtime-ports";
+
+export async function dispatchMode(
+  options: CliOptions,
+  params: CliRuntimeParams,
+  runner: CliCommandRunner,
+): Promise<void> {
+  if (options.mode === "ai") {
+    await runner.runAi({ ...params, options });
+    return;
+  }
+  if (options.mode === "home") {
+    await runner.runHome({ ...params, options });
+    return;
+  }
+  await runner.runConfigOnly({ ...params, options });
+}

package/builders/config-orchestrator.mjs

@@ -0,0 +1,40 @@
+/** Orchestrate build of config artifacts for gitpagedocs */
+
+import { LAYOUTS, FALLBACK_LAYOUTS } from "../data/layouts.mjs";
+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).
+ * @param {object} options - { useLocalLayoutConfig, githubOwner, githubRepo, root }
+ * @returns {object} { rootConfig, layoutsConfig, fallbackLayoutsConfig, docs, docsHtml, versionConfigs }
+ */
+export function buildConfigArtifacts(options = {}) {
+  const root = options.root ?? process.cwd();
+
+  const rootConfig = buildRootConfig(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);
+  }
+
+  return {
+    rootConfig,
+    layoutsConfig,
+    fallbackLayoutsConfig,
+    docs: DOCS,
+    docsHtml,
+    versionConfigs,
+  };
+}

package/builders/root-config-builder.mjs

@@ -0,0 +1,54 @@
+/** Build root config for gitpagedocs */
+import { OFFICIAL_LAYOUTS_CONFIG_URL, OFFICIAL_LAYOUTS_TEMPLATES_URL } from "../data/urls.mjs";
+import { DOCS } from "../content/docs.mjs";
+import { DOC_VERSIONS } from "../data/version-constants.mjs";
+import { defaultLangMenu } from "../data/i18n-langmenu.mjs";
+import { defaultTranslations } from "../data/i18n-translations.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 = githubOwner && githubRepo ? false : 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 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: "",
+  }));
+
+  const baseSiteConfig = getDefaultSiteConfig(DOCS, projectLink);
+
+  return {
+    site: {
+      ...baseSiteConfig,
+      layoutsConfigPathOficial: useOfficialLayouts,
+      layoutsConfigPathTemplatesOficial: useOfficialLayouts ? OFFICIAL_LAYOUTS_TEMPLATES_URL : "",
+      layoutsConfigPathOficialUrl: useOfficialLayouts ? OFFICIAL_LAYOUTS_CONFIG_URL : "",
+      repositorySearchHome,
+      rendering: renderingUrl,
+      AiChatEnabled: true,
+      langmenu: defaultLangMenu,
+    },
+    VersionControl: {
+      versions: versionEntries,
+    },
+    translations: defaultTranslations,
+  };
+}