README.md

# Простое демонстрационное расширение c node интеграцией

# 1. Общая инфрмация

1. Описание расширения находится в `package.json`
1. Инициализация расширения происходит в скрипте `root.ts` (`front`/`renderer` процесс)
1. Инициализация корневого скрипта с "node" интеграцией происходит в `root_node.ts` ("main" процесс)
1. Расширение добавляет вкладку "Демонстрационная вкладка 2" на левую панель управления, которая состоит из:
   - `static/control_panel/cp_tab.html`: описание структуры вкладки
   - `static/control_panel/cp_tab.css`: описание стилей элементов (загружается из `cp_tab.html` файла)
   - `src/control_panel/cp_tab.ts`: скрипт с логикой (загружается из `cp_tab.html` файла)
1. Данная вкладка содержит:
   - Заголовок "Демонстрационная вкладка 2"
   - Кнопки открытия основной ("рабочей" вкладки) с параметрами запуска "скрипта маршрута":
     - `open-script`: при нажатии открывается новая вкладка в основной панели ("main_panel")
1. Вкладка с конфигурацией "срипта маршрута" сотоит из:
   - `static/main_panel/mp_tab.html`: описание структуры вкладки
   - `static/main_panel/mp_tab.css`: описание стилей элементов (загружается из `mp_tab.html` файла)
   - `src/main_panel/mp_tab.ts`: скрипт с логикой (загружается из `mp_tab.html` файла)
1. Данная вкладка содержит:
   - Конфигурируемые входные параметры скрипта различных типов данных:
     - Параметр 1 (текст), обязательный
     - Параметр 2 (тумплер), опциональный
     - Параметр 3 (число), опциональный
   - Кнопка запуска скрипта "Запуск"
     - При выполнении скрипта логируется его вывод в отладочную консоль

Отладочную консоль можно открыть используя верхнее меню: `Developer` -> `Toggle Developer Tools`

# 2. Предварительная настройка окружения

1. Установить `nvm`
   - https://github.com/nvm-sh/nvm
   - Linux & MacOS: `brew install nvm`
   - Windows: `winget install nvm-windows`
1. Установить `node 20.16.0`
   - ```sh
     nvm install 20.16.0
     nvm use 20.16.0
     nvm alias default 20.16.0 # for Linux and MacOS
     node --version # check
     ```
1. Включить менеджер пакетов `yarn`
   - ```sh
     corepack enable
     yarn --version # check
     ```
1. Установить актуальную версию `yarn 4.2.1`
   - ```sh
     yarn set version berry
     yarn --versuin # check
     ```

# 3. Запуск платформы UNIAPP/TRUAPP

1. Для запуска ПО платформы необходимо запустить исполняемый файл `UNIAPP` или `TRUAPP`
1. На Linux, при возникновении проблем с запуском, попробовать запустить с флагом `--no-sandbox`:
   - ```sh
     ./UNIAPP --no-sandbox
     ```
1. Чтобы открыть отладочную консоль с логами программы, используйте верхнее меню:
   - `Developer` -> `Toggle Developer Tools`
1. Чтобы установить запакованное расширение откройте на левой панели вкладку расширений и нажмите на знак `+`
1. При возникновении ошибок, блокирующих выполнение программы (которые можно наблюдать в отладочной консоли), нажмите в верхнем меню:
   1. `Developer` -> `Clear App Storage`
   1. `Developer` -> `Remove Installed Extensions`
   1. Перезагрузите программу

# 4. Добавление расширения в режиме отладки

Так как в процессе разработки запаковывать и переустановливать расширение при каждом изменении крайне неудобно, существует механизм добавления расширения в виде обычный директории (исходников, в режиме отладки), так чтобы изменения автоматически подхватывались платформой при перезагрузке страницы.<br/>
<br/>
Для этого требуется:

1. Создать директорию на ПК, в которой будут храниться расширения в режиме отладки, например
   - `mkdir ~/truapp-debug-extensions`
1. Поместить в эту директорию текущее расширение
   - ```sh
     cd ~/truapp-debug-extensions
     git clone https://trulab.ru/trutex/public/truapp-extensions/simple-node-example.git
     ```
1. Собрать расширение
   - ```sh
     cd simple-node-example
     yarn install
     yarn build # on Windows "yarn win:build"
     ```
1. Запустить `UNIAPP` или `TRUAPP`
1. Открыть настройки (settings):
   - Либо нажав на вкладку с изображением шестеренки на боковой панели
   - Либо комбинацией клавиш `ctrl|cmd`+`,`
   - Либо выбрав в верхнем меню `App` -> `Settings` -> `Open`
1. Настройки хранятся в формате `JSON`, необходимо добавить новый параметр, указывающий абсолютный путь к директории, где хранятся расширения в режиме отладки:
   - ```json
     {
       "debugExtensionsPath": "/absolute/path/to/truapp-debug-extensions"
     }
     ```
1. Сохранить внесенные изменения:
   - Либо комбинацией клавиш `ctrl|cmd`+`s`
   - Либо выбрав в верхнем меню `File` -> `Save File`
1. Перезагрузить платформу:
   - Либо комбинацией клавиш `ctrl|cmd`+`r`
   - Либо выбрав в верхнем меню `View` -> `Reload`
1. В списке расширений должно автоматически отобразиться расширение из указанной директории со специальными метками:
   - В названии расширения должно быть указано "(debug)"
   - На икноке вкладки расширения в левой панели управления в правом нижнем углу должен отображаться маленький значек жука (bug)

# 5. Процесс внесения изменений

1. Если отредактированы файлы в папке `static/`
   - достаточно просто перезагрузить платформу
     - Либо комбинацией клавиш `ctrl|cmd`+`r`
     - Либо выбрав в верхнем меню `View` -> `Reload`
1. Если отредактированы файлы в папке `src/`
   1. Необходимо пересобрать проект `yarn build`
   1. Перезагрузить платформу:
   - Либо комбинацией клавиш `ctrl|cmd`+`r`
   - Либо выбрав в верхнем меню `View` -> `Reload`

Важно: в данный момент сборка настроена таким образом, что доступ к `node` есть только у скриптов, имеющих в названии суфикс `_node`. Например `root_node.ts`.

# 6. Структура файлов проекта

- `.yarn/`: директория где `yarn` хранит различные вспомагательные файлы
- `dist/`: директория куда происходит сборка `TypeScript` в `JavaScript` командой `yarn build`
- `node_modules/`: директория где `node` и `yarn` хранит все установленные зависимости
- `scripts/`: директория где хранятся различные дополнительные скрипты (в данный момент скрипты для сборки на Windows)
- `src/`: директория со всеми исходниками (в данный момент только `TypeScript`)
  - `root.ts`: корневой скрипт расширения, является входной точкой (`front`/`renderer` процесс)
  - `root_node.ts`: корневой скрипт расширения, имеющий доступ к `node` (`back`/`main` процесс)
  - `control_panel/`: директория где хранятся скрипты, относящиеся к панели управления
    - `cp_tab.ts`: скрипт, содержащий логику вкладки на панели управления
  - `main_panel/`: директория где хранятся скрипты, относящиеся к основной (рабочей) панели
    - `mp_tab.ts`: скрипт, содержащий логику вкладки на основной панели
- `static/`: директория где хранятся все статические данные (в данный момент это иконки, `HTML` документы и файлы стилей)
  - `icon.svg`: иконка самого расширения, отображаемая в списке расширений
  - `icons/`: директория где хранятся различные используемые иконки
  - `control_panel/`: директория где хранятся ассеты, относящиеся к панели управления
    - `cp_tab.html`: документ, описывающий содержимое вкладки на боковой панели
    - `cp_tab.css`: файл стилей, описывающий внешний вид элементов соответствующего `html` файла
  - `main_panel/`: директория где хранятся ассеты, относящиеся к основной панели
    - `mp_tab.html`: документ, описывающий содержимое вкладки на основной панели
    - `mp_tab.css`: файл стилей, описывающий внешний вид элементов соответствующего `html` файла
- `temp/`: директория где хранятся временные файл (в данный момент она используется во время сборки `yarn build`)
- `.gitattributes`: конфигурационный файл с описанием файловых параметров для `git`
- `.gitignore`: конфигурационный файл с правилами игнорирования файлов для `git`
- `.nvmrc`: конфигурационный файл для `nvm`, позволяет просто использовать команду `nvm use` для выбора необходимой версии `node`
- `.prettierignore`: конфигурационный файл с правилами игнорирования файлов для `prettier`
- `.prettierrc.json`: конфигурационный файл для `prettier` (описание правил автоформатирования текста)
- `.yarnrc.yml`: конфигурационный файл для `yarn`
- `package.json`: основной файл с описанием всех параметров расширения
- `README.md`: данный файл с общей информацией
- `tscоnfig.json`: конфигурационный файл для `TypeScript`
- `yarn.lock`: файл в котором `yarn` хранит все версии установленных зависимостей. Он необходим для обеспечения стабильности окружения

# 7. Структура `package.json`

- `id`: уникальный идентификатор расширения в специальном формате `имя-автора` `/` `название-расширения`
- `title`: название расширения
- `description`: описание расширения
- `author`: автор / разработчик / владелец расширения
- `version`: версия расширения в формате `semver`
- `url`: адрес расширения,
- `iconPath`: путь до иконки расширения
- `scriptPath`: путь до корневого (входного) скрипта расширения (`front`/`renderer` процесс)
- `backScriptPath`: путь до корневого (входного) скрипта расширения c `node` интеграцией (`back`/`main` процесс)
- `requiredApis`: список требуемых интерфейсов (API)
- `scripts`: описание `yarn` скриптов, используемых при разработке
  - `build_front`: сборка всех файлов, относящихся к `front`/`renderer` процессу
  - `build_back`: сборка всех файлов, относящихся к `back`/`main` процессу
  - `build`: финальная сборка
  - `archive`: сборка и архивация расширения в формат `.asar` для последующего распространения
  - `win:build_front`: аналогичный скрипт, адаптированный под Windows
  - `win:build_back`: аналогичный скрипт, адаптированный под Windows
  - `win:build`: аналогичный скрипт, адаптированный под Windows
  - `win:archive`: аналогичный скрипт, адаптированный под Windows
- `dependencies`: список зависимостей расширения
  - `uniapp`: модуль, осуществляющий интеграцию с API платформы
- `engines`: список требуемых инструментов и их версий
- `packageManager`: используемый менеджер пакетов
- `type: module`: включение поддержки `ES` модулей (другими словами `import` директив для `JavaScript`)
- `devDependencies`: список зависимостей, используемых только в режиме отладки

# 8. Используемые API

- `communicationApi`
- `controlPanelApi`
- `mainPanelApi`
- `nodeApi`
- `pingPongApi`

# 9. Все доступные API

- `appInfoApi` (предварительная готовность)
  - для получения информации о платформе (версия, package.json и т.д.)
- `appMenuApi` (в работе)
  - для взаимодействия с панелью кнопок ("File", "Edit", и т.д.)
- `cacheApi` (в работе)
  - для хранения данных в кэше
- `codeEditorApi` (концепция в проработке)
  - для отображения текстовых файлов через редактор кода
  - для обеспечения интеграции с различными редакторами кода
- `commandsApi` (в работе)
  - для добавления и взаимодействия с `command palette`
- `communicationApi` (предварительная готовность)
  - для обеспечения взаимодействия между разными процессами по тегам
- `contextMenuApi` (в работе)
  - для добавления опцией в выпадающее контекстное меню
- `controlPanelApi` (предварительная готовность)
  - для работы с панелью управления
- `databaseApi` (предварительная готовность)
  - для хранения данных в базе
  - для обеспечения интеграции с различными базами данных
- `extensionInfoApi` (предварительная готовность)
  - для получения информации о расширении (версия, `package.json` и т.д.)
- `fileExplorerApi` (концепция в проработке)
  - для отобрадения проводника по файлам
  - для обеспечения интеграции с различными файловыми проводниками
- `fileSystemApi` (предварительная готовность, временный)
  - для работы с файловой системой через `node.fs`
- `hotkeysApi` (в работе)
  - для добавления и взаимодействия с горячими клавишами
- `lifecycleApi` (предварительная готовность)
  - для контроля жизненного цикла (`onReady`, `onDestroy` и т.д.)
- `mainPanelApi` (предварительная готовность)
  - для работы с основной рабочей панелью
- `nodeApi` (предварительная готовность)
  - для работы с `node` через специальные `utility processes` и обеспечения общения между ними
- `notificationsApi` (в работе)
  - для отправки уведомлений
- `pathApi` (предварительная готовность)
  - для работы с файловой системой через `node.fs`
- `pingPongApi` (предварительная готовность)
  - для отправления тестовых "ping" / "pong" сигналов
- `processesApi` (предварительная готовность)
  - для добавления и взаимодействия с процессами платформы
- `settingsApi` (предварительная готовность)
  - для работы с настройками
- `statusBarApi` (в работе)
  - для взаимодействия со статусной строкой
- `storageApi` (предварительная готовность)
  - для хранения простых данных в формате "ключ" -> "значение"
- `tagsApi` (предварительная готовность)
  - для получения информации о существующих тегах
- `webApi` (предварительная готовность)
  - для контроля доступа к интернету

# 10. Используемые инструменты / технологии верхнего уровня

- `TypeScript`: для написания типизированного `JavaScript` кода
  - https://www.typescriptlang.org/
- `esbuild`: быстрый сборщик `TypeScript` файлов
  - https://esbuild.github.io/
- `ASAR`: архивный формат для распространения расширений
  - https://www.electronjs.org/docs/latest/tutorial/asar-archives

# 11. База знаний

1. [ECMAScript](https://developer.mozilla.org/en-US/docs/Glossary/ECMAScript) - основа языка JS
1. [JavaScript](https://developer.mozilla.org/en-US/docs/Web/javascript)
1. [TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html) - язык на базе JS добавляющий типизацию
1. [V8 JS Engine](<https://en.wikipedia.org/wiki/V8_(JavaScript_engine)>) - интерпретатор/компилятор JS кода
1. [Node.js](https://en.wikipedia.org/wiki/Node.js) - исполнитель JS кода использующий V8
1. [Chromium](<https://en.wikipedia.org/wiki/Chromium_(web_browser)>) - основа браузера Chrome использующая V8
1. [Electron.js](https://www.electronjs.org/docs/latest) - JS фреймворк для создания приложений использующий Chromium и Node.js
1. [Vue.js](https://vuejs.org/guide/introduction.html) - JS фреймворк, реализующий реактивность
1. [Vite.js](https://vitejs.dev/guide/why.html) - сборщик JS (web) проектов
1. [Quasar.js](https://quasar.dev/docs) - высокоуровневый фреймворк для сборки Vue.js + TS + Electron.js приложений на базе Vite.js
1. [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) - язык разметки
1. [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) - файл описания стилей
1. [SCSS](https://sass-lang.com/guide) - надстройка над CSS расширяющая его возможности
1. [ESLint](https://eslint.org/docs/latest/use/getting-started) - линтер для JS
1. [Prettier](https://prettier.io/docs/en) - инструмент для форматирования текста