@x4lt7ab/tab-for-projects 0.1.0

package/README.md

@@ -0,0 +1,266 @@
+# tab-for-projects
+
+A self-contained project management tool. Install it, run it, and get a web UI and REST API with zero configuration.
+
+All your data stays local in a single SQLite file — no external databases, no cloud accounts, no setup wizards.
+
+## Quick start
+
+```bash
+# install bun (the only prerequisite)
+curl -fsSL https://bun.sh/install | bash
+
+# install tab-for-projects
+bun install -g @x4lt7ab/tab-for-projects
+
+# run it
+tab-for-projects
+```
+
+Open `http://localhost:3000` and you're ready to go.
+
+If `tab-for-projects` is not found, add bun's global bin directory to your PATH:
+
+```bash
+echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## Configuration
+
+Everything works out of the box. If you need to customize, use environment variables or CLI flags:
+
+| Environment variable | CLI flag        | Default                               | Description                  |
+|----------------------|-----------------|---------------------------------------|------------------------------|
+| `PM_PORT`            | `--port`        | `3000`                                | HTTP port                    |
+| `PM_HOST`            | `--host`        | `127.0.0.1`                           | Bind address                 |
+| `SQLITE_PATH`        | `--sqlite-path` | `~/.tab/project-management/sqlite.db` | Full path to SQLite database |
+
+CLI flags take precedence over environment variables.
+
+```bash
+tab-for-projects --port 8080 --sqlite-path /opt/tab-for-projects/data/sqlite.db
+```
+
+## Your data
+
+All data is stored in a single file: `~/.tab/project-management/sqlite.db` by default.
+
+**Back up** your data at any time:
+
+```bash
+sqlite3 ~/.tab/project-management/sqlite.db ".backup /path/to/backup.db"
+```
+
+**Start fresh** by deleting the database file and restarting. A new one is created automatically.
+
+## API
+
+tab-for-projects exposes a REST API alongside the web UI. All endpoints return JSON.
+
+### Projects
+
+```
+GET    /api/projects          List all projects
+POST   /api/projects          Create a project
+GET    /api/projects/:slug    Get a project
+PATCH  /api/projects/:slug    Update a project
+DELETE /api/projects/:slug    Delete a project
+```
+
+**Create a project:**
+
+```bash
+curl -X POST http://localhost:3000/api/projects \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Website Redesign", "slug": "website-redesign", "description": "Q2 refresh"}'
+```
+
+**Response:**
+
+```json
+{
+  "id": "01JABBCD1234EFGH5678IJKL",
+  "name": "Website Redesign",
+  "slug": "website-redesign",
+  "description": "Q2 refresh",
+  "status": "active",
+  "created_at": "2026-03-23T12:00:00.000Z",
+  "updated_at": "2026-03-23T12:00:00.000Z"
+}
+```
+
+Project status can be `active`, `paused`, `completed`, or `archived`.
+
+### Health check
+
+```
+GET /api/health    Returns {"status": "ok"}
+```
+
+## MCP server
+
+tab-for-projects includes a [Model Context Protocol](https://modelcontextprotocol.io) server at `/mcp`, letting AI assistants manage your projects and tasks directly.
+
+The MCP endpoint is served on the same port as the API and web UI — no separate process needed.
+
+### Claude Code
+
+```bash
+claude mcp add tab-for-projects --transport http http://localhost:3000/mcp
+```
+
+Or add it to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "tab-for-projects": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Open **Settings > Developer > Edit Config** and add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tab-for-projects": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### Cursor
+
+Open **Settings > MCP Servers > Add new MCP server** and use:
+
+- **Name:** `tab-for-projects`
+- **Type:** `url`
+- **URL:** `http://localhost:3000/mcp`
+
+### Remote access
+
+To make tab-for-projects accessible from the local network, bind to all interfaces:
+
+```bash
+tab-for-projects --host 0.0.0.0
+```
+
+Then from another machine, point your MCP client at the server:
+
+```bash
+claude mcp add tab-for-projects --transport http http://192.168.1.100:3000/mcp
+```
+
+Replace `192.168.1.100` with the host's actual IP address.
+
+### Custom database path
+
+```json
+{
+  "mcpServers": {
+    "tab-for-projects": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+Start the server with a custom database path:
+
+```bash
+tab-for-projects --sqlite-path /path/to/your/sqlite.db
+```
+
+### Available tools
+
+| Tool | Description |
+|---|---|
+| `list_projects` | List all projects |
+| `get_project` | Get a project by its slug |
+| `create_project` | Create a new project (name, slug, optional description/status) |
+| `update_project` | Update a project's name, description, or status |
+| `delete_project` | Delete a project by slug |
+| `list_tasks` | List all tasks in a project |
+| `create_task` | Create a task in a project (title, optional description/status) |
+| `update_task` | Update a task's title, description, or status |
+| `delete_task` | Delete a task by ID |
+
+Task status values: `todo`, `in_progress`, `done`. Project status values: `active`, `paused`, `completed`, `archived`.
+
+## Deploying
+
+### systemd (Linux)
+
+```ini
+# /etc/systemd/system/tab-for-projects.service
+[Unit]
+Description=tab-for-projects
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=/home/pm/.bun/bin/tab-for-projects
+Environment=PM_HOST=0.0.0.0
+Environment=SQLITE_PATH=/var/lib/project-management/sqlite.db
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable --now tab-for-projects
+```
+
+### launchd (macOS)
+
+```xml
+<!-- ~/Library/LaunchAgents/com.alttab.tab-for-projects.plist -->
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.alttab.tab-for-projects</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/Users/you/.bun/bin/tab-for-projects</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+</dict>
+</plist>
+```
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.alttab.tab-for-projects.plist
+```
+
+## Upgrading
+
+```bash
+bun install -g @x4lt7ab/tab-for-projects@latest
+```
+
+Restart the server after upgrading. Database migrations run automatically — your data is preserved.
+
+## Contributing
+
+tab-for-projects is built with TypeScript, Bun, Hono, and React. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and architecture details.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@x4lt7ab/tab-for-projects",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "tab-for-projects": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "scripts": {
+    "dev": "bun run --hot src/index.ts & cd src/web && vite",
+    "build": "cd src/web && vite build",
+    "start": "bun run src/index.ts",
+    "serve": "bun run build && bun run start",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@x4lt7ab/tab-for-projects": "/Users/alttab/AltT4b/project-management",
+    "hono": "^4",
+    "ulid": "^2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2",
+    "@types/react": "^19.1.2",
+    "@types/react-dom": "^19.1.2",
+    "@vitejs/plugin-react": "^4.4.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5"
+  }
+}

package/src/domain/args.ts

@@ -0,0 +1,41 @@
+import { networkInterfaces } from "os";
+
+export interface ServerOptions {
+  port: number;
+  host: string;
+  dbPath?: string;
+}
+
+export function parseArgs(defaults: { port: number; portEnv: string }): ServerOptions {
+  const args = process.argv.slice(2);
+  let port = Number(process.env[defaults.portEnv]) || defaults.port;
+  let host = process.env.PM_HOST ?? "127.0.0.1";
+  let dbPath: string | undefined = process.env.SQLITE_PATH;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--port" && args[i + 1]) port = Number(args[++i]);
+    if (args[i] === "--host" && args[i + 1]) host = args[++i];
+    if (args[i] === "--sqlite-path" && args[i + 1]) dbPath = args[++i];
+  }
+
+  return { port, host, dbPath };
+}
+
+export function getNetworkAddress(): string | undefined {
+  for (const addrs of Object.values(networkInterfaces())) {
+    for (const addr of addrs ?? []) {
+      if (addr.family === "IPv4" && !addr.internal) return addr.address;
+    }
+  }
+}
+
+export function logListening(name: string, host: string, port: number): void {
+  const displayHost = host === "0.0.0.0" ? "localhost" : host;
+  console.error(`${name} listening on http://${displayHost}:${port}`);
+  if (host === "0.0.0.0") {
+    const networkAddr = getNetworkAddress();
+    if (networkAddr) {
+      console.error(`${name} network: http://${networkAddr}:${port}`);
+    }
+  }
+}

package/src/domain/bootstrap.ts

@@ -0,0 +1,26 @@
+import type { Database } from "bun:sqlite";
+import { createDatabase } from "./db/connection";
+import { runMigrations } from "./db/schema";
+import { ProjectRepository } from "./repositories/projects";
+import { TaskRepository } from "./repositories/tasks";
+import { ProjectService } from "./services/projects";
+import { TaskService } from "./services/tasks";
+import type { IProjectService, ITaskService } from "./services";
+
+export interface AppContext {
+  db: Database;
+  projectService: IProjectService;
+  taskService: ITaskService;
+}
+
+export function bootstrap(dbPath?: string): AppContext {
+  const db = createDatabase(dbPath);
+  runMigrations(db);
+
+  const projectRepo = new ProjectRepository(db);
+  const taskRepo = new TaskRepository(db);
+  const projectService = new ProjectService(projectRepo);
+  const taskService = new TaskService(taskRepo, projectRepo);
+
+  return { db, projectService, taskService };
+}

package/src/domain/db/connection.ts

@@ -0,0 +1,21 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const DEFAULT_DB_PATH = join(homedir(), ".tab", "project-management", "sqlite.db");
+
+export function getDbPath(): string {
+  return process.env.SQLITE_PATH ?? DEFAULT_DB_PATH;
+}
+
+export function createDatabase(dbPath?: string): Database {
+  const resolvedPath = dbPath ?? getDbPath();
+  mkdirSync(join(resolvedPath, ".."), { recursive: true });
+
+  const db = new Database(resolvedPath);
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA foreign_keys = ON");
+
+  return db;
+}

package/src/domain/db/schema.ts

@@ -0,0 +1,35 @@
+import type { Database } from "bun:sqlite";
+import { PROJECT_STATUSES, TASK_STATUSES } from "../statuses";
+
+const projectStatusCheck = PROJECT_STATUSES.map((s) => `'${s}'`).join(", ");
+const taskStatusCheck = TASK_STATUSES.map((s) => `'${s}'`).join(", ");
+
+export function runMigrations(db: Database): void {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS projects (
+      id          TEXT PRIMARY KEY,
+      slug        TEXT NOT NULL UNIQUE,
+      name        TEXT NOT NULL,
+      description TEXT NOT NULL DEFAULT '',
+      status      TEXT NOT NULL DEFAULT 'active'
+                  CHECK (status IN (${projectStatusCheck})),
+      created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    )
+  `);
+
+  db.run("CREATE UNIQUE INDEX IF NOT EXISTS idx_projects_slug ON projects(slug)");
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS tasks (
+      id          TEXT PRIMARY KEY,
+      project_id  TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+      title       TEXT NOT NULL,
+      description TEXT NOT NULL DEFAULT '',
+      status      TEXT NOT NULL DEFAULT 'todo'
+                  CHECK (status IN (${taskStatusCheck})),
+      created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+      updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+    )
+  `);
+}

package/src/domain/entities.ts

@@ -0,0 +1,21 @@
+import type { ProjectStatus, TaskStatus } from "./statuses";
+
+export interface Project {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  status: ProjectStatus;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface Task {
+  id: string;
+  project_id: string;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  created_at: string;
+  updated_at: string;
+}

package/src/domain/errors.ts

@@ -0,0 +1,9 @@
+export class ServiceError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number
+  ) {
+    super(message);
+    this.name = "ServiceError";
+  }
+}

package/src/domain/index.ts

@@ -0,0 +1,12 @@
+export * from "./statuses";
+export * from "./entities";
+export * from "./inputs";
+export * from "./errors";
+export * from "./services";
+export * from "./bootstrap";
+export { createDatabase, getDbPath } from "./db/connection";
+export { runMigrations } from "./db/schema";
+export { ProjectRepository } from "./repositories/projects";
+export { TaskRepository } from "./repositories/tasks";
+export { ProjectService } from "./services/projects";
+export { TaskService } from "./services/tasks";

package/src/domain/inputs.ts

@@ -0,0 +1,13 @@
+import type { Project, Task } from "./entities";
+
+export type CreateProjectInput = Pick<Project, "name" | "slug"> &
+  Partial<Pick<Project, "description" | "status">>;
+
+export type UpdateProjectInput = Partial<
+  Pick<Project, "name" | "description" | "status">
+>;
+
+export type CreateTaskInput = Pick<Task, "title"> &
+  Partial<Pick<Task, "description" | "status">>;
+
+export type UpdateTaskInput = Partial<Pick<Task, "title" | "description" | "status">>;

package/src/domain/repositories/projects.ts

@@ -0,0 +1,75 @@
+import type { Database } from "bun:sqlite";
+import { ulid } from "ulid";
+import type { Project } from "../entities";
+import type { CreateProjectInput, UpdateProjectInput } from "../inputs";
+
+export class ProjectRepository {
+  constructor(private db: Database) {}
+
+  findAll(): Project[] {
+    return this.db
+      .query("SELECT * FROM projects ORDER BY created_at DESC")
+      .all() as Project[];
+  }
+
+  findById(id: string): Project | null {
+    return (
+      this.db.query("SELECT * FROM projects WHERE id = ?").get(id) as Project | null
+    );
+  }
+
+  findBySlug(slug: string): Project | null {
+    return (
+      this.db.query("SELECT * FROM projects WHERE slug = ?").get(slug) as Project | null
+    );
+  }
+
+  create(input: CreateProjectInput): Project {
+    const id = ulid();
+    const now = new Date().toISOString();
+
+    this.db
+      .query(
+        `INSERT INTO projects (id, slug, name, description, status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      )
+      .run(
+        id,
+        input.slug,
+        input.name,
+        input.description ?? "",
+        input.status ?? "active",
+        now,
+        now
+      );
+
+    return this.findById(id)!;
+  }
+
+  update(slug: string, input: UpdateProjectInput): Project | null {
+    const existing = this.findBySlug(slug);
+    if (!existing) return null;
+
+    const name = input.name ?? existing.name;
+    const description = input.description ?? existing.description;
+    const status = input.status ?? existing.status;
+    const now = new Date().toISOString();
+
+    this.db
+      .query(
+        `UPDATE projects
+         SET name = ?, description = ?, status = ?, updated_at = ?
+         WHERE slug = ?`
+      )
+      .run(name, description, status, now, slug);
+
+    return this.findBySlug(slug)!;
+  }
+
+  delete(slug: string): boolean {
+    const result = this.db
+      .query("DELETE FROM projects WHERE slug = ?")
+      .run(slug);
+    return result.changes > 0;
+  }
+}

package/src/domain/repositories/tasks.ts

@@ -0,0 +1,62 @@
+import type { Database } from "bun:sqlite";
+import { ulid } from "ulid";
+import type { Task } from "../entities";
+import type { CreateTaskInput } from "../inputs";
+import type { UpdateTaskInput } from "../inputs";
+
+export class TaskRepository {
+  constructor(private db: Database) {}
+
+  findByProject(projectId: string): Task[] {
+    return this.db
+      .query("SELECT * FROM tasks WHERE project_id = ? ORDER BY created_at ASC")
+      .all(projectId) as Task[];
+  }
+
+  create(projectId: string, input: CreateTaskInput): Task {
+    const id = ulid();
+    const now = new Date().toISOString();
+
+    this.db
+      .query(
+        `INSERT INTO tasks (id, project_id, title, description, status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+      )
+      .run(
+        id,
+        projectId,
+        input.title,
+        input.description ?? "",
+        input.status ?? "todo",
+        now,
+        now
+      );
+
+    return this.db.query("SELECT * FROM tasks WHERE id = ?").get(id) as Task;
+  }
+
+  update(id: string, input: UpdateTaskInput): Task | null {
+    const existing = this.db
+      .query("SELECT * FROM tasks WHERE id = ?")
+      .get(id) as Task | null;
+    if (!existing) return null;
+
+    const title = input.title ?? existing.title;
+    const description = input.description ?? existing.description;
+    const status = input.status ?? existing.status;
+    const now = new Date().toISOString();
+
+    this.db
+      .query(
+        `UPDATE tasks SET title = ?, description = ?, status = ?, updated_at = ? WHERE id = ?`
+      )
+      .run(title, description, status, now, id);
+
+    return this.db.query("SELECT * FROM tasks WHERE id = ?").get(id) as Task;
+  }
+
+  delete(id: string): boolean {
+    const result = this.db.query("DELETE FROM tasks WHERE id = ?").run(id);
+    return result.changes > 0;
+  }
+}