prodboard 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# prodboard
+
+## 0.1.0
+
+### Minor Changes
+
+- dc917e9: Initial release of prodboard — a self-hosted, CLI-first issue tracker and cron scheduler for AI coding agents.
+
+  Features:
+
+  - Full CLI for issue tracking (add, ls, show, edit, mv, rm, comment)
+  - MCP server with 14 tools for AI agent integration
+  - Cron-based scheduler daemon for automated agent runs
+  - SQLite-backed persistent storage
+  - Configurable via JSONC config file
+  - Template engine for schedule prompts with board context injection

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prodboard contributors
+
+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,294 @@
+# prodboard
+
+A self-hosted, CLI-first issue tracker and cron scheduler for AI coding agents.
+
+## Overview
+
+prodboard provides three interfaces for managing issues and scheduled AI tasks:
+
+- **CLI** — Human-friendly commands for issue tracking and schedule management
+- **MCP Server** — Model Context Protocol server for AI agent integration
+- **Scheduler Daemon** — Cron-based task scheduler that invokes Claude on a schedule
+
+All state lives in a single SQLite database at `~/.prodboard/db.sqlite`.
+
+## Quick Start
+
+### Install
+
+```bash
+bun install -g prodboard
+```
+
+### Initialize
+
+```bash
+prodboard init
+```
+
+This creates `~/.prodboard/` with the database, config, and generated files.
+
+### Connect to Claude
+
+```bash
+claude mcp add prodboard -- bunx prodboard mcp
+```
+
+Or copy the generated MCP config:
+
+```bash
+cat ~/.prodboard/mcp.json
+```
+
+### Add the CLAUDE.md (optional)
+
+```bash
+prodboard init --claude-md
+```
+
+## CLI Reference
+
+### Issue Management
+
+```bash
+# Create an issue
+prodboard add "Fix login bug" -d "SameSite cookie issue on Safari" -s todo
+
+# List issues
+prodboard ls                        # All non-archived issues
+prodboard ls --status todo          # Filter by status
+prodboard ls --search "login"       # Search title/description
+prodboard ls --json                 # JSON output
+prodboard ls --all                  # Include archived
+
+# Show issue details
+prodboard show <id>                 # Full ID or unique prefix
+prodboard show a3f9                 # Prefix match
+
+# Edit an issue
+prodboard edit <id> --title "New title"
+prodboard edit <id> --status review
+prodboard edit <id> -d "Updated description"
+
+# Move issue status
+prodboard mv <id> done
+
+# Delete an issue
+prodboard rm <id> --force
+
+# Comments
+prodboard comment <id> "Looking into this"
+prodboard comment <id> "Fixed it" --author claude
+prodboard comments <id>
+prodboard comments <id> --json
+```
+
+### Schedule Management
+
+```bash
+# Create a schedule
+prodboard schedule add \
+  --name "daily-triage" \
+  --cron "0 9 * * 1-5" \
+  --prompt "Review the board and triage new issues"
+
+# List schedules
+prodboard schedule ls
+prodboard schedule ls --all --json
+
+# Edit a schedule
+prodboard schedule edit <id> --cron "0 10 * * *"
+
+# Enable/disable
+prodboard schedule enable <id>
+prodboard schedule disable <id>
+
+# Delete
+prodboard schedule rm <id> --force
+
+# Run immediately (foreground)
+prodboard schedule run <id>
+
+# View run history
+prodboard schedule logs
+prodboard schedule logs --schedule <id> --limit 10
+
+# View statistics
+prodboard schedule stats
+prodboard schedule stats --schedule <id> --days 7
+```
+
+### Daemon
+
+```bash
+# Start daemon (foreground, for systemd)
+prodboard daemon
+
+# Dry run (show schedules without executing)
+prodboard daemon --dry-run
+
+# Check daemon status
+prodboard daemon status
+```
+
+### Other
+
+```bash
+prodboard config    # Show current configuration
+prodboard version   # Show version
+prodboard help      # Show help
+```
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `board_summary` | Overview of issues by status, recent issues |
+| `list_issues` | List issues with optional filters |
+| `get_issue` | Get full issue details with comments |
+| `create_issue` | Create a new issue |
+| `update_issue` | Update issue fields |
+| `delete_issue` | Delete an issue |
+| `add_comment` | Add a comment (default author: claude) |
+| `pick_next_issue` | Claim next todo, move to in-progress |
+| `complete_issue` | Mark done with optional comment |
+| `list_schedules` | List scheduled tasks |
+| `create_schedule` | Create a scheduled task |
+| `update_schedule` | Update a scheduled task |
+| `delete_schedule` | Delete a scheduled task |
+| `list_runs` | View run history |
+
+### MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `prodboard://issues` | Board summary (same as board_summary) |
+| `prodboard://schedules` | Active schedules with next run times |
+
+## Configuration
+
+Config file: `~/.prodboard/config.jsonc` (JSONC format — comments allowed)
+
+```jsonc
+{
+  "general": {
+    // Issue statuses in display order
+    "statuses": ["todo", "in-progress", "review", "done", "archived"],
+    // Default status for new issues
+    "defaultStatus": "todo",
+    // Optional prefix for issue IDs
+    "idPrefix": ""
+  },
+  "daemon": {
+    // Max concurrent scheduled runs
+    "maxConcurrentRuns": 2,
+    // Default max turns for Claude
+    "maxTurns": 50,
+    // Absolute max (cannot be overridden)
+    "hardMaxTurns": 200,
+    // Run timeout in seconds
+    "runTimeoutSeconds": 1800,
+    // Days to keep run history
+    "runRetentionDays": 30,
+    // Log level: debug, info, warn, error
+    "logLevel": "info",
+    // Worktree usage: auto, always, never
+    "useWorktrees": "auto"
+  }
+}
+```
+
+## Scheduler Guide
+
+### Cron Syntax
+
+Standard 5-field cron expressions:
+
+```
+minute (0-59)
+hour (0-23)
+day of month (1-31)
+month (1-12)
+day of week (0-6, 0=Sunday)
+```
+
+Examples:
+- `0 9 * * 1-5` — Weekdays at 9:00 AM
+- `*/15 * * * *` — Every 15 minutes
+- `0 0 1 * *` — First of every month at midnight
+- `0 9,17 * * *` — 9 AM and 5 PM daily
+
+### Template Variables
+
+Use in schedule prompts:
+
+| Variable | Description |
+|----------|-------------|
+| `{{board_summary}}` | Compact summary: "3 todo, 1 in-progress, 0 review" |
+| `{{todo_count}}` | Number of todo issues |
+| `{{in_progress_count}}` | Number of in-progress issues |
+| `{{datetime}}` | Current ISO 8601 timestamp |
+| `{{schedule_name}}` | Name of the schedule |
+
+Example:
+
+```bash
+prodboard schedule add \
+  --name "morning-standup" \
+  --cron "0 9 * * 1-5" \
+  --prompt "Board status: {{board_summary}}. Pick and work on the next todo issue."
+```
+
+## Running as a Service
+
+### systemd
+
+Create `/etc/systemd/system/prodboard.service`:
+
+```ini
+[Unit]
+Description=prodboard scheduler daemon
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+ExecStart=/usr/local/bin/bun run prodboard daemon
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable prodboard
+sudo systemctl start prodboard
+sudo systemctl status prodboard
+```
+
+## Troubleshooting
+
+**"prodboard is not initialized"**
+Run `prodboard init` to create `~/.prodboard/`.
+
+**MCP server not connecting**
+Check that `~/.prodboard/mcp.json` exists and the path to prodboard is correct.
+
+**Daemon not starting**
+Check `~/.prodboard/logs/daemon.log` for errors. Ensure claude CLI is installed and accessible.
+
+**Stale PID file**
+If `prodboard daemon status` shows "stale PID file", the daemon crashed. It will auto-clean the PID file. Run `prodboard daemon` to restart.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+```
+
+## License
+
+MIT

package/bin/prodboard.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { main } from "../src/index.ts";
+
+main();

package/config.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "prodboard Configuration",
+  "type": "object",
+  "properties": {
+    "general": {
+      "type": "object",
+      "properties": {
+        "statuses": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["todo", "in-progress", "review", "done", "archived"],
+          "description": "Issue statuses in display order"
+        },
+        "defaultStatus": {
+          "type": "string",
+          "default": "todo",
+          "description": "Default status for new issues"
+        },
+        "idPrefix": {
+          "type": "string",
+          "default": "",
+          "description": "Optional prefix for issue IDs"
+        }
+      },
+      "additionalProperties": false
+    },
+    "daemon": {
+      "type": "object",
+      "properties": {
+        "maxConcurrentRuns": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 2,
+          "description": "Maximum concurrent scheduled runs"
+        },
+        "maxTurns": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 50,
+          "description": "Default max turns for Claude invocations"
+        },
+        "hardMaxTurns": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 200,
+          "description": "Absolute max turns (cannot be overridden)"
+        },
+        "runTimeoutSeconds": {
+          "type": "integer",
+          "minimum": 60,
+          "default": 1800,
+          "description": "Timeout per run in seconds"
+        },
+        "runRetentionDays": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 30,
+          "description": "Days to retain run history"
+        },
+        "logLevel": {
+          "type": "string",
+          "enum": ["debug", "info", "warn", "error"],
+          "default": "info",
+          "description": "Daemon log level"
+        },
+        "logMaxSizeMb": {
+          "type": "number",
+          "minimum": 1,
+          "default": 10,
+          "description": "Max log file size in MB"
+        },
+        "logMaxFiles": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 5,
+          "description": "Max number of rotated log files"
+        },
+        "defaultAllowedTools": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Default tools allowed for scheduled runs"
+        },
+        "nonGitDefaultAllowedTools": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Default tools for non-git environments"
+        },
+        "useWorktrees": {
+          "type": "string",
+          "enum": ["auto", "always", "never"],
+          "default": "auto",
+          "description": "Worktree usage strategy"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -1,11 +1,52 @@
 {
   "name": "prodboard",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
+  "version": "0.1.0",
+  "description": "Self-hosted, CLI-first issue tracker and cron scheduler for AI coding agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/G4brym/prodboard"
+  },
+  "homepage": "https://github.com/G4brym/prodboard#readme",
+  "bugs": {
+    "url": "https://github.com/G4brym/prodboard/issues"
+  },
+  "keywords": [
+    "cli",
+    "issue-tracker",
+    "mcp",
+    "ai-agents",
+    "scheduler",
+    "cron",
+    "sqlite"
+  ],
+  "bin": {
+    "prodboard": "bin/prodboard.ts"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "bun run bin/prodboard.ts",
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "bun run test && bun run typecheck && npm publish"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
   },
-  "author": "",
-  "license": "MIT"
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "config.schema.json",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@types/bun": "^1.3.9"
+  }
 }

package/src/commands/comments.ts

@@ -0,0 +1,86 @@
+import { Database } from "bun:sqlite";
+import { ensureDb } from "../db.ts";
+import { getIssueByPrefix } from "../queries/issues.ts";
+import { createComment, listComments } from "../queries/comments.ts";
+import { renderTable, formatDate, jsonOutput } from "../format.ts";
+
+function parseArgs(args: string[]): { flags: Record<string, string | boolean>; positional: string[] } {
+  const flags: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        flags[key] = args[++i];
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const key = arg.slice(1);
+      if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        flags[key] = args[++i];
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+export async function comment(args: string[], dbOverride?: Database): Promise<void> {
+  const { flags, positional } = parseArgs(args);
+  const issueIdOrPrefix = positional[0];
+  const body = positional.slice(1).join(" ");
+
+  if (!issueIdOrPrefix || !body) {
+    console.error("Usage: prodboard comment <issue-id> <body> [--author/-a author]");
+    throw new Error("Invalid arguments");
+  }
+
+  const db = dbOverride ?? ensureDb();
+  const issue = getIssueByPrefix(db, issueIdOrPrefix);
+
+  const author = (flags.author ?? flags.a) as string | undefined;
+  const c = createComment(db, {
+    issue_id: issue.id,
+    body,
+    author: typeof author === "string" ? author : undefined,
+  });
+
+  console.log(`Added comment by ${c.author} on issue ${issue.id}`);
+}
+
+export async function comments(args: string[], dbOverride?: Database): Promise<void> {
+  const { flags, positional } = parseArgs(args);
+  const issueIdOrPrefix = positional[0];
+
+  if (!issueIdOrPrefix) {
+    console.error("Usage: prodboard comments <issue-id> [--json]");
+    throw new Error("Invalid arguments");
+  }
+
+  const db = dbOverride ?? ensureDb();
+  const issue = getIssueByPrefix(db, issueIdOrPrefix);
+  const cmts = listComments(db, issue.id);
+
+  if (flags.json) {
+    console.log(jsonOutput(cmts));
+    return;
+  }
+
+  if (cmts.length === 0) {
+    console.log("No comments.");
+    return;
+  }
+
+  const table = renderTable(
+    ["Author", "Date", "Comment"],
+    cmts.map((c) => [c.author, formatDate(c.created_at), c.body]),
+    { maxWidths: [12, 18, 60] }
+  );
+  console.log(table);
+}

package/src/commands/daemon.ts

@@ -0,0 +1,112 @@
+import * as fs from "fs";
+import * as path from "path";
+import { ensureDb } from "../db.ts";
+import { loadConfig, PRODBOARD_DIR } from "../config.ts";
+import { listSchedules } from "../queries/schedules.ts";
+import { getNextFire } from "../cron.ts";
+import { formatDate } from "../format.ts";
+import { Daemon } from "../scheduler.ts";
+
+function parseArgs(args: string[]): { flags: Record<string, string | boolean>; positional: string[] } {
+  const flags: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      if (key === "dry-run" || key === "foreground") {
+        flags[key] = true;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
+        flags[key] = args[++i];
+      } else {
+        flags[key] = true;
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const key = arg.slice(1);
+      if (key === "f") {
+        flags.foreground = true;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+export async function daemonStart(args: string[]): Promise<void> {
+  const { flags } = parseArgs(args);
+  const db = ensureDb();
+  const config = loadConfig();
+
+  if (flags["dry-run"]) {
+    const schedules = listSchedules(db);
+    if (schedules.length === 0) {
+      console.log("No active schedules.");
+      return;
+    }
+
+    console.log("Active schedules (dry run):\n");
+    for (const s of schedules) {
+      let nextFire = "N/A";
+      try {
+        const next = getNextFire(s.cron, new Date());
+        nextFire = formatDate(next.toISOString());
+      } catch {}
+      console.log(`  ${s.id}  ${s.name}`);
+      console.log(`    Cron: ${s.cron}`);
+      console.log(`    Next: ${nextFire}`);
+      console.log();
+    }
+    return;
+  }
+
+  const daemon = new Daemon(db, config);
+  await daemon.start();
+
+  // Keep process alive
+  await new Promise(() => {});
+}
+
+export async function daemonStatus(args: string[]): Promise<void> {
+  const pidFile = path.join(PRODBOARD_DIR, "daemon.pid");
+
+  if (!fs.existsSync(pidFile)) {
+    console.log("Daemon is not running (no PID file).");
+    return;
+  }
+
+  const pidStr = fs.readFileSync(pidFile, "utf-8").trim();
+  const pid = parseInt(pidStr, 10);
+
+  let running = false;
+  try {
+    process.kill(pid, 0);
+    running = true;
+  } catch {}
+
+  if (running) {
+    console.log(`Daemon is running (PID ${pid}).`);
+
+    // Show next scheduled runs
+    try {
+      const db = ensureDb();
+      const schedules = listSchedules(db);
+      if (schedules.length > 0) {
+        console.log("\nUpcoming runs:");
+        for (const s of schedules) {
+          try {
+            const next = getNextFire(s.cron, new Date());
+            console.log(`  ${s.name}: ${formatDate(next.toISOString())}`);
+          } catch {}
+        }
+      }
+    } catch {}
+  } else {
+    console.log(`Daemon is not running (stale PID file: ${pid}).`);
+    // Clean up stale PID file
+    try { fs.unlinkSync(pidFile); } catch {}
+  }
+}