@nijaru/tk 0.0.5 → 0.1.1

package/src/db/storage.ts

@@ -1,1050 +0,0 @@
-import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  unlinkSync,
-  readFileSync,
-  writeFileSync,
-  realpathSync,
-  lstatSync,
-  renameSync,
-} from "fs";
-import { join, resolve, basename } from "path";
-import { getTasksDir, getWorkingDir } from "../lib/root";
-import { isTaskOverdue, daysUntilDue } from "../lib/time";
-import type { Task, Config, Status, Priority, TaskWithMeta, LogEntry } from "../types";
-import { DEFAULT_CONFIG, taskId, parseId, generateRef } from "../types";
-
-// --- Path Utilities ---
-
-function ensureTasksDir(): string {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) {
-    mkdirSync(tasksDir, { recursive: true });
-  }
-  return tasksDir;
-}
-
-function getTaskPath(tasksDir: string, id: string): string {
-  return join(tasksDir, `${id}.json`);
-}
-
-function getConfigPath(tasksDir: string): string {
-  return join(tasksDir, "config.json");
-}
-
-/**
- * Write a file atomically by writing to a temporary file and renaming it.
- */
-function atomicWrite(path: string, content: string): void {
-  const tempPath = `${path}.tmp.${generateRef()}`;
-  try {
-    writeFileSync(tempPath, content);
-    renameSync(tempPath, path);
-  } catch (e) {
-    if (existsSync(tempPath)) {
-      unlinkSync(tempPath);
-    }
-    throw e;
-  }
-}
-
-function validatePathSafety(path: string, tasksDir: string): boolean {
-  try {
-    if (existsSync(path)) {
-      const stats = lstatSync(path);
-      if (stats.isSymbolicLink()) {
-        const realPath = realpathSync(path);
-        const resolvedTasksDir = resolve(tasksDir);
-        if (!realPath.startsWith(resolvedTasksDir)) {
-          return false;
-        }
-      }
-    }
-    return true;
-  } catch {
-    // Fail closed: deny access on any error
-    return false;
-  }
-}
-
-const STATUS_ORDER: Record<Status, number> = { active: 0, open: 1, done: 2 };
-
-/**
- * Compare two tasks for sorting:
- * 1. Status (active > open > done)
- * 2. If active/open: overdue > priority (1-4, 0) > due date > created_at
- * 3. If done: completed_at (newest first)
- */
-export function compareTasks(a: Task, b: Task): number {
-  const sA = STATUS_ORDER[a.status];
-  const sB = STATUS_ORDER[b.status];
-  if (sA !== sB) return sA - sB;
-
-  if (a.status !== "done") {
-    // Overdue hoist
-    const overdueA = isTaskOverdue(a.due_date, a.status) ? 0 : 1;
-    const overdueB = isTaskOverdue(b.due_date, b.status) ? 0 : 1;
-    if (overdueA !== overdueB) return overdueA - overdueB;
-
-    // Priority (1-4, then 0/none)
-    const pA = a.priority === 0 ? 5 : a.priority;
-    const pB = b.priority === 0 ? 5 : b.priority;
-    if (pA !== pB) return pA - pB;
-
-    // Due date (soonest first, nulls last)
-    if (a.due_date !== b.due_date) {
-      if (!a.due_date) return 1;
-      if (!b.due_date) return -1;
-      return a.due_date.localeCompare(b.due_date);
-    }
-
-    // Created at (newest first)
-    return new Date(b.created_at).getTime() - new Date(a.created_at).getTime();
-  }
-
-  // Done tasks: newest completion first
-  const timeA = a.completed_at ? new Date(a.completed_at).getTime() : 0;
-  const timeB = b.completed_at ? new Date(b.completed_at).getTime() : 0;
-  return timeB - timeA;
-}
-
-// --- Config Operations ---
-
-export function getConfig(): Config {
-  const tasksDir = getTasksDir();
-  const configPath = getConfigPath(tasksDir);
-  if (!existsSync(configPath)) {
-    return { ...DEFAULT_CONFIG };
-  }
-  try {
-    const text = readFileSync(configPath, "utf-8");
-    const parsed = JSON.parse(text);
-    return {
-      ...DEFAULT_CONFIG,
-      ...parsed,
-      defaults: { ...DEFAULT_CONFIG.defaults, ...parsed.defaults },
-    };
-  } catch {
-    return { ...DEFAULT_CONFIG };
-  }
-}
-
-export function saveConfig(config: Config): void {
-  const tasksDir = ensureTasksDir();
-  const configPath = getConfigPath(tasksDir);
-  atomicWrite(configPath, JSON.stringify(config, null, 2));
-}
-
-export function updateConfig(updates: Partial<Config>): Config {
-  const config = getConfig();
-  Object.assign(config, updates);
-  saveConfig(config);
-  return config;
-}
-
-export function setDefaultProject(project: string): Config {
-  return updateConfig({ project });
-}
-
-export interface RenameResult {
-  renamed: string[];
-  referencesUpdated: number;
-}
-
-export function renameProject(oldProject: string, newProject: string): RenameResult {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) {
-    throw new Error("No .tasks/ directory found");
-  }
-
-  const allTasks = getAllTasks(tasksDir);
-
-  // Find tasks to rename
-  const toRename = allTasks.filter((t) => t.project === oldProject);
-  if (toRename.length === 0) {
-    throw new Error(`No tasks found with project "${oldProject}". Run 'tk ls' to see projects.`);
-  }
-
-  // Check for collisions
-  const existingIds = new Set(allTasks.map((t) => taskId(t)));
-  for (const task of toRename) {
-    const newId = `${newProject}-${task.ref}`;
-    if (existingIds.has(newId)) {
-      throw new Error(`Cannot rename: "${newId}" already exists. Choose a different project name.`);
-    }
-  }
-
-  // Build old→new ID mapping
-  const idMap = new Map<string, string>();
-  for (const task of toRename) {
-    const oldId = taskId(task);
-    const newId = `${newProject}-${task.ref}`;
-    idMap.set(oldId, newId);
-  }
-
-  // Update references in ALL tasks and rename files
-  let referencesUpdated = 0;
-  for (const task of allTasks) {
-    let modified = false;
-
-    // Update blocked_by references
-    if (task.blocked_by.length > 0) {
-      const newBlockedBy = task.blocked_by.map((id) => {
-        const newId = idMap.get(id);
-        if (newId) {
-          referencesUpdated++;
-          return newId;
-        }
-        return id;
-      });
-      if (newBlockedBy.some((id, i) => id !== task.blocked_by[i])) {
-        task.blocked_by = newBlockedBy;
-        modified = true;
-      }
-    }
-
-    // Update parent reference
-    if (task.parent && idMap.has(task.parent)) {
-      task.parent = idMap.get(task.parent)!;
-      referencesUpdated++;
-      modified = true;
-    }
-
-    // If this task is being renamed
-    if (task.project === oldProject) {
-      const oldPath = getTaskPath(tasksDir, taskId(task));
-      task.project = newProject;
-      const newPath = getTaskPath(tasksDir, taskId(task));
-
-      // Write to new path, delete old
-      atomicWrite(newPath, JSON.stringify(task, null, 2));
-      unlinkSync(oldPath);
-    } else if (modified) {
-      // Just update references in non-renamed task
-      const path = getTaskPath(tasksDir, taskId(task));
-      atomicWrite(path, JSON.stringify(task, null, 2));
-    }
-  }
-
-  // Update default project in config
-  const config = getConfig();
-  if (config.project === oldProject) {
-    updateConfig({ project: newProject });
-  }
-
-  return {
-    renamed: toRename.map((t) => `${newProject}-${t.ref}`),
-    referencesUpdated,
-  };
-}
-
-export interface MoveResult {
-  old_id: string;
-  new_id: string;
-  referencesUpdated: number;
-}
-
-export function moveTask(oldId: string, newProject: string): MoveResult {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) {
-    throw new Error("No .tasks/ directory found");
-  }
-
-  const parsed = parseId(oldId);
-  if (!parsed) {
-    throw new Error(`Invalid task ID: ${oldId}`);
-  }
-
-  if (parsed.project === newProject) {
-    throw new Error(`Task ${oldId} is already in project "${newProject}"`);
-  }
-
-  const oldPath = getTaskPath(tasksDir, oldId);
-  if (!existsSync(oldPath)) {
-    throw new Error(`Task not found: ${oldId}`);
-  }
-
-  const newId = `${newProject}-${parsed.ref}`;
-  const newPath = getTaskPath(tasksDir, newId);
-  if (existsSync(newPath)) {
-    throw new Error(
-      `Cannot move: "${newId}" already exists. The ref conflicts with an existing task.`,
-    );
-  }
-
-  const task = readTaskFile(oldPath, tasksDir);
-  if (!task) {
-    throw new Error(`Failed to read task: ${oldId}`);
-  }
-
-  // Write new file with updated project
-  task.project = newProject;
-  task.updated_at = new Date().toISOString();
-  atomicWrite(newPath, JSON.stringify(task, null, 2));
-  unlinkSync(oldPath);
-
-  // Update all blocked_by and parent refs in other tasks
-  let referencesUpdated = 0;
-  const allTasks = getAllTasks(tasksDir);
-  for (const other of allTasks) {
-    let modified = false;
-
-    if (other.blocked_by.includes(oldId)) {
-      other.blocked_by = other.blocked_by.map((id) => (id === oldId ? newId : id));
-      referencesUpdated++;
-      modified = true;
-    }
-
-    if (other.parent === oldId) {
-      other.parent = newId;
-      referencesUpdated++;
-      modified = true;
-    }
-
-    if (modified) {
-      atomicWrite(getTaskPath(tasksDir, taskId(other)), JSON.stringify(other, null, 2));
-    }
-  }
-
-  return { old_id: oldId, new_id: newId, referencesUpdated };
-}
-
-// --- Task File Operations ---
-
-function readTaskFile(path: string, tasksDir?: string): Task | null {
-  if (!existsSync(path)) return null;
-  if (tasksDir && !validatePathSafety(path, tasksDir)) {
-    return null;
-  }
-  try {
-    const text = readFileSync(path, "utf-8");
-    const parsed = JSON.parse(text);
-    // Validate structure to avoid crashes on malformed data
-    if (!isValidTaskStructure(parsed)) return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-function writeTaskFile(path: string, task: Task): void {
-  atomicWrite(path, JSON.stringify(task, null, 2));
-}
-
-/**
- * Validate that a parsed object has the minimum required Task structure.
- * Returns true if valid, false otherwise.
- */
-function isValidTaskStructure(obj: unknown): obj is Task {
-  if (!obj || typeof obj !== "object") return false;
-  const t = obj as Record<string, unknown>;
-  return (
-    typeof t.project === "string" &&
-    typeof t.ref === "string" &&
-    typeof t.title === "string" &&
-    typeof t.status === "string" &&
-    Array.isArray(t.blocked_by) &&
-    Array.isArray(t.logs)
-  );
-}
-
-/**
- * Remove references to specific IDs from a task's blocked_by and parent fields.
- * Returns true if the task was modified.
- */
-function removeRefsFromTask(task: Task, shouldRemove: (id: string) => boolean): boolean {
-  let modified = false;
-
-  const originalLen = task.blocked_by.length;
-  task.blocked_by = task.blocked_by.filter((id) => !shouldRemove(id));
-  if (task.blocked_by.length !== originalLen) {
-    modified = true;
-  }
-
-  if (task.parent && shouldRemove(task.parent)) {
-    task.parent = null;
-    modified = true;
-  }
-
-  return modified;
-}
-
-// --- Auto-cleanup ---
-
-export interface CleanupInfo {
-  orphanedBlockers: string[];
-  orphanedParent: string | null;
-  idMismatch: { was: string; fixed: string } | null;
-}
-
-/**
- * Clean orphaned references from a task. Returns info about what was cleaned.
- * Writes to disk if any changes were made.
- */
-function cleanTaskOrphans(
-  task: Task,
-  path: string,
-  expectedId: string,
-  tasksDir: string,
-): CleanupInfo {
-  const cleanup: CleanupInfo = {
-    orphanedBlockers: [],
-    orphanedParent: null,
-    idMismatch: null,
-  };
-
-  let modified = false;
-
-  // Check ID mismatch (filename vs content)
-  const actualId = taskId(task);
-  if (actualId !== expectedId) {
-    const parsed = parseId(expectedId);
-    if (parsed) {
-      cleanup.idMismatch = { was: actualId, fixed: expectedId };
-      task.project = parsed.project;
-      task.ref = parsed.ref;
-      modified = true;
-    }
-  }
-
-  // Check orphaned blocked_by references
-  const validBlockers: string[] = [];
-  for (const blockerId of task.blocked_by) {
-    if (existsSync(getTaskPath(tasksDir, blockerId))) {
-      validBlockers.push(blockerId);
-    } else {
-      cleanup.orphanedBlockers.push(blockerId);
-      modified = true;
-    }
-  }
-  if (cleanup.orphanedBlockers.length > 0) {
-    task.blocked_by = validBlockers;
-  }
-
-  // Check orphaned parent reference
-  if (task.parent && !existsSync(getTaskPath(tasksDir, task.parent))) {
-    cleanup.orphanedParent = task.parent;
-    task.parent = null;
-    modified = true;
-  }
-
-  // Write back if modified
-  if (modified) {
-    task.updated_at = new Date().toISOString();
-    atomicWrite(path, JSON.stringify(task, null, 2));
-  }
-
-  return cleanup;
-}
-
-function hasCleanup(info: CleanupInfo): boolean {
-  return (
-    info.orphanedBlockers.length > 0 || info.orphanedParent !== null || info.idMismatch !== null
-  );
-}
-
-export function formatCleanupMessage(taskId: string, info: CleanupInfo): string {
-  const parts: string[] = [];
-
-  if (info.orphanedBlockers.length > 0) {
-    const s = info.orphanedBlockers.length === 1 ? "reference" : "references";
-    parts.push(`${info.orphanedBlockers.length} orphaned ${s}`);
-  }
-  if (info.orphanedParent) {
-    parts.push("orphaned parent");
-  }
-  if (info.idMismatch) {
-    parts.push(`ID mismatch (was ${info.idMismatch.was})`);
-  }
-
-  return `(cleaned ${parts.join(", ")} from ${taskId})`;
-}
-
-function writeTaskFileExclusive(path: string, task: Task): boolean {
-  try {
-    writeFileSync(path, JSON.stringify(task, null, 2), { flag: "wx" });
-    return true;
-  } catch (e) {
-    if (e instanceof Error && "code" in e && e.code === "EEXIST") {
-      return false;
-    }
-    throw e;
-  }
-}
-
-function getAllTasks(tasksDir: string): Task[] {
-  if (!existsSync(tasksDir)) return [];
-  const files = readdirSync(tasksDir).filter((f) => f.endsWith(".json") && f !== "config.json");
-  const tasks: Task[] = [];
-  for (const file of files) {
-    const task = readTaskFile(join(tasksDir, file), tasksDir);
-    if (task) tasks.push(task);
-  }
-  return tasks;
-}
-
-// --- Cycle Detection ---
-
-function wouldCreateBlockCycle(tasksDir: string, taskIdStr: string, blockerId: string): boolean {
-  const visited = new Set<string>();
-  const stack = [blockerId];
-
-  while (stack.length > 0) {
-    const current = stack.pop()!;
-    if (current === taskIdStr) return true;
-    if (visited.has(current)) continue;
-    visited.add(current);
-
-    const task = readTaskFile(getTaskPath(tasksDir, current), tasksDir);
-    if (task) {
-      for (const dep of task.blocked_by) {
-        stack.push(dep);
-      }
-    }
-  }
-  return false;
-}
-
-function wouldCreateParentCycle(tasksDir: string, taskIdStr: string, parentId: string): boolean {
-  const visited = new Set<string>();
-  let current: string | null = parentId;
-
-  while (current) {
-    if (current === taskIdStr) return true;
-    if (visited.has(current)) return true;
-    visited.add(current);
-
-    const task = readTaskFile(getTaskPath(tasksDir, current), tasksDir);
-    current = task?.parent ?? null;
-  }
-  return false;
-}
-
-// --- Parent Validation ---
-
-export function validateParent(
-  parentId: string,
-  currentTaskId?: string,
-): { ok: boolean; error?: string } {
-  if (!parseId(parentId)) {
-    return { ok: false, error: `Invalid parent ID format: ${parentId}` };
-  }
-
-  if (currentTaskId && parentId === currentTaskId) {
-    return { ok: false, error: "Task cannot be its own parent" };
-  }
-
-  const tasksDir = getTasksDir();
-
-  const parentPath = getTaskPath(tasksDir, parentId);
-  if (!existsSync(parentPath)) {
-    return { ok: false, error: `Parent task not found: ${parentId}` };
-  }
-
-  if (currentTaskId && wouldCreateParentCycle(tasksDir, currentTaskId, parentId)) {
-    return { ok: false, error: "Would create circular parent relationship" };
-  }
-
-  return { ok: true };
-}
-
-// --- Task Enrichment ---
-
-/**
- * Enriches a Task with computed metadata.
- * Can optionally take a status map for efficient bulk processing of blockers.
- */
-export function enrichTask(task: Task, statusMap?: Map<string, Status>): TaskWithMeta {
-  const tasksDir = getTasksDir();
-  let blockedByIncomplete = false;
-
-  for (const blockerId of task.blocked_by) {
-    let status = statusMap?.get(blockerId);
-    if (status === undefined) {
-      status = readTaskFile(getTaskPath(tasksDir, blockerId), tasksDir)?.status;
-    }
-
-    if (status && status !== "done") {
-      blockedByIncomplete = true;
-      break;
-    }
-  }
-
-  return {
-    ...task,
-    id: taskId(task),
-    is_overdue: isTaskOverdue(task.due_date, task.status),
-    blocked_by_incomplete: blockedByIncomplete,
-    days_until_due: daysUntilDue(task.due_date, task.status),
-  };
-}
-
-// --- Task CRUD ---
-
-export interface CreateTaskOptions {
-  title: string;
-  description?: string;
-  priority?: Priority;
-  project?: string;
-  labels?: string[];
-  assignees?: string[];
-  parent?: string;
-  estimate?: number;
-  due_date?: string;
-}
-
-export function createTask(options: CreateTaskOptions): Task & { id: string } {
-  const tasksDir = ensureTasksDir();
-  const config = getConfig();
-  const project = options.project ?? config.project;
-  const now = new Date().toISOString();
-
-  // Generate random ref with collision detection
-  const maxRetries = 10;
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    const ref = generateRef();
-    const id = `${project}-${ref}`;
-
-    const task: Task = {
-      project,
-      ref,
-      title: options.title,
-      description: options.description ?? null,
-      status: "open",
-      priority: options.priority ?? config.defaults.priority,
-      labels: options.labels ?? [...config.defaults.labels],
-      assignees: options.assignees ?? [...config.defaults.assignees],
-      parent: options.parent ?? null,
-      blocked_by: [],
-      estimate: options.estimate ?? null,
-      due_date: options.due_date ?? null,
-      logs: [],
-      created_at: now,
-      updated_at: now,
-      completed_at: null,
-      external: {},
-    };
-
-    const path = getTaskPath(tasksDir, id);
-    if (writeTaskFileExclusive(path, task)) {
-      return enrichTask(task);
-    }
-    // Collision (extremely rare with 4 chars) - retry with new ref
-  }
-
-  throw new Error(`Failed to create task after ${maxRetries} attempts`);
-}
-
-export interface TaskResult {
-  task: TaskWithMeta;
-  cleanup: CleanupInfo | null;
-}
-
-export function getTask(id: string): TaskResult | null {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) return null;
-
-  const path = getTaskPath(tasksDir, id);
-  const task = readTaskFile(path, tasksDir);
-  if (!task) return null;
-
-  // Auto-clean orphaned references
-  const cleanup = cleanTaskOrphans(task, path, id, tasksDir);
-
-  return {
-    task: enrichTask(task),
-    cleanup: hasCleanup(cleanup) ? cleanup : null,
-  };
-}
-
-export interface ListOptions {
-  status?: Status;
-  priority?: Priority;
-  project?: string;
-  label?: string;
-  assignee?: string;
-  parent?: string;
-  roots?: boolean;
-  overdue?: boolean;
-  limit?: number;
-}
-
-export function listTasks(options?: ListOptions): TaskWithMeta[] {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) return [];
-
-  const allTasks = getAllTasks(tasksDir);
-  // Build status map from all tasks once for efficient blocker lookups during enrichment
-  const statusMap = new Map<string, Status>(allTasks.map((t) => [taskId(t), t.status]));
-
-  let tasks = allTasks;
-
-  // Apply filters declaratively
-  if (options) {
-    const filters: ((t: Task) => boolean)[] = [];
-
-    if (options.status) filters.push((t) => t.status === options.status);
-    if (options.priority !== undefined) filters.push((t) => t.priority === options.priority);
-    if (options.project) filters.push((t) => t.project === options.project);
-    if (options.label) filters.push((t) => t.labels.includes(options.label!));
-    if (options.assignee) filters.push((t) => t.assignees.includes(options.assignee!));
-    if (options.parent) filters.push((t) => t.parent === options.parent);
-    if (options.roots) filters.push((t) => t.parent === null);
-    if (options.overdue) filters.push((t) => isTaskOverdue(t.due_date, t.status));
-
-    if (filters.length > 0) {
-      tasks = tasks.filter((t) => filters.every((f) => f(t)));
-    }
-  }
-
-  tasks.sort(compareTasks);
-
-  if (options?.limit) {
-    tasks = tasks.slice(0, options.limit);
-  }
-
-  return tasks.map((t) => enrichTask(t, statusMap));
-}
-
-export function listReadyTasks(): TaskWithMeta[] {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) return [];
-
-  const allTasks = getAllTasks(tasksDir);
-  const statusMap = new Map<string, Status>(allTasks.map((t) => [taskId(t), t.status]));
-
-  const readyTasks = allTasks
-    .filter((task) => task.status === "active" || task.status === "open")
-    .filter((task) => {
-      for (const blockerId of task.blocked_by) {
-        const blockerStatus = statusMap.get(blockerId);
-        if (blockerStatus && blockerStatus !== "done") return false;
-      }
-      return true;
-    });
-
-  readyTasks.sort(compareTasks);
-
-  return readyTasks.map((t) => enrichTask(t, statusMap));
-}
-
-export function updateTaskStatus(id: string, status: Status): (Task & { id: string }) | null {
-  const tasksDir = getTasksDir();
-  const path = getTaskPath(tasksDir, id);
-  const task = readTaskFile(path, tasksDir);
-  if (!task) return null;
-
-  const now = new Date().toISOString();
-  task.status = status;
-  task.updated_at = now;
-  task.completed_at = status === "done" ? now : null;
-
-  writeTaskFile(path, task);
-  return enrichTask(task);
-}
-
-export interface UpdateTaskOptions {
-  title?: string;
-  description?: string | null;
-  priority?: Priority;
-  labels?: string[];
-  assignees?: string[];
-  parent?: string | null;
-  estimate?: number | null;
-  due_date?: string | null;
-}
-
-export function updateTask(id: string, updates: UpdateTaskOptions): (Task & { id: string }) | null {
-  const tasksDir = getTasksDir();
-  const path = getTaskPath(tasksDir, id);
-  const task = readTaskFile(path, tasksDir);
-  if (!task) return null;
-
-  const now = new Date().toISOString();
-  if (updates.title !== undefined) task.title = updates.title;
-  if (updates.description !== undefined) task.description = updates.description;
-  if (updates.priority !== undefined) task.priority = updates.priority;
-  if (updates.labels !== undefined) task.labels = updates.labels;
-  if (updates.assignees !== undefined) task.assignees = updates.assignees;
-  if (updates.parent !== undefined) task.parent = updates.parent;
-  if (updates.estimate !== undefined) task.estimate = updates.estimate;
-  if (updates.due_date !== undefined) task.due_date = updates.due_date;
-  task.updated_at = now;
-
-  writeTaskFile(path, task);
-  return enrichTask(task);
-}
-
-export function deleteTask(id: string): boolean {
-  const tasksDir = getTasksDir();
-  const path = getTaskPath(tasksDir, id);
-  if (!existsSync(path)) return false;
-
-  unlinkSync(path);
-
-  // Remove this task from all blocked_by arrays and parent references
-  const allTasks = getAllTasks(tasksDir);
-  for (const task of allTasks) {
-    const modified = removeRefsFromTask(task, (ref) => ref === id);
-    if (modified) {
-      atomicWrite(getTaskPath(tasksDir, taskId(task)), JSON.stringify(task, null, 2));
-    }
-  }
-
-  return true;
-}
-
-export interface CleanOptions {
-  olderThanMs?: number;
-  force?: boolean; // ignore age threshold
-}
-
-export function cleanTasks(options: CleanOptions): number {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) return 0;
-
-  const tasks = getAllTasks(tasksDir);
-  // Clamp cutoff to prevent negative values from very large olderThanMs
-  const cutoff = options.olderThanMs ? Math.max(0, Date.now() - options.olderThanMs) : 0;
-
-  const toDelete: string[] = [];
-
-  for (const task of tasks) {
-    if (task.status !== "done") continue;
-
-    if (!options.force && cutoff > 0) {
-      if (!task.completed_at) continue;
-      if (new Date(task.completed_at).getTime() >= cutoff) continue;
-    }
-
-    toDelete.push(taskId(task));
-  }
-
-  for (const id of toDelete) {
-    unlinkSync(getTaskPath(tasksDir, id));
-  }
-
-  // Clean up dangling blocked_by and parent references
-  if (toDelete.length > 0) {
-    const toDeleteSet = new Set(toDelete);
-    const remaining = getAllTasks(tasksDir);
-    for (const task of remaining) {
-      const modified = removeRefsFromTask(task, (id) => toDeleteSet.has(id));
-      if (modified) {
-        atomicWrite(getTaskPath(tasksDir, taskId(task)), JSON.stringify(task, null, 2));
-      }
-    }
-  }
-
-  return toDelete.length;
-}
-
-// --- Log Operations ---
-
-export function addLogEntry(taskIdStr: string, message: string): LogEntry {
-  const tasksDir = getTasksDir();
-  const path = getTaskPath(tasksDir, taskIdStr);
-  const task = readTaskFile(path, tasksDir);
-  if (!task) {
-    throw new Error(`Task not found: ${taskIdStr}`);
-  }
-
-  const now = new Date().toISOString();
-  const entry: LogEntry = {
-    ts: now,
-    msg: message,
-  };
-
-  task.logs.push(entry);
-  task.updated_at = now;
-  atomicWrite(path, JSON.stringify(task, null, 2));
-
-  return entry;
-}
-
-// --- Block Operations ---
-
-export function addBlock(taskIdStr: string, blockedBy: string): { ok: boolean; error?: string } {
-  const tasksDir = ensureTasksDir();
-  const taskPath = getTaskPath(tasksDir, taskIdStr);
-  const blockerPath = getTaskPath(tasksDir, blockedBy);
-
-  const task = readTaskFile(taskPath, tasksDir);
-  if (!task) {
-    return { ok: false, error: `Task not found: ${taskIdStr}` };
-  }
-
-  if (!existsSync(blockerPath)) {
-    return { ok: false, error: `Blocker not found: ${blockedBy}` };
-  }
-
-  if (task.blocked_by.includes(blockedBy)) {
-    return { ok: false, error: "Already blocked by this task" };
-  }
-
-  if (wouldCreateBlockCycle(tasksDir, taskIdStr, blockedBy)) {
-    return { ok: false, error: "Would create circular dependency" };
-  }
-
-  task.blocked_by.push(blockedBy);
-  task.updated_at = new Date().toISOString();
-  atomicWrite(taskPath, JSON.stringify(task, null, 2));
-
-  return { ok: true };
-}
-
-export function removeBlock(taskIdStr: string, blockedBy: string): boolean {
-  const tasksDir = getTasksDir();
-  const taskPath = getTaskPath(tasksDir, taskIdStr);
-  const task = readTaskFile(taskPath, tasksDir);
-  if (!task) return false;
-
-  const idx = task.blocked_by.indexOf(blockedBy);
-  if (idx === -1) return false;
-
-  task.blocked_by.splice(idx, 1);
-  task.updated_at = new Date().toISOString();
-  atomicWrite(taskPath, JSON.stringify(task, null, 2));
-
-  return true;
-}
-
-// --- Utility ---
-
-export function initTasks(project?: string): string {
-  const tasksDir = ensureTasksDir();
-  const config = getConfig();
-
-  // Derive project from directory name if not specified
-  if (project) {
-    config.project = project;
-  } else if (config.project === DEFAULT_CONFIG.project) {
-    // Only auto-derive if still using default "tk"
-    const dirName = basename(getWorkingDir());
-    // Sanitize: lowercase, replace non-alphanumeric with empty, ensure starts with letter
-    const sanitized = dirName.toLowerCase().replace(/[^a-z0-9]/g, "");
-    if (sanitized && /^[a-z]/.test(sanitized)) {
-      config.project = sanitized;
-    }
-  }
-  saveConfig(config);
-  return tasksDir;
-}
-
-// --- ID Resolution ---
-
-/**
- * Resolve a partial ID to a full ID.
- * Matches by prefix - if input matches start of exactly one task ID, returns it.
- * Returns null if no match or ambiguous (multiple matches).
- *
- * Optimized: only reads filenames, not file contents.
- */
-export function resolveId(input: string): string | null {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) return null;
-
-  // Fast path: full valid ID that exists
-  if (parseId(input) && existsSync(getTaskPath(tasksDir, input))) {
-    return input;
-  }
-
-  const matches = findMatchingIds(input);
-  return matches.length === 1 ? (matches[0] ?? null) : null;
-}
-
-export function findMatchingIds(input: string): string[] {
-  const tasksDir = getTasksDir();
-  if (!existsSync(tasksDir)) return [];
-
-  const inputLower = input.toLowerCase();
-  const files = readdirSync(tasksDir);
-  const matches: string[] = [];
-
-  for (const file of files) {
-    if (!file.endsWith(".json") || file === "config.json") continue;
-    const id = file.slice(0, -5);
-    if (!parseId(id)) continue;
-    const ref = id.split("-")[1] ?? "";
-    if (id.startsWith(inputLower) || ref.startsWith(inputLower)) {
-      matches.push(id);
-    }
-  }
-
-  return matches;
-}
-
-// --- Health Check ---
-
-export interface CheckResult {
-  totalTasks: number;
-  cleaned: { task: string; info: CleanupInfo }[];
-  unfixable: { file: string; error: string }[];
-}
-
-/**
- * Run health check on all tasks.
- * Auto-fixes orphaned refs/ID mismatches and reports unfixable issues.
- */
-export function checkTasks(): CheckResult {
-  const tasksDir = getTasksDir();
-  const result: CheckResult = {
-    totalTasks: 0,
-    cleaned: [],
-    unfixable: [],
-  };
-
-  if (!existsSync(tasksDir)) return result;
-
-  const files = readdirSync(tasksDir).filter((f) => f.endsWith(".json") && f !== "config.json");
-
-  for (const file of files) {
-    const expectedId = file.slice(0, -5);
-
-    // Warn about unexpected files (non-task JSON)
-    if (!parseId(expectedId)) {
-      result.unfixable.push({
-        file,
-        error: "Invalid task ID format in filename",
-      });
-      continue;
-    }
-
-    const path = join(tasksDir, file);
-
-    // Try to read and parse
-    let parsed: unknown;
-    try {
-      const text = readFileSync(path, "utf-8");
-      parsed = JSON.parse(text);
-    } catch (e) {
-      // Corrupted JSON - unfixable
-      result.unfixable.push({
-        file,
-        error: e instanceof Error ? e.message : "Invalid JSON",
-      });
-      continue;
-    }
-
-    // Validate task structure
-    if (!isValidTaskStructure(parsed)) {
-      result.unfixable.push({
-        file,
-        error: "Invalid task structure (missing required fields)",
-      });
-      continue;
-    }
-
-    const task = parsed;
-    result.totalTasks++;
-
-    // Auto-clean (same as getTask does)
-    const cleanup = cleanTaskOrphans(task, path, expectedId, tasksDir);
-    if (hasCleanup(cleanup)) {
-      result.cleaned.push({ task: expectedId, info: cleanup });
-    }
-  }
-
-  return result;
-}