### Initial Setup and Development Commands

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

Commands to clone the repository, install dependencies, and start the development server with hot reload. Assumes Node.js, pnpm, and Git are installed.

```bash
# Clone the repository into your Obsidian vault's plugin folder
cd {YOUR_OBSIDIAN_VAULT_PATH}/.obsidian/plugins
git clone https://github.com/Quorafind/Obsidian-Task-Genius.git
cd Obsidian-Task-Genius

# Install dependencies
pnpm install

# Start development with hot reload
pnpm run dev
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

Examples illustrating the conventional commit format for various types of changes, including features, fixes, documentation, and performance improvements.

```bash
feat(kanban): add drag-and-drop support
fix(parser): handle edge case in task parsing
docs(api): update TaskManager documentation
perf(indexer): optimize file scanning algorithm
```

--------------------------------

### Install esbuild-plugin-inline-worker

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/packages/esbuild-plugin-inline-worker/README.md

Install the esbuild-plugin-inline-worker package using Yarn.

```sh
yarn add esbuild-plugin-inline-worker
```

--------------------------------

### Running Tests with pnpm

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

This snippet shows command-line instructions for running tests using pnpm. It includes commands for running all tests, running tests in watch mode for continuous feedback, and running a specific test file.

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm run test:watch

# Run specific test file
pnpm test src/__tests__/unit/TaskParser.test.ts
```

--------------------------------

### TypeScript Code Style Guidelines

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

Demonstrates recommended TypeScript practices, including explicit typing, interface usage, const assertions, optional chaining, nullish coalescing, and async/await.

```typescript
// 1. Use explicit types for function parameters and returns
function calculateProgress(completed: number, total: number): number {
  return (completed / total) * 100;
}

// 2. Use interfaces for object shapes
interface TaskConfig {
  enableWorker: boolean;
  maxConcurrency: number;
  cacheTimeout: number;
}

// 3. Prefer const assertions for literals
const TASK_STATUSES = ['todo', 'in-progress', 'done'] as const;
type TaskStatus = typeof TASK_STATUSES[number];

// 4. Use optional chaining and nullish coalescing
const title = task?.metadata?.title ?? 'Untitled';

// 5. Async/await over promises
async function loadTasks(): Promise<Task[]> {
  const files = await this.getTaskFiles();
  return this.parseTasks(files);
}
```

--------------------------------

### View Configuration Interfaces and Examples (TypeScript)

Source: https://context7.com/taskgenius/taskgenius-plugin/llms.txt

Defines the TypeScript interfaces for configuring different task views in Task Genius, including general view settings, filter rules, and specific configurations for Kanban and Calendar views. It also provides examples of how to define custom views.

```typescript
interface ViewConfig {
  id: string;           // Unique view identifier
  name: string;         // Display name
  icon: string;         // Lucide icon name
  type: "default" | "custom";
  visible: boolean;     // Show in sidebar
  hideCompletedAndAbandonedTasks: boolean;
  filterBlanks: boolean;
  region?: "top" | "bottom"; // Sidebar section

  // Filter rules for this view
  filterRules?: ViewFilterRule;

  // Sort criteria
  sortCriteria?: SortCriterion[];

  // View-specific configuration
  specificConfig?: KanbanSpecificConfig | CalendarSpecificConfig;
}

interface ViewFilterRule {
  tagsInclude?: string[];
  tagsExclude?: string[];
  statusInclude?: string[];
  statusExclude?: string[];
  project?: string;
  priority?: string;
  hasDueDate?: "hasDate" | "noDate" | "any";
  dueDate?: string;      // "today", "next-week", "2024-12-31"
  hasStartDate?: "hasDate" | "noDate" | "any";
  textContains?: string;
  pathIncludes?: string;
  pathExcludes?: string;
}

interface KanbanSpecificConfig {
  viewType: "kanban";
  showCheckbox: boolean;
  hideEmptyColumns: boolean;
  defaultSortField: "priority" | "dueDate" | "scheduledDate" | "startDate" | "createdDate";
  defaultSortOrder: "asc" | "desc";
  groupBy: "status" | "priority" | "tags" | "project" | "dueDate" | "context" | "filePath";
  customColumns?: KanbanColumnConfig[];
  hiddenColumns?: string[];
}

interface CalendarSpecificConfig {
  viewType: "calendar";
  firstDayOfWeek?: number;    // 0=Sun, 1=Mon, ..., 6=Sat
  hideWeekends?: boolean;
  showWorkingHoursOnly?: boolean;
  workingHoursStart?: number; // 0-23, default: 9
  workingHoursEnd?: number;   // 0-23, default: 18
}

// Example: Define a custom "Urgent Work" view
const urgentWorkView: ViewConfig = {
  id: "urgent-work",
  name: "Urgent Work",
  icon: "flame",
  type: "custom",
  visible: true,
  hideCompletedAndAbandonedTasks: true,
  filterBlanks: false,
  region: "top",
  filterRules: {
    project: "Work",
    priority: "4", // High priority or above
    hasDueDate: "hasDate",
    statusExclude: ["x", "-"]
  },
  sortCriteria: [
    { field: "dueDate", order: "asc" },
    { field: "priority", order: "desc" }
  ]
};

// Example: Kanban view grouped by project
const projectKanban: ViewConfig = {
  id: "project-kanban",
  name: "Projects Board",
  icon: "kanban",
  type: "custom",
  visible: true,
  hideCompletedAndAbandonedTasks: false,
  filterBlanks: true,
  specificConfig: {
    viewType: "kanban",
    showCheckbox: true,
    hideEmptyColumns: true,
    groupBy: "project",
    defaultSortField: "priority",
    defaultSortOrder: "desc"
  }
};

```

--------------------------------

### TypeScript Component Best Practices

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

Illustrates TypeScript component design patterns, such as extracting complex logic into methods, using descriptive naming conventions, and documenting complex algorithms with JSDoc.

```typescript
// 1. Extract complex logic to separate methods
export class TaskList extends Component {
  private async renderTasks(): Promise<void> {
    const tasks = await this.fetchTasks();
    const filtered = this.applyFilters(tasks);
    const sorted = this.sortTasks(filtered);
    this.display(sorted);
  }

  private applyFilters(tasks: Task[]): Task[] {
    // Filter logic
  }

  private sortTasks(tasks: Task[]): Task[] {
    // Sort logic
  }
}

// 2. Use descriptive names
// Bad: const d = new Date();
// Good: const currentDate = new Date();

// 3. Document complex algorithms
/**
 * Calculates task priority score based on multiple factors
 * @param task - The task to score
 * @returns Priority score (0-100)
 */
function calculatePriorityScore(task: Task): number {
  // Implementation
}
```

--------------------------------

### Git Branching and Committing Workflow

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

Steps for creating a feature branch, running development commands, committing changes, and pushing to a remote repository. Follows conventional commit message format.

```bash
# 1. Create Feature Branch
git checkout -b feature/your-feature-name

# 2. Development Cycle
# Make changes
pnpm run dev     # Watch mode

# Run tests
pnpm test

# Lint code
pnpm run lint

# 3. Commit Changes
git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name
```

--------------------------------

### Task Genius Gantt Chart View Query (Bases Plugin)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/pages/bases/examples/sample-tasks-base.md

Creates a Gantt chart view for tasks that have both a start date and a due date. It pulls data from 'Tasks' and maps task properties including content, start date, due date, status, and project.

```base
view: task-genius-gantt
from: "Tasks"
where: start_date != null AND due_date != null
config:
  taskContent: name
  taskStartDate: start_date
  taskDueDate: due_date
  taskStatus: status
  taskProject: project
```

--------------------------------

### Mocking Obsidian API for Testing

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

This TypeScript code demonstrates how to mock the Obsidian API using Jest. It provides mock implementations for the Plugin and TFile classes, which are essential for testing plugin functionality that interacts with the Obsidian environment.

```typescript
// Mock Obsidian API
jest.mock('obsidian', () => ({
  Plugin: class MockPlugin {
    // Mock implementation
  },
  TFile: class MockTFile {
    // Mock implementation
  }
}));
```

--------------------------------

### CSS Styling Guidelines for Task Genius

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

This snippet demonstrates CSS styling conventions for the Task Genius plugin, including the BEM naming convention, usage of CSS variables for theming, and scoping styles to prevent conflicts. It ensures consistent and maintainable styling across the plugin.

```css
/* Use BEM naming convention */
.task-genius-view task-card {
  /* Block */
}

.task-genius-view task-card__header {
  /* Element */
}

.task-genius-view task-card--completed {
  /* Modifier */
}

/* Use CSS variables for theming */
.task-genius-view {
  --primary-color: var(--interactive-accent);
  --spacing-sm: 4px;
  --spacing-md: 8px;
  --spacing-lg: 16px;
}

/* Scope styles to prevent conflicts */
.workspace-leaf-content[data-type="task-genius"] {
  /* Plugin-specific styles */
}
```

--------------------------------

### MCP Server AI Agent Integration in TypeScript

Source: https://context7.com/taskgenius/taskgenius-plugin/llms.txt

The MCP Server enables AI agents to interact with tasks via HTTP JSON-RPC. It supports task querying, creation, updating, and management. Configuration includes port, host, authentication token, CORS enablement, and log level. The server can be started, stopped, and its configuration updated at runtime.

```typescript
import { McpServer } from "@/mcp/McpServer";
import { McpServerConfig } from "@/mcp/types/mcp";

// Server configuration
const config: McpServerConfig = {
  port: 3000,
  host: "127.0.0.1",
  authToken: "your-secret-token",
  enableCors: true,
  logLevel: "info" // "debug" | "info" | "warn" | "error" 
};

// Initialize and start the MCP server
const mcpServer = new McpServer(plugin, config);
await mcpServer.start();

// Check server status
const status = mcpServer.getStatus();
// { running: true, port: 3000, startTime: Date, requestCount: 42, sessions: 3 }

// Get server logs
const logs = mcpServer.getLogs();

// Update configuration at runtime
mcpServer.updateConfig({ authToken: "new-token" });

// Stop the server
await mcpServer.stop();
```

--------------------------------

### Basic Worker Import and Usage

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/packages/esbuild-plugin-inline-worker/README.md

Demonstrates how to create a worker file (example.worker.js) and import it into a main JavaScript file (example.js) to create and interact with a Web Worker.

```javascript
// example.worker.js
postMessage('hello from worker!');
```

```javascript
// example.js
import Worker from './example.worker.js';
let worker = Worker();
worker.onmessage = ({data}) => console.log(data);
```

--------------------------------

### Task Moving on Completion (Markdown)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/utils/README.md

Shows how to configure a task to be moved to a different file or a specific section within a file upon completion. This uses the 'onCompletion:move' metadata, allowing for organized task archiving.

```markdown
- [ ] Task to move onCompletion:move(Archive.md)
- [ ] Task to move to section onCompletion:move(Archive.md, Completed Tasks)
```

--------------------------------

### Task Duplication on Completion (Markdown)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/utils/README.md

Illustrates how to configure a task to be duplicated upon completion. This can be used for recurring tasks or to create copies in specific files, with options to include or exclude metadata.

```markdown
- [ ] Recurring task onCompletion:duplicate
- [ ] Duplicate to file onCompletion:duplicate(Templates.md)
- [ ] Duplicate without metadata onCompletion:duplicate(Templates.md, , false)
```

--------------------------------

### Health Check Endpoint (curl)

Source: https://context7.com/taskgenius/taskgenius-plugin/llms.txt

This snippet shows how to perform a health check on the TaskGenius API. A simple GET request to the `/health` endpoint returns the service status, uptime, request count, and active sessions.

```curl
curl http://localhost:3000/health
```

--------------------------------

### Configure esbuild-plugin-inline-worker

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/packages/esbuild-plugin-inline-worker/README.md

Illustrates how to pass a configuration object to inlineWorkerPlugin, which can include esbuild build options for the worker code.

```typescript
export type InlineWorkerPluginConfig = {
    buildOptions?: BuildOptions;
    workerName?: string
    workerArguments?: WorkerOptions
}
```

```javascript
inlineWorkerPlugin(workerPluginConfig);
```

--------------------------------

### MCP Server AI Agent Integration using cURL

Source: https://context7.com/taskgenius/taskgenius-plugin/llms.txt

This section demonstrates how to interact with the MCP Server using cURL commands for initializing sessions, listing available tools, and performing other RPC operations. It requires setting appropriate headers for authentication and session management.

```bash
# Initialize MCP session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -H "Mcp-App-Id: your-app-id" \
  -d '{ 
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize"
  }'
# Response includes Mcp-Session-Id header for subsequent requests

# List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -H "Mcp-Session-Id: session-123" \
  -d '{ 
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'
```

--------------------------------

### Task Genius Unified View Query (Bases Plugin)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/pages/bases/examples/sample-tasks-base.md

Configures a unified view with custom settings, including a 'forecast' view mode. It maps various task properties such as content, status, priority, project, tags, due date, start date, and context.

```base
view: task-genius-unified
from: "Tasks"
config:
  viewMode: "forecast"
  taskContent: name
  taskStatus: status
  taskPriority: priority
  taskProject: project
  taskTags: tags
  taskDueDate: due_date
  taskStartDate: start_date
  taskContext: context
```

--------------------------------

### Unit Testing Task Parsing Logic

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/DEVELOPMENT.md

This TypeScript code snippet illustrates unit tests for the TaskParser class using Jest. It covers parsing basic task syntax and handling tasks with metadata. The tests ensure the core functionality of task parsing is robust.

```typescript
// src/__tests__/unit/TaskParser.test.ts
describe('TaskParser', () => {
  let parser: TaskParser;

  beforeEach(() => {
    parser = new TaskParser();
  });

  describe('parseTask', () => {
    it('should parse basic task syntax', () => {
      const input = '- [ ] Sample task';
      const result = parser.parseTask(input);
      expect(result).toMatchObject({
        content: 'Sample task',
        completed: false
      });
    });

    it('should handle task with metadata', () => {
      // Test implementation
    });
  });
});
```

--------------------------------

### Integrate esbuild-plugin-inline-worker into esbuild Build

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/packages/esbuild-plugin-inline-worker/README.md

Shows how to import and use the inlineWorkerPlugin within your esbuild build configuration.

```javascript
import {build} from 'esbuild';
import inlineWorkerPlugin from 'esbuild-plugin-inline-worker';

build({
  /* ... */
  plugins: [inlineWorkerPlugin()],
});
```

--------------------------------

### Task Deletion on Completion (Markdown)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/utils/README.md

Demonstrates how to configure a task to be deleted automatically upon completion using the 'onCompletion:delete' metadata field in Markdown format. This is a simple action for managing completed tasks.

```markdown
- [ ] Task to delete on completion onCompletion:delete
```

--------------------------------

### Internal Worker Build Process

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/packages/esbuild-plugin-inline-worker/README.md

Provides insight into how the plugin internally uses esbuild to bundle the worker code, excluding entry points and output files from the worker's build options.

```javascript
if (pluginConfig.buildOptions) {
    delete pluginConfig.buildOptions.entryPoints;
    delete pluginConfig.buildOptions.outfile;
    delete pluginConfig.buildOptions.outdir;
}

await build({
    entryPoints: [workerPath],
    bundle: true,
    minify: true,
    outfile: bundlePath,
    target: "es2017",
    format: "esm",
    ...pluginConfig.buildOptions,
});
```

--------------------------------

### Task Genius Kanban Board View Query (Bases Plugin)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/pages/bases/examples/sample-tasks-base.md

Configures a Kanban board view for tasks. It specifies the data source as 'Tasks' and filters out completed tasks. The configuration maps task properties like content, status, priority, project, tags, and due date.

```base
view: task-genius-kanban
from: "Tasks"
where: status != "x"
config:
  taskContent: name
  taskStatus: status
  taskPriority: priority
  taskProject: project
  taskTags: tags
  taskDueDate: due_date
```

--------------------------------

### Task Genius Project View Query (Bases Plugin)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/pages/bases/examples/sample-tasks-base.md

Configures a project view with a tree structure, displaying tasks grouped by project. It filters for tasks with assigned projects and sorts them by project and priority. Mappings include task content, project, status, and priority.

```base
view: task-genius-projects
from: "Tasks"
where: project != null
sort: project asc, priority desc
config:
  taskContent: name
  taskProject: project
  taskStatus: status
  taskPriority: priority
```

--------------------------------

### Create a New Task (curl)

Source: https://context7.com/taskgenius/taskgenius-plugin/llms.txt

This snippet shows how to create a new task using the `create_task` method. It includes parameters for task content, file path, project, priority, due date, and tags. The request is sent via curl to the `/mcp` endpoint.

```curl
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -H "Mcp-Session-Id: session-123" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "create_task",
      "arguments": {
        "content": "Review PR #42",
        "filePath": "Daily/2024-12-15.md",
        "project": "Engineering",
        "priority": 4,
        "dueDate": "2024-12-16",
        "tags": ["code-review"]
      }
    }
  }'
```

--------------------------------

### Task Genius Review View Query (Bases Plugin)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/pages/bases/examples/sample-tasks-base.md

Creates a review view for tasks that are not completed and are either due today or have a priority of 3 or higher. It maps task content, status, priority, due date, and project.

```base
view: task-genius-review
from: "Tasks"
where: status != "x" AND (due_date <= date("today") OR priority >= 3)
config:
  taskContent: name
  taskStatus: status
  taskPriority: priority
  taskDueDate: due_date
  taskProject: project
```

--------------------------------

### Create Task API

Source: https://context7.com/taskgenius/taskgenius-plugin/llms.txt

Allows creating a new task with specified content, project, due date, and other properties.

```APIDOC
## POST /mcp

### Description
Creates a new task with provided details.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Headers
- **Content-Type** (string) - Required - `application/json`
- **Authorization** (string) - Required - `Bearer your-secret-token`
- **Mcp-Session-Id** (string) - Required - `session-123`

#### Request Body
- **jsonrpc** (string) - Required - `"2.0"`
- **id** (integer) - Required - Unique request ID
- **method** (string) - Required - `"tools/call"`
- **params** (object) - Required
  - **name** (string) - Required - `"create_task"`
  - **arguments** (object) - Required
    - **content** (string) - Required - The description of the task.
    - **filePath** (string) - Optional - Path to the file associated with the task.
    - **project** (string) - Optional - The project the task belongs to.
    - **priority** (integer) - Optional - The priority level of the task (e.g., 1-5).
    - **dueDate** (string) - Optional - The due date for the task (YYYY-MM-DD).
    - **tags** (array of strings) - Optional - Tags associated with the task.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_task",
    "arguments": {
      "content": "Review PR #42",
      "filePath": "Daily/2024-12-15.md",
      "project": "Engineering",
      "priority": 4,
      "dueDate": "2024-12-16",
      "tags": ["code-review"]
    }
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the details of the created task.
  - **taskId** (string) - The unique identifier of the newly created task.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "taskId": "task-def456"
  }
}
```
```

--------------------------------

### Configure Task Parsing in TypeScript

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/utils/README.md

Defines configuration options for the task parser, including metadata parsing, tag handling, heading extraction, metadata parse modes, and status mappings. This allows customization of how tasks are processed.

```typescript
const config: TaskParserConfig = {
  parseMetadata: true,
  parseTags: true,
  parseHeadings: true,
  metadataParseMode: MetadataParseMode.Both,
  statusMapping: {
    todo: " ",
    done: "x",
    cancelled: "-",
    // ... more mappings
  }
};
```

--------------------------------

### Task Genius Calendar View Query (Bases Plugin)

Source: https://github.com/taskgenius/taskgenius-plugin/blob/master/src/pages/bases/examples/sample-tasks-base.md

Sets up a calendar view for tasks that have a due date. It uses 'Tasks' as the data source and configures mappings for task content, due date, and status.

```base
view: task-genius-calendar
from: "Tasks"
where: due_date != null
config:
  taskContent: name
  taskDueDate: due_date
  taskStatus: status
```