sweatstack-cli 0.1.0__tar.gz

sweatstack_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv pip install:*)",
+      "Bash(uv venv:*)",
+      "Bash(source .venv/bin/activate:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run ruff check:*)",
+      "Bash(uv run ruff format:*)",
+      "Bash(uv run mypy:*)",
+      "Bash(uv run sweatstack:*)",
+      "Bash(uv sync:*)",
+      "Bash(pytest:*)",
+      "Bash(ruff check:*)",
+      "WebFetch(domain:localhost)",
+      "Bash(curl:*)",
+      "Bash(python3:*)",
+      "Bash(make help:*)"
+    ]
+  }
+}

sweatstack_cli-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

sweatstack_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

sweatstack_cli-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,403 @@
+# SweatStack CLI — Development Guide
+
+This document explains how to develop, maintain, and extend the SweatStack CLI.
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/sweatstack/sweatstack-cli
+cd sweatstack-cli
+
+# Create virtual environment and install
+uv venv
+source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
+uv pip install -e ".[dev]"
+
+# Run the CLI
+sweatstack --help
+
+# Run tests
+pytest
+```
+
+## Project Structure
+
+```
+src/sweatstack_cli/
+├── __init__.py              # Package version
+├── main.py                  # CLI entry point (Typer app)
+├── config.py                # Environment-based configuration
+├── console.py               # Rich console singleton
+├── exceptions.py            # Exception hierarchy with exit codes
+├── auth/                    # Authentication module
+│   ├── __init__.py          # Authenticator class (main API)
+│   ├── pkce.py              # PKCE challenge generation
+│   ├── jwt.py               # JWT payload decoding
+│   ├── tokens.py            # Token storage
+│   └── callback_server.py   # Local OAuth callback server
+├── api/                     # API client module
+│   ├── __init__.py          # Public exports
+│   └── client.py            # Authenticated HTTP client
+└── commands/                # CLI command modules
+    ├── __init__.py
+    ├── auth.py              # login, logout, whoami, status
+    └── pages.py             # pages deploy, list, delete
+```
+
+## Architecture
+
+### Design Principles
+
+1. **Minimal dependencies** — Only essential packages: `typer`, `httpx`, `platformdirs`
+2. **No magic** — Explicit configuration, clear error messages
+3. **Testable** — Dependency injection, protocol-based abstractions
+4. **Type safe** — Full type hints, strict mypy configuration
+
+### Authentication Flow
+
+The CLI uses OAuth2 PKCE (Proof Key for Code Exchange) for authentication:
+
+```
+User runs `sweatstack login`
+         │
+         ▼
+Generate PKCE verifier + challenge
+         │
+         ▼
+Start local HTTP server on port 8400-8499
+         │
+         ▼
+Open browser to SweatStack OAuth page
+         │
+         ▼
+User authenticates in browser
+         │
+         ▼
+Browser redirects to localhost with auth code
+         │
+         ▼
+Exchange code for tokens (access + refresh)
+         │
+         ▼
+Store tokens in ~/.../SweatStack/tokens.json
+```
+
+### Token Storage
+
+Tokens are stored in a platform-specific location using `platformdirs`:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/Application Support/SweatStack/SweatStack/tokens.json` |
+| Linux | `~/.local/share/SweatStack/SweatStack/tokens.json` |
+| Windows | `%APPDATA%\SweatStack\SweatStack\tokens.json` |
+
+**Important:** This path is shared with the `sweatstack` Python library. Both projects must maintain compatibility with this format:
+
+```json
+{
+  "access_token": "eyJ...",
+  "refresh_token": "eyJ..."
+}
+```
+
+## Adding New Commands
+
+### 1. Create a Command Module
+
+Create a new file in `src/sweatstack_cli/commands/`:
+
+```python
+# src/sweatstack_cli/commands/activities.py
+"""Activity commands."""
+
+from __future__ import annotations
+
+import typer
+
+from sweatstack_cli.api import APIClient
+from sweatstack_cli.console import console
+from sweatstack_cli.exceptions import AuthenticationError
+
+app = typer.Typer(
+    name="activities",
+    help="Manage activities.",
+    no_args_is_help=True,
+)
+
+
+@app.command(name="list")
+def list_activities(
+    limit: int = typer.Option(10, "--limit", "-n", help="Number of activities"),
+) -> None:
+    """List recent activities."""
+    try:
+        client = APIClient()
+        activities = client.get("/api/v1/activities", params={"limit": limit})
+
+        for activity in activities["items"]:
+            console.print(f"  {activity['id']}: {activity['name']}")
+
+    except AuthenticationError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(2)
+```
+
+### 2. Register in main.py
+
+```python
+# src/sweatstack_cli/main.py
+from sweatstack_cli.commands import activities
+
+app.add_typer(activities.app, name="activities")
+```
+
+### 3. Add Tests
+
+```python
+# tests/test_commands/test_activities.py
+from typer.testing import CliRunner
+from sweatstack_cli.main import app
+
+runner = CliRunner()
+
+def test_activities_help():
+    result = runner.invoke(app, ["activities", "--help"])
+    assert result.exit_code == 0
+    assert "list" in result.stdout
+```
+
+## Extending the API Client
+
+The `APIClient` class provides authenticated HTTP methods. To add new endpoints:
+
+```python
+# src/sweatstack_cli/api/activities.py
+from __future__ import annotations
+
+from sweatstack_cli.api.client import APIClient
+
+
+class ActivitiesAPI:
+    """Activities API wrapper."""
+
+    def __init__(self, client: APIClient | None = None) -> None:
+        self._client = client or APIClient()
+
+    def list(self, limit: int = 10) -> list[dict]:
+        """List activities."""
+        response = self._client.get("/api/v1/activities", params={"limit": limit})
+        return response["items"]
+
+    def get(self, activity_id: str) -> dict:
+        """Get a single activity."""
+        return self._client.get(f"/api/v1/activities/{activity_id}")
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# All tests
+pytest
+
+# With coverage
+pytest --cov=sweatstack_cli --cov-report=html
+
+# Specific test file
+pytest tests/test_auth/test_pkce.py
+
+# Specific test
+pytest tests/test_auth/test_pkce.py::TestGeneratePKCE::test_verifier_length_in_range
+
+# Verbose output
+pytest -v
+```
+
+### Test Fixtures
+
+Common fixtures are defined in `tests/conftest.py`:
+
+- `temp_token_storage` — FileTokenStorage with temp directory
+- `sample_tokens` — Valid TokenPair with future expiry
+- `expired_tokens` — TokenPair with past expiry
+- `clean_env` — Removes SweatStack env vars for isolation
+
+### Mocking HTTP Requests
+
+Use `pytest-httpx` for HTTP mocking:
+
+```python
+from pytest_httpx import HTTPXMock
+
+def test_api_call(httpx_mock: HTTPXMock):
+    httpx_mock.add_response(
+        url="https://app.sweatstack.no/api/v1/test",
+        json={"data": "value"},
+    )
+
+    client = APIClient(authenticator=mock_auth)
+    result = client.get("/api/v1/test")
+
+    assert result["data"] == "value"
+```
+
+### Mocking Authentication
+
+```python
+from unittest.mock import Mock
+from sweatstack_cli.auth import Authenticator
+from sweatstack_cli.auth.tokens import TokenPair
+
+def test_with_mock_auth(sample_tokens: TokenPair):
+    auth = Mock(spec=Authenticator)
+    auth.get_valid_tokens.return_value = sample_tokens
+
+    client = APIClient(authenticator=auth)
+    # ... test API calls
+```
+
+## Code Quality
+
+### Linting and Formatting
+
+```bash
+# Check linting
+ruff check .
+
+# Auto-fix issues
+ruff check --fix .
+
+# Format code
+ruff format .
+```
+
+### Type Checking
+
+```bash
+mypy src/sweatstack_cli
+```
+
+### Pre-commit Checks
+
+Consider adding these to CI or as pre-commit hooks:
+
+```bash
+ruff check .
+ruff format --check .
+mypy src/sweatstack_cli
+pytest
+```
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `SWEATSTACK_URL` | API base URL | `https://app.sweatstack.no` |
+| `SWEATSTACK_API_KEY` | Access token (CI/CD) | — |
+| `SWEATSTACK_REFRESH_TOKEN` | Refresh token (CI/CD) | — |
+
+For CI/CD pipelines, set `SWEATSTACK_API_KEY` and `SWEATSTACK_REFRESH_TOKEN` to bypass interactive login.
+
+## Error Handling
+
+### Exception Hierarchy
+
+```
+CLIError (exit code 1)
+├── AuthenticationError (exit code 2)
+├── APIError (exit code 3)
+└── ValidationError (exit code 4)
+```
+
+### Adding New Exceptions
+
+```python
+# src/sweatstack_cli/exceptions.py
+
+class RateLimitError(CLIError):
+    """API rate limit exceeded."""
+    exit_code = 5
+```
+
+### Using Exceptions in Commands
+
+```python
+from sweatstack_cli.exceptions import AuthenticationError
+
+def my_command():
+    try:
+        client = APIClient()
+        # ...
+    except AuthenticationError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(2)
+```
+
+## Release Process
+
+1. Update version in `src/sweatstack_cli/__init__.py`
+2. Update `pyproject.toml` version if needed
+3. Run full test suite: `pytest`
+4. Build: `uv build` or `python -m build`
+5. Publish: `twine upload dist/*`
+
+## Debugging
+
+### Verbose Output
+
+The CLI respects Rich's console settings. For debugging:
+
+```python
+from rich.console import Console
+console = Console(force_terminal=True)  # Force colors in CI
+```
+
+### Token Inspection
+
+```bash
+# Check token status
+sweatstack status
+
+# View raw token file (careful with secrets!)
+cat ~/Library/Application\ Support/SweatStack/SweatStack/tokens.json | python -m json.tool
+```
+
+### Local API Testing
+
+```bash
+# Override API URL for local testing
+SWEATSTACK_URL=http://localhost:8000 sweatstack login
+```
+
+## Compatibility Notes
+
+### Token Storage Compatibility
+
+The CLI shares token storage with the `sweatstack` Python library. Changes to the token format must be coordinated:
+
+1. Token file path: `platformdirs.user_data_dir("SweatStack", "SweatStack") / "tokens.json"`
+2. JSON format: `{"access_token": "...", "refresh_token": "..."}`
+3. File permissions: `0o600`
+
+### Python Version
+
+Requires Python 3.13+. Uses modern features:
+- `type` statement (PEP 695)
+- `X | Y` union syntax
+- `@dataclass(slots=True)`
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make changes with tests
+4. Run checks: `ruff check . && mypy src && pytest`
+5. Submit a pull request
+
+## Getting Help
+
+- GitHub Issues: [github.com/sweatstack/sweatstack-cli/issues](https://github.com/sweatstack/sweatstack-cli/issues)
+- Documentation: [docs.sweatstack.no](https://docs.sweatstack.no)

sweatstack_cli-0.1.0/Makefile

@@ -0,0 +1,50 @@
+.PHONY: help install dev test lint format typecheck check clean build publish
+
+help:
+	@echo "SweatStack CLI Development Commands"
+	@echo ""
+	@echo "  make install     Install the package"
+	@echo "  make dev         Install with development dependencies"
+	@echo "  make test        Run tests"
+	@echo "  make lint        Run linter"
+	@echo "  make format      Format code"
+	@echo "  make typecheck   Run type checker"
+	@echo "  make check       Run all checks (lint, format, typecheck, test)"
+	@echo "  make clean       Remove build artifacts"
+	@echo "  make build       Build distribution packages"
+	@echo "  make publish     Publish to PyPI"
+
+install:
+	uv pip install -e .
+
+dev:
+	uv pip install -e ".[dev]"
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check .
+
+format:
+	uv run ruff format .
+
+typecheck:
+	uv run mypy src/sweatstack_cli
+
+check: lint typecheck test
+	@echo "All checks passed!"
+
+clean:
+	rm -rf dist/ build/ *.egg-info src/*.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .mypy_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null || true
+
+build:
+	rm -rf dist
+	uv build
+
+publish: build
+	uvx uv-publish

sweatstack_cli-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: sweatstack-cli
+Version: 0.1.0
+Summary: Command-line interface for SweatStack — the sports data platform for developers
+Project-URL: Homepage, https://sweatstack.no
+Project-URL: Documentation, https://docs.sweatstack.no
+Project-URL: Repository, https://github.com/sweatstack/sweatstack-cli
+Author-email: Aart Goossens <aart@goossens.me>
+License: MIT
+Keywords: api,cli,fitness,sports,sweatstack
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SweatStack CLI
+
+Command-line interface for [SweatStack](https://sweatstack.no) — the sports data platform for developers.
+
+## Installation
+
+```bash
+pip install sweatstack-cli
+```
+
+Requires Python 3.13+.
+
+## Quick Start
+
+```bash
+# Authenticate with SweatStack
+sweatstack login
+
+# Check who you're logged in as
+sweatstack whoami
+
+# Deploy a static site
+sweatstack pages deploy ./dist --prod
+
+# View authentication status
+sweatstack status
+
+# Logout
+sweatstack logout
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `sweatstack login` | Authenticate via browser |
+| `sweatstack login --force` | Force re-authentication |
+| `sweatstack logout` | Remove stored credentials |
+| `sweatstack whoami` | Show current user |
+| `sweatstack status` | Show token status and expiry |
+
+### Pages
+
+| Command | Description |
+|---------|-------------|
+| `sweatstack pages deploy <dir>` | Deploy static site |
+| `sweatstack pages deploy --prod` | Deploy to production |
+| `sweatstack pages list` | List all sites |
+| `sweatstack pages delete <name>` | Delete a site |
+
+## CI/CD Usage
+
+For automated environments, use environment variables instead of interactive login:
+
+```bash
+export SWEATSTACK_API_KEY="your-access-token"
+export SWEATSTACK_REFRESH_TOKEN="your-refresh-token"
+
+sweatstack pages deploy ./dist --prod
+```
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `SWEATSTACK_URL` | API base URL | `https://app.sweatstack.no` |
+| `SWEATSTACK_API_KEY` | Access token | — |
+| `SWEATSTACK_REFRESH_TOKEN` | Refresh token | — |
+
+## Token Storage
+
+Credentials are stored securely in your OS user data directory:
+
+- **macOS**: `~/Library/Application Support/SweatStack/SweatStack/tokens.json`
+- **Linux**: `~/.local/share/SweatStack/SweatStack/tokens.json`
+- **Windows**: `%APPDATA%\SweatStack\SweatStack\tokens.json`
+
+This location is shared with the [sweatstack Python library](https://github.com/sweatstack/sweatstack-python), so authenticating with either tool works for both.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup and contribution guidelines.
+
+```bash
+# Install with dev dependencies
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint and format
+ruff check . && ruff format .
+
+# Type check
+mypy src/sweatstack_cli
+```
+
+## License
+
+MIT