docs: add readme\license

2026-07-15 16:15:49 +05:00
parent 4539d39576
commit 1d1f11c3f8
3 changed files with 340 additions and 0 deletions
@@ -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`).