mdboard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,191 @@
+# mdboard
+
+Git-based project management dashboard. Zero dependencies. Reads markdown files with YAML frontmatter and serves a visual kanban board, table view, milestone tracker, and metrics dashboard.
+
+Built for AI-assisted workflows — the `project/` directory is plain text that both humans and AI agents can read and update.
+
+## Quick Start
+
+```bash
+# Run instantly with npx
+npx mdboard
+
+# Or install globally
+npm install -g mdboard
+mdboard
+```
+
+## CLI Commands
+
+### `mdboard` — Start Dashboard
+
+Starts the HTTP server and opens the dashboard at `http://localhost:3333`.
+
+```bash
+mdboard                          # Serve current directory
+mdboard --port 4000              # Custom port
+mdboard --project /path/to/repo  # Specify workspace root
+```
+
+### `mdboard init` — Scaffold Project
+
+Creates a `project/` directory with starter templates.
+
+```bash
+mdboard init
+```
+
+Creates:
+```
+project/
+├── PROJECT.md      # Project overview
+├── metrics.md      # Velocity tracking
+├── milestones/     # Milestone directories go here
+└── archive/        # Completed milestones/sprints
+```
+
+### `mdboard --help`
+
+Show usage information.
+
+### `mdboard --version`
+
+Print version number.
+
+## Project Structure
+
+mdboard reads a `project/` directory with this structure:
+
+```
+project/
+├── PROJECT.md                              # Project overview and current state
+├── metrics.md                              # Velocity, quality, sprint health
+├── milestones/
+│   └── {milestone}/
+│       ├── README.md                       # Milestone description, done criteria
+│       ├── epics/
+│       │   └── {epic}/
+│       │       ├── README.md               # Epic description, dependencies
+│       │       └── backlog/
+│       │           └── FEAT-NNN-slug.md    # Feature specs with acceptance criteria
+│       └── sprints/
+│           └── {sprint}/
+│               ├── plan.md                 # Sprint goal, feature list, dates
+│               ├── board.md                # Kanban state
+│               └── review.md              # Sprint retrospective
+└── archive/                                # Completed milestones/sprints
+```
+
+## Frontmatter Schemas
+
+### PROJECT.md
+
+```yaml
+---
+name: "Project Name"
+description: "One-line description"
+created: 2026-01-01
+---
+```
+
+### Feature (FEAT-NNN-slug.md)
+
+```yaml
+---
+id: FEAT-001
+title: "Feature title"
+epic: epic-name
+milestone: mvp
+status: backlog          # backlog | todo | in-progress | in-review | done | blocked
+sprint: null
+priority: high           # urgent | high | medium | low
+points: 5
+assigned: []
+created: 2026-01-01
+started: null
+completed: null
+---
+```
+
+### Milestone README.md
+
+```yaml
+---
+id: mvp
+title: "Minimum Viable Product"
+status: active           # planned | active | completed
+deadline: null
+created: 2026-01-01
+---
+```
+
+### Epic README.md
+
+```yaml
+---
+id: epic-name
+title: "Epic Title"
+milestone: mvp
+status: active           # active | completed | blocked
+priority: high
+dependencies: []
+created: 2026-01-01
+---
+```
+
+### Sprint plan.md
+
+```yaml
+---
+id: sprint-001
+milestone: mvp
+status: active           # planned | active | completed | cancelled
+goal: "Sprint goal"
+start_date: 2026-01-01
+end_date: 2026-01-15
+planned_points: 12
+completed_points: 0
+features: [FEAT-001, FEAT-002]
+---
+```
+
+## Dashboard Views
+
+- **Board** — Kanban board with drag-and-drop. Filter by priority, epic, milestone.
+- **Table** — Sortable table of all features with filters.
+- **Milestones** — Progress view per milestone with epic breakdowns.
+- **Metrics** — Status breakdown, priority distribution, velocity, project health.
+
+## API Endpoints
+
+The server exposes a JSON API:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/project` | Project metadata |
+| GET | `/api/milestones` | All milestones with progress |
+| GET | `/api/epics` | All epics with progress |
+| GET | `/api/features` | All features (filterable via query params) |
+| GET | `/api/sprints` | All sprints |
+| GET | `/api/sprint` | Active sprint with board |
+| GET | `/api/metrics` | Metrics data |
+| GET | `/api/health` | Project health summary |
+| GET | `/api/events` | SSE stream for live updates |
+| PATCH | `/api/features/:id` | Update feature fields |
+| PATCH | `/api/epics/:id` | Update epic fields |
+| PATCH | `/api/milestones/:id` | Update milestone fields |
+| PATCH | `/api/sprints/:id` | Update sprint fields |
+
+## AI Agent Integration
+
+The `project/` directory is designed to be read and updated by AI agents. Agents can:
+
+1. Read `PROJECT.md` to understand project context
+2. Scan features to find work items
+3. Update feature status via file edits or the PATCH API
+4. Create new features by writing markdown files
+5. Use the API to query project state programmatically
+
+## License
+
+MIT

package/bin.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === '--version' || command === '-v') {
+  const pkg = require('./package.json');
+  console.log('mdboard v' + pkg.version);
+  process.exit(0);
+}
+
+if (command === '--help' || command === '-h') {
+  printHelp();
+  process.exit(0);
+}
+
+if (command === 'init') {
+  require('./init.js');
+} else if (command === 'help') {
+  printHelp();
+  process.exit(0);
+} else {
+  // Default: start server. Pass all args through.
+  require('./server.js');
+}
+
+function printHelp() {
+  console.log(`
+  mdboard — Git-based project management dashboard
+
+  Usage:
+    mdboard                    Start the dashboard server
+    mdboard init               Scaffold a new project/ directory
+    mdboard --version          Print version
+    mdboard --help             Show this help
+
+  Server options:
+    --project <path>           Workspace root directory (default: cwd)
+    --port <number>            Server port (default: 3333)
+
+  Examples:
+    npx mdboard                Start dashboard in current directory
+    npx mdboard init           Create project/ with templates
+    npx mdboard --port 4000    Start on port 4000
+`);
+}