tsk-cli 0.1.0__tar.gz

tsk_cli-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: tsk-cli
+Version: 0.1.0
+Summary: CLI for TSK — pull projects and things for editor agents
+Author: Rob Crosby
+License: MIT
+Project-URL: Homepage, https://tsk.tools
+Project-URL: Repository, https://github.com/rncrosby/text_plan
+Project-URL: Issues, https://github.com/rncrosby/text_plan/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+
+# tsk-cli
+
+Command-line interface for [TSK](https://tsk.tools) — pull projects and things into your editor so AI agents can work with them.
+
+## Install
+
+```bash
+pipx install tsk-cli
+# or
+pip install tsk-cli
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+tsk login              # authenticate via browser
+tsk orgs               # list your organizations
+tsk org <name>         # set the default org
+tsk pull               # sync projects and things to .task/
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tsk login [--server URL]` | Authenticate via browser OAuth |
+| `tsk logout` | Clear stored credentials |
+| `tsk orgs` | List your organizations |
+| `tsk org <name-or-id>` | Set the default organization |
+| `tsk pull` | Sync projects/things to `.task/` |
+| `tsk push [--force]` | Upload local edits to the server |
+| `tsk status` | Show current config and auth state |
+| `tsk list [--status S] [--project P]` | List things with optional filters |
+| `tsk show <ref>` | Display a thing's details |
+| `tsk set-status <ref> <status>` | Update status and push immediately |
+| `tsk start <ref>` | Set status to `in_progress` |
+| `tsk done <ref>` | Set status to `done` |
+| `tsk review <ref>` | Set status to `in_review` |
+| `tsk open <ref>` | Open thing in browser |
+
+## How it works
+
+`tsk pull` writes a `.task/` directory containing your projects and things as markdown files. Editor agents (Cursor, Copilot, etc.) can read these files to understand what to work on. After making changes locally, `tsk push` syncs them back to the server.
+
+## License
+
+MIT

tsk_cli-0.1.0/README.md

@@ -0,0 +1,49 @@
+# tsk-cli
+
+Command-line interface for [TSK](https://tsk.tools) — pull projects and things into your editor so AI agents can work with them.
+
+## Install
+
+```bash
+pipx install tsk-cli
+# or
+pip install tsk-cli
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+tsk login              # authenticate via browser
+tsk orgs               # list your organizations
+tsk org <name>         # set the default org
+tsk pull               # sync projects and things to .task/
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tsk login [--server URL]` | Authenticate via browser OAuth |
+| `tsk logout` | Clear stored credentials |
+| `tsk orgs` | List your organizations |
+| `tsk org <name-or-id>` | Set the default organization |
+| `tsk pull` | Sync projects/things to `.task/` |
+| `tsk push [--force]` | Upload local edits to the server |
+| `tsk status` | Show current config and auth state |
+| `tsk list [--status S] [--project P]` | List things with optional filters |
+| `tsk show <ref>` | Display a thing's details |
+| `tsk set-status <ref> <status>` | Update status and push immediately |
+| `tsk start <ref>` | Set status to `in_progress` |
+| `tsk done <ref>` | Set status to `done` |
+| `tsk review <ref>` | Set status to `in_review` |
+| `tsk open <ref>` | Open thing in browser |
+
+## How it works
+
+`tsk pull` writes a `.task/` directory containing your projects and things as markdown files. Editor agents (Cursor, Copilot, etc.) can read these files to understand what to work on. After making changes locally, `tsk push` syncs them back to the server.
+
+## License
+
+MIT

tsk_cli-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tsk-cli"
+version = "0.1.0"
+description = "CLI for TSK — pull projects and things for editor agents"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [{name = "Rob Crosby"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Bug Tracking",
+]
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://tsk.tools"
+Repository = "https://github.com/rncrosby/text_plan"
+Issues = "https://github.com/rncrosby/text_plan/issues"
+
+[project.scripts]
+tsk = "tsk_cli.main:cli"

tsk_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tsk_cli-0.1.0/tsk_cli/api.py

@@ -0,0 +1,75 @@
+"""
+HTTP client that uses stored session cookies to talk to the TSK backend.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+import requests
+
+from .config import get_auth, get_server_url
+
+
+def create_session() -> requests.Session:
+    """Build a requests.Session pre-loaded with stored auth cookies."""
+    auth = get_auth()
+    s = requests.Session()
+    sessionid = auth.get("sessionid", "")
+    csrftoken = auth.get("csrftoken", "")
+    if sessionid:
+        s.cookies.set("sessionid", sessionid)
+    if csrftoken:
+        s.cookies.set("csrftoken", csrftoken)
+        s.headers["X-CSRFToken"] = csrftoken
+    return s
+
+
+def require_auth() -> tuple[requests.Session, str]:
+    """
+    Return (session, server_url) or exit with an error message
+    if not configured / not authenticated.
+    """
+    server_url = get_server_url()
+    auth = get_auth()
+    if not auth.get("sessionid"):
+        click.echo("Not logged in. Run: tsk login", err=True)
+        sys.exit(1)
+
+    session = create_session()
+    server_url = server_url.rstrip("/")
+    return session, server_url
+
+
+def api_get(path: str) -> dict | list:
+    """GET an API endpoint. Exits on auth failure."""
+    session, server_url = require_auth()
+    resp = session.get(f"{server_url}{path}")
+    if resp.status_code == 401 or resp.status_code == 403:
+        click.echo("Session expired. Run: tsk login", err=True)
+        sys.exit(1)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def api_post(path: str, json_data: dict) -> dict:
+    """POST to an API endpoint. Exits on auth failure."""
+    session, server_url = require_auth()
+    resp = session.post(f"{server_url}{path}", json=json_data)
+    if resp.status_code in (401, 403):
+        click.echo("Session expired. Run: tsk login", err=True)
+        sys.exit(1)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def api_patch(path: str, json_data: dict) -> dict:
+    """PATCH an API endpoint. Exits on auth failure."""
+    session, server_url = require_auth()
+    resp = session.patch(f"{server_url}{path}", json=json_data)
+    if resp.status_code in (401, 403):
+        click.echo("Session expired. Run: tsk login", err=True)
+        sys.exit(1)
+    resp.raise_for_status()
+    return resp.json()

tsk_cli-0.1.0/tsk_cli/auth.py

@@ -0,0 +1,133 @@
+"""
+Browser-based OAuth login flow for the CLI.
+
+1. Start a tiny HTTP server on a random localhost port.
+2. Open the browser to the app's login page with ?cli_callback=http://localhost:<port>/callback
+3. After the user signs in, the frontend redirects to our callback with a one-time auth code.
+4. We exchange the code for session credentials via the backend's code-exchange endpoint.
+"""
+
+from __future__ import annotations
+
+import http.server
+import threading
+import urllib.parse
+import webbrowser
+from typing import Optional
+
+import click
+import requests
+
+from .config import get_server_url, save_auth
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    """Handles the redirect from the frontend after successful OAuth."""
+
+    auth_code: Optional[str] = None
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+        params = urllib.parse.parse_qs(parsed.query)
+
+        code = params.get("code", [None])[0]
+
+        if code:
+            _CallbackHandler.auth_code = code
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(
+                b"<html><body><h2>Authenticated!</h2>"
+                b"<p>You can close this tab and return to the terminal.</p>"
+                b"</body></html>"
+            )
+        else:
+            self.send_response(400)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(b"<html><body><p>Missing credentials.</p></body></html>")
+
+    def log_message(self, format: str, *args: object) -> None:  # noqa: A002
+        pass
+
+
+def login_flow() -> bool:
+    """Run the interactive browser login. Returns True on success."""
+    server_url = get_server_url().rstrip("/")
+
+    server = http.server.HTTPServer(("127.0.0.1", 0), _CallbackHandler)
+    port = server.server_address[1]
+    callback_url = f"http://localhost:{port}/callback"
+
+    login_url = f"{server_url}/login?cli_callback={urllib.parse.quote(callback_url)}"
+
+    click.echo(f"Opening browser to sign in...")
+    click.echo(f"  {login_url}")
+    click.echo()
+    click.echo("Waiting for authentication...")
+
+    webbrowser.open(login_url)
+
+    _CallbackHandler.auth_code = None
+
+    server.timeout = 120
+    while _CallbackHandler.auth_code is None:
+        server.handle_request()
+        if _CallbackHandler.auth_code is None:
+            break
+
+    server.server_close()
+
+    if _CallbackHandler.auth_code:
+        ok = _exchange_code(server_url, _CallbackHandler.auth_code)
+        if ok:
+            ok2, who = _verify_session(server_url)
+            if ok2:
+                click.echo(f"Logged in as {who}")
+                return True
+            else:
+                click.echo("Session could not be verified. Try again.")
+                return False
+        else:
+            click.echo("Code exchange failed. Try again.")
+            return False
+
+    click.echo("Login timed out or was cancelled.")
+    return False
+
+
+def _exchange_code(server_url: str, code: str) -> bool:
+    """Exchange the one-time auth code for session credentials."""
+    try:
+        resp = requests.post(
+            f"{server_url}/api/auth/cli-code-exchange/",
+            json={"code": code},
+            timeout=15,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            sid = data.get("sessionid", "")
+            csrf = data.get("csrftoken", "")
+            if sid:
+                save_auth(sessionid=sid, csrftoken=csrf)
+                return True
+    except requests.RequestException:
+        pass
+    return False
+
+
+def _verify_session(server_url: str) -> tuple[bool, str]:
+    """Hit /api/auth/me/ to confirm the stored session is valid."""
+    from .api import create_session
+
+    session = create_session()
+    try:
+        resp = session.get(f"{server_url}/api/auth/me/")
+        if resp.status_code == 200:
+            data = resp.json()
+            name = data.get("display_name") or data.get("email", "unknown")
+            return True, name
+    except requests.RequestException:
+        pass
+    return False, ""

tsk_cli-0.1.0/tsk_cli/config.py

@@ -0,0 +1,73 @@
+"""
+Manage CLI configuration stored in ~/.config/tsk/.
+
+config.json  -- server URL, default org id/name
+auth.json    -- session cookie + CSRF token
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+CONFIG_DIR = Path.home() / ".config" / "tsk"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+AUTH_FILE = CONFIG_DIR / "auth.json"
+
+
+def _ensure_dir() -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text())
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    _ensure_dir()
+    path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+# ── Config (server + org) ────────────────────────────────────────────
+
+
+def get_config() -> dict[str, Any]:
+    return _read_json(CONFIG_FILE)
+
+
+def set_config(**fields: Any) -> dict[str, Any]:
+    cfg = get_config()
+    cfg.update(fields)
+    _write_json(CONFIG_FILE, cfg)
+    return cfg
+
+
+DEFAULT_SERVER_URL = "https://tsk.tools"
+
+
+def get_server_url() -> str:
+    return get_config().get("server_url") or DEFAULT_SERVER_URL
+
+
+def get_default_org() -> Optional[dict[str, str]]:
+    """Return {"id": ..., "name": ...} or None."""
+    return get_config().get("org")
+
+
+# ── Auth (cookies) ───────────────────────────────────────────────────
+
+
+def get_auth() -> dict[str, Any]:
+    return _read_json(AUTH_FILE)
+
+
+def save_auth(*, sessionid: str, csrftoken: str) -> None:
+    _write_json(AUTH_FILE, {"sessionid": sessionid, "csrftoken": csrftoken})
+
+
+def clear_auth() -> None:
+    if AUTH_FILE.exists():
+        AUTH_FILE.unlink()

tsk_cli-0.1.0/tsk_cli/list_cmd.py

@@ -0,0 +1,87 @@
+"""
+tsk list -- list things with optional filters.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from .push import parse_thing_markdown
+from .resolve import task_root
+
+VALID_STATUSES = ("not_started", "in_progress", "in_review", "done")
+
+_STATUS_COLORS = {
+    "not_started": "white",
+    "in_progress": "cyan",
+    "in_review": "yellow",
+    "done": "green",
+}
+
+
+def list_things(
+    *,
+    status_filter: Optional[str] = None,
+    project_filter: Optional[str] = None,
+    target_dir: Path | None = None,
+) -> None:
+    root = task_root(target_dir)
+    projects_dir = root / "projects"
+
+    if not projects_dir.is_dir():
+        click.echo("No .task/projects directory. Run: tsk pull", err=True)
+        raise SystemExit(1)
+
+    if status_filter and status_filter not in VALID_STATUSES:
+        click.echo(
+            f"Invalid status: {status_filter}. Must be one of: {', '.join(VALID_STATUSES)}",
+            err=True,
+        )
+        raise SystemExit(1)
+
+    items: list[tuple[str, str, str, str]] = []
+
+    for md in sorted(projects_dir.glob("**/things/*.md")):
+        try:
+            parsed = parse_thing_markdown(md.read_text())
+        except ValueError:
+            continue
+
+        ref = parsed.frontmatter.get("ref", md.stem)
+        status = parsed.frontmatter.get("status", "not_started")
+        assigned = parsed.frontmatter.get("assigned_to", "")
+        name = parsed.name
+
+        if project_filter:
+            abbr_part = ref.split("-")[0] if "-" in ref else ""
+            if abbr_part.upper() != project_filter.upper():
+                continue
+
+        if status_filter and status != status_filter:
+            continue
+
+        items.append((ref, status, name, assigned))
+
+    if not items:
+        click.echo("No things found matching filters.")
+        return
+
+    ref_w = max(len(r) for r, _, _, _ in items)
+    status_w = max(len(s) for _, s, _, _ in items)
+
+    for ref, status, name, assigned in items:
+        color = _STATUS_COLORS.get(status, "white")
+        name_trunc = name[:50] + ("…" if len(name) > 50 else "")
+        line = (
+            f"  {ref:<{ref_w}}  "
+            f"{click.style(status, fg=color):<{status_w + 10}}  "
+            f"{name_trunc}"
+        )
+        if assigned:
+            line += f"  ({assigned})"
+        click.echo(line)
+
+    click.echo(f"\n  {len(items)} thing(s)")