From 1d1f11c3f8a1ff6cd110137ae2d2f227af195ec8 Mon Sep 17 00:00:00 2001 From: Ku6epXBOCTuK Date: Wed, 15 Jul 2026 16:15:49 +0500 Subject: [PATCH] docs: add readme\license --- LICENSE | 21 +++++++ README.md | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++ README_ru.md | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 340 insertions(+) create mode 100644 LICENSE create mode 100644 README.md create mode 100644 README_ru.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..8861728 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Ku6epXBOCTuK + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..1656645 --- /dev/null +++ b/README.md @@ -0,0 +1,160 @@ +# XBOCTuK Flow + +Local-first task management for solo developers and small teams — a VS Code +extension. + +Tasks are plain Markdown files with YAML frontmatter (default extension +`.task.md`). No cloud, no server: git-friendly, editable in any editor. + +[Русская версия](README_ru.md) + +## Features + +- **Sidebar** — Project / Global → status → tasks +- **Dashboard** — task list + description (filters, scope, sort, group) +- **Kanban** — status columns, drag-and-drop, create-in-column +- **Commands** — create / open / change status / delete +- **Two stores** — project folder (workspace) and global folder (shared on the + machine) + +### Statuses + +`backlog` · `todo` · `in-progress` · `done` · `cancelled` + +On the Kanban board, `backlog` and `cancelled` are hidden by default (use **Show +hidden**). + +### Priorities + +`critical` · `high` · `medium` · `low` + +## Requirements + +- VS Code **^1.96.0** +- Node.js 20+ (for development) + +## Development install + +```bash +npm install +npm run build +``` + +1. Open the extension folder in VS Code +2. Press **F5** — Extension Development Host +3. In the Host window, open a workspace where you want tasks + +The extension is **not** on the Marketplace yet — use dev host or a local +`.vsix` (below). + +### Local `.vsix` (optional) + +```bash +npm run build +npx @vscode/vsce package +``` + +Install: Extensions → `...` → Install from VSIX. + +## Settings + +Settings → **XBOCTuK Flow** (or `settings.json`). Defaults live in +`package.json` (`contributes.configuration`). + +| Setting | Description | Default | +| --------------------------- | --------------------------------------------------- | --------------- | +| `xboctukFlow.projectPath` | Project tasks folder **relative** to workspace root | `.vscode/tasks` | +| `xboctukFlow.globalPath` | **Absolute** path to global tasks (empty = off) | `""` | +| `xboctukFlow.fileExtension` | File extension: `.task.md` \| `.md` \| `.todo.md` | `.task.md` | + +Example: + +```json +{ + "xboctukFlow.projectPath": ".vscode/tasks", + "xboctukFlow.globalPath": "C:\\Users\\You\\Documents\\xboctuk-tasks", + "xboctukFlow.fileExtension": ".task.md" +} +``` + +## Commands + +Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`): + +| Command | Action | +| ----------------------------------- | ------------------------------------------------ | +| **XBOCTuK Flow: Create Task** | Create a task (scope pick if both paths are set) | +| **XBOCTuK Flow: Open Task** | Open the task file in the editor | +| **XBOCTuK Flow: Change Status** | Change status | +| **XBOCTuK Flow: Delete Task** | Delete task | +| **XBOCTuK Flow: Open Dashboard** | Dashboard (list + body) | +| **XBOCTuK Flow: Edit in Dashboard** | Dashboard with the selected task | +| **XBOCTuK Flow: Open Kanban** | Kanban board | + +Sidebar: title buttons (create / dashboard / kanban) and item actions (open / +edit / status / delete). + +Status bar: **Tasks** → Dashboard. + +## Task file format + +```markdown +--- +id: "550e8400-e29b-41d4-a716-446655440000" +title: "Fix login bug" +status: todo +priority: high +tags: [bug, frontend] +assignee: "" +created: 2026-07-12T10:00:00.000Z +updated: 2026-07-12T10:00:00.000Z +--- + +Task description in markdown… +``` + +One file per task. File name is derived from the title (slug). + +## Dashboard + +- Search title/body; status/priority chips; group none/status/priority +- Scope: All / Project / Global +- Sort by **created**: Oldest first (default) / Newest first +- Save description (button / `Ctrl+S` / `Cmd+S`) +- `+ Task` — create + +## Kanban + +- Columns by status; drag-and-drop updates status +- Scope filter; Show hidden (backlog/cancelled) +- `+` on a column — create with that status + +## Development + +```bash +npm run build # bundle extension → out/extension.js (Vite) +npm run watch # watch build +npm run test # Vitest (watch) +npm run test:run # Vitest single run +npm run check # tsc app + tests +npm run lint # ESLint +npm run format # Prettier +``` + +### Architecture (short) + +- **use-cases** (`src/commands/`) — no vscode; `Result` / `ResultAsync` + (neverthrow) +- **ports** + storage adapters (`FsTaskRepository`, `NodeFileSystem`, + `VscodeConfigProvider`) +- **UI** (`src/ui/`, `src/views/`) — thin vscode adapters, WebView hosts +- **settings defaults** — from `package.json`; code reads them via + `src/config.ts` + +Plan details: [`docs/PLAN.md`](docs/PLAN.md). +Small backlog: [`todo.md`](todo.md). +Russian README: [`README_ru.md`](README_ru.md). + +## License + +MIT (see `package.json`). diff --git a/README_ru.md b/README_ru.md new file mode 100644 index 0000000..45a819c --- /dev/null +++ b/README_ru.md @@ -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`).