@gitpagedocs/cli 1.1.61 → 1.1.63

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

@@ -1,167 +1,167 @@
-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";
-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",
-  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;
-  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(
-  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,
-  };
-}
-
-/** Factory seam so tests can inject a deterministic provider (DIP). */
-export type AiProviderFactory = typeof createAiProvider;
-
-export async function executeAiRunPlan(
-  plan: AiCliRunPlan,
-  cwd: string,
-  createProvider: AiProviderFactory = createAiProvider,
-): Promise<AiCliRunSummary> {
-  const provider = createProvider({
-    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(cwd);
-
-  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 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);
-    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: 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({
-    cwd: options.cwd,
-    onMigrate: (fromPath, toPath) =>
-      logInfo(`[gitpagedocs:ai] Moved configuration from ${fromPath} to ${toPath} (secure user config directory).`),
-  });
-
-  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()}`);
-  }
-
-  // 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 executeAiRunPlan(plan, options.cwd);
-  return {
-    summary,
-    runConfigScaffold: plan.runConfigScaffold,
-  };
-}
+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";
+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",
+  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;
+  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(
+  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,
+  };
+}
+
+/** Factory seam so tests can inject a deterministic provider (DIP). */
+export type AiProviderFactory = typeof createAiProvider;
+
+export async function executeAiRunPlan(
+  plan: AiCliRunPlan,
+  cwd: string,
+  createProvider: AiProviderFactory = createAiProvider,
+): Promise<AiCliRunSummary> {
+  const provider = createProvider({
+    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(cwd);
+
+  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 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);
+    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: 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({
+    cwd: options.cwd,
+    onMigrate: (fromPath, toPath) =>
+      logInfo(`[gitpagedocs:ai] Moved configuration from ${fromPath} to ${toPath} (secure user config directory).`),
+  });
+
+  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()}`);
+  }
+
+  // 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 executeAiRunPlan(plan, options.cwd);
+  return {
+    summary,
+    runConfigScaffold: plan.runConfigScaffold,
+  };
+}

package/ai/config.ts

@@ -1,50 +1,50 @@
-/**
- * @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.';
-
-/**
- * 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';
+/**
+ * @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.';
+
+/**
+ * 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

@@ -1,33 +1,33 @@
-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[];
-  /** Slugs of the gitpagedocs pages wired into the version config (if any). */
-  pages?: string[];
-}
+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[];
+  /** Slugs of the gitpagedocs pages wired into the version config (if any). */
+  pages?: string[];
+}

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

@@ -1,78 +1,78 @@
-import { AI_MODEL_DEFAULTS, type AiProviderId } from "../../config";
-import type { AiCliConfig } from "./ai-cli-config";
-
-const SUPPORTED_PROVIDERS = Object.keys(AI_MODEL_DEFAULTS) as AiProviderId[];
-const SUPPORTED_LANGUAGES: ReadonlyArray<AiCliConfig["ai"]["languages"][number]> = ["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 AiCliConfig["ai"]["languages"][number] =>
-        SUPPORTED_LANGUAGES.includes(language as AiCliConfig["ai"]["languages"][number]),
-      )
-    : [];
-  return languages.length > 0 ? languages : [...DEFAULT_LANGUAGES];
-}
-
-function asProviderId(value: unknown): AiProviderId | null {
-  return isString(value) && SUPPORTED_PROVIDERS.includes(value as AiProviderId)
-    ? (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, ""),
-    },
-  };
-}
+import { AI_MODEL_DEFAULTS, type AiProviderId } from "../../config";
+import type { AiCliConfig } from "./ai-cli-config";
+
+const SUPPORTED_PROVIDERS = Object.keys(AI_MODEL_DEFAULTS) as AiProviderId[];
+const SUPPORTED_LANGUAGES: ReadonlyArray<AiCliConfig["ai"]["languages"][number]> = ["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 AiCliConfig["ai"]["languages"][number] =>
+        SUPPORTED_LANGUAGES.includes(language as AiCliConfig["ai"]["languages"][number]),
+      )
+    : [];
+  return languages.length > 0 ? languages : [...DEFAULT_LANGUAGES];
+}
+
+function asProviderId(value: unknown): AiProviderId | null {
+  return isString(value) && SUPPORTED_PROVIDERS.includes(value as AiProviderId)
+    ? (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, ""),
+    },
+  };
+}