🐾 Hotpaws

macOS overlay application for terminal command hints

Нажмите F19, чтобы мгновенно получить доступ к командам терминала. Щелкните по любой команде, чтобы вставить её в терминал.

✨ Возможности

• Мгновенный доступ: Горячая клавиша (F19) для мгновенного перехода в полноэкранный режим подсказок
• Интеллектуальная организация: Команды сгруппированы по категориям → Группам команд → Командам
• Универсальный двоичный файл: Работает на Mac Intel (Silicon в будущих версиях)
• Настраиваемый: Редактирование команд и стилей прямо в приложении
• Несколько терминалов: Terminal.app, iTerm2, Warp и другие

🚀 Быстрый старт

# Клонируем репозиторий
git clone https://github.com/listeomin/hotpaws.git
cd hotpaws

# Собираем приложение
./scripts/build.sh

# Запускаем
open build/Hotpaws.app

Первый запуск: Предоставьте разрешение на доступ к системным функциям (Accessibility), когда появится запрос (необходимо для вставки команд).

📁 Структура проекта

hotpaws/
├── src/                      # Swift исходники
│   ├── main.swift            # Точка входа, AppDelegate, WKWebView, хоткеи
│   └── ConfigManager.swift   # Загрузка конфигов из ~/.hotpaws/
│
├── resources/                # Ресурсы (копируются в .app)
│   ├── index.html            # HTML структура оверлея
│   ├── main.css              # Стили
│   ├── main.js               # JavaScript логика
│   ├── commands.json         # Команды пользователя
│   ├── commands-meta.json    # Словарь команд для автодополнения
│   └── AppIcon.icns          # Иконка приложения
│
├── scripts/                  # Скрипты
│   ├── build.sh              # Сборка приложения
│   ├── cleanup.sh            # Очистка билдов
│   ├── terminal.applescript  # AppleScript для Terminal.app
│   ├── iterm2.applescript    # AppleScript для iTerm2
│   ├── warp.applescript      # AppleScript для Warp
│   ├── fallback.applescript  # Резервный AppleScript
│   └── README.md             # Описание скриптов
│
├── build/                    # Артефакты сборки (в .gitignore)
│   └── Hotpaws.app/          # Собранное приложение
│
├── $/                        # Рабочие документы (не в git)
│   ├── project-doc.md        # Документация проекта
│   ├── tasks.md              # Задачи с промптами
│   ├── edit-mode-tasks.md    # Задачи по режиму редактирования
│   ├── design.png            # Дизайн-макет
│   └── CATEGORY_SELECTS.md   # Документация селектов
│
├── .github/                  # GitHub конфигурация
│   ├── workflows/
│   │   └── build.yml
│   └── ISSUE_TEMPLATE/
│
├── .gitignore
├── Info.plist                # Настройки macOS приложения
├── LICENSE                   # MIT лицензия
├── README.md                 # Описание для GitHub
├── CHANGELOG.md              # История изменений
└── CONTRIBUTING.md           # Гайд для контрибьюторов

🎨 Настройка

При первом запуске Hotpaws создаёт папку ~/.hotpaws/ с файлами:

• commands.json - ваша библиотека команд
• main.css - пользовательские стили
• config.json - настройки приложения (для будущего использования)

Редактируйте эти файлы, чтобы настроить приложение под себя. Изменения вступят в силу при следующем запуске.

Пример: добавление команд

{
  "version": "1.0",
  "categories": [
    {
      "id": "docker",
      "name": "Docker",
      "icon": "🐳",
      "groups": [
        {
          "name": "Containers",
          "commands": [
            {
              "label": "List Running",
              "command": "docker ps",
              "description": "Show running containers"
            }
          ]
        }
      ]
    }
  ]
}

🛠 Технологии

• Язык: Swift 5
• Интерфейс: WKWebView (HTML + CSS + JavaScript)
• Сборка: swiftc (Xcode не требуется)
• Фреймворки: Cocoa, WebKit, Carbon
• Интеграция с терминалом: AppleScript

🔧 Архитектура

↓ [Нажмите F19]             → [Swift AppDelegate]
↓ [Окно WKWebView]
↓ [Интерфейс HTML + JS]
↓ [webkit.messageHandlers]
↓ [Swift получает команду]
↓ [AppleScript → Terminal]

📋 Требования

• macOS 12.0 и выше
• Разрешения на доступ к системным функциям (Accessibility) для вставки команд
• Terminal.app, iTerm2, Warp и другие

🐛 Известные проблемы

• При первом запуске необходимо вручную предоставить разрешение Accessibility
• Директория сборки игнорируется Git (.app пакеты исключены)

🗺 Дорожная карта

• Графический интерфейс для редактирования команд
• Поиск и фильтрация команд
• Поддержка псевдонимов команд
• Система тем
• Синхронизация в облаке Google Диск и iCloud

📝 Лицензия

MIT

🤝 Участие в проекте

Будем рады вашим вкладом! Этот проект создан для новичков, которым сложно работать с командами терминала.

Философия:

• Сосредоточенность на новичках, а не на продвинутых пользователях
• Скрытие сложности за интуитивным интерфейсом
• Внешняя настройка через конфигурацию, а не через изменения кода
• Команды не выполняются без подтверждения пользователя

📖 Документация

Полную техническую документацию см. в файле $/project-doc.md.

---

Создано с 🐾@listeomin