cupt 0.6.1__tar.gz

cupt-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Nuzum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cupt-0.6.1/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: cupt
+Version: 0.6.1
+Summary: ClickUp Task Management CLI and Python library
+Author-email: Matthew Nuzum <matthew@nuzum.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/newz2000/cupt
+Project-URL: Repository, https://github.com/newz2000/cupt
+Project-URL: Issues, https://github.com/newz2000/cupt/issues
+Project-URL: Changelog, https://github.com/newz2000/cupt/blob/main/CHANGELOG.md
+Keywords: clickup,cli,tasks,productivity,task-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: cryptography>=3.4.0
+Requires-Dist: pyyaml>=5.4.0
+Requires-Dist: colorama>=0.4.4
+Requires-Dist: python-dotenv>=0.19.0
+Dynamic: license-file
+
+# CUPT - ClickUp Task Management CLI
+
+CUPT stands for “ClickUP Terminal,” a command-line interface for accessing your tasks in ClickUp in the terminal or via your favorite AI-based tool.
+
+## Features
+- **Task Listing**: View active, overdue, and upcoming tasks with deep paging support.
+- **Subtask Support**: Visual nesting (`↳`) and parent task resolution.
+- **Hierarchical Context**: `cupt context <id>` shows parents and sibling subtasks.
+- **Time Tracking**: Start/stop timers and add manual time entries.
+- **Note Management**: Quick comments and note listing.
+- **Flexible Auth**: Supports both OAuth and Personal API Tokens.
+- **Offline Support**: After `cupt list` runs, it transparently caches the full details (description, comments, parent) for every task it just displayed, so a later `cupt show <id> --offline` works without a network. Run `cupt prefetch` to populate the same cache eagerly when you know you'll be offline soon.
+
+## Installation
+
+### Recommended: System-wide using `pipx`
+Use `pipx` to install `cupt` in an isolated environment that is globally available:
+
+```bash
+# From the project root
+pipx install .
+
+# To update an existing installation after code changes:
+pipx install --force .
+```
+
+If you don't have `pipx`, install it via Homebrew: `brew install pipx && pipx ensurepath`.
+
+### Development: Local Editable Install
+If you are developing or want an isolated virtual environment:
+```bash
+git clone https://github.com/newz2000/cupt.git
+cd cupt
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+### Configuration
+```bash
+cupt auth
+# Follow prompts to authenticate
+```
+
+## Usage
+- `cupt list`: List your active tasks
+- `cupt list --overdue`: Show overdue tasks
+- `cupt list --tag urgent --no-tag waiting`: Filter by tag (server-side)
+- `cupt list --json`: Pipeable JSON output (combines with all filters)
+- `cupt show <id>`: Show task details
+- `cupt context <id>`: Show task parent and siblings
+- `cupt done <id>`: Mark task as complete
+- `cupt tag add <id> <name>` / `cupt tag remove <id> <name>`: Manage tags
+- `cupt attach list <id>` / `cupt attach get <id> <selector>` / `cupt attach add <id> <file>`: Manage attachments
+- `cupt time start <id>` / `cupt time stop`: Timer control
+- `cupt note <id> "Your message"`: Add a note
+
+## Use as a Python library
+
+`cupt` is usable as a dependency in your own Python code. Importing it
+does no I/O — no config directory is created, no network calls happen
+until you make one explicitly.
+
+```python
+from cupt import ClickUpClient, TaskService, APIError
+
+client = ClickUpClient("pk_xxxxxxxxxxxxxxxx")     # personal API token
+service = TaskService(client)
+
+try:
+    tasks = service.list_tasks(
+        team_id="123456",
+        tags=["urgent"],          # server-side filter
+        include_closed=False,
+    )
+    urgent_billing = service.filter_by_tags(
+        tasks, required=["urgent", "billing"]
+    )
+    for t in urgent_billing:
+        print(t["id"], t["name"])
+except APIError as e:
+    print(f"ClickUp request failed: {e}")
+```
+
+Public API surface (anything importable from `cupt` top-level):
+
+| Symbol            | Purpose                                                  |
+| ----------------- | -------------------------------------------------------- |
+| `ClickUpClient`   | Thin HTTP wrapper around the ClickUp v2 REST API.        |
+| `TaskService`     | List/filter/complete tasks; resolve parent names.        |
+| `TimeService`     | Start/stop timers, add time entries, fetch totals.       |
+| `NoteService`     | Add and list task comments.                              |
+| `CuptError`       | Base exception. All `cupt` errors subclass this.         |
+| `APIError`        | HTTP failure, timeout, or invalid JSON from ClickUp.     |
+| `AuthError`       | Missing or invalid credentials.                          |
+| `ConfigError`     | Configuration is missing or malformed.                   |
+
+Other modules (`cupt.config`, `cupt.context`, command modules) are
+internal to the CLI and may change between releases.
+
+## Testing
+`cupt` is built with a strong focus on stability and testability.
+- **Coverage**: 83% total coverage
+- **Tests**: 186 unit tests using `pytest` and mocks.
+
+Run the test suite:
+```bash
+pytest --cov=cupt tests/
+```
+
+## Future Roadmap
+Exciting features planned for upcoming releases:
+- **`cupt work` / `cupt gtd`**: Sequential "focused work" mode to tackle a list of tasks one by one.
+- **Quick Create**: Rapidly create follow-up tasks or subtasks while you work.
+- **Workflow State**: Persistent session state for long-running workflows.
+- **Shell Completion**: Tab-completion for task IDs and commands.
+
+## Project Structure
+- `cupt/`: Package root.
+- `cupt/services/`: Core business logic (TaskService, TimeService, NoteService).
+- `cupt/api.py`: ClickUp API client wrapper.
+- `cupt/main.py`: CLI entry point.
+- `tests/`: Comprehensive unit tests.
+
+## Contributions
+If you or your favorite AI tool want to make improvements, please submit a pull request. Please respect the requirements in the AGENTS.md file and run the pre-commit hook to verify compliance with the coding standards. 

cupt-0.6.1/README.md

@@ -0,0 +1,126 @@
+# CUPT - ClickUp Task Management CLI
+
+CUPT stands for “ClickUP Terminal,” a command-line interface for accessing your tasks in ClickUp in the terminal or via your favorite AI-based tool.
+
+## Features
+- **Task Listing**: View active, overdue, and upcoming tasks with deep paging support.
+- **Subtask Support**: Visual nesting (`↳`) and parent task resolution.
+- **Hierarchical Context**: `cupt context <id>` shows parents and sibling subtasks.
+- **Time Tracking**: Start/stop timers and add manual time entries.
+- **Note Management**: Quick comments and note listing.
+- **Flexible Auth**: Supports both OAuth and Personal API Tokens.
+- **Offline Support**: After `cupt list` runs, it transparently caches the full details (description, comments, parent) for every task it just displayed, so a later `cupt show <id> --offline` works without a network. Run `cupt prefetch` to populate the same cache eagerly when you know you'll be offline soon.
+
+## Installation
+
+### Recommended: System-wide using `pipx`
+Use `pipx` to install `cupt` in an isolated environment that is globally available:
+
+```bash
+# From the project root
+pipx install .
+
+# To update an existing installation after code changes:
+pipx install --force .
+```
+
+If you don't have `pipx`, install it via Homebrew: `brew install pipx && pipx ensurepath`.
+
+### Development: Local Editable Install
+If you are developing or want an isolated virtual environment:
+```bash
+git clone https://github.com/newz2000/cupt.git
+cd cupt
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+### Configuration
+```bash
+cupt auth
+# Follow prompts to authenticate
+```
+
+## Usage
+- `cupt list`: List your active tasks
+- `cupt list --overdue`: Show overdue tasks
+- `cupt list --tag urgent --no-tag waiting`: Filter by tag (server-side)
+- `cupt list --json`: Pipeable JSON output (combines with all filters)
+- `cupt show <id>`: Show task details
+- `cupt context <id>`: Show task parent and siblings
+- `cupt done <id>`: Mark task as complete
+- `cupt tag add <id> <name>` / `cupt tag remove <id> <name>`: Manage tags
+- `cupt attach list <id>` / `cupt attach get <id> <selector>` / `cupt attach add <id> <file>`: Manage attachments
+- `cupt time start <id>` / `cupt time stop`: Timer control
+- `cupt note <id> "Your message"`: Add a note
+
+## Use as a Python library
+
+`cupt` is usable as a dependency in your own Python code. Importing it
+does no I/O — no config directory is created, no network calls happen
+until you make one explicitly.
+
+```python
+from cupt import ClickUpClient, TaskService, APIError
+
+client = ClickUpClient("pk_xxxxxxxxxxxxxxxx")     # personal API token
+service = TaskService(client)
+
+try:
+    tasks = service.list_tasks(
+        team_id="123456",
+        tags=["urgent"],          # server-side filter
+        include_closed=False,
+    )
+    urgent_billing = service.filter_by_tags(
+        tasks, required=["urgent", "billing"]
+    )
+    for t in urgent_billing:
+        print(t["id"], t["name"])
+except APIError as e:
+    print(f"ClickUp request failed: {e}")
+```
+
+Public API surface (anything importable from `cupt` top-level):
+
+| Symbol            | Purpose                                                  |
+| ----------------- | -------------------------------------------------------- |
+| `ClickUpClient`   | Thin HTTP wrapper around the ClickUp v2 REST API.        |
+| `TaskService`     | List/filter/complete tasks; resolve parent names.        |
+| `TimeService`     | Start/stop timers, add time entries, fetch totals.       |
+| `NoteService`     | Add and list task comments.                              |
+| `CuptError`       | Base exception. All `cupt` errors subclass this.         |
+| `APIError`        | HTTP failure, timeout, or invalid JSON from ClickUp.     |
+| `AuthError`       | Missing or invalid credentials.                          |
+| `ConfigError`     | Configuration is missing or malformed.                   |
+
+Other modules (`cupt.config`, `cupt.context`, command modules) are
+internal to the CLI and may change between releases.
+
+## Testing
+`cupt` is built with a strong focus on stability and testability.
+- **Coverage**: 83% total coverage
+- **Tests**: 186 unit tests using `pytest` and mocks.
+
+Run the test suite:
+```bash
+pytest --cov=cupt tests/
+```
+
+## Future Roadmap
+Exciting features planned for upcoming releases:
+- **`cupt work` / `cupt gtd`**: Sequential "focused work" mode to tackle a list of tasks one by one.
+- **Quick Create**: Rapidly create follow-up tasks or subtasks while you work.
+- **Workflow State**: Persistent session state for long-running workflows.
+- **Shell Completion**: Tab-completion for task IDs and commands.
+
+## Project Structure
+- `cupt/`: Package root.
+- `cupt/services/`: Core business logic (TaskService, TimeService, NoteService).
+- `cupt/api.py`: ClickUp API client wrapper.
+- `cupt/main.py`: CLI entry point.
+- `tests/`: Comprehensive unit tests.
+
+## Contributions
+If you or your favorite AI tool want to make improvements, please submit a pull request. Please respect the requirements in the AGENTS.md file and run the pre-commit hook to verify compliance with the coding standards. 

cupt-0.6.1/cupt/__init__.py

@@ -0,0 +1,39 @@
+"""
+CUPT — ClickUp Task Management CLI and Python library.
+
+Use as a CLI:
+    $ cupt list --tag urgent
+
+Use as a library:
+    from cupt import ClickUpClient, TaskService
+
+    client = ClickUpClient("pk_xxxxx")              # personal API token
+    service = TaskService(client)
+    tasks = service.list_tasks(team_id="123", tags=["urgent"])
+
+Public exports are intentionally limited to the API client, services, and
+typed exceptions. Internal helpers (config, CLI commands, formatting) are
+not part of the public API and may change between releases.
+"""
+
+from cupt.api import ClickUpClient
+from cupt.exceptions import APIError, AuthError, ConfigError, CuptError
+from cupt.services.note_service import NoteService
+from cupt.services.task_service import TaskService
+from cupt.services.time_service import TimeService
+
+__version__ = "0.6.1"
+__author__ = "Matthew Nuzum"
+__email__ = "matthew@nuzum.com"
+
+__all__ = [
+    "ClickUpClient",
+    "TaskService",
+    "TimeService",
+    "NoteService",
+    "CuptError",
+    "APIError",
+    "AuthError",
+    "ConfigError",
+    "__version__",
+]

cupt-0.6.1/cupt/ai.py

@@ -0,0 +1,82 @@
+"""
+Local AI backend abstraction for CUPT.
+
+Provider priority:
+  1. Apple Intelligence (apple-fm-sdk, macOS 26+)
+
+Future providers (not yet implemented):
+  2. Windows Copilot+ (WinRT Microsoft.Windows.AI)
+  3. Ollama (http://localhost:11434)
+"""
+
+import asyncio
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_SYSTEM_INSTRUCTIONS = (
+    "You are a concise assistant helping a professional complete task management notes. "
+    "Write clear, brief, first-person completion notes. No preamble or explanation."
+)
+
+
+def get_ai_suggestion(prompt: str) -> Optional[str]:
+    """
+    Try available local AI backends and return a suggestion, or None if unavailable.
+
+    Returns None silently when no provider is found — callers are responsible
+    for surfacing a user-facing message.
+    """
+    result = _try_apple_intelligence(prompt)
+    if result is not None:
+        return result
+
+    # Future: _try_windows_copilot(prompt)
+    # Future: _try_ollama(prompt)
+
+    return None
+
+
+def is_ai_available() -> bool:
+    """Return True if at least one local AI provider is available."""
+    return _apple_intelligence_available()
+
+
+# ------------------------------------------------------------------
+# Apple Intelligence
+# ------------------------------------------------------------------
+
+
+def _apple_intelligence_available() -> bool:
+    try:
+        import apple_fm_sdk as fm
+
+        available, _ = fm.SystemLanguageModel().is_available()
+        return available
+    except ImportError:
+        return False
+    except Exception:
+        return False
+
+
+def _try_apple_intelligence(prompt: str) -> Optional[str]:
+    try:
+        import apple_fm_sdk as fm
+
+        model = fm.SystemLanguageModel()
+        available, reason = model.is_available()
+        if not available:
+            logger.debug("Apple Intelligence not available: %s", reason)
+            return None
+
+        session = fm.LanguageModelSession(instructions=_SYSTEM_INSTRUCTIONS)
+        result = asyncio.run(session.respond(prompt))
+        return result.strip() if result else None
+
+    except ImportError:
+        logger.debug("apple-fm-sdk not installed")
+        return None
+    except Exception as e:
+        logger.debug("Apple Intelligence error: %s", e)
+        return None