kandown 0.1.0

package/dist/manifest.json

@@ -0,0 +1,17 @@
+{
+  "name": "Kandown",
+  "short_name": "Kandown",
+  "description": "File-based Kanban engine backed by Markdown",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#0a0a0a",
+  "theme_color": "#0a0a0a",
+  "icons": [
+    {
+      "src": "/favicon.svg",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "kandown",
+  "version": "0.1.0",
+  "description": "File-based Kanban engine backed by Markdown. Zero backend, AI-agent friendly.",
+  "type": "module",
+  "bin": {
+    "kandown": "bin/kandown.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "kanban",
+    "markdown",
+    "task-manager",
+    "ai-agents",
+    "local-first",
+    "file-over-app"
+  ],
+  "author": "Vanessa Depraute (https://github.com/vava-nessa)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vava-nessa/kandown.git"
+  },
+  "homepage": "https://github.com/vava-nessa/kandown#readme",
+  "bugs": {
+    "url": "https://github.com/vava-nessa/kandown/issues"
+  },
+  "license": "MIT",
+  "scripts": {
+    "dev": "node scripts/sync-agent-kandown.js && vite",
+    "dev:cli": "tsup --watch",
+    "build": "node scripts/sync-agent-kandown.js && tsc -b && vite build && pnpm build:cli",
+    "build:cli": "tsup",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "sync:agent": "node scripts/sync-agent-kandown.js"
+  },
+  "dependencies": {
+    "@tabler/icons-react": "3.41.1",
+    "@wysimark/react": "3.0.20",
+    "i18next": "26.0.5",
+    "ink": "7.0.1",
+    "marked": "18.0.2",
+    "motion": "^12.38.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-i18next": "17.0.4",
+    "three": "^0.171.0",
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/three": "0.182.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.5.1",
+    "tailwindcss": "^3.4.17",
+    "tsup": "8.5.1",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.7",
+    "vite-plugin-singlefile": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/AGENT.md

@@ -0,0 +1,102 @@
+# Kandown conventions for AI agents
+
+This project uses a file-based Kandown board located in `.kandown/`. Read this file before touching task files.
+
+## Source of truth
+
+Tasks are the source of truth. There is no board index to maintain.
+
+```
+.kandown/
+├── kandown.json      ← project settings and board columns
+├── tasks/
+│   ├── t1.md      ← task status, metadata, subtasks, notes, report
+│   └── ...
+└── kandown.html      ← local web UI
+```
+
+Columns are stored in `.kandown/kandown.json` under `board.columns`. A task belongs to a column through its frontmatter `status`.
+
+If a task has no `status`, treat it as `Backlog`.
+
+## Task file format
+
+```markdown
+---
+id: t1
+title: Full task title
+status: Todo
+priority: P1
+tags: [backend, security]
+assignee: username
+created: 2026-04-10
+due: 2026-04-25
+ownerType: human
+tools: filesystem, cli, websearch
+---
+
+# Task title
+
+## Context
+
+Background, links, decisions.
+
+## Subtasks
+
+- [ ] First step
+- [ ] Second step
+
+## Notes
+
+Additional information.
+```
+
+Frontmatter fields:
+- `status` — current board column.
+- `order` — optional numeric order inside the column.
+- `ownerType: human` — task is meant for a human.
+- `ownerType: ai` — task is meant for an AI agent.
+- `tools` — free-form tool hints, such as `filesystem, cli, websearch, browser`.
+
+## Working on a task
+
+1. Open the specific task file the user requested.
+2. Set `status: In Progress` when you start.
+3. Check off subtasks as you complete them.
+4. Add a short report below completed subtasks when useful.
+5. When done, add or update the completion report and set `status: Done`.
+
+Example completion report in frontmatter:
+
+```yaml
+report: |
+  ## Changes
+  - Created `src/auth.ts` with JWT validation.
+  - Added `/api/auth/login`.
+
+  ## Files
+  - `src/auth.ts`
+
+  ## Decisions
+  - Used RS256 for better key rotation support.
+```
+
+## Creating tasks
+
+Create a new `tasks/<id>.md` file. Pick the next available ID by scanning filenames in `.kandown/tasks/`. Task IDs use the format `t<N>` (e.g. `t1`, `t2`, `t45`).
+
+## Mutation rules
+
+| Action | Files to edit |
+|---|---|
+| Move task between columns | Task file only: update frontmatter `status` |
+| Reorder task | Task file only: update frontmatter `order` |
+| Change title/priority/tags/assignee | Task file frontmatter only |
+| Change ownerType/tools | Task file frontmatter only |
+| Edit description/notes/subtasks/report | Task file body/frontmatter only |
+| Create task | Create one file in `.kandown/tasks/` |
+| Delete task | Delete its file from `.kandown/tasks/` |
+
+## Scope control
+
+If you notice unrelated cleanup while working, create a separate task file instead of fixing it inline. Keep the current task focused.

package/templates/AGENT_KANDOWN.md

@@ -0,0 +1,146 @@
+# Kandown — AI Agent Rules
+
+## The System
+
+Kandown is a file-based Kanban backed by plain markdown. All task state lives in `.kandown/tasks/*.md` — no separate board index, no database.
+
+```
+.kandown/
+├── tasks/           # Task files (source of truth)
+├── kandown.json     # Board columns + project settings
+└── kandown.html     # Web UI
+```
+
+**Board columns** are configured in `kandown.json` at `board.columns`. Tasks without a `status` go to **Backlog**.
+
+---
+
+## Critical: Real-Time Task Updates
+
+⚠️ **ALWAYS keep task files up to date as you work.** This is not optional — it lets the user see exactly what you're doing, what was decided, and what's left.
+
+When you make progress:
+1. Check off completed subtasks: `- [ ]` → `- [x]`
+2. Add a `report:` under each done subtask with what changed
+3. Move the task to the appropriate column by updating `status:` in frontmatter
+4. Write a completion `report:` in frontmatter when the task is done
+
+---
+
+## Task Lifecycle
+
+### Start working on a task
+Update the task frontmatter: `status: In Progress`
+
+### While working — UPDATE THE TASK FILE AS YOU GO
+
+**This is the most important rule.** Every time you make progress — writing code, making a decision, discovering something — update the task file immediately. Do not wait until the task is done.
+
+For each subtask you complete:
+1. Check it off: `- [ ]` → `- [x]`
+2. Add a `report:` line under it with what changed
+
+Example subtask with report:
+```markdown
+- [x] Set up project structure
+  report: Created src/, dist/, and bin/. Initialized package.json with dependencies.
+- [ ] Add authentication
+```
+
+If there are no subtasks yet, add them as you discover what needs to be done. The task file is your real-time work log — the user should be able to open it and see exactly where things stand.
+
+**Never** wait until the end to update the task. If you finish a session without updating, you're leaving the user in the dark.
+
+### Complete a task
+
+When the task is done:
+1. Set `status: Done` in the frontmatter
+2. Write a completion `report:` in the frontmatter summarizing:
+   - **Changes**: What was created/modified/deleted
+   - **Decisions**: Why you chose a particular approach
+   - **Files**: List of affected files (especially new ones)
+
+```yaml
+---
+status: Done
+report: |
+  ## Changes
+  - Created src/auth.ts with JWT validation
+  - Added /api/auth/login endpoint
+  ## Decisions
+  - Used RS256 for better key rotation support
+  ## Files
+  - src/auth.ts (new)
+  - src/routes.ts (modified)
+---
+```
+
+The `report:` field supports markdown and is displayed prominently in the UI. Write it as a real summary, not a placeholder.
+
+---
+
+## Mutation Rules
+
+| Action | File to edit |
+|--------|-------------|
+| Move task between columns | Task file: update `status:` in frontmatter |
+| Reorder task | Task file: update `order:` in frontmatter |
+| Change title/priority/tags/assignee | Task file frontmatter |
+| Edit description/notes/subtasks | Task file body only |
+| Create task | Create one new `.kandown/tasks/t-NNN.md` |
+| Delete task | Delete the task file |
+| Create/rename/delete columns | `kandown.json` at `board.columns` |
+
+**One task file = one source of truth.** Never maintain a separate board index.
+
+---
+
+## Task File Format
+
+```markdown
+---
+id: t1
+title: Task title
+status: Backlog
+order: 0
+priority: P1
+tags: [backend]
+assignee: username
+created: 2026-04-10
+ownerType: human
+---
+
+# Task title
+
+## Context
+
+Why this exists, background, links.
+
+## Subtasks
+
+- [ ] First step
+- [x] Second step
+  report: What changed.
+
+## Notes
+
+Edge cases, gotchas.
+```
+
+### Frontmatter fields
+
+| Field | Description |
+|-------|-------------|
+| `status` | Board column (Backlog, Todo, In Progress, Review, Done) |
+| `order` | Sort order within the column |
+| `priority` | P1–P4 |
+| `tags` | Free-form labels |
+| `assignee` | Username or AI agent name |
+| `ownerType` | `human` or `ai` |
+| `report` | Completion summary (markdown, shown in UI) |
+
+---
+
+## Stack
+
+React, Motion, Tailwind, Vite, Zustand, TypeScript, Node.js ESM CLI.

package/templates/AGENT_KANDOWN_COMPACT.md

@@ -0,0 +1,65 @@
+# Kandown — AI Agent Rules
+
+You are working on a task managed by **Kandown**, a file-based Kanban system.
+Complete the task and keep its task file updated as you work.
+
+## File Locations
+
+```
+.kandown/
+├── tasks/<id>.md     ← full task details and source of truth
+└── kandown.json      ← project config, including board.columns
+```
+
+## When You Start
+
+1. Open `.kandown/tasks/<id>.md`.
+2. Set frontmatter `status: In Progress`.
+3. Read the full task context before editing code.
+
+## While Working
+
+After completing each subtask:
+1. Check it off in the task file: `- [ ]` → `- [x]`.
+2. Add a report line below it when useful: `  report: What you did.`
+
+Example:
+
+```markdown
+- [x] Create auth module
+  report: Created src/auth.ts with JWT validation. Added /api/auth route.
+- [ ] Add tests
+```
+
+## When You Finish
+
+1. Write the `report:` field in the task frontmatter (markdown supported, displayed in UI report panel):
+
+```yaml
+---
+id: t19
+title: My task
+status: Done
+report: |
+  ## Changes
+  - Created src/auth.ts (JWT, RS256)
+  - Added /api/auth/login endpoint
+  ## Files
+  - src/auth.ts (new)
+  ## Decisions
+  - Used RS256 for better key rotation support
+---
+```
+
+2. Set frontmatter `status: Done`.
+3. Leave all subtasks checked if the task is complete.
+
+**Subtask reports**: Write per-step reports in the `[REPORT]` section under each subtask in the body, not in separate sections.
+
+## Rules
+
+- The task file is the source of truth.
+- Do not maintain a separate board index.
+- If a task has no `status`, treat it as `Backlog`.
+- Board columns are configured in `.kandown/kandown.json` at `board.columns`.
+- If you notice unrelated issues, create a separate task file instead of fixing inline.

package/templates/README.md

@@ -0,0 +1,48 @@
+# .kandown/
+
+File-based kanban for this project. Zero backend, plain markdown on disk.
+
+## Usage
+
+1. Open `kandown.html` in Chrome, Edge, Brave or Opera (File System Access API required)
+2. Click **Select folder** and pick the project folder, then grant read/write permission
+3. Start editing tasks
+
+The app remembers the last 10 projects you've opened.
+
+## Structure
+
+```
+.kandown/
+├── tasks/
+│   ├── t1.md      ← full task details and board status
+│   └── ...
+├── kandown.html      ← the engine (single file, no dependencies)
+├── kandown.json      ← project preferences, columns, appearance, optional fields
+├── AGENT.md          ← AI coding agent conventions
+└── README.md         ← this file
+```
+
+## Settings
+
+Open Settings from the app header to tune this project. Board columns are stored in `kandown.json` at `board.columns`. Each task chooses a column with its frontmatter `status`.
+
+## Editing without the app
+
+Everything is plain markdown. Edit files directly in your IDE, Obsidian, or vim. Click **Reload** in the app (or press `R`) to see changes.
+
+## For AI agents
+
+See `AGENT.md`. The key convention: each task file is its own source of truth. Moving a task means editing the task's frontmatter `status`.
+
+## Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `⌘K` / `Ctrl+K` | Command palette |
+| `⌘1` / `⌘2` | Board / list view |
+| `N` | New task |
+| `R` | Reload |
+| `/` | Focus search |
+| `Esc` | Close drawer / palette |
+| `⌘S` | Save current task |

package/templates/kandown.json

@@ -0,0 +1,34 @@
+{
+  "ui": {
+    "language": "en",
+    "theme": "auto",
+    "skin": "kandown",
+    "font": "inter"
+  },
+  "agent": {
+    "suggestFollowUp": false,
+    "maxSuggestions": 3
+  },
+  "board": {
+    "columns": ["Backlog", "Todo", "In Progress", "Review", "Done"],
+    "defaultPriority": "P3",
+    "defaultOwnerType": "human"
+  },
+  "fields": {
+    "priority": false,
+    "assignee": false,
+    "tags": false,
+    "dueDate": false,
+    "ownerType": false,
+    "tools": false
+  },
+  "notifications": {
+    "browser": false,
+    "sound": false,
+    "soundId": "soft",
+    "statusChanges": true,
+    "taskEdits": true,
+    "subtaskCompletions": true,
+    "editDebounceMs": 2000
+  }
+}

package/templates/tasks/t1.md

@@ -0,0 +1,30 @@
+---
+id: t1
+title: Welcome to your kanban
+status: Todo
+priority: P3
+tags: [example]
+created: 2026-04-16
+ownerType: human
+tools:
+---
+
+# Welcome to your kanban
+
+## Context
+
+This is an example task. You can delete it once you're comfortable with the tool.
+
+Everything here is plain markdown on your disk. The app reads and writes these files directly.
+No database, no backend, no account.
+
+## Subtasks
+
+- [x] Install with `npx kandown init`
+- [x] Open `kanban.html` in Chrome
+- [ ] Create your first real task
+- [ ] Delete this example
+
+## Notes
+
+Press `⌘K` to open the command palette and fuzzy-search any task.

package/templates/tasks/t2.md

@@ -0,0 +1,32 @@
+---
+id: t2
+title: add some error handlers
+status: Done
+created: 2026-04-17
+assignee: opencode
+priority: P1
+---
+
+check for error handlers and good quality code so the app never crashes.
+
+## What was done
+
+Added comprehensive error guards across the codebase to prevent crashes from malformed data:
+
+### serializer.ts
+- `serializeTaskFile()`: Added guards for frontmatter being a valid object, type checking for frontmatter values, multiline report preservation, and null coalescing for body
+
+### parser.ts
+- `parseSimpleYaml()`: Added early return for falsy/invalid input, guards for `m[2]` and regex match access, safe array mapping
+- `buildColumnsFromTasks()`: Added fallback handling for missing statuses and unknown columns
+- `parseTaskFile()`: Added early return guard for empty input
+- `extractSubtasks()`: Added guards for body being a valid string, all line accesses, regex match groups, and text extraction
+- `injectSubtasks()`: Added nullish guards on lines array access, safe array slicing bounds, null coalescing for line content
+
+These changes ensure the app handles corrupted, incomplete, or malformed markdown files gracefully without crashing.
+
+## Subtasks
+
+- [x] check the code for errors
+- [x] add some error handlers to avoid crashes
+- [x] document that

package/templates/tasks/t3.md

@@ -0,0 +1,13 @@
+---
+id: t3
+title: New task
+status: Backlog
+created: 2026-04-17
+---
+
+# New task
+
+## Context
+
+
+## Subtasks