@nijaru/tk 0.0.1

package/src/lib/format.test.ts

@@ -0,0 +1,347 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import {
+  shouldUseColor,
+  formatTaskRow,
+  formatTaskList,
+  formatTaskDetail,
+  formatJson,
+} from "./format";
+import type { Task, TaskWithMeta, LogEntry } from "../types";
+
+describe("shouldUseColor", () => {
+  const originalEnv = process.env.NO_COLOR;
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.NO_COLOR;
+    } else {
+      process.env.NO_COLOR = originalEnv;
+    }
+  });
+
+  test("returns false when NO_COLOR is set (non-empty)", () => {
+    process.env.NO_COLOR = "1";
+    expect(shouldUseColor()).toBe(false);
+  });
+
+  test("returns false when NO_COLOR is set to any value", () => {
+    process.env.NO_COLOR = "true";
+    expect(shouldUseColor()).toBe(false);
+    process.env.NO_COLOR = "yes";
+    expect(shouldUseColor()).toBe(false);
+  });
+
+  test("respects NO_COLOR empty string as color enabled", () => {
+    process.env.NO_COLOR = "";
+    // When NO_COLOR is empty, color is allowed (depends on TTY)
+  });
+});
+
+describe("formatTaskRow", () => {
+  const task: Task & { id: string } = {
+    id: "tk-a1b2",
+    project: "tk",
+    ref: "a1b2",
+    title: "Test task",
+    description: null,
+    priority: 1,
+    status: "open",
+    labels: [],
+    assignees: [],
+    parent: null,
+    blocked_by: [],
+    estimate: null,
+    due_date: null,
+    logs: [],
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    completed_at: null,
+    external: {},
+  };
+
+  test("formats task without color", () => {
+    const result = formatTaskRow(task, false);
+    expect(result).toContain("tk-a1b2");
+    expect(result).toContain("p1");
+    expect(result).toContain("open");
+    expect(result).toContain("Test task");
+    expect(result).not.toContain("\x1b[");
+  });
+
+  test("formats task with color", () => {
+    const result = formatTaskRow(task, true);
+    expect(result).toContain("tk-a1b2");
+    expect(result).toContain("\x1b[");
+  });
+
+  test("truncates long titles to 50 chars", () => {
+    const longTask: Task & { id: string } = {
+      ...task,
+      title: "A".repeat(100),
+    };
+    const result = formatTaskRow(longTask, false);
+    expect(result.split("A").length - 1).toBeLessThanOrEqual(50);
+  });
+
+  test("includes column dividers", () => {
+    const result = formatTaskRow(task, false);
+    expect(result).toContain(" | ");
+    const parts = result.split(" | ");
+    expect(parts.length).toBe(4); // ID | PRIO | STATUS | TITLE
+  });
+
+  test("truncates long project names to 6 chars", () => {
+    const longProjectTask: Task & { id: string } = {
+      ...task,
+      id: "mylongproject-a1b2",
+    };
+    const result = formatTaskRow(longProjectTask, false);
+    expect(result).toContain("mylong-a1b2");
+    expect(result).not.toContain("mylongproject");
+  });
+
+  test("keeps short project names intact", () => {
+    const result = formatTaskRow(task, false);
+    expect(result).toContain("tk-a1b2");
+  });
+
+  test("shows overdue marker for overdue tasks", () => {
+    const overdueTask: Task & { id: string } = {
+      ...task,
+      due_date: "2020-01-01",
+    };
+    const result = formatTaskRow(overdueTask, false);
+    expect(result).toContain("[OVERDUE]");
+  });
+
+  test("does NOT show overdue marker for tasks due today", () => {
+    const today = new Date().toISOString().split("T")[0] ?? null;
+    const todayTask: Task & { id: string } = {
+      ...task,
+      due_date: today,
+    };
+    const result = formatTaskRow(todayTask, false);
+    expect(result).not.toContain("[OVERDUE]");
+  });
+});
+
+describe("formatTaskList", () => {
+  test("returns message for empty list", () => {
+    expect(formatTaskList([])).toBe("No tasks found.");
+  });
+
+  test("includes header and divider", () => {
+    const tasks: (Task & { id: string })[] = [
+      {
+        id: "tk-a1b2",
+        project: "tk",
+        ref: "a1b2",
+        title: "Test",
+        description: null,
+        priority: 3,
+        status: "open",
+        labels: [],
+        assignees: [],
+        parent: null,
+        blocked_by: [],
+        estimate: null,
+        due_date: null,
+        logs: [],
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        completed_at: null,
+        external: {},
+      },
+    ];
+    const result = formatTaskList(tasks, false);
+    expect(result).toContain("ID");
+    expect(result).toContain("PRI");
+    expect(result).toContain("STATUS");
+    expect(result).toContain("TITLE");
+    expect(result).toContain("----");
+  });
+
+  test("formats multiple tasks", () => {
+    const tasks: (Task & { id: string })[] = [
+      {
+        id: "tk-a1b2",
+        project: "tk",
+        ref: "a1b2",
+        title: "First",
+        description: null,
+        priority: 1,
+        status: "open",
+        labels: [],
+        assignees: [],
+        parent: null,
+        blocked_by: [],
+        estimate: null,
+        due_date: null,
+        logs: [],
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        completed_at: null,
+        external: {},
+      },
+      {
+        id: "tk-c3d4",
+        project: "tk",
+        ref: "c3d4",
+        title: "Second",
+        description: null,
+        priority: 3,
+        status: "active",
+        labels: [],
+        assignees: [],
+        parent: null,
+        blocked_by: [],
+        estimate: null,
+        due_date: null,
+        logs: [],
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+        completed_at: null,
+        external: {},
+      },
+    ];
+    const result = formatTaskList(tasks, false);
+    expect(result).toContain("tk-a1b2");
+    expect(result).toContain("tk-c3d4");
+    expect(result).toContain("First");
+    expect(result).toContain("Second");
+  });
+});
+
+describe("formatTaskDetail", () => {
+  const task: TaskWithMeta = {
+    id: "tk-a1b2",
+    project: "tk",
+    ref: "a1b2",
+    title: "Test task",
+    description: "A description",
+    priority: 1,
+    status: "open",
+    labels: ["bug", "urgent"],
+    assignees: ["nick"],
+    parent: null,
+    blocked_by: ["tk-c3d4"],
+    estimate: 3,
+    due_date: "2026-01-15",
+    logs: [],
+    created_at: "2024-01-01T00:00:00.000Z",
+    updated_at: "2024-01-01T00:00:00.000Z",
+    completed_at: null,
+    external: {},
+    blocked_by_incomplete: true,
+    is_overdue: false,
+  };
+
+  test("includes all task fields", () => {
+    const result = formatTaskDetail(task, [], false);
+    expect(result).toContain("ID:");
+    expect(result).toContain("tk-a1b2");
+    expect(result).toContain("Title:");
+    expect(result).toContain("Test task");
+    expect(result).toContain("Status:");
+    expect(result).toContain("open");
+    expect(result).toContain("Priority:");
+    expect(result).toContain("p1");
+    expect(result).toContain("Description:");
+    expect(result).toContain("A description");
+  });
+
+  test("shows labels", () => {
+    const result = formatTaskDetail(task, [], false);
+    expect(result).toContain("Labels:");
+    expect(result).toContain("bug, urgent");
+  });
+
+  test("shows assignees", () => {
+    const result = formatTaskDetail(task, [], false);
+    expect(result).toContain("Assignees:");
+    expect(result).toContain("nick");
+  });
+
+  test("shows estimate", () => {
+    const result = formatTaskDetail(task, [], false);
+    expect(result).toContain("Estimate:");
+    expect(result).toContain("3");
+  });
+
+  test("shows due date", () => {
+    const result = formatTaskDetail(task, [], false);
+    expect(result).toContain("Due:");
+    expect(result).toContain("2026-01-15");
+  });
+
+  test("shows blockers with status", () => {
+    const result = formatTaskDetail(task, [], false);
+    expect(result).toContain("Blockers:");
+    expect(result).toContain("tk-c3d4");
+    expect(result).toContain("(blocked)");
+  });
+
+  test("shows resolved blockers", () => {
+    const resolvedTask: TaskWithMeta = {
+      ...task,
+      blocked_by_incomplete: false,
+    };
+    const result = formatTaskDetail(resolvedTask, [], false);
+    expect(result).toContain("(resolved)");
+  });
+
+  test("shows overdue indicator", () => {
+    const overdueTask: TaskWithMeta = {
+      ...task,
+      is_overdue: true,
+    };
+    const result = formatTaskDetail(overdueTask, [], false);
+    expect(result).toContain("[OVERDUE]");
+  });
+
+  test("includes log entries", () => {
+    const logs: LogEntry[] = [
+      { ts: "2024-01-01T00:00:00.000Z", msg: "Started work" },
+      { ts: "2024-01-02T00:00:00.000Z", msg: "Made progress" },
+    ];
+    const result = formatTaskDetail(task, logs, false);
+    expect(result).toContain("Log:");
+    expect(result).toContain("Started work");
+    expect(result).toContain("Made progress");
+  });
+
+  test("shows completed_at for done tasks", () => {
+    const doneTask: TaskWithMeta = {
+      ...task,
+      status: "done",
+      completed_at: "2024-01-02T00:00:00.000Z",
+    };
+    const result = formatTaskDetail(doneTask, [], false);
+    expect(result).toContain("Completed:");
+  });
+});
+
+describe("formatJson", () => {
+  test("formats objects as pretty JSON", () => {
+    const data = { foo: "bar", num: 42 };
+    const result = formatJson(data);
+    expect(result).toBe('{\n  "foo": "bar",\n  "num": 42\n}');
+  });
+
+  test("formats arrays", () => {
+    const data = [1, 2, 3];
+    const result = formatJson(data);
+    expect(result).toBe("[\n  1,\n  2,\n  3\n]");
+  });
+
+  test("handles null", () => {
+    expect(formatJson(null)).toBe("null");
+  });
+
+  test("handles nested objects", () => {
+    const data = { nested: { value: true } };
+    const result = formatJson(data);
+    expect(result).toContain('"nested"');
+    expect(result).toContain('"value"');
+  });
+});

package/src/lib/format.ts

@@ -0,0 +1,162 @@
+import type { Task, TaskWithMeta, LogEntry } from "../types";
+import { PRIORITY_COLORS, STATUS_COLORS, OVERDUE_COLOR, RESET } from "../types";
+import { formatPriority } from "./priority";
+
+/**
+ * Determines if color output should be used.
+ * Respects NO_COLOR env var (https://no-color.org/) and TTY detection.
+ */
+export function shouldUseColor(): boolean {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "") {
+    return false;
+  }
+  if (!process.stdout.isTTY) {
+    return false;
+  }
+  return true;
+}
+
+function formatId(id: string): string {
+  // Truncate project prefix to 6 chars, keep full 4-char ref
+  // "myproject-a1b2" -> "myproj-a1b2"
+  const dash = id.lastIndexOf("-");
+  if (dash === -1) return id.slice(0, 11);
+  const project = id.slice(0, dash);
+  const ref = id.slice(dash + 1);
+  const truncatedProject = project.length > 6 ? project.slice(0, 6) : project;
+  return `${truncatedProject}-${ref}`;
+}
+
+export function formatTaskRow(task: Task & { id: string }, useColor?: boolean): string {
+  const color = useColor ?? shouldUseColor();
+  const id = formatId(task.id).padEnd(11);
+  const priority = formatPriority(task.priority).padEnd(4);
+  const status = task.status.padEnd(7);
+  const title = task.title.slice(0, 50);
+
+  // Check if overdue (due date is before today, not including today)
+  let isOverdue = false;
+  if (task.due_date && task.status !== "done") {
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    // Parse YYYY-MM-DD as local date (not UTC)
+    const parts = task.due_date.split("-").map(Number);
+    const year = parts[0];
+    const month = parts[1];
+    const day = parts[2];
+    if (year && month && day) {
+      const dueDate = new Date(year, month - 1, day);
+      isOverdue = dueDate < today;
+    }
+  }
+
+  if (color) {
+    const pc = PRIORITY_COLORS[task.priority];
+    const sc = isOverdue ? OVERDUE_COLOR : STATUS_COLORS[task.status];
+    return `${id} | ${pc}${priority}${RESET} | ${sc}${status}${RESET} | ${title}`;
+  }
+
+  const overdueMarker = isOverdue ? " [OVERDUE]" : "";
+  return `${id} | ${priority} | ${status} | ${title}${overdueMarker}`;
+}
+
+export function formatTaskList(tasks: (Task & { id: string })[], useColor?: boolean): string {
+  if (tasks.length === 0) return "No tasks found.";
+  const color = useColor ?? shouldUseColor();
+
+  const header = "ID          | PRIO | STATUS  | TITLE";
+  const divider = "-".repeat(60);
+  const rows = tasks.map((t) => formatTaskRow(t, color));
+
+  return [header, divider, ...rows].join("\n");
+}
+
+export function formatTaskDetail(task: TaskWithMeta, logs: LogEntry[], useColor?: boolean): string {
+  const color = useColor ?? shouldUseColor();
+  const lines: string[] = [];
+
+  const sc = color ? STATUS_COLORS[task.status] : "";
+  const pc = color ? PRIORITY_COLORS[task.priority] : "";
+  const oc = color ? OVERDUE_COLOR : "";
+  const r = color ? RESET : "";
+
+  lines.push(`ID:          ${task.id}`);
+  lines.push(`Title:       ${task.title}`);
+  lines.push(`Status:      ${sc}${task.status}${r}`);
+  lines.push(`Priority:    ${pc}${formatPriority(task.priority)}${r}`);
+
+  if (task.description) {
+    lines.push(`Description: ${task.description}`);
+  }
+
+  if (task.labels.length > 0) {
+    lines.push(`Labels:      ${task.labels.join(", ")}`);
+  }
+
+  if (task.assignees.length > 0) {
+    lines.push(`Assignees:   ${task.assignees.join(", ")}`);
+  }
+
+  if (task.parent) {
+    lines.push(`Parent:      ${task.parent}`);
+  }
+
+  if (task.estimate !== null) {
+    lines.push(`Estimate:    ${task.estimate}`);
+  }
+
+  if (task.due_date) {
+    const overdueStr = task.is_overdue ? ` ${oc}[OVERDUE]${r}` : "";
+    lines.push(`Due:         ${task.due_date}${overdueStr}`);
+  }
+
+  lines.push(`Created:     ${formatDate(task.created_at)}`);
+  lines.push(`Updated:     ${formatDate(task.updated_at)}`);
+
+  if (task.completed_at) {
+    lines.push(`Completed:   ${formatDate(task.completed_at)}`);
+  }
+
+  if (task.blocked_by.length > 0) {
+    const blockStatus = task.blocked_by_incomplete ? " (blocked)" : " (resolved)";
+    lines.push(`Blockers:    ${task.blocked_by.join(", ")}${blockStatus}`);
+  }
+
+  if (logs.length > 0) {
+    lines.push("");
+    lines.push("Log:");
+    for (const entry of logs) {
+      lines.push(`  [${formatDate(entry.ts)}] ${entry.msg}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatDate(timestamp: string): string {
+  return new Date(timestamp).toLocaleString();
+}
+
+export function formatJson(data: unknown): string {
+  return JSON.stringify(data, null, 2);
+}
+
+export function formatConfig(config: {
+  version: number;
+  project: string;
+  aliases: Record<string, string>;
+}): string {
+  const lines: string[] = [];
+  lines.push(`Version:  ${config.version}`);
+  lines.push(`Project:  ${config.project}`);
+
+  if (Object.keys(config.aliases).length > 0) {
+    lines.push("");
+    lines.push("Aliases:");
+    for (const [alias, path] of Object.entries(config.aliases)) {
+      lines.push(`  ${alias} → ${path}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/lib/priority.test.ts

@@ -0,0 +1,105 @@
+import { test, expect, describe } from "bun:test";
+import { parsePriority, formatPriority, formatPriorityName } from "./priority";
+
+describe("parsePriority", () => {
+  describe("valid inputs", () => {
+    test("returns 3 (medium) for undefined", () => {
+      expect(parsePriority(undefined)).toBe(3);
+    });
+
+    test("parses numeric strings 0-4", () => {
+      expect(parsePriority("0")).toBe(0);
+      expect(parsePriority("1")).toBe(1);
+      expect(parsePriority("2")).toBe(2);
+      expect(parsePriority("3")).toBe(3);
+      expect(parsePriority("4")).toBe(4);
+    });
+
+    test("parses numbers 0-4", () => {
+      expect(parsePriority(0)).toBe(0);
+      expect(parsePriority(1)).toBe(1);
+      expect(parsePriority(2)).toBe(2);
+      expect(parsePriority(3)).toBe(3);
+      expect(parsePriority(4)).toBe(4);
+    });
+
+    test("parses p0-p4 format (lowercase)", () => {
+      expect(parsePriority("p0")).toBe(0);
+      expect(parsePriority("p1")).toBe(1);
+      expect(parsePriority("p2")).toBe(2);
+      expect(parsePriority("p3")).toBe(3);
+      expect(parsePriority("p4")).toBe(4);
+    });
+
+    test("parses P0-P4 format (uppercase)", () => {
+      expect(parsePriority("P0")).toBe(0);
+      expect(parsePriority("P1")).toBe(1);
+      expect(parsePriority("P2")).toBe(2);
+      expect(parsePriority("P3")).toBe(3);
+      expect(parsePriority("P4")).toBe(4);
+    });
+
+    test("parses named priorities", () => {
+      expect(parsePriority("none")).toBe(0);
+      expect(parsePriority("urgent")).toBe(1);
+      expect(parsePriority("high")).toBe(2);
+      expect(parsePriority("medium")).toBe(3);
+      expect(parsePriority("low")).toBe(4);
+    });
+
+    test("parses named priorities case-insensitively", () => {
+      expect(parsePriority("URGENT")).toBe(1);
+      expect(parsePriority("High")).toBe(2);
+      expect(parsePriority("MEDIUM")).toBe(3);
+    });
+  });
+
+  describe("invalid inputs", () => {
+    test("throws for out of range numbers", () => {
+      expect(() => parsePriority("5")).toThrow("Invalid priority");
+      expect(() => parsePriority("-1")).toThrow("Invalid priority");
+      expect(() => parsePriority("99")).toThrow("Invalid priority");
+    });
+
+    test("throws for out of range pX format", () => {
+      expect(() => parsePriority("p5")).toThrow("Invalid priority");
+      expect(() => parsePriority("p6")).toThrow("Invalid priority");
+      expect(() => parsePriority("p-1")).toThrow("Invalid priority");
+    });
+
+    test("throws for invalid named priorities", () => {
+      expect(() => parsePriority("critical")).toThrow("Invalid priority");
+      expect(() => parsePriority("abc")).toThrow("Invalid priority");
+    });
+
+    test("throws for empty string", () => {
+      expect(() => parsePriority("")).toThrow("Invalid priority");
+    });
+
+    test("error message includes valid formats", () => {
+      expect(() => parsePriority("invalid")).toThrow(
+        "Use 0-4, p0-p4, or none/urgent/high/medium/low",
+      );
+    });
+  });
+});
+
+describe("formatPriority", () => {
+  test("formats priorities as pX", () => {
+    expect(formatPriority(0)).toBe("p0");
+    expect(formatPriority(1)).toBe("p1");
+    expect(formatPriority(2)).toBe("p2");
+    expect(formatPriority(3)).toBe("p3");
+    expect(formatPriority(4)).toBe("p4");
+  });
+});
+
+describe("formatPriorityName", () => {
+  test("formats priorities as names", () => {
+    expect(formatPriorityName(0)).toBe("none");
+    expect(formatPriorityName(1)).toBe("urgent");
+    expect(formatPriorityName(2)).toBe("high");
+    expect(formatPriorityName(3)).toBe("medium");
+    expect(formatPriorityName(4)).toBe("low");
+  });
+});

package/src/lib/priority.ts

@@ -0,0 +1,40 @@
+import type { Priority } from "../types";
+import { PRIORITY_FROM_NAME, PRIORITY_LABELS } from "../types";
+
+/**
+ * Parse priority from various formats:
+ * - Number: 0-4
+ * - Prefixed: p0-p4
+ * - Named: none, urgent, high, medium, low
+ */
+export function parsePriority(input: string | number | undefined): Priority {
+  if (input === undefined) return 3; // default: medium
+
+  const str = String(input).toLowerCase();
+
+  // Handle named format
+  const named = PRIORITY_FROM_NAME[str];
+  if (named !== undefined) {
+    return named;
+  }
+
+  // Handle pX format
+  if (str.startsWith("p")) {
+    const num = parseInt(str.slice(1), 10);
+    if (num >= 0 && num <= 4) return num as Priority;
+  }
+
+  // Handle numeric format
+  const num = parseInt(str, 10);
+  if (num >= 0 && num <= 4) return num as Priority;
+
+  throw new Error(`Invalid priority: ${input}. Use 0-4, p0-p4, or none/urgent/high/medium/low.`);
+}
+
+export function formatPriority(p: Priority): string {
+  return `p${p}`;
+}
+
+export function formatPriorityName(p: Priority): string {
+  return PRIORITY_LABELS[p];
+}