@opentask/taskin-task-manager 2.0.1 → 3.0.0

package/src/metrics.types.ts

@@ -1,9 +1,4 @@
-import type {
-  StatsQuery,
-  TaskStats,
-  TeamStats,
-  UserStats,
-} from '@opentask/taskin-types';
+import type { StatsQuery, TaskStats, TeamStats, UserStats } from '@opentask/taskin-types';
 
 /**
  * Manages metrics and statistics for users, teams, and tasks.
@@ -89,8 +84,4 @@ export interface IMetricsManager {
   getTaskMetrics(taskId: string, query?: StatsQuery): Promise<TaskStats>;
 }
 
-export type {
-  TaskStats as TaskMetrics,
-  TeamStats as TeamMetrics,
-  UserStats as UserMetrics,
-};
+export type { TaskStats as TaskMetrics, TeamStats as TeamMetrics, UserStats as UserMetrics };

package/src/provider-stats.test.ts

@@ -4,9 +4,12 @@ import type { IMetricsManager } from './metrics.types';
 describe('IMetricsManager contract', () => {
   it('accepts an object implementing IMetricsManager', async () => {
     const metrics: IMetricsManager = {
-      getUserMetrics: async (userId: string) => ({ userId }) as any,
-      getTeamMetrics: async (teamId: string) => ({ teamId }) as any,
-      getTaskMetrics: async (taskId: string) => ({ taskId }) as any,
+      getUserMetrics: async (userId: string) =>
+        ({ userId }) as unknown as Awaited<ReturnType<IMetricsManager['getUserMetrics']>>,
+      getTeamMetrics: async (teamId: string) =>
+        ({ teamId }) as unknown as Awaited<ReturnType<IMetricsManager['getTeamMetrics']>>,
+      getTaskMetrics: async (taskId: string) =>
+        ({ taskId }) as unknown as Awaited<ReturnType<IMetricsManager['getTaskMetrics']>>,
     };
 
     expect(typeof metrics.getUserMetrics).toBe('function');

package/src/task-manager.mock.ts

@@ -1,13 +1,11 @@
-import type { TaskId } from '@opentask/taskin-types';
+import { parseTaskId, type Task } from '@opentask/taskin-types';
 import { vi } from 'vitest';
-import type { ITaskProvider, TaskFile } from './task-manager.types';
+import type { ITaskProvider } from './task-manager.types';
 
-export const createMockTask = (overrides?: Partial<TaskFile>): TaskFile => ({
-  content: '# Task 001 - Implement feature',
+export const createMockTask = (overrides?: Partial<Task>): Task => ({
   createdAt: new Date().toISOString(),
   description: 'A test feature',
-  filePath: '/tasks/task-001.md',
-  id: 'task-001' satisfies string as TaskId,
+  id: parseTaskId('001'),
   status: 'pending',
   title: 'Implement feature',
   type: 'feat',

package/src/task-manager.test.ts

@@ -1,13 +1,14 @@
+import { parseTaskId, type Task } from '@opentask/taskin-types';
 import type { Mock } from 'vitest';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { TaskManager } from './task-manager';
 import { createMockTask, createMockTaskProvider } from './task-manager.mock';
-import type { ITaskProvider, TaskFile } from './task-manager.types';
+import type { ITaskProvider } from './task-manager.types';
 
 describe('TaskManager', () => {
   let taskManager: TaskManager;
   let mockTaskProvider: ITaskProvider;
-  let mockTask: TaskFile;
+  let mockTask: Task;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -20,30 +21,58 @@ describe('TaskManager', () => {
     it('should start a pending task', async () => {
       (mockTaskProvider.findTask as Mock).mockResolvedValue(mockTask);
 
-      const updatedTask = await taskManager.startTask('task-001');
+      const updatedTask = await taskManager.startTask(parseTaskId('001'));
 
-      expect(mockTaskProvider.findTask).toHaveBeenCalledWith('task-001');
-      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(
-        expect.objectContaining({ status: 'in-progress' }),
-      );
+      expect(mockTaskProvider.findTask).toHaveBeenCalledWith('001');
+      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(expect.objectContaining({ status: 'in-progress' }));
       expect(updatedTask.status).toBe('in-progress');
     });
 
     it('should throw an error if task is not found', async () => {
       (mockTaskProvider.findTask as Mock).mockResolvedValue(undefined);
-      await expect(taskManager.startTask('not-found')).rejects.toThrow(
-        "Task with ID 'not-found' not found.",
-      );
+      await expect(taskManager.startTask(parseTaskId('999'))).rejects.toThrow("Task with ID '999' not found.");
     });
 
     it('should throw an error if task is already in progress', async () => {
       const inProgressTask = { ...mockTask, status: 'in-progress' as const };
       (mockTaskProvider.findTask as Mock).mockResolvedValue(inProgressTask);
 
-      await expect(taskManager.startTask('task-001')).rejects.toThrow(
-        "Task 'task-001' is already in progress.",
+      await expect(taskManager.startTask(parseTaskId('001'))).rejects.toThrow("Task '001' is already in progress.");
+    });
+  });
+
+  describe('pauseTask', () => {
+    it('should pause an in-progress task', async () => {
+      const inProgressTask = { ...mockTask, status: 'in-progress' as const };
+      (mockTaskProvider.findTask as Mock).mockResolvedValue(inProgressTask);
+
+      const updatedTask = await taskManager.pauseTask(parseTaskId('001'));
+
+      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(expect.objectContaining({ status: 'paused' }));
+      expect(updatedTask.status).toBe('paused');
+    });
+
+    it('should throw an error if task is not found', async () => {
+      (mockTaskProvider.findTask as Mock).mockResolvedValue(undefined);
+
+      await expect(taskManager.pauseTask(parseTaskId('999'))).rejects.toThrow("Task with ID '999' not found.");
+    });
+
+    it('should throw an error if task is not in-progress', async () => {
+      (mockTaskProvider.findTask as Mock).mockResolvedValue({ ...mockTask, status: 'pending' as const });
+
+      await expect(taskManager.pauseTask(parseTaskId('001'))).rejects.toThrow(
+        "Task '001' must be in 'in-progress' status to be paused",
       );
     });
+
+    it('should let startTask resume a paused task', async () => {
+      (mockTaskProvider.findTask as Mock).mockResolvedValue({ ...mockTask, status: 'paused' as const });
+
+      const updatedTask = await taskManager.startTask(parseTaskId('001'));
+
+      expect(updatedTask.status).toBe('in-progress');
+    });
   });
 
   describe('finishTask', () => {
@@ -51,11 +80,9 @@ describe('TaskManager', () => {
       const inProgressTask = { ...mockTask, status: 'in-progress' as const };
       (mockTaskProvider.findTask as Mock).mockResolvedValue(inProgressTask);
 
-      const updatedTask = await taskManager.finishTask('task-001');
+      const updatedTask = await taskManager.finishTask(parseTaskId('001'));
 
-      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(
-        expect.objectContaining({ status: 'done' }),
-      );
+      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(expect.objectContaining({ status: 'done' }));
       expect(updatedTask.status).toBe('done');
     });
   });
@@ -65,29 +92,25 @@ describe('TaskManager', () => {
       const inProgressTask = { ...mockTask, status: 'in-progress' as const };
       (mockTaskProvider.findTask as Mock).mockResolvedValue(inProgressTask);
 
-      const updatedTask = await taskManager.reviewTask('task-001');
+      const updatedTask = await taskManager.reviewTask(parseTaskId('001'));
 
-      expect(mockTaskProvider.findTask).toHaveBeenCalledWith('task-001');
-      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(
-        expect.objectContaining({ status: 'in-review' }),
-      );
+      expect(mockTaskProvider.findTask).toHaveBeenCalledWith('001');
+      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(expect.objectContaining({ status: 'in-review' }));
       expect(updatedTask.status).toBe('in-review');
     });
 
     it('should throw an error if task is not found', async () => {
       (mockTaskProvider.findTask as Mock).mockResolvedValue(undefined);
 
-      await expect(taskManager.reviewTask('not-found')).rejects.toThrow(
-        "Task with ID 'not-found' not found.",
-      );
+      await expect(taskManager.reviewTask(parseTaskId('999'))).rejects.toThrow("Task with ID '999' not found.");
     });
 
     it('should throw an error if task is not in-progress', async () => {
       const pendingTask = { ...mockTask, status: 'pending' as const };
       (mockTaskProvider.findTask as Mock).mockResolvedValue(pendingTask);
 
-      await expect(taskManager.reviewTask('task-001')).rejects.toThrow(
-        "Task 'task-001' must be in 'in-progress' status to be reviewed",
+      await expect(taskManager.reviewTask(parseTaskId('001'))).rejects.toThrow(
+        "Task '001' must be in 'in-progress' status to be reviewed",
       );
     });
 
@@ -95,8 +118,8 @@ describe('TaskManager', () => {
       const doneTask = { ...mockTask, status: 'done' as const };
       (mockTaskProvider.findTask as Mock).mockResolvedValue(doneTask);
 
-      await expect(taskManager.reviewTask('task-001')).rejects.toThrow(
-        "Task 'task-001' must be in 'in-progress' status to be reviewed",
+      await expect(taskManager.reviewTask(parseTaskId('001'))).rejects.toThrow(
+        "Task '001' must be in 'in-progress' status to be reviewed",
       );
     });
 
@@ -104,18 +127,42 @@ describe('TaskManager', () => {
       const reviewTask = { ...mockTask, status: 'in-review' as const };
       (mockTaskProvider.findTask as Mock).mockResolvedValue(reviewTask);
 
-      await expect(taskManager.reviewTask('task-001')).rejects.toThrow(
-        "Task 'task-001' must be in 'in-progress' status to be reviewed",
+      await expect(taskManager.reviewTask(parseTaskId('001'))).rejects.toThrow(
+        "Task '001' must be in 'in-progress' status to be reviewed",
       );
     });
   });
 
+  describe('provider-specific fields', () => {
+    // The manager is generic over the provider's task shape, so extra fields a
+    // provider carries (filePath/content for the file system, an issue number
+    // for a tracker) must survive a status transition untouched.
+    type ProviderTask = Task & { filePath: string; content: string };
+
+    it('should preserve provider fields through a transition', async () => {
+      const providerTask: ProviderTask = {
+        ...createMockTask(),
+        filePath: '/tasks/task-001.md',
+        content: '# Task 001',
+      };
+      const provider = createMockTaskProvider() as unknown as ITaskProvider<ProviderTask>;
+      (provider.findTask as Mock).mockResolvedValue(providerTask);
+
+      const manager = new TaskManager(provider);
+      const updated = await manager.startTask(parseTaskId('001'));
+
+      expect(updated.filePath).toBe('/tasks/task-001.md');
+      expect(updated.content).toBe('# Task 001');
+      expect(updated.status).toBe('in-progress');
+      expect(provider.updateTask).toHaveBeenCalledWith(expect.objectContaining({ filePath: '/tasks/task-001.md' }));
+    });
+  });
+
   describe('createTask', () => {
     it('should delegate task creation to provider', async () => {
       const createOptions = { title: 'New Task', type: 'feat' as const };
       const createResult = {
         task: mockTask,
-        taskId: '001',
         filePath: '/tasks/task-001.md',
       };
 
@@ -134,9 +181,11 @@ describe('TaskManager', () => {
         description: 'Fix something',
         assignee: 'john-doe',
       };
+      // Antes o assert batia no campo `taskId` do result, que dizia '002'
+      // enquanto o `task` dizia outro id. Com um campo so, o teste tem que
+      // devolver a task que ele afirma ter criado.
       const createResult = {
-        task: mockTask,
-        taskId: '002',
+        task: createMockTask({ id: parseTaskId('002') }),
         filePath: '/tasks/task-002.md',
       };
 
@@ -145,7 +194,7 @@ describe('TaskManager', () => {
       const result = await taskManager.createTask(createOptions);
 
       expect(mockTaskProvider.createTask).toHaveBeenCalledWith(createOptions);
-      expect(result.taskId).toBe('002');
+      expect(result.task.id).toBe('002');
     });
   });
 

package/src/task-manager.ts

@@ -1,16 +1,33 @@
+import type { Task, TaskId, TaskStatus } from '@opentask/taskin-types';
 import type {
   CreateTaskOptions,
   CreateTaskResult,
   ITaskManager,
   ITaskProvider,
   LintResult,
-  TaskFile,
 } from './task-manager.types';
 
-export class TaskManager implements ITaskManager {
-  constructor(private taskProvider: ITaskProvider) {}
+/**
+ * Orchestrates task state transitions on top of any {@link ITaskProvider}.
+ *
+ * `TTask` is inferred from the provider passed to the constructor, so callers
+ * get their provider's task shape back without this class ever naming it.
+ */
+export class TaskManager<TTask extends Task = Task> implements ITaskManager<TTask> {
+  constructor(private taskProvider: ITaskProvider<TTask>) {}
+
+  /**
+   * Returns a copy of `task` with a new status.
+   *
+   * TypeScript cannot prove that spreading a generic yields that same generic,
+   * so the assertion is required. It is sound here: `status` is a known key of
+   * `Task`, and every other field is carried over untouched.
+   */
+  private withStatus(task: TTask, status: TaskStatus): TTask {
+    return { ...task, status } as TTask;
+  }
 
-  async startTask(taskId: string): Promise<TaskFile> {
+  async startTask(taskId: TaskId): Promise<TTask> {
     const task = await this.taskProvider.findTask(taskId);
 
     if (!task) {
@@ -25,26 +42,43 @@ export class TaskManager implements ITaskManager {
       throw new Error(`Task '${taskId}' is already done.`);
     }
 
-    const updatedTask: TaskFile = { ...task, status: 'in-progress' };
+    const updatedTask = this.withStatus(task, 'in-progress');
+    await this.taskProvider.updateTask(updatedTask);
+
+    return updatedTask;
+  }
+
+  async pauseTask(taskId: TaskId): Promise<TTask> {
+    const task = await this.taskProvider.findTask(taskId);
+
+    if (!task) {
+      throw new Error(`Task with ID '${taskId}' not found.`);
+    }
+
+    if (task.status !== 'in-progress') {
+      throw new Error(`Task '${taskId}' must be in 'in-progress' status to be paused. Current status: ${task.status}`);
+    }
+
+    const updatedTask = this.withStatus(task, 'paused');
     await this.taskProvider.updateTask(updatedTask);
 
     return updatedTask;
   }
 
-  async finishTask(taskId: string): Promise<TaskFile> {
+  async finishTask(taskId: TaskId): Promise<TTask> {
     const task = await this.taskProvider.findTask(taskId);
 
     if (!task) {
       throw new Error(`Task with ID '${taskId}' not found.`);
     }
 
-    const updatedTask: TaskFile = { ...task, status: 'done' };
+    const updatedTask = this.withStatus(task, 'done');
     await this.taskProvider.updateTask(updatedTask);
 
     return updatedTask;
   }
 
-  async reviewTask(taskId: string): Promise<TaskFile> {
+  async reviewTask(taskId: TaskId): Promise<TTask> {
     const task = await this.taskProvider.findTask(taskId);
 
     if (!task) {
@@ -57,13 +91,13 @@ export class TaskManager implements ITaskManager {
       );
     }
 
-    const updatedTask: TaskFile = { ...task, status: 'in-review' };
+    const updatedTask = this.withStatus(task, 'in-review');
     await this.taskProvider.updateTask(updatedTask);
 
     return updatedTask;
   }
 
-  async createTask(options: CreateTaskOptions): Promise<CreateTaskResult> {
+  async createTask(options: CreateTaskOptions): Promise<CreateTaskResult<TTask>> {
     return this.taskProvider.createTask(options);
   }
 

package/src/task-manager.types.ts

@@ -1,4 +1,4 @@
-import type { Task, TaskType, User } from '@opentask/taskin-types';
+import type { Task, TaskId, TaskType } from '@opentask/taskin-types';
 
 /**
  * Options for creating a new task
@@ -16,16 +16,18 @@ export interface CreateTaskOptions {
 }
 
 /**
- * Result of creating a new task
+ * Result of creating a new task.
+ *
+ * Providers are free to return a wider object (e.g. the file system provider
+ * adds `filePath`); returning extra fields is allowed because the result is
+ * only ever consumed through this contract.
+ *
+ * @typeParam TTask - The task shape produced by the provider
  * @public
  */
-export interface CreateTaskResult {
+export interface CreateTaskResult<TTask extends Task = Task> {
   /** The created task */
-  task: TaskFile;
-  /** The generated task ID */
-  taskId: string;
-  /** The file path where the task was created */
-  filePath: string;
+  task: TTask;
 }
 
 /**
@@ -68,60 +70,58 @@ export interface LintResult {
   infoCount: number;
 }
 
-/**
- * A task with additional file system metadata.
- * Extends the base Task type with content and path information.
- * @public
- */
-export type TaskFile = Task & {
-  /** The raw markdown content of the task file */
-  content: string;
-  /** Absolute or relative path to the task file */
-  filePath: string;
-  /** The type of work this task represents */
-  type: TaskType;
-  /** Optional user assigned to this task */
-  assignee?: User;
-};
-
 /**
  * Interface for task storage providers.
  * Implementations handle reading and writing tasks from different sources
- * (e.g., file system, database, API).
+ * (e.g., file system, GitHub issues, Redmine).
+ *
+ * The task shape is a type parameter so that a provider can enrich `Task` with
+ * whatever its backing store requires — the file system provider carries
+ * `content`/`filePath`, a Redmine provider would carry its own fields — without
+ * that shape leaking into this package. Consumers that do not care about the
+ * extra fields can simply use the default and work with plain `Task`.
+ *
+ * @typeParam TTask - The task shape this provider reads and writes
  * @public
  */
-export interface ITaskProvider {
+/*
+ * Os membros sao propriedades de funcao, nao metodos, de proposito: TypeScript
+ * trata metodos como bivariantes mesmo com `strictFunctionTypes`, e isso
+ * deixava `ITaskProvider<TaskFile>` ser atribuido a `ITaskProvider<Task>` — o
+ * que compila e depois quebra em `updateTask`, que le `task.filePath`.
+ */
+export interface ITaskProvider<TTask extends Task = Task> {
   /**
    * Initialize the provider, performing any necessary setup or loading.
    * This may involve reading existing tasks, setting up connections, etc.
    */
-  initialize(): Promise<void>;
+  initialize: () => Promise<void>;
 
   /**
    * Find a specific task by its ID.
    * @param taskId - The unique identifier of the task
    * @returns The task if found, undefined otherwise
    */
-  findTask(taskId: string): Promise<TaskFile | undefined>;
+  findTask: (taskId: TaskId) => Promise<TTask | undefined>;
 
   /**
    * Retrieve all tasks from the provider.
    * @returns Array of all tasks
    */
-  getAllTasks(): Promise<TaskFile[]>;
+  getAllTasks: () => Promise<TTask[]>;
 
   /**
    * Update an existing task.
    * @param task - The task with updated information
    */
-  updateTask(task: TaskFile): Promise<void>;
+  updateTask: (task: TTask) => Promise<void>;
 
   /**
    * Create a new task.
    * @param options - Options for creating the task
    * @returns The created task information
    */
-  createTask(options: CreateTaskOptions): Promise<CreateTaskResult>;
+  createTask: (options: CreateTaskOptions) => Promise<CreateTaskResult<TTask>>;
 
   /**
    * Validate all tasks managed by this provider.
@@ -129,15 +129,22 @@ export interface ITaskProvider {
    * @param fix - If true, attempt to automatically fix validation issues
    * @returns The lint result with any validation issues found
    */
-  lint(fix?: boolean): Promise<LintResult>;
+  lint: (fix?: boolean) => Promise<LintResult>;
 }
 
 /**
  * Interface for task management operations.
  * Provides high-level methods for managing task workflow and state transitions.
+ *
+ * Mirrors the provider's task shape: a manager built on top of the file system
+ * provider hands back the provider's richer task, while a manager built on any
+ * other provider hands back that provider's shape. This package never needs to
+ * know which one it is.
+ *
+ * @typeParam TTask - The task shape produced by the underlying provider
  * @public
  */
-export interface ITaskManager {
+export interface ITaskManager<TTask extends Task = Task> {
   /**
    * Mark a task as finished.
    * Transitions the task to 'done' status.
@@ -145,7 +152,7 @@ export interface ITaskManager {
    * @returns The updated task
    * @throws Error if task is not found
    */
-  finishTask(taskId: string): Promise<TaskFile>;
+  finishTask: (taskId: TaskId) => Promise<TTask>;
 
   /**
    * Mark a task as ready for review.
@@ -154,23 +161,34 @@ export interface ITaskManager {
    * @returns The updated task
    * @throws Error if task is not found or not in 'in-progress' status
    */
-  reviewTask(taskId: string): Promise<TaskFile>;
+  reviewTask: (taskId: TaskId) => Promise<TTask>;
 
   /**
    * Start working on a task.
    * Transitions the task to 'in-progress' status.
+   * Also used to resume a paused task.
    * @param taskId - The unique identifier of the task
    * @returns The updated task
    * @throws Error if task is not found, already in progress, or already done
    */
-  startTask(taskId: string): Promise<TaskFile>;
+  startTask: (taskId: TaskId) => Promise<TTask>;
+
+  /**
+   * Pause work on a task.
+   * Transitions the task from 'in-progress' to 'paused' status.
+   * Resume with {@link ITaskManager.startTask}.
+   * @param taskId - The unique identifier of the task
+   * @returns The updated task
+   * @throws Error if task is not found or not in 'in-progress' status
+   */
+  pauseTask: (taskId: TaskId) => Promise<TTask>;
 
   /**
    * Create a new task.
    * @param options - Options for creating the task
    * @returns The created task information
    */
-  createTask(options: CreateTaskOptions): Promise<CreateTaskResult>;
+  createTask: (options: CreateTaskOptions) => Promise<CreateTaskResult<TTask>>;
 
   /**
    * Validate all tasks in the system.
@@ -178,5 +196,5 @@ export interface ITaskManager {
    * @param fix - If true, attempt to automatically fix validation issues
    * @returns The lint result with any validation issues found
    */
-  lint(fix?: boolean): Promise<LintResult>;
+  lint: (fix?: boolean) => Promise<LintResult>;
 }