@task-mcp/cli 1.0.4

package/README.md

@@ -0,0 +1,88 @@
+# @task-mcp/cli
+
+Zero-dependency CLI for task-mcp with beautiful terminal visualization.
+
+```
+████████  █████  ███████ ██   ██     ███    ███  ██████ ██████
+   ██    ██   ██ ██      ██  ██      ████  ████ ██      ██   ██
+   ██    ███████ ███████ █████       ██ ████ ██ ██      ██████
+   ██    ██   ██      ██ ██  ██      ██  ██  ██ ██      ██
+   ██    ██   ██ ███████ ██   ██     ██      ██  ██████ ██
+```
+
+## Requirements
+
+- **Bun** runtime (not Node.js)
+
+## Installation
+
+```bash
+# Install globally
+bun add -g @task-mcp/cli
+
+# Or run directly
+bunx @task-mcp/cli
+```
+
+## Usage
+
+```bash
+# Show dashboard (default)
+task
+
+# Show dashboard for specific project
+task dashboard proj_abc123
+task d proj_abc123
+
+# List all tasks
+task list
+task ls
+
+# List tasks with filters
+task list --status pending --priority high
+task list --status pending,in_progress
+task list --all  # Include completed/cancelled
+
+# List projects
+task projects
+task p
+task projects --all  # Include archived
+
+# Help & version
+task help
+task version
+```
+
+## Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `dashboard [id]` | `d` | Show project dashboard with stats and task table |
+| `list` | `ls` | List tasks with optional filters |
+| `projects` | `p` | List all projects |
+| `help` | - | Show help message |
+| `version` | - | Show version |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--status <status>` | Filter by status (pending, in_progress, blocked, completed, cancelled) |
+| `--priority <priority>` | Filter by priority (critical, high, medium, low) |
+| `--all` | Include completed/cancelled tasks or archived projects |
+
+## Dashboard Features
+
+- **Progress Bar**: Visual task completion progress
+- **Priority Breakdown**: Tasks grouped by priority level
+- **Dependency Metrics**: Ready tasks, blocked tasks, most depended-on task
+- **Next Task Suggestion**: AI-powered recommendation for next task
+- **Task Table**: Full task list with status, priority, and dependencies
+
+## Data Location
+
+The CLI reads data from the `.tasks/` directory created by the task-mcp MCP server.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@task-mcp/cli",
+  "version": "1.0.4",
+  "description": "Zero-dependency CLI for task-mcp with Bun native visualization",
+  "type": "module",
+  "bin": {
+    "task": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "bun run ./src/index.ts",
+    "dashboard": "bun run ./src/index.ts dashboard",
+    "typecheck": "bun --bun tsc --noEmit"
+  },
+  "keywords": [
+    "task-mcp",
+    "cli",
+    "task-management",
+    "terminal",
+    "dashboard"
+  ],
+  "author": "addsalt1t",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/addsalt1t/task-mcp.git",
+    "directory": "packages/cli"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.14",
+    "typescript": "^5.7.2"
+  }
+}

package/src/ansi.ts

@@ -0,0 +1,422 @@
+/**
+ * Zero-dependency ANSI utilities for terminal visualization
+ * Uses Bun native APIs where available, falls back to raw ANSI codes
+ */
+
+// ANSI escape codes
+const ESC = "\x1b[";
+const RESET = `${ESC}0m`;
+
+// Color codes (foreground)
+const FG = {
+  black: 30,
+  red: 31,
+  green: 32,
+  yellow: 33,
+  blue: 34,
+  magenta: 35,
+  cyan: 36,
+  white: 37,
+  gray: 90,
+  brightRed: 91,
+  brightGreen: 92,
+  brightYellow: 93,
+  brightBlue: 94,
+  brightMagenta: 95,
+  brightCyan: 96,
+  brightWhite: 97,
+} as const;
+
+// Style codes
+const STYLE = {
+  bold: 1,
+  dim: 2,
+  italic: 3,
+  underline: 4,
+  inverse: 7,
+  strikethrough: 9,
+} as const;
+
+type ColorName = keyof typeof FG;
+type StyleName = keyof typeof STYLE;
+
+/**
+ * Apply color to text
+ */
+export function color(text: string, colorName: ColorName): string {
+  return `${ESC}${FG[colorName]}m${text}${RESET}`;
+}
+
+/**
+ * Apply style to text
+ */
+export function style(text: string, styleName: StyleName): string {
+  return `${ESC}${STYLE[styleName]}m${text}${RESET}`;
+}
+
+/**
+ * Combine color and style
+ */
+export function styled(text: string, colorName: ColorName, styleName?: StyleName): string {
+  if (styleName) {
+    return `${ESC}${STYLE[styleName]};${FG[colorName]}m${text}${RESET}`;
+  }
+  return color(text, colorName);
+}
+
+// Convenience color functions
+export const c = {
+  red: (t: string) => color(t, "red"),
+  green: (t: string) => color(t, "green"),
+  yellow: (t: string) => color(t, "yellow"),
+  blue: (t: string) => color(t, "blue"),
+  cyan: (t: string) => color(t, "cyan"),
+  magenta: (t: string) => color(t, "magenta"),
+  gray: (t: string) => color(t, "gray"),
+  white: (t: string) => color(t, "white"),
+  bold: (t: string) => style(t, "bold"),
+  dim: (t: string) => style(t, "dim"),
+
+  // Semantic colors
+  success: (t: string) => color(t, "green"),
+  error: (t: string) => color(t, "red"),
+  warning: (t: string) => color(t, "yellow"),
+  info: (t: string) => color(t, "cyan"),
+  muted: (t: string) => color(t, "gray"),
+};
+
+// Box drawing characters (Unicode)
+export const BOX = {
+  // Single line
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  horizontal: "─",
+  vertical: "│",
+
+  // T-junctions
+  tTop: "┬",
+  tBottom: "┴",
+  tLeft: "├",
+  tRight: "┤",
+  cross: "┼",
+
+  // Double line
+  dTopLeft: "╔",
+  dTopRight: "╗",
+  dBottomLeft: "╚",
+  dBottomRight: "╝",
+  dHorizontal: "═",
+  dVertical: "║",
+
+  // Rounded
+  rTopLeft: "╭",
+  rTopRight: "╮",
+  rBottomLeft: "╰",
+  rBottomRight: "╯",
+} as const;
+
+/**
+ * Create a horizontal line
+ */
+export function hline(width: number, char = BOX.horizontal): string {
+  return char.repeat(width);
+}
+
+/**
+ * Create a box around text
+ */
+export function box(content: string, options: {
+  padding?: number;
+  borderColor?: ColorName;
+  title?: string;
+  rounded?: boolean;
+} = {}): string {
+  const { padding = 1, borderColor = "cyan", title, rounded = true } = options;
+
+  const lines = content.split("\n");
+  const maxLen = Math.max(...lines.map(l => stripAnsi(l).length), title ? title.length + 2 : 0);
+  const innerWidth = maxLen + padding * 2;
+
+  const tl = rounded ? BOX.rTopLeft : BOX.topLeft;
+  const tr = rounded ? BOX.rTopRight : BOX.topRight;
+  const bl = rounded ? BOX.rBottomLeft : BOX.bottomLeft;
+  const br = rounded ? BOX.rBottomRight : BOX.bottomRight;
+  const h = BOX.horizontal;
+  const v = BOX.vertical;
+
+  const applyBorder = (s: string) => color(s, borderColor);
+
+  // Top border with optional title
+  let top: string;
+  if (title) {
+    const titlePart = ` ${title} `;
+    const remaining = innerWidth - titlePart.length;
+    const leftPad = Math.floor(remaining / 2);
+    const rightPad = remaining - leftPad;
+    top = applyBorder(tl + h.repeat(leftPad)) + c.bold(titlePart) + applyBorder(h.repeat(rightPad) + tr);
+  } else {
+    top = applyBorder(tl + h.repeat(innerWidth) + tr);
+  }
+
+  // Padding lines
+  const padLine = applyBorder(v) + " ".repeat(innerWidth) + applyBorder(v);
+  const paddingLines = Array(padding).fill(padLine);
+
+  // Content lines
+  const contentLines = lines.map(line => {
+    const stripped = stripAnsi(line);
+    const padRight = innerWidth - stripped.length - padding;
+    return applyBorder(v) + " ".repeat(padding) + line + " ".repeat(Math.max(0, padRight)) + applyBorder(v);
+  });
+
+  // Bottom border
+  const bottom = applyBorder(bl + h.repeat(innerWidth) + br);
+
+  return [top, ...paddingLines, ...contentLines, ...paddingLines, bottom].join("\n");
+}
+
+/**
+ * Strip ANSI codes from string (for length calculation)
+ */
+export function stripAnsi(str: string): string {
+  return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+/**
+ * Check if a character is a wide character (CJK, emoji, etc.)
+ * Wide characters take 2 columns in terminal
+ */
+function isWideChar(char: string): boolean {
+  const code = char.codePointAt(0) ?? 0;
+
+  // CJK ranges
+  if (
+    (code >= 0x1100 && code <= 0x115F) ||  // Hangul Jamo
+    (code >= 0x2E80 && code <= 0x9FFF) ||  // CJK
+    (code >= 0xAC00 && code <= 0xD7AF) ||  // Hangul Syllables
+    (code >= 0xF900 && code <= 0xFAFF) ||  // CJK Compatibility
+    (code >= 0xFE10 && code <= 0xFE1F) ||  // Vertical forms
+    (code >= 0xFE30 && code <= 0xFE6F) ||  // CJK Compatibility Forms
+    (code >= 0xFF00 && code <= 0xFF60) ||  // Fullwidth Forms
+    (code >= 0xFFE0 && code <= 0xFFE6) ||  // Fullwidth Signs
+    (code >= 0x20000 && code <= 0x2FFFF)   // CJK Extension B+
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Get display width of a string (CJK = 2, ASCII = 1)
+ */
+export function displayWidth(str: string): number {
+  const stripped = stripAnsi(str);
+  let width = 0;
+  for (const char of stripped) {
+    width += isWideChar(char) ? 2 : 1;
+  }
+  return width;
+}
+
+/**
+ * Pad string to width (accounting for ANSI codes and wide characters)
+ */
+export function pad(str: string, width: number, align: "left" | "right" | "center" = "left"): string {
+  const len = displayWidth(str);
+  const diff = width - len;
+  if (diff <= 0) return str;
+
+  switch (align) {
+    case "right":
+      return " ".repeat(diff) + str;
+    case "center":
+      const left = Math.floor(diff / 2);
+      return " ".repeat(left) + str + " ".repeat(diff - left);
+    default:
+      return str + " ".repeat(diff);
+  }
+}
+
+/**
+ * Truncate string to max display width
+ */
+export function truncate(str: string, maxLen: number, suffix = "..."): string {
+  const stripped = stripAnsi(str);
+  if (displayWidth(stripped) <= maxLen) return str;
+
+  // Truncate by display width
+  const suffixWidth = displayWidth(suffix);
+  let width = 0;
+  let result = "";
+
+  for (const char of stripped) {
+    const charWidth = isWideChar(char) ? 2 : 1;
+    if (width + charWidth > maxLen - suffixWidth) break;
+    result += char;
+    width += charWidth;
+  }
+
+  return result + suffix;
+}
+
+/**
+ * Create a simple table
+ */
+export interface TableColumn {
+  header: string;
+  key: string;
+  width?: number;
+  align?: "left" | "right" | "center";
+  format?: (value: unknown) => string;
+}
+
+export function table<T extends Record<string, unknown>>(
+  data: T[],
+  columns: TableColumn[],
+  options: {
+    headerColor?: ColorName;
+    borderColor?: ColorName;
+  } = {}
+): string {
+  const { headerColor = "cyan", borderColor = "gray" } = options;
+
+  // Calculate column widths using display width
+  const widths = columns.map(col => {
+    const headerWidth = displayWidth(col.header);
+    const maxDataWidth = Math.max(
+      ...data.map(row => {
+        const val = col.format ? col.format(row[col.key]) : String(row[col.key] ?? "");
+        return displayWidth(val);
+      }),
+      0
+    );
+    return col.width ?? Math.max(headerWidth, maxDataWidth);
+  });
+
+  const border = color(BOX.vertical, borderColor);
+  const hBorder = color(BOX.horizontal, borderColor);
+
+  // Header
+  const headerRow = columns
+    .map((col, i) => color(pad(col.header, widths[i], col.align), headerColor))
+    .join(` ${border} `);
+
+  // Separator
+  const separator = widths.map(w => hBorder.repeat(w)).join(color(`─${BOX.cross}─`, borderColor));
+
+  // Data rows
+  const dataRows = data.map(row =>
+    columns
+      .map((col, i) => {
+        const val = col.format ? col.format(row[col.key]) : String(row[col.key] ?? "");
+        return pad(truncate(val, widths[i]), widths[i], col.align);
+      })
+      .join(` ${border} `)
+  );
+
+  return [headerRow, separator, ...dataRows].join("\n");
+}
+
+/**
+ * Create a progress bar
+ */
+export function progressBar(
+  current: number,
+  total: number,
+  options: {
+    width?: number;
+    filled?: string;
+    empty?: string;
+    showPercent?: boolean;
+    filledColor?: ColorName;
+    emptyColor?: ColorName;
+  } = {}
+): string {
+  const {
+    width = 20,
+    filled = "█",
+    empty = "░",
+    showPercent = true,
+    filledColor = "green",
+    emptyColor = "gray",
+  } = options;
+
+  const percent = total > 0 ? Math.round((current / total) * 100) : 0;
+  const filledCount = Math.round((percent / 100) * width);
+  const emptyCount = width - filledCount;
+
+  const bar = color(filled.repeat(filledCount), filledColor) + color(empty.repeat(emptyCount), emptyColor);
+
+  return showPercent ? `${bar} ${percent}%` : bar;
+}
+
+/**
+ * Status icons
+ */
+export const icons = {
+  // Status
+  pending: c.yellow("○"),
+  in_progress: c.blue("◐"),
+  completed: c.green("✓"),
+  blocked: c.red("✗"),
+  cancelled: c.gray("⊘"),
+
+  // Priority
+  critical: c.red("!!!"),
+  high: c.yellow("!!"),
+  medium: c.blue("!"),
+  low: c.gray("·"),
+
+  // Misc
+  arrow: c.cyan("→"),
+  bullet: c.gray("•"),
+  check: c.green("✓"),
+  cross: c.red("✗"),
+  warning: c.yellow("⚠"),
+  info: c.cyan("ℹ"),
+};
+
+/**
+ * ASCII art text (simple implementation)
+ */
+export function banner(text: string): string {
+  // Simple block letters for "TASK MCP"
+  const letters: Record<string, string[]> = {
+    T: ["████", " ██ ", " ██ ", " ██ ", " ██ "],
+    A: [" ██ ", "████", "██ █", "████", "██ █"],
+    S: ["████", "██  ", "████", "  ██", "████"],
+    K: ["██ █", "███ ", "██  ", "███ ", "██ █"],
+    M: ["█   █", "██ ██", "█ █ █", "█   █", "█   █"],
+    C: ["████", "██  ", "██  ", "██  ", "████"],
+    P: ["████", "██ █", "████", "██  ", "██  "],
+    " ": ["  ", "  ", "  ", "  ", "  "],
+  };
+
+  const chars = text.toUpperCase().split("");
+  const lines: string[] = ["", "", "", "", ""];
+
+  for (const char of chars) {
+    const letterLines = letters[char] ?? letters[" "];
+    for (let i = 0; i < 5; i++) {
+      lines[i] += (letterLines[i] ?? "") + " ";
+    }
+  }
+
+  return lines.map(l => c.cyan(l)).join("\n");
+}
+
+/**
+ * Clear screen
+ */
+export function clearScreen(): void {
+  process.stdout.write("\x1b[2J\x1b[H");
+}
+
+/**
+ * Move cursor
+ */
+export function moveCursor(row: number, col: number): void {
+  process.stdout.write(`\x1b[${row};${col}H`);
+}

package/src/commands/dashboard.ts

@@ -0,0 +1,142 @@
+/**
+ * Dashboard command - displays project overview like Taskmaster
+ */
+
+import {
+  c,
+  box,
+  progressBar,
+  table,
+  icons,
+  banner,
+  hline,
+  pad,
+  type TableColumn,
+} from "../ansi.js";
+import {
+  listProjects,
+  listTasks,
+  listAllTasks,
+  calculateStats,
+  calculateDependencyMetrics,
+  suggestNextTask,
+  type Task,
+  type Project,
+} from "../storage.js";
+
+function formatStatus(status: Task["status"]): string {
+  const icon = icons[status] ?? icons.pending;
+  return `${icon} ${status}`;
+}
+
+function formatPriority(priority: Task["priority"]): string {
+  const colors: Record<string, (s: string) => string> = {
+    critical: c.red,
+    high: c.yellow,
+    medium: c.blue,
+    low: c.gray,
+  };
+  return (colors[priority] ?? c.gray)(priority);
+}
+
+function formatDependencies(deps: Task["dependencies"]): string {
+  if (!deps || deps.length === 0) return c.gray("None");
+  return c.cyan(deps.map(d => d.taskId.slice(0, 4)).join(", "));
+}
+
+export async function dashboard(projectId?: string): Promise<void> {
+  // Print banner
+  console.log();
+  console.log(banner("TASK MCP"));
+  console.log();
+
+  // Get projects and tasks
+  const projects = await listProjects();
+
+  if (projects.length === 0) {
+    console.log(c.yellow("No projects found. Create a project first using the MCP server."));
+    return;
+  }
+
+  // If projectId specified, show single project. Otherwise show all.
+  let project: Project | undefined;
+  let tasks: Task[];
+
+  if (projectId) {
+    project = projects.find(p => p.id === projectId || p.id.startsWith(projectId));
+    if (!project) {
+      console.log(c.error(`Project not found: ${projectId}`));
+      return;
+    }
+    tasks = await listTasks(project.id);
+  } else if (projects.length === 1) {
+    project = projects[0];
+    tasks = await listTasks(project!.id);
+  } else {
+    // Show all tasks across all projects
+    tasks = await listAllTasks();
+  }
+
+  // Project info
+  const projectInfo = project
+    ? `${c.bold("Project:")} ${project.name}`
+    : `${c.bold("All Projects")} (${projects.length} projects)`;
+
+  console.log(c.dim(`Version: 1.0.4  ${projectInfo}`));
+  console.log();
+
+  // Calculate stats
+  const stats = calculateStats(tasks);
+  const depMetrics = calculateDependencyMetrics(tasks);
+  const nextTask = suggestNextTask(tasks);
+
+  // Left panel: Project Dashboard
+  const dashboardContent = `${c.bold("Project Dashboard")}
+Tasks Progress: ${progressBar(stats.completed, stats.total - stats.cancelled, { width: 30 })}
+${c.green(`Done: ${stats.completed}`)}  ${c.blue(`In Progress: ${stats.inProgress}`)}  ${c.yellow(`Pending: ${stats.pending}`)}  ${c.red(`Blocked: ${stats.blocked}`)}
+${stats.cancelled > 0 ? c.gray(`Cancelled: ${stats.cancelled}`) : ""}
+
+${c.bold("Priority Breakdown")}
+${c.red("•")} Critical: ${stats.byPriority.critical}
+${c.yellow("•")} High: ${stats.byPriority.high}
+${c.blue("•")} Medium: ${stats.byPriority.medium}
+${c.gray("•")} Low: ${stats.byPriority.low}`;
+
+  // Right panel: Dependency Status
+  const depContent = `${c.bold("Dependency Status & Next Task")}
+${c.cyan("Dependency Metrics:")}
+• Tasks with no dependencies: ${depMetrics.noDependencies}
+• Tasks ready to work on: ${c.green(String(depMetrics.readyToWork))}
+• Tasks blocked by dependencies: ${depMetrics.blockedByDependencies}
+${depMetrics.mostDependedOn ? `• Most depended-on task: ${c.cyan(`#${depMetrics.mostDependedOn.id.slice(0, 4)}`)} (${depMetrics.mostDependedOn.count} dependents)` : ""}
+• Avg dependencies per task: ${depMetrics.avgDependencies}
+
+${c.yellow("Next Task to Work On:")}
+${nextTask
+    ? `ID: ${c.cyan(nextTask.id.slice(0, 4))} - ${c.bold(nextTask.title)}
+Priority: ${formatPriority(nextTask.priority)}  Dependencies: ${formatDependencies(nextTask.dependencies)}`
+    : c.gray("No actionable tasks available")}`;
+
+  // Print boxes side by side (simplified: stacked for now)
+  console.log(box(dashboardContent, { title: "Dashboard", borderColor: "cyan" }));
+  console.log();
+  console.log(box(depContent, { title: "Dependencies", borderColor: "yellow" }));
+  console.log();
+
+  // Task table
+  if (tasks.length > 0) {
+    const columns: TableColumn[] = [
+      { header: "ID", key: "id", width: 6, format: (v) => c.cyan(String(v).slice(0, 4)) },
+      { header: "Title", key: "title", width: 50 },
+      { header: "Status", key: "status", width: 14, format: (v) => formatStatus(v as Task["status"]) },
+      { header: "Priority", key: "priority", width: 10, format: (v) => formatPriority(v as Task["priority"]) },
+      { header: "Dependencies", key: "dependencies", width: 16, format: (v) => formatDependencies(v as Task["dependencies"]) },
+    ];
+
+    console.log(table(tasks, columns));
+  } else {
+    console.log(c.gray("No tasks found."));
+  }
+
+  console.log();
+}

package/src/commands/list.ts

@@ -0,0 +1,128 @@
+/**
+ * List commands - list tasks and projects
+ */
+
+import { c, table, icons, type TableColumn } from "../ansi.js";
+import {
+  listProjects,
+  listTasks,
+  listAllTasks,
+  type Task,
+  type Project,
+} from "../storage.js";
+
+function formatStatus(status: Task["status"]): string {
+  const icon = icons[status] ?? icons.pending;
+  return `${icon} ${status}`;
+}
+
+function formatPriority(priority: Task["priority"]): string {
+  const colors: Record<string, (s: string) => string> = {
+    critical: c.red,
+    high: c.yellow,
+    medium: c.blue,
+    low: c.gray,
+  };
+  return (colors[priority] ?? c.gray)(priority);
+}
+
+function formatProjectStatus(status: Project["status"]): string {
+  const statusMap: Record<string, string> = {
+    active: c.green("● active"),
+    on_hold: c.yellow("◐ on_hold"),
+    completed: c.blue("✓ completed"),
+    archived: c.gray("⊘ archived"),
+  };
+  return statusMap[status] ?? status;
+}
+
+function formatDate(dateStr?: string): string {
+  if (!dateStr) return c.gray("-");
+  const date = new Date(dateStr);
+  return date.toLocaleDateString();
+}
+
+export async function listTasksCmd(options: {
+  projectId?: string;
+  status?: string;
+  priority?: string;
+  all?: boolean;
+}): Promise<void> {
+  let tasks: Task[];
+
+  if (options.projectId) {
+    tasks = await listTasks(options.projectId);
+  } else {
+    tasks = await listAllTasks();
+  }
+
+  // Apply filters
+  if (options.status) {
+    const statuses = options.status.split(",");
+    tasks = tasks.filter(t => statuses.includes(t.status));
+  } else if (!options.all) {
+    // By default, hide completed/cancelled
+    tasks = tasks.filter(t => t.status !== "completed" && t.status !== "cancelled");
+  }
+
+  if (options.priority) {
+    const priorities = options.priority.split(",");
+    tasks = tasks.filter(t => priorities.includes(t.priority));
+  }
+
+  if (tasks.length === 0) {
+    console.log(c.gray("No tasks found."));
+    return;
+  }
+
+  console.log(c.bold(`\nTasks (${tasks.length})\n`));
+
+  const columns: TableColumn[] = [
+    { header: "ID", key: "id", width: 6, format: (v) => c.cyan(String(v).slice(0, 4)) },
+    { header: "Title", key: "title", width: 45 },
+    { header: "Status", key: "status", width: 14, format: (v) => formatStatus(v as Task["status"]) },
+    { header: "Priority", key: "priority", width: 10, format: (v) => formatPriority(v as Task["priority"]) },
+    { header: "Due", key: "dueDate", width: 12, format: (v) => formatDate(v as string) },
+  ];
+
+  console.log(table(tasks, columns));
+  console.log();
+}
+
+export async function listProjectsCmd(options: {
+  all?: boolean;
+}): Promise<void> {
+  const projects = await listProjects(options.all);
+
+  if (projects.length === 0) {
+    console.log(c.gray("No projects found."));
+    return;
+  }
+
+  console.log(c.bold(`\nProjects (${projects.length})\n`));
+
+  // Get task counts for each project
+  const projectsWithStats = await Promise.all(
+    projects.map(async p => {
+      const tasks = await listTasks(p.id);
+      const completed = tasks.filter(t => t.status === "completed").length;
+      const total = tasks.filter(t => t.status !== "cancelled").length;
+      return {
+        ...p,
+        taskCount: tasks.length,
+        progress: total > 0 ? `${completed}/${total}` : "0/0",
+      };
+    })
+  );
+
+  const columns: TableColumn[] = [
+    { header: "ID", key: "id", width: 6, format: (v) => c.cyan(String(v).slice(0, 4)) },
+    { header: "Name", key: "name", width: 30 },
+    { header: "Status", key: "status", width: 14, format: (v) => formatProjectStatus(v as Project["status"]) },
+    { header: "Tasks", key: "progress", width: 10 },
+    { header: "Updated", key: "updatedAt", width: 12, format: (v) => formatDate(v as string) },
+  ];
+
+  console.log(table(projectsWithStats, columns));
+  console.log();
+}

package/src/index.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env bun
+/**
+ * Task MCP CLI - Zero-dependency terminal visualization
+ *
+ * Usage:
+ *   task                    # Show dashboard (default)
+ *   task dashboard [id]     # Show project dashboard
+ *   task d [id]             # Alias for dashboard
+ *   task list               # List tasks
+ *   task ls                 # Alias for list
+ *   task projects           # List projects
+ *   task p                  # Alias for projects
+ *   task help               # Show help
+ */
+
+import { c, banner } from "./ansi.js";
+import { dashboard } from "./commands/dashboard.js";
+import { listTasksCmd, listProjectsCmd } from "./commands/list.js";
+
+const VERSION = "1.0.4";
+
+interface ParsedArgs {
+  command: string;
+  args: string[];
+  flags: Record<string, string | boolean>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const args = argv.slice(2); // Skip bun and script path
+  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, value] = arg.slice(2).split("=");
+      if (value !== undefined) {
+        flags[key!] = value;
+      } else if (args[i + 1] && !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 (args[i + 1] && !args[i + 1]!.startsWith("-")) {
+        flags[key] = args[++i]!;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return {
+    command: positional[0] ?? "dashboard",
+    args: positional.slice(1),
+    flags,
+  };
+}
+
+function showHelp(): void {
+  console.log(`
+${c.cyan(c.bold("Task MCP CLI"))} ${c.gray(`v${VERSION}`)}
+${c.dim("Zero-dependency terminal visualization for task-mcp")}
+
+${c.yellow("USAGE")}
+  ${c.bold("task")} [command] [options]
+
+${c.yellow("COMMANDS")}
+  ${c.cyan("dashboard")} [project-id]   Show project dashboard (default)
+  ${c.cyan("d")} [project-id]           Alias for dashboard
+  ${c.cyan("list")}                     List all tasks
+  ${c.cyan("ls")}                       Alias for list
+  ${c.cyan("projects")}                 List all projects
+  ${c.cyan("p")}                        Alias for projects
+  ${c.cyan("help")}                     Show this help message
+  ${c.cyan("version")}                  Show version
+
+${c.yellow("OPTIONS")}
+  ${c.cyan("--status")} <status>        Filter tasks by status (pending,in_progress,blocked,completed,cancelled)
+  ${c.cyan("--priority")} <priority>    Filter tasks by priority (critical,high,medium,low)
+  ${c.cyan("--all")}                    Include completed/cancelled tasks
+
+${c.yellow("EXAMPLES")}
+  ${c.dim("# Show dashboard for all projects")}
+  task
+
+  ${c.dim("# Show dashboard for a specific project")}
+  task dashboard proj_abc123
+
+  ${c.dim("# List pending high-priority tasks")}
+  task list --status pending --priority high
+
+  ${c.dim("# List all projects including archived")}
+  task projects --all
+`);
+}
+
+function showVersion(): void {
+  console.log(`task-mcp-cli v${VERSION}`);
+}
+
+async function main(): Promise<void> {
+  const { command, args, flags } = parseArgs(process.argv);
+
+  try {
+    switch (command) {
+      case "dashboard":
+      case "d":
+        await dashboard(args[0]);
+        break;
+
+      case "list":
+      case "ls":
+        await listTasksCmd({
+          projectId: args[0],
+          status: flags.status as string | undefined,
+          priority: flags.priority as string | undefined,
+          all: flags.all === true,
+        });
+        break;
+
+      case "projects":
+      case "p":
+        await listProjectsCmd({
+          all: flags.all === true,
+        });
+        break;
+
+      case "help":
+      case "-h":
+      case "--help":
+        showHelp();
+        break;
+
+      case "version":
+      case "-v":
+      case "--version":
+        showVersion();
+        break;
+
+      default:
+        console.log(c.error(`Unknown command: ${command}`));
+        console.log(c.dim("Run 'task help' for usage information."));
+        process.exit(1);
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(c.error(`Error: ${error.message}`));
+    } else {
+      console.error(c.error("An unexpected error occurred"));
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/src/storage.ts

@@ -0,0 +1,267 @@
+/**
+ * Simple file-based storage reader for CLI
+ * Reads directly from .tasks/ directory
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface Task {
+  id: string;
+  title: string;
+  description?: string;
+  status: "pending" | "in_progress" | "blocked" | "completed" | "cancelled";
+  priority: "critical" | "high" | "medium" | "low";
+  projectId: string;
+  dependencies?: { taskId: string; type: string; reason?: string }[];
+  dueDate?: string;
+  createdAt: string;
+  updatedAt: string;
+  completedAt?: string;
+  contexts?: string[];
+  tags?: string[];
+}
+
+export interface Project {
+  id: string;
+  name: string;
+  description?: string;
+  status: "active" | "on_hold" | "completed" | "archived";
+  defaultPriority?: string;
+  createdAt: string;
+  updatedAt: string;
+  targetDate?: string;
+}
+
+export interface TasksFile {
+  version: number;
+  tasks: Task[];
+}
+
+function getTasksDir(): string {
+  return join(process.cwd(), ".tasks");
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await readFile(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJson<T>(path: string): Promise<T | null> {
+  try {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content) as T;
+  } catch {
+    return null;
+  }
+}
+
+async function listDirs(path: string): Promise<string[]> {
+  try {
+    const entries = await readdir(path, { withFileTypes: true });
+    return entries.filter(e => e.isDirectory()).map(e => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * List all projects
+ */
+export async function listProjects(includeArchived = false): Promise<Project[]> {
+  const projectsDir = join(getTasksDir(), "projects");
+  const projectIds = await listDirs(projectsDir);
+
+  const projects: Project[] = [];
+  for (const id of projectIds) {
+    const project = await readJson<Project>(join(projectsDir, id, "project.json"));
+    if (project) {
+      if (includeArchived || project.status !== "archived") {
+        projects.push(project);
+      }
+    }
+  }
+
+  return projects.sort(
+    (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+  );
+}
+
+/**
+ * Get a project by ID
+ */
+export async function getProject(projectId: string): Promise<Project | null> {
+  const path = join(getTasksDir(), "projects", projectId, "project.json");
+  return readJson<Project>(path);
+}
+
+/**
+ * List tasks for a project
+ */
+export async function listTasks(projectId: string): Promise<Task[]> {
+  const path = join(getTasksDir(), "projects", projectId, "tasks.json");
+  const data = await readJson<TasksFile>(path);
+  return data?.tasks ?? [];
+}
+
+/**
+ * List all tasks across all projects
+ */
+export async function listAllTasks(): Promise<Task[]> {
+  const projects = await listProjects(true);
+  const allTasks: Task[] = [];
+
+  for (const project of projects) {
+    const tasks = await listTasks(project.id);
+    allTasks.push(...tasks);
+  }
+
+  return allTasks.sort(
+    (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+  );
+}
+
+/**
+ * Get project statistics
+ */
+export interface ProjectStats {
+  total: number;
+  completed: number;
+  inProgress: number;
+  pending: number;
+  blocked: number;
+  cancelled: number;
+  byPriority: Record<string, number>;
+  completionPercent: number;
+}
+
+export function calculateStats(tasks: Task[]): ProjectStats {
+  const stats: ProjectStats = {
+    total: tasks.length,
+    completed: 0,
+    inProgress: 0,
+    pending: 0,
+    blocked: 0,
+    cancelled: 0,
+    byPriority: { critical: 0, high: 0, medium: 0, low: 0 },
+    completionPercent: 0,
+  };
+
+  for (const task of tasks) {
+    switch (task.status) {
+      case "completed":
+        stats.completed++;
+        break;
+      case "in_progress":
+        stats.inProgress++;
+        break;
+      case "pending":
+        stats.pending++;
+        break;
+      case "blocked":
+        stats.blocked++;
+        break;
+      case "cancelled":
+        stats.cancelled++;
+        break;
+    }
+    stats.byPriority[task.priority]++;
+  }
+
+  const nonCancelled = stats.total - stats.cancelled;
+  stats.completionPercent = nonCancelled > 0
+    ? Math.round((stats.completed / nonCancelled) * 100)
+    : 0;
+
+  return stats;
+}
+
+/**
+ * Get dependency metrics
+ */
+export interface DependencyMetrics {
+  noDependencies: number;
+  readyToWork: number;
+  blockedByDependencies: number;
+  mostDependedOn: { id: string; title: string; count: number } | null;
+  avgDependencies: number;
+}
+
+export function calculateDependencyMetrics(tasks: Task[]): DependencyMetrics {
+  const activeTasks = tasks.filter(t => t.status !== "completed" && t.status !== "cancelled");
+  const completedIds = new Set(tasks.filter(t => t.status === "completed").map(t => t.id));
+
+  // Count how many tasks depend on each task
+  const dependentCounts: Record<string, number> = {};
+  for (const task of activeTasks) {
+    for (const dep of task.dependencies ?? []) {
+      dependentCounts[dep.taskId] = (dependentCounts[dep.taskId] ?? 0) + 1;
+    }
+  }
+
+  let mostDependedOn: DependencyMetrics["mostDependedOn"] = null;
+  let maxCount = 0;
+  for (const [id, count] of Object.entries(dependentCounts)) {
+    if (count > maxCount) {
+      maxCount = count;
+      const task = tasks.find(t => t.id === id);
+      if (task) {
+        mostDependedOn = { id, title: task.title, count };
+      }
+    }
+  }
+
+  const noDependencies = activeTasks.filter(t => (t.dependencies?.length ?? 0) === 0).length;
+
+  // Ready to work: no uncompleted dependencies
+  const readyToWork = activeTasks.filter(t => {
+    const deps = t.dependencies ?? [];
+    if (deps.length === 0) return true;
+    return deps.every(d => completedIds.has(d.taskId));
+  }).length;
+
+  const blockedByDependencies = activeTasks.length - readyToWork;
+
+  const totalDeps = activeTasks.reduce((sum, t) => sum + (t.dependencies?.length ?? 0), 0);
+  const avgDependencies = activeTasks.length > 0 ? totalDeps / activeTasks.length : 0;
+
+  return {
+    noDependencies,
+    readyToWork,
+    blockedByDependencies,
+    mostDependedOn,
+    avgDependencies: Math.round(avgDependencies * 10) / 10,
+  };
+}
+
+/**
+ * Get next task suggestion
+ */
+export function suggestNextTask(tasks: Task[]): Task | null {
+  const completedIds = new Set(tasks.filter(t => t.status === "completed").map(t => t.id));
+
+  // Filter to actionable tasks
+  const actionable = tasks.filter(t => {
+    if (t.status !== "pending" && t.status !== "in_progress") return false;
+
+    // Check if all dependencies are completed
+    const deps = t.dependencies ?? [];
+    return deps.every(d => completedIds.has(d.taskId));
+  });
+
+  if (actionable.length === 0) return null;
+
+  // Sort by priority then by creation date
+  const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+  actionable.sort((a, b) => {
+    const pDiff = priorityOrder[a.priority] - priorityOrder[b.priority];
+    if (pDiff !== 0) return pDiff;
+    return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+  });
+
+  return actionable[0] ?? null;
+}