185 lines
6.4 KiB
Markdown
185 lines
6.4 KiB
Markdown
# XBOCTuK Flow
|
||
|
||
Local-first task management for solo developers and small teams — VS Code
|
||
extension.
|
||
|
||
[English version](README.md)
|
||
|
||
Задачи хранятся как обычные Markdown-файлы с YAML frontmatter (расширение
|
||
`.xflow.md`). Без облака и отдельного сервера: git-friendly, редактируются в
|
||
любом редакторе.
|
||
|
||
## Возможности
|
||
|
||
- **Sidebar** — дерево Project / Global → статусы → задачи
|
||
- **Dashboard** — список + описание задачи (фильтры, scope, sort, group)
|
||
- **Kanban** — колонки по статусу, drag-and-drop, create в колонке
|
||
- **Команды** — create / open / change status / delete
|
||
- **In-editor** — lint frontmatter + status/priority/tags/assignee
|
||
- **Теги проекта** — каталог в `config.yml` папки задач
|
||
- **Два хранилища** — проектное (в 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 | `.xflow` |
|
||
| `xboctukFlow.globalPath` | **Абсолютный** путь к глобальным задачам (пусто = выкл.) | `""` |
|
||
|
||
Файлы задач всегда с расширением **`.xflow.md`**.
|
||
|
||
Пример:
|
||
|
||
```json
|
||
{
|
||
"xboctukFlow.projectPath": ".xflow",
|
||
"xboctukFlow.globalPath": "C:\\Users\\You\\Documents\\xboctuk-flow"
|
||
}
|
||
```
|
||
|
||
## Команды
|
||
|
||
Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`):
|
||
|
||
| Команда | Действие |
|
||
| ----------------------------------------- | ----------------------------------------------- |
|
||
| **XBOCTuK Flow: Create Task** | Создать задачу (scope, если настроены оба path) |
|
||
| **XBOCTuK Flow: Open Task** | Открыть `.xflow.md` в editor |
|
||
| **XBOCTuK Flow: Change Status** | Сменить статус |
|
||
| **XBOCTuK Flow: Edit Status (in file)** | Status во frontmatter через Quick Pick |
|
||
| **XBOCTuK Flow: Edit Priority (in file)** | Priority во frontmatter через Quick Pick |
|
||
| **XBOCTuK Flow: Delete Task** | Удалить задачу |
|
||
| **XBOCTuK Flow: Open Dashboard** | Dashboard (список + body) |
|
||
| **XBOCTuK Flow: Open 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…
|
||
```
|
||
|
||
Один файл — одна задача (`*.xflow.md`). Имя файла строится из title (slug).
|
||
Макс. длина `title`: 80 символов.
|
||
|
||
### Конфиг проекта (`config.yml` в папке задач)
|
||
|
||
По умолчанию:
|
||
|
||
```text
|
||
.xflow/
|
||
config.yml
|
||
fix-login.xflow.md
|
||
```
|
||
|
||
```yaml
|
||
# .xflow/config.yml
|
||
tags:
|
||
- bug
|
||
- frontend
|
||
```
|
||
|
||
Если `config.yml` есть, теги вне каталога — warning (Quick Fix: **Add tag "…" to
|
||
project**). Hover на `tags` → **Edit tags…**.
|
||
|
||
## Dashboard
|
||
|
||
- Поиск по title/body, chips status/priority, group none/status/priority
|
||
- Scope: All / Project / Global
|
||
- Sort by **created**: Oldest first (default) / Newest first
|
||
- Detail только просмотр; **Edit** открывает файл задачи в editor
|
||
- `+ 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`).
|