161 lines
4.7 KiB
Markdown
161 lines
4.7 KiB
Markdown
# 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`).
|