taskin 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -20,21 +20,57 @@ Taskin is a command-line tool that helps you manage tasks directly from your ter
 ## 🚀 Installation
 
 \`\`\`bash
+
 # Using npx (recommended - no installation needed!)
+
 npx taskin init
 
 # Or install globally
+
 npm install -g taskin
 
 # Or with pnpm
+
 pnpm add -g taskin
 
 # Or with yarn
+
 yarn global add taskin
 \`\`\`
 
 > **Note:** This is a beta version. Please report any issues on [GitHub](https://github.com/opentask-app/taskin/issues).
 
+## 📦 Available Packages
+
+Taskin is built as a modular ecosystem. Besides the CLI, you can use individual packages:
+
+### Core Packages
+
+| Package                           | Description                      | npm                                                                                     |
+| --------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
+| **taskin**                        | Complete CLI + programmatic API  | [![npm](https://img.shields.io/npm/v/taskin.svg)](https://www.npmjs.com/package/taskin) |
+| **@opentask/taskin-types**        | TypeScript types and Zod schemas | Coming soon                                                                             |
+| **@opentask/taskin-core**         | Core task management logic       | Coming soon                                                                             |
+| **@opentask/taskin-task-manager** | Task lifecycle orchestration     | Coming soon                                                                             |
+
+### Task Providers
+
+| Provider                              | Description                           | Status         | npm         |
+| ------------------------------------- | ------------------------------------- | -------------- | ----------- |
+| **@opentask/taskin-fs-provider**      | File System provider (Markdown files) | ✅ Stable      | Coming soon |
+| **@opentask/taskin-redmine-provider** | Redmine integration                   | 🚧 Coming Soon | -           |
+| **@opentask/taskin-jira-provider**    | Jira Cloud integration                | 🚧 Coming Soon | -           |
+| **@opentask/taskin-github-provider**  | GitHub Issues integration             | 🚧 Coming Soon | -           |
+
+### Utilities
+
+| Package                        | Description          | npm         |
+| ------------------------------ | -------------------- | ----------- |
+| **@opentask/taskin-git-utils** | Git workflow helpers | Coming soon |
+| **@opentask/taskin-utils**     | Shared utilities     | Coming soon |
+
+> 💡 **Tip:** When you run `taskin init`, providers are automatically installed on-demand. You don't need to install them manually!
+
 ## Quick Start
 
 1. **Initialize Taskin in your project:**
@@ -60,12 +96,53 @@ yarn global add taskin
 
 ## Commands
 
-- \`taskin init\` - Initialize Taskin in your project with interactive setup
-- \`taskin list\` - List all tasks
-- \`taskin start <id>\` - Start working on a task
-- \`taskin pause <id>\` - Pause work on a task
-- \`taskin finish <id>\` - Complete a task
-- \`taskin lint\` - Validate task files
+- `taskin init` - Initialize Taskin in your project with interactive setup
+- `taskin list` - List all tasks
+- `taskin start <id>` - Start working on a task
+- `taskin pause <id>` - Pause work on a task
+- `taskin finish <id>` - Complete a task
+- `taskin lint` - Validate task files
+
+## 📦 Programmatic Usage
+
+Taskin can also be used as a library in your TypeScript/JavaScript projects:
+
+```bash
+npm install taskin
+```
+
+```typescript
+import { createTaskin, getTaskin, type ITaskin } from 'taskin';
+
+// Create a Taskin instance with custom tasks directory
+const taskin = createTaskin('./my-tasks');
+
+// Or use the default instance (uses ./TASKS)
+const taskin = getTaskin();
+
+// Use the API
+const tasks = await taskin.list();
+await taskin.start('task-001');
+await taskin.pause('task-001', { message: 'Break time!' });
+await taskin.finish('task-001');
+
+// Lint tasks
+const lintResult = await taskin.lint({ path: './TASKS' });
+console.log(`Checked ${lintResult.tasksChecked} tasks`);
+```
+
+### TypeScript Support
+
+Taskin is written in TypeScript and exports full type definitions:
+
+```typescript
+import type { Task, TaskId, TaskStatus, ITaskin } from 'taskin';
+
+// All types are available for your TypeScript projects
+function processTask(task: Task): void {
+  console.log(`Processing ${task.title}`);
+}
+```
 
 ## 🏗️ Architecture
 
@@ -83,12 +160,12 @@ See [EXAMPLES.md](./EXAMPLES.md) for detailed usage examples and workflows.
 
 ## 🔌 Available Providers
 
-| Provider         | Status         | Package                           |
-| ---------------- | -------------- | --------------------------------- |
-| 📁 File System   | ✅ Stable      | \`@taskin/fs-task-provider\`      |
-| 🔴 Redmine       | 🚧 Coming Soon | \`@taskin/redmine-task-provider\` |
-| 🔵 Jira          | 🚧 Coming Soon | \`@taskin/jira-task-provider\`    |
-| 🐙 GitHub Issues | 🚧 Coming Soon | \`@taskin/github-task-provider\`  |
+| Provider         | Status         | Package                             |
+| ---------------- | -------------- | ----------------------------------- |
+| 📁 File System   | ✅ Stable      | `@opentask/taskin-fs-provider`      |
+| 🔴 Redmine       | 🚧 Coming Soon | `@opentask/taskin-redmine-provider` |
+| 🔵 Jira          | 🚧 Coming Soon | `@opentask/taskin-jira-provider`    |
+| 🐙 GitHub Issues | 🚧 Coming Soon | `@opentask/taskin-github-provider`  |
 
 Want to create your own provider? See [ARCHITECTURE.md](./ARCHITECTURE.md#-criando-um-novo-provider).
 
@@ -108,10 +185,12 @@ Found a bug? Have a feature request? Please [open an issue](https://github.com/o
 ## � Team
 
 **OpenTask**
+
 - Website: [opentask.com.br](https://opentask.com.br)
 - Email: contato@opentask.com.br
 
 **Contributors:**
+
 - Sidarta Veloso ([@sidartaveloso](https://github.com/sidartaveloso))
 
 ## 📄 License

package/dist/index.d.ts

@@ -1,8 +1,383 @@
 #!/usr/bin/env node
+import { z } from 'zod';
+
 /**
- * Taskin CLI - Main entry point
- * Command-line interface for managing tasks
+ * Task identifier schema.
+ * Represents a unique identifier for a task (UUID format).
+ *
+ * @public
  */
-export type { ITaskin } from '@taskin/types-ts';
-export { createTaskin, getTaskin } from './main.js';
-export { Taskin } from './taskin.js';
+declare const TaskIdSchema: z.ZodBranded<z.ZodString, "TaskId">;
+/**
+ * Runtime validator for task type values.
+ * Use this to validate user input or external data.
+ *
+ * @public
+ */
+declare const TaskTypeSchema: z.ZodEnum<["feat", "fix", "refactor", "docs", "test", "chore"]>;
+/**
+ * Runtime validator for task objects.
+ * Use this to parse and validate task data from external sources (API, database, forms).
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Parse and validate task data
+ * const task = TaskSchema.parse(userInput);
+ *
+ * // Safe parse with error handling
+ * const result = TaskSchema.safeParse(untrustedData);
+ * if (result.success) {
+ *   console.log(result.data);
+ * }
+ * ```
+ */
+declare const TaskSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    id: z.ZodBranded<z.ZodString, "TaskId">;
+    status: z.ZodEnum<["pending", "in-progress", "done", "blocked"]>;
+    title: z.ZodString;
+    type: z.ZodEnum<["feat", "fix", "refactor", "docs", "test", "chore"]>;
+    assignee: z.ZodOptional<z.ZodString>;
+    completed: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    createdAt: string;
+    id: string & z.BRAND<"TaskId">;
+    status: "pending" | "in-progress" | "done" | "blocked";
+    title: string;
+    type: "feat" | "fix" | "refactor" | "docs" | "test" | "chore";
+    assignee?: string | undefined;
+    completed?: boolean | undefined;
+    description?: string | undefined;
+    userId?: string | undefined;
+}, {
+    createdAt: string;
+    id: string;
+    status: "pending" | "in-progress" | "done" | "blocked";
+    title: string;
+    type: "feat" | "fix" | "refactor" | "docs" | "test" | "chore";
+    assignee?: string | undefined;
+    completed?: boolean | undefined;
+    description?: string | undefined;
+    userId?: string | undefined;
+}>;
+/**
+ * Runtime validator for user objects.
+ * Use this to parse and validate user data from external sources.
+ *
+ * @public
+ */
+declare const UserSchema: z.ZodObject<{
+    email: z.ZodString;
+    id: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    email: string;
+    name: string;
+}, {
+    id: string;
+    email: string;
+    name: string;
+}>;
+
+/**
+ * Taskin Core Interface
+ * Main interface for task management operations
+ */
+
+interface ListTasksOptions {
+    assignee?: string;
+    status?: string;
+    type?: string;
+}
+interface StartTaskOptions {
+    base?: string;
+    force?: boolean;
+}
+interface PauseTaskOptions {
+    message?: string;
+    skipCommit?: boolean;
+}
+interface FinishTaskOptions {
+    push?: boolean;
+    skipUpdate?: boolean;
+}
+interface LintTasksOptions {
+    path?: string;
+}
+/**
+ * Validation issue found during task linting
+ * Provider-agnostic - works with any task storage backend
+ */
+interface TaskValidationIssue {
+    message: string;
+    severity: 'error' | 'warning';
+    taskId: string;
+    line?: number;
+}
+/**
+ * Task metadata extracted from task source
+ */
+interface TaskMetadata {
+    assignee?: string;
+    status?: string;
+    type?: string;
+}
+/**
+ * Result of task validation/linting operation
+ */
+interface LintResult {
+    errors: TaskValidationIssue[];
+    tasksChecked: number;
+    valid: boolean;
+    warnings: TaskValidationIssue[];
+}
+/**
+ * ITaskin - Core interface for task management system
+ */
+interface ITaskin {
+    /**
+     * Finish a task
+     */
+    finish(taskId: TaskId, options?: FinishTaskOptions): Promise<void>;
+    /**
+     * Lint/validate tasks from the configured provider
+     */
+    lint(options?: LintTasksOptions): Promise<LintResult>;
+    /**
+     * List all tasks with optional filters
+     */
+    list(options?: ListTasksOptions): Promise<Task[]>;
+    /**
+     * Pause work on a task
+     */
+    pause(taskId: TaskId, options?: PauseTaskOptions): Promise<void>;
+    /**
+     * Start working on a task
+     */
+    start(taskId: TaskId, options?: StartTaskOptions): Promise<void>;
+}
+/**
+ * Unique identifier for a task (UUID branded type).
+ * Use this type for type-safe task ID handling across the system.
+ *
+ * @public
+ * @example
+ * ```ts
+ * function getTask(id: TaskId): Task { ... }
+ * const taskId: TaskId = '550e8400-e29b-41d4-a716-446655440000' as TaskId;
+ * ```
+ */
+type TaskId = z.infer<typeof TaskIdSchema>;
+/**
+ * Type of task based on the kind of work being performed.
+ * Follows conventional commit types for consistency across the codebase.
+ *
+ * @public
+ */
+type TaskType = z.infer<typeof TaskTypeSchema>;
+/**
+ * Represents a task in the Taskin system.
+ * Contains all core information needed to track and manage work items.
+ *
+ * @public
+ */
+type Task = z.infer<typeof TaskSchema>;
+/**
+ * Represents a user in the Taskin system.
+ * Contains basic user identification and contact information.
+ *
+ * @public
+ */
+type User = z.infer<typeof UserSchema>;
+
+/**
+ * A task with additional file system metadata.
+ * Extends the base Task type with content and path information.
+ * @public
+ */
+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
+ */
+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>;
+}
+/**
+ * Interface for task management operations.
+ * Provides high-level methods for managing task workflow and state transitions.
+ * @public
+ */
+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>;
+}
+
+declare class TaskManager implements ITaskManager {
+    private taskProvider;
+    constructor(taskProvider: ITaskProvider);
+    startTask(taskId: string): Promise<TaskFile>;
+    finishTask(taskId: string): Promise<TaskFile>;
+}
+
+declare class FileSystemTaskProvider implements ITaskProvider {
+    private tasksDirectory;
+    constructor(tasksDirectory: string);
+    findTask(taskId: string): Promise<TaskFile | undefined>;
+    updateTask(task: TaskFile): Promise<void>;
+    getAllTasks(): Promise<TaskFile[]>;
+}
+
+/**
+ * FileSystem task linter types
+ * Re-exports from @opentask/taskin-types + FileSystem-specific extensions
+ */
+
+/**
+ * FileSystem-specific validation error
+ * Extends TaskValidationIssue with file-specific information
+ */
+interface FileValidationError extends Omit<TaskValidationIssue, 'taskId'> {
+    file: string;
+}
+/**
+ * FileSystem-specific lint result
+ * Contains file-based validation results
+ */
+interface FileLintResult {
+    errors: FileValidationError[];
+    filesChecked: number;
+    valid: boolean;
+    warnings: FileValidationError[];
+}
+/**
+ * FileSystem-specific task linter interface
+ * Defines validation operations for file-based task providers
+ */
+interface IFileSystemTaskLinter {
+    /**
+     * Lint all task files in a directory
+     * @param tasksDir - Directory containing task markdown files
+     * @returns Validation results for all files
+     */
+    lintDirectory(tasksDir: string): Promise<FileLintResult>;
+    /**
+     * Lint a single task file
+     * @param filePath - Path to the task markdown file
+     * @returns Array of validation errors found in the file
+     */
+    lintFile(filePath: string): Promise<FileValidationError[]>;
+    /**
+     * Validate task metadata
+     * @param metadata - Task metadata to validate
+     * @param fileName - Name of the file being validated
+     * @returns Array of validation errors
+     */
+    validateMetadata(metadata: Record<string, unknown>, fileName: string): FileValidationError[];
+}
+
+/**
+ * FileSystem-specific task linter implementation
+ * Validates task markdown files in the local filesystem
+ */
+declare class FileSystemTaskLinter implements IFileSystemTaskLinter {
+    private errors;
+    private addError;
+    /**
+     * Validate task file name format (FileSystem-specific)
+     */
+    validateFileName(fileName: string): FileValidationError | null;
+    private extractMetadata;
+    /**
+     * Validate task metadata (FileSystem-specific)
+     */
+    validateMetadata(metadata: TaskMetadata, filePath: string): FileValidationError[];
+    private validateContent;
+    /**
+     * Lint a single task file (FileSystem-specific)
+     */
+    lintFile(filePath: string): Promise<FileValidationError[]>;
+    /**
+     * Lint all task files in the specified directory (FileSystem-specific)
+     */
+    lintDirectory(tasksDir: string): Promise<FileLintResult>;
+    static printResults(result: FileLintResult): void;
+}
+
+/**
+ * Taskin - Concrete implementation of ITaskin
+ * Main class that implements task management with dependency injection
+ */
+
+declare class Taskin implements ITaskin {
+    private readonly taskProvider;
+    private readonly taskManager;
+    private readonly linter;
+    constructor(taskProvider: FileSystemTaskProvider, taskManager: TaskManager, linter: FileSystemTaskLinter);
+    list(options?: ListTasksOptions): Promise<Task[]>;
+    start(taskId: TaskId, options?: StartTaskOptions): Promise<void>;
+    pause(taskId: TaskId, options?: PauseTaskOptions): Promise<void>;
+    finish(taskId: TaskId, _options?: FinishTaskOptions): Promise<void>;
+    lint(options?: LintTasksOptions): Promise<LintResult>;
+}
+
+/**
+ * Main entry point for Taskin CLI
+ * Handles dependency injection and initialization
+ */
+
+/**
+ * Factory function to create a configured Taskin instance
+ */
+declare function createTaskin(tasksDir?: string): Taskin;
+/**
+ * Get the default Taskin instance
+ * Uses current working directory TASKS folder
+ */
+declare function getTaskin(): Taskin;
+
+export { type ITaskin, Taskin, createTaskin, getTaskin };