@nijaru/tk 0.0.3 → 0.0.5

package/src/cli.ts

@@ -13,11 +13,13 @@ import {
   green,
   red,
   yellow,
+  dim,
 } from "./lib/format";
 import { findRoot, setWorkingDir } from "./lib/root";
 import { parseId } from "./types";
 import type { Status, TaskWithMeta } from "./types";
 import { BASH_COMPLETION, ZSH_COMPLETION, FISH_COMPLETION } from "./lib/completions";
+import { MAIN_HELP, COMMAND_HELP } from "./lib/help";
 
 const VALID_STATUSES: Status[] = ["open", "active", "done"];
 const PROJECT_PATTERN = /^[a-z][a-z0-9]*$/;
@@ -40,7 +42,7 @@ const TASK_MUTATION_OPTIONS = {
 function validateProject(name: string): void {
   if (!PROJECT_PATTERN.test(name)) {
     throw new Error(
-      `Invalid project name: ${name}. Use lowercase letters and numbers, starting with a letter.`,
+      `Invalid project name: ${name}. Use lowercase letters and numbers, starting with a letter (e.g., 'api', 'web2').`,
     );
   }
 }
@@ -108,7 +110,7 @@ function resolveId(input: string | undefined, context: string): string {
   const matches = storage.findMatchingIds(input);
   if (matches.length > 1) {
     throw new Error(
-      `Ambiguous ID '${input}' matches ${matches.length} tasks: ${matches.join(", ")}`,
+      `Ambiguous ID '${input}' matches ${matches.length} tasks: ${matches.join(", ")}. Use more characters to narrow it down.`,
     );
   }
 
@@ -116,7 +118,7 @@ function resolveId(input: string | undefined, context: string): string {
   // and let getTask handle the "not found" error consistently.
   if (parseId(input)) return input;
 
-  throw new Error(`Task not found: ${input}`);
+  throw new Error(`Task not found: ${input}. Run 'tk ls' to see available tasks.`);
 }
 
 /**
@@ -126,7 +128,7 @@ function resolveId(input: string | undefined, context: string): string {
 function resolveTask(input: string | undefined, context: string): TaskWithMeta {
   const id = resolveId(input, context);
   const result = storage.getTask(id);
-  if (!result) error(`Task not found: ${id}`);
+  if (!result) error(`Task not found: ${id}. Run 'tk ls' to see available tasks.`);
 
   outputCleanup(id, result.cleanup);
   return result.task;
@@ -195,258 +197,12 @@ function error(message: string): never {
   process.exit(1);
 }
 
-function showHelp() {
-  console.log(`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.
-`);
+function showHelp(): void {
+  console.log(MAIN_HELP);
 }
 
-function showCommandHelp(cmd: string) {
-  const helps: 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
-`,
-  };
-
-  const help = helps[cmd];
+function showCommandHelp(cmd: string): void {
+  const help = COMMAND_HELP[cmd];
   if (help) {
     console.log(help);
   } else {
@@ -498,7 +254,7 @@ function main() {
       if (info.exists) {
         output(
           { path: info.tasksDir, created: false },
-          green(`Already initialized: ${info.tasksDir}`),
+          dim(`Already initialized: ${info.tasksDir}`),
         );
       } else {
         const path = storage.initTasks(values.project);
@@ -525,7 +281,8 @@ function main() {
       let parentId: string | undefined;
       if (values.parent) {
         const resolved = storage.resolveId(values.parent);
-        if (!resolved) error(`Parent task not found: ${values.parent}`);
+        if (!resolved)
+          error(`Parent task not found: ${values.parent}. Run 'tk ls' to see available tasks.`);
         parentId = resolved;
         const parentResult = storage.validateParent(parentId);
         if (!parentResult.ok) error(parentResult.error!);
@@ -551,8 +308,9 @@ function main() {
       const { values } = parseArgs({
         args,
         options: {
-          ...COMMON_OPTIONS,
-          label: COMMON_OPTIONS.labels, // alias for consistency
+          project: { type: "string", short: "P" },
+          priority: { type: "string", short: "p" },
+          label: { type: "string", short: "l" },
           status: { type: "string", short: "s" },
           assignee: { type: "string" },
           parent: { type: "string" },
@@ -571,7 +329,8 @@ function main() {
       let parentFilter: string | undefined;
       if (values.parent) {
         const resolved = storage.resolveId(values.parent);
-        if (!resolved) error(`Parent task not found: ${values.parent}`);
+        if (!resolved)
+          error(`Parent task not found: ${values.parent}. Run 'tk ls' to see available tasks.`);
         parentFilter = resolved;
       }
 
@@ -579,7 +338,7 @@ function main() {
         status,
         priority,
         project: values.project,
-        label: values.label ?? values.labels,
+        label: values.label,
         assignee: values.assignee,
         parent: parentFilter,
         roots: values.roots,
@@ -592,7 +351,10 @@ function main() {
 
     case "ready": {
       const list = storage.listReadyTasks();
-      output(list, formatTaskList(list));
+      output(
+        list,
+        formatTaskList(list, undefined, "No ready tasks. All tasks are either done or blocked."),
+      );
       break;
     }
 
@@ -641,12 +403,12 @@ function main() {
       let labels: string[] | undefined;
       if (values.labels) {
         if (values.labels.startsWith("+")) {
-          // Add label (avoid duplicates)
-          const newLabel = values.labels.slice(1);
+          const newLabel = values.labels.slice(1).trim();
+          if (!newLabel) throw new Error("Label name required after '+'");
           labels = task.labels.includes(newLabel) ? task.labels : [...task.labels, newLabel];
         } else if (values.labels.startsWith("-")) {
-          // Remove label
-          const removeLabel = values.labels.slice(1);
+          const removeLabel = values.labels.slice(1).trim();
+          if (!removeLabel) throw new Error("Label name required after '-'");
           labels = task.labels.filter((l: string) => l !== removeLabel);
         } else {
           // Replace labels
@@ -660,7 +422,8 @@ function main() {
         resolvedParent = null;
       } else if (values.parent) {
         const resolved = storage.resolveId(values.parent);
-        if (!resolved) error(`Parent task not found: ${values.parent}`);
+        if (!resolved)
+          error(`Parent task not found: ${values.parent}. Run 'tk ls' to see available tasks.`);
         resolvedParent = resolved;
         const parentResult = storage.validateParent(resolvedParent, task.id);
         if (!parentResult.ok) error(parentResult.error!);
@@ -668,7 +431,7 @@ function main() {
 
       const updated = storage.updateTask(task.id, {
         title: values.title?.trim() || undefined,
-        description: values.description,
+        description: values.description === "-" ? null : values.description,
         priority: values.priority ? parsePriority(values.priority) : undefined,
         labels,
         assignees: parseAssignees(values.assignees),
@@ -696,10 +459,13 @@ function main() {
     }
 
     case "block": {
-      if (!args[0] || !args[1]) error("Usage: tk block <task> <blocker>");
+      if (!args[0] || !args[1])
+        error(
+          "Two IDs required: tk block <task> <blocker>. The first task becomes blocked by the second.",
+        );
       const taskId = resolveId(args[0], "block");
       const blockerId = resolveId(args[1], "block");
-      if (taskId === blockerId) error("Task cannot block itself");
+      if (taskId === blockerId) error("Task cannot block itself.");
       const result = storage.addBlock(taskId, blockerId);
       if (!result.ok) error(result.error!);
       output(
@@ -710,7 +476,7 @@ function main() {
     }
 
     case "unblock": {
-      if (!args[0] || !args[1]) error("Usage: tk unblock <task> <blocker>");
+      if (!args[0] || !args[1]) error("Two IDs required: tk unblock <task> <blocker>.");
       const taskId = resolveId(args[0], "unblock");
       const blockerId = resolveId(args[1], "unblock");
       const removed = storage.removeBlock(taskId, blockerId);
@@ -726,11 +492,24 @@ function main() {
     case "remove": {
       const id = resolveId(args[0], "rm");
       const deleted = storage.deleteTask(id);
-      if (!deleted) error(`Task not found: ${id}`);
+      if (!deleted) error(`Task not found: ${id}. Run 'tk ls' to see available tasks.`);
       output({ id, deleted: true }, green(`Deleted: ${id}`));
       break;
     }
 
+    case "mv":
+    case "move": {
+      const id = resolveId(args[0], "mv");
+      const newProject = args[1];
+      if (!newProject) error("Project required: tk mv <id> <project>");
+      validateProject(newProject);
+      const result = storage.moveTask(id, newProject);
+      const refMsg =
+        result.referencesUpdated > 0 ? `\nUpdated ${result.referencesUpdated} references` : "";
+      output(result, green(`Moved: ${result.old_id} → ${result.new_id}${refMsg}`));
+      break;
+    }
+
     case "clean": {
       const config = storage.getConfig();
       const { values } = parseArgs({
@@ -851,43 +630,8 @@ function main() {
           }
           break;
         }
-        case "alias": {
-          const { values, positionals } = parseArgs({
-            args: args.slice(1),
-            options: {
-              rm: { type: "string" },
-              list: { type: "boolean" },
-            },
-            allowPositionals: true,
-          });
-
-          if (values.rm) {
-            const updated = storage.removeAlias(values.rm);
-            output(updated, green(`Removed alias: ${values.rm}`));
-          } else if (positionals.length >= 2) {
-            const alias = positionals[0];
-            const path = positionals[1];
-            if (!alias || !path || !alias.trim()) {
-              error("Alias name and path are required");
-            }
-            const updated = storage.setAlias(alias, path);
-            output(updated, green(`Added alias: ${alias} → ${path}`));
-          } else {
-            // List aliases
-            const aliases = config.aliases;
-            if (Object.keys(aliases).length === 0) {
-              output({ aliases: {} }, "No aliases defined.");
-            } else {
-              const lines = Object.entries(aliases)
-                .map(([a, p]) => `${a} → ${p}`)
-                .join("\n");
-              output({ aliases }, lines);
-            }
-          }
-          break;
-        }
         default:
-          error(`Unknown config command: ${subcommand}`);
+          error(`Unknown config command: ${subcommand}. Valid: project.`);
       }
       break;
     }
@@ -905,7 +649,7 @@ function main() {
           console.log(FISH_COMPLETION);
           break;
         default:
-          error("Shell required: tk completions <bash|zsh|fish>");
+          error("Shell required: tk completions <bash|zsh|fish>. Add to your shell's rc file.");
       }
       break;
     }