doql

Rodzina OQL — paczka kompletna

AI Cost Tracking

PyPI Version Python License AI Cost Human Time Model

Generated on 2026-06-09 using openrouter/qwen/qwen3-coder-next

Version Python License Status

Data wydania: 2026-04-20
Wersja: 1.0.0 (stable)
Zawartość: repo doql/ + repo articles/ + ten README
Zmiany: CSS-like syntax, redeploy integration, public API __all__

Do czego można użyć doql

doql (Declarative OQL) to generator deklaratywny, który z jednego pliku .doql tworzy kompletne aplikacje, dokumenty i integracje. Zamiast pisać kod — deklarujesz co ma powstać, a generator robi jak.

10 głównych zastosowań

# Zastosowanie Co powstaje Przykład w repo
1 Aplikacje SaaS Full-stack: API + Web + Mobile + Desktop examples/asset-management/ — klon Drägerware dla BHP
2 Laboratoria kalibracyjne System ISO 17025 z 4-eyes, WORM, świadectwami examples/calibration-lab/ — lab z zarządzaniem wzorcami
3 Flota IoT Zarządzanie urządzeniami, OTA, monitoring Prometheus examples/iot-fleet/ — flota Raspberry Pi z mapą
4 Generowanie dokumentów PDF, HTML, DOCX bez backendu examples/document-generator/ — świadectwa kalibracyjne
5 Stanowiska kiosk Tablety/Raspberry Pi w trybie fullscreen examples/kiosk-station/ — operator panel na hali
6 Prototypy full-stack API + web + mobile + desktop z jednego pliku examples/notes-app/ — notatnik wszystkie platformy
7 Aplikacje PWA Mobile-first, offline, installable examples/todo-pwa/ — minimalna lista zadań
8 Systemy CMS Blogi, treści, tagi, komentarze examples/blog-cms/ — prosty blog
9 CRM i pipeline Kontakty, leady, sprzedaż examples/crm-contacts/ — zarządzanie klientami
10 Sklepy e-commerce Koszyk, zamówienia, płatności examples/e-commerce-shop/ — sklep online

Co generuje doql z jednej deklaracji

Formaty deklaracji

app.doql          # YAML-like, indentacja
app.doql.css      # CSS-like: entity[name="X"] { ... }
app.doql.less     # CSS + zmienne @primary
app.doql.sass     # SASS + zmienne $primary

Wszystkie formaty są równoważne — możesz konwertować między nimi.

Co jest w tej paczce

doql/ — nowy projekt: generator deklaratywny

Kompletny projekt doql — warstwa deklaratywna nad oqlos, która z jednego pliku .doql generuje aplikacje, dokumenty, kioski, integracje API. Licencja Apache 2.0 (open core).

Kluczowe dokumenty:

Dziesięć przykładów (gotowych .doql / .doql.css / .doql.less / .doql.sass):

Infrastruktura projektu:

Paczki tooling (packages/*2doql) — mosty wejścia → DOQL (.doql.less). Pełny indeks: packages/README.md.

Pakiet Do czego służy README
mcp2doql Serwer MCP (stdio) — query/patch/validate/DSL przez narzędzia MCP packages/mcp2doql/README.md
cli2doql Shell CLI (REPL) sterujący DOQL przez DSL (dsl2doql) packages/cli2doql/README.md
dsl2doql DSL sterowania DOQL (QUERY, PATCH, VALIDATE, ADOPT, …) packages/dsl2doql/README.md
nlp2doql Sterowanie DOQL przez NL (generate, apply, edit) packages/nlp2doql/README.md
uri2doql doql:// URI — query, patch, apply, nlp2uri packages/uri2doql/README.md

Skanowanie MCP/CLI (adopt) i konwersja OQL→workflow są w doql/: doql/adopt/scanner/interfaces/{mcp,cli}.py, doql/importers/oql_converter.py.

Instalacja dev (wszystkie paczki workspace):

uv sync --extra deploy
# lub: pip install -e ".[dev]" -e packages/mcp2doql -e packages/cli2doql ...

articles/ — artykuły WordPress

Sześć artykułów markdown z YAML front-matter gotowych do publikacji (kompatybilne z wp-cli i WordPress REST API). Każdy artykuł to jeden projekt / jedna nowość.

Lista:

  1. 01-oqlos-status-2026-q2.md — status oqlos po refaktorze (CC̄ 3,7→3,2)
  2. 02-testql-status-2026-q2.md — TestQL, porównanie z Playwright
  3. 03-saas-www-status-2026-q2.md — SaaS oqlos.com, 5 bugów P0, diagnoza landingu
  4. 04-doql-ogloszenie.md — ogłoszenie doql v0.1 (SaaS generator)
  5. 05-wizja-ekosystemu-oqlos.md — wizja całej rodziny (4 warstwy, strategia open-core)
  6. 06-doql-v02-dokumenty-kiosk.md — doql v0.2 (dokumenty, kiosk, semantyka)

Każdy 800-1800 słów, po polsku, gotowy do kopiuj-wklej do WordPressa.

Jak to odpalić

Instalacja doql (po sklonowaniu do repo)

cd doql/
pip install -e .
doql --version

Przykłady użycia CLI

Inicjalizacja nowego projektu

# Utwórz nowy projekt z szablonu
doql init my-app --template minimal
cd my-app

# Lista dostępnych szablonów
doql init - --list-templates

Reverse-engineer istniejącego projektu

# Zeskanuj istniejący projekt → app.doql.less
doql adopt ./my-project --force

# Zeskanuj zdalne urządzenie przez SSH
doql adopt --from-device pi@kiosk-01.local --format css

# Zbuduj w innym folderze
cp app.doql.less /tmp/rebuild/
cd /tmp/rebuild
doql build --force

Minimalny przykład — Todo PWA

cd examples/todo-pwa
doql validate                    # sprawdź deklarację
doql plan                        # podgląd co zostanie wygenerowane
doql build                       # generuj kod
doql run -t api                 # uruchom API na http://localhost:8000
doql run -t mobile              # uruchom PWA na http://localhost:8091

Asset Management — pełen stack (API + Web + Mobile + Desktop)

cd examples/asset-management
cp .env.example .env
doql validate
doql build

doql run -t api        # FastAPI → http://localhost:8000/docs
doql run -t web        # React   → http://localhost:5173
doql run -t mobile     # PWA     → http://localhost:8091
doql run -t desktop    # Tauri desktop app (wymaga Rust)
doql run               # pełny stack via docker-compose

Laboratorium kalibracyjne ISO 17025

cd examples/calibration-lab
doql validate
doql build
doql run -t api        # FastAPI → http://localhost:8000/docs
doql run -t web        # React   → http://localhost:5173

Generator PDF (świadectwa kalibracyjne)

cd examples/document-generator
cp .env.example .env
doql validate
doql build
doql run -t web        # htmx UI → http://localhost:8080

# Generowanie pojedynczego dokumentu (nazwa musi pasować do DOCUMENT w pliku .doql):
doql generate calibration_certificate

CRM Contacts

cd examples/crm-contacts
doql validate
doql build
doql run -t api        # FastAPI → http://localhost:8000/docs
doql run -t web        # React   → http://localhost:5173

IoT Fleet Manager (Kubernetes)

cd examples/iot-fleet
doql validate
doql build
doql run -t api        # FastAPI → http://localhost:8000/docs
doql run -t web        # React + Leaflet map → http://localhost:5173

Kiosk Station (Raspberry Pi)

cd examples/kiosk-station
doql validate
doql build

# Instalacja na urządzeniu:
scp -r build/infra pi@kiosk-01.local:/tmp/
ssh pi@kiosk-01.local "sudo /tmp/infra/install-kiosk.sh && sudo reboot"

Deployment via redeploy (v1.0+)

# Instaluj z opcjonalnym deploy support
cd examples/asset-management
pip install "doql[deploy]>=1.0.0"

# Build generuje migration.yaml
doql build

# Deploy do środowiska dev (wymaga redeploy>=0.2.0)
doql deploy --env dev

# Deploy do Podman Quadlet (rootless)
doql quadlet --install

Synchronizacja zmian (merge-friendly)

# Re-generuj tylko zmienione części (bez nadpisywania ręcznych zmian)
doql sync

# Synchronizacja w innym katalogu
doql -d examples/asset-management sync

Eksport do innych formatów

# Eksport specyfikacji do CSS
doql export --format css -o spec.doql.css

# Eksport do LESS ze zmiennymi
doql export --format less -o spec.doql.less

# Eksport do SASS
doql export --format sass -o spec.doql.sass

# Eksport OpenAPI spec
doql export --format openapi -o openapi.yaml

# Eksport Postman collection
doql export --format postman -o collection.json

# Eksport TypeScript SDK
doql export --format typescript-sdk -o sdk/

# Eksport dokumentacji Markdown
doql export --format markdown -o docs/

# Eksport YAML
doql export --format yaml -o spec.yaml

Import z YAML

# Import YAML → .doql
doql import spec.yaml --format css -o app.doql.css

# Import z konwersją do LESS
doql import spec.yaml --format less -o app.doql.less

Generowanie pojedynczych artefaktów

# Generuj pojedynczy dokument (nazwa musi pasować do DOCUMENT w pliku .doql)
doql generate calibration_certificate

# Generuj raport
doql generate monthly_report

Renderowanie szablonów

# Renderuj szablon z danymi
doql render templates/invoice.jinja2

Query — zapytania do źródeł danych

# Zapytaj źródło danych i zwróć JSON
doql query customer_db

# Z zapytaniem w kontekście innym niż CWD
doql -d examples/asset-management query devices

Kiosk — zarządzanie urządzeniami kiosk

# Instalacja kiosk na obecnym urządzeniu (Raspberry Pi)
doql kiosk --install

# Zbuduj i zainstaluj
cd examples/kiosk-station
doql build && doql kiosk --install

Quadlet — Podman rootless

# Instalacja Quadlet do systemd (rootless)
doql quadlet --install

# Sprawdź status
doql doctor --env local

Dokumentacja

# Generuj stronę dokumentacji z projektu
doql docs

# Zapisz do konkretnego folderu
doql docs && cp -r build/docs /var/www/html/

Diagnostyka projektu

# Diagnostyka lokalnego projektu
doql doctor

# Diagnostyka zdalnego środowiska
doql doctor --env staging

# Napraw automatycznie wykryte problemy
doql doctor --fix

Drift — porównanie z rzeczywistością

# Porównaj deklarację ze stanem zdalnego urządzenia
doql drift --from-device pi@kiosk-01.local

# Wyjście JSON (machine-readable)
doql drift --from-device pi@kiosk-01.local --json

# Porównanie z konkretnym plikiem
doql drift --from-device pi@kiosk-01.local --file app.doql.less

Publikacja artefaktów

# Publikuj wszystko (PyPI, npm, Docker, GitHub)
doql publish

# Tylko wybrane targety
doql publish --target pypi,docker

# Symulacja (dry-run)
doql publish --dry-run

Uwaga: doql run vs doql -d ... run

# z katalogu projektu — krótsza forma:
cd examples/asset-management
doql run -t desktop

# z dowolnego miejsca — z flagą -d:
doql -d examples/asset-management run -t desktop
doql -d examples/notes-app run -t web

Szybki start z CLI shell (alternatywa)

# Generuj i uruchom desktop app
./doql.sh examples/notes-app/app.doql desktop

# Generuj i uruchom web
./doql.sh examples/notes-app/app.doql web

# Generuj wszystko
./doql.sh examples/notes-app/app.doql all

doql workspace — operacje na wielu projektach

Gdy trzymasz kilka projektów z app.doql.css w jednym folderze (np. ~/github/oqlos/), doql workspace pozwala na grupowe operacje.

# Wylistuj wszystkie projekty z app.doql.css (głębokość 2)
doql workspace list --root ~/github/oqlos --depth 2

# Przeanalizuj wszystkie projekty: workflowy, entity, bazy, interfejsy
doql workspace analyze --root ~/github/oqlos

# Eksport do CSV (do arkusza / BI / raportu)
doql workspace analyze --root ~/github/oqlos -o oqlos_report.csv

# Walidacja manifestów (puste workflowy, brak sekcji app{}, itp.)
doql workspace validate --root ~/github/oqlos
doql workspace validate --root ~/github/oqlos --strict   # exit 1 przy błędach

# Filtrowanie po obecności workflowa
doql workspace list --root ~/github/oqlos --has-workflow test

# Uruchomienie `doql <action>` we wszystkich projektach
doql workspace run validate --root ~/github/oqlos --dry-run
doql workspace run validate --root ~/github/oqlos
doql workspace run build    --root ~/github/oqlos --fail-fast

# Naprawa błędów w manifestach (wymaga `pip install taskfile`)
doql workspace fix --root ~/github/oqlos --dry-run
doql workspace fix --root ~/github/oqlos

Podstawowa pętla (list/analyze/validate/run) działa bez dodatkowych zależności. Komenda fix używa taskfile.workspace do napraw (puste workflowy, orphans, brakujące workflowy z Taskfile.yml) — zainstaluj pip install taskfile, aby odblokować.

Pełna dokumentacja i równoważna komenda taskfile workspace: zob. pyfunc/taskfile/docs/WORKSPACE.md.

Publikacja artykułów

Opcja A — ręcznie do WP (najprostsze):

  1. Skopiuj treść pliku .md bez front-matter
  2. Wklej w edytorze WordPress (tryb Markdown jeśli masz plugin)
  3. Tytuł, slug, kategorie, tagi z YAML front-matter

Opcja B — wp-cli:

for file in articles/*.md; do
  # yq wyciąga pola z front-matter, sed wycina YAML z body
  title=$(yq -r '.title' "$file")
  slug=$(yq -r '.slug' "$file")
  body=$(sed '/^---$/,/^---$/d' "$file")
  wp post create --post_title="$title" --post_name="$slug" \
    --post_content="$body" --post_status=publish
done

Opcja C — GitHub Action z WP REST API (plik .github/workflows/publish.yml — nie dołączony, łatwo dopisać).

Formaty plików .doql

doql obsługuje cztery równoważne formaty specyfikacji:

Format Rozszerzenie Styl
Classic .doql indentacja YAML-like
CSS .doql.css entity[name="X"] { ... }
LESS .doql.less CSS + zmienne @var
SASS .doql.sass CSS + zmienne $var, indent-based

Wszystkie formaty parsują się do tego samego DoqlSpec — można mieszać w projekcie i konwertować:

# Eksport do innego formatu
doql export --format less -o spec.doql.less

# Import z YAML
doql import spec.yaml --format css -o app.doql

Każdy example zawiera zarówno wersję .doql jak i wersję CSS-like (.doql.css / .doql.less / .doql.sass).

Architektura — jak się to wszystko łączy

┌─────────────────────────────────────────────┐
│   doql file (.doql / .doql.css / .less / …) │
│   deklaracja CO ma powstać                  │
└──────────────┬──────────────────────────────┘
               │  doql build
               ▼
   ┌───────────┴───────────┬──────────────┬─────────────┐
   ▼                       ▼              ▼             ▼
 ┌────┐   ┌────┐   ┌──────────┐   ┌────────┐   ┌──────────┐
 │API │   │Web │   │ Mobile/  │   │Kiosk   │   │Documents │
 │    │   │    │   │ Desktop  │   │        │   │PDF/HTML  │
 └─┬──┘   └────┘   └──────────┘   └────────┘   └──────────┘
   │
   │ wywołuje scenariusze .oql
   ▼
 ┌────────────────────────────────────┐
 │ oqlos runtime (interpretuje .oql)  │
 └──────────────┬─────────────────────┘
                │ Modbus / MQTT / USB / GPIO
                ▼
         ┌────────────┐
         │  Hardware  │
         └────────────┘

Testy aplikacji (.testql.toon.yaml) → testql → Playwright-alternative z integracją hardware.

Co dalej

Zrealizowane (Fazy 0–4):

Następne kroki:

Q3-Q4:

Licencja

Premium plugins doql (komercyjne) — osobne warunki, patrz doql/LICENSE.

Kontakt

License

Licensed under Apache-2.0.

Architecture

This site is open source. Improve this page.