Skip to content

PROGRAM_DESCRIPTION.md

Latest commit

 

History

History
302 lines (217 loc) · 13.7 KB

PROGRAM_DESCRIPTION.md

File metadata and controls

302 lines (217 loc) · 13.7 KB
Raw

Описание программы

Назначение

GUI Bootstrap Manager — это desktop-приложение на PySide6 для автоматизации создания новых проектов через графический интерфейс.

Программа не является конечным продуктом для обычного пользователя. Это внутренний инженерный инструмент, который помогает:

  • выбрать технологический стек;
  • проверить наличие нужных инструментов разработки;
  • подготовить среду через PowerShell provisioning;
  • сгенерировать структуру нового проекта из шаблонов;
  • выполнить начальную инициализацию выбранного стека;
  • открыть созданный проект на диске.

Если кратко: программа заменяет ручной bootstrap нового проекта на управляемый GUI-сценарий.

Что делает программа

Приложение выполняет следующий основной цикл:

  1. Запускает окно на PySide6.
  2. Дает ввести имя проекта и выбрать папку назначения.
  3. Позволяет выбрать один из поддерживаемых типов проекта.
  4. Проверяет наличие обязательных инструментов для выбранного стека.
  5. При необходимости запускает provisioning среды через PowerShell и winget.
  6. Создает новую папку проекта.
  7. Генерирует файлы из шаблонов в каталоге templates/.
  8. Выполняет стек-специфичную инициализацию.
  9. Добавляет служебные файлы и метаданные.
  10. При включенной опции выполняет git init.
  11. Позволяет открыть созданную папку проекта из интерфейса.

Поддерживаемые типы проектов

Go desktop

  • Стек: Wails + React + TypeScript + Tailwind
  • Ключ стека: go
  • Проверяемые инструменты: git, go, node, npm, wails
  • Профиль provisioning: go
  • Инициализация после генерации: wails init

Назначение: создание desktop-приложения на Go с web-интерфейсом через Wails.

C# Windows

  • Стек: .NET + WinUI 3 + Windows App SDK + XAML
  • Ключ стека: cs
  • Проверяемые инструменты: git, dotnet
  • Профиль provisioning: cs
  • Инициализация после генерации: dotnet new winui

Назначение: создание Windows-приложения на C# с нативным UI через WinUI 3.

Python desktop

  • Стек: PySide6 + Qt Quick + QML + PyInstaller + Nuitka
  • Ключ стека: python
  • Проверяемые инструменты: git, python
  • Профиль provisioning: python
  • Инициализация после генерации:
    • создание venv;
    • обновление pip;
    • установка зависимостей из requirements.txt

Назначение: создание desktop-приложения на Python с GUI через Qt/QML.

Landing

  • Стек: Astro + TypeScript + Tailwind
  • Ключ стека: astro
  • Проверяемые инструменты: git, node, npm
  • Профиль provisioning: web
  • Инициализация после генерации: npm create astro@latest

Назначение: создание статического сайта или лендинга.

Web app

  • Стек: Next.js + TypeScript + React + Tailwind
  • Ключ стека: next
  • Проверяемые инструменты: git, node, npm
  • Профиль provisioning: web
  • Инициализация после генерации: npx create-next-app@latest

Назначение: создание web-приложения на Next.js.

Documentation

  • Стек: Docusaurus + TypeScript + MDX
  • Ключ стека: docs
  • Проверяемые инструменты: git, node, npm
  • Профиль provisioning: docs
  • Инициализация после генерации: npx create-docusaurus@latest

Назначение: создание сайта документации.

Архитектура по модулям

Точка входа

  • main.py

    • Минимальная точка входа.
    • Делегирует запуск в app.main.run().

  • app/main.py

    • Создает QApplication.
    • Настраивает имя приложения и организацию.
    • Создает MainWindow.
    • Показывает окно.
    • Запускает Qt event loop.

GUI

  • app/window.py
    • Главный модуль интерфейса.
    • Создает форму с полями:
      • имя проекта;
      • папка назначения;
      • стек;
      • git init;
      • Upgrade при provisioning.
    • Содержит действия пользователя:
      • выбор папки;
      • проверка инструментов;
      • запуск provisioning;
      • создание проекта;
      • открытие папки проекта.
    • Заполняет таблицу статусов инструментов.
    • Пишет сообщения в лог.
    • Показывает ошибки через QMessageBox.

Конфигурация стеков

  • app/models.py
    • Описывает структуру StackDefinition.
    • Хранит словарь STACKS со всеми поддерживаемыми типами проектов.
    • Определяет DEFAULT_PROJECT_ROOT.

Проверка инструментов

  • app/services/tooling.py
    • Ищет системные команды через shutil.which.
    • Определяет версии инструментов через subprocess.run.
    • Возвращает список статусов для отображения в таблице GUI.

Provisioning среды

  • app/services/provisioning.py
    • Находит provisioning/setup_env.ps1.
    • Проверяет, что скрипт существует.
    • Разрешает provisioning только на Windows.
    • Запускает powershell с параметрами профиля и опцией -Upgrade.

Генерация проекта

  • app/services/generator.py
    • Основной модуль генерации.
    • Проверяет валидность выбранного стека.
    • Нормализует имя проекта.
    • Создает директорию проекта и базовые подпапки.
    • Рендерит шаблоны из templates/<stack>/.
    • Копирует обычные файлы и обрабатывает .j2 шаблоны через Jinja2.
    • Выполняет стек-специфичную инициализацию.
    • Записывает служебные файлы:
      • CHANGELOG.md;
      • локали;
      • .cursorrules;
      • .windsurfrules;
      • AGENTS.md;
      • .editorconfig;
      • .gitignore;
      • .env.example;
      • bootstrap.meta.json.
    • При необходимости выполняет git init.

Вспомогательные утилиты

  • app/utils.py

    • Содержит вспомогательные функции работы с путями и именем проекта.

  • app/widgets/log_view.py

    • Реализует виджет текстового лога для главного окна.

Пользовательский сценарий

Шаг 1. Запуск приложения

Пользователь запускает main.py. Открывается главное окно приложения.

Шаг 2. Выбор параметров проекта

Пользователь:

  • вводит имя проекта;
  • выбирает папку назначения;
  • выбирает технологический стек;
  • при необходимости включает git init.

Шаг 3. Проверка среды

После выбора стека программа:

  • автоматически проверяет нужные инструменты;
  • показывает, какие из них найдены;
  • показывает путь к команде и версию, если она доступна.

Шаг 4. Подготовка среды

Если в системе не хватает инструментов, пользователь может запустить provisioning:

  • выбирается профиль по стеку;
  • вызывается setup_env.ps1;
  • установка идет через winget и стек-специфичные команды.

Шаг 5. Создание проекта

После нажатия на кнопку создания программа:

  1. Проверяет имя проекта.
  2. Нормализует его для безопасного имени папки.
  3. Создает структуру каталогов.
  4. Рендерит шаблоны выбранного стека.
  5. Запускает первичную инициализацию фреймворка.
  6. Создает общие служебные файлы.
  7. При необходимости выполняет git init.

Шаг 6. Завершение

После успешного завершения программа:

  • пишет путь проекта в лог;
  • показывает количество созданных файлов;
  • выводит результат framework-init;
  • позволяет открыть папку проекта из интерфейса.

Что именно генерируется

Вне зависимости от стека программа создает базовые каталоги:

  • src
  • assets
  • assets/locales
  • docs
  • tests
  • build
  • scripts
  • tools

Также создаются общие файлы:

  • CHANGELOG.md
  • assets/locales/en.json
  • assets/locales/ru.json
  • assets/locales/uk.json
  • .cursorrules
  • .windsurfrules
  • AGENTS.md
  • .editorconfig
  • .gitignore
  • .env.example
  • bootstrap.meta.json

Дополнительно создаются стек-специфичные файлы из каталога templates/.

Слабые места и риски текущей реализации

Блокировка интерфейса при provisioning

Вывод процесса provisioning читается синхронно через stdout.read(). Пока PowerShell-скрипт не завершится, GUI может зависать.

Несовпадение имени папки проекта

При генерации имя проекта нормализуется, а при открытии папки используется исходный ввод пользователя. Если имя содержит запрещенные символы, папка может быть создана с одним именем, а открытие будет искать другое.

Проверка инструментов не блокирует генерацию

Даже если обязательные инструменты не найдены, пользователь все равно может запустить создание проекта. Это может привести к частично сгенерированному проекту без успешной framework-init стадии.

Инициализация выполняется в режиме best effort

Если внешняя команда недоступна, генератор не всегда падает с ошибкой. Вместо этого он может просто вернуть текст о пропуске или ошибке. В результате проект может выглядеть созданным, но быть неполным.

Ошибка git init может остаться незаметной

git init вызывается без явного контроля результата и без обязательного логирования причины сбоя.

Сильная привязка к Windows

Проект ориентирован на Windows-среду:

  • provisioning через PowerShell;
  • установка через winget;
  • генерация .bat скриптов;
  • отдельная поддержка WinUI и Windows SDK.

Часть функций на других ОС либо не работает, либо работает ограниченно.

Итог

Это GUI-оркестратор для стандартизированного старта новых проектов под несколько стеков. Его задача не в разработке прикладной логики, а в том, чтобы быстро подготовить основу нового репозитория, проверить инструменты, установить зависимости среды и создать рабочий стартовый scaffold.