# 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`).