Skip to content

Commit b8fda21

Browse files
claudeclaude
committed
NIC-VDE: clean baseline (v1.2, post deep review)
Single squashed commit of the reviewed, cleaned ecosystem state: third_party drift fixed via sync_vendor + CI, docs/naming/comments unified to English, all libraries on v1.2. Replaces the prior incremental history. https://claude.ai/code/session_01UTLgeynyvS72gVeytasCfG
0 parents  commit b8fda21

35 files changed

Lines changed: 6373 additions & 0 deletions

‎.github/workflows/vendor-sync-check.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: vendor-sync-check
2+
3+
# Fails if any file under third_party/ has drifted from its canonical source in
4+
# the NIC-MLA / NIC-DMD repos. The mapping lives in tools/vendor_manifest.txt;
5+
# to update the copies run `python3 tools/sync_vendor.py` and commit the result.
6+
7+
on:
8+
push:
9+
branches: ["**"]
10+
pull_request:
11+
12+
jobs:
13+
check:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout this repo
17+
uses: actions/checkout@v4
18+
19+
# The canonical libraries live in sibling repos. Checking them out here
20+
# lets us diff the vendored copies against the real source. For private
21+
# repos the default GITHUB_TOKEN cannot read other repos — set a
22+
# NIC_SYNC_TOKEN secret (a PAT/fine-grained token with read access) then.
23+
- name: Checkout canonical NIC-MLA
24+
uses: actions/checkout@v4
25+
with:
26+
repository: project-nic/nic-mla
27+
path: _sources/nic-mla
28+
token: ${{ secrets.NIC_SYNC_TOKEN || github.token }}
29+
30+
- name: Checkout canonical NIC-DMD
31+
uses: actions/checkout@v4
32+
with:
33+
repository: project-nic/nic-dmd
34+
path: _sources/nic-dmd
35+
token: ${{ secrets.NIC_SYNC_TOKEN || github.token }}
36+
37+
- name: Set up Python
38+
uses: actions/setup-python@v5
39+
with:
40+
python-version: "3.x"
41+
42+
- name: Verify vendored copies are in sync
43+
env:
44+
NIC_SRC_DIR: ${{ github.workspace }}/_sources
45+
run: python3 tools/sync_vendor.py --check --require-sources

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.egg-info/
4+
.venv/
5+
venv/
6+
.pytest_cache/
7+
*.mla
8+
*.MLA
9+
# keep the committed sample for GUI development
10+
!samples/weather.mla

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
MIT License
2+
3+
Copyright (c) 2026 NIC — Native Intellect Community
4+
Project-NIC/NIC-VDE
5+
6+
Permission is hereby granted, free of charge, to any person obtaining a copy
7+
of this software and associated documentation files (the "Software"), to deal
8+
in the Software without restriction, including without limitation the rights
9+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10+
copies of the Software, and to permit persons to whom the Software is
11+
furnished to do so, subject to the following conditions:
12+
13+
The above copyright notice and this permission notice shall be included in all
14+
copies or substantial portions of the Software.
15+
16+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22+
SOFTWARE.

‎NICVDE.svg‎

Lines changed: 261 additions & 0 deletions
Loading

‎README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<p align="center">
2+
<img src="NICVDE.svg" width="200"/>
3+
</p>
4+
5+
# Volkov Data Ecosystem
6+
7+
*[English](README.md) · [Čeština](README_cs.md) · [Русский](README_ru.md)*
8+
9+
10+
A cross-platform, two-pane file manager in the style of **Volkov Commander**,
11+
written in Python on **prompt_toolkit**. It browses the local filesystem and
12+
steps *inside* **NIC-MLA** containers, showing each logged record as a file.
13+
14+
> Status: **1.2** — built against **NIC-MLA v1.2**. Two-pane browsing, file
15+
> operations, file/record viewer, and an MLA backend that browses and views
16+
> records — with limited editing of the self-describing tables (not a general
17+
> record editor, and not strictly read-only). MLA is a deliberately *dumb*
18+
> container, so the backend leans on those tables: the **schema table** decodes
19+
> each packed payload into real values + units, and the **station table** turns
20+
> the log's 1-byte station index into real region/number — both flow straight
21+
> into CSV/SQL export, and both are editable in place via the `F4` table editor.
22+
>
23+
> The design mirrors MLA's own philosophy — **dumb libraries + thin glue**:
24+
> reusable, format-aware libraries underneath (`export`, plus the vendored MLA +
25+
> its schema reader), with the backends as thin adapters on top. All of
26+
> `volkov_core/` is GUI-free, so it can be reused headless.
27+
28+
## Run
29+
30+
```bash
31+
pip install -r requirements.txt
32+
python3 volkov_data.py [left_dir] [right_dir]
33+
```
34+
35+
**Keys**
36+
37+
| Key | Action |
38+
|---|---|
39+
| `Tab` | switch panel |
40+
| `↑/↓ PgUp/PgDn Home/End` | move cursor |
41+
| `Enter` | open dir / step into `.mla` / go up (`..`) |
42+
| `F1` | info about the selected item / record |
43+
| `F2` | check an `.mla` container — report valid / dead / damaged slots |
44+
| `F3` | view file or record payload (text/hex) |
45+
| `F4` | on a record: decoded value(s) + units · on `..` inside an editable `.mla`: schema/station table editor |
46+
| `F5` | copy selected file to the other panel |
47+
| `F6` | rename or move — inside an `.mla`, export all records to CSV |
48+
| `F7` | make directory |
49+
| `F8` | delete (with confirmation) |
50+
| `F9` | pull-down menu (sorting, language, export to SQL, …) |
51+
| `F10` / `q` / `Ctrl-Q` | quit · `Esc` closes any overlay |
52+
53+
Press `Enter` on `samples/weather.mla` to step inside and browse its records.
54+
55+
## Tests
56+
57+
The `volkov_core/` logic is GUI-free, so it is covered by a stdlib `unittest`
58+
suite (no extra dependencies):
59+
60+
```bash
61+
python3 -m unittest discover -s tests
62+
```
63+
64+
The tests build throwaway MLA containers on the fly and also smoke-test the
65+
committed `samples/weather.mla`.
66+
67+
## Layout
68+
69+
```
70+
volkov_data.py prompt_toolkit GUI (thin shell over volkov_core)
71+
volkov_core/ GUI-free logic — reusable headless
72+
backend.py storage-backend abstraction (VdeEntry / VdeBackend)
73+
local.py VdeLocalBackend — host filesystem
74+
mla.py VdeMlaBackend — thin adapter: records as "files",
75+
schema decode + station resolve + export
76+
export.py dumb library — generic rows → CSV / SQLite bytes
77+
stations.py glue — station index → real region/number
78+
samples/make_sample.py generator for a self-describing sample datalogger file
79+
samples/weather.mla committed sample (packed rows + schema + stations)
80+
tests/ stdlib unittest suite for volkov_core (GUI-free)
81+
third_party/nic_mla/ vendored NIC-MLA (Python reference) — canonical data format
82+
third_party/nic_dmd/ vendored NIC-DMD — decodes compressed (keyframe/delta) records
83+
tools/mla_schema.py host-only schema/station builders + readers (VDE links)
84+
85+
The desktop reads the logger format through MLA's Python reference
86+
(`third_party/nic_mla/nic_mla.py`) and decodes payloads + stations via the
87+
host-only reader (`tools/mla_schema.py`), both kept byte-identical to the C core.
88+
The Volkov Commander sources are a **behavior reference only** — not ported code.
89+
90+
```
91+
## License
92+
93+
MIT License — Copyright (c) 2026 NIC — Native Intellect Community
94+
95+
---
96+
97+
## Acknowledgements
98+
99+
To my brother for advice during the development of this project.
100+
For technical assistance with code optimisation, to AI assistants Claude (Anthropic) and Gemini (Google).
101+
102+
★ Viva La Resistánce ★

‎README_cs.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<p align="center">
2+
<img src="NICVDE.svg" width="200"/>
3+
</p>
4+
5+
# Volkov Data Ekosystém
6+
7+
*[English](README.md) · [Čeština](README_cs.md) · [Русский](README_ru.md)*
8+
9+
10+
Multiplatformní dvoupanelový souborový manažer ve stylu **Volkov Commanderu**,
11+
napsaný v Pythonu nad knihovnou **prompt_toolkit**. Prochází místní souborový
12+
systém a umí *vstoupit dovnitř* kontejnerů **NIC-MLA**, kde každý zalogovaný
13+
záznam zobrazí jako soubor.
14+
15+
> Stav: **1.2** — postaveno nad **NIC-MLA v1.2**. Dvoupanelové procházení,
16+
> souborové operace, prohlížeč souborů i záznamů a MLA backend, který prochází
17+
> a zobrazuje záznamy — s omezenými úpravami self-describing tabulek (není to
18+
> obecný editor záznamů ani čistě jen prohlížeč). MLA je záměrně *hloupý*
19+
> kontejner, takže se backend opírá o tyto tabulky: **schema tabulka** dekóduje
20+
> každý packed payload na reálné hodnoty + jednotky a **station tabulka** přeloží
21+
> 1bajtový index stanice z logu na reálný region/number — obojí jde rovnou do
22+
> CSV/SQL exportu a obojí lze upravovat na místě editorem tabulek pod `F4`.
23+
>
24+
> Návrh zrcadlí filozofii samotného MLA — **hloupé knihovny + tenké lepidlo**:
25+
> dole znovupoužitelné knihovny (`export` plus přibalené MLA i jeho reader),
26+
> backendy jsou nad nimi jen tenké adaptéry. Celé `volkov_core/` je bez GUI,
27+
> takže ho lze použít i samostatně.
28+
29+
## Spuštění
30+
31+
```bash
32+
pip install -r requirements.txt
33+
python3 volkov_data.py [levý_adresář] [pravý_adresář]
34+
```
35+
36+
**Klávesy**
37+
38+
| Klávesa | Akce |
39+
|---|---|
40+
| `Tab` | přepnout panel |
41+
| `↑/↓ PgUp/PgDn Home/End` | pohyb kurzoru |
42+
| `Enter` | otevřít adresář / vstoupit do `.mla` / o úroveň výš (`..`) |
43+
| `F1` | informace o vybrané položce / záznamu |
44+
| `F2` | kontrola kontejneru `.mla` — počet platných / mrtvých / poškozených slotů |
45+
| `F3` | zobrazit obsah souboru nebo záznamu (text/hex) |
46+
| `F4` | na záznamu: dekódované hodnoty + jednotky · na `..` v editovatelné `.mla`: editor schématu/stanic |
47+
| `F5` | kopírovat vybraný soubor do druhého panelu |
48+
| `F6` | přejmenovat nebo přesunout — uvnitř `.mla` export všech záznamů do CSV |
49+
| `F7` | vytvořit adresář |
50+
| `F8` | smazat (s potvrzením) |
51+
| `F9` | rozbalovací menu (třídění, jazyk, export do SQL, …) |
52+
| `F10` / `q` / `Ctrl-Q` | konec · `Esc` zavře jakékoli překryvné okno |
53+
54+
Stiskem `Enter` na `samples/weather.mla` vstoupíš dovnitř a procházíš jeho záznamy.
55+
56+
## Testy
57+
58+
Logika v `volkov_core/` je bez GUI, takže ji pokrývá sada testů ve standardní
59+
knihovně `unittest` (bez dalších závislostí):
60+
61+
```bash
62+
python3 -m unittest discover -s tests
63+
```
64+
65+
Testy si za běhu vytvářejí dočasné MLA kontejnery a navíc otestují i přiložený
66+
vzorek `samples/weather.mla`.
67+
68+
## Struktura
69+
70+
```
71+
volkov_data.py GUI v prompt_toolkit (tenká slupka nad volkov_core)
72+
volkov_core/ logika bez GUI — použitelná samostatně
73+
backend.py abstrakce úložného backendu (VdeEntry / VdeBackend)
74+
local.py VdeLocalBackend — souborový systém hostitele
75+
mla.py VdeMlaBackend — tenký adaptér: záznamy jako „soubory“,
76+
dekódování dle schématu + překlad stanice + export
77+
export.py hloupá knihovna — generické řádky → CSV / SQLite
78+
stations.py lepidlo — index stanice → reálný region/number
79+
samples/make_sample.py generátor self-describing vzorku meteostanice
80+
samples/weather.mla přiložený vzorek (packed řádky + schéma + stanice)
81+
tests/ sada testů unittest pro volkov_core (bez GUI)
82+
third_party/nic_mla/ přibalená NIC-MLA (Python reference) — kanonický datový formát
83+
third_party/nic_dmd/ přibalená NIC-DMD — dekóduje komprimované (keyframe/delta) záznamy
84+
tools/mla_schema.py host-only buildery + readery schématu/stanic (VDE je linkuje)
85+
```
86+
87+
Aplikace čte formát loggeru přes referenční Python implementaci MLA
88+
(`third_party/nic_mla/nic_mla.py`) a dekóduje payloady i stanice přes host-only
89+
reader (`tools/mla_schema.py`), obojí udržované bajt po bajtu shodné s C jádrem.
90+
Zdrojáky Volkov Commanderu slouží **jen jako vzor chování** — nejde o přepsaný kód.
91+
92+
---
93+
94+
## Licence
95+
96+
MIT License — Copyright (c) 2026 NIC — Native Intellect Community
97+
98+
---
99+
100+
## Poděkování
101+
102+
Bratrovi za rady při tvorbě tohoto projektu.
103+
Za technickou asistenci s optimalizací kódu AI asistentům Claude (Anthropic) a Gemini (Google).
104+
105+
★ Viva La Resistánce ★

‎README_ru.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<p align="center">
2+
<img src="NICVDE.svg" width="200"/>
3+
</p>
4+
5+
# Volkov Data Ecosystem
6+
7+
*[English](README.md) · [Čeština](README_cs.md) · [Русский](README_ru.md)*
8+
9+
Кроссплатформенный двухпанельный файловый менеджер в стиле **Volkov Commander**,
10+
написанный на Python с использованием **prompt_toolkit**. Просматривает локальную
11+
файловую систему и умеет *заходить внутрь* контейнеров **NIC-MLA**, показывая
12+
каждую записанную запись как файл.
13+
14+
> Статус: **1.2** — построено на **NIC-MLA v1.2**. Двухпанельный просмотр,
15+
> файловые операции, просмотрщик файлов и записей, а также MLA-бэкенд для
16+
> просмотра записей — с ограниченным редактированием самоописывающих таблиц
17+
> (это не универсальный редактор записей и не строго «только чтение»). MLA —
18+
> намеренно *глупый* контейнер, поэтому бэкенд опирается на эти таблицы:
19+
> **таблица схемы** декодирует каждый упакованный payload в реальные значения +
20+
> единицы, а **таблица станций** превращает 1-байтовый индекс станции из лога в
21+
> реальные регион/номер — и то и другое сразу попадает в экспорт CSV/SQL и то и
22+
> другое можно править на месте редактором таблиц по `F4`.
23+
>
24+
> Архитектура повторяет философию самого MLA — **глупые библиотеки + тонкий
25+
> клей**: внизу переиспользуемые библиотеки (`export` плюс встроенный MLA и его
26+
> ридер), а бэкенды над ними — лишь тонкие адаптеры. Весь `volkov_core/` не
27+
> зависит от GUI, поэтому пригоден и для использования без интерфейса.
28+
29+
## Запуск
30+
31+
```bash
32+
pip install -r requirements.txt
33+
python3 volkov_data.py [левый_каталог] [правый_каталог]
34+
```
35+
36+
**Клавиши**
37+
38+
| Клавиша | Действие |
39+
|---|---|
40+
| `Tab` | переключить панель |
41+
| `↑/↓ PgUp/PgDn Home/End` | перемещение курсора |
42+
| `Enter` | открыть каталог / войти в `.mla` / на уровень вверх (`..`) |
43+
| `F1` | сведения о выбранном элементе / записи |
44+
| `F2` | проверка контейнера `.mla` — число корректных / мёртвых / повреждённых слотов |
45+
| `F3` | просмотр содержимого файла или записи (текст/hex) |
46+
| `F4` | на записи: значения + единицы · на `..` в редактируемой `.mla`: редактор схемы/станций |
47+
| `F5` | копировать выбранный файл на другую панель |
48+
| `F6` | переименовать или переместить — внутри `.mla` экспорт всех записей в CSV |
49+
| `F7` | создать каталог |
50+
| `F8` | удалить (с подтверждением) |
51+
| `F9` | выпадающее меню (сортировка, язык, экспорт в SQL, …) |
52+
| `F10` / `q` / `Ctrl-Q` | выход · `Esc` закрывает любое всплывающее окно |
53+
54+
Нажмите `Enter` на `samples/weather.mla`, чтобы войти внутрь и просмотреть его записи.
55+
56+
## Тесты
57+
58+
Логика в `volkov_core/` не зависит от GUI, поэтому покрыта набором тестов на
59+
стандартной библиотеке `unittest` (без дополнительных зависимостей):
60+
61+
```bash
62+
python3 -m unittest discover -s tests
63+
```
64+
65+
Тесты создают временные MLA-контейнеры на лету, а также проверяют приложенный
66+
образец `samples/weather.mla`.
67+
68+
## Структура
69+
70+
```
71+
volkov_data.py GUI на prompt_toolkit (тонкая оболочка над volkov_core)
72+
volkov_core/ логика без GUI — пригодна для самостоятельного использования
73+
backend.py абстракция бэкенда хранилища (VdeEntry / VdeBackend)
74+
local.py VdeLocalBackend — файловая система хоста
75+
mla.py VdeMlaBackend — тонкий адаптер: записи как «файлы»,
76+
декодирование по схеме + разбор станции + экспорт
77+
export.py глупая библиотека — обобщённые строки → CSV / SQLite
78+
stations.py клей — индекс станции → реальные регион/номер
79+
samples/make_sample.py генератор самоописывающего образца метеостанции
80+
samples/weather.mla приложенный образец (упакованные строки + схема + станции)
81+
tests/ набор тестов unittest для volkov_core (без GUI)
82+
third_party/nic_mla/ встроенный NIC-MLA (Python reference) — канонический формат данных
83+
third_party/nic_dmd/ встроенный NIC-DMD — декодирует сжатые (keyframe/delta) записи
84+
tools/mla_schema.py host-only сборщики и ридеры схемы/станций (VDE их линкует)
85+
```
86+
87+
Приложение читает формат логгера через эталонную Python-реализацию MLA
88+
(`third_party/nic_mla/nic_mla.py`) и декодирует payload-ы и станции через
89+
host-only ридер (`tools/mla_schema.py`), оба поддерживаются побайтово
90+
идентичными ядру на C. Исходники Volkov Commander служат **только образцом
91+
поведения** — это не портированный код.
92+
93+
---
94+
95+
## Лицензия
96+
97+
Лицензия MIT — Авторское право (c) 2026 NIC — Native Intellect Community
98+
99+
---
100+
101+
## Благодарности
102+
103+
Брату за советы при создании этого проекта.
104+
За техническую помощь при оптимизации кода помощникам ИИ Claude (Anthropic) и Gemini (Google).
105+
106+
★ Viva La Resistánce ★

‎requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
prompt_toolkit>=3.0

0 commit comments

Comments
 (0)