@dominikcz/greg 0.9.27

package/src/lib/MarkdownDocs/aiServer.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * Greg standalone AI server — for production deployments.
+ *
+ * Reads a pre-built search-index.json, builds the RAG pipeline, then serves:
+ *   POST /api/ai/ask          — ask a question, receive answer + source links
+ *   GET  /api/ai/characters   — list available AI personas
+ *
+ * Usage:
+ *   node src/lib/MarkdownDocs/aiServer.js [options]
+ *   greg ai-server                                  (via CLI)
+ *
+ * Options (CLI flags or environment variables):
+ *   --index       PATH    Path to search-index.json  (GREG_AI_INDEX,       default: dist/search-index.json)
+ *   --port        NUMBER  HTTP port                  (GREG_AI_PORT,        default: 3200)
+ *   --host        ADDR    Bind address               (GREG_AI_HOST,        default: localhost)
+ *   --url         PATH    API base URL path          (GREG_AI_URL,         default: /api/ai)
+ *   --provider    NAME    LLM provider               (GREG_AI_PROVIDER,    default: ollama)
+ *   --model       NAME    LLM model name             (GREG_AI_MODEL)
+ *   --ollama-url  URL     Ollama base URL            (GREG_AI_OLLAMA_URL,  default: http://localhost:11434)
+ *   --cors-origin VALUE   CORS allowed origin        (GREG_AI_CORS_ORIGIN, default: *)
+ *   --cors-methods VALUE  CORS allowed methods       (GREG_AI_CORS_METHODS,  default: GET, POST, OPTIONS)
+ *   --cors-headers VALUE  CORS allowed headers       (GREG_AI_CORS_HEADERS,  default: Content-Type)
+ *   --cors-max-age VALUE  CORS preflight cache secs  (GREG_AI_CORS_MAX_AGE,  default: 86400)
+ *
+ * Example — run after `greg build`:
+ *   greg ai-server --index dist/search-index.json --provider ollama --model llama3.2
+ *
+ * Then set search.ai.serverUrl in greg.config.js → 'http://localhost:3200/api/ai'
+ * (or configure a reverse proxy).
+ */
+
+import { createServer } from 'node:http';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildChunks } from './ai/chunker.js';
+import { MemoryStore } from './ai/stores/memoryStore.js';
+import { resolveCharacters } from './ai/characters.js';
+import { RagPipeline } from './ai/ragPipeline.js';
+import { loadGregConfig } from './loadGregConfig.js';
+
+/** @param {string} storeType @param {object} aiCfg @param {import('./ai/aiProvider.js').AiProvider} [provider] */
+async function createStore(storeType, aiCfg, provider) {
+	if (storeType === 'sqlite') {
+		const { SqliteStore } = await import('./ai/stores/sqliteStore.js');
+		const sqliteCfg = aiCfg?.sqlite ?? {};
+		return new SqliteStore({
+			dbPath: sqliteCfg.dbPath ?? 'docs.db',
+			embeddingDimensions: sqliteCfg.embeddingDimensions ?? 0,
+			provider: sqliteCfg.embeddingDimensions ? provider : undefined,
+			embeddingBatchSize: sqliteCfg.embeddingBatchSize,
+			bm25Weight: sqliteCfg.bm25Weight,
+		});
+	}
+	return new MemoryStore();
+}
+
+const startupT0 = process.hrtime.bigint();
+
+function msSince(t0) {
+	return Number(process.hrtime.bigint() - t0) / 1e6;
+}
+
+function fmtMs(ms) {
+	return `${ms.toFixed(1)}ms`;
+}
+
+// ── CLI argument parser ───────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+	const args = {};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a.startsWith('--') && i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+			args[a.slice(2)] = argv[i + 1];
+			i++;
+		} else if (a.startsWith('--')) {
+			args[a.slice(2)] = true;
+		}
+	}
+	return args;
+}
+
+// ── Resolve configuration ─────────────────────────────────────────────────────
+
+const cliArgs = parseArgs(process.argv.slice(2));
+const gregConfig = await loadGregConfig();
+const aiConfig = gregConfig?.search?.ai ?? {};
+
+const port = parseInt(cliArgs.port ?? process.env.GREG_AI_PORT ?? '3200', 10);
+const host = String(cliArgs.host ?? process.env.GREG_AI_HOST ?? 'localhost');
+const url = String(cliArgs.url ?? process.env.GREG_AI_URL ?? '/api/ai');
+const index = resolve(String(cliArgs.index ?? process.env.GREG_AI_INDEX ?? 'dist/search-index.json'));
+const providerType = String(cliArgs.provider ?? process.env.GREG_AI_PROVIDER ?? aiConfig?.provider ?? 'ollama');
+const corsOrigin = String(cliArgs['cors-origin'] ?? process.env.GREG_AI_CORS_ORIGIN ?? '*');
+const corsMethods = String(cliArgs['cors-methods'] ?? process.env.GREG_AI_CORS_METHODS ?? 'GET, POST, OPTIONS');
+const corsHeaders = String(cliArgs['cors-headers'] ?? process.env.GREG_AI_CORS_HEADERS ?? 'Content-Type');
+const corsMaxAge = String(cliArgs['cors-max-age'] ?? process.env.GREG_AI_CORS_MAX_AGE ?? '86400');
+
+function getCorsHeaders(req) {
+	const reflectedOrigin = req.headers.origin ? String(req.headers.origin) : '*';
+	const allowOrigin = corsOrigin === 'request' ? reflectedOrigin : corsOrigin;
+	return {
+		'Access-Control-Allow-Origin': allowOrigin,
+		'Access-Control-Allow-Methods': corsMethods,
+		'Access-Control-Allow-Headers': corsHeaders,
+		'Access-Control-Max-Age': corsMaxAge,
+		...(corsOrigin === 'request' ? { 'Vary': 'Origin' } : {}),
+	};
+}
+
+// ── Build provider ────────────────────────────────────────────────────────────
+
+async function createProvider() {
+	if (providerType === 'ollama') {
+		const { OllamaAdapter } = await import('./ai/adapters/ollamaAdapter.js');
+		const ollamaUrl = String(
+			cliArgs['ollama-url'] ??
+			process.env.GREG_AI_OLLAMA_URL ??
+			aiConfig?.ollama?.baseUrl ??
+			'http://localhost:11434',
+		);
+		const model = String(
+			cliArgs.model ??
+			process.env.GREG_AI_MODEL ??
+			aiConfig?.ollama?.model ??
+			'llama3.2',
+		);
+		return new OllamaAdapter({ baseUrl: ollamaUrl, model, ...(aiConfig?.ollama ?? {}) });
+	}
+
+	if (providerType === 'openai') {
+		const { OpenAiAdapter } = await import('./ai/adapters/openaiAdapter.js');
+		const model = String(
+			cliArgs.model ??
+			process.env.GREG_AI_MODEL ??
+			aiConfig?.openai?.model ??
+			'gpt-4o-mini',
+		);
+		return new OpenAiAdapter({ model, ...(aiConfig?.openai ?? {}) });
+	}
+
+	throw new Error(`[greg-ai] Unknown provider: "${providerType}". Supported: "ollama", "openai".`);
+}
+
+// ── Load search index ─────────────────────────────────────────────────────────
+
+console.log(`[greg-ai] Loading index: ${index}`);
+
+if (!existsSync(index)) {
+	console.error(`[greg-ai] Index file not found: ${index}`);
+	console.error('[greg-ai] Run "greg build" first to generate dist/search-index.json.');
+	process.exit(1);
+}
+
+const loadT0 = process.hrtime.bigint();
+let indexData;
+try {
+	indexData = JSON.parse(readFileSync(index, 'utf-8'));
+} catch (err) {
+	console.error(`[greg-ai] Failed to parse index: ${err.message}`);
+	process.exit(1);
+}
+const loadMs = msSince(loadT0);
+
+// ── Build RAG pipeline ────────────────────────────────────────────────────────
+
+const chunkT0 = process.hrtime.bigint();
+const chunks = buildChunks(indexData, aiConfig?.chunking ?? {});
+const chunkMs = msSince(chunkT0);
+
+const characters = resolveCharacters(
+	aiConfig?.characters,
+	aiConfig?.customCharacters ?? [],
+);
+
+const provider = await createProvider();
+
+const storeType = String(cliArgs.store ?? process.env.GREG_AI_STORE ?? aiConfig?.store ?? 'memory');
+const storeT0 = process.hrtime.bigint();
+const store = await createStore(storeType, aiConfig, provider);
+await store.index(chunks);
+const storeMs = msSince(storeT0);
+
+const pipeline = new RagPipeline(provider, store, characters);
+
+// ── HTTP server helpers ───────────────────────────────────────────────────────
+
+function readBody(req) {
+	return new Promise((resolve, reject) => {
+		let body = '';
+		req.on('data', chunk => { body += chunk; });
+		req.on('end', () => {
+			try { resolve(JSON.parse(body || '{}')); }
+			catch { resolve({}); }
+		});
+		req.on('error', reject);
+	});
+}
+
+// ── HTTP server ───────────────────────────────────────────────────────────────
+
+const server = createServer(async (req, res) => {
+	const rawUrl = req.url ?? '';
+	const qIdx = rawUrl.indexOf('?');
+	const pathname = qIdx >= 0 ? rawUrl.slice(0, qIdx) : rawUrl;
+
+	// CORS preflight
+	if (req.method === 'OPTIONS') {
+		res.writeHead(204, { ...getCorsHeaders(req) });
+		res.end();
+		return;
+	}
+
+	// GET /api/ai/characters
+	if (pathname === `${url}/characters` && req.method === 'GET') {
+		const body = JSON.stringify({ characters: pipeline.getCharacters() });
+		res.writeHead(200, {
+			'Content-Type': 'application/json; charset=utf-8',
+			'Content-Length': Buffer.byteLength(body),
+			...getCorsHeaders(req),
+		});
+		res.end(body);
+		return;
+	}
+
+	// POST /api/ai/ask
+	if (pathname === `${url}/ask` && req.method === 'POST') {
+		let requestBody;
+		try {
+			requestBody = await readBody(req);
+		} catch {
+			res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8', ...getCorsHeaders(req) });
+			res.end(JSON.stringify({ error: 'Invalid JSON body' }));
+			return;
+		}
+
+		const query = String(requestBody.query ?? requestBody.q ?? '').trim();
+		if (!query) {
+			res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8', ...getCorsHeaders(req) });
+			res.end(JSON.stringify({ error: 'query is required' }));
+			return;
+		}
+
+		const characterId = String(requestBody.character ?? aiConfig?.defaultCharacter ?? 'professional');
+		const locale = String(requestBody.locale ?? '');
+
+		try {
+			const result = await pipeline.ask(query, characterId, locale);
+			const body = JSON.stringify(result);
+			res.writeHead(200, {
+				'Content-Type': 'application/json; charset=utf-8',
+				'Cache-Control': 'no-cache',
+				'Content-Length': Buffer.byteLength(body),
+				...getCorsHeaders(req),
+			});
+			res.end(body);
+		} catch (err) {
+			console.error('[greg-ai] Query failed:', err.message);
+			res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8', ...getCorsHeaders(req) });
+			res.end(JSON.stringify({ error: 'AI query failed', detail: err.message }));
+		}
+		return;
+	}
+
+	res.writeHead(404, { ...getCorsHeaders(req) });
+	res.end();
+});
+
+server.listen(port, host, () => {
+	const startupMs = msSince(startupT0);
+	console.log(`[greg-ai] Listening on http://${host}:${port}${url}`);
+	console.log(
+		`[greg-ai] Startup: load=${fmtMs(loadMs)}, chunk=${fmtMs(chunkMs)}, ` +
+		`store-index=${fmtMs(storeMs)}, total=${fmtMs(startupMs)}`,
+	);
+	console.log(
+		`[greg-ai] Docs: ${indexData.length} pages | Chunks: ${store.size()} | Store: ${storeType} | Provider: ${providerType}`,
+	);
+	console.log(`[greg-ai] Characters: ${characters.map(c => `${c.icon} ${c.id}`).join(', ')}`);
+	console.log(
+		`[greg-ai] CORS: origin=${corsOrigin}, methods="${corsMethods}", ` +
+		`headers="${corsHeaders}", max-age=${corsMaxAge}`,
+	);
+	console.log(`[greg-ai] Endpoints:`);
+	console.log(`[greg-ai]   POST http://${host}:${port}${url}/ask`);
+	console.log(`[greg-ai]   GET  http://${host}:${port}${url}/characters`);
+});

package/src/lib/MarkdownDocs/codeDirectives.js

@@ -0,0 +1,191 @@
+function parseLineRanges(meta) {
+    const text = String(meta ?? '').replace(/\[[^\]]*\]/g, '');
+    const match = text.match(/\{([^}]+)\}/);
+    if (!match?.[1]) return new Set();
+
+    const out = new Set();
+    const parts = match[1].split(',').map((p) => p.trim()).filter(Boolean);
+    for (const part of parts) {
+        if (/^\d+$/.test(part)) {
+            out.add(Number(part));
+            continue;
+        }
+        const range = part.match(/^(\d+)\s*-\s*(\d+)$/);
+        if (!range) continue;
+        const start = Number(range[1]);
+        const end = Number(range[2]);
+        const lo = Math.min(start, end);
+        const hi = Math.max(start, end);
+        for (let i = lo; i <= hi; i++) out.add(i);
+    }
+    return out;
+}
+
+function parseLineNumbers(meta) {
+    const text = String(meta ?? '');
+    if (/\bno-line-numbers\b/i.test(text)) return { enabled: false, start: 1 };
+    const match = text.match(/\bline-numbers(?:=(\d+))?\b/i);
+    if (!match) return { enabled: false, start: 1 };
+    const start = match[1] ? Math.max(1, Number(match[1])) : 1;
+    return { enabled: true, start };
+}
+
+function parseMarkerToken(token, info) {
+    const t = token.trim().toLowerCase();
+    if (t === '++') info.diffAdd = true;
+    else if (t === '--') info.diffRemove = true;
+    else if (t === 'warning') info.diffWarning = true;
+    else if (t === 'error') info.diffError = true;
+    else if (t === 'focus') info.focus = true;
+    else if (t === 'highlight') info.highlight = true;
+}
+
+export function parseCodeDirectives(code, meta = '', lang = '') {
+    const normalizedCode = String(code ?? '').replace(/\r?\n$/, '');
+    const normalizedLang = String(lang ?? '').trim().toLowerCase();
+    const isMarkdownSource = normalizedLang === 'md' || normalizedLang === 'markdown';
+    if (isMarkdownSource) {
+        return {
+            cleanedCode: normalizedCode,
+            lineInfo: [],
+            lineNumbers: { enabled: false, start: 1 },
+        };
+    }
+
+    const highlightedLines = parseLineRanges(meta);
+    const lineNumbers = parseLineNumbers(meta);
+    const lines = normalizedCode.split(/\r?\n/);
+    const lineInfo = [];
+
+    const markerRe = /\[!code\s+([^\]]+)\]/gi;
+
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i];
+        const info = {
+            highlight: highlightedLines.has(i + 1),
+            focus: false,
+            diffAdd: false,
+            diffRemove: false,
+            diffWarning: false,
+            diffError: false,
+        };
+
+        markerRe.lastIndex = 0;
+        for (const match of line.matchAll(markerRe)) {
+            parseMarkerToken(match[1] ?? '', info);
+        }
+
+        // Remove trailing marker comments and any stray marker tokens.
+        line = line.replace(/\s*(?:\/\/|#|<!--)?\s*\[!code\s+[^\]]+\]\s*(?:-->)?\s*$/gi, '');
+        line = line.replace(/\s*\[!code\s+[^\]]+\]\s*/gi, '');
+
+        lines[i] = line;
+        lineInfo.push(info);
+    }
+
+    return {
+        cleanedCode: lines.join('\n'),
+        lineInfo,
+        lineNumbers,
+    };
+}
+
+function addClassesToLineWrapper(lineHtml, classes) {
+    const classText = classes.join(' ');
+    if (!classText) return lineHtml;
+
+    if (/^<span class="[^"]*line[^"]*">/.test(lineHtml)) {
+        return lineHtml.replace(/^<span class="([^"]*)">/, (_m, cls) => {
+            const next = `${cls} ${classText}`.trim().replace(/\s+/g, ' ');
+            return `<span class="${next}">`;
+        });
+    }
+
+    return `<span class="line ${classText}">${lineHtml}</span>`;
+}
+
+function decorateLineSpanFragment(fragment, classes, dataLine) {
+    return fragment.replace(/<span class="([^"]*\bline\b[^"]*)">([\s\S]*?)<\/span>/, (_m, cls, inner) => {
+        const merged = `${cls} ${classes.join(' ')}`.trim().replace(/\s+/g, ' ');
+        const dataLineAttr = Number.isFinite(dataLine) ? ` data-line="${dataLine}"` : '';
+        return `<span class="${merged}"${dataLineAttr}>${inner}</span>`;
+    });
+}
+
+function addClassToPre(html, cls) {
+    if (!cls) return html;
+    if (/<pre\b[^>]*class="[^"]*"/i.test(html)) {
+        return html.replace(/<pre\b([^>]*?)class="([^"]*)"([^>]*)>/i, (_m, preA, preCls, preB) => {
+            const merged = `${preCls} ${cls}`.trim().replace(/\s+/g, ' ');
+            return `<pre${preA}class="${merged}"${preB}>`;
+        });
+    }
+    return html.replace(/<pre\b/i, `<pre class="${cls}"`);
+}
+
+function addAttrsToCode(html, attrs) {
+    const entries = Object.entries(attrs).filter(([, v]) => v != null && v !== '');
+    if (!entries.length) return html;
+
+    const attrsText = entries.map(([k, v]) => `${k}="${String(v)}"`).join(' ');
+    if (/<code\b[^>]*>/i.test(html)) {
+        return html.replace(/<code\b([^>]*)>/i, (_m, codeAttrs) => `<code${codeAttrs} ${attrsText}>`);
+    }
+    return html;
+}
+
+export function decorateHighlightedCodeHtml(highlightedHtml, directives) {
+    const lines = String(highlightedHtml ?? '').split('\n');
+    let hasFocused = false;
+    let hasDiff = false;
+    const lineNumbersEnabled = Boolean(directives.lineNumbers?.enabled);
+    const lineNumberStart = Number.isFinite(directives.lineNumbers?.start)
+        ? directives.lineNumbers.start
+        : 1;
+
+    for (let i = 0; i < lines.length; i++) {
+        const info = directives.lineInfo[i] ?? {
+            highlight: false,
+            focus: false,
+            diffAdd: false,
+            diffRemove: false,
+            diffWarning: false,
+            diffError: false,
+        };
+
+        if (/<span class="[^"]*\bline\b[^"]*">/.test(lines[i])) {
+            const classes = [];
+            if (info.highlight) classes.push('highlighted');
+            if (info.focus) {
+                classes.push('focused');
+                hasFocused = true;
+            }
+            if (info.diffAdd) classes.push('diff', 'add');
+            if (info.diffRemove) classes.push('diff', 'remove');
+            if (info.diffWarning) classes.push('diff', 'warning');
+            if (info.diffError) classes.push('diff', 'error');
+            if (info.diffAdd || info.diffRemove || info.diffWarning || info.diffError) hasDiff = true;
+
+            const dataLine = lineNumbersEnabled ? lineNumberStart + i : undefined;
+            lines[i] = decorateLineSpanFragment(lines[i], classes, dataLine);
+        } else if (directives.lineInfo.length && info.highlight) {
+            lines[i] = addClassesToLineWrapper(lines[i], ['highlighted']);
+        }
+    }
+
+    let html = lines.join('\n');
+    if (hasFocused) html = addClassToPre(html, 'has-focused-lines');
+    if (hasDiff) html = addClassToPre(html, 'has-diff');
+
+    if (lineNumbersEnabled) {
+        const totalLines = lines.filter((l) => /<span class="[^"]*\bline\b[^"]*">/.test(l)).length;
+        const maxLineNumber = Math.max(lineNumberStart + totalLines - 1, lineNumberStart);
+        const maxDigits = String(maxLineNumber).length;
+        html = addAttrsToCode(html, {
+            'data-line-numbers': 'true',
+            'data-line-numbers-max-digits': maxDigits,
+        });
+    }
+
+    return html;
+}

package/src/lib/MarkdownDocs/codeFenceInfo.js

@@ -0,0 +1,45 @@
+/**
+ * Normalize fenced code info so VitePress-style forms are supported:
+ * - ```ts{2}
+ * - ```ts:line-numbers=10 {1}
+ * - ```ts line-numbers=10 {1}
+ */
+export function normalizeCodeFenceInfo(rawLang = '', rawMeta = '') {
+    const langToken = String(rawLang ?? '').trim();
+    const baseMeta = String(rawMeta ?? '').trim();
+
+    if (!langToken) {
+        return { lang: '', meta: baseMeta };
+    }
+
+    const m = langToken.match(/^([^:{\s]+)([\s\S]*)$/);
+    if (!m) return { lang: langToken, meta: baseMeta };
+
+    const lang = m[1].trim().toLowerCase();
+    const suffix = m[2] ?? '';
+
+    const metaParts = [];
+    if (baseMeta) metaParts.push(baseMeta);
+
+    for (const token of suffix.matchAll(/:([^\s{}]+)/g)) {
+        if (token[1]) metaParts.push(token[1].trim());
+    }
+    for (const block of suffix.matchAll(/\{[^}]+\}/g)) {
+        metaParts.push(block[0]);
+    }
+
+    const seen = new Set();
+    const mergedMeta = metaParts
+        .map((p) => p.trim())
+        .filter(Boolean)
+        .filter((p) => {
+            const key = p.toLowerCase();
+            if (seen.has(key)) return false;
+            seen.add(key);
+            return true;
+        })
+        .join(' ')
+        .trim();
+
+    return { lang, meta: mergedMeta };
+}

package/src/lib/MarkdownDocs/codeGroup.ts

@@ -0,0 +1,46 @@
+/**
+ * Delegated DOM handlers for static rehype code-group tabs.
+ *
+ * Used by mdsvex-rendered markdown pages where tab markup is emitted as
+ * plain HTML (<div class="rehype-code-group">...).
+ */
+export function handleCodeGroupClick(event: MouseEvent) {
+    const target = event.target;
+    if (!(target instanceof HTMLElement)) return;
+
+    const tab = target.closest(".rcg-tab");
+    if (!(tab instanceof HTMLButtonElement)) return;
+
+    const group = tab.closest(".rehype-code-group");
+    if (!(group instanceof HTMLElement)) return;
+
+    const tabs = Array.from(group.querySelectorAll(".rcg-tab"));
+    const blocks = Array.from(group.querySelectorAll(".rcg-block"));
+    const index = tabs.indexOf(tab);
+    if (index < 0 || index >= blocks.length) return;
+
+    tabs.forEach((item) => {
+        item.classList.remove("active");
+        item.setAttribute("aria-selected", "false");
+    });
+    blocks.forEach((block) => {
+        block.classList.remove("active");
+        block.setAttribute("hidden", "true");
+    });
+
+    tab.classList.add("active");
+    tab.setAttribute("aria-selected", "true");
+
+    const activeBlock = blocks[index];
+    activeBlock.classList.add("active");
+    activeBlock.removeAttribute("hidden");
+}
+
+export function handleCodeGroupKeydown(event: KeyboardEvent) {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    const target = event.target;
+    if (!(target instanceof HTMLElement)) return;
+    if (!target.closest(".rcg-tab")) return;
+    event.preventDefault();
+    handleCodeGroupClick(event as unknown as MouseEvent);
+}

package/src/lib/MarkdownDocs/common.ts

@@ -0,0 +1,47 @@
+import gregConfig from "virtual:greg-config";
+
+const EXTERNAL_RE = /^(?:[a-z][a-z\d+\-.]*:|\/\/)/i;
+const SLASHES_RE = /\/+/g;
+
+function normalizeBase(value: unknown): string {
+    const raw = String(value || "/").trim();
+    return raw === "/" ? "/" : `/${raw.replace(/^\/+|\/+$/g, "")}`;
+}
+
+export function joinPath(base: string, path: string) {
+  return `${base}${path}`.replace(SLASHES_RE, '/')
+}
+
+export const pathConfig = {
+    base: normalizeBase((gregConfig as any).base),
+    srcDir: String((gregConfig as any).srcDir ?? "docs").replace(SLASHES_RE, '/'),
+    docsBase: String(
+        Object.prototype.hasOwnProperty.call((gregConfig as any), "docsBase")
+            ? (gregConfig as any).docsBase
+            : "",
+    ).replace(SLASHES_RE, '/'),
+};
+
+export function withBase(path: string): string {
+    if (EXTERNAL_RE.test(path) || !path.startsWith("/")) return path;
+    return joinPath(pathConfig.base, path);
+}
+
+export function withoutBase(path: string): string {
+    if (EXTERNAL_RE.test(path) || !path.startsWith("/")) return path;
+    const base = pathConfig.base;
+    if (base && path.startsWith(base)) return joinPath('/', path.slice(base.length));
+    return path;
+}
+
+/**
+ * Normalize any path to the canonical `/something` form.
+ * Returns `"/"` for empty, null-ish, or root inputs.
+ * Mirrors `normalizeSrcDir` from `localeUtils` to avoid a circular import.
+ */
+export function normalizePath(path: string): string {
+    const value = String(path || "").trim();
+    if (!value || value === "/") return "/";
+    return "/" + value.replace(/^\/+|\/+$/g, "");
+}
+