ms-todo-oauth

A robust CLI skill to manage Microsoft To Do tasks via Microsoft Graph API. Supports full task lifecycle management including lists, tasks with priorities, due dates, reminders, recurrence patterns, views, search, and data export. Includes comprehensive test suite for reliability. THIS IS A REVISED OAUTH2-BASED VERSION OF ms-todo-sync with AI ASSISTANCE. ALL CREDITS TO THE ORIGINAL AUTHOR.

# ms-todo-oauth

A fully-tested Microsoft To Do command-line client for managing tasks and lists via Microsoft Graph API.

## ⚠️This is a oauth based script. It contains a generated Azure Client ID and Secret ID

IF YOU WORRIED ABOUT YOUR PRIVACY, CONSIDER REPLACING THEM TO YOUR OWN IN `scripts\ms-todo-oauth.py`.
Just search for values below:

`client_id="ca6ec244……`

`client_secret="TwQ8Q……`

## ✨ Features

- ✅ **Full Task Management**: Create, complete, delete, and search tasks
- 🗂️ **List Organization**: Create and manage multiple task lists
- ⏰ **Rich Task Options**: Priorities, due dates, reminders, descriptions, tags
- 🔄 **Recurring Tasks**: Daily, weekly, monthly patterns with custom intervals
- 📊 **Multiple Views**: Today, overdue, pending, statistics
- 🔍 **Powerful Search**: Find tasks across all lists
- 💾 **Data Export**: Export all tasks to JSON
- 🧪 **Fully Tested**: 29 comprehensive automated tests
- 🌐 **Unicode Support**: Full support for Chinese characters and emojis

## Prerequisites

1. **Python >= 3.9** must be installed
2. **Working directory**: All commands MUST be run from the root of this skill (the directory containing this SKILL.md file)
3. **Network access**: Requires internet access to Microsoft Graph API endpoints
4. **Microsoft Account**: Personal Microsoft account (Hotmail, Outlook.com) or work/school account
5. **Authentication**: First-time use requires OAuth2 login via browser. See [Authentication](#authentication) section
   - **Token cache**: `~/.mstodo_token_cache.json` (persists across sessions, auto-refreshed)

## Installation & Setup

### First-Time Setup

Before using this skill for the first time, dependencies must be installed:

```bash
# Navigate to skill directory
cd <path-to-ms-todo-oauth>

# Create a venv in the project (creates '.venv' folder)
python3 -m venv .venv
# Activate the venv choose based on platforms:
#- Bash/Zsh: 
source .venv/bin/activate
# - Fish: 
source .venv/bin/activate.fish
#  - Windows (PowerShell):
.venv\Scripts\Activate.ps1

pip install --upgrade pip
pip install -r requirements.txt

# Alternative (global python env, not recommended):
# pip install -r requirements.txt
```

**Dependencies:**

- `msal` (Microsoft Authentication Library) - Official Microsoft OAuth library
- `requests` - HTTP client for API calls
- Specified in `requirements.txt`

### Environment Verification

After installation, verify the setup:

```bash

# If using native venv (activate as above):
python3 scripts/ms-todo-oauth.py --help

# Expected: Command help text should be displayed
```

**Troubleshooting:**

- If `Python not found`, install Python 3.9 or higher from https://python.org


### Testing (Optional but Recommended)

Verify all functionality works correctly:

```bash
# Run comprehensive automated test suite (29 tests)
python3 test_ms_todo_oauth.py

# Expected: All tests pass (100% pass rate)
```

See [Testing](#testing) section for details.

### Security Notes

- Uses official Microsoft Graph API via Microsoft's `msal` library
- All code is plain Python (.py files), readable and auditable
- Tokens stored locally in `~/.mstodo_token_cache.json`
- All API calls go directly to Microsoft endpoints (graph.microsoft.com)
- OAuth2 standard authentication flow
- No third-party services involved

## Command Reference

All commands follow this pattern:

```
python3 scripts/ms-todo-oauth.py [GLOBAL_OPTIONS] <command> [COMMAND_OPTIONS]
```

### Global Options

| Option            | Description                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `-v, --verbose` | Show detailed information (IDs, dates, notes).**Must be placed BEFORE the subcommand.**                                       |
| `--debug`       | Enable debug mode to display API requests and responses. Useful for troubleshooting.**Must be placed BEFORE the subcommand.** |
| `--reauth`      | Force re-authentication by clearing the token cache and starting fresh login                                                        |

> ⚠️ **Common mistake**: Global options MUST come before the subcommand.
>
> - ✅ `python3 scripts/ms-todo-oauth.py -v lists`
> - ✅ `python3 scripts/ms-todo-oauth.py --debug add "Task"`
> - ❌ `python3 scripts/ms-todo-oauth.py lists -v`

---

### Authentication

Authentication uses OAuth2 authorization code flow, designed for both interactive and automated environments.

#### `login get` — Get OAuth2 authorization URL

```bash
python3 scripts/ms-todo-oauth.py login get
```

**Output example:**

```
======================================================================
🔐 OAuth2 Authorization Required
======================================================================

Please visit the following URL to authorize the application:

  https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize?...

After authorization, you will be redirected to a callback URL.
Copy the 'code' parameter from the callback URL and run:

  ms-todo-oauth.py login verify <authorization_code>

======================================================================
```

**What to do:**

1. Open the provided URL in your browser
2. Sign in with your Microsoft account
3. Grant permissions when prompted
4. You'll be redirected to a URL like: `http://localhost:8000/callback?code=M.R3_BAY.abc123...`
5. Copy the entire code after `code=` (usually a long string starting with `M.R3_BAY.`)

**Agent behavior**: Present the URL to the user and explain they need to:

1. Visit the URL
2. Complete the login
3. Copy the authorization code from the callback URL
4. Provide it to you

#### `login verify` — Complete login with authorization code

```bash
python3 scripts/ms-todo-oauth.py login verify <authorization_code>
```

**Example:**

```bash
python3 scripts/ms-todo-oauth.py login verify "M.R3_BAY.abc123def456..."
```

**Output on success:**

```
✓ Authentication successful!
✓ Login information saved, you will be logged in automatically next time.
```

**Output on failure:**

```
❌ Token acquisition failed
Error: invalid_grant
Description: AADSTS54005: OAuth2 Authorization code was already redeemed...
```

**Exit code**: 0 on success, 1 on failure.

**Important notes:**

- Each authorization code can only be used ONCE
- If verification fails, you need to run `login get` again to get a new code
- Once successfully logged in, the token is cached and you won't need to login again unless:
  - You run `logout`
  - You run `--reauth`
  - The token expires and cannot be auto-refreshed

#### `logout` — Clear saved login

```bash
python3 scripts/ms-todo-oauth.py logout
```

Output: `✓ Login information cleared`

Only use when the user explicitly asks to switch accounts or clear login data. Under normal circumstances, the token is cached and login is automatic.

---

### List Management

#### `lists` — List all task lists

```bash
python3 scripts/ms-todo-oauth.py lists
python3 scripts/ms-todo-oauth.py -v lists  # with IDs and creation dates
```

**Output example:**

```
📋 Task Lists (3 total):

1. 任务
   ID: AQMkADAwATYwMAItYTQwZC04OThhLTAwAi0wMAoALgAAA0QJKpxW32BIsIlHaM...
   Created: 2024-12-15T08:30:00Z
2. Work
3. Shopping
```

#### `create-list` — Create a new list

```bash
python3 scripts/ms-todo-oauth.py create-list "<name>"
```

| Argument | Required | Description                                     |
| -------- | -------- | ----------------------------------------------- |
| `name` | Yes      | Name of the new list (supports Unicode/Chinese) |

**Example:**

```bash
python3 scripts/ms-todo-oauth.py create-list "项目 A"
```

Output: `✓ List created: 项目 A`

#### `delete-list` — Delete a list

```bash
python3 scripts/ms-todo-oauth.py delete-list "<name>" [-y]
```

| Argument/Option | Required | Description                |
| --------------- | --------