xboct-flow/README_ru.md

XBOCTuK Flow

Local-first task management for solo developers and small teams — VS Code extension.

English version

Задачи хранятся как обычные 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+ (для разработки)

Установка (разработка)

npm install
npm run build

1. Открой папку расширения в VS Code
2. F5 — Extension Development Host
3. В Host-окне открой workspace, где нужны задачи

Пока расширение не опубликовано в Marketplace — только dev / локальный .vsix (см. ниже).

Локальный .vsix (опционально)

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.

Пример:

{
  "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.

Формат файла задачи

---
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 в папке задач)

По умолчанию:

.xflow/
  config.yml
  fix-login.xflow.md

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

Разработка

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.
Бэклог мелочей: todo.md.
English README: README.md.

Лицензия

MIT (см. package.json).