@nijaru/tk 0.0.2 → 0.0.4

package/src/lib/format.test.ts

@@ -6,7 +6,7 @@ import {
   formatTaskDetail,
   formatJson,
 } from "./format";
-import type { Task, TaskWithMeta, LogEntry } from "../types";
+import type { TaskWithMeta, LogEntry } from "../types";
 
 describe("shouldUseColor", () => {
   const originalEnv = process.env.NO_COLOR;
@@ -38,7 +38,7 @@ describe("shouldUseColor", () => {
 });
 
 describe("formatTaskRow", () => {
-  const task: Task & { id: string } = {
+  const task: TaskWithMeta = {
     id: "tk-a1b2",
     project: "tk",
     ref: "a1b2",
@@ -57,6 +57,8 @@ describe("formatTaskRow", () => {
     updated_at: new Date().toISOString(),
     completed_at: null,
     external: {},
+    blocked_by_incomplete: false,
+    is_overdue: false,
   };
 
   test("formats task without color", () => {
@@ -75,7 +77,7 @@ describe("formatTaskRow", () => {
   });
 
   test("truncates long titles to 50 chars", () => {
-    const longTask: Task & { id: string } = {
+    const longTask: TaskWithMeta = {
       ...task,
       title: "A".repeat(100),
     };
@@ -90,13 +92,13 @@ describe("formatTaskRow", () => {
     expect(parts.length).toBe(4); // ID | PRIO | STATUS | TITLE
   });
 
-  test("truncates long project names to 6 chars", () => {
-    const longProjectTask: Task & { id: string } = {
+  test("truncates long project names with ellipsis", () => {
+    const longProjectTask: TaskWithMeta = {
       ...task,
       id: "mylongproject-a1b2",
     };
     const result = formatTaskRow(longProjectTask, false);
-    expect(result).toContain("mylong-a1b2");
+    expect(result).toContain("mylon…-a1b2");
     expect(result).not.toContain("mylongproject");
   });
 
@@ -106,9 +108,10 @@ describe("formatTaskRow", () => {
   });
 
   test("shows overdue marker for overdue tasks", () => {
-    const overdueTask: Task & { id: string } = {
+    const overdueTask: TaskWithMeta = {
       ...task,
       due_date: "2020-01-01",
+      is_overdue: true,
     };
     const result = formatTaskRow(overdueTask, false);
     expect(result).toContain("[OVERDUE]");
@@ -116,9 +119,10 @@ describe("formatTaskRow", () => {
 
   test("does NOT show overdue marker for tasks due today", () => {
     const today = new Date().toISOString().split("T")[0] ?? null;
-    const todayTask: Task & { id: string } = {
+    const todayTask: TaskWithMeta = {
       ...task,
       due_date: today,
+      is_overdue: false,
     };
     const result = formatTaskRow(todayTask, false);
     expect(result).not.toContain("[OVERDUE]");
@@ -126,12 +130,16 @@ describe("formatTaskRow", () => {
 });
 
 describe("formatTaskList", () => {
-  test("returns message for empty list", () => {
-    expect(formatTaskList([])).toBe("No tasks found.");
+  test("returns helpful message for empty list", () => {
+    expect(formatTaskList([])).toBe("No tasks found. Run 'tk add \"title\"' to create one.");
+  });
+
+  test("allows custom empty hint", () => {
+    expect(formatTaskList([], undefined, "Custom hint")).toBe("Custom hint");
   });
 
   test("includes header and divider", () => {
-    const tasks: (Task & { id: string })[] = [
+    const tasks: TaskWithMeta[] = [
       {
         id: "tk-a1b2",
         project: "tk",
@@ -151,6 +159,8 @@ describe("formatTaskList", () => {
         updated_at: new Date().toISOString(),
         completed_at: null,
         external: {},
+        blocked_by_incomplete: false,
+        is_overdue: false,
       },
     ];
     const result = formatTaskList(tasks, false);
@@ -162,7 +172,7 @@ describe("formatTaskList", () => {
   });
 
   test("formats multiple tasks", () => {
-    const tasks: (Task & { id: string })[] = [
+    const tasks: TaskWithMeta[] = [
       {
         id: "tk-a1b2",
         project: "tk",
@@ -182,6 +192,8 @@ describe("formatTaskList", () => {
         updated_at: new Date().toISOString(),
         completed_at: null,
         external: {},
+        blocked_by_incomplete: false,
+        is_overdue: false,
       },
       {
         id: "tk-c3d4",
@@ -202,6 +214,8 @@ describe("formatTaskList", () => {
         updated_at: new Date().toISOString(),
         completed_at: null,
         external: {},
+        blocked_by_incomplete: false,
+        is_overdue: false,
       },
     ];
     const result = formatTaskList(tasks, false);

package/src/lib/format.ts

@@ -1,6 +1,7 @@
-import type { Task, TaskWithMeta, LogEntry } from "../types";
+import type { TaskWithMeta, LogEntry } from "../types";
 import { PRIORITY_COLORS, STATUS_COLORS, OVERDUE_COLOR, RESET } from "../types";
 import { formatPriority } from "./priority";
+import { formatDate, formatRelativeTime } from "./time";
 
 // Message colors
 const GREEN = "\x1b[32m";
@@ -42,56 +43,59 @@ export function dim(msg: string): string {
   return shouldUseColor() ? `${DIM}${msg}${RESET}` : msg;
 }
 
-function formatId(id: string): string {
-  // Truncate project prefix to 6 chars, keep full 4-char ref
-  // "myproject-a1b2" -> "myproj-a1b2"
+function truncate(text: string, maxLen: number): string {
+  return text.length <= maxLen ? text : text.slice(0, maxLen - 1) + "…";
+}
+
+function formatId(id: string, maxLen = 11): string {
+  // Truncate project prefix to fit maxLen, keep full 4-char ref
+  // "myproject-a1b2" -> "mypr…-a1b2"
   const dash = id.lastIndexOf("-");
-  if (dash === -1) return id.slice(0, 11);
+  if (dash === -1) return truncate(id, maxLen);
   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}`;
+  const maxProjectLen = maxLen - ref.length - 1; // -1 for dash
+  return project.length > maxProjectLen
+    ? `${truncate(project, maxProjectLen)}-${ref}`
+    : `${project}-${ref}`;
 }
 
-export function formatTaskRow(task: Task & { id: string }, useColor?: boolean): string {
+export function formatTaskRow(task: TaskWithMeta, 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;
-    }
+  const title = truncate(task.title, 50);
+  const isOverdue = task.is_overdue;
+
+  let statusText: string = task.status;
+  if (task.status === "done" && task.completed_at) {
+    statusText = `done ${formatRelativeTime(task.completed_at)}`;
   }
+  const status = statusText.padEnd(12);
 
   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 tc = task.status === "done" ? DIM : "";
+    return `${id} | ${pc}${priority}${RESET} | ${sc}${status}${RESET} | ${tc}${title}${RESET}`;
   }
 
   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.";
+export function formatTaskList(
+  tasks: TaskWithMeta[],
+  useColor?: boolean,
+  emptyHint?: string,
+): string {
+  if (tasks.length === 0) {
+    return emptyHint ?? "No tasks found. Run 'tk add \"title\"' to create one.";
+  }
   const color = useColor ?? shouldUseColor();
 
-  const header = "ID          | PRIO | STATUS  | TITLE";
-  const divider = "-".repeat(60);
+  const header = "ID          | PRIO | STATUS       | TITLE";
+  const divider = "-".repeat(65);
   const rows = tasks.map((t) => formatTaskRow(t, color));
 
   return [header, divider, ...rows].join("\n");
@@ -159,10 +163,6 @@ export function formatTaskDetail(task: TaskWithMeta, logs: LogEntry[], useColor?
   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);
 }

package/src/lib/help.ts

@@ -0,0 +1,249 @@
+import { version } from "../../package.json";
+
+export const MAIN_HELP = `tk v${version} - Task tracker for AI agents
+
+USAGE:
+  tk <command> [options]
+
+COMMANDS:
+  init         Initialize .tasks/ directory
+  add          Create task
+  ls, list     List tasks
+  ready        List ready tasks (active/open + unblocked)
+  show         Show task details
+  start        Start working (open -> active)
+  done         Complete task
+  reopen       Reopen task
+  edit         Edit task
+  log          Add log entry
+  block        Add blocker
+  unblock      Remove blocker
+  rm, remove   Delete task
+  clean        Remove old done tasks
+  check        Check for data issues
+  config       Show/set configuration
+  completions  Output shell completions
+
+GLOBAL OPTIONS:
+  -C <dir>     Run in different directory
+  --json       Output as JSON
+  -h, --help   Show help
+  -V           Show version
+
+Run 'tk <command> --help' for command-specific options.
+`;
+
+export const COMMAND_HELP: Record<string, string> = {
+  init: `tk init - Initialize .tasks/ directory
+
+USAGE:
+  tk init [options]
+
+OPTIONS:
+  -P, --project <name>   Set default project name
+`,
+  add: `tk add - Create a new task
+
+USAGE:
+  tk add <title> [options]
+
+OPTIONS:
+  -p, --priority <0-4>       Priority (0=none, 1=urgent, 2=high, 3=medium, 4=low)
+  -P, --project <name>       Project prefix for ID
+  -d, --description <text>   Description
+  -l, --labels <csv>         Labels (comma-separated)
+  -A, --assignees <csv>      Assignees (comma-separated, @me for git user)
+  --parent <id>              Parent task ID
+  --estimate <n>             Estimate (user-defined units)
+  --due <date>               Due date (YYYY-MM-DD or +Nh/+Nd/+Nw/+Nm)
+
+EXAMPLES:
+  tk add "Fix login bug" -p 1
+  tk add "New feature" -P api -l bug,urgent
+  tk add "Sprint task" --due +7d
+`,
+  ls: `tk ls - List tasks
+
+USAGE:
+  tk ls [options]
+
+OPTIONS:
+  -s, --status <status>   Filter by status (open, active, done)
+  -p, --priority <0-4>    Filter by priority
+  -P, --project <name>    Filter by project
+  -l, --label <label>     Filter by label
+  --assignee <name>       Filter by assignee
+  --parent <id>           Filter by parent
+  --roots                 Show only root tasks (no parent)
+  --overdue               Show only overdue tasks
+  -n, --limit <n>         Limit results (default: 20)
+  -a, --all               Show all (no limit)
+
+EXAMPLES:
+  tk ls -s open -p 1      # Urgent open tasks
+  tk ls --overdue         # Overdue tasks
+  tk ls -P api --roots    # Root tasks in api project
+`,
+  list: `tk list - List tasks (alias for 'ls')
+
+Run 'tk ls --help' for options.
+`,
+  ready: `tk ready - List ready tasks (active/open + unblocked)
+
+USAGE:
+  tk ready
+
+Shows active or open tasks that are not blocked by any incomplete task.
+`,
+  show: `tk show - Show task details
+
+USAGE:
+  tk show <id>
+
+EXAMPLES:
+  tk show tk-1
+  tk show 1        # If unambiguous
+`,
+  start: `tk start - Start working on a task
+
+USAGE:
+  tk start <id>
+
+Changes status from open to active.
+`,
+  done: `tk done - Complete a task
+
+USAGE:
+  tk done <id>
+
+Changes status to done.
+`,
+  reopen: `tk reopen - Reopen a task
+
+USAGE:
+  tk reopen <id>
+
+Changes status back to open.
+`,
+  edit: `tk edit - Edit a task
+
+USAGE:
+  tk edit <id> [options]
+
+OPTIONS:
+  -t, --title <text>         New title
+  -d, --description <text>   New description
+  -p, --priority <0-4>       New priority
+  -l, --labels <csv>         Replace labels (use +tag/-tag to add/remove)
+  -A, --assignees <csv>      Replace assignees
+  --parent <id>              Set parent (use - to clear)
+  --estimate <n>             Set estimate (use - to clear)
+  --due <date>               Set due date (use - to clear)
+
+EXAMPLES:
+  tk edit tk-1 -t "New title"
+  tk edit tk-1 -l +urgent     # Add label
+  tk edit tk-1 --due -        # Clear due date
+`,
+  log: `tk log - Add a log entry to a task
+
+USAGE:
+  tk log <id> "<message>"
+
+Message must be quoted.
+
+EXAMPLES:
+  tk log tk-1 "Started implementation"
+  tk log tk-1 "Blocked on API changes"
+`,
+  block: `tk block - Add a blocker dependency
+
+USAGE:
+  tk block <task> <blocker>
+
+The first task becomes blocked by the second.
+
+EXAMPLES:
+  tk block tk-2 tk-1    # tk-2 is blocked by tk-1
+`,
+  unblock: `tk unblock - Remove a blocker dependency
+
+USAGE:
+  tk unblock <task> <blocker>
+
+EXAMPLES:
+  tk unblock tk-2 tk-1
+`,
+  rm: `tk rm - Delete a task
+
+USAGE:
+  tk rm <id>
+
+EXAMPLES:
+  tk rm tk-1
+`,
+  remove: `tk remove - Delete a task (alias for 'rm')
+
+USAGE:
+  tk remove <id>
+`,
+  clean: `tk clean - Remove old completed tasks
+
+USAGE:
+  tk clean [options]
+
+OPTIONS:
+  --older-than <days>   Age threshold in days (default: from config, 14)
+  -f, --force           Remove all done tasks (ignores age and disabled state)
+
+EXAMPLES:
+  tk clean                  # Remove done tasks older than config.clean_after days
+  tk clean --older-than 30  # Remove done tasks older than 30 days
+  tk clean --force          # Remove all done tasks regardless of age
+`,
+  check: `tk check - Check for data issues
+
+USAGE:
+  tk check
+
+Scans all tasks for issues. Auto-fixable issues (orphaned references, ID
+mismatches) are fixed automatically. Unfixable issues (corrupted JSON) are
+reported for manual intervention.
+
+Note: Auto-fixing also happens during normal task operations (show, done,
+edit, etc.) - this command is for bulk cleanup or diagnostics.
+
+EXAMPLES:
+  tk check                  # Scan and fix all tasks
+`,
+  config: `tk config - Show or set configuration
+
+USAGE:
+  tk config                              Show all config
+  tk config project                      Show default project
+  tk config project <name>               Set default project
+  tk config project <new> --rename <old> Rename project (old-* → new-*)
+  tk config alias                        List aliases
+  tk config alias <name> <path>          Add alias
+  tk config alias --rm <name>            Remove alias
+
+EXAMPLES:
+  tk config project api
+  tk config project lsmvec --rename cloudlsmvec
+  tk config alias web src/web
+`,
+  completions: `tk completions - Output shell completions
+
+USAGE:
+  tk completions <shell>
+
+SHELLS:
+  bash   Bash completion script
+  zsh    Zsh completion script
+  fish   Fish completion script
+
+EXAMPLES:
+  eval "$(tk completions bash)"   # Add to ~/.bashrc
+  eval "$(tk completions zsh)"    # Add to ~/.zshrc
+`,
+};

package/src/lib/time.ts

@@ -0,0 +1,115 @@
+import type { Status } from "../types";
+
+/**
+ * Determines if a task is overdue.
+ * Done tasks are never overdue.
+ */
+export function isTaskOverdue(dueDate: string | null, status: Status): boolean {
+  if (!dueDate || status === "done") return false;
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  const parts = dueDate.split("-").map(Number);
+  const year = parts[0];
+  const month = parts[1];
+  const day = parts[2];
+  if (!year || !month || !day) return false;
+  const due = new Date(year, month - 1, day);
+  return due < today;
+}
+
+/**
+ * Format a timestamp into a human-readable relative time (e.g., "2d", "5h").
+ */
+export function formatRelativeTime(timestamp: string): string {
+  const now = new Date();
+  const date = new Date(timestamp);
+  const diffMs = now.getTime() - date.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+
+  if (diffDay > 0) return `${diffDay}d`;
+  if (diffHour > 0) return `${diffHour}h`;
+  if (diffMin > 0) return `${diffMin}m`;
+  return "now";
+}
+
+/**
+ * Format a timestamp into a localized date string.
+ */
+export function formatDate(timestamp: string): string {
+  return new Date(timestamp).toLocaleString();
+}
+
+/**
+ * Format a Date object into YYYY-MM-DD.
+ */
+export function formatLocalDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Parse a due date input string. Supports YYYY-MM-DD and relative formats like +7d.
+ */
+export function parseDueDate(input: string | undefined): string | undefined {
+  if (!input) return undefined;
+  if (input === "-") return undefined;
+
+  // Handle relative dates like +7d
+  if (input.startsWith("+")) {
+    const match = input.match(/^\+(\d+)([dwmh])$/);
+    if (match && match[1] && match[2]) {
+      const num = match[1];
+      const unit = match[2] as "h" | "d" | "w" | "m";
+      const n = Number(num);
+      const now = new Date();
+      now.setSeconds(0, 0); // Normalize to start of minute for predictability
+      switch (unit) {
+        case "h":
+          now.setHours(now.getHours() + n);
+          break;
+        case "d":
+          now.setDate(now.getDate() + n);
+          break;
+        case "w":
+          now.setDate(now.getDate() + n * 7);
+          break;
+        case "m":
+          now.setMonth(now.getMonth() + n);
+          break;
+      }
+      return formatLocalDate(now);
+    }
+    throw new Error(`Invalid relative date: ${input}. Use format like +7d, +2w, +1m`);
+  }
+
+  // Validate YYYY-MM-DD format
+  const dateMatch = input.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (dateMatch) {
+    const [, year, month, day] = dateMatch;
+    const y = parseInt(year!, 10);
+    const m = parseInt(month!, 10);
+    const d = parseInt(day!, 10);
+    const date = new Date(y, m - 1, d);
+    if (date.getFullYear() === y && date.getMonth() === m - 1 && date.getDate() === d) {
+      return input;
+    }
+  }
+
+  throw new Error(`Invalid date format: ${input}. Use YYYY-MM-DD or relative like +7d`);
+}
+
+/**
+ * Parse an estimate string (number of minutes/hours/etc. depending on convention).
+ */
+export function parseEstimate(input: string | undefined): number | undefined {
+  if (!input) return undefined;
+  if (!/^\d+$/.test(input)) {
+    throw new Error(`Invalid estimate: ${input}. Must be a non-negative number.`);
+  }
+  return Number(input);
+}