@nijaru/tk 0.0.3 → 0.0.5

package/src/lib/help.ts

@@ -0,0 +1,266 @@
+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
+  mv, move     Move task to different project
+  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
+`,
+  mv: `tk mv - Move a task to a different project
+
+USAGE:
+  tk mv <id> <project>
+
+Moves a task to a new project, keeping the same ref.
+Errors if the new ID already exists.
+Updates all blocked_by and parent references.
+
+EXAMPLES:
+  tk mv api-a1b2 web        # Moves api-a1b2 → web-a1b2
+  tk mv a1b2 archive        # Partial ID resolution
+`,
+  move: `tk move - Move a task to a different project (alias for 'mv')
+
+USAGE:
+  tk move <id> <project>
+
+Run 'tk mv --help' for options.
+`,
+  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-*)
+
+EXAMPLES:
+  tk config project api
+  tk config project lsmvec --rename cloudlsmvec
+`,
+  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.test.ts

@@ -0,0 +1,222 @@
+import { test, expect, describe } from "bun:test";
+import {
+  isTaskOverdue,
+  daysUntilDue,
+  formatRelativeTime,
+  formatDate,
+  formatLocalDate,
+  parseDueDate,
+  parseEstimate,
+  DUE_SOON_THRESHOLD,
+} from "./time";
+
+describe("isTaskOverdue", () => {
+  test("returns false when no due date", () => {
+    expect(isTaskOverdue(null, "open")).toBe(false);
+  });
+
+  test("returns false for done tasks regardless of date", () => {
+    expect(isTaskOverdue("2020-01-01", "done")).toBe(false);
+  });
+
+  test("returns false for active done tasks", () => {
+    expect(isTaskOverdue("2020-01-01", "done")).toBe(false);
+  });
+
+  test("returns true for past dates (open)", () => {
+    expect(isTaskOverdue("2020-01-01", "open")).toBe(true);
+  });
+
+  test("returns true for past dates (active)", () => {
+    expect(isTaskOverdue("2020-06-15", "active")).toBe(true);
+  });
+
+  test("returns false for today", () => {
+    const today = new Date().toISOString().split("T")[0]!;
+    expect(isTaskOverdue(today, "open")).toBe(false);
+  });
+
+  test("returns false for future dates", () => {
+    const future = new Date();
+    future.setDate(future.getDate() + 7);
+    const dateStr = future.toISOString().split("T")[0]!;
+    expect(isTaskOverdue(dateStr, "open")).toBe(false);
+  });
+
+  test("returns false for invalid date string", () => {
+    expect(isTaskOverdue("not-a-date", "open")).toBe(false);
+  });
+});
+
+describe("daysUntilDue", () => {
+  test("returns null when no due date", () => {
+    expect(daysUntilDue(null, "open")).toBeNull();
+  });
+
+  test("returns null when no due date (active)", () => {
+    expect(daysUntilDue(null, "active")).toBeNull();
+  });
+
+  test("returns null for done tasks", () => {
+    const future = new Date();
+    future.setDate(future.getDate() + 3);
+    const dateStr = future.toISOString().split("T")[0]!;
+    expect(daysUntilDue(dateStr, "done")).toBeNull();
+  });
+
+  test("returns 0 for due today (open)", () => {
+    const today = new Date().toISOString().split("T")[0]!;
+    expect(daysUntilDue(today, "open")).toBe(0);
+  });
+
+  test("returns 0 for due today (active)", () => {
+    const today = new Date().toISOString().split("T")[0]!;
+    expect(daysUntilDue(today, "active")).toBe(0);
+  });
+
+  test("returns N for due in N days", () => {
+    const future = new Date();
+    future.setDate(future.getDate() + 3);
+    const dateStr = future.toISOString().split("T")[0]!;
+    expect(daysUntilDue(dateStr, "open")).toBe(3);
+  });
+
+  test("returns null for past dates (already overdue)", () => {
+    expect(daysUntilDue("2020-01-01", "open")).toBeNull();
+  });
+
+  test("returns null for invalid date string", () => {
+    expect(daysUntilDue("not-a-date", "open")).toBeNull();
+  });
+
+  test("DUE_SOON_THRESHOLD is 7", () => {
+    expect(DUE_SOON_THRESHOLD).toBe(7);
+  });
+});
+
+describe("formatRelativeTime", () => {
+  test("returns 'now' for very recent timestamps", () => {
+    const ts = new Date().toISOString();
+    expect(formatRelativeTime(ts)).toBe("now");
+  });
+
+  test("returns minutes for timestamps minutes ago", () => {
+    const ts = new Date(Date.now() - 5 * 60 * 1000).toISOString();
+    expect(formatRelativeTime(ts)).toBe("5m");
+  });
+
+  test("returns hours for timestamps hours ago", () => {
+    const ts = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+    expect(formatRelativeTime(ts)).toBe("3h");
+  });
+
+  test("returns days for timestamps days ago", () => {
+    const ts = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString();
+    expect(formatRelativeTime(ts)).toBe("2d");
+  });
+});
+
+describe("formatDate", () => {
+  test("returns a non-empty string for a valid ISO timestamp", () => {
+    const result = formatDate("2024-01-15T10:30:00.000Z");
+    expect(typeof result).toBe("string");
+    expect(result.length).toBeGreaterThan(0);
+  });
+});
+
+describe("formatLocalDate", () => {
+  test("formats date as YYYY-MM-DD", () => {
+    const date = new Date(2026, 0, 15); // Jan 15 2026
+    expect(formatLocalDate(date)).toBe("2026-01-15");
+  });
+
+  test("zero-pads month and day", () => {
+    const date = new Date(2026, 1, 5); // Feb 5 2026
+    expect(formatLocalDate(date)).toBe("2026-02-05");
+  });
+});
+
+describe("parseDueDate", () => {
+  test("returns undefined for undefined input", () => {
+    expect(parseDueDate(undefined)).toBeUndefined();
+  });
+
+  test("returns undefined for '-' (clear sentinel)", () => {
+    expect(parseDueDate("-")).toBeUndefined();
+  });
+
+  test("returns valid YYYY-MM-DD unchanged", () => {
+    expect(parseDueDate("2026-06-15")).toBe("2026-06-15");
+  });
+
+  test("parses +Nd relative date", () => {
+    const result = parseDueDate("+7d");
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    const resultDate = new Date(result!);
+    const today = new Date();
+    const diffDays = Math.round((resultDate.getTime() - today.getTime()) / (1000 * 60 * 60 * 24));
+    expect(diffDays).toBeGreaterThanOrEqual(6);
+    expect(diffDays).toBeLessThanOrEqual(8);
+  });
+
+  test("parses +Nw relative date", () => {
+    const result = parseDueDate("+2w");
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("parses +Nm relative date", () => {
+    const result = parseDueDate("+1m");
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("parses +Nh relative date", () => {
+    const result = parseDueDate("+3h");
+    expect(result).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  test("throws for invalid relative format", () => {
+    expect(() => parseDueDate("+7x")).toThrow("Invalid relative date");
+  });
+
+  test("throws for bare + with no content", () => {
+    expect(() => parseDueDate("+")).toThrow("Invalid relative date");
+  });
+
+  test("throws for non-date string", () => {
+    expect(() => parseDueDate("not-a-date")).toThrow("Invalid date format");
+  });
+
+  test("throws for invalid calendar date (month 13)", () => {
+    expect(() => parseDueDate("2026-13-01")).toThrow("Invalid date format");
+  });
+
+  test("throws for invalid calendar date (day 32)", () => {
+    expect(() => parseDueDate("2026-01-32")).toThrow("Invalid date format");
+  });
+});
+
+describe("parseEstimate", () => {
+  test("returns undefined for undefined input", () => {
+    expect(parseEstimate(undefined)).toBeUndefined();
+  });
+
+  test("parses valid integer string", () => {
+    expect(parseEstimate("42")).toBe(42);
+  });
+
+  test("parses zero", () => {
+    expect(parseEstimate("0")).toBe(0);
+  });
+
+  test("throws for non-numeric string", () => {
+    expect(() => parseEstimate("abc")).toThrow("Invalid estimate");
+  });
+
+  test("throws for decimal", () => {
+    expect(() => parseEstimate("3.5")).toThrow("Invalid estimate");
+  });
+
+  test("throws for negative number", () => {
+    expect(() => parseEstimate("-1")).toThrow("Invalid estimate");
+  });
+});

package/src/lib/time.ts

@@ -1,5 +1,7 @@
 import type { Status } from "../types";
 
+export const DUE_SOON_THRESHOLD = 7;
+
 /**
  * Determines if a task is overdue.
  * Done tasks are never overdue.
@@ -12,11 +14,32 @@ export function isTaskOverdue(dueDate: string | null, status: Status): boolean {
   const year = parts[0];
   const month = parts[1];
   const day = parts[2];
-  if (!year || !month || !day) return false;
+  if (year === undefined || !month || !day) return false;
   const due = new Date(year, month - 1, day);
   return due < today;
 }
 
+/**
+ * Returns the number of days until a task is due (0 = today), or null if:
+ * - No due date
+ * - Task is done
+ * - Task is already overdue
+ */
+export function daysUntilDue(dueDate: string | null, status: Status): number | null {
+  if (!dueDate || status === "done") return null;
+  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 === undefined || !month || !day) return null;
+  const due = new Date(year, month - 1, day);
+  const diffMs = due.getTime() - today.getTime();
+  if (diffMs < 0) return null; // already overdue
+  return Math.round(diffMs / (1000 * 60 * 60 * 24));
+}
+
 /**
  * Format a timestamp into a human-readable relative time (e.g., "2d", "5h").
  */

package/src/types.ts

@@ -51,7 +51,8 @@ export function parseId(id: string): { project: string; ref: string } | null {
 // Generate random 4-char ref (a-z0-9)
 export function generateRef(): string {
   const chars = "abcdefghijklmnopqrstuvwxyz0123456789"; // 36 chars
-  const maxValid = 252; // 36 * 7 - reject >= 252 to avoid modulo bias
+  const charsetLen = chars.length; // 36
+  const maxValid = charsetLen * Math.floor(256 / charsetLen); // 252: reject >= maxValid to avoid modulo bias
   const result: string[] = [];
 
   while (result.length < 4) {
@@ -59,7 +60,7 @@ export function generateRef(): string {
     crypto.getRandomValues(bytes);
     for (const b of bytes) {
       if (b < maxValid && result.length < 4) {
-        result.push(chars[b % 36]!);
+        result.push(chars[b % charsetLen]!);
       }
     }
   }
@@ -70,6 +71,7 @@ export interface TaskWithMeta extends Task {
   id: string; // computed from project-ref
   blocked_by_incomplete: boolean;
   is_overdue: boolean;
+  days_until_due: number | null;
 }
 
 export interface Config {
@@ -80,7 +82,6 @@ export interface Config {
     labels: string[];
     assignees: string[];
   };
-  aliases: Record<string, string>; // alias -> path for auto-project detection
   clean_after: number | false; // days to keep done tasks, or false to disable
 }
 
@@ -92,7 +93,6 @@ export const DEFAULT_CONFIG: Config = {
     labels: [],
     assignees: [],
   },
-  aliases: {},
   clean_after: 14,
 };