@dominikcz/greg 0.9.27

package/README.md

@@ -0,0 +1,397 @@
+# Greg
+
+Svelte 5 + Vite-powered documentation engine. Write Markdown, get a beautiful documentation site — hot-reloaded in milliseconds.
+
+Inspired by [VitePress](https://vitepress.dev){target="_blank"}, built on Svelte 5.
+
+## Quick start
+
+```sh
+npx @dominikcz/greg init
+```
+
+For unattended/default setup (no prompts):
+
+```sh
+npx @dominikcz/greg init --defaults
+```
+
+The interactive wizard will ask for docs path, site title, TypeScript preference, and the type of initial documentation (empty, sample, or generated fake docs). It can also install all required dependencies for you.
+
+At the end you only need:
+
+```sh
+npm run dev
+```
+
+In this repository, prefer `npm run ...` scripts for development.
+In consumer projects using Greg, use `greg ...` (typically via npm scripts) or `npx greg ...`.
+
+## Manual installation
+
+```sh
+npm install --save-dev @dominikcz/greg @sveltejs/vite-plugin-svelte svelte vite
+```
+
+If your `package.json` does not already define module type, set:
+
+```json
+{
+    "type": "module"
+}
+```
+
+**`vite.config.js`**
+
+```js
+import { defineConfig } from 'vite'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import {
+    vitePluginGregConfig,
+    vitePluginSearchIndex,
+    vitePluginSearchServer,
+    vitePluginFrontmatter,
+    vitePluginCopyDocs,
+} from '@dominikcz/greg/plugins'
+
+export default defineConfig({
+    plugins: [
+        svelte(),
+        vitePluginGregConfig(),
+        vitePluginSearchIndex({ docsDir: 'docs', srcDir: '/' }),
+        vitePluginSearchServer({ docsDir: 'docs', srcDir: '/' }),
+        vitePluginFrontmatter({ docsDir: 'docs', srcDir: '/' }),
+        vitePluginCopyDocs({ docsDir: 'docs', srcDir: '/' }),
+    ],
+})
+```
+
+**`svelte.config.js`** (must be `.js` — not `.ts`)
+
+```js
+export { default } from '@dominikcz/greg/svelte.config'
+```
+
+**`greg.config.js`** (or `.ts`)
+
+```js
+/** @type {import('@dominikcz/greg').GregConfig} */
+export default {
+    srcDir: 'docs',
+    docsBase: '',
+    mainTitle: 'My Docs',
+    sidebar: [
+        { text: 'Guide', auto: '/guide' },
+        { text: 'GitHub', link: 'https://github.com/dominikcz/greg' }, // default: _self
+        { text: 'GitHub (new tab)', link: 'https://github.com/dominikcz/greg', target: '_blank' },
+    ],
+}
+```
+
+**`src/App.svelte`**
+
+```svelte
+<script>
+    import MarkdownDocs from '@dominikcz/greg'
+</script>
+
+<MarkdownDocs />
+```
+
+## Localization (VitePress-compatible)
+
+Greg supports VitePress-style `locales` in `greg.config.js`.
+
+- Locale keys use paths like `'/'`, `'/pl/'`, `'/de/'`
+- They are resolved under `docsBase` (URL prefix)
+- Supported per locale: `lang`, `title`, `label`
+- Supported per locale `themeConfig` keys:
+    `nav`, `sidebar`, `outline`, `lastUpdatedText`, `langMenuLabel`,
+    `sidebarMenuLabel`, `skipToContentLabel`, `returnToTopLabel`,
+    `darkModeSwitchLabel`, `lightModeSwitchTitle`, `darkModeSwitchTitle`,
+    `docFooter`, `siteTitle`, `logo`, `socialLinks`, `editLink`, `footer`, `aside`, `lastUpdated`
+- Header automatically shows a language switcher when at least two locales are configured
+- `i18nRouting: true` (default) keeps the same relative page when possible
+- `i18nRouting: false` switches directly to locale root
+
+```js
+/** @type {import('@dominikcz/greg').GregConfig} */
+export default {
+    srcDir: 'docs',
+    docsBase: '',
+    i18nRouting: true,
+    locales: {
+        '/': {
+            lang: 'en-US',
+            title: 'My Docs',
+            themeConfig: {
+                nav: [
+                    { text: 'Guide', link: '/guide' },
+                    { text: 'Reference', link: '/reference' },
+                ],
+                sidebar: [
+                    { text: 'Guide', auto: '/guide' },
+                    { text: 'Reference', auto: '/reference' },
+                ],
+                outline: [2, 3],
+                lastUpdatedText: 'Last updated:',
+                langMenuLabel: 'Change language',
+                sidebarMenuLabel: 'Menu',
+                skipToContentLabel: 'Skip to content',
+                returnToTopLabel: 'Return to top',
+                darkModeSwitchLabel: 'Appearance',
+                lightModeSwitchTitle: 'Switch to light theme',
+                darkModeSwitchTitle: 'Switch to dark theme',
+                docFooter: { prev: 'Previous', next: 'Next' },
+            },
+        },
+        '/pl/': {
+            lang: 'pl-PL',
+            label: 'Polski',
+            title: 'Moje Dokumenty',
+            themeConfig: {
+                nav: [
+                    { text: 'Przewodnik', link: '/pl/guide' },
+                    { text: 'Referencja', link: '/pl/reference' },
+                ],
+                sidebar: [
+                    { text: 'Przewodnik', auto: '/pl/guide' },
+                    { text: 'Referencja', auto: '/pl/reference' },
+                ],
+                outline: { level: [2, 3], label: 'Na tej stronie' },
+                lastUpdatedText: 'Zaktualizowano:',
+                langMenuLabel: 'Zmien jezyk',
+                sidebarMenuLabel: 'Menu',
+                skipToContentLabel: 'Przejdz do tresci',
+                returnToTopLabel: 'Wroc na gore',
+                darkModeSwitchLabel: 'Wyglad',
+                lightModeSwitchTitle: 'Przelacz na jasny motyw',
+                darkModeSwitchTitle: 'Przelacz na ciemny motyw',
+                docFooter: { prev: 'Poprzednia', next: 'Nastepna' },
+            },
+        },
+    },
+}
+```
+
+## CLI
+
+For development in this repository, use `npm run ...` scripts (they call the local CLI entrypoint).
+When Greg is installed in a project, the `greg` command is still available via npm scripts and `npx greg ...`.
+
+| Command               | Description                           |
+| --------------------- | ------------------------------------- |
+| `greg init`           | Interactive project scaffolding       |
+| `greg dev`            | Start Vite dev server                 |
+| `greg build`          | Production build (auto versioning)    |
+| `greg build:static`   | Production build + static export      |
+| `greg build:markdown` | Export resolved markdown              |
+| `greg preview`        | Preview production build              |
+| `greg search-server`  | Standalone search API server          |
+
+## Multi-version Docs
+
+Greg supports two source strategies configured under `greg.config.* > versioning`:
+
+- `branches` (default): reads docs from configured git branches/refs and caches snapshots/builds per commit SHA
+- `folders`: reads docs directly from version folders in the working tree
+
+### Rules
+
+1. Put all versioning config in `greg.config.js` (or `greg.config.ts`) under `versioning`.
+2. Choose one strategy in `versioning.strategy`.
+3. Map each built version id to its source:
+     - branch mode: `versioning.branches[]` with `version` + `branch`
+     - folder mode: `versioning.folders[]` with `version` + `dir`
+4. Set `versioning.default` and optional `versioning.aliases` for selector behavior.
+
+### Branch Mode Guide
+
+Use this when each docs version should come from a Git branch/ref.
+
+What to configure:
+
+1. `versioning.strategy = 'branches'`
+2. `versioning.branches[]` entries with `version`, `branch`, optional `docsDir`, `title`
+3. `versioning.default` and optional `versioning.aliases`
+
+Example `versioning` value:
+
+```js [greg.config.js]
+export default {
+    versioning: {
+        strategy: 'branches',
+        default: 'latest',
+        aliases: {
+            latest: '2.1',
+            stable: '2.0'
+        },
+        branches: [
+            { version: '2.1', branch: 'main', title: '2.1' },
+            { version: '2.0', branch: 'release/2.0', title: '2.0' }
+        ]
+    }
+}
+```
+
+### Folder Mode Guide
+
+Use this when each docs version should come from a directory in the working tree.
+
+What to configure:
+
+1. `versioning.strategy = 'folders'`
+2. `versioning.folders[]` entries with `version`, `dir`, optional `srcDir`, `title`
+3. `versioning.default` and optional `versioning.aliases`
+
+Example `versioning` value:
+
+```js [greg.config.js]
+export default {
+    versioning: {
+        strategy: 'folders',
+        default: 'latest',
+        aliases: {
+            latest: '2.1',
+            stable: '2.0'
+        },
+        folders: [
+            { version: '2.1', dir: './docs', title: '2.1' },
+            { version: '2.0', dir: './versions/2.0/docs', title: '2.0' }
+        ]
+    }
+}
+```
+
+### Commands
+
+After configuration is in place, run:
+
+```sh
+greg build
+```
+
+Output is generated to `<outDir>/__versions/<version>` (default `dist/__versions/<version>`) and a manifest is written to `<outDir>/__versions/versions.json`.
+After that, Greg syncs the default version to `dist/` so the root output is directly hostable.
+
+Defaults are VitePress-compatible:
+
+- `outDir` comes from top-level `greg.config.* > outDir` (default `dist`)
+- manifest path prefix is based on top-level `greg.config.* > base` (default `/`)
+
+Optional UI labels/messages can be configured under `versioning.ui`:
+
+```js [greg.config.js]
+export default {
+    versioning: {
+        ui: {
+            versionMenuLabel: 'Version',
+            manifestUnavailableText: 'Version selector unavailable',
+            showManifestUnavailableStatus: false,
+            outdatedVersionMessage: 'You are viewing an older version ({current}). Recommended: {default}.',
+            outdatedVersionActionLabel: 'Go to latest'
+        }
+    }
+}
+```
+
+To override those labels per locale, use `versioning.locales`:
+
+```js [greg.config.js]
+export default {
+    versioning: {
+        locales: {
+            '/': {
+                ui: {
+                    versionMenuLabel: 'Version'
+                }
+            },
+            '/pl/': {
+                ui: {
+                    versionMenuLabel: 'Wersja'
+                }
+            }
+        }
+    }
+}
+```
+
+Resolution order for versioning UI text is:
+
+1. `versioning.locales[active-locale].ui`
+2. `versioning.ui`
+3. built-in default text
+
+If `versions.json` cannot be loaded, Greg now shows a subtle fallback text in the header instead of the selector.
+
+Example manifest:
+
+```json
+{
+    "default": "latest",
+    "versions": [
+        { "version": "2.1", "title": "2.1", "path": "/__versions/2.1/" },
+        { "version": "2.0", "title": "2.0", "path": "/__versions/2.0/" }
+    ],
+    "aliases": {
+        "latest": "2.1",
+        "stable": "2.0"
+    }
+}
+```
+
+## Resolved Markdown Export
+
+Generate a fully expanded markdown snapshot (all `<!--@include: ...-->` and `<<< ...` resolved)
+for AI knowledge-base ingestion or server-side indexing pipelines.
+
+```sh
+greg build:markdown
+```
+
+Output is written to `dist/resolved-markdown` and mirrors the `docs/` structure.
+
+## TypeScript
+
+Greg ships types at `@dominikcz/greg`. `greg.config.ts` is supported — it is transpiled via esbuild at build time.
+
+```ts
+import type { GregConfig } from '@dominikcz/greg'
+
+export default {
+    srcDir: 'docs',
+    docsBase: '',
+    mainTitle: 'My Docs',
+} satisfies GregConfig
+```
+
+`srcDir` can also be an array when your docs are split across multiple folders:
+
+```ts
+import type { GregConfig } from '@dominikcz/greg'
+
+export default {
+    srcDir: ['docs', 'api-docs', 'handbook'],
+    docsBase: '',
+} satisfies GregConfig
+```
+
+When multiple folders contain the same relative path (for example `guide/index.md`),
+the later entry in the `srcDir` array overrides the earlier one.
+
+> **Note:** `svelte.config` must remain a `.js` file — `@sveltejs/vite-plugin-svelte` loads it directly via Node ESM without a TypeScript transform.
+
+## Links
+
+- [Documentation](https://github.com/dominikcz/greg)
+- [GitHub](https://github.com/dominikcz/greg)
+- [npm](https://www.npmjs.com/package/@dominikcz/greg)
+
+---
+
+## TODO
+
+- [ ] AI search integration
+- [ ] edit mode
+- [ ] comments
+- [ ] code cleanup

package/bin/greg.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * greg CLI
+ *
+ * Usage:
+ *   greg init                    Initialise a new documentation project
+ *   greg dev                    Start the Vite development server
+ *   greg build                  Build for production (auto-detects versioning config)
+ *   greg build:static           Build for production and generate static route files
+ *   greg build:markdown         Export resolved markdown files
+ *   greg preview                Preview the production build
+ *   greg search-server          Start the standalone search server (production)
+ *   greg --version              Print the Greg version
+ *   greg --help                 Show this help message
+ */
+import { spawnSync, fork } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+import { DEFAULT_OUTPUT_BASE_DIR } from '../src/lib/MarkdownDocs/versioningDefaults.js';
+import { loadGregConfig } from '../src/lib/MarkdownDocs/loadGregConfig.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+
+const [, , command, ...args] = process.argv;
+
+function color(text, code) {
+    return USE_COLOR ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+
+function infoTag() {
+    return color('[greg]', '1;36');
+}
+
+function warnTag() {
+    return color('[greg:warn]', '1;33');
+}
+
+function errorTag() {
+    return color('[greg:error]', '1;31');
+}
+
+function help() {
+    console.log(`
+  greg v${pkg.version}
+
+  Usage: greg <command> [options]
+
+  Commands:
+    init           Initialise a new documentation project (interactive)
+    dev            Start the Vite development server
+    build          Build for production (auto-detects versioning config)
+    build:static   Build and generate static route files
+    build:markdown Export resolved markdown files to dist/resolved-markdown
+    preview        Preview the production build
+    search-server  Start the standalone search API server (production)
+                   Options: --index <path>  --port <number>  --host <addr>
+                            --url   <path>  (endpoint path, default /api/search)
+                            --cors-origin <value>  (default *)
+                            --cors-methods <value> (default "GET, OPTIONS")
+                            --cors-headers <value> (default "Content-Type")
+                            --cors-max-age <value> (default 86400)
+    ai-server      Start the standalone AI/RAG API server (production)
+                   Options: --index <path>    (default dist/search-index.json)
+                            --port <number>   (default 3200)
+                            --host <addr>     (default localhost)
+                            --url  <path>     (endpoint path, default /api/ai)
+                            --provider <name> (ollama|openai, default ollama)
+                            --model <name>    (LLM model override)
+                            --ollama-url <url>(default http://localhost:11434)
+                            --cors-origin / --cors-methods / --cors-headers / --cors-max-age
+
+  Options:
+    --version   Show version number
+    --help      Show this help message
+    --single    With 'build': force a single vite build
+        --clean-versions With 'build' + versioning: remove versioned output before build
+        --rebuild-all With 'build' + versioning: rebuild all versions and skip build cache
+`);
+}
+
+function run(cmd, extraArgs = [], options = {}) {
+    const { exit = true } = options;
+    const result = spawnSync(cmd, extraArgs, {
+        stdio: 'inherit',
+        shell: true,
+        // Ensure the local node_modules/.bin is on the PATH so that
+        // the project-local vite binary is preferred.
+        env: {
+            ...process.env,
+            PATH: resolve(__dirname, '../node_modules/.bin') +
+                (process.platform === 'win32' ? ';' : ':') +
+                (process.env.PATH ?? ''),
+        },
+    });
+    const status = result.status ?? 0;
+    if (exit) process.exit(status);
+    return status;
+}
+
+function runNodeScript(scriptPath, extraArgs = [], options = {}) {
+    const { exit = true } = options;
+    const result = spawnSync(process.execPath, [scriptPath, ...extraArgs], {
+        stdio: 'inherit',
+        env: {
+            ...process.env,
+            PATH: resolve(__dirname, '../node_modules/.bin') +
+                (process.platform === 'win32' ? ';' : ':') +
+                (process.env.PATH ?? ''),
+        },
+    });
+    const status = result.status ?? 0;
+    if (exit) process.exit(status);
+    return status;
+}
+
+function printElapsedSeconds(startMs) {
+    const elapsed = ((Date.now() - startMs) / 1000).toFixed(1);
+    console.log(`\n${infoTag()} ${color(`Done in ${elapsed}s`, '32')}`);
+}
+
+async function hasVersioningBuildConfig() {
+    try {
+        const config = await loadGregConfig();
+        const versioning = config?.versioning;
+        if (!versioning || typeof versioning !== 'object' || Array.isArray(versioning)) return false;
+
+        const hasBranches = Array.isArray(versioning.branches) && versioning.branches.length > 0;
+        const hasFolders = Array.isArray(versioning.folders) && versioning.folders.length > 0;
+        const hasFoldersDir = typeof versioning.foldersDir === 'string' && versioning.foldersDir.trim().length > 0;
+        return hasBranches || hasFolders || hasFoldersDir;
+    } catch (error) {
+        console.warn(`${warnTag()} Could not read greg.config.* (${error?.message || error}). Falling back to single build.`);
+        return false;
+    }
+}
+
+function resolveSiteOutDir(config) {
+    return String(config?.outDir || DEFAULT_OUTPUT_BASE_DIR).trim() || DEFAULT_OUTPUT_BASE_DIR;
+}
+
+function resolveDocsSourceDir(config) {
+    return String(config?.srcDir || 'docs').trim() || 'docs';
+}
+
+function resolveDocsBase(config) {
+    const docsBaseValue = Object.prototype.hasOwnProperty.call(config || {}, 'docsBase')
+        ? config.docsBase
+        : '';
+    const cleaned = String(docsBaseValue ?? '').trim().replace(/^\/+|\/+$/g, '');
+    return '/' + cleaned;
+}
+
+switch (command) {
+    case 'init': {
+        const initScript = resolve(__dirname, 'init.js');
+        const child = fork(initScript, args, { stdio: 'inherit' });
+        child.on('exit', code => process.exit(code ?? 0));
+        break;
+    }
+    case 'dev':
+        run('vite', args);
+        break;
+    case 'build': {
+        const startedAt = Date.now();
+        const forceSingle = args.includes('--single');
+        const passthroughArgs = args.filter((a) => a !== '--single');
+        const shouldBuildVersions = !forceSingle && await hasVersioningBuildConfig();
+
+        if (shouldBuildVersions) {
+            console.log(`${infoTag()} ${color('versioning config detected. Running multi-version build.', '36')}`);
+            const versionsScript = resolve(__dirname, '../scripts/build-versions.js');
+            const status = runNodeScript(versionsScript, passthroughArgs, { exit: false });
+            printElapsedSeconds(startedAt);
+            process.exit(status);
+        }
+
+        const status = run('vite build', passthroughArgs, { exit: false });
+        printElapsedSeconds(startedAt);
+        process.exit(status);
+    }
+    case 'build:static': {
+        const startedAt = Date.now();
+        const config = await loadGregConfig();
+        const distDir = resolveSiteOutDir(config);
+        const docsDir = resolveDocsSourceDir(config);
+        const srcDir = resolveDocsBase(config);
+        const buildStatus = run('vite build', args, { exit: false });
+        if (buildStatus !== 0) {
+            printElapsedSeconds(startedAt);
+            process.exit(buildStatus);
+        }
+        const staticScript = resolve(__dirname, '../scripts/generate-static.js');
+        const status = runNodeScript(
+            staticScript,
+            ['--docsDir', docsDir, '--srcDir', srcDir, '--distDir', distDir],
+            { exit: false },
+        );
+        printElapsedSeconds(startedAt);
+        process.exit(status);
+        break;
+    }
+    case 'build:markdown': {
+        const markdownScript = resolve(__dirname, '../scripts/render-markdown.js');
+        runNodeScript(markdownScript, args);
+        break;
+    }
+    case 'preview':
+        run('vite preview', args);
+        break;
+    case 'search-server': {
+        // Run the standalone search server directly in this process
+        // (no shell needed - it is a Node.js script in the package).
+        const serverScript = resolve(__dirname, '../src/lib/MarkdownDocs/searchServer.js');
+        const child = fork(serverScript, args, { stdio: 'inherit' });
+        child.on('exit', code => process.exit(code ?? 0));
+        break;
+    }
+    case 'ai-server': {
+        const aiServerScript = resolve(__dirname, '../src/lib/MarkdownDocs/aiServer.js');
+        const child = fork(aiServerScript, args, { stdio: 'inherit' });
+        child.on('exit', code => process.exit(code ?? 0));
+        break;
+    }
+    case '--version':
+    case '-v':
+        console.log(pkg.version);
+        break;
+    case '--help':
+    case '-h':
+    case undefined:
+        help();
+        break;
+    default:
+        console.error(`${errorTag()} Unknown command: ${command}\n`);
+        help();
+        process.exit(1);
+}