@opentask/taskin-task-manager 1.0.6

package/eslint.config.js

@@ -0,0 +1,8 @@
+import tsConfig from '../../eslint/typescript.js';
+
+export default [
+  ...tsConfig,
+  {
+    ignores: ['vitest.config.ts', '*.config.js', '*.config.ts', 'dist/**'],
+  },
+];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@opentask/taskin-task-manager",
+  "version": "1.0.6",
+  "description": "Task lifecycle management for Taskin",
+  "type": "module",
+  "motivation": "To manage the lifecycle of tasks, including creation, status updates, and retrieval.",
+  "solve": "Provides a structured API for interacting with task data, abstracting the underlying storage mechanism.",
+  "scope": "core",
+  "status": "active",
+  "since": "2025-11-05",
+  "keywords": [
+    "taskin",
+    "task-manager",
+    "task-management",
+    "lifecycle"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sidartaveloso/taskin.git",
+    "directory": "packages/task-manager"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@opentask/taskin-types": "1.0.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist coverage .turbo",
+    "dev": "tsc --watch",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './task-manager';
+export * from './task-manager.types';
+
+// Re-export commonly used types from @opentask/taskin-types for convenience
+export type { Task, TaskStatus, TaskType, User } from '@opentask/taskin-types';

package/src/metrics.types.ts

@@ -0,0 +1,96 @@
+import type {
+  StatsQuery,
+  TaskStats,
+  TeamStats,
+  UserStats,
+} from '@opentask/taskin-types';
+
+/**
+ * Manages metrics and statistics for users, teams, and tasks.
+ * Aggregates data from Git history and task files to provide productivity insights.
+ *
+ * @remarks
+ * This interface separates analytics/reporting responsibilities from ITaskProvider,
+ * following the Single Responsibility Principle.
+ *
+ * @example
+ * ```ts
+ * const metrics = new FileSystemMetricsAdapter(tasksDir, userRegistry, gitAnalyzer);
+ * const stats = await metrics.getUserMetrics('john-doe', { period: 'week' });
+ * console.log(`Commits: ${stats.codeMetrics.commits}`);
+ * ```
+ *
+ * @public
+ */
+export interface IMetricsManager {
+  /**
+   * Get productivity metrics for a specific user.
+   *
+   * Includes code metrics (commits, lines of code), temporal patterns
+   * (day of week, time of day), and engagement statistics (completion rate, streaks).
+   *
+   * @param userId - User identifier (username or registry ID)
+   * @param query - Optional query parameters to filter results
+   * @param query.period - Time period to analyze ('day' | 'week' | 'month' | 'year')
+   * @returns Promise resolving to user statistics
+   *
+   * @example
+   * ```ts
+   * const stats = await metrics.getUserMetrics('alice', { period: 'month' });
+   * console.log(`Tasks completed: ${stats.contributionMetrics.tasksCompleted}`);
+   * console.log(`Completion rate: ${(stats.engagementMetrics.completionRate * 100).toFixed(1)}%`);
+   * ```
+   */
+  getUserMetrics(userId: string, query?: StatsQuery): Promise<UserStats>;
+
+  /**
+   * Get aggregated metrics for an entire team.
+   *
+   * Provides overview of team productivity with breakdown by individual contributors.
+   * Useful for team retrospectives, capacity planning, and identifying top contributors.
+   *
+   * @param teamId - Team identifier
+   * @param query - Optional query parameters to filter results
+   * @returns Promise resolving to team statistics with per-contributor breakdown
+   *
+   * @example
+   * ```ts
+   * const stats = await metrics.getTeamMetrics('frontend', { period: 'week' });
+   * console.log(`Total commits: ${stats.totalCommits}`);
+   * console.log(`Contributors: ${stats.totalContributors}`);
+   * stats.contributors.forEach(c => {
+   *   console.log(`${c.username}: ${c.commits} commits, ${c.tasksCompleted} tasks`);
+   * });
+   * ```
+   */
+  getTeamMetrics(teamId: string, query?: StatsQuery): Promise<TeamStats>;
+
+  /**
+   * Get detailed metrics for a specific task.
+   *
+   * Includes timeline analysis, contributor activity, code impact metrics,
+   * and work patterns. Useful for task retrospectives and understanding
+   * effort distribution.
+   *
+   * @param taskId - Task identifier (task number like '015' or full ID like 'task-015')
+   * @param query - Optional query parameters
+   * @returns Promise resolving to task-specific statistics
+   *
+   * @example
+   * ```ts
+   * const stats = await metrics.getTaskMetrics('task-015', {});
+   * console.log(`Duration: ${stats.duration} days`);
+   * console.log(`Contributors: ${stats.contributors.map(c => c.name).join(', ')}`);
+   * if (stats.refactoringMetrics) {
+   *   console.log(`Simplification ratio: ${stats.refactoringMetrics.simplificationRatio.toFixed(2)}x`);
+   * }
+   * ```
+   */
+  getTaskMetrics(taskId: string, query?: StatsQuery): Promise<TaskStats>;
+}
+
+export type {
+  TaskStats as TaskMetrics,
+  TeamStats as TeamMetrics,
+  UserStats as UserMetrics,
+};

package/src/provider-stats.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+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,
+    };
+
+    expect(typeof metrics.getUserMetrics).toBe('function');
+    expect(typeof metrics.getTeamMetrics).toBe('function');
+    expect(typeof metrics.getTaskMetrics).toBe('function');
+
+    await expect(metrics.getUserMetrics('u1')).resolves.toBeDefined();
+    await expect(metrics.getTeamMetrics('t1')).resolves.toBeDefined();
+    await expect(metrics.getTaskMetrics('task1')).resolves.toBeDefined();
+  });
+});

package/src/task-manager.mock.ts

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

package/src/task-manager.test.ts

@@ -0,0 +1,133 @@
+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';
+
+describe('TaskManager', () => {
+  let taskManager: TaskManager;
+  let mockTaskProvider: ITaskProvider;
+  let mockTask: TaskFile;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockTaskProvider = createMockTaskProvider();
+    mockTask = createMockTask();
+    taskManager = new TaskManager(mockTaskProvider);
+  });
+
+  describe('startTask', () => {
+    it('should start a pending task', async () => {
+      (mockTaskProvider.findTask as Mock).mockResolvedValue(mockTask);
+
+      const updatedTask = await taskManager.startTask('task-001');
+
+      expect(mockTaskProvider.findTask).toHaveBeenCalledWith('task-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.",
+      );
+    });
+
+    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.",
+      );
+    });
+  });
+
+  describe('finishTask', () => {
+    it('should finish an in-progress task', async () => {
+      const inProgressTask = { ...mockTask, status: 'in-progress' as const };
+      (mockTaskProvider.findTask as Mock).mockResolvedValue(inProgressTask);
+
+      const updatedTask = await taskManager.finishTask('task-001');
+
+      expect(mockTaskProvider.updateTask).toHaveBeenCalledWith(
+        expect.objectContaining({ status: 'done' }),
+      );
+      expect(updatedTask.status).toBe('done');
+    });
+  });
+
+  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',
+      };
+
+      (mockTaskProvider.createTask as Mock).mockResolvedValue(createResult);
+
+      const result = await taskManager.createTask(createOptions);
+
+      expect(mockTaskProvider.createTask).toHaveBeenCalledWith(createOptions);
+      expect(result).toEqual(createResult);
+    });
+
+    it('should pass through description and assignee to provider', async () => {
+      const createOptions = {
+        title: 'New Task',
+        type: 'fix' as const,
+        description: 'Fix something',
+        assignee: 'john-doe',
+      };
+      const createResult = {
+        task: mockTask,
+        taskId: '002',
+        filePath: '/tasks/task-002.md',
+      };
+
+      (mockTaskProvider.createTask as Mock).mockResolvedValue(createResult);
+
+      const result = await taskManager.createTask(createOptions);
+
+      expect(mockTaskProvider.createTask).toHaveBeenCalledWith(createOptions);
+      expect(result.taskId).toBe('002');
+    });
+  });
+
+  describe('lint', () => {
+    it('should delegate lint without fix to provider', async () => {
+      const lintResult = { errors: 0, warnings: 2, details: [] };
+      (mockTaskProvider.lint as Mock).mockResolvedValue(lintResult);
+
+      const result = await taskManager.lint();
+
+      expect(mockTaskProvider.lint).toHaveBeenCalledWith(undefined);
+      expect(result).toEqual(lintResult);
+    });
+
+    it('should delegate lint with fix=true to provider', async () => {
+      const lintResult = { errors: 0, warnings: 0, details: [] };
+      (mockTaskProvider.lint as Mock).mockResolvedValue(lintResult);
+
+      const result = await taskManager.lint(true);
+
+      expect(mockTaskProvider.lint).toHaveBeenCalledWith(true);
+      expect(result).toEqual(lintResult);
+    });
+
+    it('should delegate lint with fix=false to provider', async () => {
+      const lintResult = { errors: 1, warnings: 2, details: [] };
+      (mockTaskProvider.lint as Mock).mockResolvedValue(lintResult);
+
+      const result = await taskManager.lint(false);
+
+      expect(mockTaskProvider.lint).toHaveBeenCalledWith(false);
+      expect(result).toEqual(lintResult);
+    });
+  });
+});

package/src/task-manager.ts

@@ -0,0 +1,54 @@
+import type {
+  CreateTaskOptions,
+  CreateTaskResult,
+  ITaskManager,
+  ITaskProvider,
+  LintResult,
+  TaskFile,
+} from './task-manager.types';
+
+export class TaskManager implements ITaskManager {
+  constructor(private taskProvider: ITaskProvider) {}
+
+  async startTask(taskId: string): Promise<TaskFile> {
+    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}' is already in progress.`);
+    }
+
+    if (task.status === 'done') {
+      throw new Error(`Task '${taskId}' is already done.`);
+    }
+
+    const updatedTask: TaskFile = { ...task, status: 'in-progress' };
+    await this.taskProvider.updateTask(updatedTask);
+
+    return updatedTask;
+  }
+
+  async finishTask(taskId: string): Promise<TaskFile> {
+    const task = await this.taskProvider.findTask(taskId);
+
+    if (!task) {
+      throw new Error(`Task with ID '${taskId}' not found.`);
+    }
+
+    const updatedTask: TaskFile = { ...task, status: 'done' };
+    await this.taskProvider.updateTask(updatedTask);
+
+    return updatedTask;
+  }
+
+  async createTask(options: CreateTaskOptions): Promise<CreateTaskResult> {
+    return this.taskProvider.createTask(options);
+  }
+
+  async lint(fix?: boolean): Promise<LintResult> {
+    return this.taskProvider.lint(fix);
+  }
+}

package/src/task-manager.types.ts

@@ -0,0 +1,167 @@
+import type { Task, TaskType, User } from '@opentask/taskin-types';
+
+/**
+ * Options for creating a new task
+ * @public
+ */
+export interface CreateTaskOptions {
+  /** Task title */
+  title: string;
+  /** Task type (feat, fix, chore, etc.) */
+  type: TaskType;
+  /** Optional task description */
+  description?: string;
+  /** Optional assignee user ID or name */
+  assignee?: string;
+}
+
+/**
+ * Result of creating a new task
+ * @public
+ */
+export interface CreateTaskResult {
+  /** The created task */
+  task: TaskFile;
+  /** The generated task ID */
+  taskId: string;
+  /** The file path where the task was created */
+  filePath: string;
+}
+
+/**
+ * Severity level for validation issues
+ * @public
+ */
+export type ValidationSeverity = 'error' | 'warning' | 'info';
+
+/**
+ * A validation error or warning found during linting
+ * @public
+ */
+export interface ValidationIssue {
+  /** The file or task that has the issue */
+  file: string;
+  /** Optional line number where the issue occurs */
+  line?: number;
+  /** Human-readable description of the issue */
+  message: string;
+  /** Severity level of the issue */
+  severity: ValidationSeverity;
+  /** Optional suggestion for fixing the issue */
+  suggestion?: string;
+}
+
+/**
+ * Result of a lint operation
+ * @public
+ */
+export interface LintResult {
+  /** Whether the lint passed without errors */
+  valid: boolean;
+  /** List of validation issues found */
+  issues: ValidationIssue[];
+  /** Number of errors found */
+  errorCount: number;
+  /** Number of warnings found */
+  warningCount: number;
+  /** Number of info messages */
+  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).
+ * @public
+ */
+export interface ITaskProvider {
+  /**
+   * 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>;
+
+  /**
+   * Retrieve all tasks from the provider.
+   * @returns Array of all tasks
+   */
+  getAllTasks(): Promise<TaskFile[]>;
+
+  /**
+   * Update an existing task.
+   * @param task - The task with updated information
+   */
+  updateTask(task: TaskFile): Promise<void>;
+
+  /**
+   * Create a new task.
+   * @param options - Options for creating the task
+   * @returns The created task information
+   */
+  createTask(options: CreateTaskOptions): Promise<CreateTaskResult>;
+
+  /**
+   * Validate all tasks managed by this provider.
+   * Each provider knows its own format and validation rules.
+   * @param fix - If true, attempt to automatically fix validation issues
+   * @returns The lint result with any validation issues found
+   */
+  lint(fix?: boolean): Promise<LintResult>;
+}
+
+/**
+ * Interface for task management operations.
+ * Provides high-level methods for managing task workflow and state transitions.
+ * @public
+ */
+export interface ITaskManager {
+  /**
+   * Mark a task as finished.
+   * Transitions the task to 'done' status.
+   * @param taskId - The unique identifier of the task
+   * @returns The updated task
+   * @throws Error if task is not found
+   */
+  finishTask(taskId: string): Promise<TaskFile>;
+
+  /**
+   * Start working on a task.
+   * Transitions the task to 'in-progress' status.
+   * @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>;
+
+  /**
+   * Create a new task.
+   * @param options - Options for creating the task
+   * @returns The created task information
+   */
+  createTask(options: CreateTaskOptions): Promise<CreateTaskResult>;
+
+  /**
+   * Validate all tasks in the system.
+   * Delegates to the underlying provider's lint implementation.
+   * @param fix - If true, attempt to automatically fix validation issues
+   * @returns The lint result with any validation issues found
+   */
+  lint(fix?: boolean): Promise<LintResult>;
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "module": "ESNext",
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*"],
+  "references": [{ "path": "../types-ts" }]
+}