@gitpagedocs/tools 1.1.44

package/src/ai/providers/gemini-provider.ts

@@ -0,0 +1,84 @@
+import type {
+  AIProvider,
+  AiMessage,
+  AiProviderId,
+  GenerateRequest,
+  GenerateResponse,
+  ProviderCapabilities,
+  ProviderConfig,
+  StreamResponse,
+} from "../../ports/ai";
+import type { ProviderSpec } from "../catalog";
+import { type FetchLike, ensureOk, readSseData, resolveFetch } from "../http/streaming";
+import { collect, requireKey, resolveBaseUrl } from "./shared";
+
+/** Google Gemini streamGenerateContent adapter (SSE, API key in query). */
+export class GeminiProvider implements AIProvider {
+  readonly id: AiProviderId;
+  readonly capabilities: ProviderCapabilities;
+
+  constructor(
+    private readonly spec: ProviderSpec,
+    private readonly fetchImpl?: FetchLike,
+  ) {
+    this.id = spec.id;
+    this.capabilities = spec.capabilities;
+  }
+
+  private mapParts(msg: AiMessage): unknown[] {
+    const parts: unknown[] = [];
+    if (msg.content) parts.push({ text: msg.content });
+    for (const att of msg.attachments ?? []) {
+      parts.push({ inlineData: { mimeType: att.mimeType, data: att.data } });
+    }
+    return parts;
+  }
+
+  async *stream(request: GenerateRequest, config: ProviderConfig): AsyncGenerator<string> {
+    const fetchImpl = resolveFetch(this.fetchImpl);
+    requireKey(this.spec, config);
+    const base = resolveBaseUrl(this.spec, config);
+    const model = encodeURIComponent(config.model || this.spec.defaultModel);
+    const query = new URLSearchParams({ alt: "sse", key: config.apiKey as string });
+    const url = `${base}/${model}:streamGenerateContent?${query.toString()}`;
+
+    const contents = request.messages
+      .filter((m) => m.role !== "system")
+      .map((m) => ({ role: m.role === "assistant" ? "model" : "user", parts: this.mapParts(m) }));
+    const systemText =
+      request.system ??
+      request.messages
+        .filter((m) => m.role === "system")
+        .map((m) => m.content)
+        .join("\n");
+
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        contents,
+        systemInstruction: systemText ? { parts: [{ text: systemText }] } : undefined,
+        generationConfig: { temperature: request.temperature, maxOutputTokens: request.maxTokens },
+      }),
+      signal: request.signal,
+    });
+    const ok = await ensureOk(response, this.spec.label);
+    for await (const data of readSseData(ok.body as ReadableStream<Uint8Array>)) {
+      if (!data) continue;
+      try {
+        const parsed = JSON.parse(data) as {
+          candidates?: Array<{ content?: { parts?: Array<{ text?: string }> } }>;
+        };
+        const text = parsed.candidates?.[0]?.content?.parts?.map((p) => p.text ?? "").join("") ?? "";
+        if (text) yield text;
+      } catch {
+        /* ignore partial frames */
+      }
+    }
+  }
+
+  async generate(request: GenerateRequest, config: ProviderConfig): Promise<GenerateResponse> {
+    const text = await collect(this.stream(request, config) as StreamResponse);
+    return { text, model: config.model || this.spec.defaultModel };
+  }
+}

package/src/ai/providers/ollama-provider.ts

@@ -0,0 +1,69 @@
+import type {
+  AIProvider,
+  AiProviderId,
+  GenerateRequest,
+  GenerateResponse,
+  ProviderCapabilities,
+  ProviderConfig,
+  StreamResponse,
+} from "../../ports/ai";
+import type { ProviderSpec } from "../catalog";
+import { type FetchLike, ensureOk, readJsonLines, resolveFetch } from "../http/streaming";
+import { collect, resolveBaseUrl } from "./shared";
+
+/** Local Ollama /api/chat adapter (NDJSON streaming, no auth). */
+export class OllamaProvider implements AIProvider {
+  readonly id: AiProviderId;
+  readonly capabilities: ProviderCapabilities;
+
+  constructor(
+    private readonly spec: ProviderSpec,
+    private readonly fetchImpl?: FetchLike,
+  ) {
+    this.id = spec.id;
+    this.capabilities = spec.capabilities;
+  }
+
+  private endpoint(config: ProviderConfig): string {
+    const base = resolveBaseUrl(this.spec, config);
+    return /\/api\/chat\/?$/i.test(base) ? base.replace(/\/$/, "") : `${base}/api/chat`;
+  }
+
+  async *stream(request: GenerateRequest, config: ProviderConfig): AsyncGenerator<string> {
+    const fetchImpl = resolveFetch(this.fetchImpl);
+    const messages = request.messages.map((m) => {
+      const images = (m.attachments ?? []).filter((a) => a.kind === "image").map((a) => a.data);
+      return images.length > 0
+        ? { role: m.role, content: m.content, images }
+        : { role: m.role, content: m.content };
+    });
+    if (request.system) messages.unshift({ role: "system", content: request.system });
+
+    const response = await fetchImpl(this.endpoint(config), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: config.model || this.spec.defaultModel,
+        messages,
+        options: { temperature: request.temperature },
+        stream: true,
+      }),
+      signal: request.signal,
+    });
+    const ok = await ensureOk(response, this.spec.label);
+    for await (const line of readJsonLines(ok.body as ReadableStream<Uint8Array>)) {
+      try {
+        const parsed = JSON.parse(line) as { message?: { content?: string }; done?: boolean };
+        if (parsed.message?.content) yield parsed.message.content;
+        if (parsed.done) break;
+      } catch {
+        /* ignore partial frames */
+      }
+    }
+  }
+
+  async generate(request: GenerateRequest, config: ProviderConfig): Promise<GenerateResponse> {
+    const text = await collect(this.stream(request, config) as StreamResponse);
+    return { text, model: config.model || this.spec.defaultModel };
+  }
+}

package/src/ai/providers/openai-compatible-provider.ts

@@ -0,0 +1,75 @@
+import type {
+  AIProvider,
+  AiProviderId,
+  GenerateRequest,
+  GenerateResponse,
+  ProviderCapabilities,
+  ProviderConfig,
+  StreamResponse,
+} from "../../ports/ai";
+import type { ProviderSpec } from "../catalog";
+import { type FetchLike, ensureOk, readSseData, resolveFetch } from "../http/streaming";
+import { buildAuthHeaders, collect, resolveBaseUrl, toOpenAiMessages } from "./shared";
+
+/**
+ * Adapter for every OpenAI chat-completions-compatible provider: OpenAI,
+ * OpenRouter, Groq, Mistral, DeepSeek, Together, Fireworks, Perplexity, xAI and
+ * Azure OpenAI. One strategy, parameterized by the catalog spec.
+ */
+export class OpenAiCompatibleProvider implements AIProvider {
+  readonly id: AiProviderId;
+  readonly capabilities: ProviderCapabilities;
+
+  constructor(
+    private readonly spec: ProviderSpec,
+    private readonly fetchImpl?: FetchLike,
+  ) {
+    this.id = spec.id;
+    this.capabilities = spec.capabilities;
+  }
+
+  private endpoint(config: ProviderConfig): string {
+    const base = resolveBaseUrl(this.spec, config);
+    // Azure deployment URLs already include the full path via baseUrl.
+    if (this.spec.id === "azure-openai") return base;
+    return `${base}/chat/completions`;
+  }
+
+  private body(request: GenerateRequest, config: ProviderConfig, stream: boolean): string {
+    return JSON.stringify({
+      model: config.model || this.spec.defaultModel,
+      messages: toOpenAiMessages(request),
+      temperature: request.temperature,
+      max_tokens: request.maxTokens,
+      stream,
+    });
+  }
+
+  async *stream(request: GenerateRequest, config: ProviderConfig): AsyncGenerator<string> {
+    const fetchImpl = resolveFetch(this.fetchImpl);
+    const response = await fetchImpl(this.endpoint(config), {
+      method: "POST",
+      headers: buildAuthHeaders(this.spec, config),
+      body: this.body(request, config, true),
+      signal: request.signal,
+    });
+    const ok = await ensureOk(response, this.spec.label);
+    for await (const data of readSseData(ok.body as ReadableStream<Uint8Array>)) {
+      if (!data || data === "[DONE]") continue;
+      try {
+        const parsed = JSON.parse(data) as {
+          choices?: Array<{ delta?: { content?: string } }>;
+        };
+        const delta = parsed.choices?.[0]?.delta?.content;
+        if (delta) yield delta;
+      } catch {
+        /* ignore partial JSON frames */
+      }
+    }
+  }
+
+  async generate(request: GenerateRequest, config: ProviderConfig): Promise<GenerateResponse> {
+    const text = await collect(this.stream(request, config) as StreamResponse);
+    return { text, model: config.model || this.spec.defaultModel };
+  }
+}

package/src/ai/providers/shared.ts

@@ -0,0 +1,72 @@
+import type { AiMessage, GenerateRequest, ProviderConfig } from "../../ports/ai";
+import type { ProviderSpec } from "../catalog";
+import { ProviderError } from "../../errors/app-error";
+
+/** Build request auth headers from the provider's declared auth style. */
+export function buildAuthHeaders(spec: ProviderSpec, config: ProviderConfig): Record<string, string> {
+  const headers: Record<string, string> = { "Content-Type": "application/json", ...config.extraHeaders };
+  switch (spec.auth) {
+    case "bearer":
+      requireKey(spec, config);
+      headers.Authorization = `Bearer ${config.apiKey}`;
+      break;
+    case "x-api-key":
+      requireKey(spec, config);
+      headers["x-api-key"] = config.apiKey as string;
+      headers["anthropic-version"] = "2023-06-01";
+      // Required for direct browser calls (the docs run as a static site);
+      // ignored server-side. Without it Anthropic rejects the CORS preflight.
+      headers["anthropic-dangerous-direct-browser-access"] = "true";
+      break;
+    case "api-key-header":
+      requireKey(spec, config);
+      headers["api-key"] = config.apiKey as string;
+      break;
+    case "query-key":
+    case "none":
+      break;
+  }
+  return headers;
+}
+
+export function requireKey(spec: ProviderSpec, config: ProviderConfig): void {
+  if (!config.apiKey) {
+    throw new ProviderError(`${spec.label} requires an API key.`, { details: { provider: spec.id } });
+  }
+}
+
+export function resolveBaseUrl(spec: ProviderSpec, config: ProviderConfig): string {
+  const base = (config.baseUrl ?? spec.baseUrl).replace(/\/+$/, "");
+  if (spec.requiresBaseUrl && !config.baseUrl && !spec.baseUrl) {
+    throw new ProviderError(`${spec.label} requires a baseUrl.`, { details: { provider: spec.id } });
+  }
+  return base;
+}
+
+/** OpenAI chat-completions message shape (text + optional image parts). */
+export function toOpenAiMessages(request: GenerateRequest): unknown[] {
+  const out: unknown[] = [];
+  if (request.system) out.push({ role: "system", content: request.system });
+  for (const msg of request.messages) {
+    out.push(mapOpenAiMessage(msg));
+  }
+  return out;
+}
+
+function mapOpenAiMessage(msg: AiMessage): unknown {
+  const images = (msg.attachments ?? []).filter((a) => a.kind === "image");
+  if (images.length === 0) return { role: msg.role, content: msg.content };
+  const content: unknown[] = [];
+  if (msg.content) content.push({ type: "text", text: msg.content });
+  for (const img of images) {
+    content.push({ type: "image_url", image_url: { url: `data:${img.mimeType};base64,${img.data}` } });
+  }
+  return { role: msg.role, content };
+}
+
+/** Drain an async iterable of text deltas into a single string. */
+export async function collect(stream: AsyncIterable<string>): Promise<string> {
+  let text = "";
+  for await (const delta of stream) text += delta;
+  return text;
+}

package/src/ai/registry.ts

@@ -0,0 +1,29 @@
+import type { AiProviderId, ProviderRegistration, ProviderRegistry } from "../ports/ai";
+import { ProviderError } from "../errors/app-error";
+
+/** In-memory provider registry (Registry pattern). */
+export class InMemoryProviderRegistry implements ProviderRegistry {
+  private readonly registrations = new Map<AiProviderId, ProviderRegistration>();
+
+  register(registration: ProviderRegistration): void {
+    this.registrations.set(registration.id, registration);
+  }
+
+  has(id: AiProviderId): boolean {
+    return this.registrations.has(id);
+  }
+
+  get(id: AiProviderId): ProviderRegistration | undefined {
+    return this.registrations.get(id);
+  }
+
+  list(): readonly ProviderRegistration[] {
+    return [...this.registrations.values()];
+  }
+
+  require(id: AiProviderId): ProviderRegistration {
+    const found = this.registrations.get(id);
+    if (!found) throw new ProviderError(`Unknown AI provider: ${id}`, { details: { provider: id } });
+    return found;
+  }
+}

package/src/cache/file-cache.ts

@@ -0,0 +1,86 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type { Cache, CacheEntryOptions } from "../ports/cache";
+import { CacheError } from "../errors/app-error";
+
+interface PersistedEntry {
+  readonly value: unknown;
+  readonly expiresAt?: number;
+}
+
+type PersistedMap = Record<string, PersistedEntry>;
+
+/**
+ * JSON-file backed cache (Node). Suitable for CLI/MCP persistence across runs.
+ * One file holds the whole namespace; loaded lazily and written on mutation.
+ */
+export class FileCache<TValue = unknown> implements Cache<TValue> {
+  private cache?: PersistedMap;
+
+  constructor(
+    private readonly filePath: string,
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  private async load(): Promise<PersistedMap> {
+    if (this.cache) return this.cache;
+    if (!existsSync(this.filePath)) {
+      this.cache = {};
+      return this.cache;
+    }
+    try {
+      const raw = await readFile(this.filePath, "utf8");
+      this.cache = raw.trim() ? (JSON.parse(raw) as PersistedMap) : {};
+    } catch (cause) {
+      throw new CacheError(`Failed to read cache file: ${this.filePath}`, { cause });
+    }
+    return this.cache;
+  }
+
+  private async persist(): Promise<void> {
+    const dir = path.dirname(this.filePath);
+    if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+    await writeFile(this.filePath, JSON.stringify(this.cache ?? {}, null, 2), "utf8");
+  }
+
+  private isExpired(entry: PersistedEntry): boolean {
+    return entry.expiresAt !== undefined && entry.expiresAt <= this.now();
+  }
+
+  async get(key: string): Promise<TValue | undefined> {
+    const map = await this.load();
+    const entry = map[key];
+    if (!entry) return undefined;
+    if (this.isExpired(entry)) {
+      delete map[key];
+      await this.persist();
+      return undefined;
+    }
+    return entry.value as TValue;
+  }
+
+  async set(key: string, value: TValue, options?: CacheEntryOptions): Promise<void> {
+    const map = await this.load();
+    map[key] = {
+      value,
+      expiresAt: options?.ttlMs !== undefined ? this.now() + options.ttlMs : undefined,
+    };
+    await this.persist();
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== undefined;
+  }
+
+  async delete(key: string): Promise<void> {
+    const map = await this.load();
+    delete map[key];
+    await this.persist();
+  }
+
+  async clear(): Promise<void> {
+    this.cache = {};
+    await this.persist();
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,9 @@
+export { MemoryCache } from "./memory-cache";
+export type { Clock } from "./memory-cache";
+export { FileCache } from "./file-cache";
+export {
+  WebStorageCache,
+  createLocalStorageCache,
+  createSessionStorageCache,
+} from "./web-storage-cache";
+export type { WebStorageLike } from "./web-storage-cache";

package/src/cache/memory-cache.ts

@@ -0,0 +1,47 @@
+import type { Cache, CacheEntryOptions } from "../ports/cache";
+
+interface Entry<TValue> {
+  readonly value: TValue;
+  readonly expiresAt?: number;
+}
+
+/** Clock injection keeps the cache testable without Date.now() flakiness. */
+export type Clock = () => number;
+
+/** In-process cache with optional TTL. Default Strategy for hot, ephemeral data. */
+export class MemoryCache<TValue = unknown> implements Cache<TValue> {
+  private readonly store = new Map<string, Entry<TValue>>();
+
+  constructor(private readonly now: Clock = () => Date.now()) {}
+
+  private isExpired(entry: Entry<TValue>): boolean {
+    return entry.expiresAt !== undefined && entry.expiresAt <= this.now();
+  }
+
+  async get(key: string): Promise<TValue | undefined> {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (this.isExpired(entry)) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  async set(key: string, value: TValue, options?: CacheEntryOptions): Promise<void> {
+    const expiresAt = options?.ttlMs !== undefined ? this.now() + options.ttlMs : undefined;
+    this.store.set(key, { value, expiresAt });
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== undefined;
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+}

package/src/cache/web-storage-cache.ts

@@ -0,0 +1,91 @@
+import type { Cache, CacheEntryOptions } from "../ports/cache";
+
+/**
+ * Minimal subset of the Web Storage API. Injected so this module stays free of
+ * DOM lib types and works in the Node-typed tools package. The browser passes
+ * `window.localStorage` (→ LocalStorageCache) or `window.sessionStorage`
+ * (→ SessionStorageCache).
+ */
+export interface WebStorageLike {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+  key(index: number): string | null;
+  readonly length: number;
+}
+
+interface StoredEntry {
+  readonly value: unknown;
+  readonly expiresAt?: number;
+}
+
+/** Cache backed by a Web Storage-like store, namespaced by key prefix. */
+export class WebStorageCache<TValue = unknown> implements Cache<TValue> {
+  constructor(
+    private readonly storage: WebStorageLike,
+    private readonly prefix = "gpd:cache:",
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  private k(key: string): string {
+    return `${this.prefix}${key}`;
+  }
+
+  async get(key: string): Promise<TValue | undefined> {
+    const raw = this.storage.getItem(this.k(key));
+    if (raw === null) return undefined;
+    let entry: StoredEntry;
+    try {
+      entry = JSON.parse(raw) as StoredEntry;
+    } catch {
+      this.storage.removeItem(this.k(key));
+      return undefined;
+    }
+    if (entry.expiresAt !== undefined && entry.expiresAt <= this.now()) {
+      this.storage.removeItem(this.k(key));
+      return undefined;
+    }
+    return entry.value as TValue;
+  }
+
+  async set(key: string, value: TValue, options?: CacheEntryOptions): Promise<void> {
+    const entry: StoredEntry = {
+      value,
+      expiresAt: options?.ttlMs !== undefined ? this.now() + options.ttlMs : undefined,
+    };
+    this.storage.setItem(this.k(key), JSON.stringify(entry));
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.get(key)) !== undefined;
+  }
+
+  async delete(key: string): Promise<void> {
+    this.storage.removeItem(this.k(key));
+  }
+
+  async clear(): Promise<void> {
+    const toRemove: string[] = [];
+    for (let i = 0; i < this.storage.length; i += 1) {
+      const k = this.storage.key(i);
+      if (k && k.startsWith(this.prefix)) toRemove.push(k);
+    }
+    for (const k of toRemove) this.storage.removeItem(k);
+  }
+}
+
+/** localStorage-backed cache (persistent). */
+export function createLocalStorageCache<TValue = unknown>(
+  storage: WebStorageLike,
+  prefix?: string,
+): WebStorageCache<TValue> {
+  return new WebStorageCache<TValue>(storage, prefix ?? "gpd:local:");
+}
+
+/** sessionStorage-backed cache (per-session). */
+export function createSessionStorageCache<TValue = unknown>(
+  storage: WebStorageLike,
+  prefix?: string,
+): WebStorageCache<TValue> {
+  return new WebStorageCache<TValue>(storage, prefix ?? "gpd:session:");
+}

package/src/config/config-loader.ts

@@ -0,0 +1,59 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import type { ConfigExtension, ConfigLoader, LoadedConfig } from "../ports/config";
+import { CONFIG_BASE, CONFIG_EXTENSIONS } from "../constants/config";
+import { ConfigurationError } from "../errors/app-error";
+
+/**
+ * Node config loader for gitpagedocs/config.{json,js,ts}. Behaviour mirrors the
+ * frontend loader (src/entities/docs/api/io/config-loader.ts) so the contract
+ * is identical: JSON is parsed, JS/TS are dynamically imported (default export
+ * or module namespace).
+ */
+export class GitPageDocsConfigLoader implements ConfigLoader {
+  async resolveConfigPath(cwd: string = process.cwd()): Promise<string | undefined> {
+    const base = path.join(cwd, CONFIG_BASE);
+    for (const ext of CONFIG_EXTENSIONS) {
+      const fullPath = base + ext;
+      if (existsSync(fullPath)) return fullPath;
+    }
+    return undefined;
+  }
+
+  async loadGitPageDocsConfig<TConfig = Record<string, unknown>>(
+    cwd: string = process.cwd(),
+  ): Promise<LoadedConfig<TConfig>> {
+    const sourcePath = await this.resolveConfigPath(cwd);
+    if (!sourcePath) {
+      throw new ConfigurationError(
+        `No config file found. Expected one of: ${CONFIG_EXTENSIONS.map((e) => CONFIG_BASE + e).join(", ")}`,
+        { details: { cwd } },
+      );
+    }
+    const extension = path.extname(sourcePath) as ConfigExtension;
+    const config = await this.parse<TConfig>(sourcePath, extension);
+    return { config, sourcePath, extension };
+  }
+
+  private async parse<TConfig>(resolvedPath: string, ext: ConfigExtension): Promise<TConfig> {
+    if (ext === ".json") {
+      const text = await readFile(resolvedPath, "utf8");
+      return JSON.parse(text) as TConfig;
+    }
+    if (ext === ".js" || ext === ".ts") {
+      const mod = (await import(pathToFileURL(resolvedPath).href)) as Record<string, unknown>;
+      const value = (mod.default ?? mod) as TConfig | undefined;
+      if (value == null) {
+        throw new ConfigurationError(
+          `Config file ${resolvedPath} did not export default or module.exports.`,
+        );
+      }
+      return value;
+    }
+    throw new ConfigurationError(`Unsupported config extension: ${ext}`);
+  }
+}
+
+export const defaultConfigLoader = new GitPageDocsConfigLoader();

package/src/config/index.ts

@@ -0,0 +1 @@
+export { GitPageDocsConfigLoader, defaultConfigLoader } from "./config-loader";

package/src/constants/config.ts

@@ -0,0 +1,8 @@
+/**
+ * Config constants — mirror of src/shared/config/constants.ts so the shared
+ * core stays contract-compatible with the frontend's config loader.
+ */
+export const CONFIG_BASE = "gitpagedocs/config";
+export const CONFIG_EXTENSIONS = [".json", ".js", ".ts"] as const;
+export const DEFAULT_CONFIG_PATH = "gitpagedocs/config.json";
+export const DEFAULT_HIERARCHY = { md: 0, html: 1, video: 2, audio: 3 } as const;

package/src/constants/index.ts

@@ -0,0 +1 @@
+export * from "./config";

package/src/crypto/index.ts

@@ -0,0 +1,2 @@
+export { NodeCryptoService, safeHexEqual } from "./node-crypto-service";
+export { WebCryptoService } from "./web-crypto-service";