{"id":50086511,"url":"https://github.com/grinev/boardown","last_synced_at":"2026-05-22T20:07:35.515Z","repository":{"id":355715140,"uuid":"1226880839","full_name":"grinev/boardown","owner":"grinev","description":"Boardown — Markdown task board for VS Code. Store tasks, epics and releases as .md files inside your repo. Local-first, git-native, no cloud required.","archived":false,"fork":false,"pushed_at":"2026-05-17T12:17:21.000Z","size":552,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T13:39:03.245Z","etag":null,"topics":["local-first","markdown","productivity","project-management","task-manager","vs-code-extenstion"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grinev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T23:45:37.000Z","updated_at":"2026-05-17T12:17:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/grinev/boardown","commit_stats":null,"previous_names":["grinev/boardown"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/grinev/boardown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grinev%2Fboardown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grinev%2Fboardown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grinev%2Fboardown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grinev%2Fboardown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grinev","download_url":"https://codeload.github.com/grinev/boardown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grinev%2Fboardown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33364341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"online","status_checked_at":"2026-05-22T02:00:06.671Z","response_time":265,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["local-first","markdown","productivity","project-management","task-manager","vs-code-extenstion"],"created_at":"2026-05-22T20:07:32.936Z","updated_at":"2026-05-22T20:07:35.497Z","avatar_url":"https://github.com/grinev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# boardown\n\n\u003e 🚧 **Status: work in progress.** The VS Code extension is in development,\n\u003e but boardown can already be used from sources via the local web shell.\n\nA local-first task board that stores its data as plain markdown files inside\nyour project's git repo. Releases, epics and tasks live in `.boardown/` next\nto your code, so they version, branch and diff with the rest of the project —\nno cloud, no server, no account.\n\nThe primary MVP target is a **VS Code extension** that reads `.boardown/`\nfrom the open workspace. While that extension is being built, the browser app\nin this repo (`packages/web`) can run locally against any `.boardown/` data\ndirectory, which works well in VS Code's built-in browser panel. An Electron\nbuild is post-MVP.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/screenshot-1.png\" alt=\"boardown board view\" width=\"80%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/screenshot-2.png\" alt=\"boardown task details\" width=\"80%\" /\u003e\n\u003c/p\u003e\n\nSee [PRODUCT.md](./PRODUCT.md) for the full spec and the MVP roadmap.\n\n## Try it from sources\n\nInstall dependencies once:\n\n```sh\npnpm install\n```\n\nStart boardown against this repo's sample `.boardown/`:\n\n```sh\npnpm dev\n```\n\nOr open another project by pointing `--data-dir` at that project's `.boardown/`\ndirectory:\n\n```sh\npnpm dev -- --data-dir /path/to/project/.boardown\n```\n\nThen open `http://localhost:5173` in a browser. In VS Code, run\n**Simple Browser: Show** from the Command Palette, enter\n`http://localhost:5173`, and pin the tab if you want it to behave like a local\nboard panel.\n\nIf the selected `.boardown/` has no `config.yaml`, the web shell creates the\ndefault structure automatically with `idPrefix: TASK`. Create `config.yaml`\nmanually before first launch if you want a different prefix.\n\n## Development\n\nRequirements:\n\n- Node.js **\u003e= 20** (the repo pins `20` via `.nvmrc`; Node 22 also works)\n- pnpm **10+** (`npm install -g pnpm` or via `corepack`)\n\nInstall dependencies once if you skipped the quick start above:\n\n```sh\npnpm install\n```\n\nThe repo is a pnpm workspace with three packages:\n\n- [`packages/core`](./packages/core) — platform-agnostic logic (schemas,\n  parser, board operations). Pure TypeScript, runs in Node.\n- [`packages/ui`](./packages/ui) — the React app: components, Zustand store,\n  UI flow. Takes an `FsAdapter` as input, knows nothing about the host.\n  Source-only (consumed directly by the shell's bundler).\n- [`packages/web`](./packages/web) — dev-only browser shell: Vite app that\n  mounts `@boardown/ui` over a Vite middleware which serves a local\n  `.boardown/` data directory. Used for iterating on the UI from sources.\n\nA future `packages/vscode` (the primary MVP distribution target) and\n`packages/electron` (post-MVP) will be additional shells next to `web`,\nreusing `@boardown/ui` unchanged.\n\n### Common scripts (run from the repo root)\n\n| Command            | What it does                                              |\n|--------------------|-----------------------------------------------------------|\n| `pnpm dev`         | Start the web dev server against this repo's `.boardown/` (Vite, `http://localhost:5173`) |\n| `pnpm build`       | Build every package that has a `build` script (core → `dist/`, web → Vite bundle; `ui` is source-only) |\n| `pnpm test`        | Run Vitest across all packages                            |\n| `pnpm typecheck`   | Run `tsc --noEmit` in every package                       |\n| `pnpm lint`        | Run ESLint over the workspace                             |\n| `pnpm format`      | Apply Prettier in-place                                   |\n| `pnpm format:check`| Check Prettier formatting without writing                 |\n\n### Running a single package\n\nUse pnpm's `--filter`:\n\n```sh\npnpm --filter @boardown/web dev      # only the web dev server\npnpm --filter @boardown/core build   # only the core build\npnpm --filter @boardown/core test    # only core tests\n```\n\nThe dev server runs in any modern browser — it talks to the selected\n`.boardown/` over a local Vite middleware, so no File System Access API or\nChromium-only feature is involved.\n\nTo open another boardown data directory from sources, pass `--data-dir`. The\npath must point to the `.boardown` directory itself, not to the project root:\n\n```sh\npnpm dev -- --data-dir /path/to/project/.boardown\n```\n\nIf `--data-dir` is omitted, boardown uses this repository's `.boardown/`, same\nas before. Relative `--data-dir` paths are resolved from the directory where\nyou run the command.\n\n### Sample board for the dev server\n\nThe repo ships a `.boardown/` folder at the root with a minimal config and a\ncouple of empty releases / epics. `pnpm dev` reads the selected data directory\nvia a small Vite middleware that exposes `/api/fs/{read,list,stat,write}` over\nHTTP, and `@boardown/ui` mounts on top of a `DevHttpFsAdapter` that talks to\nthose endpoints. This is the working environment for UI development and local\nuse from sources; a production browser deployment (folder picker, FS Access\nAPI or otherwise) is not in the MVP scope.\n\nWhen the selected data directory has no `config.yaml`, the web shell creates\nthe default structure:\n\n```text\n.boardown/\n├── config.yaml\n├── backlog.md\n├── releases/\n│   └── v0.1.md\n└── epics/\n```\n\nThe generated config uses `idPrefix: TASK`, so the first generated task id is\n`TASK-1`:\n\n```yaml\nidPrefix: TASK\nnextId: 1\nprojectName: My Board\n```\n\nThe `projectName` field is required and shown in the app header. Create\n`config.yaml` yourself before first launch if you want a different prefix or\nproject name. The starter release is named `v0.1` and has `status: current`,\nso the board is ready for new tasks immediately.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrinev%2Fboardown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrinev%2Fboardown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrinev%2Fboardown/lists"}