@gkucmierz/knowledge-base-engine

Zero-Config, Interactive Knowledge Base & Handbook Engine powered by Vue 3, Vite, MiniSearch, KaTeX, and dual-mode Mermaid diagrams.

@gkucmierz/knowledge-base-engine to lekki, uniwersalny silnik interaktywnej dokumentacji technicznej, procedur DevOps oraz podręczników dydaktycznych działający w konwencji Zero-Config. Wystarczy katalog z artykułami Markdown (articles/) oraz polecenie CLI (kb dev), aby natychmiast uruchomić aplikację z reaktywnymi blokami kodu, parametryzacją w locie, wyszukiwarką pełnotekstową, diagramami architektonicznymi i opcjonalnym szyfrowanym skarbcem.

🌟 Real-World Showcase (Projekty na Silniku)

Silnik napędza produkcyjne projekty ekosystemu 7u.pl:

1. Baza Wiedzy (knowledge-base.7u.pl):

   • Osobista baza wiedzy technicznej, procedury DevOps, komendy Linux/macOS i runbooki awaryjne.
   • Posiada wbudowany skarbiec kryptograficzny (Envelope Encryption AES-256-GCM + PBKDF2) dla poufnych notatek z automatyczną detekcją i odblokowywaniem w sesji.

2. 3D Handbook (3d-handbook.7u.pl):

   • Interaktywny podręcznik profesjonalnego modelowania 3D, anatomii twarzy (Hippydrome loops), stylizacji anime (Custom Normals Transfer & Inverted Hull), standardu Apple ARKit 52 blendshapes oraz bezgłowego Blendera (bpy).
   • Ustrukturyzowana wiedza modułowa z sekwencyjną nawigacją lekcji [← Poprzednia] / [Następna →].

🎯 Filozofia: The "5-Second Outage" Runbook

Tradycyjne systemy dokumentacji (Notion, Obsidian, Docusaurus) prezentują statyczny tekst wymagający ręcznego kopiowania i edytowania komend w terminalu. knowledge-base-engine przekształca dokumentację w interaktywny pulpit inżynierski:

1. Struktura TL;DR-first:
   • Maksymalny stosunek sygnału do szumu, zero zbędnych wstępów.
   • Zdanie wprowadzające $\rightarrow$ Gotowy snippet produkcyjny $\rightarrow$ 1–3 kluczowe pułapki $\rightarrow$ Opcjonalny diagram Mermaid.
2. Reaktywna Parametryzacja w Locie (CodeBlock.vue):
   • Zmieniaj porty, domeny, maile czy dane logowania w pasku parametrów nad blokiem kodu.
   • Snippet, kolorowanie składni i przycisk Kopiuj natychmiast aktualizują się do wprowadzonych wartości.
3. Ścisłe OPSEC i Maskowanie Haseł:
   • Pola typu password posiadają przełącznik widoczności (👁️) i są wizualnie maskowane jako •••••••• w ciele kodu, chroniąc przed podglądaniem ekranu (shoulder surfing / screen-sharing).
   • Przycisk Kopiuj zawsze pobiera rzeczywistą wartość. Hasła nigdy nie są zapisywane w localStorage.
4. Zero-Trust & Offline-First:
   • 100% lokalnych zależności przez npm i Vite. Brak zewnętrznych CDN-ów czy czcionek Google.

✨ Kluczowe Cechy Silnika

• ⚡ Reaktywny Silnik Bloków Kodu:
  • Parametry definiowane w nagłówku bloku Markdown: ```bash port:port="8080" user:text="admin" pass:password="secret"
  • Obsługiwane typy: email (zapisywany w localStorage), password (maskowany, OPSEC-hardened), port (walidacja 1–65535), number, bool / boolean (interaktywne przełączniki pills: true/false, 1/0, on/off, yes/no), text.
• 🚀 Wykonywanie Kodu w Przeglądarce (instacode):
  • Uruchamianie skryptów JavaScript po stronie klienta (np. profilery lagów event loopa, benchmarki, testy regexów) z przechwytywaniem wyjścia konsoli (console.log).
• 🧩 Modularna Transkluzja Kodu (id & include):
  • Współdzielenie bibliotek i powtarzalnych skryptów pomiędzy blokami w artykule.
  • Dołączany kod automatycznie scala się z aktywnymi zmiennymi i komentarzami właściwymi dla danego języka (#, //, --).
  • Dedykowane okno Imports umożliwia weryfikację pełnego złożonego skryptu przed skopiowaniem.
• 📊 Dual-Mode Diagramy Mermaid:
  • Natywne wsparcie dla flowchart, sequenceDiagram, stateDiagram, classDiagram, gitGraph oraz mindmap.
  • Dynamiczna adaptacja do motywu Dark / Light.
  • Przełącznik w nagłówku do podglądu kodu źródłowego diagramu z numeracją linii.
• 📐 Formuły Matematyczne KaTeX:
  • Renderowanie równań $\LaTeX$ inline $x$ oraz blokowych $$...$$.
• 🏷️ SSOT Tagów & Wiki Linker:
  • Tagi deklarowane w nagłówku YAML (tags: [...]).
  • Automatycznie generowana sekcja tagów z filtrowaniem wyszukiwarki.
  • Wewnętrzne hashtagi w treści (np. #docker, #blender) automatycznie stają się klikalnymi odnośnikami.
• 🔍 Błyskawiczna Wyszukiwarka Pełnotekstowa:
  • Oparta na bibliotece @gkucmierz/vue-minisearch z wyszukiwaniem rozmytym (fuzzy search), dopasowywaniem prefiksów i ważeniem pól (tytuł, slug, tagi, treść).
• 🔒 Dynamiczny Skarbiec Kryptograficzny (Zero-Leak Vault):
  • Oparty na standardzie Envelope Encryption (AES-256-GCM + PBKDF2 z 10 milionami iteracji).
  • Kłódka i okno deszyfrowania renderują się wyłącznie wtedy, gdy w projekcie wykryte zostaną pliki .enc. W czystych podręcznikach (jak 3d-handbook) UI skarbca jest w 100% niewidoczne.
• 🌐 SSG & SEO Ready:
  • Automatyczne pre-renderowanie statycznego HTML dla każdego artykułu, kategorii i tagu wraz z Open Graph, Twitter Cards, Schema.org JSON-LD (TechArticle) oraz sitemap.xml.

🚀 Szybki Start (Quick Start)

1. Inicjalizacja projektu

W pustym katalogu utwórz strukturę:

mkdir my-handbook && cd my-handbook
npm init -y
npm install @gkucmierz/knowledge-base-engine

2. Struktura plików

my-handbook/
├── articles/
│   ├── 01-wstep/
│   │   └── 01-pierwsze-kroki.md
│   └── 02-architektura/
│       └── 01-zasady-systemu.md
├── public/
│   └── logo.svg             # Opcjonalny własny logotyp
├── kb.config.json           # Opcjonalna konfiguracja
└── package.json

3. Konfiguracja package.json

{
  "name": "my-handbook",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "kb dev",
    "build": "kb build",
    "preview": "kb preview",
    "vault:encrypt": "kb encrypt"
  },
  "dependencies": {
    "@gkucmierz/knowledge-base-engine": "^1.0.0"
  }
}

4. Uruchomienie deweloperskie

npm run dev
# 💡 Launching Knowledge Base dev server on http://localhost:15631/

💻 CLI Commands

Silnik udostępnia globalną i lokalną binarkę kb:

kb dev [-p, --port 51958]       # Uruchamia serwer developerski z HMR
kb build                        # Kompiluje bundle SPA i generuje statyczny SSG HTML do dist/
kb preview [-p, --port 51958]   # Podgląd zbudowanej wersji produkcyjnej
kb encrypt                      # Szyfruje articles/private/*.md do articles/encrypted/*.enc
kb encrypt --rekey              # Wymusza rotację klucza DEK sejfu

⚙️ Konfiguracja (kb.config.json)

Wszystkie opcje w pliku kb.config.json są opcjonalne:

{
  "title": "3D Handbook",
  "tagline": "Interaktywne kompendium profesjonalnego modelowania 3D i WebGL",
  "port": 15631,
  "badge": "3D",
  "logo": "/3d-handbook.svg",
  "baseUrl": "https://3d-handbook.7u.pl",
  "analyticsApp": "3d-handbook",
  "categories": [
    { "id": "01-pipeline", "label": "Pipeline & glTF" },
    { "id": "02-topology", "label": "Topologia Twarzy" }
  ]
}

| Opcja | Typ | Domyślnie | Opis | | :--- | :--- | :--- | :--- | | title | string | "Knowledge Base" | Tytuł w navbarze oraz w tagu <title> | | tagline | string | "" | Opis projektu w nagłówku i meta tagach Open Graph | | port | number | 51958 | Port serwera deweloperskiego (lub z dport) | | badge | string | "" | Opcjonalny badge obok tytułu (np. "7u.pl", "3D", "DOCS") | | logo | string | "/default-logo.svg" | Ścieżka do logotypu SVG/PNG w katalogu public/ | | baseUrl | string | "https://knowledge-base.7u.pl" | URL kanoniczny dla sitemapy i tagów Open Graph | | analyticsApp | string | Nazwa z package.json | Aplikacja zgłaszana do analityki @gkucmierz/analytics | | categories | array | auto-detected | Własne etykiety kategorii (lub wyliczane z podfolderów) |

🐳 Wdrożenie Produkcyjne (Docker & Gitea CI/CD)

Wzorcowa konfiguracja stosowana na serwerach produkcyjnych (zgodna ze standardem 7u.pl):

Dockerfile

# Stage 1: Kompilacja aplikacji SPA i SSG
FROM node:22-alpine AS build-stage
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Stage 2: Serwer Nginx
FROM nginx:stable-alpine AS production-stage
COPY --from=build-stage /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=3s CMD wget --quiet --tries=1 --spider http://localhost/health || exit 1
CMD ["nginx", "-g", "daemon off;"]

docker-compose.yml

name: 3d-handbook

services:
  app:
    build: .
    image: 3d-handbook:latest
    container_name: 3d-handbook
    restart: unless-stopped
    networks:
      - npm_network

networks:
  npm_network:
    external: true

.gitea/workflows/build.yaml

name: Build and Deploy to Production PL

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: self-hosted-pl
    steps:
      - name: Checkout repository code
        uses: actions/checkout@v4

      - name: Build and deploy with Docker Compose (Zero-Downtime)
        run: |
          docker compose build
          docker compose up -d --remove-orphans

📄 Licencja

MIT © Grzegorz Kućmierz