doql

doql — Declarative OQL: build apps from .doql files

Co to jest

doql (PyPI) to declarative infrastructure-as-code w formacie .doql (LESS-like syntax) — pojedynczy plik app.doql.less opisuje pełną strukturę aplikacji: workflows, dependencies, runtime, deployment.

W koru doql jest companion-em dla:

• sumr — auto-generuje boilerplate app.doql.less przy sumr .
• redeploy — doql adopt --from-device snapshot rzeczywistego stanu device do app.doql.less (intended state dla drift detection)
• op3 — feeduje doql warstwami obserwacji (Physical/OS/Service/...)

Kiedy używać

Scenariusz	Komenda
Opisz nowy projekt declaratively	doql init (template wizard)
Reverse-engineer istniejący repo	doql adopt . → wygeneruje app.doql.less
Generuj artefakty (SDK, OpenAPI, docker)	doql build lub doql generate <type>
Dry-run (zobacz co wygeneruje)	doql plan
Sync zmian z .doql → kod	doql sync
Walidacja app.doql.less + .env	doql validate
Drift detection vs live device	doql drift
Snapshot device state	doql adopt --from-device user@host
Health check projektu	doql doctor
Generuj Podman Quadlet z DOQL	doql quadlet
Multi-project workspace ops	doql workspace ...

Konfiguracja

app.doql.less (root projektu)

LESS-syntax declarative description:

// Generated by sumd / hand-written

app {
  name: <APP_NAME>;
  version: 1.0.0;
}

interface[type="cli"] {
  framework: click;
}

workflow[name="install"]    { command: pip install -e .; }
workflow[name="dev"]        { command: python -m <APP_NAME>; }
workflow[name="build"]      { command: python -m build; }
workflow[name="test"]       { command: pytest tests/ -v; }
workflow[name="lint"]       { command: ruff check src tests; }

runtime[type="container"] {
  image: localhost/<APP_NAME>:latest;
  ports: 8000:8000;
}

endpoint[type="http"][path="/health"] {
  expected_status: 200;
}

Env vars

Env var	Cel
DOQL_VERBOSE=1	szczegółowe logi
DOQL_DRY_RUN=1	nie zapisuj plików

Komendy

doql --version
doql --help

# Bootstrap nowego projektu
doql init                         # interactive template wizard
doql init --template python-cli   # explicit template

# Adopt istniejącego repo
doql adopt .                      # generate app.doql.less based on detection
doql adopt . -f                   # force regenerate
doql adopt --from-device user@host -o app.doql.less   # SSH device snapshot

# Build artefakty
doql plan                         # dry-run, show what would generate
doql build                        # generate all
doql sync                         # re-generate changed parts (merge-friendly)
doql generate <artifact>          # single artifact (openapi, postman, ts-sdk)
doql export --format markdown     # export do dokumentacji

# Drift detection
doql drift                        # compare app.doql.less vs current state
doql drift --layer service        # tylko service layer
doql drift --device user@host     # przeciw device

# Diagnostyka
doql validate                     # check app.doql.less + .env
doql doctor                       # auto-fix common issues

# Specjalne
doql quadlet                      # generate Podman Quadlet units
doql kiosk                        # kiosk appliance management
doql workspace status             # multi-project ops

Integracja z koru

Plik	Rola
app.doql.less (root)	declarative state — generated przez sumr . (sumd's --generate-doql flag)
templates/redeploy/device/manifest.yaml.template	używa doql adopt --from-device w phase: detect
templates/redeploy/device/diagnose.md.template	drift check przeciw app.doql.less
Taskfile.yml → deploy:drift	doql adopt --from-device "{{.DEVICE_HOST}}" -o app.doql.less

W koru pełny drift loop:

# 1. Po deploy:
task deploy:device DEVICE=edge01

# 2. Snapshot intended state:
task deploy:drift DEVICE_HOST=user@edge01
# → doql adopt --from-device user@edge01 -o app.doql.less

# 3. Commit baseline:
git add app.doql.less
git commit -m "chore(deploy): snapshot intended state for edge01"

# 4. Następne deploy widzi drift jeśli ktoś ad-hoc zmienił device

Reference deployment (c2004)

Produkcyjnie w maskservice/c2004:

Plik	Rola
app.doql.less	intended state c2004 (pełna deklaracja: 6 services + Traefik + endpoints)
redeploy/pi109/manifest.yaml:34	intended_state: app.doql.less
redeploy/pi109/manifest.yaml:165-171	drift.intended_file: app.doql.less + action_on_drift: pause
Taskfile.yml → deploy:drift (analogiczny do koru)	doql adopt --from-device pi@192.168.188.109

Workflow: sumd → doql → redeploy

Trzy narzędzia tworzą pipeline:

sumd .                       # wygeneruje SUMR.md + app.doql.less (boilerplate)
  ↓
[edit app.doql.less manualnie albo doql adopt z device]
  ↓
doql validate                # sanity check
doql build                   # generate code/artifacts z DOQL
  ↓
redeploy run <spec>          # apply state to target
  ↓
doql adopt --from-device     # snapshot actual state
  ↓
doql drift                   # compare intended vs actual → loop

Troubleshooting

Problem	Rozwiązanie
doql: command not found	pip install --user --upgrade doql
app.doql.less syntax error	doql validate pokaże dokładną linię
Drift fałszywy positive	sprawdź doql drift --layer <name> — może być specific layer
doql adopt --from-device SSH timeout	dodaj --ssh-timeout 30 lub sprawdź ssh user@host 'echo ok'
Generated code overwrites custom	doql sync jest merge-friendly; doql build overwrites
Quadlet generation broken	sprawdź runtime[type="container"] block w app.doql.less

Linki

• Repo / PyPI: https://pypi.org/project/doql/
• Reference: c2004 app.doql.less + redeploy/pi109/manifest.yaml
• Companion: sumd (auto-generates boilerplate), op3 (multi-layer obs), redeploy (apply state)