docs: add readme\license

2026-07-15 16:15:49 +05:00
parent 4539d39576
commit 1d1f11c3f8
3 changed files with 340 additions and 0 deletions
@@ -0,0 +1,159 @@
+# XBOCTuK Flow
+
+Local-first task management for solo developers and small teams — VS Code
+extension.
+
+[English version](README.md)
+
+Задачи хранятся как обычные Markdown-файлы с YAML frontmatter (по умолчанию
+`.task.md`). Без облака и отдельного сервера: git-friendly, редактируются в
+любом редакторе.
+
+## Возможности
+
+- **Sidebar** — дерево Project / Global → статусы → задачи
+- **Dashboard** — список + описание задачи (фильтры, scope, sort, group)
+- **Kanban** — колонки по статусу, drag-and-drop, create в колонке
+- **Команды** — create / open / change status / delete
+- **Два хранилища** — проектное (в workspace) и глобальное (общая папка на
+  машине)
+
+### Статусы
+
+`backlog` · `todo` · `in-progress` · `done` · `cancelled`
+
+В Kanban `backlog` и `cancelled` по умолчанию скрыты (кнопка Show hidden).
+
+### Приоритеты
+
+`critical` · `high` · `medium` · `low`
+
+## Требования
+
+- VS Code **^1.96.0**
+- Node.js 20+ (для разработки)
+
+## Установка (разработка)
+
+```bash
+npm install
+npm run build
+```
+
+1. Открой папку расширения в VS Code
+2. **F5** — Extension Development Host
+3. В Host-окне открой workspace, где нужны задачи
+
+Пока расширение **не опубликовано** в Marketplace — только dev / локальный
+`.vsix` (см. ниже).
+
+### Локальный `.vsix` (опционально)
+
+```bash
+npm run build
+npx @vscode/vsce package
+```
+
+Установка: Extensions → `...` → Install from VSIX.
+
+## Настройки
+
+Settings → **XBOCTuK Flow** (или JSON). Defaults задаются в `package.json`
+(`contributes.configuration`).
+
+| Setting                     | Описание                                                 | Default         |
+| --------------------------- | -------------------------------------------------------- | --------------- |
+| `xboctukFlow.projectPath`   | Папка проектных задач **относительно** корня workspace   | `.vscode/tasks` |
+| `xboctukFlow.globalPath`    | **Абсолютный** путь к глобальным задачам (пусто = выкл.) | `""`            |
+| `xboctukFlow.fileExtension` | Расширение файлов: `.task.md` \| `.md` \| `.todo.md`     | `.task.md`      |
+
+Пример:
+
+```json
+{
+  "xboctukFlow.projectPath": ".vscode/tasks",
+  "xboctukFlow.globalPath": "C:\\Users\\You\\Documents\\xboctuk-tasks",
+  "xboctukFlow.fileExtension": ".task.md"
+}
+```
+
+## Команды
+
+Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`):
+
+| Команда                             | Действие                                        |
+| ----------------------------------- | ----------------------------------------------- |
+| **XBOCTuK Flow: Create Task**       | Создать задачу (scope, если настроены оба path) |
+| **XBOCTuK Flow: Open Task**         | Открыть `.task.md` в editor                     |
+| **XBOCTuK Flow: Change Status**     | Сменить статус                                  |
+| **XBOCTuK Flow: Delete Task**       | Удалить задачу                                  |
+| **XBOCTuK Flow: Open Dashboard**    | Dashboard (список + body)                       |
+| **XBOCTuK Flow: Edit in Dashboard** | Dashboard с выбранной задачей                   |
+| **XBOCTuK Flow: Open Kanban**       | Kanban board                                    |
+
+В sidebar: кнопки title (create / dashboard / kanban) и actions на задаче (open
+/ edit / status / delete).
+
+Status bar: **Tasks** → Dashboard.
+
+## Формат файла задачи
+
+```markdown
+---
+id: "550e8400-e29b-41d4-a716-446655440000"
+title: "Пофиксить баг логина"
+status: todo
+priority: high
+tags: [bug, frontend]
+assignee: ""
+created: 2026-07-12T10:00:00.000Z
+updated: 2026-07-12T10:00:00.000Z
+---
+
+Описание задачи в markdown…
+```
+
+Один файл — одна задача. Имя файла строится из title (slug).
+
+## Dashboard
+
+- Поиск по title/body, chips status/priority, group none/status/priority
+- Scope: All / Project / Global
+- Sort by **created**: Oldest first (default) / Newest first
+- Save description (кнопка / `Ctrl+S` / `Cmd+S`)
+- `+ Task` — create
+
+## Kanban
+
+- Колонки по статусу, DnD → смена status
+- Scope filter, Show hidden (backlog/cancelled)
+- `+` на колонке — create с этим status
+
+## Разработка
+
+```bash
+npm run build       # бандл extension → out/extension.js (Vite)
+npm run watch       # watch-сборка
+npm run test        # Vitest (watch)
+npm run test:run    # Vitest один прогон
+npm run check       # tsc app + tests
+npm run lint        # ESLint
+npm run format      # Prettier
+```
+
+### Архитектура (кратко)
+
+- **use-cases** (`src/commands/`) — без vscode, `Result` / `ResultAsync`
+  (neverthrow)
+- **ports** + adapters storage (`FsTaskRepository`, `NodeFileSystem`,
+  `VscodeConfigProvider`)
+- **UI** (`src/ui/`, `src/views/`) — тонкие vscode-адаптеры, WebView host
+- **defaults settings** — из `package.json`; код читает их через `src/config.ts`
+
+Детали плана: [`docs/PLAN.md`](docs/PLAN.md).  
+Бэклог мелочей: [`todo.md`](todo.md).  
+English README: [`README.md`](README.md).
+
+## Лицензия
+
+MIT (см. `package.json`).